SPP (Simple & Powerful Proxy)

SPP is a versatile, high-performance network proxy and traffic-forwarding tool written in Go.

Disclaimer: This tool is intended exclusively for academic, research, and authorized testing purposes. Do not use it for unauthorized or illegal activities.

• Features
• Installation
• Quick Start
  • 1. Automatic Configuration Generator (Recommended)
  • 2. Command-Line Usage
• Proxy Modes & Examples
  • Port Forwarding (Forward Proxy)
  • NAT Traversal / Intranet Penetration (Reverse Proxy)
  • SOCKS5 Proxy (Forward & Reverse)
  • HTTP / HTTPS Proxy (Forward & Reverse)
  • Cross-Protocol Tunneling (QUIC / KCP / RUDP / RICMP)
• Configuration Files
• Performance & Benchmark
• Health Check & Monitoring
• Ecosystem & Plugins
• Documentation
• License

• Multi-Protocol Transit: Supports establishing tunnel connections over TCP, UDP, RUDP (Reliable UDP), RICMP (Reliable ICMP ping tunnel), RHTTP (Reliable HTTP), KCP, and QUIC.
• Protocol Multiplexing & Conversion: Transparently tunnel TCP or UDP traffic through any supported reliable transit protocol across network boundaries. Multiple forwarding rules share a single multiplexed transit tunnel.
• Versatile Proxy Topologies:
  • Forward Proxy: Expose remote services on a local port.
  • Reverse Proxy: Expose local services behind NATs/firewalls to the public server.
  • SOCKS5 Proxy: Standard SOCKS5 proxy supporting both TCP streaming and UDP relay (UDP ASSOCIATE), with optional username/password authentication.
  • Reverse SOCKS5 Proxy: Turn the public server into a SOCKS5 entrypoint routing out through the client network.
  • HTTP/HTTPS Proxy: Full HTTP proxy supporting standard HTTP methods and HTTPS tunneling (CONNECT), with optional Basic authentication.
  • Reverse HTTP/HTTPS Proxy: Provide an HTTP/HTTPS proxy endpoint on the public server backed by the client.
  • Shadowsocks SIP003 Plugin: Pluggable transport support via spp-shadowsocks-plugin.
• Strong Security:
  • HMAC-SHA256 challenge-response handshake (-key); credentials are never transmitted in plaintext.
  • Full-payload AEAD wire encryption (-encrypt) using ChaCha20-Poly1305 or AES-GCM.
  • Strict key requirement: no insecure default passwords.
• High Performance & Low Latency:
  • High-throughput streaming with configurable zstd (default) or zlib compression.
  • Multi-queue priority scheduling ensuring low-latency delivery of control and handshake frames.
  • Zero-cost log bypass mode (-nolog 1 -noprint 1) for extreme throughput environments.
• Operational Reliability:
  • Health probe endpoints (/healthz and /status via -statusaddr).
  • Active keepalive ping monitoring and auto-reconnection.
  • Graceful shutdown on standard OS termination signals.

Download ready-to-use binaries for Linux, macOS, and Windows from the Releases page.

Requirements: Go 1.20 or newer.

git clone https://github.com/esrrhs/spp.git
cd spp
go build -o spp .

SPP provides an official container image:

# Pull image
docker pull esrrhs/spp:latest

# Run SPP server with host networking
docker run -d --name spp-server --net=host esrrhs/spp \
  -type server -proto tcp -listen :8888 -key "your-auth-key" -encrypt "your-encrypt-key"

Generate an all-protocol server configuration alongside ready-to-use client templates with a single command:

./spp -genconfig
# Or generate into a dedicated directory:
./spp -genconfig -outdir ./conf -force

This generates paired configurations pre-populated with matching secure random keys:

• config_server.json: Preconfigured with multi-protocol listeners (tcp, rudp, ricmp, kcp, quic, rhttp).
• config_proxy_client.json: Forward port proxy client.
• config_reverse_proxy_client.json: Reverse port proxy client.
• config_socks5_client.json: Local SOCKS5 proxy client.
• config_reverse_socks5_client.json: Reverse SOCKS5 proxy client.
• config_http_client.json: Local HTTP/HTTPS proxy client.
• config_reverse_http_client.json: Reverse HTTP/HTTPS proxy client.

Start the instances:

# Run server
./spp -config config_server.json

# Run desired client (e.g., SOCKS5)
./spp -config config_socks5_client.json

Both endpoints must use matching -key (authentication) and -encrypt (wire encryption) flags.

Listen on TCP port 8888:

./spp -type server -proto tcp -listen :8888 \
  -key "your-auth-key" -encrypt "your-encrypt-key"

The server can also listen on multiple protocols and ports simultaneously:

