PolarProxy
PolarProxy is a transparent TLS and SSL inspection proxy created for incident responders, malware analysts and security researchers.
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:
https://media.netresec.com/pcap/polarproxy-demo.pcap
Download Links
Forward, Reverse, Termination or In-Line TLS Proxy
PolarProxy supports many different modes of operation, such as:
- Transparent Forward Proxy : PolarProxy connects to external TLS servers on behalf of clients on a network.
This mode is typically used in order to intercept and monitor otherwise encrypted HTTPS traffic from clients.
Instructions on how to forward decrypted traffic to an IDS can be found in our blog posts
“Sniffing Decrypted TLS Traffic with Security Onion”
and “Capturing Decrypted TLS Traffic with Arkime”.
The transparent proxy mode is ideal for intercepting malware traffic from a sandbox in order to either
decrypt and forward all outgoing TLS traffic to a local server or to only
redirect TLS traffic for specific domains to a local server, such as INetSim.
- Reverse Proxy : PolarProxy connects to one or several local TLS servers on behalf of external clients.
This mode is used in order to monitor the incoming TLS traffic as if it was unencrypted.
Use the --leafcert load option to import server certificates.
See our blog post “Reverse Proxy and TLS Termination” for more details.
- TLS Termination Proxy : PolarProxy terminates the TLS encryption for incoming connections and forwards the application layer traffic in decrypted form to a local server.
Use the --terminate option to terminate the TLS encryption for incoming connections.
See our blog post “Reverse Proxy and TLS Termination” for more details.
- Transparent In-Line Proxy : PolarProxy decrypts, re-encrypts and forwards all TLS connections to a specific proxy, security gateway or some other form of “Next-Generation Firewall”.
Use the --connect argument to specify which server to connect to.
- mTLS Proxy : PolarProxy performs mTLS handshakes with client certificates on behalf of the clients. This feature can be used to enable applications that lack support for mutual authentication to communicate with web applications or microservices without having to authenticate themselves.
Use the --clientcert option to enable the mTLS proxy mode.
- SOCKS Proxy : PolarProxy runs as a local SOCKS proxy server, which clients can use to access the Internet.
All TLS traffic passing through PolarProxy's SOCKS server will be decrypted and re-encrypted regardless of port.
Use the --socks option to activate the SOCKS proxy.
The SOCKS proxy can be used in combination with --nontls allow to also allow non-TLS traffic to pass through the proxy.
See our blog post “PolarProxy 0.9 Released” for more details.
- HAProxy : PolarProxy runs as a local HAProxy server, using the PROXY protocol v1 (send-proxy), to which a HAProxy load balancer can connect.
Use --haproxy 7654 to start a HAProxy listener on TCP port 7654.
The HAProxy mode can be used in combination with --nontls allow to also allow non-TLS traffic to pass through the proxy.
- HTTP CONNECT Proxy : PolarProxy runs as a local HTTP proxy server, which only supports the CONNECT request method.
TLS traffic passing through PolarProxy's HTTP CONNECT proxy will be decrypted and re-encrypted regardless of port.
Use the --httpconnect option to activate the HTTP CONNECT proxy.
See our blog post “PolarProxy 0.9 Released” for more details.
- TLS Firewall : PolarProxy with rule based logic for determining if a session should be allowed to pass through, get blocked or if the TLS encrypted data should be inspected (i.e. decrypted and re-encrypted) by the proxy.
See our TLS firewall page for more details.
PolarProxy is typically installed as a Transparent In-Line Proxy when acting as a TLS firewall,
but the firewall mode can be used in combination with any of the modes of operation above.
PolarProxy in a Container
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 in Windows Sandbox
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.
Linux x64 or Linux ARM
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.
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 download and start PolarProxy on TCP 443 on a Linux machine:
mkdir ~/PolarProxy
cd ~/PolarProxy/
curl https://www.netresec.com/?download=PolarProxy | tar -xzf -
sudo ./PolarProxy -v -p 443,80 -x /usr/local/share/polarproxy.cer --certhttp 10080 -w ../polarproxy.pcap
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 running PolarProxy on the command line,
you will need to bind the proxy to TCP port 10443 instead of 443:
./PolarProxy -v -p 10443,80,443 --certhttp 10080 -w ~/polarproxy.pcap
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:
./PolarProxy -p 10443,80,443 --certhttp 10080 -w - | wireshark -k -i -
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.
./PolarProxy -p 10443,80,443 --certhttp 10080 --pcapoverip 57012
The decrypted packets can then be read directly from TCP port 57012 with Wireshark or tshark like this:
wireshark -k -i TCP@127.0.0.1:57012
For more details on how to read the decrypted traffic from PolarProxy's PCAP-over-IP service, see our
Real-time PCAP-over-IP in Wireshark and
PolarProxy in Windows Sandbox blog posts.
Installing PolarProxy as a systemd service in Linux
- 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
- Create log directory for proxyuser:
sudo mkdir /var/log/PolarProxy
sudo chown proxyuser:root /var/log/PolarProxy/
sudo chmod 0775 /var/log/PolarProxy/
-
Download and install PolarProxy:
sudo su - proxyuser
mkdir ~/PolarProxy
cd ~/PolarProxy/
curl https://www.netresec.com/?download=PolarProxy | tar -xzf -
exit
-
Install the systemd script for PolarProxy:
sudo cp /home/proxyuser/PolarProxy/PolarProxy.service /etc/systemd/system/PolarProxy.service
-
Enable and start PolarProxy service:
sudo systemctl enable PolarProxy.service
sudo systemctl start PolarProxy.service
-
Check the status of PolarProxy service:
systemctl status PolarProxy.service
journalctl -t PolarProxy
-
Test run the proxy service with curl:
curl --insecure --connect-to www.netresec.com:443:127.0.0.1:10443 https://www.netresec.com/
If you have modified PolarProxy.service so that it listens to TCP port 443, or other port below 1024, then you also need to run this command to allow PolarProxy to bind to that port without root permissions:
sudo setcap CAP_NET_BIND_SERVICE=+eip /home/proxyuser/PolarProxy/PolarProxy
Routing HTTPS Traffic to the Proxy
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.
Routing Option #1: PolarProxy installed on the gateway/firewall
Note: eth1 is the "inside" interface on the GW pointing towards the clients.
-
Add an inbound allow rule to allow traffic to tcp/10443 from the local network:
sudo iptables -I INPUT -i eth1 -p tcp --dport 10443 -m state --state NEW -j ACCEPT
-
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 1:
The following firewall rules should be added to the router/firewall acting as the default gateway (GW),
not to the PolarProxy machine.
Note 2:
eth1 is the "inside" interface on the GW pointing towards the clients.
PolarProxy server has IP address 10.11.12.13.
-
Add a forward rule on the gateway to allow forwarding traffic to our PolarProxy server:
sudo iptables -I FORWARD -i eth1 -d 10.11.12.13 -p tcp --dport 10443 -m state --state NEW -j ACCEPT
-
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
-
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" rule requires that you have a related or established rule
configured. If you don't have that you can add it with:
sudo iptables -I INPUT 1 -m state --state RELATED,ESTABLISHED -j ACCEPT
sudo iptables -I FORWARD 1 -m state --state RELATED,ESTABLISHED -j ACCEPT
If your gateway is 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
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.
sudo iptables -I INPUT -p tcp --dport 10443 -j ACCEPT
sudo iptables -t nat -A OUTPUT -m owner --uid 1000 -p tcp --dport 443 -j REDIRECT --to 10443
Test and Save Firewall Rules
Test the firewall rule(s) with curl:
curl --insecure --resolve www.netresec.com:443:[PolarProxyIP] https://www.netresec.com/
Now is a good time 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:
- Double-click on "polarproxy.cer"
-
Click [Install Certificate...]
-
Select 🔘 Local Machine and click [Next]
-
Select 🔘 Place all certificates in the following store and click [Browse...]
-
Choose "Trusted Root Certification Authorities" and click [OK], then [Next]
-
Click [Finish]
Install the certificate from command line:
certutil.exe -addstore Root C:\polarproxy.cer
Install the certificate with PowerShell:
Import-Certificate -FilePath "C:\polarproxy.cer" -CertStoreLocation Cert:\LocalMachine\Root
Verify that it was successfully installed:
- Run: certlm.msc
- Open: Certificates - Local Computer > Trusted Root Certification Authorities > Certificates
- Look for "PolarProxy Root CA" (unless you specified otherwise with the "-cn" switch)
We also recommend disabling OCSP certificate revocation checks, which can be done as follows:
- Run: inetcpl.cpl
- Click the tab [Advanced] and scroll to "Security"
- Uncheck the "Check for server certificate revocation" and click [OK]
- Restart the computer or VM
The certificate revocation checks can also be disabled by running this command as Administrator:
reg add "HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings" /v "CertificateRevocation" /t REG_DWORD /d "0" /f
Group Policy (Active Directory)
A root CA certificate can be pushed to all clients in an Active Directory domain with a Group Policy Object (GPO).
-
Download polarproxy.cer from http://10.11.12.13:10080/ and save it on a file share
-
Start the Group Policy Management console and navigate to Group Policy Object
Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies
-
Right-click Trusted Root Certification Authorities and click [Import]
- Select polarproxy.cer from the file share (step 1.)
OCSP certificate revocation checks can also be disabled with a group policy.
-
Start the Group Policy Management console and navigate to Group Policy Object
User Configuration > Preferences > Windows Settings
- Right Click Registry and select New > Registry Item
- Navigate to the following registry entry:
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings\
- Set 'CertificateRevocation' DWORD to 0
Firefox
-
Download the root CA certificate from: http://10.11.12.13:10080/
(replace "10.11.12.13" with the IP of PolarProxy)
- Open: about:preferences#privacy
- Scroll down to "Certificates" and click [View Certificates...]
- In the "Authorities" tab, click [Import...]
- Open "polarproxy.cer"
-
☑ Trust this CA to identify websites. (check the box)
- Click [OK]
Google Chrome in Windows
-
Download the root CA certificate from: http://10.11.12.13:10080/
(replace "10.11.12.13" with the IP of PolarProxy)
- Settings > Advanced > Manage certificates
- Open the "Trusted Root Certification Authorities" and click [Import]
- Open "polarproxy.cer"
- Click [Next] and [Finish]
Ubuntu
Replace "10.11.12.13" below with the IP of PolarProxy.
- wget http://10.11.12.13:10080/polarproxy.cer
- sudo mkdir /usr/share/ca-certificates/extra
- sudo openssl x509 -inform DER -in polarproxy.cer -out /usr/share/ca-certificates/extra/PolarProxy-root-CA.crt
- sudo dpkg-reconfigure ca-certificates
- Select the "extra/PolarProxy-root-CA.crt" Certificate Authority
- Click <Ok>
Android
Replace "10.11.12.13" below with the IP of PolarProxy.
-
Download the public certificate from http://10.11.12.13:10080/polarproxy.cer
- Settings > Security > (Encryption & credentials) > Install from SD card
- Select "polarproxy.cer"
- Select type "VPN and Apps"
Note: You will need to use a PIN code, password or similar to secure the Android device.
On rooted Android devices we recommend moving the PolarProxy certificate from the User's trusted credentials to the System CA store,
because Android doesn't trust user certificates since Android version 7 SDK 23.
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
An alternative to manually copying the root CA cert to the system store is to use NVISO's Magisk Trust User Certs module, which makes installed user certificates part of the system certificate store.
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.
iOS
Replace "10.11.12.13" below with the IP of PolarProxy.
-
Open Safari and download the public certificate from http://10.11.12.13:10080/polarproxy.cer
- Settings (app) > General > About > Certificate Trust Settings
- Locate the PolarProxy certificate in "Enable full trust for root certificates" and enable it
Apple recommends deploying certificates via Apple Configurator or Mobile Device Management (MDM). Certificate payloads are automatically trusted for SSL when installed with Configurator, MDM, or as part of an MDM enrollment profile.
Java, Python, Node JS and Golang
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.
Accessing Decrypted Packets
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.
License Levels
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 a company, organization or individual to proxy up to
10 GB of data or 10 000 TLS sessions per day without a license.
PolarProxy will still continue forwarding TLS traffic when this daily limit is reached,
but it will not decrypt the TLS traffic.
If you need to proxy more than 10 GB of data, 10 000 TLS sessions
or perform over 10 000 TLS firewall ruleset queries per day, then please consider buying a commercial license for PolarProxy.
License |
Bytes per day |
Sessions per day |
Rule matches per day |
Price |
None |
10 GB |
10 000
|
10 000
|
Free |
Level 1 |
100 GB |
100 000
|
100 000
|
Contact Netresec |
Level 2 |
300 GB |
300 000
|
300 000
|
Contact Netresec |
Level 3 |
1 TB |
1 000 000 |
1 000 000 |
Contact Netresec |
Offline |
UNLIMITED |
UNLIMITED |
UNLIMITED |
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.
Command Line Arguments
Usage: PolarProxy [arguments]
Arguments:
--autoflush <seconds> Flush buffered packets and flow metadata to disk automatically every <seconds>.
Default value is 60. Set to 0 to disable auto-flush.
--bypass <file> Bypass decryption for domains that match any regex value in <file>.
--bypassexact <file> Bypass decryption for domains in <file> (exact string matching).
--bypassonfail NR:SEC Dynamically bypass decryption for client-domain pairs after recent decryption failures.
NR Number of failed client-domain connections required to bypass decryption.
SEC Time (in seconds) until failed connections are forgotten.
--cacert <action> Configure root CA certificate, where <action> can be:
cn:"<name>" Set CA Certificate Subject Name CN value to <name>.
load:FILE:PASSWORD Load pre-generated root CA certificate from disk.
FILE Path to PKCS12 root CA certificate.
PASSWORD Password for PKCS12 certificate.
--certhttp <port> Start HTTP server listening on <port> that hosts the public X.509 root CA cert.
--clientcert DOMAINS:FILE:PWD Use client certificate in outgoing mTLS connections.
DOMAINS Comma-separated list of domains the client cert should be used against.
FILE Path to PKCS12 client certificate.
PWD Password for PKCS12 certificate.
--connect <host> Connect all external sessions to <host>, for example to another transparent proxy.
-d Print debug info to STDERR. Also enables -v
-f <file> Log flow metadata for proxied sessions to <file>. Logged columns are:
timestamp, internal_5-tuple, external_5-tuple, domain_name, external_cert_hash, decrypted_5-tuple, ja3_hash
-h, --help Print this help and exit.
--helphtml Print HTML formatted help and exit.
--haproxy [IP:]PORT Run local HAProxy PROXY protocol v1 server (send-proxy).
IP IPv4 or IPv6 address to bind HAProxy PROXY protocol service to. Default is 0.0.0.0.
PORT TCP port to listen for incoming HAProxy PROXY protocol requests on.
--httpconnect [IP:]PORT Run local HTTP CONNECT proxy server (RFC 7231, section 4.3.6).
IP IPv4 or IPv6 address to bind HTTP CONNECT service to. Default is 0.0.0.0.
PORT TCP port to listen for incoming HTTP CONNECT requests on.
--key <license> Use license key <license> to proxy more data/sessions.
--leafcert <config> Generate server leaf certs with <config>, where <config> can be:
clone Clone original server certificates. (default)
cloneserials Clone original server certificates and serial numbers. See RFC 5280 4.1.2.2.
load:DOMAINS:FILE:PWD Load server cert from disk.
DOMAINS Comma-separated list of domains the server cert should be used for.
FILE Path to PKCS12 server certificate / leaf certificate.
PWD Password for PKCS12 certificate.
noclone Generate new certificates with CN=SNI instead of cloning original certs.
sign Always sign generated certs with PP's root CA, even when original server cert isn't trusted.
--mss <size> Use TCP Maximum Segment Size <size> in PCAP. Default is 1420.
--nontls <action> Perform <action> on incoming sessions that don't use TLS, where <action> can be:
block (default)
allow Allow connection to pass through. Only works when target host is known, such as for --socks and --haproxy.
forward:HOST:PORT Forward session to HOST:PORT, for example a proxy server.
encrypt:HOST:PORT Encrypt session data in TLS connection to HOST:PORT.
--nosni <host> Set target to <host> if client TLS handshake doesn't specify SNI. Default action is to close the session.
-o <directory> Set output directory for hourly rotated PCAP files.
--pcapoverip [IP:]PORT Serve decrypted TLS data as PCAP-over-IP.
IP IPv4 or IPv6 address to bind PCAP-over-IP listener to. Default is 127.0.0.1.
PORT TCP port to bind PCAP-over-IP listener to.
--pcapoveripconnect HOST:PORT Connect to remote PCAP-over-IP listener.
HOST Remote hostname, IPv4 or IPv6 address to send a PCAP-over-IP stream to.
PORT Remote TCP port to send PCAP-over-IP stream to.
-p [LISTEN-IP,]LISTEN-PORT,DECRYPTED-PORT[,EXTERNAL-PORT] Run local transparent proxy.
LISTEN-IP IPv4 or IPv6 address to bind proxy to.
LISTEN-PORT TCP port to bind proxy to.
DECRYPTED-PORT TCP server port to use for decrypted traffic in PCAP.
EXTERNAL-PORT TCP port for proxy to connect to. Default value is same as LISTEN-PORT.
--redirect HOSTS:TARGET Redirect TLS connections for HOSTS to TARGET, with SNI set to TARGET. Can be used multiple times.
HOSTS Comma separated list of server hosts to redirect traffic from.
TARGET Target domain to redirect traffic to.
--ruleset FILE Load ruleset from FILE with match conditions and proxy actions (block/bypass/encrypt/inspect/terminate).
FILE Path or URL to json ruleset.
--socks [IP:]PORT Run local SOCKS proxy server.
IP IPv4 or IPv6 address to bind SOCKS service to. Default is 0.0.0.0.
PORT TCP port to listen for incoming SOCKS4 or SOCKS5 requests on.
-v Verbose output to STDERR.
-w <file> Write PCAP to a single file, without rotation or ringbuffer.
Standard output is used if <file> is '-'.
--writeall Write all packets, including encrypted sessions, to the output PCAP file/stream.
--terminate Run as TLS termination proxy that forwards decrypted data to the target host.
--timeout <seconds> Maximum time in seconds that PolarProxy will attempt to establish a TCP connection. Default is 5.
-x <file> Export DER encoded public CA certificate to <file>.
Example commands:
PolarProxy -p 443,80 -o /var/log/pcap/ -f /var/log/proxyflows.log -x polarproxy.cer
PolarProxy -p 0.0.0.0,10443,80,443 --cacert cn:"ACME Corp Transparent Proxy CA" -o /var/log/
PolarProxy -p 443,80 -p 995,110 -p 993,143 -p 465,25 -o ~/.local/share/ -v
PolarProxy -p 10443,80,443 --pcapoverip 57012
PolarProxy -p 10443,80,443 --pcapoveripconnect 127.0.0.1:57012
PolarProxy -p 10443,80,3129 --connect 10.0.2.25 --leafcert sign -w decrypted.pcap
PolarProxy -p 10443,80,80 --connect 10.0.1.2 --terminate --nosni nosni.example.com
PolarProxy -p 443,80,80 --terminate --connect 10.0.1.2 --leafcert load:example.com,www.example.com:cert.p12:pwd
PolarProxy -p 10443,80,443 --clientcert api.example.com:client.p12:pwd -w api_decrypted.pcap
PolarProxy --httpconnect 8080 -p 443,80 --pcapoverip 57012
PolarProxy --socks 1080 --redirect youtube.com,www.youtube.com,youtu.be:google.com --leafcert noclone
PolarProxy --socks 1080 --nontls allow
PolarProxy --haproxy 7654 --nontls allow
PolarProxy -p 10443,80,443 --ruleset ruleset-block-malicious.json
PolarProxy -p 10443,80,443 --ruleset ruleset-inspect-interesting.json
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:
./PolarProxy -p 10443,80,443
Q: Does PolarProxy use a static built-in private certificate for 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: Does PolarProxy support TLS 1.3?
Yes, PolarProxy supports TLS 1.2 as well as TLS 1.3.
Q: Does PolarProxy support encrypted SNI (ESNI)?
No.
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 --cacert load command line switch to load the certificate (use --help for more details).
Q: Can PolarProxy use a client cert to authenticate to the server, for example in order to perform mutual TLS authentication (mTLS) between an IoT device and a cloud service?
If you have access to the client cert, including private keys, then yes you can! Use PolarProxy's --clientcert argument to specify a client certificate to be used for outgoing connections.
Q: I have the client's certificate and private key and want to proxy the mTLS traffic with PolarProxy's --clientcert feature. How do I convert them from PEM to PKCS12 format?
openssl pkcs12 -export -out cert.p12 -in cert.pem -inkey key.pem
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, run PolarProxy as a TLS firewall with the domain_in_file match type and bypass action.
Another option is to 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 decrypts TLS and SSL traffic regardless of which protocol is inside.
PolarProxy thereby enables decryption of protocols such as HTTPS (TCP 443) — containing HTTP/1, HTTP/2 or WebSockets —, DNS-over-TLS (853), FTPS (990), SMTPS (465), IMAPS (993), POP3S (995), SIP-TLS (5061) and MQTTS (8883).
After decrypting the traffic from these TLS wrapped protocols PolarProxy saves the clear text traffic to a PCAP file.
Q: Can PolarProxy be used to capture traffic from non-TLS protocols like HTTP, SSH or FTP?
No, not in general. PolarProxy is designed primarily to intercept protocols that use TLS.
Even though the options --nontls forward and --writeall can be used to capture traffic from some non-TLS protocols, our recommendation is to instead capture such traffic with a traditional sniffer (like tcpdump, dumpcap or netsniff-ng).
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.
However, the TLS firewall mode can be used to block or inspect potentially malicious traffic while letting legitimate traffic pass through.
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: 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?
Yes, provided that you give appropriate credit (see CC BY-ND 4.0).
As an example, PolarProxy is included in the Linux distribution REMnux.
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 --autoflush switch to configure PolarProxy to flush the cached packets to disk more often.
Another option is to restart the proxy service, to flush the buffered packets to disk and have PolarProxy rotate to a new capture file, with:
sudo systemctl restart PolarProxy
Q: Can PolarProxy decrypt or inspect traffic that is using StartTLS or explicit TLS?
No, PolarProxy doesn't support decryption of oportunistic TLS (STARTTLS) in protocols like SMTP and IMAP or explicit TLS (AUTH TLS) in FTPS.
Q: Is PolarProxy FIPS compliant?
No, PolarProxy uses cryptographic algorithms that are not FIPS 140-compliant. If run on a FIPS enabled computer PolarProxy will display an error message, such as
Unhandled exception. Interop+Crypto+OpenSslCryptographicException: error:03000086:digital envelope routines::initialization error
Q: When I connect to PolarProxy from Windows I get this error message:
(35) schannel: next InitializeSecurityContext failed: Unknown error (0x80092013) - The revocation function was unable to check revocation because the revocation server was offline.
I have already added trust to PolarProxy's root CA and disabled OCSP certificate revocation checks.
Curl's Schannel library doesn't honor Windows' OCSP setting and alerts that the revocation check failed. Use the --ssl-no-revoke or --ssl-revoke-best-effort switch in curl to prevent OCSP revocation errors.
Q: Can I verify the integrity of my PolarProxy download somehow?
Yes, the SHA256 hash of the latest PolarProxy Linux x64 release is:
25644b4104bca7f1a330ea26d9f55985cd56bedef6d08dfc3dc0d147c03298c5 (link)
🐻❄️ ʕ•ᴥ•ʔ