DNSDB RRset lookups

RRset lookups query DNSDB’s RRset index, which supports “forward” lookups based on the owner name of an RRset.

URL Path Scheme

/dnsdb/v2/lookup/rrset/TYPE/VALUE/RRTYPE/BAILIWICK

Both TYPE and VALUE are required; RRTYPE and BAILIWICK are optional. If RRTYPE is not specified, the query functions as if “ANY” was specified.

Type Parameter

The TYPE parameter specifies how VALUE is interpreted:

Type	Description
name	The VALUE is a DNS owner name in presentation format or wildcards as described below. We sometimes call this just an rrset search.
raw	The VALUE is an even number of hexadecimal digits specifying a raw octet string.

Wildcards

Wildcards come in two forms:

• Left-hand wildcard (*.example.com): Matches any RRsets whose owner names end with the given domain name
• Right-hand wildcard (www.example.*): Matches any RRsets whose owner names start with the given label(s)

Note

Left-hand wildcard queries are somewhat more expensive and slower than right-hand wildcard queries.

RRtype Parameter

The OWNER_NAME and BAILIWICK are DNS names specified in DNS presentation format. RRTYPE is specified as a DNS RRtype mnemonic.

The RRtype ANY is modified from its usual meaning:

• A DNSDB lookup for RRtype ANY matches any RRtype except DNSSEC-related RRtypes: DS, RRSIG, NSEC, DNSKEY, NSEC3, NSEC3PARAM, DLV, CDS, CDNSKEY, and TA
• The pseudo-mnemonic ANY-DNSSEC returns only those DNSSEC-related records
• RRtype ANY may be specified for RRTYPE to perform bailiwick filtering without filtering on a particular RRtype

Bailiwick Parameter

The BAILIWICK may not be specified with raw queries.

Wildcard Domain Consolidation

July 2022 Update

As of July 2022, DNSDB was changed to reduce junk wildcard domains. We are gradually rolling out a change to replace multiple wildcarded DNS rrnames with a single rrname starting with a _WILDCARD_. label. No other rrname labels contain uppercase letters, so records with this (all upper case) _WILDCARD_. were never in DNSDB before. Note that there are existing, real domain names that contain a _wildcard_. label (all lower case).

Result Metadata

The results of an rrset lookup return zero or more RRsets, along with the following metadata for each result:

Item	Description
count	The number of times the RRset was observed via passive DNS replication.
bailiwick	The “bailiwick” of an RRset in DNSDB observed via passive DNS replication is the closest enclosing zone delegated to a nameserver which served the RRset. The “bailiwick” of an RRset in DNSDB observed in a zone file is simply the name of the zone containing the RRset.
first seen	A UTC timestamp with seconds granularity indicating the first time an RRset was seen in the given bailiwick via passive DNS replication.
last seen	A UTC timestamp with seconds granularity indicating the last time an RRset was seen in the given bailiwick via passive DNS replication.
first seen in zone file	A UTC timestamp with seconds granularity indicating the first time an RRset was seen in the given bailiwick via zone file import.
last seen in zone file	A UTC timestamp with seconds granularity indicating the last time an RRset was seen in the given bailiwick via zone file import.

Note

An rrset search result may be missing either the pair of (first seen, last seen) timestamps from passive DNS replication or from zone file import, but at least one pair of timestamps will always be present. This may change if a fundamentally new data source is introduced in the future, but there will always be at least one timestamp pair associated with an RRset.

RRSIG Time Format

Note

The DNSDB API returns RRSIG records with the expiration and inception times in Unix epoch time format (seconds since 1 January 1970 00:00:00 UTC). RFC 4034 also allows presentation of these times in YYYYMMDDHHmmSS format, which many DNSSEC tools and presentation libraries use. It is always possible to distinguish between these two formats because the YYYYMMDDHHmmSS format will always be exactly 14 digits, while the decimal representation of a 32-bit unsigned integer can never be longer than 10 digits.

Result Format

Results are returned in JSON Lines format with the following keys:

