ait.core.pcap module

This module, pcap.py, is a library to read/write PCAP-formatted files with simple open, read, write, close functions

class ait.core.pcap.PCapFileStats(nbytes=None, npackets=None, nseconds=None)

Bases: object

Current and threshold and statistics in PCapRolloverStream

__init__(nbytes=None, npackets=None, nseconds=None)

x.__init__(…) initializes x; see help(type(x)) for signature

nbytes
npackets
nseconds
class ait.core.pcap.PCapGlobalHeader(stream=None)

Represents a PCap global header. See:

__init__(stream=None)

Creates a new PCapGlobalHeader with default values. If a stream is given, the global header data is read from it.

incomplete()

Indicates whether or not this PCapGlobalHeader is incomplete.

read(stream)

Reads PCapGlobalHeader data from the given stream.

class ait.core.pcap.PCapPacketHeader(stream=None, swap=None, orig_len=0, maxlen=65535)

Represents a PCap packet header. See:

__init__(stream=None, swap=None, orig_len=0, maxlen=65535)

Creates a new PCapPacketHeader with default values. If a stream is given, the packet header data is read from it.

incomplete()

Indicates whether or not this PCapGlobalHeader is incomplete.

read(stream)

Reads PCapPacketHeader data from the given stream.

timestamp

Packet timestamp as a Python Datetime object

ts

Packet timestamp as a float, a combination of ts_sec and ts_usec

class ait.core.pcap.PCapRolloverStream(format, nbytes=None, npackets=None, nseconds=None, dryrun=False)

Wraps a PCapStream to rollover to a new filename, based on packet times, file size, or number of packets.

__init__(format, nbytes=None, npackets=None, nseconds=None, dryrun=False)

Creates a new PCapRolloverStream with the given thresholds.

A PCapRolloverStream behaves like a PCapStream, except that writing a new packet will cause the current file to be closed and a new file to be opened when one or more of thresholds (nbytes, npackets, nseconds) is exceeded.

The new filename is determined by passing the format string through PCapPacketHeader.timestamp.strftime() for the first packet in the file.

When segmenting based on time (nseconds), for file naming and interval calculation purposes ONLY, the timestamp of the first packet in the file is rounded down to nearest even multiple of the number of seconds. This yields nice round number timestamps for filenames. For example:

PCapRolloverStream(format=”%Y%m%dT%H%M%S.pcap”, nseconds=3600)

If the first packet written to a file has a time of 2017-11-23 19:28:58, the file will be named:

20171123T190000.pcap

And a new file will be started when a packet is written with a timestamp that exceeds 2017-11-23 19:59:59.

Parameters:
  • format – Output filename in strftime(3) format
  • nbytes – Rollover after writing nbytes
  • npackets – Rollover after writing npackets
  • nseconds – Rollover after nseconds have elapsed between the first and last packet timestamp in the file.
  • dryrun – Simulate file writes and output log messages.
close()

Closes this :class:PCapStream by closing the underlying Python stream.

write(bytes, header=None)

Writes packet bytes and the optional pcap packet header.

If the pcap packet header is not specified, one will be generated based on the number of packet bytes and current time.

rollover

Indicates whether or not its time to rollover to a new file.

class ait.core.pcap.PCapStream(stream, mode='rb')

PCapStream is the primary class of the pcap.py module. It exposes open(), read(), write(), and close() methods to read and write pcap-formatted files.

See:

__init__(stream, mode='rb')

Creates a new PCapStream, which wraps the underlying Python stream, already opened in the given mode.

close()

Closes this PCapStream by closing the underlying Python stream.

next()

Returns the next header and packet from this PCapStream. See read().

read()

Reads a single packet from the this pcap stream, returning a tuple (PCapPacketHeader, packet)

write(bytes, header=None)

write() is meant to work like the normal file write(). It takes two arguments, a byte array to write to the file as a single PCAP packet, and an optional header if one already exists. The length of the byte array should be less than 65535 bytes. write() returns the number of bytes actually written to the file.

ait.core.pcap.open(filename, mode='r', **options)

Returns an instance of a PCapStream class which contains the read(), write(), and close() methods. Binary mode is assumed for this module, so the “b” is not required when calling open().

If the optiontal rollover parameter is True, a PCapRolloverStream is created instead. In that case filename is treated as a strftime(3) format string and nbytes, npackets, nseconds, and dryrun parameters may also be specified. See :class:PCapRolloverStream for more information.

NOTE: PCapRolloverStream is always opened in write mode (“wb”) and supports only write() and close(), not read().

ait.core.pcap.query(starttime, endtime, output=None, *filenames)

Given a time range and input file, query creates a new file with only that subset of data. If no outfile name is given, the new file name is the old file name with the time range appended.

Args:
starttime:
The datetime of the beginning time range to be extracted from the files.
endtime:
The datetime of the end of the time range to be extracted from the files.
output:
Optional: The output file name. Defaults to [first filename in filenames][starttime]-[endtime].pcap
filenames:
A tuple of one or more file names to extract data from.
ait.core.pcap.segment(filenames, format, **options)

Segment the given pcap file(s) by one or more thresholds (nbytes, npackets, nseconds). New segment filenames are determined based on the strftime(3) format string and the timestamp of the first packet in the file.

Parameters:
  • filenames – Single filename (string) or list of filenames
  • format – Output filename in strftime(3) format
  • nbytes – Rollover after writing N bytes
  • npackets – Rollover after writing N packets
  • nseconds – Rollover after N seconds have elapsed between the first and last packet timestamp in the file.
  • dryrun – Simulate file writes and output log messages.
ait.core.pcap.times(filenames, tolerance=2)

For the given file(s), return the time ranges available. Tolerance sets the number of seconds between time ranges. Any gaps larger than tolerance seconds will result in a new time range.

Parameters:
  • filenames – Single filename (string) or list of filenames
  • tolerance – Maximum seconds between contiguous time ranges
Returns:

A dictionary keyed by filename, with each value a list

of (start, stop) time ranges for that file.