PacketCircle macOS — User Manual

The desktop half of PacketCircle Native: conversation topology, live capture, native Decode, and one-click handoff to Wireshark — built in Swift/SwiftUI.

1. Background and motivation

PacketCircle macOS is the desktop half of PacketCircle Native — a Swift/SwiftUI rewrite of the ideas behind the original open-source PacketCircle Wireshark plugin. It shares PacketCircleCore with the iOS app: open a PCAP/PCAPNG (or capture live), see who’s talking to whom, spot rough TCP health, and drill into a conversation — all without shipping Wireshark or a GPL dissection stack.

What it is

A capture visualizer built around conversation topology (the circle), a sortable pair table, rate/quality gauges, and a native packet Decode window. Desktop-native: Decode opens in its own window, live capture from local interfaces, replay of a capture at original timing, and one-click handoff to Wireshark when you need its full dissector depth. Proprietary — not open source.

On macOS 1.2.x: Expert Alerts, Compare Conversations, Sanitize Capture, Generate Report, Map, and tunable Settings — see §16, below.

What it is not

PacketCircle is not a desktop Wireshark. It contains no open-source Wireshark / libwireshark dissection. Decode is native and best-effort: solid IP/TCP/UDP detail and some application-layer recognition, not dissector-for-dissector parity with Wireshark. TCP session-quality grades are a native heuristic — explicitly labeled “not Wireshark tcp.analysis” wherever shown. When you need full dissector depth, Open in Wireshark hands the capture off with the current display filter already copied.

2. Getting started

Before anything is loaded, the main window offers the same four entry points directly on the canvas:

Empty state — Open Capture, Interfaces, Demo Mode, and Replay, all one click away.

3. Main window layout

The window is a single split view: a sidebar (pair list + protocol legend) on the left, and the active display mode (Circle / Table / Gauges) on the right, with a two-row toolbar above.

Circle view with Demo Mode loaded. Loading a capture adds a second toolbar row for export, reset, report, external-open, and close.

The protocol legend at the bottom of the sidebar lists every protocol seen in the capture in two columns; click one to filter, and where the list is long a Show all link expands it.

3.1 Primary toolbar

3.2 View options bar

3.3 Sidebar

The pair list mirrors what’s on the circle, filtered by the protocol legend. Selecting a row highlights it orange and highlights the matching arc on the circle.

Selecting a conversation highlights both the sidebar row and the matching arc.

4. Circle view

Hosts sit on a ring as hexagonal nodes; each conversation is an arc, colored and weighted per the view options above. One-way traffic is dotted with an arrowhead; two-way traffic is a solid line.

Gestures

Floating canvas controls (top-right): a search field (IP, CIDR, or name), fit-to-screen, rearrange, a Hosts toggle, and Reset.

4.1 Right-click on an arc (conversation)

Restart capture · this conversation / · src / · dst · Follow TCP Stream · Copy Wireshark Filter · Copy BPF Filter · Select.

5. Connection details popup

Selecting a conversation opens a floating popup with a real triage panel for that pair — not just an address summary.

TCP session health, handshake RTT, and ACK round-trip quality charts, right next to the packet counts.

Actions: Copy Filter · Decode (filtered to this pair) · Follow TCP Stream · Wireshark · Save Session… (save just this conversation as its own file). Closing the popup also clears the selection, so the sidebar row and circle arc stop being highlighted.

6. Table view

A sortable table of the same Top-N pairs, with real analysis columns rather than just addresses.

Source, Destination, Ports, Pkts, Bytes, Protocol, Quality (grade + score), Issues (R:n Z:n), Window, plus RTT/health columns.

7. Gauges view

A dashboard of rate gauges and distribution charts: arc gauges for packets/s, bytes/s, and errors/s (labeled “Session average” on a static capture, “Instantaneous” with a live sparkline during capture/replay), plus Top Talkers and Top Protocols bar charts.

Rate gauges, Top Talkers, and Top Protocols.

8. Decode window

Decode opens in its own window (⇧⌘D, or the toolbar Decode button) so you can keep the Circle in view while reading packets.

Filter chips, packet list, expandable protocol tree, and synced hex dump.

Open it filtered to one conversation via Decode in the connection popup, or unfiltered via the toolbar/⇧⌘D for the whole capture.

9. Follow TCP Stream

An in-window modal (not a separate window) that reassembles one TCP flow’s payload bytes.

Client/server bytes color-coded, with direction and format controls.

10. Live capture

Interfaces… (⇧⌘I) opens a sheet listing local interfaces (native, live rates via dumpcap) with a traffic sparkline and packets/s per interface.

Interface list, optional BPF filter, Promiscuous / Hide idle toggles.

macOS may ask for your password once per reboot to allow packet capture — not again when you stop. Once running, the status line reads e.g. ● CAPTURING · en0 · 292 pkts · 34 pairs, and Gauges switch to Instantaneous readings with live sparklines.

Live capture — footer reminds: “All traffic — Save to keep · right-click pair/node to filter.”

