{"id":50668173,"url":"https://github.com/phreakocious/tcptrace-ng","last_synced_at":"2026-06-08T08:07:52.866Z","repository":{"id":361856609,"uuid":"1255544324","full_name":"phreakocious/tcptrace-ng","owner":"phreakocious","description":"local web UI for tcptrace pcap analysis","archived":false,"fork":false,"pushed_at":"2026-06-01T15:16:35.000Z","size":56,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T16:08:34.035Z","etag":null,"topics":["packet-analysis","packet-capture","pcap","pcap-analyzer","tcpdump"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phreakocious.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T00:23:49.000Z","updated_at":"2026-06-01T15:43:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/phreakocious/tcptrace-ng","commit_stats":null,"previous_names":["phreakocious/tcptrace-ng"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/phreakocious/tcptrace-ng","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phreakocious%2Ftcptrace-ng","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phreakocious%2Ftcptrace-ng/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phreakocious%2Ftcptrace-ng/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phreakocious%2Ftcptrace-ng/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phreakocious","download_url":"https://codeload.github.com/phreakocious/tcptrace-ng/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phreakocious%2Ftcptrace-ng/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34053580,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["packet-analysis","packet-capture","pcap","pcap-analyzer","tcpdump"],"created_at":"2026-06-08T08:06:39.011Z","updated_at":"2026-06-08T08:07:52.852Z","avatar_url":"https://github.com/phreakocious.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tcptrace-ng\n\nLocal web UI for [tcptrace](https://github.com/blitz/tcptrace) pcap analysis, with interactive in-browser graphs.\n\n![tcptrace-ng UI](docs/example.png)\n\n## Quickstart\n\n```bash\n# 1. Get a tcptrace binary — pick one:\ngit clone --recurse-submodules \u003cthis repo\u003e \u0026\u0026 cd tcptrace-ng \u0026\u0026 make vendor-tcptrace\n# or: brew install tcptrace            # macOS\n# or: apt install tcptrace             # Debian/Ubuntu\n\n# 2. Install tcptrace-ng\npip install -e \".[dev]\"\n# or: uv pip install -e \".[dev]\"\n\n# 3. Run it in a directory of pcaps\ncd /path/with/pcaps\ntcptrace-ng\n```\n\nA browser opens to a local NiceGUI page laid out as a top bar + sidebar + main panel. Pick a pcap in the header; the sidebar fills with that pcap's connections (filterable). Click any connection to analyze it on the spot. The main panel shows:\n\n- One tab per generated `.xpl` graph (time-sequence, throughput, RTT, owin, ssize), rendered as interactive Plotly charts with pan/zoom.\n- A **tcptrace output** button (top-right) opens the raw color-coded analysis in a modal (green = good, yellow = interesting, red = bad).\n- Header checkboxes toggle common tcptrace flags — **DNS** (opt-in, off by default → adds `-n` to skip hostname/port resolution), **RTT** (`-r`), **warn** (`-w`), **csum** (`--checksum --warn_printbadcsum` to verify and surface bad IP/TCP checksums — useful for catching NIC offload artifacts), **0-axis** (`-zx`). Toggling re-runs analysis and busts the cache for that flag combo.\n- A `⚠ N warnings` chip appears in the header when the pre-flight scan flags conditions that distort analysis. Currently detects NIC offload (LSO/GSO/TSO/LRO/GRO) — when the capture shows TCP segments larger than 1500 B, the captured MSS, time-sequence staircases, and retransmit detection are all unreliable. Click for full text.\n\n### Tunnel decapsulation\n\ntcptrace doesn't know about modern overlay encapsulations, so any flow wrapped in **Geneve** (UDP/6081), **VXLAN** (UDP/4789), or **GRE** (IP protocol 47) is invisible to it. tcptrace-ng auto-detects these in the first ~200 frames; if any are present, it rewrites the pcap once (stripping outer headers) and feeds the decapsulated copy to tcptrace. The decap'd pcap is cached at `.tcptrace/\u003cpcap\u003e/decap.pcap`. The header shows `decap: geneve` (or `vxlan+gre`, etc.) when a decap pass ran.\n\nBare-IP inners (common with GRE) get a synthetic Ethernet header so the output stays DLT_EN10MB. IPv6 extension headers (HBH/routing/destination/fragment) are already handled natively by tcptrace's `ipv6.c`.\n\nClick another connection to swap the view --- already-analyzed connections render instantly from cache. The sidebar footer has a \"↓ xpl zip\" button that bundles every connection you've analyzed in this session, in case you still want to view them in desktop `xplot`/`jplot`.\n\n## Caching\n\nPer-pcap caches live in `.tcptrace/\u003cpcap-name\u003e/` next to each pcap. The header shows total cache size. **Clear cache** wipes everything; **Reanalyze** wipes just the current pcap's cache.\n\nAdd `.tcptrace/` to your `.gitignore`.\n\n## CLI options\n\n```\ntcptrace-ng [DIR]\n  --port PORT          bind port (default: pick free)\n  --no-browser         don't auto-open browser\n  --timeout SECONDS    per-subprocess timeout (default: 60)\n  --debug              verbose logs\n  -V, --version\n```\n\n## Vendored tcptrace\n\nUpstream tcptrace ([tcptrace.org](http://tcptrace.org)) hasn't been touched since 2006; its TLS cert is expired and the source no longer builds on modern toolchains. [github.com/blitz/tcptrace](https://github.com/blitz/tcptrace) is the practical canonical source — it's what the FreeBSD port and Homebrew formula track. tcptrace-ng vendors a fork of that at `vendor/tcptrace` (submodule → [phreakocious/tcptrace](https://github.com/phreakocious/tcptrace)) with two build fixes for modern macOS/Linux toolchains:\n\n- `mod_traffic.c`: silenced an unused-return-value warning that `-Wreturn-type` now fails on.\n- `tcpdump.c`: replaced the private `pcap_offline_read()` (removed in modern libpcap) with `pcap_dispatch()` — [msagarpatel's 2021 Ubuntu fix](https://github.com/blitz/tcptrace/pull/9).\n\n```bash\ngit submodule update --init    # if you didn't clone with --recurse-submodules\nmake vendor-tcptrace           # configure + build → vendor/tcptrace/tcptrace\n```\n\nThe runner resolves the binary in this order: `$TCPTRACE_BIN` (if set) → `vendor/tcptrace/tcptrace` (if built) → first `tcptrace` on `$PATH`. Installed wheels skip the vendored copy and fall back to `$PATH`.\n\n## Development\n\n```bash\nuv venv \u0026\u0026 source .venv/bin/activate\nuv pip install -e \".[dev]\"\npytest -q                # unit tests\nruff check src tests     # lint\nruff format src tests    # format\n```\n\n## Optional dependencies\n\nFor non-pcap captures (e.g., `.cap` from older tools), install the Wireshark CLI tools (`capinfos`, `editcap`). tcptrace-ng will run them automatically as a fallback.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphreakocious%2Ftcptrace-ng","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphreakocious%2Ftcptrace-ng","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphreakocious%2Ftcptrace-ng/lists"}