Skip to content

README.md

Latest commit

 

History

History
260 lines (204 loc) · 9.15 KB

README.md

File metadata and controls

260 lines (204 loc) · 9.15 KB

🚀 Rust Forward Proxy

Rust License: MIT Build Status

A high-performance HTTP/HTTPS forward proxy server written in Rust with advanced TLS interception, certificate management, and comprehensive logging capabilities.

✨ Features

🔒 Complete HTTPS Interception

  • TLS Termination & Re-encryption - Full decrypt/inspect/re-encrypt capability
  • Certificate Generation - Automatic domain certificate creation with CA signing
  • Certificate Caching - Memory & Redis backends for 25-30x performance improvement
  • Multiple Certificate Modes - Support for rootCA and Securly CA certificates

🌐 Full Proxy Capabilities

  • HTTP Request Interception - Complete request/response logging and modification
  • HTTPS CONNECT Tunneling - Standards-compliant tunnel for encrypted traffic
  • Dual Server Mode - Simultaneous HTTP (8080) and HTTPS (8443) operation
  • Production Logging - Clean INFO level for production, detailed DEBUG for development

⚡ High Performance

  • Async Architecture - Built on Tokio/Hyper for maximum throughput
  • Connection Pooling - Efficient upstream connection management
  • Smart Body Handling - Optimized request/response body processing
  • Certificate Caching - Sub-millisecond certificate retrieval

🔧 Developer Experience

  • Comprehensive CLI Tools - Certificate generation, validation, and server management
  • Flexible Configuration - Environment variables + configuration files
  • Docker Support - Production-ready containerization with Redis
  • Extensive Documentation - Complete guides for setup, deployment, and usage

🚀 Quick Start

Simple HTTP Proxy

# Start basic HTTP proxy
make dev

# Test HTTP request
curl -x http://127.0.0.1:8080 http://httpbin.org/get

# Test HTTPS tunneling
curl -x http://127.0.0.1:8080 https://httpbin.org/get

HTTPS Interception (See Encrypted Content)

# Setup root CA certificate for browser
make setup-ca

# Start HTTPS interception proxy
make dev

# Configure browser proxy: 127.0.0.1:8080
# Install rootCA.crt in browser (see BROWSER_SETUP.md)
# Browse to https://httpbin.org/get
# Check proxy logs - you'll see complete HTTPS content!

Production Deployment

# Production with Docker + Redis caching
make prod-docker

# Local production mode
make prod

📁 Project Structure

rust-forward-proxy/
├── 📦 src/                         # Core implementation
│   ├── 🌐 proxy/                   # HTTP/HTTPS proxy logic
│   │   ├── server.rs              # Main server implementation
│   │   ├── http_client.rs         # Optimized upstream client
│   │   └── streaming.rs           # Smart body handling
│   ├── 🔒 tls/                     # TLS & certificate management
│   │   ├── server.rs              # HTTPS termination server
│   │   ├── cert_gen.rs            # Certificate generation
│   │   ├── cache.rs               # Certificate caching (Memory/Redis)
│   │   └── config.rs              # TLS configuration
│   ├── ⚙️ config/                  # Configuration management
│   ├── 📋 logging/                 # Production-grade logging
│   ├── 🛠️ utils/                   # HTTP/URL/Time utilities
│   ├── 🎮 cli/                     # Command-line interface
│   └── 📊 models/                  # Data structures
├── 📚 docs/                        # Comprehensive documentation
├── 🐳 docker-compose.yml           # Docker deployment
├── 📋 Makefile                     # Development commands
└── 🧪 scripts/                     # Testing & setup scripts

🎯 How It Works

HTTP Request Flow

Client → [HTTP Proxy:8080] → [Full Interception] → [Log Everything] → Upstream
   ↖                                                                      ↙
    ↖                          [Response Logging]                       ↙
     ↖                                                                ↙
      ↖─────────────────── Clean Response ──────────────────────────↙

HTTPS Interception Flow

Client → [HTTPS Proxy:8443] → [TLS Terminate] → [Decrypt] → [Log Content] → [Re-encrypt] → Upstream
   ↖                                                                                           ↙
    ↖                                    [Certificate Cache]                                 ↙
     ↖                                                                                     ↙
      ↖─────────────────────────── Encrypted Response ────────────────────────────────↙

Certificate Generation Flow

Request for domain.com
        ↓
[Cache Check] → Hit: Return cached cert (0ms)
        ↓
     Miss: Generate new cert (5-10ms)
        ↓
[Sign with CA] → Cache for 24h → Return cert

🔧 Configuration

Certificate Modes

# Default mode (uses rootCA)
make dev

# Securly CA mode
CERT=securly make dev
# or
make dev-securly

Environment Variables

# Proxy Configuration
PROXY_LISTEN_ADDR=127.0.0.1:8080
HTTPS_LISTEN_ADDR=127.0.0.1:8443

# TLS Configuration
TLS_ENABLED=true
TLS_INTERCEPTION_ENABLED=true
TLS_CA_CERT_PATH=ca-certs/rootCA.crt
TLS_CA_KEY_PATH=ca-certs/rootCA.key

# Logging
RUST_LOG=info                    # Clean production logs
RUST_LOG=debug                   # Verbose development logs

# Redis (for certificate caching)
REDIS_URL=redis://redis:6379

📖 Documentation

🚀 Getting Started

🏗️ Architecture & Implementation

🚀 Deployment & Operations

🧪 Testing

# Test basic functionality
make test

# Test HTTPS interception
make test-intercept

# Test Docker deployment
make test-docker

# Run all tests
make test-all

🎯 Use Cases

🔍 Development & Debugging

  • API Development - See exactly what your applications send/receive
  • Security Testing - Analyze encrypted traffic for vulnerabilities
  • Network Debugging - Troubleshoot mysterious network issues

🛡️ Security & Monitoring

  • Traffic Analysis - Monitor and log all HTTP/HTTPS traffic
  • Content Filtering - Inspect and potentially modify requests/responses
  • Compliance Auditing - Log all network communications

⚡ Performance Testing

  • Load Testing - Proxy traffic for performance analysis
  • Caching Analysis - Understand application caching behavior
  • Bandwidth Monitoring - Track data usage and patterns

🚀 Performance

Benchmarks

  • HTTP Throughput: 1000+ requests/second
  • HTTPS Latency: +2-5ms overhead for interception
  • Certificate Generation: 5-10ms first request, <1ms cached
  • Memory Usage: ~10-50MB depending on load
  • Concurrent Connections: 1000+ simultaneous HTTPS sessions

Certificate Caching Performance

Without Caching: 25-30ms per HTTPS request
With Caching:     <1ms per HTTPS request
Performance Gain: 25-30x improvement

🤝 Contributing

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

📝 License

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

🙏 Acknowledgments

🎉 Ready to Start?

# Clone and run
git clone <your-repo-url>
cd rust-forward-proxy
make dev

# Start intercepting HTTP traffic in seconds!
curl -x http://127.0.0.1:8080 http://httpbin.org/get

🔥 For HTTPS interception, see our Browser Setup Guide to configure certificate trust!