Right-click actions on the circle (Restart capture · this conversation / · host) restart the live capture with a BPF filter scoped to just that traffic.

11. Replay and Demo Mode

Demo Mode loads a bundled sample capture — the fastest way to see the app populated without your own PCAP; every screenshot in this manual uses it. Replay (⌥⌘R) replays an already-open file at its original inter-frame timing, so arcs and gauges animate the way they would live. Stop (⌘.) ends it and returns to the static full-file view.

12. Settings

Settings has three tabs: Display, Decode, and Colors.

12.1 Display

Host names toggle and quality grade-band selector.

12.2 Decode

Monospace font picker with live preview, and a 9–20pt size slider — applies to the Decode packet list, protocol tree, and hex dump.

12.3 Colors

Per-protocol color overrides for the Decode window, with a Reset All to restore defaults.

13. Wireshark integration

Open in Wireshark… — from the toolbar, the connection popup, or Follow TCP Stream — hands the current capture (or filtered view) off to a locally installed Wireshark, with the equivalent display filter already copied to the clipboard. Disabled if Wireshark isn’t installed.

14. Keyboard shortcuts

15. Workflows

A. First look at a capture

⌘O to open a file (or Demo Mode). On Circle, skim arcs; switch edge color to Quality to spot Fair/Poor sessions. Click an arc for the connection popup, or open Table for a sortable list with quality/issue columns.

B. Diagnose a bad TCP session

Edge color → Quality; look for orange/red arcs, or sort Table by Quality. Click the arc → connection popup → read TCP session health and the quality charts. Follow TCP Stream for payload, or Decode for frame-by-frame detail. Save Session… to keep just this conversation. Reset clears the selection once you’re done.

C. Live triage on the wire

⇧⌘I → pick an interface, optionally set a BPF filter → Start Capturing. Watch Circle/Gauges update live; right-click a conversation → Restart capture · this conversation to narrow the live capture to just that traffic. ⇧⌘P to pause and inspect, ⌘. to stop and analyze the full trace.

D. Handoff to Wireshark

Select a conversation (or none, for the whole capture). Open in Wireshark… from the toolbar, the popup, or Follow TCP Stream — the display filter is copied automatically.

16. What’s new in 1.2.x (Tech Preview)

The macOS app shares PacketCircleCore with iOS, plus desktop chrome: multi-window Decode/Compare, live capture, Map, Pro tools, and Expert Alerts. Positioning is unchanged: not Wireshark, proprietary native analysis, no telemetry.

Circle view with the Expert Alerts strip (App / L4+ / L3 / DLC) and quality bar.

16.1 Getting started (Mac)

Live capture (where entitled) and save options remain available from the Capture / File menus.

Expert Alerts browser popover — severity, summary, endpoints, and Suppress in the context menu.

Tools / toolbar cluster with the Pro actions: Sanitize, Report, Decode.

16.2 Expert Alerts (Circle)

Left of the Circle: stacked chips App → L4+ → L3 → DLC. Counts are warnings and errors only.

Use: Left-click a chip to filter conversations that have alerts in that band. Right-click a chip → Show … alerts… to browse hits; hover highlights the chord; click selects the pair (and the socket that raised the alert when ports are known). In the list, right-click a row → Suppress “…” to hide that message type from chips/lists. Re-enable under Settings → Expert.

The chip menu itself does not offer Suppress (browse only).

16.3 Connection panel Expert

Below the conversation summary (when findings exist), an Expert section lists merged messages for this pair: capture App/L3/DLC alerts, TCP quality experts, and (when relevant) STP / topology alerts from the Map pass.

Connection details — Expert section with app / TCP findings.

16.4 Decode: Expert Info & TLS alerts

Decode window — Expert Info plus TLS Alert Meaning on a failing handshake frame.

Decode is a separate window (packet list · tree · hex). Per-frame Expert Info can appear at the top of the tree; parent layers may show severity badges.

TLS Alert records:

• Cleartext — level (warning/fatal), RFC description (e.g. bad_certificate), and a short Meaning.
• Encrypted / opaque — labeled as such (payload bytes after the cipher is active are not real level/description codes).

Suppressed Expert types are omitted from Decode annotations as well.

16.5 Settings

PacketCircle → Settings… panes include:

Settings → Expert — thresholds and suppressed alert types.

16.6 Sanitize Capture & Generate Report

• Sanitize Capture… — native streaming scrub (cleartext / all payload / payload + IP/MAC) with checksum fixups; write PCAPNG via the save panel. No Wireshark engine required.
• Generate Report… — multi-section PDF (file summary with SHA-256, charts, port/TCP analysis, optional annotated sidebars).

Generate Report — sample PDF output.

Example pages from a generated report: cover, IP communication matrix, TCP analysis.

16.7 Compare Conversations

Tools → Compare Conversations… (⇧⌘Y), or Compare… from Connection details. Side A is the reference; side B another edge or a second capture. The report covers MAC/IP (incl. TOS/DSCP), TCP setup, RTT, certificates, app/auth samples, and findings (RST, TLS alert, RTT gap, cert/SNI, auth).

