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.
Subpackages
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(oryes,trueoron, in any case) to runpcapkitin development mode.See also
- PCAPKIT_VERBOSE¶
Set to
1(oryes,trueoron, in any case) for verbose output.See also
- PCAPKIT_SPHINX¶
Set to
1(oryes,trueoron, 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.