identities module

The identities module is part of the nmeta suite

It provides an abstraction for participants (identities), using a MongoDB database for storage and data retention maintenance.

Identities are identified via TBD....

There are methods (see class docstring) that provide harvesting of identity metadata and various retrieval searches

class identities.Identities(config, policy, secondary=0)

Bases: baseclass.BaseClass

An object that represents identity metadata

Main function used to harvest identity metadata: (assumes class instantiated as an object called ‘ident’)

ident.harvest(pkt, flow.packet)

Passed a raw packet and packet metadata from flow object. Check a packet_in event and harvest any relevant identity indicators to metadata

Functions available for Classifiers: (assumes class instantiated as an object called ‘ident’)

ident.findbymac(mac_address)

Look up identity object for a MAC address

ident.findbynode(host_name)

Look up identity object by host name (aka node) Additionally, can set:

regex=True Treat service_name as a regular expression harvest_type= Specify what type of harvest (i.e. DHCP)

ident.findbyservice(service_name)

Look up identity object by service name Additionally, can set:

regex=True Treat service_name as a regular expression harvest_type= Specify what type of harvest (i.e. DNS_A) ip_address= Look for specific IP address

See function docstrings for more information

class Identity

Bases: object

An object that represents an individual Identity Indicator

dbdict()

Return a dictionary object of identity metadata parameters for storing in the database

class DHCPMessage

Bases: object

An object that represents an individual DHCP message. Used for storing DHCP state by recording DHCP events

dbdict()

Return a dictionary object of dhcp message parameters for storing in the database

harvest(pkt, flow_pkt)

Passed a raw packet and packet metadata from flow object. Check a packet_in event and harvest any relevant identity indicators to metadata

harvest_arp(pkt, flow_pkt)

Harvest ARP identity metadata into database. Passed packet-in metadata from flow object. Check ARP reply and harvest identity indicators to metadata

harvest_dhcp(flow_pkt)

Harvest DHCP identity metadata into database. Passed packet-in metadata from flow object. Check LLDP TLV fields and harvest any relevant identity indicators to metadata

harvest_lldp(flow_pkt)

Harvest LLDP identity metadata into database. Passed packet-in metadata from flow object. Check LLDP TLV fields and harvest any relevant identity indicators to metadata

harvest_dns(flow_pkt)

Harvest DNS identity metadata into database. Passed packet-in metadata from flow object. Check DNS answer(s) and harvest any relevant identity indicators to metadata

findbymac(mac_addr, test=0)

Passed a MAC address and reverse search identities collection returning first match as a dictionary version of an Identity class, or empty dictionary if not found

Setting test=1 returns database query execution statistics

findbynode(host_name, harvest_type='any', regex=False, test=0)

Find by node name Pass it the name of the node to search for. Additionally, can set:

regex=True Treat service_name as a regular expression harvest_type= Specify what type of harvest (i.e. DHCP)

Returns a dictionary version of an Identity class, or 0 if not found

Setting test=1 returns database query execution statistics

findbyservice(service_name, harvest_type='any', regex=False, ip_address='any', test=0)

Find by service name Pass it the name of the service to search for. Additionally, can set:

regex=True Treat service_name as a regular expression harvest_type= Specify what type of harvest (i.e. DNS_A) ip_address= Look for specific IP address

Returns an identity record or 0 if no match

Setting test=1 returns database query execution statistics

get_service_by_ip(ip_addr, test=0)

Passed an IP address. Look this up in the identities db collection. Returns the most recent identities record for this IP address that has the a service_name, or 0 if no match.

Checks to see if service name is an alias for a CNAME and if it is moves the service name to service alias and returns the CNAME as the service name. Caution: returns the first CNAME and there could be a many to one mapping... Also, does not recurse.

Setting test=1 returns database query execution statistics

get_host_by_ip(ip_addr, test=0)

Passed an IP address. Look this up in the identities db collection. Returns the most recent identities record for this IP address that has a host_name, or 0 if no match.

Setting test=1 returns database query execution statistics

get_location_by_mac(mac_addr, test=0)

Passed a MAC address. Look this up in the identities db collection and return a source logical location string if present, otherwise return 0. Setting test=1 returns database query execution statistics

get_dns_cname(service_name, test=0)

Passed a DNS A Record name. Look this up in the identities db collection. Return the most recent CNAME for this A Record or 0 if no match.

Setting test=1 returns database query execution statistics

identities.mac_addr(address)

Convert a MAC address to a readable/printable string