PolarProxy is a transparent SSL/TLS proxy created for incident responders and malware researchers. PolarProxy is primarily designed to intercept and decrypt TLS encrypted traffic from malware. PolarProxy decrypts and re-encrypts TLS traffic, while also saving the decrypted traffic in a PCAP file that can be loaded into Wireshark or an intrusion detection system (IDS).
Here is an example PCAP file generated by PolarProxy:
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.
There is one limitation though, the tool only allows up to 10 GB of data
If you need to proxy more than 10 GB of data
|License||Bytes per day||Sessions per day||Price|
|Level 1||100 GB||
|Level 2||300 GB||
|Level 3||1 TB||1 000 000||Contact Netresec|
The offline license does not require an online connection to the PolarProxy license server, but L1-L3 licenses do.
Free Licenses for Pro-Bono Work
We can provide vetted security researchers and malware analysts, who do pro bono work, with free L1-L3 licenses. If you are a security researcher or organization performing research or analysis of malware for the public good, then please contact us to go through our vetting procedure and get your own free license. We particularly favor projects that run malware in sandboxes and share PCAP files from the malware executions for free, either openly or within vetted security communities.
PolarProxy supports many different modes of operation, such as:
PolarProxy can be run in a container using OS-level virtualization. Our blog post "PolarProxy in Docker" describes how to deploy PolarProxy in Docker. If you prefer Podman, then check out the "PolarProxy in Podman" blog post instead.
PolarProxy can be run in Windows Sandbox (available in Windows 10/11 Pro and Enterprise editions) to decrypt and inspect TLS traffic locally in an isolated environment. A Windows Sandbox WSB file, which boots up a fresh install of Windows 10 or 11 with the latest version of PolarProxy extracted to the desktop, can be downloaded from here:
Windows' built-in proxy settings aren't available in Windows Sandbox though, so you'll have to install a third party proxy client, such as Proxifier, in order to redirect all outgoing traffic to PolarProxy's SOCKS proxy server.
Check out our blog post "PolarProxy in Windows Sandbox" for more detailed instructions on how PolarProxy can be used to intercept and decrypt TLS traffic in Windows Sandbox.
See our blog post "Raspberry Pi WiFi Access Point with TLS Inspection" for instructions on how to install PolarProxy on a Linux ARM computer, such as a Raspberry Pi. We also have a blog posts that cover how to install PolarProxy in Security Onion and Arkime. There's also a very detailed writeup by Nils Hanke on how to setup a honeypot with IDS, ELK and TLS traffic inspection, which covers how to forward decrypted TLS traffic from PolarProxy to Suricata. For instructions on how to install PolarProxy on a generic 64-bit Linux machine, simply continue reading below.
PolarProxy can be run as a systemd service, but you can also run it as a regular command line application if you just wanna proxy a few sessions or take PolarProxy for a test ride. Follow these instructions in order download and start PolarProxy on TCP 443 on a Linux machine:
To run some traffic through PolarProxy, simply edit the hosts file of any client PC on your network so that some domain name(s) point to your proxy.
You will also need to install the generated
In order to use the firewall rules below, while running PolarProxy on the command line, you will need to bind the proxy to TCP port 10443 instead of 443:
Another cool option is to write the PCAP data to standard output using the "
Another way to read the decrypted packets in-real time is to stream them directly from a TCP socket with help of PolarProxy's PCAP-over-IP feature.
The decrypted packets can then be read directly from TCP port 57012 with Wireshark or tshark like this:
If the default gateway (GW) out from the intercepted network is a Linux router or firewall that you manage, then we recommend installing PolarProxy directly on the gateway. If not, then you will need to install PolarProxy on a separate machine.
Note: eth1 is the "inside" interface on the GW pointing towards the clients.
Note 1: The following firewall rules should be added to the router/firewall acting as the default gateway (GW), not to the PolarProxy machine.
eth1 is the "inside" interface on the GW pointing towards the clients.
PolarProxy server has IP address 10.11.12.13.
The "-m state" rules requires that you have a related or established rule configured. If you don't have that you can add it with:
If your gateway is using the conntrack module instead of state module then you can just change "-m state --state" to "-m conntrack --ctstate".
This configuration will only proxy the traffic for the local user with uid 1000. Make sure PolarProxy runs under a different uid, it will otherwise end up connecting to itself in an endless loop. One way to get around this issue is to start PolarProxy with "sudo" to ensure it runs as uid 0 (root). Another option is to create a special user just for running PolarProxy, as explained in "Installing PolarProxy as a systemd service in Linux" above.
Test the firewall rule(s) with curl:
Now is a good time to save your iptables rules!
The root CA certificate used by PolarProxy must be trusted by all clients that will have their TLS traffic routed through the proxy. Your PolarProxy root CA must be trusted by both the operating system and any browsers or applications that have their own list of trusted root certificates in order to get a seamless integration of the proxy.
There are two ways you can export your PolarProxy’s root CA as a DER encoded X.509 certificate.
How and where to install the public root CA certificate varies between operating systems and applications. A few common examples are listed here below.
Install the certificate in GUI:
Install the certificate from command line:
Install the certificate with PowerShell:
Verify that it was successfully installed:
We also recommend disabling OCSP certificate revocation checks by running this command as Administrator:
A root CA certificate can be pushed to all clients in an Active Directory domain with a Group Policy Object (GPO).
OCSP certificate revocation checks can also be disabled with a group policy.
Replace "10.11.12.13" below with the IP of PolarProxy.
Replace "10.11.12.13" below with the IP of PolarProxy.
On rooted Android devices we recommend moving the PolarProxy certificate from the User's trusted credentials to the System CA store, because many apps don't accept CA certificates trusted by the User. CA certs trusted by the user are typically located in "/data/misc/user/0/cacerts-added" and system CA certs are in "/system/etc/security/cacerts". A reboot is required after moving the certificate for the change to take place.
Image: PolarProxy root CA certificate installed in "Trusted credentials" for SYSTEM
Hint 1: If you want to redirect TLS traffic from an Android device to PolarProxy with adb, then check out Niklas Barsk's Sniffing TLS traffic on Android blog post.
Hint 2: Certificate pinning can often be circumvented by following Miguel Frade's Android Network Traffic Interception tutorial, which uses Maurizio Siddu's frida-multiple-unpinning script. Another option is Piergiovanni Cipolloni's Universal Android SSL Pinning Bypass frida script.
Ronnie Flathers has posted a great writeup titled "Proxying and Intercepting CLI Tools" where he covers how to install Burp certificates into keystores for Java, Python, Node JS and Golang. You can install PolarProxy's root CA certificate using the same methods as Ronnie describes in his blog post.
The decrypted TLS traffic can be accessed in the PCAP files created by PolarProxy. The location of the decrypted PCAP files is controlled by the "-w <file>" and "-o <directory>" command line arguments.
A real-time live stream of decrypted packets can also be accessed from PolarProxy if the "--pcapoverip <port>" argument is used, this PCAP stream can be accessed directly from Wireshark as well as from NetworkMiner. Another way to get access to this real-time PCAP stream is to use PolarProxy's "--pcapoveripconnect <host>:<port>" feature, as explained in our Capturing Decrypted TLS Traffic with Arkime blog post.
Q: Can PolarProxy be configured to listen to a high port (≥1024), so that I won’t need root permissions to run the proxy?
Yes, Polar Proxy can be configured to listen to a high port but still use a well-known low port for the outgoing TCP session. The following “-p” argument will have PolarProxy listen on TCP 10443, save the decrypted traffic as TCP 80 in the generated PCAP files and use TCP 443 for the outgoing connections to the real web servers:
Q: Does PolarProxy use a static built-in private certificate for the SSL interception?
No, PolarProxy dynamically creates a new and unique private certificate when it is first run on a machine. The purpose for doing so is to protect against man-in-the-middle attacks performed by others with access to the private certificate from some other PolarProxy instance.
Q: Can we have PolarProxy use our own private CA certificate instead of the dynamically generated one?
Yes. If you have a PKCS12 file with your private CA certificate, then simply use the “-c” command line switch to load the certificate (use “--help” for more details).
Q: Can I configure my browser to connect to PolarProxy using the browser's proxy settings?
Yes, PolarProxy can be used as a SOCKS or HTTP CONNECT proxy. See our blog post PolarProxy 0.9 Released for more details.
Q: Why do I get an error when I try to import PolarProxy's CA certificate (polarproxy.cer) as a PEM file?
The public CA certificate exported by PolarProxy (with -x or --certhttp) is using the DER encoding.
You can convert it to a PEM file with openssl:
openssl x509 -inform DER -in polarproxy.cer -out polarproxy-pem.crt
Q: Can I supply a list of whitelisted domains for which the TLS decryption should be bypassed?
Yes, use the “--bypass <file>” command line argument to point PolarProxy to a file containing one or multiple regular expressions (one per line). The TLS decryption will be bypassed for domains that are matched by any of the regular expressions in the supplied whitelist file. If you're intercepting Chrome devices, then use this bypass/allow list in order to avoid errors.
Q: I'm getting a Security Alert window saying "Revocation information for the security certificate for this site is not available. Do you want to proceed?". How do I disable OCSP certificate revocation checks in Windows?
Run "inetcpl.cpl" or open Control Panel > Internet Options, click the "Advanced" tab, scroll down to "Security" and uncheck the "Check for server certificate revocation" box. You should not see these alerts any more after rebooting.
Q: Which protocols (and ports) can be decrypted by PolarProxy?
PolarProxy only decrypts TLS and SSL traffic. However, many application layer protocols use TLS for encryption, such as HTTPS (TCP 443), DNS-over-TLS (853), FTPS (990), SMTPS (465), IMAPS (993), POP3S (995), SIP-TLS (5061) and MQTTS (8883). These TLS wrapped protocols can be decrypted using PolarProxy, so that you can analyze them in their clear text format.
Q: Can PolarProxy alert on malicious activity?
No, PolarProxy only decrypts the SSL/TLS encrypted traffic and saves it in a capture file (a.k.a. PCAP file). Read the PCAP file with an IDS of your choice, like Snort, Suricata or Zeek in order to generate alerts for malicious traffic.
Q: How is PolarProxy different from mitmproxy / Burp Suite / Fiddler / Charles Proxy / Bettercap?
Unlike many other proxies, PolarProxy is not designed to interfere with the data inside the encrypted stream. PolarProxy only decrypts the TLS stream for inspection and then re-encrypts the exact same stream again. Another unique feature of PolarProxy is that it writes the decrypted data to a PCAP file containing the decrypted data, this PCAP file can be loaded into Wireshark, NetworkMiner or an IDS tool for inspection.
Q: What about TLS wrapped protocols other than HTTPS?
You can run any TLS wrapped protocol through PolarProxy to see the decrypted contents.
It doesn’t matter if it is a proprietary protocol running inside the TLS session
or if it is a well-known TLS wrapped protocol like HTTP/2, SMTPS, IMAPS or POP3S.
They are all decrypted by PolarProxy, as long as you have configured it to listen on the desired port using the
Q: How about badssl.com?
PolarProxy is designed to forward all properties of the external TLS session to the internal one as far as possible. This means that visiting, for example https://expired.badssl.com, will yield an expired certificate also on the inside. The same thing goes for most other badssl tests, like self signed certs, certs with wrong hostname etc.
Q: Is PolarProxy free? Can I use this software commercially?
Yes, and yes. PolarProxy is released under a Creative Commons Attribution-NoDerivatives 4.0 International License, which means that you can copy and redistribute PolarProxy in any medium or format for any purpose, even commercially.
Q: Can I include PolarProxy in another product?
Q: Can PolarProxy decrypt HTTPS traffic from a network tap or pcap file if I have a key log file or private RSA key?
No. PolarProxy will need to communicate with both the client and server in order to decrypt the traffic. Please use Wireshark in order to do passive decryption with SSLKEYLOGFILE.
Q: I'm running PolarProxy as a service and have successfully used it to proxy an HTTPS session. Why don't I get any packets in the PCAP file?
The packets captured by PolarProxy are not written to disk instantly because PolarProxy uses buffered file writing in order to improve performance.
You can use the
Q: Can I verify the integrity of my PolarProxy download somehow?
Yes, the SHA256 hash of the latest PolarProxy linux-x64 release is:
The SHA256 hash of the latest PolarProxy linux-arm release is:
The SHA256 hash of the latest PolarProxy linux-arm64 release is: