For any technical and/or maintenance information, please kindly refer to the Official Documentation.
The PyPCAPKit project is an open source Python program focused on network packet parsing and analysis, which works as a comprehensive PCAP file extraction, construction and analysis library, with DictDumper as its formatted output dumper.
Unlike popular PCAP file extractors such as Scapy,
DPKT and PyShark,
pcapkit is designed to be much more comprehensive: it reports more detailed
information about each packet, and offers a more Pythonic interface to work
with it. When that depth is not what you need, the same interface will also drive
six third-party extraction engines instead.
The whole project supports Python 3.6 or later.
pip install pypcapkitOr 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] # every pure-Python extraFour of the engines need something beyond a pip install -- a tshark binary, a
C compiler, libpcap headers, or an older interpreter -- and all deliberately
excludes both pypcap and pcap-ct, which must never be installed together.
The installation guide
covers every constraint and the reason for it, and pcapkit enforces each one in
code: asking for an engine that cannot run in the current environment warns with
the actual cause and falls back to pcapkit's own parser.
>>> 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 above is from examples/captures/in.pcap, which is committed, so it
is reproducible from a clone.
Reassembly, TCP flow tracing and a different engine are all keyword arguments on 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)
3More worked examples, including the command line interface, are in How to ....
The official documentation is the reference for everything below. The pages worth knowing by name:
| Page | What is in it |
|---|---|
| API reference | Every module, protocol and constant |
| Module structure | What each of the eight subpackages is for |
| Engine comparison | Which engines exist, which Python versions they run on, and measured speed per packet |
| Engine support | What each engine does not support, and how the gap is surfaced |
| Installation | Extras, engine prerequisites and the local development setup |
| Testing | Running the suite, and the sample captures it needs |
| How to ... | Worked examples, library and CLI |
| Extensions | Registering your own protocols, engines and dumpers |
Release history is in CHANGELOG.md, and contribution guidelines are in CONTRIBUTING.md.