Questions About Capturing HTTPS Traffic with Whistle
Whistle is a staple in my workflow, and most sites now default to HTTPS. To proxy those requests correctly, Whistle needs a bit of configuration.
Occasionally, things still go wrong—requests fail to appear, for example. Understanding the underlying design makes troubleshooting easier, so I’m collecting the key points here.
Pseudo Headers in Chrome DevTools
Inspecting HTTPS requests in Chrome reveals a few special headers.
HTTPS Request Headers
- These are
pseudo-header fields. - HTTP/1.x uses a request line (see RFC7230 §3.1) to express the target URI. HTTP/2 instead encodes method and status information in pseudo headers that begin with a colon (
:).
HTTP Request Headers
The Legacy X- Prefix
For decades the convention was to add an
X-prefix when defining custom headers—Xfor extension—per RFC 822. That’s why we still see headers likeX-Powered-By.
In June 2012 the IETF published RFC 6648, recommending that custom headers drop the X- prefix.
If you’re defining a permanently private header, consider namespacing it with your organization (for example, a reverse domain like com.example.foo).
Header Name Casing
Header names are case-insensitive, so write them however you prefer.
Each header field consists of a name followed by a colon (":") and the field value. Field names are case-insensitive.
Three Key Whistle Settings for HTTPS Capture
- Download RootCA
- Capture TUNNEL CONNECTS
- Enable HTTP/2
Installing the Certificate
After you download → install → trust Whistle’s certificate, the telltale sign that everything works is seeing Whistle listed as the issuer when you inspect a site’s certificate.
Why MitM Works
Without decrypting HTTPS, a proxy sees only the domain; request and response bodies remain opaque because of TLS. Whistle—and tools like Surge—solve this via a man-in-the-middle (MitM) approach.
MitM works because the proxy presents a self-signed certificate to the client and simultaneously maintains the real TLS connection to the origin server.
Capture TUNNEL CONNECTS
If this option is disabled, Whistle can’t capture HTTPS request and response bodies.
Why the name? Because:
- A tunnel is an HTTP application that blindly relays raw data across two connections once established.
- For HTTPS requests, the browser sends an HTTP
CONNECTmethod to the proxy to establish that tunnel.
Enable HTTP/2
Disable this option and Whistle will report HTTP/1.1 for requests and may mis-handle them entirely.
When Whistle Fails to Capture Traffic
Requests Missing from the Network Tab
Often the requests never hit Whistle because they bypass the proxy. A recent example from my setup:
My system proxy is Surge. Chrome sends traffic to Surge, which then forwards to Whistle on port 8899. I noticed that any service on the
192.168.x.xLAN wasn’t being captured. Turns out Surge had a “skip proxy” rule for internal addresses, so those requests never reached Whistle.
When this happens, double-check that your traffic is actually routed through Whistle.
Rules Not Working
Look at the request details in Whistle’s Network tab. If the rule section is empty, the rule didn’t match. At the moment, Whistle doesn’t validate rule syntax—it’s on you to ensure the configuration is correct.
Extras
Nginx and HTTP/2
Nginx can’t serve different protocols on the same port across multiple virtual hosts. For example, if port 443 hosts several server blocks and you enable HTTP/2 on just one, all of them effectively speak HTTP/2.
Final Thoughts
With these pieces understood, debugging Whistle’s HTTPS capture becomes much more manageable, and you can rely on the tool confidently.
