User Guides

DNSDB API User Guide

Introduction

DNSDB is a database that stores and indexes both the passive DNS data available via Farsight Security’s Security Information Exchange (SIE) as well as the authoritative DNS data that various zone operators make available. DNSDB makes it easy to search for individual DNS RRsets and provides additional metadata for search results—such as first seen and last seen timestamps and the DNS bailiwick associated with an RRset. DNSDB also has the ability to perform inverse or rdata searches.

The Farsight DNSDB API Documentation can be found at https://api.dnsdb.info/

DNSDB Capabilities and limits

Access to DNSDB can be licensed in a number of ways and access can be granted via a number of interfaces and tools. These licenses and tools have different capabilities and limits that a user needs to be aware of.

This table summarizes these capabilities and limits summary:

Trial Products

Product	Quota	Maximum Results	Duration	Data Available	Rate Limit	Query Privacy
Maltego Free Queries	12 per hour	12	N/A	2010 to now	12 per hour	No

To request a demonstration of DNSDB please contact the DomainTools sales team.

Subscription Products

Product	Quota	Maximum Results	Duration	Data Available	Rate Limit	Query Privacy
Queries per Day (QPD)	1K – Unlimited	10K – 1M	1 Year	2010 to now	None	Yes

User Guide Notes

In the Curl examples below, $APIKEY is expressed as an environmental variable. You can set the variable in the current shell with (note: this is an example key only):

$ APIKEY="QmIodGqF12TKOf8bqBe6S6WxvZ4LTtzP1VlS09g0UApw28gedka545OcumVW4WHkB"

Please note the API calls below all use API Version 2.

Using Curl 7.42.0 or higher you can use the option --path-as-is to prevent curl from squashing or merging sequences of /../ or /./

Primary Pivots

When using the Farsight DNSDB API for historical DNS investigations, there are five primary pivots of which one should be aware:

Name -> Answers (names and IPs)
Wildcard left hand side
Wildcard right hand side
IP -> Names
Name -> Names

Name -> Answers

A name is specified and historical answers associated with the name are returned. Common records types to be returned would be A, AAAA, NS, MX, SOA, TXT, etc. If no record type is specified, all record types will be returned.

Hostname

Hostname: www.fsi.io

When investigating a hostname/FQDN, you will often only get a few record types back. Often an investigator might obtain additional value from the base level domain. See the next section as an example:

$ curl -s -H 'Accept: application/x-ndjson' -H "X-API-Key: $APIKEY" \
     "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/www.fsi.io?limit=10000"

Second Level Domain

Hostname: fsi.io

$ curl -s -H 'Accept: application/x-ndjson' -H "X-API-Key: $APIKEY" \
    "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/fsi.io?limit=10000"

Wildcard left hand side

This search effectively enumerates all of the sub-domains of a second level domains.

$ curl -s -H 'Accept: application/x-ndjson' -H "X-API-Key: $APIKEY" \
    "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/*.fsi.io?limit=10000"

Wildcard right hand side

This search effectively enumerates other TLDs the ASCII name can be seen in, as well as where the ASCII name can be see as a sub-domain. It is not a regex search.

$ curl -s -H 'Accept: application/x-ndjson' -H "X-API-Key: $APIKEY" \
    "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/farsightsecurity.*?limit=10000"

IP -> Names

A single IP address

This search returns all names that have pointed to the IP address specified (/32).

$ curl -s -H 'Accept: application/x-ndjson' -H "X-API-Key: $APIKEY" \
    "https://api.dnsdb.info/dnsdb/v2/lookup/rdata/ip/104.244.13.104?limit=10000"

A CIDR range

This search returns all names that have pointed to the CIDR Range specified (/24).

$ curl -s -H 'Accept: application/x-ndjson' -H "X-API-Key: $APIKEY" \
    "https://api.dnsdb.info/dnsdb/v2/lookup/rdata/ip/104.244.13.0,24?limit=10000"

Name -> Names

This search returns any names pointing to a name. A name pointing to a name as its NS record is a good example of its usefulness.

$ curl -s -H 'Accept: application/x-ndjson' -H "X-API-Key: $APIKEY" \
    "https://api.dnsdb.info/dnsdb/v2/lookup/rdata/name/ns1.infocity.club/NS?limit=10000"

Considerations

Things to consider when implementing DNSDB API:

When the plan is to truncate answers displayed to the user, you will often want to make a much larger query to the API to ensure you receive the most recent results. Query limit of 10,000 at a minimum.
The data returned by the API is not sorted, you will often want to sort the data by time_last. Often the most recent DNS results are of the most value to the investigator.
Email addresses found in SOA records make a good pivot into other databases like historical WHOIS.
In a graphical UI, being able to pivot between names and IP addressees as hyperlinks is a often a good user experience.
The ability to filter (hide) various DNS record types can make it easier to parse through the passive DNS results.