Experts in network security monitoring and network forensics NETRESEC > Products > PolarProxy

PolarProxy

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).

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 or 10 000 TLS sessions to be proxied per day. PolarProxy will still continue forwarding TLS traffic when this daily limit is reached, but it will not decrypt the TLS traffic. However, we do provide vetted security researchers and malware analysts, who do pro bono work, with free licenses that allow them to proxy as much data they need. So, 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.

Here is an example PCAP file generated by PolarProxy:
https://www.netresec.com/files/polarproxy-demo.pcap

Linux x64 or Linux ARM

PolarProxy can be run on most Linux versions. 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. For instructions on installing PolarProxy in 64-bit Linux, simply continue reading below.

Running PolarProxy as a regular user

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 to fire up 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 /usr/local/share/polarproxy.cer file as a trusted root certificate in the client PC's operating system and browser. This X.509 CA certificate can also be accessed from a web browser by visiting PolarProxy's web server on port 10080 (see the "--certhttp" command line switch). A PCAP file containing decrypted HTTPS traffic will be written to ~/polarproxy.pcap.

In order to use the firewall rules below, while runing 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 "-w -" switch. This enables real time traffic analysis with tcpdump, tshark, wireshark or whatever tool you fancy by reading from standard input. Here's how you pipe the decrypted traffic directly to Wireshark:

Installing PolarProxy as a systemd service in Linux

1. Create a system user for the PolarProxy daemon:
   Ubuntu:
   sudo adduser --system --shell /bin/bash proxyuser
   CentOS:
   sudo adduser --system --shell /bin/bash --create-home proxyuser
2. Create log directory for proxyuser:
   sudo mkdir /var/log/PolarProxy
   sudo chown proxyuser:root /var/log/PolarProxy/
   sudo chmod 0775 /var/log/PolarProxy/
3. Download and install PolarProxy:
   sudo su - proxyuser
   mkdir ~/PolarProxy
   cd ~/PolarProxy/
   curl https://www.netresec.com/?download=PolarProxy | tar -xzf -
   exit
4. Install the systemd script for PolarProxy:
   sudo cp /home/proxyuser/PolarProxy/PolarProxy.service /etc/systemd/system/PolarProxy.service
5. Enable and start PolarProxy service:
   sudo systemctl enable PolarProxy.service
   sudo systemctl start PolarProxy.service
6. Check the status of PolarProxy service:
   systemctl status PolarProxy.service
   journalctl -t PolarProxy

Routing HTTPS Traffic to the Proxy

If the default gateway 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.

Routing Option #1: PolarProxy installed on the gateway/firewall

Note: eth1 is the "inside" interface on the GW pointing towards the clients.

1. Add a inbound allow rule to allow traffic to tcp/10443 from the local network:
   sudo iptables -A INPUT -i eth1 -p tcp --dport 10443 -m state --state NEW -j ACCEPT
2. Add a nat rule to redirect 443 traffic to 10443:
   sudo iptables -t nat -A PREROUTING -i eth1 -p tcp --dport 443 -j REDIRECT --to 10443

Routing Option #2: PolarProxy installed on a separate machine

Note: eth1 is the "inside" interface on the GW pointing towards the clients.
PolarProxy server has ip address 10.11.12.13.

1. Add a forward rule on the gateway to allow forwarding traffic to our PolarProxy server:
   sudo iptables -A FORWARD -i eth1 -d 10.11.12.13 -p tcp --dport 10443 -m state --state NEW -j ACCEPT
2. Add a DNAT rule to forward 443 traffic to PolarProxy on port 10443:
   sudo iptables -t nat -A PREROUTING -i eth1 -p tcp --dport 443 -j DNAT --to 10.11.12.13:10443
3. Optional: if the reverse traffic from PolarProxy to the client doesn't pass the gateway, then we must add a hide-nat rule to fool PolarProxy that we are coming from the gateway:
   sudo iptables -t nat -A POSTROUTING -o eth1 -d 10.11.12.13 -p tcp --dport 10443 -j MASQUERADE

