PolarProxy 2.0 Released

A new major release of PolarProxy is out with a self-contained single-file binary, expanded platform support (musl/ARM), and improved container and service plumbing.

PolarProxy is a transparent TLS/SSL inspection proxy built for incident responders, malware analysts and security researchers. It decrypts and re‑encrypts TLS traffic and writes decrypted sessions to PCAP for analysis in Wireshark or an IDS.

What's new

• Packaged as a self-contained, single-file binary for easier installation and management.
• Improved HTTP proxy server: support for unencrypted HTTP traffic with --nontls allow
• Upgraded runtime: migrated from .NET 8 to .NET 10.
• More supported platforms: Linux musl (Alpine) builds for ARM and ARM64 architectures added.
• Simplified container deployment: Dockerfile and docker-compose.yml included with all musl/Alpine releases.
• Service installer for Linux: systemd unit (polarproxy.service) and install script included in non-musl Linux releases.
• New runtime flags:
  • --tlstimeout <seconds> — sets a TLS handshake/authentication timeout.
  • --cutoff <bytes> — limits PCAP output to the specified number of bytes per flow.

Why this release matters

• Self-contained single binary simplifies deployment and maintenance. This is a breaking change, at least for container/pod deployments, so make sure to validate your deployment before rolling out the new 2.0 release to production.
• The .NET 10 upgrade brings improved runtime performance and security updates.
• Better container support with musl/Alpine build for ARM and ARM64 in addition to existing x64 builds, and simplified container deployments with included config files.
• The new timeout for TLS handshakes improves error handling of connections to broken TLS middleboxes and extremely slow web servers.
• The flow cutoff CLI option enables users to prevent large downloads from filling up disk volumes. This setting also limits the per-flow size of decrypted traffic that is made available through PCAP-over-IP.

Quick start for Linux (regular user)

1. Download the appropriate tar archive for your platform (see download links).
   
2. Create directory:
   
   mkdir ~/PolarProxy
3. Change directory:
   
   cd ~/PolarProxy/
4. Extract the archive:
   
   tar -xzf ~/Downloads/PolarProxy_2.0.0_linux-x64.tar.gz
5. Create log directory:
   
   sudo mkdir -p /var/log/polarproxy
6. Change log dir owner:
   
   sudo chown "$USER" /var/log/polarproxy
7. Start PolarProxy:
   
   ./PolarProxy -p 10443,80,443 --socks 1080 --httpconnect 8080 --nontls allow --certhttp 10080 -x /var/log/polarproxy/polarproxy.cer -f /var/log/polarproxy/proxyflows.log --pcapoverip 0.0.0.0:57012 -o /var/log/polarproxy/ -v

Quick start for Linux with systemd

1. Download the appropriate tar archive for your platform (see download links).
   
2. Create and change into a new temp directory:
   
   cd $(mktemp -d)
3. Extract the archive:
   
   tar -xzf ~/Downloads/PolarProxy_2.0.0_linux-x64.tar.gz
4. Run install script:
   
   sudo ./install-polarproxy-service.sh
5. Show service status:
   
   systemctl status polarproxy.service
6. Show logs:
   
   sudo journalctl -t polarproxy

The install script creates a system user “polarproxy”, a systemd service called “polarproxy.service”, and then starts that service. You are, of course, free to modify the installation script and polarproxy.service file if you want a different configuration.

Quick start for Alpine Docker

1. Download the appropriate Linux musl archive for your platform (see download links).
2. Create and change into a new temp directory:
   
   cd $(mktemp -d)
3. Extract:
   
   tar -xzf ~/Downloads/PolarProxy_2.0.0_linux-musl-x64.tar.gz
4. Deploy to docker:
   
   sudo docker compose up -d --build
5. Show container status:
   
   sudo docker ps --filter "name=polarproxy"
6. Show logs:
   
   sudo docker logs polarproxy

The docker-compose.yml will create a container named “polarproxy” with a non-root user called “polarproxy” without a password.

Listening services in quick start examples

All three quick start deployments above expose the following TCP ports:

• 10443 — Transparent TLS proxy
•  1080 — SOCKS server
•  8080 — HTTP Proxy server
• 10080 — Web server hosting the root CA certificate
• 57012 — PCAP-over-IP server providing decrypted traffic

