Decrypting TLS Traffic with PolarProxy

This is a guest blog post by Erik Hjelmvik, an expert in network forensics and network security monitoring at NETRESEC.


PolarProxy is a transparent TLS proxy that outputs decrypted TLS traffic as PCAP files. PolarProxy doesn’t interfere with the tunnelled data in any way, it simply takes the incoming TLS stream, decrypts it, re-encrypts it and forwards it to the destination. Because of this PolarProxy can be used as a generic TLS decryption proxy for just about any protocol that uses TLS encryption, including HTTPS, HTTP/2, DoH, DoT, FTPS, SMTPS, IMAPS, POP3S and SIP-TLS.

PolarProxy is primarily designed for inspecting otherwise encrypted traffic from malware, such as botnets that use HTTPS for command-and-control of victim PCs. Other popular use cases for PolarProxy is to inspect encrypted traffic from IoT devices and other embedded products or to analyze otherwise encrypted traffic from mobile phones and tablets. The fact that PolarProxy exports the decrypted traffic in a decrypted format without any TLS headers also enables users to inspect the decrypted traffic with products that don’t support TLS decryption, such as intrusion detection and network forensics products like Suricata, Zeek and NetworkMiner.

PolarProxy creates a unique root CA certificate for each installation which must be trusted by clients that will have their TLS traffic decrypted. PolarProxy’s root CA must therefore be trusted by the operating systems, browsers and applications that you wish to decrypt TLS traffic from.

The Wireshark screenshot above shows DNS-over-HTTPS (DoH) traffic in the file proxy-191023-091924.pcap, which was captured live during my  TLS Interception and Decryption talk at the CS3Sthlm conference in 2019. As you can see, the DoH query is sent inside an HTTP/2 request. You might also notice that the HTTP/2 request is not encapsulated by a TLS record. This is because PolarProxy has removed all TLS data before saving the decrypted traffic to a capture file.PolarProxy decryption flow chart

PolarProxy is released under a CC BY-ND 4.0 license, which means you are free to use the software for any purpose, even commercially. To take PolarProxy for a test run, simply run the following commands on a Linux machine:

You will then have a PolarProxy service listening on TCP port 443 that will output decrypted packets to “/tmp/polarproxy.pcap“. To test the proxy, simply run the following curl command on any PC in your network:

Note: Replace 10.1.2.3 with the IP address of PolarProxy.

This command tells curl to behave as if weberblog.net resolved to PolarProxy’s IP, whereby the outgoing connection is sent via the TLS decryption proxy. The --insecure option is there because PolarProxy will generate a fake X.509 certificate for the domain in question (here: weberblog.net) on the fly and sign it with its own root CA certificate, which neither curl nor your operating system trusts by default. This root CA cert can be downloaded from an HTTP service listening on port 10080 on the PolarProxy machine. For instructions on how to configure a PC to trust this certificate, please see the “Trusting the PolarProxy root CA” section on the PolarProxy documentation.

It’s not possible to decrypt traffic from applications that use techniques like certificate transparency or public key pinning with PolarProxy though since they will not accept the X.509 certificate provided by PolarProxy even though it is signed by a trusted root.

PolarProxy is a transparent proxy, which means that, apart from trusting the root CA cert, no configuration is needed on the client in order to have the TLS traffic intercepted. Instead, you’ll need to deploy a firewall DNAT rule that redirects all outgoing TLS traffic to PolarProxy. For instructions on how to do this with iptables, please see the PolarProxy page. For other firewall solutions, however, you’ll need to figure out how to do this yourself.

If you wanna learn how to deploy PolarProxy as a container, then take a look at my other blog posts covering how to install PolarProxy in Docker and Podman. I have also written blog posts covering how to integrate PolarProxy with network security monitoring solutions like Arkime and Security Onion.

Photo by Hans-Jurgen Mager on Unsplash.

1 thought on “Decrypting TLS Traffic with PolarProxy

Leave a Reply

Your email address will not be published. Required fields are marked *