c4ch3c4d3andfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
cc1eb55c58
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
74 lines
2.1 KiB
Markdown
74 lines
2.1 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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.
|