A port forwarding (DNAT) firewall rule must be configured, which redirects TCP 443 traffic to the transparent TLS proxy, in order to run PolarProxy as a transparent TLS proxy that intercepts outgoing TLS traffic. See the Routing Option alternatives on the official PolarProxy page for more details.

Decrypted traffic from all proxy services is accessible through the PCAP-over-IP service on TCP port 57012. They are also written to PCAP files in /var/log/polarproxy/.

Test your deployment

Download PolarProxy’s root CA certificate:

Convert to PEM format:

Monitor decrypted traffic via PCAP-over-IP in one terminal/shell:

Test transparent proxy in another terminal/shell:

Test SOCKS proxy:

Test HTTP proxy:

Downloads and docs

See the PolarProxy product page for downloads, full command-line options, sample configurations etc.

Feel free to share feedback or report bugs about PolarProxy.

Posted by Erik Hjelmvik on Monday, 18 May 2026 07:01:00 (UTC/GMT)

Tags: #PolarProxy​ #systemd​ #cutoff​

Don't Delete PCAP Files - Trim Them!

We are happy to release TrimPCAP today! TrimPCAP is a free open source tool that reduces the size of capture files in an intelligent way.

The retention period of a packet capture solution is typically limited by either legal requirements or available disk space. In the latter case the oldest capture files are simply removed when the storage starts getting full. This means that if there is a long ongoing session, such as a download of a large ISO file, streamed video or a reverse shell backdoor, then the start of this session will likely be removed.

I know from experience that it’s painful to analyze network traffic where the start of a session is missing. The most important and interesting stuff generally happens in the beginning of each session, such as the HTTP GET request for an ISO file. As an analyst you don’t need to look at all the other packets in that ISO download (unless you believe the ISO contains malware), it’s enough to see that there is a GET request for the file and the server responds with a “200 OK”.

Image: CapLoader transcript of an ISO download

If that download had been truncated, so that only the last few packets were remaining, then it would be really difficult to know what was being downloaded. The same is true also for other protocols, including proprietary C2 protocols used by botnets and other types of malware.

✂  TrimPCAP  

TrimPCAP is designed to overcome the issue with truncated sessions by removing data from the end of sessions rather than from the beginning. This also comes with a great bonus when it comes to saving on disk usage, since the majority of the bytes transferred across the Internet are made up of big sessions (a.k.a “Elephant Flows”). Thus, by trimming a PCAP file so that it only contains the first 100kB of each TCP and UDP session it’s possible to significantly reduce required storage for that data.

The following command reduces the PCAP dataset used in our Network Forensics Training from 2.25 GB to just 223 MB:

user@so$ python trimpcap.py 102400 /nsm/sensor_data/so-eth1/dailylogs/*/*
Trimming capture files to max 102400 bytes per flow.
Dataset reduced by 90.30% = 2181478771 bytes
user@so$

A maximum session size (or "flow cutoff") of 100kB enables trimpcap.py to reduce the required storage for that dataset to about 10% of its original size, which will significantly extend the maximum retention period.

Putting TrimPCAP Into Practice

Let’s assume that your organization currently has a maximum full content PCAP retention period of 10 days and that trimming sessions to 100kB reduces the required storage to 10%. TrimPCAP will then enable you to store 5 days with full session data plus 50 additional days with trimmed sessions using the same disk space as before!

A slightly more advanced scheme would be to have multiple trim limits, such as trimming to 1MB after 3 days, 100kB after 6 days and 10kB after 30 days. Such a setup would probably extend your total retention period from 10 days to over 100 days.

An even more advanced trimming scheme is implemented in our packet capture agent PacketCache. PacketCache constantly trims its PCAP dataset because it is designed to use only 1 percent of a PC’s RAM to store observed packets, in case they are needed later on for incident response. PacketCache uses a trim limit which declines individually for each observed TCP and UDP session depending on when they were last observed.

Downloading TrimPCAP

TrimPCAP is open source software and is released under the GNU General Public License version 2 (GPLv2). You can download your own copy of TrimPCAP from the official TrimPCAP page:
https://www.netresec.com/?page=TrimPCAP

Happy trimming!

✂- - - - - - - - -

Posted by Erik Hjelmvik on Tuesday, 05 December 2017 12:40:00 (UTC/GMT)

Tags: #PCAP​ #python​ #flow​ #cutoff​