pcap-parser

Extract devices, flows, and hostnames from pcap files.

Quick Start

pip install pcap-extract

Parse a capture and get an instant overview:

pcap-parse output.csv capture.pcap
pcap-summary output.csv

List devices on the network:

pcap-devices output.csv

Identify unknown devices with a fine-tuned LLM:

pcap-devices output.csv --identify

Features

• Parse .pcap and .pcapng files using tshark
• Instant capture summaries with protocol breakdown, top talkers, and top destinations
• Per-device traffic profiles with OUI vendor, DHCP hostname, and traffic volume
• LLM-powered device identification via IoT Inspector
• Hostname enrichment from DNS, TLS SNI, DHCP, and reverse DNS
• Flow aggregation with packet counts, byte counts, and inter-arrival times
• JSON output for all commands (--json)

Requirements

• Python 3.9+
• tshark (comes with Wireshark)

Installation

pip install pcap-extract

Or for development:

git clone https://github.com/nyu-mlab/pcap-parser.git
cd pcap-parser
pip install -e ".[dev]"

Usage

Parse pcap files

pcap-parse output.csv capture.pcap
pcap-parse output.csv /path/to/pcap_directory/

Get a quick summary

pcap-summary output.csv

List devices

pcap-devices output.csv
pcap-devices output.csv --identify    # LLM-powered device identification
pcap-devices output.csv --json        # machine-readable output

Aggregate into flows

pcap-flow output.csv flows.csv

Output columns

pcap-parse produces a CSV with columns including:

Column	Description
frame.time_epoch	Packet timestamp
ip.src / ip.dst	Source and destination IPs
tcp.srcport / tcp.dstport	TCP ports
udp.srcport / udp.dstport	UDP ports
_ws.col.Protocol	Protocol (TCP, UDP, DNS, TLS, etc.)
frame.len	Packet length in bytes
src_hostname / dst_hostname	Resolved hostnames
dhcp_hostname	DHCP-advertised hostname
eth.src.oui_resolved	Device vendor from MAC OUI
http.user_agent	HTTP user-agent string

Running tests

pytest tests/ -v

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE for details.