A native Wireshark plugin that visualizes network communication pairs in an interactive circle diagram with protocol color coding, traffic volume indicators, and PDF report export.

Beta Status: This is version 0.3.2, a public beta release. While fully functional, the software is under active development. Please report any issues you encounter.

▶️ Watch the intro video on YouTube — see PacketCircle in action in under 4 minutes.

• Circle Visualization - Interactive circular graph showing communication relationships between network endpoints
• Protocol Color Coding - Lines colored by transport protocol (TCP, UDP, ICMP, ARP, SCTP, etc.)
• Multicolor Lines - Connections using both TCP and UDP are drawn as dotted lines with alternating colors, making mixed-protocol communication instantly visible
• Line Weight - Proportional to packet/byte volume for at-a-glance traffic assessment
• Rich Tooltips - Hover over nodes to see IP address, packet counts, destination ports, and service names in a detailed popup
• Directional Filtering - Select individual communication pairs to apply precise unidirectional Wireshark display filters
• Connection Popup - Click a line in the circle to see port-level connection details with protocol, service name, and packet counts
• Connection Context Menu - Right-click a connection to apply a filter, follow a TCP stream, or open TCP throughput / round-trip time graphs
• Search - Search by IP address, CIDR range, or port (e.g., TCP 443, UDP 53) with blinking red highlights
• Select Search Results - After a search, select only the matching pairs with one click
• Protocol Filtering - Filter the visualization by specific protocols using interactive checkboxes
• Theme-Aware UI - Automatically adapts to light and dark themes
• PDF Report Export - Generate a one-page PDF report with the circle visualization, IP pair table, and summary text
• Multiple Views - Toggle between circle view and table view
• Conversation Limits - Limit display to top 10, 25, or 50 conversations
• Live Capture Support - Works with both loaded PCAP files and live captures
• Cross-Platform - macOS Universal Binary (Intel + Apple Silicon), Linux x86_64, Windows x86_64

Access the plugin from the Wireshark menu: Tools -> PacketCircle

Interactive circle visualization showing network communication pairs with protocol color coding

Setting a filter based on the visualization

Connections that use both TCP and UDP are drawn as dotted lines with alternating colors, making mixed-protocol communication instantly visible.

Dotted multicolor lines indicate endpoints communicating over both TCP and UDP

Click any line in the circle to open a connection popup showing per-port details. Right-click a row to apply a Wireshark display filter, reassemble and follow a TCP stream, or launch Wireshark's TCP throughput and round-trip time statistics graphs -- all directly from within PacketCircle.

Connection popup with port-level details and context menu

The search bar supports not only IP addresses and CIDR ranges but also TCP and UDP port queries. Type TCP 443 or UDP 53 to instantly highlight all communication pairs using that port. Matching pairs blink red in both the circle and the node pair list. Use the Select Results button to isolate just those pairs.

Searching for TCP port 443 highlights all HTTPS communication pairs

Hover over any node to see a detailed popup with IP address, total packet count, destination ports, and resolved service names.

Node tooltip showing destination ports and service names

Important: Pre-built binaries are available for all major platforms. macOS and Windows target Wireshark 4.6.x. The Linux unified installer supports 4.2.x, 4.4.x, and 4.6.x and auto-detects your version. See Supported Wireshark Versions.

git clone https://github.com/netwho/PacketCircle.git
cd PacketCircle/installer/macos-universal
chmod +x install.sh
./install.sh

Recommended — double-click or run the batch file (no execution policy changes needed):

git clone https://github.com/netwho/PacketCircle.git
cd PacketCircle\installer\windows-x86_64
install.bat

The .bat wrapper launches the PowerShell installer with a temporary -ExecutionPolicy Bypass for the current process only — it does not change your system policy.

cd PacketCircle\installer\windows-x86_64
.\install.ps1

git clone https://github.com/netwho/PacketCircle.git
cd PacketCircle/installer/linux-x86_64
chmod +x install.sh
./install.sh

The unified Linux installer auto-detects your Wireshark version and installs the matching binary.

Note: macOS uses dashes (4-6), Linux uses dots (4.2, 4.4, 4.6), Windows uses dashes (4-6) in the plugin directory name.

# macOS (Wireshark 4.6.x)
mkdir -p ~/.local/lib/wireshark/plugins/4-6/epan/
cp installer/macos-universal/packetcircle.so ~/.local/lib/wireshark/plugins/4-6/epan/

