Impacket split.py

Back to the category index / Back to the command index

Overview

Reads a pcap file and splits IPv4 TCP traffic into separate files by source and destination.

Item	Details
Implementation	examples/split.py
Category	Packets / ICMP / capture
Size	147 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/split.py <capture.pcap>

It uses only the first positional argument as the input pcap. There is no output path option. It creates one file per connection in the current working directory, using a filename based on the two endpoints: <src-ip>.<src-port>-<dst-ip>.<dst-port>.pcap.

Detailed processing flow

pcapy.open_offline() reads the capture in order. A decoder for its datalink type extracts TCP/IP. The script builds a directional string key and filename from each source/destination endpoint pair, then appends complete capture records for that direction to one pcap file.

How it works

split does not reconstruct TCP byte streams. It distributes packets from a pcap into separate pcap files by connection key. It sets a BPF filter on the input handle: ip proto \tcp. Ethernet and Linux SLL decoders extract IPv4 and TCP headers. The filter excludes non-IPv4 and non-TCP packets.

A connection key is a string joining the source (IP, port) and destination (IP, port) in that order. The Connection class has a __cmp__() intended to treat both directions as equal, but the dictionary actually uses directional strings, not Connection objects, as keys. Thus, on the current Python 3 implementation, outbound and return traffic go to separate files. For a new key, it opens a pcapdumper with an endpoint-ordered filename and writes the original capture header and entire packet unchanged.

It does not reorder sequence numbers, remove retransmissions, reassemble IP fragments or TCP segments, or distinguish generations of the same 4-tuple by session timeout. The output is therefore a collection of packets seen in one direction of the capture, not an application payload file. To combine both directions, create an explicitly order-independent key. Many flows also increase the number of open dumpers, so handle closure and resource limits matter when improving the implementation.

Key implementation elements

Symbol	Location	Where to trace its responsibility
Connection	35	__init__(), getFilename()
Decoder	69	__init__(), start(), packetHandler()
main()	127	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

• The main operation parses local files. Treat input as untrusted: validate offsets, lengths, and format identifiers before accessing data.
• Options may create or update local files. Check how existing files are handled and the permissions on output containing secrets.

Failure paths and cleanup

• Distinguish a missing input file, a damaged file, an incomplete read, and an unsupported format.

When changing the implementation

The code depends on pcapy, EthDecoder, and LinuxSLLDecoder. pcapy is not declared as a direct dependency. Decoder.packetHandler() sorts packets by directional flow; it does not reconstruct TCP streams or resolve retransmissions, missing segments, or out-of-order delivery.

Verification

• Syntax: python -m py_compile examples/split.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.