PyPCAPKit -- Comprehensive Network Packet Analysis Library

For technical and maintenance information, see the Official Documentation.

PyPCAPKit is an open-source Python library for parsing, constructing and analysing network packets and PCAP files, with DictDumper as its formatted output dumper.

Unlike popular PCAP extractors such as Scapy, DPKT and PyShark, pcapkit reports more detail about each packet through a more Pythonic interface. Where that depth is not needed, the same interface also drives third-party extraction engines.

The whole project requires Python 3.8 or later. CI supports 3.11 to 3.15, and still tests the end-of-life 3.8 to 3.10 without letting a failure block anything.

Installation

pip install pypcapkit

Or from a clone, for the latest version and for development:

git clone https://github.com/JarryShaw/PyPCAPKit.git
cd PyPCAPKit
pip install -e .

The extraction engines and plug-ins are optional extras:

pip install pypcapkit[DPKT]         # or Scapy, PyShark, PyPCAPFile, PyPCAP, PCAP_CT
pip install pypcapkit[crypto]       # ESP payload decryption
pip install pypcapkit[cli]          # command line interface
pip install pypcapkit[all]          # core addons only: cli + crypto + NGAP (pycrate)

Engines are on demand; all bundles only the core addons the library needs for full functionality. Some engines also need something beyond pip install -- a tshark binary, a C compiler, libpcap headers, or an older interpreter -- and pypcap/pcap-ct must never be installed together. The engine prerequisites give each constraint and its reason. pcapkit enforces them in code: asking for an engine that cannot run in the current environment warns with the cause and falls back to its own parser.

Usage

>>> import pcapkit
>>> extraction = pcapkit.extract('in.pcap', nofile=True)
>>> len(extraction.frame)
6
>>> frame = extraction.frame[0]
>>> str(frame.protochain)
'Ethernet:IPv6:IPv6_ICMP'
>>> frame.info.time
datetime.datetime(2017, 11, 19, 15, 49, 5, 471719, tzinfo=datetime.timezone.utc)
>>> frame.payload.payload.src
IPv6Address('fe80::a6:87f9:2793:16ee')

The output is from the committed examples/captures/in.pcap, so it is reproducible from a clone.

Reassembly, TCP flow tracing and the engine are keyword arguments to the same call:

>>> scapy = pcapkit.extract('in.pcap', nofile=True, engine='scapy')
>>> reasm = pcapkit.extract('in.pcap', nofile=True, reassembly=True, ipv6=True)
>>> flows = pcapkit.extract('in.pcap', nofile=True, trace=True, tcp=True)
>>> len(flows.trace.tcp)
2

More examples, including the command line interface, are in How to ....

Documentation

The official documentation is the reference. Pages worth knowing by name:

The newest changelog entry is in CHANGELOG.md, which links to the full history, and contribution guidelines are in CONTRIBUTING.md.