Resolvers

Lookup everything!

Motivation

Lots of information is not available on first sight, and we need to combine our data with knowledge from other data sources to make it easier to understand for humans.

Think of resolving ip addresses to geolocations, hardware addreses to manufacturers, domains to ip addresses and vice versa, or simply identifying the service name associated with a given port number. Or consider filtering ip addresses or domain names against a whitelist, to eliminate known legitimate traffic.

The resolvers package provides primitives for such tasks, and if possible, caches results in memory for better performance.

Design

External data sources are stored in a central directory on the system, which defaults to /usr/local/etc/netcap/db but can be overridden using the NC_DATABASE_SOURCE environment variable.

Database files:

  • domain-whitelist.csv

  • GeoLite2-City.mmdb

  • GeoLite2-ASN.mmdb

  • ja3fingerprint.json

  • macaddress.io-db.json

  • service-names-port-numbers.csv

  • ja3UserAgents.json

  • ja3erDB.json

Configuration

By default, all resolvers are disabled. You need to use the -reverse-dns, -local-dns, -macDB, -ja3DB, -serviceDB and -geoDB to enable what you want to use, or configure it via environment variables or config file, as described in:

Configuration

Quickstart

You can download a bundled version of all databases except for the MaxMind GeoLite, here:

DNS

Reverse DNS lookups can be used to identify the domains associated with an address. By default the standard system resolver will be contacted for this.

Passive / Local DNS

Passive DNS will read the hosts mapping from a file and load it into memory, instead of looking up encountered adresses by contacting a resolver. This can be used to provide names for known hosts in your network for example.

To avoid producing lookups that leave the network, you can generate a hosts mapping based on the DNS traffic in your dumpfile using tshark:

$ tshark -r traffic.pcap -q -z hosts

And provide it to netcaps resolver via a hosts file in the database directory.

Domain Whitelisting

To filter known legitimate domains away, the alexa top 1 million can be used for example.

You can download the CSV file here:

Rename it to domain-whitelist.csv and move it into the database path:

$ mv top-1m.csv /usr/local/etc/netcap/db/domain-whitelist.csv

Geolocation

To determine the geolocation for a given host, the MaxMind GeoLite database is used. The lite database is freely available, but you have to register on their website to download it.

Geolocation lookups can provide the Country, City and ASN where an ip adress is registered.

Download the databases and move them into the database path.

Vendor Identification

To identify the vendor for a given MAC address, the macaddress.io JSON database is used.

At the time of this writing it contains 39,041 tracked address blocks and 28,961 unique vendors.

Service Identification

Resolving port numbers to service names is done according to the CSV mapping from IANA, which contains 6104 records for TCP and UDP services at the time of this writing:

TLS Fingerprints

To identify hosts that use TLS connections, the Ja3 fingerprint database from Trisul is used:

For more fingerprints, you can load other databases additionally. For example from ja3erDB:

Last updated