unixdump
"tcpdump for unix domain sockets"
unixdump is a powerful command-line Unix domain socket "packet" capturer. It
is an eBPF-based kernel tracing tool that extracts, processes, and dumps all
data sent over unix domain sockets across an entire Linux host with support
for performant in-kernel filters for a wide range of filtering granularity. It
enables manual traffic inspection of Unix socket traffic between processes,
including ancillary data, such as file descriptors and Unix credentials.
Installation
BCC
unixdump depends on the BCC eBPF tracing tool framework. See the
BCC install instructions
for your distribution. We recommend building and installing BCC from
source.
Note: While BCC updates may result in breakages, the current version of
unixdump is known to work with version 0.24.0
on Ubuntu 20.04 when using clang/llvm 10 from https://apt.llvm.org/ (bcc's
build hardcodes llvm 10 paths). If you are having issues with unixdump,
please make sure you are not running an out-of-date version of BCC (such as if
you installed the Ubuntu packages).
unixdump
Via pip
sudo -H pip3 install unixdump
From source
sudo python3 setup.py install
or
python3 setup.py bdist_wheel
sudo -H pip3 install ./dist/unixdump-*.whl
Usage
unixdump is best used with filters. Several of the important ones are defined
below, and the rest can be listed with --help. To dump all Unix
domain socket traffic of a system (sans the terminal process rendering the
output), run unixdump without any arguments:
Note: unixdump requires CAP_SYS_ADMIN privileges and full access to
sysfs/debugfs.
sudo unixdump
For an example use case, let's say we know the program creates a Unix domain
socket with random characters that begins with /tmp/domain-socket-. We can
limit our output to only sockets beginning with that string:
sudo unixdump -b -s '/tmp/domain-socket'
The output can be further restricted using combinations of unixdump filter
options.
Options
unixdump provides many different arguments to filter output and fine tune
performance. Below are some of the more notable options:
-
-s, --socket: When the user knows the exact name of the socket path, this is the option to use. By specifying an empty string like so-s '',unixdumpwill filter on unnamed sockets. -
-@, --base64: To filter on binary abstract namespace keys, this option instructsunixdumpto parse the-b/-soptions as base64. -
-b, --beginswith: One ofunixdump's most useful filters is to match starting sequences of socket paths. This proves extremely helpful when the program creates socket paths ending with random characters yet the beginning is unique and constant. This makes filtering possible without knowing the entire socket name ahead of time. -
-p, --pid: To home in on a specific process (and anything communicating with it), use this option. -
-x, --exclude: For when the user is listening for general traffic and wants to hide noisy processes such asXorg. This argument takes a space separated list ofpidsto exclude. -
-t, --excludeownterminal: (requireswmctrl) Attempts to exclude the current terminal process from capture. Currently supports Wayland and X11, and thetmuxandscreenterminal multiplexers.
Note: screen is not currently supported on Wayland -
-l, --ancillarydata: For those who want to only watch for traffic containing ancillary data. This will provide the file descriptors or Unix credentials that were sent. -
-o, --dir: To save output into separate files based onpidpairs. The option-c, --colorcan also be set to add color like in wireshark. -
-B, --extract: Extract the buffer contents from a file saved by--dirand output it to binary in separate client and server files.
Metadata
Release files for unixdump 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| unixdump-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for unixdump-1.2.0-py3-none-any.whl |
Release files / unixdump-1.2.0-py3-none-any.whl
| Download URL | unixdump-1.2.0-py3-none-any.whl |
|---|---|
| Size | 31.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dd08c6d4b89f8efae251fae47d172557ae59a71d1c518c02fd885789ec9bb767
|
|
BLAKE2b-256 checksum How to use checksums |
ab013ab4ce80f04ab8aabf64b41bdbed262997c14d55c0e33f4eb60c611a4506
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.0 CPython/3.9.12
|
Security for unixdump 1.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.