Pcap Documentation

The libpcap file format is the main capture file format used in TcpDump/WinDump, snort, and many other networking tools. It is fully supported by Wireshark/TShark

This file format is a very basic format to save captured network data. The file consists of a fixed length GlobalHeader followed by multiple Pcap records. Each record consists of a fixed length header followed by a variable length payload.

As there are no offsets or indices, the file has to be loaded one record at a time

The file format is fully documented here https://wiki.wireshark.org/Development/LibpcapFileFormat

Read a Pcap File

Pass in the pcap filename to the Pcap class, then iterate through the pcap object to get the records

Writing a Pcap File

Open the file in mode=’w’. Then each record is written using Pcap.write() and finally close the file using Pcap.close()

Pcap Objects

class AcraNetwork.Pcap.Pcap(filename: str, **kwargs)

Create a new Pcap object with the specified filename. Set the mode to define read, write or append

Parameters:

filename (str) – The PCAP filename

Keyword Arguments:

• mode – r: read w: write a: append

Pcap files look like:

-------------- --------------- ---------------- --------------- ---------------- -------
Global Header | Record Header | Record payload | Record Header | Record payload | .....
-------------- --------------- ---------------- --------------- ---------------- -------

So after opening the file, iterate through the object to read the records

A PCAP file can be opened for reading or writing by specifying mode “r” or “w”, or for append by specifying “a”.

When a PCAP file is open for writing or appending, PcapRecord objects can be written to it.

# Write 10 UDP records to a file # For simplicity use the same MAC, IP and UDP headers in all records >>> headers = (bytes((0x77,0x88,0x99,0xAA,0xBB,0xCC,0x66,0x55,0x44,0x33,0x22,0x11, … 0x08,0x00)) … +bytes((0x45,0x00,0x00,0x36,0x77,0x77,0x40,0x00,0xff,0x11,0x8a,0xa4, … 0x12,0x34,0x56,0x78,0x99,0x88,0x77,0x66)) … +bytes((0x12,0x34,0x56,0x78,0x00,0x22,0x00,0x00)) … ) >>> with Pcap(“_dummy.pcap”, mode=’w’) as p: … r = PcapRecord() … for i in range(10): … start_ch = ord(‘A’) + i … r.payload = headers + bytes((x for x in range(start_ch,start_ch+26))) … p.write(r)

When a PCAP file is open for reading, iterate through the records. >>> with Pcap(“_dummy.pcap”, mode=’r’) as p2: … print(f”{p2.filename} contains {p2.filesize} bytes and is open with mode ‘{p2.mode}’”) … print(f”Network type ID {p2.network}{’ (Ethernet)’ if p2.network==1 else ‘’}”) … for ix, record in enumerate(p2): … print(f”{ix} {record.orig_len} bytes: {record.payload}”) … _dummy.pcap contains 864 bytes and is open with mode ‘r’ Network type ID 1 (Ethernet) 0 68 bytes: b’wˆ™ª»ÌfUD3”E6ww@ÿŠ¤4Vx™ˆwf4Vx"ABCDEFGHIJKLMNOPQRSTUVWXYZ’ 1 68 bytes: b’wˆ™ª»ÌfUD3”E6ww@ÿŠ¤4Vx™ˆwf4Vx"BCDEFGHIJKLMNOPQRSTUVWXYZ[’ 2 68 bytes: b’wˆ™ª»ÌfUD3”E6ww@ÿŠ¤4Vx™ˆwf4Vx"CDEFGHIJKLMNOPQRSTUVWXYZ[' 3 68 bytes: b’wˆ™ª»ÌfUD3”E6ww@ÿŠ¤4Vx™ˆwf4Vx"DEFGHIJKLMNOPQRSTUVWXYZ[]’ 4 68 bytes: b’wˆ™ª»ÌfUD3”E6ww@ÿŠ¤4Vx™ˆwf4Vx"EFGHIJKLMNOPQRSTUVWXYZ[]^’ 5 68 bytes: b’wˆ™ª»ÌfUD3”E6ww@ÿŠ¤4Vx™ˆwf4Vx"FGHIJKLMNOPQRSTUVWXYZ[]^_’ 6 68 bytes: b’wˆ™ª»ÌfUD3”E6ww@ÿŠ¤4Vx™ˆwf4Vx"GHIJKLMNOPQRSTUVWXYZ[]^_`’ 7 68 bytes: b’wˆ™ª»ÌfUD3”E6ww@ÿŠ¤4Vx™ˆwf4Vx"HIJKLMNOPQRSTUVWXYZ[]^_`a’ 8 68 bytes: b’wˆ™ª»ÌfUD3”E6ww@ÿŠ¤4Vx™ˆwf4Vx"IJKLMNOPQRSTUVWXYZ[]^_`ab’ 9 68 bytes: b’wˆ™ª»ÌfUD3”E6ww@ÿŠ¤4Vx™ˆwf4Vx"JKLMNOPQRSTUVWXYZ[]^_`abc’

The pcap can also be treated a list to select the relevant object.

>>> # Create a pcap file
>>> p = Pcap("_dummy.pcap", mode='w')
>>> r = PcapRecord()
>>> r.payload = bytes(1)
>>> p.write(r)
>>> p.close()
>>> # Now open and read it
>>> p2 = Pcap(os.path.join("_dummy.pcap"))
>>> print(p2.network)
1
>>> import struct
>>> for mypcaprecord in p2:
...    (firstbyte,) = struct.unpack(">B", mypcaprecord.payload)
...    print(firstbyte)
0

close()

Close the current pcap file

Return type:

None

write(pcaprecord: PcapRecord)

Write the supplied pcaprecord to the pcap file

Parameters:

pcaprecord (PcapRecord) – The Pcap Record to write

filename: str

The filename of the PCAP file

magic: int

The magic_number which defines the file format. Leave as is.

mode: str

The file reading mode

network: int

Link-layer header type. http://www.tcpdump.org/linktypes.html

sigfigs: int

Set to 0

snaplen: int

snapshot length. Typically unchanged

versionmaj: int

File format major version. Currently 2

versionmin: int

File format minor version. Currently 4

zone: int

The timezone correction in seconds. 0 = GMT

PcapRecord Objects

class AcraNetwork.Pcap.PcapRecord(now=False)

Class that can be used to store one pcap record. A Pcap file contains one or more PcapRecords

pack() → bytes

Pack a PcapRecord into a buffer

Return type:

bytes

set_current_time()

Convienece method to set the time of the PCAP record

Return type:

bool

unpack(buf: bytes) → None

Unpack the pcap header. Pass in a buffer containing the header

incl_len: int

The number of bytes captured and saved in the file

orig_len: int

The number of bytes as appeared on the network when captured

property packet

The payload within the pcap record. Payload is more accurate

Return type:

bytes

property payload

The payload within the pcap record.

Return type:

bytes

sec: int

Second timestamp of the record. Epoch time

usec: int

Microsecond timestamp of the record