diff --git a/README.md b/README.md index 05f568d..d5849eb 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ Rust-powered WebSocket server with Python API for remote command execution and i - **Command Execution** - Run shell commands on remote machines with timeout control - **Interactive Sessions** - Full PTY sessions with bash for manual work - **File Transfer** - Upload/download files between controller and workers +- **Tunnel Mode (VPN)** - Secure mesh networking with WireGuard encryption via Tailscale - **High Performance** - Rust async runtime handles high-concurrency workloads - **Auto Reconnection** - Workers reconnect automatically on network failures - **Cross-Platform** - Linux, macOS, Windows support @@ -46,8 +47,8 @@ Rust-powered WebSocket server with Python API for remote command execution and i │ └────────────────────────────────────┘ │ └──────────────────────────────────────────┘ ▲ - │ WebSocket (WSS) - │ (Daemon initiates connection) + │ WebSocket + │ (ws:// in direct mode, encrypted via VPN in tunnel mode) │ ┌─────────┼─────────┐ │ │ │ @@ -132,16 +133,19 @@ sandd --server-url ws://10.200.0.1:8765/ws \ ### Tunnel Mode (Production) -For secure multi-cloud deployments with mesh VPN: +For secure multi-cloud deployments with mesh VPN (no TLS setup needed): ```python -from sandd import Server +from sandd import Server, TunnelConfig config = TunnelConfig( authkey="YOUR_KEY", server="http://headscale:8080", ) -server = Server(connect="tunnel", tunnel_config=config) # Secure tunnel mode +server = Server(connect="tunnel", tunnel_config=config) +# ✓ Encrypted with WireGuard (no TLS needed) +# ✓ Works across NAT/firewalls +# ✓ No public IPs required ``` See [Tunnel Mode Guide](./docs/TUNNEL.md) for setup instructions. @@ -154,20 +158,8 @@ See [Tunnel Mode Guide](./docs/TUNNEL.md) for setup instructions. - [Development Guide](./docs/DEVELOP.md) - [Examples](./examples) -## Security - -⚠️ **Add security layers for production use:** - -- Use `wss://` (TLS) instead of plain `ws://` -- Add authentication (tokens, mTLS) -- Run workers in containers -- Validate commands before execution -- Audit log all commands - ## Roadmap -- [ ] **Authentication** - Token-based auth for daemon connections -- [ ] **TLS Support** - Built-in WSS with certificate management - [ ] **Audit Logging** - Track all commands, sessions, and file transfers - [ ] **Metrics** - Prometheus-compatible metrics for monitoring - [ ] **Resource Limits** - CPU/memory/timeout controls per daemon diff --git a/docs/TUNNEL.md b/docs/TUNNEL.md index eb72c52..3762963 100644 --- a/docs/TUNNEL.md +++ b/docs/TUNNEL.md @@ -105,13 +105,13 @@ Behind home router Behind cloud firewall ``` ┌────────────────────────────────────────┐ -│ 1. Coordination (Headscale) │ -│ "Who can join? Where are they?" │ +│ 1. Coordination (Headscale) │ +│ "Who can join? Where are they?" │ │ → Authentication & peer discovery │ └────────────────────────────────────────┘ + ┌────────────────────────────────────────┐ -│ 2. NAT Traversal (Hole Punching) │ +│ 2. NAT Traversal (Hole Punching) │ │ "How do I reach you behind NAT?" │ │ → Makes devices reachable │ └────────────────────────────────────────┘ @@ -147,7 +147,7 @@ Behind home router Behind cloud firewall ``` ┌──────────────────────────────┐ │ Headscale (Public) │ -│ 203.0.113.100:8080 │ +│ 203.0.113.100:8080 │ └──────────────────────────────┘ ↑ ↑ │ Outbound ✓ │ Outbound ✓ @@ -221,8 +221,8 @@ Daemon → Internet → Controller (public IP:8765) ### Tunnel Mode ``` ┌─────────────────────────────────────────────────────────┐ -│ Headscale Server │ -│ (runs once, centrally) │ +│ Headscale Server │ +│ (runs once, centrally) │ └─────────────────────────────────────────────────────────┘ ↑ ↑ │ │