The "-m state" rules requires that you have a related or established rule configured. If you dont have that you can add it with:

If your gateway are using the conntrack module instead of state module then you can just change "-m state --state" to "-m conntrack --ctstate".

Routing Option #3: PolarProxy on the client PC

Note: This configuration will only proxy the traffic for the local user with uid 1000.

Save the Iptables Rules

Finally, don't forget to save your iptables rules!

Trusting the PolarProxy root CA

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. PolarProxy’s -x <file> command line switch can be used to export the root CA certificate to any location you desire. Then simply copy the certificate to all clients that you plan to proxy TLS traffic for. Another option is to use the --certhttp <port> switch, which will make the public root CA cert available on a web server running at the specified port. Simply start a browser on the client and enter the IP address of PolarProxy, such as http://10.11.12.13:10080/polarproxy.cer (if started with --certhttp 10080), to access the 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.

Windows

Install the certificate in GUI:

1. Double-click on "polarproxy.cer"
2. Click [Install Certificate...]
3. Select 🔘 Local Machine and press [Next]
4. Select 🔘 Place all certificates in the following store and press [Browse...]
5. Choose "Trusted Root Certification Authorities" and press [OK], then [Next]
6. Press [Finish]

Install the certificate without GUI:

1. Start cmd.exe as Administrator
2. certutil.exe -addstore Root C:\polarproxy.cer

Verify that it was successfully installed:

1. Run: certmgr
2. Open: Certificates - Local Computer > Trusted Root Certification Authorities > Certificates
3. Look for "PolarProxy Root CA" (unless you specified otherwise with the "-cn" switch)

Firefox

1. Open: http://10.11.12.13:10080/ (replace "10.11.12.13" with the IP of PolarProxy)

   
2. ☑ Trust this CA to identify websites. (check the box)
3. Press [OK]

OR

1. Options / Preferences
2. Press [Privacy & Security]
3. Scroll down to "Certificates" and press [View Certificates...]
4. In the "Authorities" tab, press [Import...]
5. Open "polarproxy.cer"
6. ☑ Trust this CA to identify websites. (check the box)
7. Press [OK]

Ubuntu

Replace "10.11.12.13" below with the IP of PolarProxy.

1. wget http://10.11.12.13:10080/polarproxy.cer
2. sudo mkdir /usr/share/ca-certificates/extra
3. sudo openssl x509 -inform DER -in polarproxy.cer -out /usr/share/ca-certificates/extra/PolarProxy-root-CA.crt
4. sudo dpkg-reconfigure ca-certificates
   
5. Select the "extra/PolarProxy-root-CA.crt" Certificate Authority
6. Press <Ok>

Android

Replace "10.11.12.13" below with the IP of PolarProxy.

1. Download the public certificate from http://10.11.12.13:10080/polarproxy.cer.
2. Settings > Security > (Encryption & credentials) > Install from SD card
3. Select "polarproxy.cer"
4. Select type "VPN and Apps"

Note: You will need to use a PIN code, password or similar to secure the Android device.

FAQ – Frequently Asked Questions

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: 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.

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) and SIP-TLS (5061). 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 “-p <listen-port>,<decrypted-port>” switch.

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 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?
PolarProxy will start writing to a new capture file every 60 minutes. However, the captured packets are not written to disk instantly because PolarProxy uses buffered file writing in order to improve performance. You can restart the proxy service if you wish to flush the buffered packets to disk and have PolarProxy rotate to a new capture file with: sudo systemctl restart PolarProxy

Q: Can I verify the integrity of my PolarProxy download somehow?
Yes, the SHA256 hash of the latest PolarProxy release is: 314445990581f98894ed84c84cd1d6f877d2c4968f0e54c408f377f5dcebcf48 (link)
The SHA256 hash of the latest PolarProxy linux-arm release is: c8e0d32bb51dfaf390074dc626f223b13f9bf219b9ffe4b9f5c3ad3700c2fa8a (link)

© 2010-2020 𝙽𝙴𝚃𝚁𝙴𝚂𝙴𝙲 𝙰𝙱 | Contact Us | Privacy | RSS