DNSDB API New Features

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 seen
• time_first_after: Filter results relative to after the time first seen
• time_last_before: Filter results relative to before the time last seen
• time_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.