pcapng.structs¶
Module providing facilities for handling struct-like data.
-
pcapng.structs.
read_int
(stream, size, signed=False, endianness='=')[source]¶ Read (and decode) an integer number from a binary stream.
Parameters: - stream – an object providing a
read()
method - size – the size, in bits, of the number to be read. Supported sizes are: 8, 16, 32 and 64 bits.
- signed – Whether a signed or unsigned number is required.
Defaults to
False
(unsigned int). - endianness – specify the endianness to use to decode the number,
in the same format used by Python
struct
module. Defaults to ‘=’ (native endianness). ‘!’ means “network” endianness (big endian), ‘<’ little endian, ‘>’ big endian.
Returns: the read integer number
- stream – an object providing a
-
pcapng.structs.
read_section_header
(stream)[source]¶ Read a section header block from a stream.
Note
The byte order magic will be removed from the returned data This is ok as we don’t need it anymore once we determined the correct endianness of the section.
Returns: a dict containing the 'endianness'
and'data'
keys that will be used to construct aSectionHeader
instance.
-
pcapng.structs.
read_block_data
(stream, endianness)[source]¶ Read block data from a stream.
Each “block” is in the form:
- 32bit integer indicating the size (including header and size)
- block payload (the above-specified number of bytes minus 12)
- 32bit integer indicating the size (again)
Parameters: - stream – the stream from which to read data
- endianness – Endianness marker, one of ‘<’, ‘>’, ‘!’, ‘=’.
-
pcapng.structs.
read_bytes
(stream, size)[source]¶ Read the given amount of raw bytes from a stream.
Parameters: - stream – the stream from which to read data
- size – the size to read, in bytes
Returns: the read data
Raises: StreamEmpty
if zero bytes were readRaises: TruncatedFile
if 0 < bytes < size were read
-
pcapng.structs.
read_bytes_padded
(stream, size, pad_block_size=4)[source]¶ Read the given amount of bytes from a stream, plus read and discard any necessary extra byte to align up to the pad_block_size-sized next block.
Parameters: - stream – the stream from which to read data
- size – the size to read, in bytes
Returns: the read data
Raises: StreamEmpty
if zero bytes were readRaises: TruncatedFile
if 0 < bytes < size were read
-
class
pcapng.structs.
RawBytes
(size)[source]¶ Field containing a fixed-width amount of raw bytes
Parameters: size – field size, in bytes
-
class
pcapng.structs.
IntField
(size, signed=False)[source]¶ Field containing an integer number.
Parameters: - size – number size, in bits. Currently supported are 8, 16, 32 and 64-bit integers
- signed – whether the number is a signed or unsigned integer. Defaults to False (unsigned)
-
class
pcapng.structs.
OptionsField
(options_schema)[source]¶ Field containing some options.
Parameters: options_schema – Same as the schema
parameter toOptions
class constructor.
-
class
pcapng.structs.
PacketDataField
[source]¶ Field containing some “packet data”, used in the Packet and EnhancedPacket blocks.
The packet data is composed of three fields (returned in a tuple):
- captured len (uint32)
- packet len (uint32)
- packet data (captured_len-sized binary data)
-
class
pcapng.structs.
SimplePacketDataField
[source]¶ Field containing packet data from a SimplePacket object.
The packet data is represented by two fields (returned as a tuple):
- packet_len (uint32)
- packet_data (packet_len-sized binary data)
-
class
pcapng.structs.
ListField
(subfield)[source]¶ A list field is a variable amount of fields of some other type. Used for packets containing multiple “items”, such as
NameResolution
.It will keep loading data using a subfield until a
StreamEmpty
excaption is raised, indicating we reached the end of data (note that a sub-field might even “simulate” a stream end once it reaches some end marker in the file).Values are returned in a list.
Parameters: subfield – a StructField
sub-class instance to be used to read values from the stream.
-
class
pcapng.structs.
NameResolutionRecordField
[source]¶ A name resolution record field contains an item of data used in the
NameResolution
block.it is composed of three fields:
- record type (uint16)
- record length (uint16)
- payload
Accepted types are:
0x00
- end marker0x01
- ipv4 address resolution0x02
- ipv6 address resolution
In both cases, the payload is composed of a valid address in the selected IP version, followed by domain name up to the field end.
-
pcapng.structs.
read_options
(stream, endianness)[source]¶ Read “options” from an “options block” in a stream, until a
StreamEmpty
exception is caught, or an end marker is reached.Each option is composed by:
- option_code (uint16)
- value_length (uint16)
- value (value_length-sized binary data)
The end marker is simply an option with code
0x0000
and no payload
-
class
pcapng.structs.
Options
(schema, data, endianness)[source]¶ Wrapper object used to easily access the contents of an “options” field.
Fields can be accessed either by numerical id or by name (if one was specified in the schema).
Note
When iterating the object (or calling
keys()
/iterkeys()
/viewkeys()
) string keys will be returned if possible in place of numeric keys. (The purpose of this is to achieve better readability, for example, when converting to a dictionary).Parameters: - schema –
Definition of the known options: a list of 2- or 3-tuples (the third argument is optional) representing, respectively, the numeric option code, the option name and the value type.
The following value types are currently supported:
string
: convert value to a unicode string, using utf-8 encoding{u,i}{8,16,32,64}
: (un)signed integer of the specified lengthipv4
: a single ipv4 address [4 bytes]ipv4+mask
: an ipv4 address followed by a netmask [8 bytes]ipv6
: a single ipv6 address [16 bytes]ipv6+prefix
: an ipv6 address followed by prefix length [17 bytes]macaddr
: a mac address [6 bytes]euiaddr
: a eui address [8 bytes]
- data – Initial data for the options. A list of two-tuples:
(code, value)
. Items with the same code may be repeated; only the first one will be accessible using subscriptoptions[code]
; the others can be accessed usingget_all()
and related methods - endianness – The current endianness of the section these options came from. Required in order to load numeric fields.
- schema –
-
pcapng.structs.
struct_decode
(schema, stream, endianness='=')[source]¶ Decode structured data from a stream, following a schema.
Parameters: - schema – a list of two tuples:
``(name, field)
, wherename
is a string representing the attribute name, andfield
is an instance of aStructField
sub-class, providing a.load()
method to be called on the stream to get the field value. - stream – a file-like object, providing a
.read()
method, from which data will be read. - endianness – endianness specifier, as accepted by Python struct module
(one of
<>!=
, defaults to=
).
Returns: a dictionary mapping the field names to decoded data
- schema – a list of two tuples:
-
pcapng.structs.
struct_encode
(schema, obj, outstream, endianness='=')[source]¶ In the future, this function will be used to encode a structure into a stream. For the moment, it just raises
NotImplementedError
.
-
pcapng.structs.
struct_decode_string
(schema, data)[source]¶ Utility function to pass a string to
struct_decode()
-
pcapng.structs.
struct_encode_string
(schema, obj)[source]¶ Utility function to pass a string to
struct_encode()
and get the result back as a bytes string.