mentat.plugin.enricher.passivedns module¶

Enricher plugins performing DNS lookup of all Source/IPx addresses using CESNET and The Email Laundry (EML) PassiveDNS service.

The implementation consists of PassiveDNS connectors and their Enricher plugins. The connectors provide information about domains linked to a user defined IP address. Each domain record provides at least information when the domain name in combination with the IP address was seen for the first and the last time from the point of a DNS sniffer.

Note

To use the plugin based on The Email Laundry services you must have a private API key and specify it in the plugin configuration.

Warning

Still a work in progress and alpha code.

class mentat.plugin.enricher.passivedns.PassiveDNSCESNETEnricherPlugin[source]¶

Bases: mentat.plugin.enricher.EnricherPlugin

Enricher plugin performing PassiveDNS lookup of all Source/IPx addresses using CESNET PassiveDNS service.

SOURCE_ID = 'https://passivedns.cesnet.cz/'¶

process(daemon, message_id, message)[source]¶: Process and enrich given message.

setup(daemon, config_updates=None)[source]¶: Process configuration parameters and prepare PassiveDNS connector

class mentat.plugin.enricher.passivedns.PassiveDNSConnectorBase(cache=None, api_timeout=0.5, rec_validity=168)[source]¶

Bases: object

The abstract base class for PassiveDNS connectors.

The class provides common interface and basic record caching.

query(ip_addr, timeout=None)[source]¶

Get domains of an IP address based on PassiveDNS

First, the IP address is searched in the local cache. If the corresponding record is present and valid, the result is returned immediately without querying a PassiveDNS server. Otherwise, a new query is send to the remote server and results of successfully processed queries are stored into the local cache and returned.

Parameters

ip_addr (str) – IP address to query
timeout (int) – Query timeout in seconds (if None, default timeout is used)

Returns

Parsed domains as a list of internal records (can be empty)

Return type

list of dict

query_multi(ip_addrs, timeout=None)[source]¶

Get domains of multiple IP addresses based on PassiveDNS

Similar to the casual query, however, results of multiple IP addresses are returned as dictionary where keys are IP addresses and values are lists of parsed domains. IP addresses without known domain records are not present in the result.

Parameters

of str ip_addrs (list) – List of IP addresses to query
timeout (int) – Single query timeout in seconds (if None, default timeout is used)

Returns

IP addresses and their domains (can be empty)

Return type

dict [str, list of dict]

status()[source]¶

Determine and return the status of internal cache table and configuration

Returns: Dictionary containing various subkeys
Return type: dict

class mentat.plugin.enricher.passivedns.PassiveDNSConnectorCESNET(api_limit=100, cache_mgr=None, cache_exp=7200, **kwargs)[source]¶

Bases: mentat.plugin.enricher.passivedns.PassiveDNSConnectorBase

PassiveDNS connector for ‘CESNET’ PassiveDNS API

API_SERVER = 'https://passivedns.cesnet.cz'¶

API_URL = '/pdns/ip/{ip_address}?from={start}&to={end}'¶

class mentat.plugin.enricher.passivedns.PassiveDNSConnectorEML(api_key, api_limit=100, cache_mgr=None, cache_exp=7200, **kwargs)[source]¶

Bases: mentat.plugin.enricher.passivedns.PassiveDNSConnectorBase

PassiveDNS connector for ‘The Email Laundry’ PassiveDNS API

This connector uses PassiveDNS API provided by The Email Laundry. To use this API you MUST define your private API Key.

API_SERVER = 'http://feedapi.theemaillaundry.net'¶

API_URL = '/pdns/api/v0.1/ipv{ip_version}/{ip_address}?key={key}'¶

exception mentat.plugin.enricher.passivedns.PassiveDNSConnectorError[source]¶

Bases: RuntimeError

Custom error of the PassiveDNSConnector

class mentat.plugin.enricher.passivedns.PassiveDNSEMLEnricherPlugin[source]¶

Bases: mentat.plugin.enricher.EnricherPlugin

Enricher plugin performing PassiveDNS lookup of all Source/IPx addresses using The Email Laundry (EML) service.

SOURCE_ID = 'http://feedapi.theemaillaundry.net/'¶

process(daemon, message_id, message)[source]¶: Process and enrich given message.

setup(daemon, config_updates=None)[source]¶: Process configuration parameters and prepare PassiveDNS connector