Skip to content

Reference

simplepcap.parser

This module contains the abstract classes for parsers and parser iterators.

The SomeParser is used to denote the implementation. You should replace it with the name of the parser you want to use.

Main Idea of the Parser is to provide an easy way to iterate over the packets in a pcap file. To ensure safe opening and closing of the file use "with" statement or call the open() and close() methods. (preferred way is to use "with" statement)

Parser(*, file_path)

Bases: Protocol

Abstract class for parsers. Parser is used to iterate over the packets in a pcap file. Parser supports multiple iterators over the same file. Each iterator has its own position in the file.

Attributes:

Name Type Description
file_path Path

Path to the pcap file.
file_header FileHeader

File header.
is_open bool

True if the file is open.
itearators bool

List of iterators over the packets in the file.

Note: When iterator raises StopIteration it is removed from the list.
Example

Note: Replace SomeParser with the name of the parser you want to use.

  1. Recommended way to use the parser is to use "with" statement. When you iterate over the parser it load the packets one by one from the file. 

    from simplepcap.parsers import SomeParser


with SomeParser(file_path="file.pcap") as parser:
    for i, packet in enumerate(parser):
        print(i, packet)

  2. Not recommended way to use the parser is to open and close the file manually. 

    from simplepcap.parsers import SomeParser


parser = SomeParser(file_path="file.pcap")
parser.open()
for packet in parser:
    print(packet)
parser.close()

  3. You can also use the get_all_packets() method to get a list of all packets in the file. 

    from simplepcap.parsers import SomeParser


with SomeParser(file_path="file.pcap") as parser:
    packets = parser.get_all_packets()
for packet in packets:
    print(packet)

  4. Not recommended way to use the parser is to open and close the file manually. 

    from simplepcap.parsers import SomeParser


parser = SomeParser(file_path="file.pcap")
parser.open()
packets = parser.get_all_packets()
parser.close()
for packet in packets:
    print(packet)

  5. Every iterator has its own position in the file. 

    from simplepcap.parsers import SomeParser


with SomeParser(file_path="file.pcap") as parser:
    iter1 = iter(parser)
    iter2 = iter(parser)
    print(next(iter1)) # packet1
    print(next(iter1)) # packet2
    print(next(iter1)) # packet3
    print(next(iter2)) # packet1
    print(next(iter2)) # packet2
    print(next(iter1)) # packet4

    Note: When iterator raises StopIteration it is removed from the list.

Constructor method for Parser.

Parameters:

Name Type Description Default
file_path Path | str

Path to the pcap file.

 required

Raises:

Type Description
PcapFileNotFoundError

if the file does not exist.
WrongFileHeaderError

if the file header is invalid.
UnsupportedFileVersionError

if the file version is not supported.

__iter__() abstractmethod

Return an iterator over the packets in the file.

Raises:

Type Description
FileIsNotOpenError

if the file is not open.

Returns:

Type Description
ParserIterator

Iterator over the packets in the file.

close() abstractmethod

Close the file. This method is not needed if the parser is used as a context manager.

get_all_packets() abstractmethod

Return a list of all packet in the file. This method is not recommended for large files.

open() abstractmethod

Open the file. This method is not needed if the parser is used as a context manager.

ParserIterator

Bases: Protocol

Abstract class for parser iterators. This class is used to iterate over the packets in a pcap file.

Attributes:

Name Type Description
position int

Current position in the file.

__next__() abstractmethod

Return the next packet in the file.

Raises:

Type Description
WrongPacketHeaderError

if the packet header is invalid.
IncorrectPacketSizeError

if the packet size is incorrect.
ReadAfterCloseError

if the file is closed and you try to read a packet from it.
StopIteration

if there are no more packets in the file.

simplepcap.types

FileHeader dataclass

Pcap file header.

Attributes:

Name Type Description
magic int

used to detect the file format itself and the byte ordering. The writing application writes 0xa1b2c3d4 with it's native byte ordering format into this field. The reading application will read either 0xa1b2c3d4 (identical) or 0xd4c3b2a1 (swapped). If the reading application reads the swapped 0xd4c3b2a1 value, it knows that all the following fields will have to be swapped too.

Source
version Version

version of the pcap file format.
reserved Reserved

reserved bytes. Should be 0.
snaplen Reserved

