Shuttle: Building a Rule-Based Multi-Protocol Proxy with MITM Inspection in Go
Hook
Most developers think proxies just forward traffic. Shuttle intercepts, inspects, rewrites, and routes every packet through a rule engine—all while preventing DNS poisoning and supporting multiple concurrent protocol listeners.
Context
In regions with network restrictions or for developers debugging complex API integrations, you need more than a simple proxy. You need traffic inspection, protocol flexibility, and intelligent routing. Traditional tools force you to choose: either get powerful MITM capabilities with tools like mitmproxy but sacrifice daily routing convenience, or use fast protocol proxies like Shadowsocks but lose visibility into what’s actually happening on the wire.
Shuttle emerged as a hybrid solution: a local proxy server that speaks multiple protocols simultaneously while providing deep HTTP/HTTPS inspection and rule-based routing. Built in Go for cross-platform deployment, it runs three listening ports on your machine—HTTP/HTTPS on 8080, SOCKS5 on 8081, and a web dashboard on 8082. This architecture lets you route browser traffic through HTTP, terminal commands through SOCKS5, and monitor everything through a web interface. The tool provides protocol versatility with inspection capabilities, distributed as a Go binary with configuration files.
Technical Insight
Shuttle’s architecture centers on a request interception pipeline that separates protocol handling from routing logic. When traffic arrives at any of the three ports, it enters a unified processing flow: protocol decoding → DNS resolution → rule matching → server selection → request forwarding. This modular design means the same routing rules apply whether you’re using HTTP, HTTPS, or SOCKS5.
The DNS resolution layer offers three resolution strategies to prevent DNS cache poisoning. The configuration supports per-domain DNS behavior with three types: remote (resolve via remote proxy server), direct (use local DNS with specified server), and static (static address mapping). The remote type forwards DNS queries through the proxy server itself, ensuring you get authentic responses. This happens transparently—your applications never know they’re getting remotely-resolved addresses.
Rule-based routing builds on this DNS layer. Shuttle evaluates each request against an ordered rule list, supporting domain matching (DOMAIN for full match, DOMAIN-SUFFIX for suffix match, DOMAIN-KEYWORD for keyword match), IP-CIDR ranges, and GeoIP lookups. The Policy field can reference server groups, not just individual servers. Shuttle supports grouping multiple upstream proxies—the README confirms support for Shadowsocks, SOCKS5, and SOCKS5-over-TLS protocols—and selecting between them based on RTT (round-trip time) or manual preference. This turns Shuttle into a load balancer that can automatically fail over to faster servers.
For HTTP/HTTPS traffic, Shuttle goes beyond simple forwarding with its MITM capabilities. When enabled, the tool can decrypt HTTPS traffic for inspection (requiring installation of its root CA). The configuration supports request/response header modification and URL rewriting, making Shuttle valuable for development scenarios: test CORS configurations, inject authentication headers, or mock API responses by rewriting URLs to local files in the RespFiles/ directory. The web dashboard at port 8082 shows traffic details, letting you inspect request/response pairs and analyze connections.
The server selection mechanism supports RTT-based selection, where Shuttle measures latency to servers in a group. Requests can be routed to faster responding servers with periodic re-evaluation. Server groups are configured with a policy of either RTT or Manual selection. The implementation benefits from Go’s lightweight goroutines for concurrent health checking without blocking request processing.
Gotcha
Shuttle’s biggest limitation is its lack of UDP support. The README explicitly shows UDP with an unchecked checkbox in the features list, confirming this is a known unimplemented feature. Despite supporting SOCKS5 protocol (which includes UDP association in the spec), actual UDP proxying isn’t available. This eliminates use cases like gaming, VoIP applications, or modern QUIC-based protocols.
The project’s documentation has gaps. The README mentions an API document (linked as static/API.md) but detailed API documentation isn’t fully provided in the materials. Traffic capture and request mapping features are listed in the feature checklist but lack detailed configuration examples—you may need to examine source code to understand advanced features. The README’s Configuration section, while comprehensive for basic setup, doesn’t provide complete YAML syntax examples for all features like DNS configuration, rule matching, and MITM header modification.
Platform setup requires manual system proxy configuration on macOS and Windows. The README provides step-by-step instructions, but you’ll need to configure system preferences yourself—Shuttle doesn’t auto-configure your OS proxy settings. The tool also requires maintaining separate configuration files (shuttle.yaml) and a response files directory (RespFiles/), so it’s not a truly standalone binary.
The Web UI is built with Angular 6 and Ant Design according to the README. While functional, developers should be aware of the technology stack when considering maintenance or customization.
Verdict
Use Shuttle if you need a local proxy that combines protocol flexibility with HTTP/HTTPS inspection for development, debugging, or personal use in network-restricted environments. It excels when you want to: route different applications through different proxy servers based on domain rules, inspect and modify HTTPS traffic, prevent DNS poisoning while maintaining fast local resolution for internal domains, or test API integrations by rewriting requests and mocking responses. The Go-based binary with web dashboard makes it accessible for developers comfortable with command-line tools and YAML configuration. Skip Shuttle if you need UDP support for gaming or VoIP, require comprehensive documentation without source-diving, want automatic OS proxy configuration, or need a completely standalone binary without external configuration files. The project appears suitable for technical users who can work with the provided documentation and don’t mind occasional configuration troubleshooting.
