Impacket sniff.py

Back to the category index / Back to the command index

Overview

Captures packets with libpcap, then decodes and displays them according to their link-layer format.

Item	Details
Implementation	examples/sniff.py
Category	Packets / ICMP / capture
Size	112 lines
Distribution	Installed as a script through scripts=examples/*.py in setup.py

CLI and input

This older sample does not handle -h. Check its usage message and top-level sys.argv handling.

python examples/sniff.py [BPF filter ...]

It joins all arguments with spaces and passes them to pcapy.setfilter(). With no arguments, the filter is empty, so all packets are included. The interface is not an argument: the user selects it interactively from a list obtained through pcap.

Detailed processing flow

The script lists available interfaces for selection and opens a capture handle with pcapy.open_live(). DecoderThread receives packet callbacks, builds a protocol tree with a decoder for the pcap datalink type, and displays it.

How it works

pcapy.open_live() creates a libpcap capture handle for the selected interface. It receives packets with a snaplen of 1500, non-promiscuous mode, and a short read timeout. The remaining CLI text becomes a BPF expression for the kernel/libpcap filter, so only packets that pass the filter reach the Python callback.

The first header in the captured bytes depends on the interface’s datalink type. The code selects EthDecoder for Ethernet or LinuxSLLDecoder for Linux cooked captures. The decoder then builds a child hierarchy such as Ethernet/SLL to IP to TCP. A fixed IP decoder would be wrong because link-layer headers vary in length and format.

DecoderThread runs pcap.loop(0, callback) until stopped and immediately displays each packet in human-readable form. It does not save capture files, reconstruct flows, or reassemble packets. Maintenance improvements include reporting unknown datalink types, callback exceptions, and lost interfaces rather than silently ending the thread, and adding explicit stop and handle-close paths.

Key implementation elements

Symbol	Location	Where to trace its responsibility
DecoderThread	40	__init__(), run(), packetHandler()
getInterface()	66	Module function
main()	91	Module function

Dependencies

Within Impacket

Module	Main names used
impacket	version
impacket.ImpactDecoder	EthDecoder, LinuxSLLDecoder

External packages (used directly)

Import name	Distribution package	Import path and declaration status
pcapy	pcapy	Imported directly; not declared as a direct dependency

Output, side effects, and required privileges

• Performs network probing or live packet capture. Check the send and receive scope, interface, filters, and handling of captured data.
• Starts a listening socket or long-running loop. Check the bind address, port, stop method, and shared state across concurrent connections.
• Raw socket or packet capture privileges may be required. Captured data may include third-party traffic.

Failure paths and cleanup

• Ensure stop requests, client disconnections, partial reads or writes, and worker exceptions do not leave the listener in an inconsistent state.

When changing the implementation

The code depends on pcapy, EthDecoder, LinuxSLLDecoder, and threading. pcapy is not declared as a direct project dependency. When changing the code, check capture privileges, snaplen, promiscuous mode, and unknown link types.

Verification

• Syntax: python -m py_compile examples/sniff.py
• CLI: Use a subprocess to check the usage message and exit code with no or too few arguments.
• No test specific to this command was found. Choose shared-module tests and, if needed, a run in an isolated environment.