./spp -type server \
  -proto tcp -listen :8888 \
  -proto rudp -listen :9999 \
  -proto quic -listen :4433 \
  -key "your-auth-key" -encrypt "your-encrypt-key"

Forward a local port through the SPP server to a target destination:

# Forward local port 8080 to target remote 8080 over TCP
./spp -type proxy_client -server www.server.com:8888 \
  -fromaddr :8080 -toaddr :8080 -proxyproto tcp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

Forward multiple ports (TCP + UDP) over one tunnel:

./spp -type proxy_client -server www.server.com:8888 \
  -fromaddr :8080 -toaddr :8080 -proxyproto tcp \
  -fromaddr :9000 -toaddr :9000 -proxyproto udp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

Expose a local internal service to visitors reaching the public SPP server:

# External clients accessing server:8080 are routed to local service on 8080
./spp -type reverse_proxy_client -server www.server.com:8888 \
  -fromaddr :8080 -toaddr :8080 -proxyproto tcp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

Start a SOCKS5 proxy on local port 1080 forwarding outbound requests via the server (supports TCP and UDP relay):

./spp -type socks5_client -server www.server.com:8888 \
  -fromaddr :1080 -proxyproto tcp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

With authentication:

./spp -type socks5_client -server www.server.com:8888 \
  -fromaddr :1080 -proxyproto tcp \
  -username "admin" -password "secret" \
  -key "your-auth-key" -encrypt "your-encrypt-key"

Open a SOCKS5 entrypoint on the public server (e.g. port 1080), egressing through the client's internal network:

./spp -type reverse_socks5_client -server www.server.com:8888 \
  -fromaddr :1080 -proxyproto tcp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

Spawn an HTTP proxy on local port 8080 (supporting standard HTTP and HTTPS CONNECT tunnels):

./spp -type http_client -server www.server.com:8888 \
  -fromaddr :8080 -proxyproto tcp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

With Basic Auth:

./spp -type http_client -server www.server.com:8888 \
  -fromaddr :8080 -proxyproto tcp \
  -username "admin" -password "secret" \
  -key "your-auth-key" -encrypt "your-encrypt-key"

Open an HTTP proxy port on the public server that tunnels traffic out through the client network:

./spp -type reverse_http_client -server www.server.com:8888 \
  -fromaddr :8080 -proxyproto tcp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

SPP allows wrapping application traffic (proxyproto) inside any supported transit protocol (proto).

• Tunnel over QUIC:

  ./spp -type proxy_client -proto quic -server www.server.com:4433 \
    -fromaddr :8080 -toaddr :8080 -proxyproto tcp \
    -key "your-auth-key" -encrypt "your-encrypt-key"

• Tunnel over KCP with Reed-Solomon FEC:

  # Client side with 10 data shards and 3 parity shards
  ./spp -type socks5_client -proto kcp -server www.server.com:8888 \
    -kcpfecdata 10 -kcpfecparity 3 \
    -fromaddr :1080 -proxyproto tcp \
    -key "your-auth-key" -encrypt "your-encrypt-key"

• Tunnel over ICMP Echo Ping (RICMP, bypasses TCP/UDP blocking):

  # Server listening on ICMP (requires root/CAP_NET_RAW)
  ./spp -type server -proto ricmp -listen 0.0.0.0 -key "your-key" -encrypt "your-key"
  
  # Client connecting via ICMP
  ./spp -type socks5_client -proto ricmp -server www.server.com \
    -fromaddr :1080 -proxyproto tcp -key "your-key" -encrypt "your-key"

Instead of lengthy CLI commands, manage configurations with JSON files:

{
  "type": "socks5_client",
  "server": "1.2.3.4:8888",
  "proto": ["tcp"],
  "proxyproto": ["tcp"],
  "fromaddr": [":1080"],
  "key": "your-auth-key",
  "encrypt": "your-encrypt-key",
  "encrypttype": "chacha20",
  "compress": 128,
  "compresstype": "zstd"
}

Load the configuration file:

./spp -config client.json

Maximum single-machine bandwidth testing with TCP proxy over various transit protocols (tested via iperf):

SPP provides a built-in lightweight HTTP status server via -statusaddr:

./spp -type server -proto tcp -listen :8888 -statusaddr 127.0.0.1:6060 -key "key"

Endpoints:

• http://127.0.0.1:6060/healthz — Returns 200 OK ("ok") for orchestrator readiness and liveness probes.
• http://127.0.0.1:6060/status — Returns internal telemetry and state.

• Android App: spp_client_android provides an easy-to-use VPN GUI for Android devices powered by SPP.
• Shadowsocks Plugin: spp-shadowsocks-plugin integrates SPP as a SIP003 transport plugin for Shadowsocks.

For advanced scenarios, full parameter descriptions, protocol matrix details, and fine-tuning options: 👉 Read the Full Usage Guide (USAGE.md)

This project is licensed under the MIT License.