API

class fparser.FParser

__init__(source, is_file = False, flow_timeout = 600, fin_timeout = 30, filter = "ip", snaplen = 100, log_level = syslog.LOG_ERR, tcp_callback = None, udp_callback = None, kill_callback = None)

An FParser object is a single instance of the parser. It is either offline or online. The online (default) variant will keep running and consuming flows until the FParser object exits from scope and is no longer refrenced from anywhere else or is explicitly killed. The offline variant will keep running until the source is exhausted. Note that when sniffing on a live interface the python process will need the required priviledges (i.e. to be run as root or as a user that is allowed to put the interface in promiscous mode).

Parameters:

• source (str) – Where to sniff packets from. Can be either an interface name or a file name. If it is a file name is_file must be set to True. Cannot be None.
• is_file (boolean) – Does the source argument refer to a file or to an interface name. This determines whether the parser runs online or offline.
• flow_timeout (int) – The timeout in seconds to wait before considering a flow dead (if no FIN is seen)
• fin_timeout (int) – The timeout in seconds to wait before considering a flow dead (FIN is seen)
• filter (str) – BPF to apply to the capture
• snaplen (int) – How many bytes to capture from each packet. Should be large enough to include headers.
• log_level (syslog.X) – How much logging output should the parser generate. The logging output is printed to stdout.
• tcp_callback (callable) – A callable to call when a TCP flow terminates. The callable should take one argument (the flow).
• udp_callback (callable) – A callable to call when a UDP flow terminates. Tha callable should take one argument (the flow).
• kill_callback (callable) – A callable to call when the parser is killed. This can happen either explicitly or when the source is exhausted. The callable should take no arguments.

stop()

Kills the parser. After this method is called the object cannot be used anymore.

set_tcp_callback(tcp_callback)

Sets or resets the TCP flow callback.

Parameters:tcp_callback (callable) – A callable to call when a TCP flow terminates. The callable should take one argument (the flow).

set_udp_callback(udp_callback)

Sets or resets the UDP flow callback.

Parameters:udp_callback (callable) – A callable to call when a UDP flow terminates. The callable should take one argument (the flow).

flow_iter()

Returns an iterator over the flows currently active in this parser. The iterator can be used in a for loop to iterate over the flows.

find_tcp_flow(src_ip, sport, dest_ip, dport)

Finds a currently active TCP flow with given network and transport layer identifiers. Much faster than iterating over all flows when there are lots of flows.

Parameters:

• src_ip (str) – The source IP address of the flow
• sport (int) – The TCP source port
• dest_ip (str) – The destination IP address of the flow
• dport (int) – The TCP destination port

find_udp_flow(src_ip, sport, dest_ip, dport)

Finds a currently active UDP flow with given network and transport layer identifiers. Much faster than iterating over all flows when there are lots of flows.

Parameters:

• src_ip (str) – The source IP address of the flow
• sport (int) – The UDP source port
• dest_ip (str) – The destination IP address of the flow
• dport (int) – The UDP destination port

get_info()

Get information about the parser

Returns:an FParserInfo containing information for this parser. Return type:FParserInfo

class fparser.FParserInfo

An immutable class that carries information about a running FParser instance.

avg_pps

The average number of packets per second seen by the parser

tcp_flows

The number of active TCP flows

udp_flows

The number of active UDP flows

tcp_pkts

The number of TCP packets stored

udp_pkts

The number of UDP packets stored

time_collecting

Time spent collecting. A collection is initiated periodically and “reaps” all the flows that are deemed timed out or terminated.