Skip to content

Jo-spect/anyproxy

BranchesTags
 
 

Repository files navigation

AnyProxy

License: MIT Go Version Ask DeepWiki Build Status Release

AnyProxy is a secure tunneling solution that enables you to expose local services to the internet through multiple transport protocols. Built with a modular architecture supporting WebSocket, gRPC, and QUIC transports with end-to-end TLS encryption.

📑 Table of Contents

✨ Key Features

  • 🔄 Multiple Transport Protocols: Choose between WebSocket, gRPC, or QUIC
  • 🔐 End-to-End TLS Encryption: Secure communication for all protocols
  • 🚀 Triple Proxy Support: HTTP/HTTPS, SOCKS5, and TUIC proxies
    • HTTP Proxy: Standard web browsing and API access
    • SOCKS5 Proxy: Universal protocol support with low overhead
    • TUIC Proxy: Ultra-low latency UDP-based proxy with 0-RTT handshake
  • 🎯 Group-Based Routing: Route traffic to specific client groups
  • ⚡ Port Forwarding: Direct port mapping for services
  • 🌐 Cross-Platform: Linux, macOS, Windows support
  • 🐳 Container Ready: Official Docker images available

🏗️ Architecture Overview

System Architecture

Internet Users                       Public Gateway Server                   Private Networks
     │                                       │                                     │
     │ ◄─── HTTP/SOCKS5/TUIC Proxy ──► ┌─────────────┐ ◄─── TLS Tunnels ───► ┌──────────────┐
     │                                 │   Gateway   │                       │   Clients    │
     │                                 │             │                       │              │
     │                                 │ • HTTP:8080 │                       │ • SSH Server │
     │                                 │ • SOCKS:1080│                       │ • Web Apps   │
     │                                 │ • TUIC:9443 │                       │ • Databases  │
     │                                 │             │                       │ • AI Models  │
     │                                 │ Transports: │                       │              │
     │                                 │ • WS:8443   │                       │              │
     │                                 │ • gRPC:9090 │                       │              │
     │                                 │ • QUIC:9091 │                       │              │
     │                                 └─────────────┘                       └──────────────┘
     │                                        │                                     │
SSH, Web, AI ←────────────────── Secure Proxy Connection ──────────────→ Local Services

Transport Protocols Comparison

Transport Best For Key Benefits Port
WebSocket Firewall compatibility • Works through most firewalls
• HTTP/HTTPS compatible
• Wide browser support		 8443
gRPC High performance • HTTP/2 multiplexing
• Efficient binary protocol
• Built-in load balancing		 9090
QUIC Mobile/unreliable networks • Ultra-low latency
• 0-RTT handshake
• Connection migration		 9091

Proxy Protocols Comparison

Protocol Type Best For Key Features Port
HTTP TCP Web browsing, API calls • Standard HTTP CONNECT
• Compatible with all browsers
• Simple authentication		 8080
SOCKS5 TCP General purpose • Protocol agnostic
• Low overhead
• Wide client support		 1080
TUIC UDP Gaming, real-time apps • 0-RTT connection setup
• Built-in multiplexing
• Connection migration
• TLS 1.3 required		 9443

Note: Each Gateway/Client instance uses only ONE transport protocol.

Group-Based Routing Architecture

                              Gateway Server
                          ┌─────────────────────┐
  User Requests           │   Route by Group    │           Client Groups
       │                  │                     │                │
       ├─ user.prod ────► │  ┌─────────────┐    │ ────► ┌─────────────────┐
       │                  │  │  Prod Group │    │       │  Production Env │
       │                  │  │   Router    │    │       │ • prod-api.com  │
       │                  │  └─────────────┘    │       │ • prod-db:5432  │
       │                  │                     │       └─────────────────┘
       ├─ user.staging ──►│  ┌─────────────┐    │ ────► ┌─────────────────┐
       │                  │  │ Staging     │    │       │  Staging Env    │
       │                  │  │  Router     │    │       │ • staging-api   │
       │                  │  └─────────────┘    │       │ • staging-db    │
       │                  │                     │       └─────────────────┘
       └─ user.dev ──────►│  ┌─────────────┐    │ ────► ┌─────────────────┐
                          │  │   Dev       │    │       │  Development    │
                          │  │  Router     │    │       │ • localhost:*   │
                          │  └─────────────┘    │       │ • dev-services  │
                          └─────────────────────┘       └─────────────────┘

Usage Examples:
• curl -x http://user.prod:pass@gateway:8080 https://prod-api.com
• curl -x http://user.staging:pass@gateway:8080 https://staging-api.com  
• curl -x http://user.dev:pass@gateway:8080 http://localhost:3000

