PolarProxy 1.0.1 Released

The new release of PolarProxy generates JA4 fingerprints and enables ruleset to match on specific decryption errors, for example to enable fail-open in case the TLS traffic cannot be decrypted and inspected.

JA4 Fingerprints

JA4 fingerprints provide several improvements over its JA3 predecessor. One advantage is that JA4 fingerprints have a human readable segment that allow humans (as well as computers) to instantly see important features in a client handshake, such as the TLS version and whether or not the SNI and ALPN extensions are used. JA4 is also resilient against TLS extension order randomization.

We added support for rule based matching of JA4 fingerprints in the previous release of PolarProxy. Such a JA4 rule can be used to have PolarProxy take different actions (block, intercept, bypass etc.) based on the JA4 fingerprint of the client’s TLS handshake.

This release additionally includes JA4 fingerprints in the flow metadata that PolarProxy writes to disk when the -f <file> argument is provided.

Flexible Handling of TLS Auth Failures

PolarProxy’s firewall rules now support using TLS authentication error codes as triggers. As an example, the ruleset fail-open.json attempts to inspect (decrypt and re-encrypt) all TLS traffic, except when the client has rejected the server’s certificate at least once during the past 60 seconds. More specifically, it only bypasses decryption if the reason for the rejection was either “bad certificate” or “unknown CA”.

The specific error codes (here 0x0A000412 for “bad certificate” and 0x0A000418 for “unknown CA”) might differ between deployments, since they depend on the underlying TLS library of the PolarProxy machine. The specific values in this example are from a Linux deployment with OpenSSL 3.0.13 installed. Look for the “decrypt_fail_errorcode” messages that PolarProxy prints to stderr to find out what error codes your system is using. You can also run PolarProxy with -v (verbose) or -d (debug) to get even more information about the error codes.

Ruleset Reload on SIGHUP

A PolarProxy ruleset can now be updated on the fly without having to restart PolarProxy. Simply send a SIGHUP signal to PolarProxy, for example pkill -HUP PolarProxy, to have it reload the updated ruleset without affecting sessions that PolarProxy is currently proxying.

If PolarProxy is running as a systemd service, then adding

ExecReload=/bin/kill -HUP $MAINPID

.NET 8

The .NET version has been bumped from 6 to 8 in the 1.0.1 release, which provides better performance as well as long-term support. We've also bumped the System.Security.Cryptography.Xml library from version 4.5 to 9.0.

Posted by Erik Hjelmvik on Friday, 07 February 2025 10:10:00 (UTC/GMT)

Tags: #PolarProxy​ #JA4​ #fail-open​

TLS Redirection and Dynamic Decryption Bypass in PolarProxy

PolarProxy is constantly being updated with new features, enhanced performance and bug fixes, but these updates are not always communicated other than as a short mention in the ChangeLog. I would therefore like to highlight a few recent additions to PolarProxy in this blog post.

Custom TLS Redirection

One new feature in PolarProxy is the --redirect argument, which can be used to redirect TLS traffic destined for a specific domain name to a different domain. This feature can be used to redirect TLS-encrypted malware traffic going to a known C2 domain to a local HTTPS sandbox instead, for example INetSim.

This --redirect argument will cause PolarProxy to terminate outgoing TLS traffic to malware-c2.com and redirect the decrypted traffic into a new TLS session going to inetsim.local instead. The “--leafcert noclone” argument forces PolarProxy to generate a fake X.509 certificate for “malware-c2.com” rather than sending a clone of the certificate received from the INetSim server to the malware implant.

Note: You also need to specify a proxy mode, such as -p for transparent proxy or --socks for SOCKS proxy, to make the command above work.

The --redirect argument can also be used to perform domain fronting, which is a clever method for hiding the true destination of HTTPS based communication, in order to circumvent censorship or for other reasons conceal who you’re communicating with. The following command can be used to set up a local socks proxy that redirects traffic destined for YouTube to google.com instead:

A browser configured to use PolarProxy as a SOCKS proxy will send HTTPS requests for youtube.com to PolarProxy, which then decrypts the TLS layer and re-encrypts the HTTP communication in a new TLS session directed at google.com instead. Someone who monitors the outgoing traffic from PolarProxy will assume that this is normal Google traffic, since the SNI as well as certificate will be for google.com. On the server side however, after having decrypted the TLS layer, Google will kindly forward the client’s original HTTP request for youtube.com to an endpoint that serves the content for YouTube.

Dynamic TLS Decryption Bypass

PolarProxy is designed to block TLS connections that it can’t decrypt, except for when the server’s domain name is explicitly marked for decryption bypass with the “--bypass” command line argument. However, as of recently PolarProxy also supports dynamic TLS decryption bypass using a form of fail-open mode. When this fail-open mode is enabled, PolarProxy attempts to intercept and decrypt proxied TLS traffic, but allows connections to bypass decryption if the same client-server pair has previously rejected PolarProxy’s certificate. This method is convenient when monitoring network traffic from applications that enforce certificate pinning or for some other reason can’t be configured to trust PolarProxy’s root CA – provided that it’s acceptable to let traffic that can’t be decrypted to pass through untouched rather than blocking it, of course.

The following command line option configures PolarProxy to allow new TLS connections to bypass decryption for one hour (3600 seconds) after previously having failed to decrypt traffic between the same client and server.

A simple way to verify this fail-open feature is to do a simple test with curl. It doesn’t matter if the client you’re testing on is Windows, Linux or macOS, since PolarProxy as well as curl is available for all three platforms.

Web browsers that don’t trust PolarProxy’s root CA will display a certificate warning the first time they visit a website that PolarProxy tries to decrypt traffic for.

But once the dynamic bypass has kicked in the user will no longer see a certificate warning when visiting the same website again, since traffic between that client and server is now end-to-end encrypted.

Handling of non-TLS traffic and Better Logging

Other new features in PolarProxy is the “--nontls” argument, which can be used to specify how to handle connections that doesn’t use TLS. The default action is to block non-TLS connections, but they can also be allowed to pass through (if the target host is known) or to forward the connection to a specific host and port. There is even a “--nontls encrypt” argument, which can be used to encrypt traffic that isn’t already TLS-encrypted before forwarding it to a specific host. This feature can be used as an alternative to stunnel to wrap traffic from applications that lack TLS support inside a TLS tunnel.

PolarProxy now also produces less output to stdout, unless -v is used, and error messages have been improved to be more specific and easier to understand.

Posted by Erik Hjelmvik on Tuesday, 28 February 2023 13:42:00 (UTC/GMT)

Tags: #PolarProxy​ #TLS​ #redirect​ #bypass​ #fail-open​ #SNI​ #ASCII-art​