# Linux — pick the binary matching your Wireshark version:
# bin/packetcircle-ws42.so  → Wireshark 4.2.x
# bin/packetcircle-ws44.so  → Wireshark 4.4.x
# bin/packetcircle-ws46.so  → Wireshark 4.6.x
mkdir -p ~/.local/lib/wireshark/plugins/4.4/epan/
cp installer/linux-x86_64/bin/packetcircle-ws44.so ~/.local/lib/wireshark/plugins/4.4/epan/packetcircle.so

# Windows (Wireshark 4.6.x) — run in PowerShell
Copy-Item installer\windows-x86_64\packetcircle.dll "$env:APPDATA\Wireshark\plugins\4-6\epan\"

Tip: Check your exact plugin path in Wireshark under Help -> About Wireshark -> Folders -> Personal Plugins.

1. Load a capture file in Wireshark (or start a live capture)
2. Open PacketCircle: Tools -> PacketCircle
3. Explore: Hover over nodes for details, click pairs to filter
4. Export: Click "PDF" to generate a report

See QUICKSTART.md for a detailed guide.

The PDF export generates a professional one-page report including:

• Header with PacketCircle logo and report title
• Summary text describing the capture (packet count, unique hosts, time range)
• Circle visualization rendered with print-optimized colors (white background, high-contrast labels)
• IP pair table listing source, destination, packets, and bytes
• Footer with generation timestamp

src/
  circle_plugin.c/h      # Plugin entry point and Wireshark integration
  packet_analyzer.c/h    # Packet analysis engine, communication pair extraction
  circle_widget.c/h      # Qt widget for circle rendering, tooltips, PDF rendering
  ui_main_window.c/h     # Main window, controls, filter logic, PDF export
  ui_bridge.cpp/h        # C/C++ bridge for Wireshark plugin API
  plugin.c               # Plugin registration
  CMakeLists.txt         # Build configuration
  packetcircle.qrc       # Qt resource file (embedded assets)

• Wireshark source code (matching your installed version, e.g., 4.6.3)
• CMake 3.10+
• Qt6 (Core, Widgets, Gui) — must be the exact same Qt version bundled by Wireshark (see BUILD.md)
• GLib 2.54+
• C/C++ compiler (Clang recommended on macOS)

Critical: Do not use Homebrew's qt@6 — it is typically newer than what Wireshark bundles, and even a minor version mismatch causes ABI errors at runtime (Symbol not found: __ZN7QObject13doSetPropertyE...). Use aqtinstall to install the exact matching Qt version. See BUILD.md for details.

1. Place the src/ contents into plugins/epan/packetcircle/ within the Wireshark source tree
2. Configure and build:

cd wireshark-source
mkdir build && cd build
cmake -DCUSTOM_PLUGIN_SRC_DIR=plugins/epan/packetcircle ..
make packetcircle

3. The built plugin is at:

build/run/Wireshark.app/Contents/PlugIns/wireshark/4-6/epan/packetcircle.so

To create a binary that works on both Intel and Apple Silicon Macs:

1. Build for arm64 (on Apple Silicon Mac with /opt/homebrew dependencies)
2. Install x86_64 Homebrew and dependencies at /usr/local
3. Build for x86_64 in a separate build directory
4. Merge with lipo:

lipo -create build-arm64/packetcircle.so build-x86_64/packetcircle.so -output packetcircle-universal.so

See BUILD.md for detailed instructions.

macOS and Windows ship with Wireshark 4.6.x builds only. On these platforms, Wireshark is typically installed or updated directly from wireshark.org, so running the latest 4.6.x release is straightforward.

Linux distributions often ship older Wireshark versions in their package repositories (e.g., Debian 13 Trixie ships 4.4.x, some distributions still carry 4.2.x). The unified Linux installer (installer/linux-x86_64/) includes binaries for all three series and automatically selects the right one.

Why separate binaries? Wireshark uses a versioned plugin ABI (MAJOR.MINOR). Each minor release series (4.0, 4.2, 4.4, 4.6) has its own ABI. Pre-built plugins only load in the matching series.

• Wireshark 4.6.x (macOS/Windows) or 4.2.x–4.6.x (Linux), or any 4.x if building from source
• macOS 13.0 or later (Ventura+) — Universal Binary (Intel + Apple Silicon)
• Windows 10/11 x86_64 — Wireshark 4.6.x with Qt6
• Linux x86_64 — Ubuntu 22.04+, Debian 12+/13, Fedora 39+, or similar with Qt6
• No additional runtime dependencies beyond what Wireshark provides

