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 aPCapStream
, 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 throughPCapPacketHeader.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.pcapAnd 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.
- format – Output filename in
-
close
()¶ Closes this :class:
PCapStream
by closing the underlying Python stream.
-
write
(bytes, header=None)¶ Writes packet
bytes
and the optional pcap packetheader
.If the pcap packet
header
is not specified, one will be generated based on the number of packetbytes
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 theread()
,write()
, andclose()
methods. Binary mode is assumed for this module, so the “b” is not required when callingopen()
.If the optiontal
rollover
parameter is True, aPCapRolloverStream
is created instead. In that casefilename
is treated as astrftime(3)
format string andnbytes
,npackets
,nseconds
, anddryrun
parameters may also be specified. See :class:PCapRolloverStream
for more information.NOTE:
PCapRolloverStream
is always opened in write mode (“wb”) and supports onlywrite()
andclose()
, notread()
.
-
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 thestrftime(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.