# PcapXray for offline and live packet capture analysis

> PcapXray is a Python GUI for turning PCAP files or live traffic into annotated network diagrams, with device details, protocol views, Tor detection, heuristic malicious-traffic flags, and file extraction. It is most appropriate for investigators who need a visual starting point and can work within its packet-parsing and privilege constraints.

**srixivas/PcapXray** — :snowflake: PcapXray - A Network Forensics Tool - To visualize a Packet Capture offline as a Network Diagram including device identification, highlight important communication and file extraction

- Repository: https://github.com/srixivas/PcapXray
- Stars: 1,890 · Forks: 292
- Language: Python
- License: GPL-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/srixivas-pcapxray

## Why PcapXray is built around a network map

PcapXray addresses the initial triage problem faced by forensic investigators and anyone analyzing network traffic: a packet capture contains many sessions, but it does not present those sessions as a readily understandable network. The project aims to turn a `.pcap` file, a `.pcapng` file, or live traffic into an annotated diagram that shows hosts, traffic flows, selected protocols, Tor communication, and traffic marked by its heuristics. It also exposes per-session data such as payloads, TLS records, DNS queries, device information, and output files.

The intended users are investigators, security analysts, and other people who need to understand network evidence without manually reading every packet first. PcapXray is not presented as a general packet inspection command line or as a replacement for a complete forensic acquisition platform. Its main value is the combination of a graph-oriented view with lookup and classification features. The README describes server details, OUI vendor information, hostname resolution, WHOIS data, Tor consensus matching, and port and domain based malicious-traffic flags.

That scope also defines its main boundary. A flag is a heuristic indicator, not a verified verdict. A node identified through an address or hostname is useful context, but the generated diagram should not be treated as proof of a person's identity or of malicious intent. The project does describe extraction of data involved in each session, but the documentation does not claim that every application payload can be recovered from encrypted protocols.

## The PcapXray analysis pipeline from packets to diagrams

The documented architecture begins with `user_interface.py`, which acts as the GUI controller. It connects to `pcap_reader`, the component responsible for file input and live capture. Parsed or discovered session data is held in `memory.py`, described as shared state. Other modules then consume that state. `communication_details_fetch` handles DNS and WHOIS-related details, `device_details_fetch` performs OUI vendor lookup, `tor_traffic_handle` works with Tor consensus data, and `malicious_traffic_identifier` applies heuristic flags.

The output path uses `plot_lan_network` to produce Graphviz PNG output and pyvis HTML. The GUI also has an `interactive_gui` module using Matplotlib for a panel that can update during live capture. A `sqlite_store` provides session persistence, allowing a session to be reloaded without repeating the analysis. This is a useful design for investigators who may need to inspect the same capture repeatedly, although the README does not document retention controls, cache invalidation behavior, or a rollback procedure.

The parser is selected in the toolbar. `auto` tries `dpkt` first and falls back to `scapy`. `dpkt` is intended for large files and lower memory use. `scapy` is positioned for deeper protocol inspection and is described as slower on large files. `pyshark` offers the broadest protocol coverage, but it requires `tshark`. The choice affects both coverage and resource cost, so the default is not a universal answer. A capture whose useful evidence is in a protocol that the selected engine does not decode can produce an incomplete diagram even if the visualization itself succeeds.

## Installing PcapXray and analyzing the first capture

The README requires Python 3.10 or newer. On Ubuntu or Debian, install the system packages for Tk, Graphviz, and tshark, then install the Python requirements. The documented commands are:

```bash
sudo apt-get update
sudo apt-get install -y python3-tk graphviz tshark
pip3 install -r requirements.txt
sudo python3 Source/main.py
```

The `python3-tk` package supplies the Tk binding. The README specifically says to install Pillow through pip rather than `python3-pil` from apt because the latter conflicts with the intended setup. On macOS, the documented sequence is:

```bash
brew install graphviz
pip3 install -r requirements.txt
sudo python3 Source/main.py
```

File analysis runs without `sudo`, while live capture requires it. For the first real use, enter or browse to a `.pcap` or `.pcapng` file, choose an output directory, leave the engine at `auto` unless there is a specific reason to change it, and click `Analyze!`. After analysis, click `Visualize!` to generate the static network diagram. `Interactive Graph` opens the pyvis HTML in a browser, while `Graph Panel` opens the Matplotlib view. The expected result is a generated diagram plus the report and session data described by the project, rather than a command-line transcript.

## Live capture and the GUI controls

PcapXray can use `AsyncSniffer` for live capture. The interface presents a network-interface selector, `Start Live`, `Stop`, and `Visualize!`. Live capture requires root or `sudo` for raw socket access on all platforms. The documented graph refresh interval is four seconds. Selecting `Stop` ends capture and runs covert channel detection afterward. The static snapshot can then be generated with `Visualize!`.

For a file-only investigation, this privilege requirement is avoidable. That distinction is important when PcapXray is installed on a workstation where the analyst has permission to inspect an existing capture but should not run the GUI as root. The macOS instructions explicitly state that file analysis runs without `sudo`, while live capture requires it.

The GUI also provides traffic filters for All, HTTP, HTTPS, Tor, Malicious, ICMP, and DNS. These filters are presentation controls around the analyzed traffic, not independent detectors. For example, filtering for DNS does not establish that the capture contains complete DNS evidence. Similarly, the malicious filter exposes sessions marked by the configured heuristics, but the README does not document a signature database, confidence score, or false-positive analysis. The graph is most useful as an investigation index: select a node or flow, inspect its details, and then decide which sessions require deeper validation.

