Hyperfox: Building a Man-in-the-Middle Proxy with Go's Standard Library

Hook

Every HTTPS connection you make trusts dozens of certificate authorities you've never heard of—but with a MITM proxy like Hyperfox, you can become one yourself in under five minutes.

Context

Debugging encrypted web traffic has always been frustrating. When developers need to inspect API calls from mobile apps, diagnose SSL/TLS issues, or analyze encrypted traffic for security audits, they face a fundamental problem: HTTPS was designed to prevent exactly this kind of inspection. Traditional packet capture tools like tcpdump show only encrypted gibberish, while browser developer tools can't see traffic from native applications or IoT devices.

This gap created demand for MITM (man-in-the-middle) proxies that can decrypt, inspect, and re-encrypt HTTPS traffic transparently. Established tools like mitmproxy and Burp Suite dominate this space, but they come with complexity—Python dependencies, Java runtimes, steep learning curves, or commercial licenses. Hyperfox emerged as a minimal, Go-based alternative that does one thing well: intercept HTTP/HTTPS traffic and store it in a queryable database. Built with Go's excellent standard library support for TLS and HTTP/2, it provides the core MITM functionality in a single binary with an optional web UI for traffic inspection.

Technical Insight

Hyperfox's architecture reveals how Go's crypto/tls package makes building MITM proxies surprisingly straightforward. The core insight is that TLS interception requires two separate encrypted connections: one between the client and proxy, and another between the proxy and the real server. The proxy acts as a server to the client and as a client to the upstream server, decrypting traffic from both sides.

The magic happens during TLS handshake through Server Name Indication (SNI). When a client connects to example.com:443 via the proxy, the proxy reads the SNI field to determine the target domain, then dynamically generates a certificate for example.com signed by your provided CA certificate. Here's how Hyperfox implements this certificate generation:

// Simplified from hyperfox's certificate generation logic
func generateCert(host string, ca *tls.Certificate) (*tls.Certificate, error) {
    serialNumber, _ := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
    
    template := x509.Certificate{
        SerialNumber: serialNumber,
        Subject: pkix.Name{
            Organization: []string{"Hyperfox Proxy"},
            CommonName:   host,
        },
        NotBefore:             time.Now(),
        NotAfter:              time.Now().Add(365 * 24 * time.Hour),
        KeyUsage:              x509.KeyUsageKeyEncipherment | x509.KeyUsageDigitalSignature,
        ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
        BasicConstraintsValid: true,
        DNSNames:              []string{host},
    }
    
    // Sign with the CA's private key
    certDER, err := x509.CreateCertificate(rand.Reader, &template, caCert, &privateKey.PublicKey, caPrivateKey)
    // ... certificate packaging
}

This on-the-fly certificate generation is the crux of HTTPS interception. The client sees a valid certificate chain (assuming your CA is trusted) and establishes an encrypted connection to the proxy, while the proxy simultaneously connects to the real server with proper encryption. Both sides think they have end-to-end encryption, but the proxy sits in the middle reading plaintext.

For traffic persistence, Hyperfox makes an elegant choice: SQLite. Each proxy session creates a timestamped database file containing all intercepted requests and responses. This design decision offers several advantages over alternatives like plain text logs or in-memory storage. The schema is straightforward—tables for requests, responses, headers, and bodies—making post-capture analysis with SQL queries trivial:

SELECT origin, url, status, LENGTH(body) as size 
FROM response 
WHERE content_type LIKE '%json%' 
ORDER BY created DESC 
LIMIT 20;

The built-in web UI queries this database via a REST API, providing real-time traffic inspection without requiring external tools. The API endpoint /api/log streams captured traffic as JSON, making it easy to build custom analysis tools or integrate with CI/CD pipelines for automated security scanning.

Hyperfox also handles a subtle challenge in proxy testing: DNS resolution. When testing locally with modified /etc/hosts entries, you often want the proxy to bypass system DNS and use your custom mappings. Hyperfox supports custom DNS resolution through its -addr flag, allowing patterns like -addr example.com=127.0.0.1:8080 to route specific domains to localhost services. This feature becomes critical when testing mobile apps that ignore system proxy settings or when performing network-level traffic interception through ARP spoofing.

The HTTP/2 support deserves mention because it's essentially free—Go's net/http package handles HTTP/2 automatically when serving over TLS. This means Hyperfox intercepts modern HTTP/2 traffic without additional implementation complexity, a testament to Go's well-designed standard library. The same proxy code that handles HTTP/1.1 seamlessly upgrades connections to HTTP/2 when clients request it via ALPN (Application-Layer Protocol Negotiation) during the TLS handshake.

Gotcha

The biggest gotcha with Hyperfox is certificate trust configuration—it's both the hardest part and the most critical. You must generate a CA certificate, configure Hyperfox to use it, then install that CA as trusted on every device you want to intercept. On iOS, this requires navigating through Settings → General → Profile → Certificate Trust Settings. On Android, you'll wrestle with user vs. system certificate stores, with Android 7+ requiring apps to explicitly opt into trusting user certificates. Corporate MDM environments create additional friction. Miss this setup on even one test device, and you'll see certificate errors for every HTTPS request with zero visibility into why.

The security model for the web UI is minimalist to the point of concern. The REST API generates a random key on startup (--api-key flag), but this key appears in your shell history, process listings, and gets transmitted in plain HTTP headers. There's no user authentication, no HTTPS option for the UI itself, and no rate limiting. If you're running Hyperfox on a shared network or cloud instance, anyone who discovers the API key can view your entire captured traffic database, potentially including authentication tokens, API keys, and sensitive user data. For serious security work, you'll want to tunnel the UI through SSH or put it behind a proper reverse proxy with authentication. The tool clearly prioritizes convenience over security, which is fine for local development but dangerous in any multi-user environment.

Verdict

Use if: You need a lightweight, Go-based proxy for security auditing, mobile app debugging, or API traffic analysis in controlled environments where you have full certificate trust control. The single-binary deployment and SQLite persistence make it excellent for reproducible security testing, CI/CD integration, or documentation of API behavior. It's particularly valuable when working with Go services where you might want to extend or modify the proxy code for custom inspection logic. Skip if: You need production-grade authentication, can't install custom root certificates on target devices (corporate MDM, locked-down systems), or require advanced features like request rewriting, scripting, or complex filtering rules. Also skip for anything involving sensitive production traffic without additional security hardening—the minimal API security model isn't suitable for shared environments. For those cases, mitmproxy's mature ecosystem or Burp Suite's enterprise features are worth the additional complexity.