⌘-click a second Circle edge first to pre-fill A and B.

Compare Conversations — findings plus side-by-side table.

16.8 Topology Map

Map view with STP / topology context.

Map view walks L2/L3 relationships. STP root-change / TCN-style signals can appear under conversation Expert. Clicking a node opens Connection details (MAC mode when needed for L2).

16.9 Decode display filter (1.2.2)

Decode has a display filter next to search, using Wireshark syntax for the protocols and fields PacketCircle actually decodes: tcp, tcp.port == 80, ip.addr == 10.0.0.1, http and tcp.flags.syn, chained with contains, and/or/not. Autocomplete offers only names from PacketCircle’s own catalog — unsupported names (ospf, wlan, tcp.stream) turn the field red and leave the packet list unfiltered rather than silently matching nothing.

tcp.analysis.* covers the native per-frame experts raised elsewhere in the app: retransmission, spurious retransmission, ACKed unseen segment, zero window, duplicate ACK. This is PacketCircle’s own analysis, not Wireshark’s engine — tcp.stream and out-of-order detection remain unavailable.

16.10 Report Expert messages (1.2.3)

Generate Report’s Detailed and Field guide PDFs add an Expert messages section built from the capture-wide expert modules: type, description, counters, and sample nodes/pairs. Some findings are explicitly informational — present in the capture without proving a connectivity or performance problem (SPAN duplicates, traceroute TTL=1, jumbo frames, one-sided unanswered ARP, HTTP 404, encrypted TLS alerts, and similar).

16.11 Settings → Expert thresholds (1.2.3)

Settings → Expert (Mac; iOS Options) adds sliders for thresholds that vary by LAN:

16.12 ARP experts & Circle Expert mode (1.2.3)

Two new Expert Alerts: ARP request storm (who-has burst per second) and ARP unanswered (retried who-has with no reply anywhere in the file).

The Circle toolbar gains an Experts mode after Top 10/25/50: it shows conversations carrying warn/error Expert Alerts instead of only the busiest (capped at 250). Solo an Expert Alerts band first to restrict which layer it draws from.

16.13 Capture & decode depth (1.2.4)

IGMP / MLD decode — group addresses, v1/v2/v3 queries and reports (source lists, INCLUDE/EXCLUDE), well-known multicast labels (SSDP, mDNS, all-systems).

TLS on HTTP alt ports — HTTPS on 8080 / 80xx / 8888 is labeled TLS when the payload is a TLS record; plaintext HTTP on those ports still shows as HTTP.

PCAP over IP (client) — PacketCircle connects out to a remote pcap stream (TCP@host:57012), the same convention Wireshark uses with -k -i TCP@host:port. The phone or Mac never sniffs its own Wi-Fi or cellular traffic — the other side must already be sending a PCAP stream, for example from the pcapoverip broker or PolarProxy. See PacketTools → PCAP over IP for the broker link and a small diagram of how it fits together.

iOS PCAP over IP — connect sheet and the resulting live capture on the Circle.

Payload NetFlow / syslog — custom collector ports (e.g. UDP 515) classify from the datagram, not only IANA 2055/514.

Richer mDNS — Bonjour service types, cache-flush / QU, additional A/AAAA.

Fixed in 1.2.4: live PCAP-over-IP no longer re-analyzes the whole file every second or re-packs the Circle ring; iOS remote-connect failures no longer look like a Files import error (invalid host/port is shown in the sheet); Options → PCAP over IP waits for Options to dismiss before presenting the connect sheet.

16.14 NetBIOS and Windows browsing decode (1.2.5)

NetBIOS Name Service — queries, responses, name records and NBSTAT name tables; names also feed the host labels on Circle and Talkers.

NetBIOS Datagram and the Windows Browser protocol — \\MAILSLOT\\BROWSE host announcements and elections, shown in Decode and the Connection details Application preview.

Separate labels for NetBIOS-NS, NetBIOS-DGM and NetBIOS-SSN (ports 137–139) instead of one generic NetBIOS bucket.

16.15 Connection Expert follows the socket (1.2.6)

Viewing one socket (for example HTTP on port 80) now shows only that service’s Expert findings and TCP health, plus host-wide L3 / DLC findings — not FTP, mail, or other services’ alerts from the same pair of hosts.

A new Other sockets list at the bottom of Connection details switches between sockets in one click, with a warning marker on the ones that have alerts. Whole conversation is one click away.

The same finding on two services of one conversation (for example HTTP 404 on :80 and :8080) is now listed per socket instead of merged into a single Expert Alerts row.

16.16 More accurate Expert Alerts, smaller fixes (1.2.5)

Kerberos findings only fire on Kerberos traffic (ports 88 / 464) — no more false alarms on unrelated TCP streams.

Jumbo / giant frame findings are based on the real on-wire frame size, not a reassembly artifact.

Reset always returns the Circle to the IP view, even after filtering on link-layer (DLC) alerts.

Show host names is on by default for new installs.