rustunnel/README.md

rustunnel

rustunnel is a cross-platform Rust tool for lab and development tunneling over HTTPS with mutual TLS and an application auth token. It exposes a local SOCKS5 proxy on the connector side and forwards traffic only after the HTTPS, certificate, and auth checks succeed.

Legitimate use

Use rustunnel for local labs, development environments, and controlled testing where you own or are authorized to operate both endpoints. Do not use it to access systems without permission.

Build and test

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo check
cargo test --all-targets
cargo build

Generate credentials

Generate local certificate and auth material into an explicit directory:

rustunnel generate --out ./creds

This creates ca.pem, ca.key, server.crt, server.key, client.crt, client.key, token.txt, and config.json.

Run a tunnel

Start the HTTPS listener:

rustunnel listen \
  --listen 127.0.0.1:4180 \
  --cert ./creds/server.crt \
  --key ./creds/server.key \
  --ca-cert ./creds/ca.pem \
  --auth-token-file ./creds/token.txt

Start the connector and local SOCKS5 proxy:

rustunnel connect \
  --target 127.0.0.1:4180 \
  --socks 127.0.0.1:1180 \
  --cert ./creds/client.crt \
  --key ./creds/client.key \
  --ca-cert ./creds/ca.pem \
  --auth-token-file ./creds/token.txt

Use the SOCKS5 proxy from a local client:

curl --proxy socks5h://127.0.0.1:1180 http://127.0.0.1:4181/

Defaults and custom ports

• HTTPS listener: 127.0.0.1:4180
• SOCKS5 proxy: 127.0.0.1:1180

Override ports with --listen, --target, and --socks, as shown above.

Security posture

HTTPS is the default tunnel carrier. The listener requires a trusted client certificate and a valid auth token; the connector validates the server certificate before establishing the tunnel. Private keys and auth tokens are treated as sensitive and are redacted from normal logs.

Cross-platform CI

CI runs on Linux, macOS, and Windows. It checks formatting, Clippy, tests, builds, CLI smoke commands, release artifacts, and a minimal local generate/listen/connect/SOCKS5 end-to-end flow.