Module Documentation

pcapkit is an independent open source library, using DictDumper as its formatted output dumper.

Unlike Scapy, DPKT and PyShark, pcapkit aims to support each protocol in full, options and parameters included, so it carries the protocols’ enumeration registries, independent schema definitions and customisable interfaces.

Package Metadata

pcapkit.__version__ = '1.6.1.post1'

version number

See also

Release Process, on how the release pipeline bumps and reads it.

Library Index

pcapkit.all gathers the public names of the pcapkit subpackages in one namespace – pcapkit.const as a module, and pcapkit.vendor not at all – with the third-party engines’ pcapkit.toolkit helpers prefixed by engine, such as scapy_packet2dict.

Command Line Tool

Note

The emoji package (the cli extra) decorates the -v output. Without it, importing the module warns with EmojiWarning and the CLI prints plain text.

pcapkit.__main__ provides the CLI, merged in from the deprecated jspcapy project.

usage: pcapkit-cli [-h] [-V] [-o file-name] [-f format] [-j] [-p] [-t] [-a]
                   [-v] [-F] [-E PKG] [-P PROTOCOL] [-L LAYER] [-B]
                   [-O file-name]
                   input-file-name

PCAP file extractor and formatted dumper

positional arguments:
  input-file-name       The name of the input PCAP or PCAP-NG file. With
                        `--auto-extension`, ".pcap" is appended unless its
                        extension is already ".pcap", ".cap" or ".pcapng". Use
                        "-" to read from standard input.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -o, --output file-name
                        The name of the output report file. If it is omitted,
                        "out" is used. With `--auto-extension`, the extension
                        of the output format (e.g. ".json") is appended if
                        absent. With `--files`, the directory each frame's
                        report is written to.
  -f, --format format   The format of the report: "json", "plist" (or "xml"),
                        "tree" (or "text", "txt") or "pcap" (or "cap"). Takes
                        precedence over `--json`, `--plist` and `--tree`. With
                        no format option, "tree" is used.
  -j, --json            Write the report as JSON, as `--format json` does.
                        Ignored if `--format` is given.
  -p, --plist           Write the report as a macOS property list, as
                        `--format plist` does. Ignored if `--format` or
                        `--json` is given.
  -t, --tree            Write the report as tree view text, as `--format tree`
                        does; this is the default. Ignored if `--format`,
                        `--json` or `--plist` is given.
  -a, --auto-extension  Append missing file extensions: ".pcap" to the input
                        file name, and the extension of the output format
                        (e.g. ".json") to the output file name unless
                        `--files` is set.
  -v, --verbose         Print the input name, the protocol chain of each
                        frame, and where the report is stored.
  -F, --files           Write a report file per frame, in the directory named
                        by `--output`.
  -E, --engine PKG      The extraction engine, case-insensitive: "default" (or
                        "pcapkit"), or a third-party one such as "dpkt" or
                        "scapy", which needs its package installed. An unknown
                        or unavailable engine falls back to "default".
  -P, --protocol PROTOCOL
                        Stop dissecting each frame after this protocol, e.g.
                        "IPv4" (case-insensitive); the rest of the frame is
                        kept as raw data. Third-party engines ignore it.
  -L, --layer LAYER     Stop dissecting each frame after its protocol in this
                        layer: "link", "internet", "transport" or
                        "application" (case-insensitive); "none", the default,
                        sets no limit. Third-party engines ignore it.
  -B, --buffer-save     Save a copy of the input to a file as it is read. Only
                        an input that is not seekable, such as a pipe on
                        standard input, is saved.
  -O, --buffer-path file-name
                        The name of the file `--buffer-save` writes. If it is
                        omitted, a temporary file is used and then deleted.

Changed in version 1.5.0: -P and -L stop the extraction where they say, which 1.4.x ignored, and -L accepts only link, internet, transport, application or none, in any case (#356).

Environment Variables

PCAPKIT_DEVMODE

Set to 1 (or yes, true or on, in any case) to run pcapkit in development mode.

PCAPKIT_VERBOSE

Set to 1 (or yes, true or on, in any case) for verbose output.

PCAPKIT_SPHINX

Set to 1 (or yes, true or on, in any case) for the extra typing hints and docstrings the Sphinx build reads.

pcapkit.utilities.config reads the PCAPKIT_* tunable limits, such as FRAME_LAYER_LIMIT, and lists each with its default, range and risks. pcapkit.vendor.default reads the crawlers’ PCAPKIT_VENDOR_RETRY, PCAPKIT_CI_MODE, PCAPKIT_HTTP_PROXY and PCAPKIT_HTTPS_PROXY, listed under Environment Variables.

Changed in version 1.5.0: PCAPKIT_HTTP_PROXY and PCAPKIT_HTTPS_PROXY are documented with pcapkit.vendor.default rather than here, and are still read on every request. The tunable limits are new as variables (#1726). A bad value of PCAPKIT_DEVMODE, PCAPKIT_VERBOSE, PCAPKIT_SPHINX, PCAPKIT_CI_MODE or PCAPKIT_VENDOR_RETRY warns with ConfigWarning instead of being taken silently, or, for PCAPKIT_VENDOR_RETRY, crashing the import.