Port Forward Architecture

Internet Access                Gateway Server               Target Services
      │                    ┌──────────────────┐                   │
      │                    │  Port Mappings   │                   │
      ├─ SSH :2222 ──────► │ 2222 → Client A  │─────────────► SSH:22
      │                    │                  │                   │
      ├─ HTTP :8000 ─────► │ 8000 → Client B  │─────────────► Web:80
      │                    │                  │                   │ 
      ├─ DB :5432 ───────► │ 5432 → Client C  │─────────────► PostgreSQL :5432
      │                    │                  │                   │
      └─ API :3000 ──────► │ 3000 → Client D  │─────────────► API Server :3000
                           └──────────────────┘

Configuration Example:
open_ports:
  - remote_port: 2222    # Gateway listens on :2222
    local_port: 22       # Forward to client's SSH :22
    local_host: "localhost"
    protocol: "tcp"
    
  - remote_port: 5432    # Gateway listens on :5432  
    local_port: 5432     # Forward to internal database
    local_host: "database.internal"
    protocol: "tcp"

Access: ssh -p 2222 user@gateway.example.com
       psql -h gateway.example.com -p 5432 mydb

🚀 Quick Start

Prerequisites

  • Public Server for Gateway deployment (with public IP)
  • Private Network with services you want to expose
  • Docker installed on both environments

Step 1: Deploy Gateway (Public Server)

# On your public server (e.g., VPS, Cloud instance)
mkdir anyproxy-gateway && cd anyproxy-gateway
mkdir -p configs certs logs

Gateway Configuration:

cat > configs/gateway.yaml << 'EOF'
log:
  level: "info"
  format: "json"
  output: "file"
  file: "logs/gateway.log"

transport:
  type: "websocket"  # Choose: websocket, grpc, or quic

proxy:
  http:
    listen_addr: ":8080"
    auth_username: "proxy_user"
    auth_password: "secure_proxy_password"
  socks5:
    listen_addr: ":1080"
    auth_username: "socks_user"
    auth_password: "secure_socks_password"
  tuic:
    listen_addr: ":9443"
    token: "your-tuic-token-here"
    uuid: "12345678-1234-5678-9abc-123456789abc"
    cert_file: "certs/server.crt"
    key_file: "certs/server.key"

gateway:
  listen_addr: ":8443"  # WebSocket port (use :9090 for gRPC, :9091 for QUIC)
  tls_cert: "certs/server.crt"
  tls_key: "certs/server.key"
  auth_username: "gateway_admin"
  auth_password: "very_secure_gateway_password"
EOF

Generate Certificates & Start:

# Generate certificate
openssl req -x509 -newkey rsa:2048 -keyout certs/server.key -out certs/server.crt \
    -days 365 -nodes -subj "/CN=YOUR_PUBLIC_DOMAIN_OR_IP"

# Start gateway
docker run -d --name anyproxy-gateway \
  --restart unless-stopped \
  -p 8080:8080 -p 1080:1080 -p 9443:9443/udp -p 8443:8443 \
  -v $(pwd)/configs:/app/configs:ro \
  -v $(pwd)/certs:/app/certs:ro \
  -v $(pwd)/logs:/app/logs \
  buhuipao/anyproxy:latest ./anyproxy-gateway --config configs/gateway.yaml

Step 2: Deploy Client (Private Network)

# On your private network machine
mkdir anyproxy-client && cd anyproxy-client
mkdir -p configs certs logs

# Copy server certificate from gateway

Client Configuration:

cat > configs/client.yaml << 'EOF'
log:
  level: "info"
  format: "json"
  output: "file"
  file: "logs/client.log"

transport:
  type: "websocket"  # Must match gateway transport

client:
  gateway_addr: "YOUR_PUBLIC_SERVER_IP:8443"  # Replace with your gateway IP
  gateway_tls_cert: "certs/server.crt"
  client_id: "home-client-001"
  group_id: "homelab"
  replicas: 1
  auth_username: "gateway_admin"
  auth_password: "very_secure_gateway_password"
  
  # Security: Only allow specific local services
  allowed_hosts:
    - "localhost:22"        # SSH
    - "localhost:80"        # Web server
    - "localhost:3000"      # Dev server
    
  # Block dangerous hosts
  forbidden_hosts:
    - "169.254.0.0/16"      # Cloud metadata
    - "127.0.0.1"           # Localhost
    - "0.0.0.0"
    
  # Optional: Port forwarding
  open_ports:
    - remote_port: 2222     # Gateway port
      local_port: 22        # Local SSH port
      local_host: "localhost"
      protocol: "tcp"
