Skip to content

santoshxshrestha/voxlan

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

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.

Rust License: MIT

๐Ÿš€ 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
  • ๓ฐฒ 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

๐ŸŽฏ Planned Features

  • ๐Ÿ“‹ Filter Lists: Advanced filtering capabilities for network traffic
  • ๐ŸŽ›๏ธ CLI Interface: Comprehensive command-line interface with clap integration
  • ๐Ÿ”ข Device Selection: Target specific devices by number or identifier
  • ๐Ÿ“ก Custom Request Handling: Flexible request processing and routing
  • ๐Ÿ” Security Features: Traffic filtering and access control

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-port and target-port
# is only one)
voxlan run -b 8081 -t 8080

# Start VoxLAN by targeting specific port
voxlan run -b <bind-port>

# List of all the open ports
voxlan list

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

Note

path should be specified without '/' bind-port(optional), default path is /

# Run the client
voxlan client -b <bind-port> --path <path>

voxlan client -b <bind-port> -p <path>

# Run clint to http://localhost:8080
voxlan client -b 8080 -p echo

# Help for the client
voxlan client --help

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
  • Add device selection by number
  • Custom request configuration
  • Filter list implementation

Phase 3: Advanced Features ๐Ÿ“‹

  • Rich terminal UI (voxlan-style)
  • Real-time network monitoring
  • Traffic filtering and rules
  • Configuration file support
  • Plugin system architecture

๐Ÿค 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


Built with โค๏ธ and Rust

Star โญ this repository if you find it helpful!

About

Voice of the LAN, or LAN proxy that speaks

Resources

License

Stars

Watchers

Forks

Packages

No packages published