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 are to inspect encrypted traffic from IoT devices and other embedded products or to analyse 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 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:
mkdir ~/PolarProxy cd ~/PolarProxy/ curl https://www.netresec.com/?download=PolarProxy | tar -xzf - sudo ./PolarProxy -v -p 443,80 --certhttp 10080 -w /tmp/polarproxy.pcap
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:
curl --insecure --resolve www.netresec.com:443:10.1.2.3 https://www.netresec.com/
Note: Replace 10.1.2.3 with the IP address of PolarProxy.
This command tells curl to behave as if netresec.com 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, 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 want to 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.
Erik Hjelmvik is a developer, incident responder, and teacher. He created NetworkMiner, and runs Netresec AB, where he develops network forensics software and occasionally teaches network forensic classes.
This post was originally published at Weberblog.
The views expressed by the authors of this blog are their own and do not necessarily reflect the views of APNIC. Please note a Code of Conduct applies to this blog.
Hello Eric
I don’t understand how the system works. This command…
curl –insecure –resolve http://www.netresec.com:443:10.1.2.3 https://www.netresec.com/
This will make curl connect to 10.1.2.3:443 instead of http://www.netresec.com:443. Once the TCP and TLS handshakes are complete between curl and PolarProxy, all the PolarProxy will see is the bare HTTP GET request, like
GET /
So, as you can see, the original IP address of http://www.netresec.com is lost! So how does PolarProxy know where to send this GET request?
Unless, Polar is using TLS SNI field, or HTTP HOST field to dig out the original destination. But these fields are not mandatory. And HOST field is used only in HTTP protocol, which is just one of the many protocols tunneled by TLS. So how does the whole thing work? Can you please throw some light on this.
Hello Flying Horse,
PolarProxy relies on the TLS SNI field to know where the client wish to connect. The vast majority of all legitimate TLS traffic on the internet uses SNI. TLS traffic without SNI can be handled separately using a rule like this:
“match”: { “type”: “domain”, “expression”: null },
“action”: {“type”: “bypass”, “target”: “www.netresec.com”}
You can find more information about PolarProxy’s ruleset format here:
rule as described here:
https://tlsfirewall.com