Python: module dshell

dshell (version 3.0) | index /build/dshell/src/dshell/lib/dshell.py

`Dshell base classes`

Modules
`` |  |
dpkt logging | os socket | struct traceback | util

Classes
`` |  | __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) `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 changing duplicate segment handling to always take largest segment` 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 clientclosed, serverclosed: flag indicating if a direction has closed the connection 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` closeIP(self, tuple) `Track if we have seen a FIN packet from given tuple tuple should be of form (ip, port)` connectionClosed(self) 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=None, notfound='--') `Get ASN associated with an IP. Requires GeoIP library (geoip2) and data files.` getGeoIP(self, ip, db=None, notfound='--') `Get country code associated with an IP. Requires GeoIP library (geoip2) and data files.` 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=None, notfound='--') `Get ASN associated with an IP. Requires GeoIP library (geoip2) and data files.` getGeoIP(self, ip, db=None, notfound='--') `Get country code associated with an IP. Requires GeoIP library (geoip2) and data files.` 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=None, notfound='--') `Get ASN associated with an IP. Requires GeoIP library (geoip2) and data files.` getGeoIP(self, ip, db=None, notfound='--') `Get country code associated with an IP. Requires GeoIP library (geoip2) and data files.` 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=None, notfound='--') `Get ASN associated with an IP. Requires GeoIP library (geoip2) and data files.` getGeoIP(self, ip, db=None, notfound='--') `Get country code associated with an IP. Requires GeoIP library (geoip2) and data files.` 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=None, notfound='--') `Get ASN associated with an IP. Requires GeoIP library (geoip2) and data files.` getGeoIP(self, ip, db=None, notfound='--') `Get country code associated with an IP. Requires GeoIP library (geoip2) and data files.` 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=None, notfound='--') `Get ASN associated with an IP. Requires GeoIP library (geoip2) and data files.` getGeoIP(self, ip, db=None, notfound='--') `Get country code associated with an IP. Requires GeoIP library (geoip2) and data files.` 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=None, notfound='--') `Get ASN associated with an IP. Requires GeoIP library (geoip2) and data files.` getGeoIP(self, ip, db=None, notfound='--') `Get country code associated with an IP. Requires GeoIP library (geoip2) and data files.` 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)`

Data
`` |  | __version__ = '3.0'