• QUICKSTART.md - 5-minute getting started guide
• CHANGELOG.md - Version history
• LICENSE - GNU GPL v2

This is the most common error and means your Wireshark version doesn't match the plugin binary.

Example errors:

• Library not loaded: @rpath/libwireshark.19.dylib — you installed the 4.6.x binary but have Wireshark 4.4.x or 4.2.x.
• Library not loaded: @rpath/libwireshark.18.dylib — you installed the 4.4.x binary but have Wireshark 4.6.x.
• Symbol not found: _some_function_name — similar ABI mismatch between your Wireshark and the plugin.

Fix: Use the unified Linux installer (installer/linux-x86_64/) which auto-detects your version, or build from source (see Building from Source).

Check:

1. Your Wireshark version matches the plugin binary (Help -> About Wireshark)
2. Plugin is in the correct directory:
   • macOS (4.6.x): ~/.local/lib/wireshark/plugins/4-6/epan/
   • Windows (4.6.x): %APPDATA%\Wireshark\plugins\4.6\epan\
   • Linux (4.2.x): ~/.local/lib/wireshark/plugins/4.2/epan/
   • Linux (4.4.x): ~/.local/lib/wireshark/plugins/4.4/epan/
   • Linux (4.6.x): ~/.local/lib/wireshark/plugins/4.6/epan/
3. File has correct permissions: chmod 644 packetcircle.so (Linux/macOS)
4. Wireshark was restarted after installation
5. Verify the exact path: Help -> About Wireshark -> Folders -> Personal Plugins

Fix (Linux/macOS):

# Find your plugin (check all possible locations)
ls -la ~/.local/lib/wireshark/plugins/*/epan/packetcircle.so

# Fix permissions
chmod 644 packetcircle.so

Common Linux issue: If you installed to 4-6 (dashes) on Linux, move the file to 4.6 (dots). Linux Wireshark uses dots in the plugin version directory.

DBus warnings: Messages like "Session DBus not running" are harmless Qt warnings and do not prevent the plugin from loading.

The plugin has been verified on Windows 11 but may fail to load on Windows 10 due to differences in DLL search paths, VC++ runtime versions, or internet download blocking.

Quick checks:

1. Unblock the DLL - If you downloaded the plugin from GitHub, Windows may silently block it. Right-click packetcircle.dll -> Properties -> check Unblock -> Apply. Or in PowerShell:

   Unblock-File "$env:APPDATA\Wireshark\plugins\4.6\epan\packetcircle.dll"

2. Install the latest VC++ Redistributable - Download and install VC++ 2022 Redistributable (x64)
3. Verify the plugin directory - Check Help -> About Wireshark -> Folders -> Personal Plugins for the exact path Wireshark expects, then confirm the DLL is in the epan subdirectory
4. Check Wireshark's debug log:

   "C:\Program Files\Wireshark\Wireshark.exe" -o log.level:debug 2> debug.txt

   Search debug.txt for packetcircle to find loading errors.

Automated diagnostics: Run the troubleshooting script from the tools/ directory:

cd tools
troubleshoot.bat

The .bat wrapper launches the PowerShell troubleshooter with a temporary execution policy bypass — no system policy changes required. You can also run the PowerShell script directly if you prefer:

.\troubleshoot.ps1

A copy of the troubleshooter is also included in the Windows installer directory (installer/windows-x86_64/troubleshoot.ps1).

This script checks all DLL dependencies, verifies the plugin directory, tests DLL loading, detects internet download blocks, and reports exactly what is wrong. No extra software needed — it runs natively on any Windows 10/11 machine. See tools/README.md for details.

• Ensure you're using a compatible Wireshark version (4.6.x for macOS/Windows; 4.2.x, 4.4.x, or 4.6.x for Linux)
• Check that the binary matches your architecture (file packetcircle.so)
• Try reinstalling using the appropriate installer for your platform

• Ensure a capture file is loaded before exporting
• Check that at least one communication pair exists in the visualization

GNU General Public License v2 - see LICENSE file for details.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

• Wireshark development team for the plugin framework and Qt integration
• Network analysis community for feedback and testing
• AI-Assisted: yes (Claude) — used for build system automation, installer scripting, cross-platform compatibility, and documentation

• Issues: GitHub Issues
• Documentation: See docs in this repository

Built with ❤️ for the network analysis community — github.com/netwho/PacketCircle