| |
- __builtin__.object
-
- Data
-
- Blob
- Packet
-
- Connection
- Decoder
-
- IPDecoder
-
- IP6Decoder
- UDPDecoder
-
- TCPDecoder
-
- TCP6Decoder
- UDP6Decoder
class Blob(Data) |
|
a blob containins a contiguous part of the half-stream
Members:
starttime,endtime : start and end timestamps of this blob
direction : direction of this blob's data 'sc' or 'cs'
data(): this blob's data
startoffset,endoffset: offset of this blob start/end in bytes from start of stream |
|
- Method resolution order:
- Blob
- Data
- __builtin__.object
Methods defined here:
- __init__(self, ts, direction, startoffset)
- __iter__(self)
- return each segment data in offset order
for TCP this will return segments ordered but not reassembled
(gaps and overlaps may exist)
for UDP this will return datagrams payloads in capture order,
(very useful for RTP or other streaming protocol.)
- __repr__(self)
- __str__(self)
- returns segments of blob as string
- data(self, errorHandler=None, padding=None, overlap=True, caller=None, dup=-1)
- returns segments of blob reassembled into a string
if next segment offset is not the expected offset
errorHandler(blob,expected,offset) will be called
blob is a reference to the blob
if expected<offset, data is missing
if expected>offset, data is overlapping
else a KeyError will be raised.
if the exception is passed and data is missing
if padding != None it will be used to fill the gap
if segment overlaps existing data
new data is kept if overlap=True
existing data is kept if overlap=False
caller: a ref to the calling object, passed to errorhandler
dup: how to handle duplicate segments:
0: use first segment seen
-1 (default): use last segment seen
- update(self, ts, data, offset=None)
Data and other attributes defined here:
- MAX_OFFSET = 4294967295
Methods inherited from Data:
- __getitem__(self, k)
- __setitem__(self, k, v)
- info(self, *args, **kwargs)
- update/return info stored in this object
data can be passwd as dict(s) or keyword args
- pack(self, fmt, *args)
- packs info keys in args using fmt
- unpack(self, fmt, data, *args)
- unpacks data using fmt to keys listed in args
Data descriptors inherited from Data:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
|
class Connection(Packet) |
|
Connection class is used for tracking all information
contained within an established TCP connection / UDP pseudoconnection
Extends Packet()
Additional members:
{client|server}ip, {client|server}port: aliases of sip,sport,dip,dport
{client|server}countrycode, {client|server}asn: aliases of sip/dip country codes and ASNs
clientpackets, serverpackets: counts of packets from client and server
clientbytes, serverbytes: total bytes from client and server
starttime,endtime: timestamps of start and end (or last packet) time of connection.
direction: indicates direction of last traffic:
'init' : established, no traffic
'cs': client to server
'sc': server to client
state: TCP state of this connection
blobs: array of reassembled half stream blobs
a new blob is started when the direction changes
stop: if True, stopped following stream |
|
- Method resolution order:
- Connection
- Packet
- Data
- __builtin__.object
Methods defined here:
- __init__(self, decoder, addr, ts=None, **kwargs)
- __iter__(self)
- return each blob in capture order
- __repr__(self)
- __str__(self)
- return all data interleaved
- data(self, direction=None, errorHandler=None, padding=None, overlap=True, caller=None)
- returns reassembled half-stream selected by direction 'sc' or 'cs'
if no direction, return all stream data interleaved
see Blob.data() for errorHandler docs
- update(self, ts, direction, data, offset=None)
Data and other attributes defined here:
- MAX_OFFSET = 4294967295
Methods inherited from Data:
- __getitem__(self, k)
- __setitem__(self, k, v)
- info(self, *args, **kwargs)
- update/return info stored in this object
data can be passwd as dict(s) or keyword args
- pack(self, fmt, *args)
- packs info keys in args using fmt
- unpack(self, fmt, data, *args)
- unpacks data using fmt to keys listed in args
Data descriptors inherited from Data:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
|
class Data(__builtin__.object) |
|
base class for data objects (packets,connections, etc..)
these objects hold data (appendable array, typically of strings)
and info members (updateable/accessible as members or as dict via info())
typically one will extend the Data class and replace the data member
and associated functions (update,iter,str,repr) with a data() function
and functions to manipulate the data |
|
Methods defined here:
- __getitem__(self, k)
- __init__(self, *args, **kwargs)
- __iter__(self)
- returns each data element in order added
- __repr__(self)
- __setitem__(self, k, v)
- __str__(self)
- return string built from data
- info(self, *args, **kwargs)
- update/return info stored in this object
data can be passwd as dict(s) or keyword args
- pack(self, fmt, *args)
- packs info keys in args using fmt
- unpack(self, fmt, data, *args)
- unpacks data using fmt to keys listed in args
- update(self, *args, **kwargs)
- updates data (and optionally keyword args)
Data descriptors defined here:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
|
class Decoder(__builtin__.object) |
|
Base class that all decoders will inherit
The Dshell class initializes the decoder to work in the framework
and provides common functions such as CC/ASN lookup
Configuration attributes, settable by Dshell.__init__(attr=value,...) or in subclass __init__:
name: name of this decoder.
description: single-line description of this decoder
longdescription: multi-line description of this decoder
author: who to blame for this decoder
filter: default BPF filter for capture.
format: output format string for this decoder, overrides default for
Please read how text, DB, etc.. Output() classes parse a format string.
optionsdict: optionParser compatible config, specific to decoder
dict of { 'optname':{'default':..., 'help':..., etc...
<destination is auto-filled from optname>},
'optname':... }
'optname' is set by --deodername_optname=... on command line
and under [decodername] section in config file
cleanupinterval - seconds with no activity before state is discarded (default 60)
chainable - set True to indicate this decoder can be chained (can pass output to another decoder)
subDecoder - decoder to pass output to, if not None.
(create new Data objects and call subDecoder.XHandler from XHandler, etc..) |
|
Methods defined here:
- __init__(self, **kwargs)
- __repr__(self)
- __super__(self)
- convenience function to get bound instance of superclass
- alert(self, *args, **kw)
- sends alert to output handler
typically self.alert will be called with the decoded data and the packet/connection info dict last, as follows:
self.alert(alert_arg,alert_arg2...,alert_data=value,alert_data2=value2....,**conn/pkt.info())
example: self.alert(decoded_data,conn.info(),blob.info()) [blob info overrides conn info]
this will pass all information about the decoder, the connection, and the specific event up to the output module
if a positional arg is a dict, it updates the kwargs
if an arg is a list, it extends the arg list
else it is appended to the arg list
all arguments are optional, at the very least you want to pass the **pkt/conn.info() so all traffic info is available.
output modules handle this data as follows:
- the name of the alerting decoder is available in the "decoder" field
- all non-keyword arguments will be concatenated into the "data" field
- keyword arguments, including all provided by .info() will be used to populate matching fields
- remaining keyword arguments that do not match fields will be represented by "key=value" strings
concatenated together into the "extra" field
- cleanConnectionStore(self)
- cleans connection store of all information, flushing out data
- cleanup(self, ts)
- if cleanup interval expired, close connections not updated in last interval
- close(self, conn, ts=None)
- for connection based decoders
close and discard the connection object
- debug(self, msg)
- logs msg at debug level
- decode(self, *args, **kw)
- # we get the raw output from pcapy as header, data
- dump(self, *args, **kw)
- write packet data (probably to the PCAP writer if present)
- error(self, msg)
- logs msg at error level
- find(self, addr, state=None)
- getASN(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- getGeoIP(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- log(self, msg, level=20)
- logs msg at specified level (default of INFO is for -v/--verbose output)
- parseArgs(self, args, options={})
- called to parse command-line arguments and cli/config file options
if options dict contains 'all' or the decoder name as a key
class members will be updated from value
- parseOptions(self, options={})
- option keys:values will set class members (self.key=value)
if key is in optiondict
- postFile(self)
- postModule(self)
- postModule is called after capture stops
default postModule, prints basic decoding stats
- preFile(self)
- preModule(self)
- preModule is called before capture starts
default preModule, dumps object data to debug
- stop(self, conn)
- stop following connection
handlers will not be called, except for connectionCloseHandler
- track(self, addr, data=None, ts=None, offset=None, **kwargs)
- connection tracking for TCP and UDP
finds or creates connection based on addr
updates connection with data if provided (using offset to reorder)
tracks timestamps if ts provided
extra args get passed to new connection objects
- warn(self, msg)
- logs msg at warning level
- write(self, obj, **kw)
- write session data
Data descriptors defined here:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
|
class IP6Decoder(IPDecoder) |
| |
- Method resolution order:
- IP6Decoder
- IPDecoder
- Decoder
- __builtin__.object
Methods inherited from IPDecoder:
- IPHandler(self, addr, pkt, ts, **kwargs)
- called if packet is IPv4/IPv6
check packets using filterfn here
- __init__(self, **kwargs)
- ipdefrag(self, pkt)
- ip fragment reassembly
- rawHandler(self, pktlen, pkt, ts, **kwargs)
- takes ethernet data and determines if it contains IP or IP6.
defragments IPv4
if 6to4, unencaps the IPv6
If IP/IP6, hands off to IPDecoder via IPHandler()
Data and other attributes inherited from IPDecoder:
- IP_PROTO_MAP = {0: 'IP', 1: 'ICMP', 6: 'TCP', 17: 'UDP', 41: 'IP6', 58: 'ICMP6'}
Methods inherited from Decoder:
- __repr__(self)
- __super__(self)
- convenience function to get bound instance of superclass
- alert(self, *args, **kw)
- sends alert to output handler
typically self.alert will be called with the decoded data and the packet/connection info dict last, as follows:
self.alert(alert_arg,alert_arg2...,alert_data=value,alert_data2=value2....,**conn/pkt.info())
example: self.alert(decoded_data,conn.info(),blob.info()) [blob info overrides conn info]
this will pass all information about the decoder, the connection, and the specific event up to the output module
if a positional arg is a dict, it updates the kwargs
if an arg is a list, it extends the arg list
else it is appended to the arg list
all arguments are optional, at the very least you want to pass the **pkt/conn.info() so all traffic info is available.
output modules handle this data as follows:
- the name of the alerting decoder is available in the "decoder" field
- all non-keyword arguments will be concatenated into the "data" field
- keyword arguments, including all provided by .info() will be used to populate matching fields
- remaining keyword arguments that do not match fields will be represented by "key=value" strings
concatenated together into the "extra" field
- cleanConnectionStore(self)
- cleans connection store of all information, flushing out data
- cleanup(self, ts)
- if cleanup interval expired, close connections not updated in last interval
- close(self, conn, ts=None)
- for connection based decoders
close and discard the connection object
- debug(self, msg)
- logs msg at debug level
- decode(self, *args, **kw)
- # we get the raw output from pcapy as header, data
- dump(self, *args, **kw)
- write packet data (probably to the PCAP writer if present)
- error(self, msg)
- logs msg at error level
- find(self, addr, state=None)
- getASN(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- getGeoIP(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- log(self, msg, level=20)
- logs msg at specified level (default of INFO is for -v/--verbose output)
- parseArgs(self, args, options={})
- called to parse command-line arguments and cli/config file options
if options dict contains 'all' or the decoder name as a key
class members will be updated from value
- parseOptions(self, options={})
- option keys:values will set class members (self.key=value)
if key is in optiondict
- postFile(self)
- postModule(self)
- postModule is called after capture stops
default postModule, prints basic decoding stats
- preFile(self)
- preModule(self)
- preModule is called before capture starts
default preModule, dumps object data to debug
- stop(self, conn)
- stop following connection
handlers will not be called, except for connectionCloseHandler
- track(self, addr, data=None, ts=None, offset=None, **kwargs)
- connection tracking for TCP and UDP
finds or creates connection based on addr
updates connection with data if provided (using offset to reorder)
tracks timestamps if ts provided
extra args get passed to new connection objects
- warn(self, msg)
- logs msg at warning level
- write(self, obj, **kw)
- write session data
Data descriptors inherited from Decoder:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
|
class IPDecoder(Decoder) |
|
extend IP6Decoder to capture IPv4 and IPv6 data
(but does basic IPv4 defragmentation)
config:
l2decoder: dpkt class for layer-2 decoding (Ethernet)
striplayers: strip n layers above layer-2, removes PPP/PPPoE encap, IP-over-IP, etc.. (0)
defrag: defragment IPv4 (True)
v6only: if True, will ignore IPv4 data. (False)
decode6to4: if True, will decode IPv6-over-IP, if False will treat as IP (True)
filterfn: lambda function that accepts addr 2x2tuples and returns if packet should pass (addr:True)
filterfn is required for IPv6 as port-based BPF filters don't work,
so keep your BPF to 'tcp' or 'udp' and set something like
self.filterfn = lambda ((sip,sp),(dip,dp)): (sp==53 or dp==53) |
|
- Method resolution order:
- IPDecoder
- Decoder
- __builtin__.object
Methods defined here:
- IPHandler(self, addr, pkt, ts, **kwargs)
- called if packet is IPv4/IPv6
check packets using filterfn here
- __init__(self, **kwargs)
- ipdefrag(self, pkt)
- ip fragment reassembly
- rawHandler(self, pktlen, pkt, ts, **kwargs)
- takes ethernet data and determines if it contains IP or IP6.
defragments IPv4
if 6to4, unencaps the IPv6
If IP/IP6, hands off to IPDecoder via IPHandler()
Data and other attributes defined here:
- IP_PROTO_MAP = {0: 'IP', 1: 'ICMP', 6: 'TCP', 17: 'UDP', 41: 'IP6', 58: 'ICMP6'}
Methods inherited from Decoder:
- __repr__(self)
- __super__(self)
- convenience function to get bound instance of superclass
- alert(self, *args, **kw)
- sends alert to output handler
typically self.alert will be called with the decoded data and the packet/connection info dict last, as follows:
self.alert(alert_arg,alert_arg2...,alert_data=value,alert_data2=value2....,**conn/pkt.info())
example: self.alert(decoded_data,conn.info(),blob.info()) [blob info overrides conn info]
this will pass all information about the decoder, the connection, and the specific event up to the output module
if a positional arg is a dict, it updates the kwargs
if an arg is a list, it extends the arg list
else it is appended to the arg list
all arguments are optional, at the very least you want to pass the **pkt/conn.info() so all traffic info is available.
output modules handle this data as follows:
- the name of the alerting decoder is available in the "decoder" field
- all non-keyword arguments will be concatenated into the "data" field
- keyword arguments, including all provided by .info() will be used to populate matching fields
- remaining keyword arguments that do not match fields will be represented by "key=value" strings
concatenated together into the "extra" field
- cleanConnectionStore(self)
- cleans connection store of all information, flushing out data
- cleanup(self, ts)
- if cleanup interval expired, close connections not updated in last interval
- close(self, conn, ts=None)
- for connection based decoders
close and discard the connection object
- debug(self, msg)
- logs msg at debug level
- decode(self, *args, **kw)
- # we get the raw output from pcapy as header, data
- dump(self, *args, **kw)
- write packet data (probably to the PCAP writer if present)
- error(self, msg)
- logs msg at error level
- find(self, addr, state=None)
- getASN(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- getGeoIP(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- log(self, msg, level=20)
- logs msg at specified level (default of INFO is for -v/--verbose output)
- parseArgs(self, args, options={})
- called to parse command-line arguments and cli/config file options
if options dict contains 'all' or the decoder name as a key
class members will be updated from value
- parseOptions(self, options={})
- option keys:values will set class members (self.key=value)
if key is in optiondict
- postFile(self)
- postModule(self)
- postModule is called after capture stops
default postModule, prints basic decoding stats
- preFile(self)
- preModule(self)
- preModule is called before capture starts
default preModule, dumps object data to debug
- stop(self, conn)
- stop following connection
handlers will not be called, except for connectionCloseHandler
- track(self, addr, data=None, ts=None, offset=None, **kwargs)
- connection tracking for TCP and UDP
finds or creates connection based on addr
updates connection with data if provided (using offset to reorder)
tracks timestamps if ts provided
extra args get passed to new connection objects
- warn(self, msg)
- logs msg at warning level
- write(self, obj, **kw)
- write session data
Data descriptors inherited from Decoder:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
|
class Packet(Data) |
|
metadata class for connectionless data
Members:
sip, sport, dip, dport : source ip and port, dest ip and port
addr : ((sip,sport),(dip,dport)) tuple. sport/dport will be None if N/A
sipcc, dipcc, sipasn, dipasn : country codes and ASNs for source and dest IPs
ts : datetime.datetime() UTC timestamp of packet. use util.mktime(ts) to get POSIX timestamp
pkt : raw packet data
any additional args will be added to info dict |
|
- Method resolution order:
- Packet
- Data
- __builtin__.object
Methods defined here:
- __init__(self, decoder, addr, ts=None, pkt=None, **kwargs)
- __iter__(self)
- __repr__(self)
- __str__(self)
Methods inherited from Data:
- __getitem__(self, k)
- __setitem__(self, k, v)
- info(self, *args, **kwargs)
- update/return info stored in this object
data can be passwd as dict(s) or keyword args
- pack(self, fmt, *args)
- packs info keys in args using fmt
- unpack(self, fmt, data, *args)
- unpacks data using fmt to keys listed in args
- update(self, *args, **kwargs)
- updates data (and optionally keyword args)
Data descriptors inherited from Data:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
|
class TCP6Decoder(TCPDecoder) |
| |
- Method resolution order:
- TCP6Decoder
- TCPDecoder
- UDPDecoder
- IPDecoder
- Decoder
- __builtin__.object
Methods inherited from TCPDecoder:
- IPHandler(self, addr, pkt, ts, **kwargs)
- IPv4 dispatch
- TCP(self, addr, tcp, ts, **kwargs)
- TCP dispatch
- __init__(self, **kwargs)
Methods inherited from UDPDecoder:
- UDP(self, addr, data, pkt, ts=None, **kwargs)
- will call self.packetHandler(udp=Packet(),data=data)
(see Packet() for Packet object common attributes)
udp.pkt will contain the raw IP data
data will contain the decoded UDP payload
State tracking:
only if connectionHandler or blobHandler is present
and packetHandler is not present
UDPDecoder will call:
self.connectionInitHandler(conn=Connection())
when UDP state is established
(see Connection() for Connection object attributes)
self.blobHandler(conn=Connection(),blob=Blob())
when stream direction switches (if following stream)
blob=(see Blob() objects)
self.connectionHandler(conn=Connection())
when UDP state is flushed (if following stream)
state is flushed when stale or when maxblobs is exceeded
if maxblobs exceeded, current data will go into new connection
self.connectionCloseHandler(conn=Connection())
when state is discarded (always)
Methods inherited from IPDecoder:
- ipdefrag(self, pkt)
- ip fragment reassembly
- rawHandler(self, pktlen, pkt, ts, **kwargs)
- takes ethernet data and determines if it contains IP or IP6.
defragments IPv4
if 6to4, unencaps the IPv6
If IP/IP6, hands off to IPDecoder via IPHandler()
Data and other attributes inherited from IPDecoder:
- IP_PROTO_MAP = {0: 'IP', 1: 'ICMP', 6: 'TCP', 17: 'UDP', 41: 'IP6', 58: 'ICMP6'}
Methods inherited from Decoder:
- __repr__(self)
- __super__(self)
- convenience function to get bound instance of superclass
- alert(self, *args, **kw)
- sends alert to output handler
typically self.alert will be called with the decoded data and the packet/connection info dict last, as follows:
self.alert(alert_arg,alert_arg2...,alert_data=value,alert_data2=value2....,**conn/pkt.info())
example: self.alert(decoded_data,conn.info(),blob.info()) [blob info overrides conn info]
this will pass all information about the decoder, the connection, and the specific event up to the output module
if a positional arg is a dict, it updates the kwargs
if an arg is a list, it extends the arg list
else it is appended to the arg list
all arguments are optional, at the very least you want to pass the **pkt/conn.info() so all traffic info is available.
output modules handle this data as follows:
- the name of the alerting decoder is available in the "decoder" field
- all non-keyword arguments will be concatenated into the "data" field
- keyword arguments, including all provided by .info() will be used to populate matching fields
- remaining keyword arguments that do not match fields will be represented by "key=value" strings
concatenated together into the "extra" field
- cleanConnectionStore(self)
- cleans connection store of all information, flushing out data
- cleanup(self, ts)
- if cleanup interval expired, close connections not updated in last interval
- close(self, conn, ts=None)
- for connection based decoders
close and discard the connection object
- debug(self, msg)
- logs msg at debug level
- decode(self, *args, **kw)
- # we get the raw output from pcapy as header, data
- dump(self, *args, **kw)
- write packet data (probably to the PCAP writer if present)
- error(self, msg)
- logs msg at error level
- find(self, addr, state=None)
- getASN(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- getGeoIP(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- log(self, msg, level=20)
- logs msg at specified level (default of INFO is for -v/--verbose output)
- parseArgs(self, args, options={})
- called to parse command-line arguments and cli/config file options
if options dict contains 'all' or the decoder name as a key
class members will be updated from value
- parseOptions(self, options={})
- option keys:values will set class members (self.key=value)
if key is in optiondict
- postFile(self)
- postModule(self)
- postModule is called after capture stops
default postModule, prints basic decoding stats
- preFile(self)
- preModule(self)
- preModule is called before capture starts
default preModule, dumps object data to debug
- stop(self, conn)
- stop following connection
handlers will not be called, except for connectionCloseHandler
- track(self, addr, data=None, ts=None, offset=None, **kwargs)
- connection tracking for TCP and UDP
finds or creates connection based on addr
updates connection with data if provided (using offset to reorder)
tracks timestamps if ts provided
extra args get passed to new connection objects
- warn(self, msg)
- logs msg at warning level
- write(self, obj, **kw)
- write session data
Data descriptors inherited from Decoder:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
|
class TCPDecoder(UDPDecoder) |
|
IPv6 TCP/UDP decoder
reassembles TCP and UDP streams
For TCP and UDP (if no packetHandler)
self.connectionInitHandler(conn=Connection())
when TCP connection is established
(see Connection() for Connection object attributes)
self.blobHandler(conn=Connection(),blob=Blob())
when stream direction switches (if following stream)
blob=(see Blob() objects)
self.connectionHandler(conn=Connection())
when connection closes (if following stream)
self.connectionCloseHandler(conn=Connection())
when connection closes (always)
For UDP only:
self.packetHandler(udp=Packet(),data=data)
with every packet
data=decoded UDP data
if packetHandler is present, it will be called only for UDP (and UDP will not be tracked) |
|
- Method resolution order:
- TCPDecoder
- UDPDecoder
- IPDecoder
- Decoder
- __builtin__.object
Methods defined here:
- IPHandler(self, addr, pkt, ts, **kwargs)
- IPv4 dispatch
- TCP(self, addr, tcp, ts, **kwargs)
- TCP dispatch
- __init__(self, **kwargs)
Methods inherited from UDPDecoder:
- UDP(self, addr, data, pkt, ts=None, **kwargs)
- will call self.packetHandler(udp=Packet(),data=data)
(see Packet() for Packet object common attributes)
udp.pkt will contain the raw IP data
data will contain the decoded UDP payload
State tracking:
only if connectionHandler or blobHandler is present
and packetHandler is not present
UDPDecoder will call:
self.connectionInitHandler(conn=Connection())
when UDP state is established
(see Connection() for Connection object attributes)
self.blobHandler(conn=Connection(),blob=Blob())
when stream direction switches (if following stream)
blob=(see Blob() objects)
self.connectionHandler(conn=Connection())
when UDP state is flushed (if following stream)
state is flushed when stale or when maxblobs is exceeded
if maxblobs exceeded, current data will go into new connection
self.connectionCloseHandler(conn=Connection())
when state is discarded (always)
Methods inherited from IPDecoder:
- ipdefrag(self, pkt)
- ip fragment reassembly
- rawHandler(self, pktlen, pkt, ts, **kwargs)
- takes ethernet data and determines if it contains IP or IP6.
defragments IPv4
if 6to4, unencaps the IPv6
If IP/IP6, hands off to IPDecoder via IPHandler()
Data and other attributes inherited from IPDecoder:
- IP_PROTO_MAP = {0: 'IP', 1: 'ICMP', 6: 'TCP', 17: 'UDP', 41: 'IP6', 58: 'ICMP6'}
Methods inherited from Decoder:
- __repr__(self)
- __super__(self)
- convenience function to get bound instance of superclass
- alert(self, *args, **kw)
- sends alert to output handler
typically self.alert will be called with the decoded data and the packet/connection info dict last, as follows:
self.alert(alert_arg,alert_arg2...,alert_data=value,alert_data2=value2....,**conn/pkt.info())
example: self.alert(decoded_data,conn.info(),blob.info()) [blob info overrides conn info]
this will pass all information about the decoder, the connection, and the specific event up to the output module
if a positional arg is a dict, it updates the kwargs
if an arg is a list, it extends the arg list
else it is appended to the arg list
all arguments are optional, at the very least you want to pass the **pkt/conn.info() so all traffic info is available.
output modules handle this data as follows:
- the name of the alerting decoder is available in the "decoder" field
- all non-keyword arguments will be concatenated into the "data" field
- keyword arguments, including all provided by .info() will be used to populate matching fields
- remaining keyword arguments that do not match fields will be represented by "key=value" strings
concatenated together into the "extra" field
- cleanConnectionStore(self)
- cleans connection store of all information, flushing out data
- cleanup(self, ts)
- if cleanup interval expired, close connections not updated in last interval
- close(self, conn, ts=None)
- for connection based decoders
close and discard the connection object
- debug(self, msg)
- logs msg at debug level
- decode(self, *args, **kw)
- # we get the raw output from pcapy as header, data
- dump(self, *args, **kw)
- write packet data (probably to the PCAP writer if present)
- error(self, msg)
- logs msg at error level
- find(self, addr, state=None)
- getASN(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- getGeoIP(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- log(self, msg, level=20)
- logs msg at specified level (default of INFO is for -v/--verbose output)
- parseArgs(self, args, options={})
- called to parse command-line arguments and cli/config file options
if options dict contains 'all' or the decoder name as a key
class members will be updated from value
- parseOptions(self, options={})
- option keys:values will set class members (self.key=value)
if key is in optiondict
- postFile(self)
- postModule(self)
- postModule is called after capture stops
default postModule, prints basic decoding stats
- preFile(self)
- preModule(self)
- preModule is called before capture starts
default preModule, dumps object data to debug
- stop(self, conn)
- stop following connection
handlers will not be called, except for connectionCloseHandler
- track(self, addr, data=None, ts=None, offset=None, **kwargs)
- connection tracking for TCP and UDP
finds or creates connection based on addr
updates connection with data if provided (using offset to reorder)
tracks timestamps if ts provided
extra args get passed to new connection objects
- warn(self, msg)
- logs msg at warning level
- write(self, obj, **kw)
- write session data
Data descriptors inherited from Decoder:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
|
class UDP6Decoder(UDPDecoder) |
| |
- Method resolution order:
- UDP6Decoder
- UDPDecoder
- IPDecoder
- Decoder
- __builtin__.object
Methods inherited from UDPDecoder:
- IPHandler(self, addr, pkt, ts, **kwargs)
- IPv4 dispatch, hands address, UDP payload and packet up to UDP callback
- UDP(self, addr, data, pkt, ts=None, **kwargs)
- will call self.packetHandler(udp=Packet(),data=data)
(see Packet() for Packet object common attributes)
udp.pkt will contain the raw IP data
data will contain the decoded UDP payload
State tracking:
only if connectionHandler or blobHandler is present
and packetHandler is not present
UDPDecoder will call:
self.connectionInitHandler(conn=Connection())
when UDP state is established
(see Connection() for Connection object attributes)
self.blobHandler(conn=Connection(),blob=Blob())
when stream direction switches (if following stream)
blob=(see Blob() objects)
self.connectionHandler(conn=Connection())
when UDP state is flushed (if following stream)
state is flushed when stale or when maxblobs is exceeded
if maxblobs exceeded, current data will go into new connection
self.connectionCloseHandler(conn=Connection())
when state is discarded (always)
- __init__(self, **kwargs)
Methods inherited from IPDecoder:
- ipdefrag(self, pkt)
- ip fragment reassembly
- rawHandler(self, pktlen, pkt, ts, **kwargs)
- takes ethernet data and determines if it contains IP or IP6.
defragments IPv4
if 6to4, unencaps the IPv6
If IP/IP6, hands off to IPDecoder via IPHandler()
Data and other attributes inherited from IPDecoder:
- IP_PROTO_MAP = {0: 'IP', 1: 'ICMP', 6: 'TCP', 17: 'UDP', 41: 'IP6', 58: 'ICMP6'}
Methods inherited from Decoder:
- __repr__(self)
- __super__(self)
- convenience function to get bound instance of superclass
- alert(self, *args, **kw)
- sends alert to output handler
typically self.alert will be called with the decoded data and the packet/connection info dict last, as follows:
self.alert(alert_arg,alert_arg2...,alert_data=value,alert_data2=value2....,**conn/pkt.info())
example: self.alert(decoded_data,conn.info(),blob.info()) [blob info overrides conn info]
this will pass all information about the decoder, the connection, and the specific event up to the output module
if a positional arg is a dict, it updates the kwargs
if an arg is a list, it extends the arg list
else it is appended to the arg list
all arguments are optional, at the very least you want to pass the **pkt/conn.info() so all traffic info is available.
output modules handle this data as follows:
- the name of the alerting decoder is available in the "decoder" field
- all non-keyword arguments will be concatenated into the "data" field
- keyword arguments, including all provided by .info() will be used to populate matching fields
- remaining keyword arguments that do not match fields will be represented by "key=value" strings
concatenated together into the "extra" field
- cleanConnectionStore(self)
- cleans connection store of all information, flushing out data
- cleanup(self, ts)
- if cleanup interval expired, close connections not updated in last interval
- close(self, conn, ts=None)
- for connection based decoders
close and discard the connection object
- debug(self, msg)
- logs msg at debug level
- decode(self, *args, **kw)
- # we get the raw output from pcapy as header, data
- dump(self, *args, **kw)
- write packet data (probably to the PCAP writer if present)
- error(self, msg)
- logs msg at error level
- find(self, addr, state=None)
- getASN(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- getGeoIP(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- log(self, msg, level=20)
- logs msg at specified level (default of INFO is for -v/--verbose output)
- parseArgs(self, args, options={})
- called to parse command-line arguments and cli/config file options
if options dict contains 'all' or the decoder name as a key
class members will be updated from value
- parseOptions(self, options={})
- option keys:values will set class members (self.key=value)
if key is in optiondict
- postFile(self)
- postModule(self)
- postModule is called after capture stops
default postModule, prints basic decoding stats
- preFile(self)
- preModule(self)
- preModule is called before capture starts
default preModule, dumps object data to debug
- stop(self, conn)
- stop following connection
handlers will not be called, except for connectionCloseHandler
- track(self, addr, data=None, ts=None, offset=None, **kwargs)
- connection tracking for TCP and UDP
finds or creates connection based on addr
updates connection with data if provided (using offset to reorder)
tracks timestamps if ts provided
extra args get passed to new connection objects
- warn(self, msg)
- logs msg at warning level
- write(self, obj, **kw)
- write session data
Data descriptors inherited from Decoder:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
|
class UDPDecoder(IPDecoder) |
|
extend UDPDecoder to decode UDP optionally track state
config if tracking state with connectionHandler or blobHandler
maxblobs - if tracking state, max blobs to track before flushing
swaplowport - when establishing state, swap source/dest so dest has low port
cleanupinterval - seconds with no activity before state is discarded (default 60) |
|
- Method resolution order:
- UDPDecoder
- IPDecoder
- Decoder
- __builtin__.object
Methods defined here:
- IPHandler(self, addr, pkt, ts, **kwargs)
- IPv4 dispatch, hands address, UDP payload and packet up to UDP callback
- UDP(self, addr, data, pkt, ts=None, **kwargs)
- will call self.packetHandler(udp=Packet(),data=data)
(see Packet() for Packet object common attributes)
udp.pkt will contain the raw IP data
data will contain the decoded UDP payload
State tracking:
only if connectionHandler or blobHandler is present
and packetHandler is not present
UDPDecoder will call:
self.connectionInitHandler(conn=Connection())
when UDP state is established
(see Connection() for Connection object attributes)
self.blobHandler(conn=Connection(),blob=Blob())
when stream direction switches (if following stream)
blob=(see Blob() objects)
self.connectionHandler(conn=Connection())
when UDP state is flushed (if following stream)
state is flushed when stale or when maxblobs is exceeded
if maxblobs exceeded, current data will go into new connection
self.connectionCloseHandler(conn=Connection())
when state is discarded (always)
- __init__(self, **kwargs)
Methods inherited from IPDecoder:
- ipdefrag(self, pkt)
- ip fragment reassembly
- rawHandler(self, pktlen, pkt, ts, **kwargs)
- takes ethernet data and determines if it contains IP or IP6.
defragments IPv4
if 6to4, unencaps the IPv6
If IP/IP6, hands off to IPDecoder via IPHandler()
Data and other attributes inherited from IPDecoder:
- IP_PROTO_MAP = {0: 'IP', 1: 'ICMP', 6: 'TCP', 17: 'UDP', 41: 'IP6', 58: 'ICMP6'}
Methods inherited from Decoder:
- __repr__(self)
- __super__(self)
- convenience function to get bound instance of superclass
- alert(self, *args, **kw)
- sends alert to output handler
typically self.alert will be called with the decoded data and the packet/connection info dict last, as follows:
self.alert(alert_arg,alert_arg2...,alert_data=value,alert_data2=value2....,**conn/pkt.info())
example: self.alert(decoded_data,conn.info(),blob.info()) [blob info overrides conn info]
this will pass all information about the decoder, the connection, and the specific event up to the output module
if a positional arg is a dict, it updates the kwargs
if an arg is a list, it extends the arg list
else it is appended to the arg list
all arguments are optional, at the very least you want to pass the **pkt/conn.info() so all traffic info is available.
output modules handle this data as follows:
- the name of the alerting decoder is available in the "decoder" field
- all non-keyword arguments will be concatenated into the "data" field
- keyword arguments, including all provided by .info() will be used to populate matching fields
- remaining keyword arguments that do not match fields will be represented by "key=value" strings
concatenated together into the "extra" field
- cleanConnectionStore(self)
- cleans connection store of all information, flushing out data
- cleanup(self, ts)
- if cleanup interval expired, close connections not updated in last interval
- close(self, conn, ts=None)
- for connection based decoders
close and discard the connection object
- debug(self, msg)
- logs msg at debug level
- decode(self, *args, **kw)
- # we get the raw output from pcapy as header, data
- dump(self, *args, **kw)
- write packet data (probably to the PCAP writer if present)
- error(self, msg)
- logs msg at error level
- find(self, addr, state=None)
- getASN(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- getGeoIP(self, ip, db=[], notfound='--')
- Get record associated with an IP
requires GeoIP
- log(self, msg, level=20)
- logs msg at specified level (default of INFO is for -v/--verbose output)
- parseArgs(self, args, options={})
- called to parse command-line arguments and cli/config file options
if options dict contains 'all' or the decoder name as a key
class members will be updated from value
- parseOptions(self, options={})
- option keys:values will set class members (self.key=value)
if key is in optiondict
- postFile(self)
- postModule(self)
- postModule is called after capture stops
default postModule, prints basic decoding stats
- preFile(self)
- preModule(self)
- preModule is called before capture starts
default preModule, dumps object data to debug
- stop(self, conn)
- stop following connection
handlers will not be called, except for connectionCloseHandler
- track(self, addr, data=None, ts=None, offset=None, **kwargs)
- connection tracking for TCP and UDP
finds or creates connection based on addr
updates connection with data if provided (using offset to reorder)
tracks timestamps if ts provided
extra args get passed to new connection objects
- warn(self, msg)
- logs msg at warning level
- write(self, obj, **kw)
- write session data
Data descriptors inherited from Decoder:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
| |