EOF

Start Client:

docker run -d --name anyproxy-client \
  --restart unless-stopped \
  --network host \
  -v $(pwd)/configs:/app/configs:ro \
  -v $(pwd)/certs:/app/certs:ro \
  -v $(pwd)/logs:/app/logs \
  buhuipao/anyproxy:latest ./anyproxy-client --config configs/client.yaml

Step 3: Test Connection

# Test HTTP proxy
curl -x http://proxy_user:secure_proxy_password@YOUR_PUBLIC_SERVER_IP:8080 \
  http://localhost:80

# Test SOCKS5 proxy
curl --socks5 socks_user:secure_socks_password@YOUR_PUBLIC_SERVER_IP:1080 \
  http://localhost:22

# Test TUIC proxy (requires TUIC-compatible client)
# Use TUIC client with: tuic://your-tuic-token@YOUR_PUBLIC_SERVER_IP:9443?uuid=12345678-1234-5678-9abc-123456789abc

# Test port forwarding (if configured)
ssh -p 2222 user@YOUR_PUBLIC_SERVER_IP

🎯 Common Use Cases

1. SSH Server Access

Quick SSH Setup:

# Gateway: Standard setup with SOCKS5
# Client: Allow SSH only
cat > configs/ssh-client.yaml << 'EOF'
transport:
  type: "websocket"

client:
  gateway_addr: "YOUR_GATEWAY_IP:8443"
  gateway_tls_cert: "certs/server.crt"
  client_id: "ssh-client"
  group_id: "ssh"
  replicas: 1
  auth_username: "gateway_admin"
  auth_password: "very_secure_gateway_password"
  allowed_hosts:
    - "localhost:22"
  forbidden_hosts:
    - "169.254.0.0/16"
EOF

# Connect via SSH
ssh -o "ProxyCommand=nc -X 5 -x socks_user:secure_socks_password@YOUR_GATEWAY_IP:1080 %h %p" user@localhost

2. Web Development

Development Server Access:

# Use QUIC for better performance
transport:
  type: "quic"

gateway:
  listen_addr: ":9091"  # QUIC port

client:
  gateway_addr: "YOUR_GATEWAY_IP:9091"
  allowed_hosts:
    - "localhost:*"
    - "127.0.0.1:*"

# Access local dev servers
curl -x http://proxy_user:secure_proxy_password@YOUR_GATEWAY_IP:8080 http://localhost:3000

3. Database Access

Database Tunnel Setup:

# Use port forwarding for direct database access
open_ports:
  - remote_port: 5432
    local_port: 5432
    local_host: "database.internal"
    protocol: "tcp"

# Connect directly
psql -h YOUR_GATEWAY_IP -p 5432 -U postgres mydb

4. TUIC Proxy (Ultra-Low Latency)

TUIC Setup for 0-RTT Performance:

# Gateway: Enable TUIC proxy in configuration
proxy:
  tuic:
    listen_addr: ":9443"
    token: "your-secure-token"
    uuid: "12345678-1234-5678-9abc-123456789abc"
    cert_file: "certs/server.crt"
    key_file: "certs/server.key"

# TUIC provides:
# - 0-RTT connection establishment
# - Built-in UDP and TCP multiplexing
# - Optimal for mobile networks
# - Enhanced connection migration

# Client usage (with TUIC-compatible clients):
# tuic://your-secure-token@YOUR_GATEWAY_IP:9443?uuid=12345678-1234-5678-9abc-123456789abc

TUIC is ideal for:

  • Gaming Applications: Minimal latency for real-time gaming
  • Video Streaming: Smooth streaming with connection migration
  • Mobile Networks: Handles network switching seamlessly
  • IoT Devices: Efficient for frequent short-lived connections
  • Real-time Communications: VoIP, video calls, live chat

Performance Benefits:

  • 0-RTT Handshake: Connect instantly without round-trip delays
  • Connection Migration: Maintain connections when switching networks
  • Multiplexing: Multiple data streams over single UDP connection
  • TLS 1.3: Modern encryption with perfect forward secrecy

⚙️ Configuration

Transport Selection

Choose ONE transport per Gateway/Client pair:

# WebSocket (Recommended for most cases)
transport:
  type: "websocket"
gateway:
  listen_addr: ":8443"

# gRPC (High performance)
transport:
  type: "grpc"
gateway:
  listen_addr: ":9090"

# QUIC (Mobile/unstable networks)
transport:
  type: "quic"