## Parsing engines, memory limits, and wrong-tool cases

PcapXray's engine choice is a practical constraint. `dpkt` is the documented choice for large offline captures because it is described as fast and memory efficient. `scapy` is intended for deeper protocol inspection, but it is slower on large files. `pyshark` depends on `tshark` and is presented as the option for maximum protocol coverage. `auto` attempts `dpkt`, then falls back to `scapy`, which simplifies initial use but gives the analyst less deliberate control over the trade-off.

The README warns that memory usage scales with session count and that very large PCAPs of 1GB or more may be slow. This makes PcapXray a poor fit as the only tool for an unrestricted, very large capture where selective extraction or streaming analysis is required. The documented recommendation is to use `dpkt` for large files, but that does not remove the session-count memory issue. A user who needs constant-memory processing across an enormous capture should verify that the tool's state model is acceptable before relying on it.

There are other wrong-tool cases. PcapXray does not provide packet-level editing, payload modification, or an intrusion-detection workflow. It does not explain how to interpret an uncertain Tor match as attribution, and it does not document rollback for the SQLite cache. For encrypted application data, a diagram can show an endpoint or TLS record without revealing the application content. It should therefore complement, rather than replace, a protocol-specific analysis tool when the investigation depends on payload interpretation.

## Rendering, persistence, and maintenance implications

Static diagrams depend on Graphviz, while the browser-oriented graph is generated with pyvis. Matplotlib supplies the embedded interactive panel. These are separate output paths with different operational requirements. The README documents the dependencies but does not describe what happens when Graphviz or `tshark` is missing, so an installation should be checked before beginning a batch of investigations. The Dockerfile provides an Ubuntu 22.04 setup, installing Graphviz, Tk, Git, GTK and related system packages before cloning the repository and installing `requirements.txt`.

Session persistence through SQLite can reduce repeated work when reopening an analysis. The repository also has a `sqlite_store` module, but the available documentation does not state the database file location, retention policy, schema migration behavior, or how cached results relate to changed capture files. Operators should treat the cache as investigation state rather than an archival evidence format unless they verify those details in `DEV.md` or the implementation.

The project is licensed under GPL-2.0. That matters for distribution and integration, especially if PcapXray code is modified or included in another product. The license should be reviewed for the intended deployment model. No legal conclusion is made here.

The repository is not archived, but its last push was on 2026-05-01, and recent releases are v5.0, v5.1, and v5.2 from April and May 2026. That recent release history does not remove the need to assess Python version changes, dependency changes, and the cost of migrating SQLite sessions. The README reports testing on Python 3.10, 3.11, and 3.12 and describes test commands, but it does not claim compatibility with future releases.

## How PcapXray compares with protocol-specific analysis

A real alternative is to use a protocol-specific packet analysis tool and build the traffic review manually around the questions in the capture. Such a workflow may provide more direct control over individual protocols, fields, payloads, and export formats. Its cost is the work required to construct a host inventory, correlate flows, inspect DNS, and document relationships without PcapXray's graph and session cache.

PcapXray's different approach is integration. It combines several parsing engines, shared session state, DNS and WHOIS lookups, OUI data, Tor consensus handling, heuristic traffic flags, Graphviz rendering, pyvis HTML, and Matplotlib views in one GUI. That makes it a better fit when the immediate task is to move from a capture file to a navigable overview. It is less compelling when the investigation requires one protocol with unusually deep detail, guaranteed payload extraction, or a strict chain of custody for generated artifacts.

The choice should therefore follow the question being asked. Use PcapXray for visual triage and relationship discovery. Use a protocol-focused workflow for exact field inspection and application-level evidence. The README does not claim that PcapXray replaces those tasks, and its stated future protocol support is not evidence that QUIC, HTTP/2, or mDNS analysis is already available.

## Conclusion

Adopt PcapXray when you need a GUI-based network map and a set of first-pass traffic annotations from a PCAP or live capture, especially if PyShark and tshark are acceptable dependencies. Do not choose it as the sole evidence system for very large captures, environments without root access for live capture, or cases requiring verified attribution of every malicious flag. Verify first that the selected parsing engine works with the capture format, that external Graphviz rendering is available, and that the documented SQLite session data and generated reports are acceptable for your investigation workflow.

## FAQ

### How do I install PcapXray on Ubuntu or Debian?

Install Python 3.10 or newer, the documented system packages for Tk, Graphviz, and tshark, and the Python requirements. The README then launches the GUI with `sudo python3 Source/main.py`.

### Does PcapXray support live network capture?

Yes. The GUI includes an interface selector, `Start Live`, and `Stop` controls, and the graph panel updates every four seconds. Live capture requires root or `sudo` because it needs raw socket access.

### Which PcapXray engine should I use for a large PCAP?

The README recommends `dpkt` for large files and lower memory use. It describes `scapy` as slower on large files and `pyshark` as requiring `tshark` for maximum protocol coverage.

### Can PcapXray identify Tor and malicious traffic?

PcapXray documents Tor detection using Tor consensus data and session matching. It also flags possible malicious traffic using port and domain heuristics, so those flags should be treated as indicators requiring investigation rather than confirmed attribution.

## Sources

- [Issues](https://github.com/srixivas/PcapXray/issues)
- [License: GPL-2.0](https://github.com/srixivas/PcapXray/blob/master/LICENSE)
- [README](https://github.com/srixivas/PcapXray/blob/master/README.md)
- [Releases](https://github.com/srixivas/PcapXray/releases)
- [srixivas/PcapXray on GitHub](https://github.com/srixivas/PcapXray)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/srixivas-pcapxray