VoxLAN

Voice of the LAN - A powerful LAN proxy that speaks your network's language It is a Rust-based command-line and proxy server tool that scans local TCP ports to find open services, then starts a proxy server forwarding requests to the first detected open port. It provides real-time feedback via terminal animations and supports forwarding HTTP requests using Actix Web and Reqwest.

What is VoxLAN?

VoxLAN is a sophisticated LAN proxy server built in Rust that discovers and manages network connections. It acts as an intelligent intermediary for your local network communications, providing seamless proxy functionality with advanced network discovery capabilities.

Features

Current Features

• Network Discovery: Automatically scans and identifies open ports on local network
• Comprehensive CLI: A full-featured command-line interface built with clap for intuitive control.
• 󰐲 QR Access: Generates QR codes for quick and easy access
• Real-time Monitoring: Live port scanning and network status reporting
• Request Forwarding: Seamless proxy functionality for local services
• High Performance: Built with Actix-web for optimal performance
• TCP Tunneling: Host and connect to TCP connections between machines.
• Access Control: Filter TCP connections with IP-based allow and block lists.

🎯 Planned Features

• 📋 Filter Lists: Advanced filtering capabilities for network traffic
• 🔢 Device Selection: Target specific devices by number or identifier
• 📡 Custom Request Handling: Flexible request processing and routing
• 📄 Configuration Files: Support for loading settings from a configuration file.
• 🔐 Security Features: Traffic filtering and access control

---

🛠️ Installation

You have three options: via Cargo, via prebuilt script, or manual install.

🔹 1. Easiest: Install via Cargo (Recommended)

If you have Rust installed, you can install directly from crates.io:

cargo install voxlan

This is the most "Rusty" and portable way.
It automatically downloads, compiles, and installs the latest version to your $HOME/.cargo/bin.

If you want even faster installs with prebuilt binaries, check out cargo-binstall:

cargo binstall voxlan

---

🔹 2. Quick Install via Script

Alternative: Installs the latest release binary to your system PATH.

curl -sSfL https://raw.githubusercontent.com/santoshxshrestha/voxlan/main/scripts/install.sh | bash

• This script will:
  1. Build voxlan in release mode (if Rust is present).
  2. Copy the binary to /usr/local/bin.
  3. Make it executable.

Tip: You may need to enter your password for sudo privileges.

---

🔹 3. Manual Build & Install

If you prefer full control or want to customize the build:

1. Clone the repository:

   git clone https://github.com/santoshxshrestha/voxlan.git
   cd voxlan
   

2. Build the Release Binary:

   cargo build --release
   

   This places the binary at target/release/voxlan.

3. Copy to a PATH directory (e.g., /usr/local/bin):

   sudo cp target/release/voxlan /usr/local/bin/voxlan
   

4. (Optional) Ensure executable permission:

   sudo chmod +x /usr/local/bin/voxlan
   

5. Run from anywhere:

   voxlan
   

---

🗑️ Uninstallation

You can uninstall using the provided script or manually:

🔹 1. Quick Uninstall via Script

curl -sSfL https://raw.githubusercontent.com/santoshxshrestha/voxlan/main/scripts/uninstall.sh | bash

🔹 2. Manual Uninstall

Remove the binary from your PATH:

sudo rm /usr/local/bin/voxlan

or

sudo rm /usr/bin/voxlan

If you also want to remove your cloned repository:

rm -rf ~/voxlan

If installed with Cargo:

cargo uninstall voxlan

---

🎮 Usage

Basic Usage

[!NOTE] By default the voxlan is bound to 8081 and target would be the open port if it

# Start VoxLAN with default settings
voxlan run

# Start VoxLAN by specifying the bind and target ports
voxlan run -b 8081 -t 8080

# Start VoxLAN by targeting specific port
voxlan run -t <target-port>

# List of all open ports 
voxlan list

# Get help for a specific command
voxlan <command> -h

[!NOTE] The path should be specified without a leading /. bind-port(optional), default path is /

Running client "HTTP"

# Run the client and send a request
voxlan client -b <bind-port> --path <path>

# Example: Run client to send a request to http://localhost:8080/echo
voxlan client -b 8080 -p echo

# Get help for the client command
voxlan client --help

Hosting and connecting a TCP Tunnel

[!NOTE] This feautre is intended for a pair of connections. If a crertain IP is in both the allow-list and block-list it will be blocked If no args are passed in the allow and block lists then all the IP will be allowed

# To host a TCP connection
voxlan host -b <bind-port>


# To connect to a TCP host
voxlan connect  -i <private-ip-of-host-machine> -t <target-port>

# To apply an allow-list while hosting
voxlan host -b <bind-port> --allow-ip=IP1,IP2,IP3,...

# To apply a block-list while hosting
voxlan host -b <bind-port> --block-ip=IP1,IP2,IP3,...

Current Workflow

1. Network Scan: VoxLAN scans ports 1-10000 on localhost
2. Discovery: Reports all open ports found
3. Proxy Start: Launches HTTP proxy server on port 8081
4. Request Forwarding: Forwards requests to localhost:8080

🏗️ Architecture

┌────────────────┐    ┌────────────────────┐    ┌──────────────────────────┐
│    Client      │────│      VoxLAN        │────│         Target           │
│    Request     │    │      Proxy         │    │         Service          │
│                │    │ :8081(By default)  │    │ :acitve port(By default) │
└────────────────┘    └────────────────────┘    └──────────────────────────┘

Core Components

• Port Scanner: Multi-threaded port discovery
• HTTP Proxy: Actix-web based proxy server
• Request Router: Intelligent request forwarding
• Network Utils: IP discovery and connection management

🔧 Configuration

Default Settings

• Proxy Port: 8081
• Target Port: UserSpecified(By default opened port)
• Scan Range: 1-10000
• Timeout: 100ms per port

📋 Roadmap

Phase 1: Core Enhancement ✅

• Basic proxy functionality
• Network discovery
• HTTP request forwarding
• Add option to specify port

Phase 2: CLI Integration 🚧

• Implement clap for argument parsing
• Custom request configuration
• Filter list implementation
• Added QR code generation for easy access

Phase 3: Advanced Features 📋

• Rich terminal UI (voxlan-style)
• Real-time network monitoring
• Advance traffic filtering and rules
• Configuration file support (.toml or .yaml)

🤝 Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Install development dependencies
cargo install cargo-watch

# Run with auto-reload
cargo watch -x run

# Run tests
cargo test

# Format code
cargo fmt

# Lint code
cargo clippy

📊 Performance

• Port Scanning: ~1000 ports in <2 seconds
• Proxy Latency: <5ms additional overhead
• Memory Usage: ~10MB baseline
• Concurrent Connections: 1000+ supported

🔍 Troubleshooting

Common Issues

Port Already in Use

# Check what's using port 8081
lsof -i :8081

# Kill the process
kill -9 <PID>

Permission Denied

# Run with elevated privileges if needed
sudo voxlan

Connection Timeout

• Increase timeout in scan_port function
• Check firewall settings
• Verify target service is running

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Dependencies

• 🚀 Actix Web - High-performance web framework
• 🎯 Anstyle - ANSI styling for clap's help and error message formatting
• ⚙️ Clap - Command line argument parser with derive macros
• 🔳 QR2Term - Terminal QR code generator and display library
• 🌐 Reqwest - HTTP client library with JSON support
• ⚡ Tokio - Asynchronous runtime for Rust with full feature set

  ---

🐛 Issues: GitHub Issues

---