Key	Description
rrname	The owner name of the RRset in DNS presentation format.
rrtype	The resource record type of the RRset, either using the standard DNS type mnemonic, or an RFC 3597 generic type, i.e. the string TYPE immediately followed by the decimal RRtype number.
rdata	An array of one or more Rdata values. The Rdata values are converted to the standard presentation format based on the rrtype value. If the encoder lacks a type-specific presentation format for the RRset’s rrtype, then the RFC 3597 generic Rdata encoding will be used.
bailiwick	The “bailiwick” metadata value described above.
count	The number of times the RRset was observed via passive DNS replication.
time_first, time_last	UNIX epoch timestamps with second granularity indicating the first and last times the RRset was observed via passive DNS replication. Will not be present if the RRset was only observed via zone file import.
zone_time_first, zone_time_last	UNIX epoch timestamps with second granularity indicating the first and last times the RRset was observed via zone file import. Will not be present if the RRset was only observed via passive DNS replication.

Examples

Example 1: Lookup all RRsets for www.farsightsecurity.com

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/www.farsightsecurity.com?limit=2"

Response:

{"cond": "begin"}
{"obj":{"count":5059,"time_first":1380139330,"time_last":1427881899,
    "rrname":"www.farsightsecurity.com.","rrtype":"A","bailiwick":"farsightsecurity.com.",
    "rdata":["66.160.140.81"]}}
{"obj":{"count":17381,"time_first":1427893644,"time_last":1468329272,
    "rrname":"www.farsightsecurity.com.","rrtype":"A","bailiwick":"farsightsecurity.com.",
    "rdata":["104.244.13.104"]}}
{"cond": "limited", "msg": "Result limit reached"}

Example 2: Lookup all NS RRsets ending in farsightsecurity.com

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/*.farsightsecurity.com/ns/farsightsecurity.com"

Response:

{"cond": "begin"}
{"obj":{"count":51,"time_first":1372688083,"time_last":1374023864,
    "rrname":"farsightsecurity.com.","rrtype":"NS","bailiwick":"farsightsecurity.com.",
    "rdata":["ns.lah1.vix.com.","ns1.isc-sns.net.","ns2.isc-sns.com.",
    "ns3.isc-sns.info."]}}
{"obj":{"count":495241,"time_first":1374096380,"time_last":1468324876,
    "rrname":"farsightsecurity.com.","rrtype":"NS","bailiwick":"farsightsecurity.com.",
    "rdata":["ns5.dnsmadeeasy.com.","ns6.dnsmadeeasy.com.","ns7.dnsmadeeasy.com."]}}
{"cond": "succeeded"}

Example 3: Lookup DNSSEC records

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/*.farsightsecurity.com/ANY-DNSSEC?limit=2"

Response:

{"cond": "begin"}
{"obj":{"count":1696,"zone_time_first":1374250920,"zone_time_last":1521734545,
    "rrname":"farsightsecurity.com.","rrtype":"DS","bailiwick":"com.",
    "rdata":["60454 5 2 3672C35CFA8FF14C9C223B84277BD645C0AF54BAD5790375FE797161E4801479"]}}
{"obj":{"count":3,"zone_time_first":1374250920,"zone_time_last":1374423636,
    "rrname":"farsightsecurity.com.","rrtype":"RRSIG","bailiwick":"com.",
    "rdata":["DS 8 2 86400 1374774350 1374165350 8795 com.
        cuOdo+2G0yJpBN5ba2zxiljSzgtTzminrVc3CrsNxQPqc5YVQX4eBWMB
        +kpgSEXPT+DF2D9HwIsPpBDNdJekBpXIRW41Yl7IdZYHySqabn7hgt9M
        mk5KNy9gqCOK/JLRs07LPAm3wvfyYer8e0/7VCTEjF9/DMbMGsLLH3xr kBA="]}}
{"cond": "limited", "msg": "Result limit reached"}

Example 4: Raw query for records under fsi.io

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/raw/0366736902696f00?limit=2"

Response:

{"cond": "begin"}
{"obj":{"count":10392,"time_first":1381265499,"time_last":1428418529,
    "rrname":"fsi.io.","rrtype":"A","bailiwick":"fsi.io.","rdata":["66.160.140.76"]}}
{"obj":{"count":69435,"time_first":1428433465,"time_last":1538014110,
    "rrname":"fsi.io.","rrtype":"A","bailiwick":"fsi.io.","rdata":["104.244.13.104"]}}
{"cond": "limited", "msg": "Result limit reached"}