packetlogic2.pldb.connlog

This module contains functionality for reading the connection log from the PacketLogic system.

Do NOT import this module directly. The PLConnection object should be used, e.g:

>>> import packetlogic2
>>> pl = packetlogic2.connect("192.168.1.25", "admin", "password")
>>> cl = pl.ConnLog()

Classes defined here:

ConnLog - This resource will allow you to search the connectionlog (if enabled in the

ConnLog

This resource will allow you to search the connectionlog (if enabled in the system).

Inherits from: Resource

Methods:
Ungrouped		list_services(self, day) List all services seen on specified day
Ungrouped	`list` of `dict`	search(self, timefr, timeto, server=None, serverport=None, client=None, clientport=None, service=None, serverhostname=None, protocol=None, endtimefr=None, endtimeto=None, netobject=None, natclient=None, natclientport=None, natserver=None, natserverport=None, max_hits=50, offset=0, callback=None) Search the connection log with parameters
Inherited from Resource		close(self) Immediately disconnects the resource
		commit(self, message='PythonAPI commit') Store the current transaction to the database
		ping(self, string='') Send a command to server to test if it is up
	`tuple` of (`str`, `int`)	protocol(self, protocol, strict=False) Translate protocol name OR number to tuple with name AND number
	`dict` of `str`:`int` and `int`:`str`	protocols_dict(self) Returns a dictionary with name:nr and nr:name items for IP protocols
		rollback(self) Abort the current transaction and discard the data
		services_cmd(self, services=[], props=[]) Send services to pldbd
	`list` of `str`	services_list(self) List all services
	`list` of `str`	services_prop_list(self) List all properties
		wait_for_commit(self, pinginterval=60) Wait for new data to be committed on resource
	`list` of `str`	xfb_flags_list(self) List all XFB (Transfer Behaviour) flags, that can be used in FlagObjects

Properties:
commitid	The CommitID associated with this session

close(self)

Immediately disconnects the resource.

After this method has been called this object becomes useless.

It may be used to force a disconnect when the garbage collector can't be trusted to do a timely disconnect.

commit(self, message='PythonAPI commit')

Store the current transaction to the database.

When you do this PacketLogic will reload the ruleset. This will take a lot of CPU resources from the system, try to do this in batches.

Observe that if you don't commit the changes you've made, no other resource (including the client) will see your changes.

Parameters:

message (str) - Message recorded in the commit log. Ignored in v12.1 and earlier.

message parameter is ignored in v12.1 firmware and earlier.

list_services(self, day)

List all services seen on specified day.

>>> cl.list_services("2009-12-24")
['Diablo 2',
 'HTTP',
 'Microsoft Online Crash Analysis',
 'World of Warcraft login',
 'Flash audio over HTTP',
 'OCSP over HTTP',
 'Internet Key Exchange',
 'HTTP media stream',
 'IMAP4']

Parameters:

day (str) - Day to list services for, in the format 'YYYY-MM-DD'

list_services method requires v12.2 firmware or newer.

ping(self, string='')

Send a command to server to test if it is up.

protocol(self, protocol, strict=False)

Translate protocol name OR number to tuple with name AND number. Can be used to e.g translate numerical protocol in connlog.search() result to protocol name.

An unknown protocol will be translated to e.g '#7' or -1, unless strict is set to True, in which case ValueError is raised for unknown protocols.

Returns:

Tuple with name and nr of specified protocol.
tuple of (str, int)

Parameters:

protocol (int, str or a ProtocolObject Item) - Name or number of an IP protocol

strict (bool) - If True, ValueError is raised for an unknown protocol, if False (default), an unknown protocol translates to number -1 or name '#7' (where 7 is the supplied unknown protocol number).

protocols_dict(self)

Returns a dictionary with name:nr and nr:name items for IP protocols. Can be used to e.g translate numerical protocol in connlog.search() result to protocol name.

Returns:

Dict with name:nr and nr:name items for IP protocols.
dict of str:int and int:str

rollback(self)

Abort the current transaction and discard the data.

This will also automatically happen if your connection drops or that you exit the program without commit.

Exceptions raised:

resource.PLDBError - If the rollback command failed.

search(self, timefr, timeto, server=None, serverport=None, client=None, clientport=None, service=None, serverhostname=None, protocol=None, endtimefr=None, endtimeto=None, netobject=None, natclient=None, natclientport=None, natserver=None, natserverport=None, max_hits=50, offset=0, callback=None)

Search the connection log with parameters. All parameters except timefr and timeto can be omitted, which will evaluate to "any". You must specify at least one other search criteria though.

Time is specified as the local time on the PacketLogic system. The 'time' item in the returned dictionary is a unix timestamp adjusted for the timezone on the PacketLogic system, to get a python timetuple representing the PacketLogic systems local time convert it (despite the misleading function name) with: pl_local_time_tuple = time.gmtime(connlog_data['time'])

>>> cl.search("2005-12-19 10:00", "2005-12-20 12:04", service="http", max_hits=3)
[{'client': '10.2.20.75',
  'client_port': 3429,
  'protocol': 6,
  'server': '194.14.70.50',
  'server_port': 80,
  'serverhostname': 'www.svt.se',
  'service': 'http',
  'time': 1135033194},
 {'client': '10.2.95.71',
  'client_port': 1958,
  'protocol': 6,
  'server': '70.85.224.194',
  'server_port': 80,
  'serverhostname': 'www.dumpalink.com',
  'service': 'http',
  'time': 1135033194},
 {'client': '10.2.20.75',
  'client_port': 3430,
  'protocol': 6,
  'server': '194.14.70.50',
  'server_port': 80,
  'serverhostname': 'www.svt.se',
  'service': 'http',
  'time': 1135033194}]

Returns:

A list of hits unless callback is set.
list of dict

Parameters:

timefr (str or datetime.date or datetime.datetime) - Search for connections beginning at specified date or later. The date has to be in YYYY-MM-DD HH:MM or YYYY-MM-DD format, time default to 00:00.

timeto (str or datetime.date or datetime.datetime) - Search for connections beginning at specified date or earlier. The date has to be in YYYY-MM-DD HH:MM or YYYY-MM-DD format, time default to 00:00.

endtimefr (str or datetime.date or datetime.datetime) - Search for connections ending at specified date or later. The date has to be in YYYY-MM-DD HH:MM or YYYY-MM-DD format, time default to 00:00. Requires firmware v12.2 or newer.

endtimeto (str or datetime.date or datetime.datetime) - Search for connections ending at specified date or earlier. The date has to be in YYYY-MM-DD HH:MM or YYYY-MM-DD format, time default to 00:00. Requires firmware v12.2 or newer.

server (str) - The servers ip address.

serverport (int) - The server port.

client (str) - The clients ip address

clientport (int) - client port.

service (str) - a string with the name of the service (e.g. FTP or FTP transfer)

serverhostname (str) - the hostname of the server, this only works on protocols where the serverhostname is extractedlike HTTP.

protocol (int) - The IP protocol used. (6=TCP)

netobject (str) - Visible netobject that the local host of the connection appeared in. Requires firmware v12.2 or newer.

natserver (str) - The servers post NAT ip address. Requires firmware v15.0 or newer.

natserverport (int) - The servers post NAT port. Requires firmware v15.0 or newer.

natclient (str) - The clients post NAT ip address Requires firmware v15.0 or newer.

natclientport (int) - The clients post NAT port. Requires firmware v15.0 or newer.

max_hits (int) - Number of answers you want.

offset (int) - Start on this number of answers .. (i.e. if you set max_hits to 50 and offset to 50 you will get answers between 50 and 100)

callback (callable) - Optional function to be called for each chunk of data received instead of returning a list.

Exceptions raised:

ValueError - If search criteria is missing.

PLDBUnsupportedFeatureError - If 'connlog' feature is disabled (See ruleset.Ruleset.features_get()).

PLDBUnsupportedInFirmware - If endtimefr/endtimeto arguments are used withoutfirmware support.

endtimefr/endtimeto parameters require v12.2 firmware or newer.

natserver/natserverport/natclient/natclientport parameters require v15.0 firmware or newer.

services_cmd(self, services=[], props=[])

Send services to pldbd

Sets stringtable for services and properties. Do NOT use this unless you know exactly what you are doing.

Parameters:

services (list of str) - List of services

props (list of str) - List of service properties

services_list(self)

List all services

Returns:

List of services
list of str

services_prop_list(self)

List all properties.

Returns:

List of service properties
list of str

wait_for_commit(self, pinginterval=60)

Wait for new data to be committed on resource.

This method returns as soon as the server signals that another client has committed new data to the resource. It also periodically tests the connection to the server. If connection is broken (or any other error happens) an exception is raised.

Parameters:

pinginterval (int) - Interval used to check if connection still is alive.

xfb_flags_list(self)

List all XFB (Transfer Behaviour) flags, that can be used in FlagObjects.

Returns:

List of XFB flags
list of str

commitid

The CommitID associated with this session. (14.0 or newer only)