gateway:
  listen_addr: ":9091"

TUIC Proxy Configuration

proxy:
  tuic:
    listen_addr: ":9443"               # UDP port for TUIC
    token: "your-tuic-token"           # TUIC protocol token
    uuid: "12345678-1234-5678-9abc-123456789abc"  # TUIC client UUID
    cert_file: "certs/server.crt"      # TLS certificate (required)
    key_file: "certs/server.key"       # TLS private key (required)

TUIC Protocol Features:

  • 0-RTT Handshake: Ultra-fast connection establishment
  • UDP-Based: Built on QUIC for optimal performance
  • TLS 1.3 Required: Mandatory encryption
  • Multiplexing: Multiple streams over single connection
  • Connection Migration: Seamless network switching

Security Configuration

client:
  # Block dangerous hosts
  forbidden_hosts:
    - "169.254.0.0/16"      # Cloud metadata
    - "127.0.0.1"           # Localhost
    - "10.0.0.0/8"          # Private networks
    - "172.16.0.0/12"
    - "192.168.0.0/16"
  
  # Only allow specific services
  allowed_hosts:
    - "localhost:22"        # SSH only
    - "localhost:80"        # HTTP only
    - "localhost:443"       # HTTPS only

🐳 Docker Deployment

Gateway (Public Server)

# docker-compose.gateway.yml
version: '3.8'
services:
  anyproxy-gateway:
    image: buhuipao/anyproxy:latest
    container_name: anyproxy-gateway
            command: ./anyproxy-gateway --config configs/gateway.yaml
    ports:
      - "8080:8080"     # HTTP proxy
      - "1080:1080"     # SOCKS5 proxy
      - "9443:9443/udp" # TUIC proxy (UDP)
      - "8443:8443"     # WebSocket (or 9090 for gRPC, 9091 for QUIC)
    volumes:
      - ./configs:/app/configs:ro
      - ./certs:/app/certs:ro
      - ./logs:/app/logs
    restart: unless-stopped

Client (Private Network)

# docker-compose.client.yml
version: '3.8'
services:
  anyproxy-client:
    image: buhuipao/anyproxy:latest
    container_name: anyproxy-client
            command: ./anyproxy-client --config configs/client.yaml
    volumes:
      - ./configs:/app/configs:ro
      - ./certs:/app/certs:ro
      - ./logs:/app/logs
    restart: unless-stopped
    network_mode: host

🔐 Security

Certificate Management

# Generate certificate
openssl req -x509 -newkey rsa:2048 -keyout certs/server.key -out certs/server.crt \
    -days 365 -nodes -subj "/CN=YOUR_DOMAIN"

# Or use Let's Encrypt
certbot certonly --standalone -d gateway.yourdomain.com

📊 Troubleshooting

Basic Health Checks

# Check gateway connectivity
curl -x http://user:pass@gateway:8080 https://httpbin.org/ip

# Check TUIC proxy port (UDP)
nc -u -v gateway 9443

# Check logs
docker logs anyproxy-gateway
docker logs anyproxy-client

# Test specific service
curl -x http://user:pass@gateway:8080 http://localhost:22

Common Issues

  • Connection refused: Check firewall and port configuration
  • Authentication failed: Verify usernames and passwords in configs
  • Certificate errors: Ensure certificate matches domain/IP
  • Transport mismatch: Ensure Gateway and Client use the same transport type

🔗 Integration

Python Example

import requests

proxies = {
    'http': 'http://user:pass@gateway.com:8080',
    'https': 'http://user:pass@gateway.com:8080'
}

response = requests.get('http://localhost:8000/api', proxies=proxies)
print(response.json())

cURL Example

# HTTP proxy
curl -x http://user:pass@gateway:8080 http://localhost:3000

# SOCKS5 proxy
curl --socks5 user:pass@gateway:1080 http://localhost:22

📚 Quick Reference

Default Ports:

  • HTTP Proxy: 8080
  • SOCKS5 Proxy: 1080
  • TUIC Proxy: 9443 (UDP)
  • WebSocket: 8443, gRPC: 9090, QUIC: 9091

Key Commands:

# Start gateway
./anyproxy-gateway --config gateway.yaml

# Start client  
./anyproxy-client --config client.yaml

# Test connection
curl -x http://user:pass@gateway:8080 https://httpbin.org/ip

🤝 Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ by the AnyProxy team

Support & Community

For the latest updates and releases, visit our GitHub repository.

About

Expose your local network and services to public safely

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Go 94.0%
  • Shell 4.5%
  • Makefile 1.1%
  • Dockerfile 0.4%