the "snapshot length" for the capture (typically 65535 or even more, but might be limited by the user), see: incl_len vs. orig_len below.

Source
link_type LinkType

link-layer header type, specifying the type of headers at the beginning of the packet (e.g. 1 for Ethernet, see tcpdump.org's link-layer header types page for details); this can be various types such as 802.11, 802.11 with various radio information, PPP, Token Ring, FDDI, etc.

Source

Note: network is a synonym for link_type.

Packet dataclass

Packet.

Attributes:

Name Type Description
header PacketHeader

packet header.
data bytes

packet data.

PacketHeader dataclass

Packet record header.

Attributes:

Name Type Description
timestamp datetime

Seconds and microseconds when this packet was captured.

Source
captured_len int

the number of bytes of packet data actually captured and saved in the file. This value should never become larger than orig_len or the snaplen value of the global header.

Source
original_len int

the length of the packet as it appeared on the network when it was captured. If incl_len and orig_len differ, the actually saved packet size was limited by snaplen.

Source

Reserved dataclass

Reserved bytes. Should be 0.

Attributes:

Name Type Description
reserved1 bytes

not used - SHOULD be filled with 0 by pcap file writers, and MUST be ignored by pcap file readers. This value was documented by some older implementations as "gmt to local correction". Some older pcap file writers stored non-zero values in this field.

Source

Alternatively, the correction time in seconds between GMT (UTC) and the local timezone of the following packet header timestamps. Examples: If the timestamps are in GMT (UTC), thiszone is simply 0. If the timestamps are in Central European time (Amsterdam, Berlin, …) which is GMT + 1:00, thiszone must be -3600. In practice, time stamps are always in GMT, so thiszone is always 0.

Source
reserved2 bytes

not used - SHOULD be filled with 0 by pcap file writers, and MUST be ignored by pcap file readers. This value was documented by some older implementations as "accuracy of timestamps". Some older pcap file writers stored non-zero values in this field.

Source

Alternatively, in theory, the accuracy of time stamps in the capture; in practice, all tools set it to 0.

Source

Version dataclass

Version of the pcap file format.

Attributes:

Name Type Description
major int

an unsigned value, giving the number of the current major version of the format. The value for the current version of the format is 2. This value should change if the format changes in such a way that code that reads the new format could not read the old format (i.e., code to read both formats would have to check the version number and use different code paths for the two formats) and code that reads the old format could not read the new format.

Source
minor int

an unsigned value, giving the number of the current minor version of the format. The value is for the current version of the format is 4. This value should change if the format changes in such a way that code that reads the new format could read the old format without checking the version number but code that reads the old format could not read all files in the new format.

Source

simplepcap.enum

LinkType

Bases: int, Enum

Link Type values.

From www.ietf.org

Exceptions

FileIsNotOpenError(*args, file_path, **kwargs)

Bases: PcapFileError

file_path = file_path instance-attribute
IncorrectPacketSizeError(*args, packet_number, file_path, **kwargs)

Bases: PcapFileError

file_path = file_path instance-attribute
packet_number = packet_number instance-attribute
PcapFileError

Bases: SimplePcapError

Exception raised for errors in the input file.

PcapFileNotFoundError(*args, file_path, **kwargs)

Bases: PcapFileError, FileNotFoundError

file_path = file_path instance-attribute
ReadAfterCloseError(*args, packet_number, file_path, **kwargs)

Bases: PcapFileError

file_path = file_path instance-attribute
packet_number = packet_number instance-attribute
SimplePcapError

Bases: Exception

Base class for exceptions in this module.

UnsupportedFileVersionError(*args, file_path, **kwargs)

Bases: PcapFileError

file_path = file_path instance-attribute
WrongFileHeaderError(*args, file_path, **kwargs)

Bases: PcapFileError

file_path = file_path instance-attribute
WrongPacketHeaderError(*args, packet_number, file_path, **kwargs)

Bases: PcapFileError

file_path = file_path instance-attribute
packet_number = packet_number instance-attribute

Proposed Parser Implementations

Default Parser

Fully Python based parser. This parser will be the default parser for the library.

simplepcap.parsers.default.DefaultParser(*, file_path)

Bases: Parser

simplepcap.parsers.default.DefaultParserIterator(*, file_path, buffered_reader, remove_iterator_callback=None)

Bases: ParserIterator