DNSDB API New Features
By Henry Stern
Introduction
Farsight Security's DNSDB (TM) is a historical database that stores and indexes both the Passive DNS data available via Farsight Security's Security Information Exchange 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 as well as the DNS bailiwick associated with an RRset. DNSDB also has the ability to perform inverse or rdata searches.
If you're interested in getting access, please apply for an account!
DNSDB Delivery Options
DNSDB is delivered in one of three ways:
- DNSDB Web UI: Simple web interface for executing one-off queries
- DNSDB Export: Customer-premise database instance running on customer-provided infrastructure
- DNSDB Access API: Cloud-based RESTful API with JSON responses, available using open source command line tools, and also readily integrated into existing automated systems.
This article reveals new options for DNSDB Access API.
New DNSDB API Feature: Server-Side Time Filtering
Farsight Security has added some new parameters to the DNSDB API that allow DNSDB users to pre-filter search results based on the first- and last-seen times of each RRset being before or after a certain time. There are four new parameters:
time_first_before
: Filter results relative to before the time first seentime_first_after
: Filter results relative to after the time first seentime_last_before
: Filter results relative to before the time last seentime_last_after
: Filter results relative to after the time last seen
Users may provide either an absolute UNIX timestamp in UTC: 1420657758
or a
relative timestamp (which preceded by -): -86400
.
See our
API documentation for further details on how to use
these parameters with the API. The latest version of our
dnsdb-query tool makes use of this filtering with the --before
and --after
options.
The following are some recipes showing how you can use this new API feature.
Return only RRsets that have been seen recently
DNSDB, our historical Passive DNS database, spans back to 2010. Certain
queries will return a lot of older results that may not be relevant if you
would prefer a more current snapshot. You can use the time_last_after
parameter to eliminate all of the older RRsets. Here is an example that
filters out everything older than one month:
https://api.dnsdb.info/lookup/rrset/name/example.com?time_last_after=-2592000
Return only new RRsets
If you are using DNSDB to monitor a domain name for changes or a network
address for new names referring to it, you can use the time_first_after
parameter to filter out everything older than a day:
https://api.dnsdb.info/lookup/rdata/ip/198.51.100.0,24?time_first_after=-86400
Return the set of RRsets that were seen at a certain time
If you are investigating an incident and you find some network activity that
you suspect to be botnet command and control traffic, you can combine the
time_first_before
and time_last_after
parameters to find the list of
hostnames that were observed mapping to that address when the incident
happened:
https://api.dnsdb.info/lookup/rdata/ip/192.0.2.0,24?time_first_before=X&time_last_after=X
Return RRsets that were only seen during a certain time interval
If you are investigating an incident where a domain name was hijacked by a
third party and you want to find all of the RRsets that were only seen during a
time interval you can combine the time_first_after
and time_last_before
parameters:
https://api.dnsdb.info/lookup/rrset/name/example.com?time_first_after=X&time_last_before=Y
Henry Stern is a Senior Distributed System Engineer for Farsight Security, Inc.