Skip to main content

Python client for Farsight Security's DNSDB API

Project description


Python client for Farsight Security's DNSDB API.


  • supports all capabilities of DNSDB API
  • sorting of results by last_seen
  • convert epoch to ISO 8601
  • normalize results with regard sensor or zone observation
  • supports the caching of DNSDB API results
  • returns an object with the following attributes:
    • records
    • status code
    • error
    • quota
    • cache
  • CLI named dnsdb


Use the package manager pip to install dnsdb.

pip install dnsdb



>>> from dnsdb import Dnsdb

>>> api_key="12345"
>>> dnsdb = Dnsdb(api_key)

Example 1

>>> result ="")

>>> pprint(result.status_code)

>>> pprint(result.error)

>>> pprint(result.records[0])
{'bailiwick': '',
 'count': 4213726,
 'rdata': [''],
 'rrname': '',
 'rrtype': 'A',
 'source': 'sensor',
 'time_first': '2014-12-10T00:19:18Z',
 'time_last': '2019-03-05T14:37:31Z'}
>>> pprint(result.quota)
{'expires': None,
 'limit': '1000000',
 'remaining': '999970',
 'reset': '1551830400',
 'results_max': None}

Example 2

>>> result ="")

>>> pprint(result.status_code)

>>> pprint(result.error)
{'code': 404, 'message': 'Error: no results found for query.'}

>>> pprint(result.records)

>>> pprint(result.quota)
{'expires': None,
 'limit': '1000000',
 'remaining': '999969',
 'reset': '1551830400',
 'results_max': None}

More Usage

from dnsdb import Dnsdb

dnsdb = Dnsdb(api_key)
dnsdb = Dnsdb(api_key, cache=True)
dnsdb = Dnsdb(api_key, cache=True, cache_timeout=900)
dnsdb = Dnsdb(api_key, cache=True, cache_location="/tmp/dnsdb-cache")

result ="")
result ="", inverse=True)
result ="")
result ="")
result ="2620:11c:f008::108")
result ="36757a35")
result ="", type="A")
result ="", bailiwick="com.")
result ="", wildcard_left=True)
result ="fsi", wildcard_right=True)
result ="", sort=False)
result ="", remote_limit=150000, return_limit=1000)
result ="", time_last_after="2019-01-01")
result ="", time_last_after="2019-01-01T00:00:00Z")
result ="", epoch=True, time_last_after=1546300800)
result ="", epoch=True)
result = dnsdb.quota()


The dnsdb module includes CLI client


$ dnsdb -h
usage: dnsdb [-h] (-n NAME | -i IP | --hex HEXADECIMAL) [-t TYPE]
             [-b BAILIWICK] [-r] [--wildcard-left] [--wildcard-right] [--sort]
             [--epoch] [-f {csv,json,jsonp}] [--return-limit RETURN_LIMIT]
             [--remote-limit REMOTE_LIMIT] [--first-before TIME_FIRST_BEFORE]
             [--first-after TIME_FIRST_AFTER] [--last-before TIME_LAST_BEFORE]
             [--last_after TIME_LAST_AFTER] [--cache]
             [--cache-location CACHE_LOCATION] [--cache-timeout CACHE_TIMEOUT]
             [--apikey API_KEY] [--server SERVER] [-v] [-c CONFIG] [--version]

CLI client for DNSDB

optional arguments:
  -h, --help            show this help message and exit
  -n NAME, --name NAME  fully qualified domain mame
  -i IP, --ip IP        IPv4 or IPv6 address, CIDR notation is valid
  --hex HEXADECIMAL     hexadecimal digits specifying a raw octet string
  -t TYPE, --type TYPE  dns resource record types (ANY, A, MX, SIG, etc)
  -b BAILIWICK, --bailiwick BAILIWICK
                        a label in a fqdn, not valid for inverse queries
  -r, --inverse         search for names resolving to names (e.g. MX, NS,
                        CNAME, etc)
  --wildcard-left       wildcard search to the left of a dot in a domain name
  --wildcard-right      wildcard search to the right of a dot in a domain name
  --sort                sort results by time last
  --epoch               return timestamps in epoch
  -f {csv,json,jsonp}, --format {csv,json,jsonp}
                        output formats
  --return-limit RETURN_LIMIT
                        number of client side results returned
  --remote-limit REMOTE_LIMIT
                        number of server side results returned
  --first-before TIME_FIRST_BEFORE
                        server side filter for time first before
  --first-after TIME_FIRST_AFTER
                        server side filter for time first after
  --last-before TIME_LAST_BEFORE
                        server side filter for time last before
  --last_after TIME_LAST_AFTER
                        server side filter for time last after
  --cache               Use cached results
  --cache-location CACHE_LOCATION
                        Path to cache
  --cache-timeout CACHE_TIMEOUT
                        Timeout in seconds
  --apikey API_KEY      DNSDB API key
  --server SERVER       Server URL
  -v, --verbose         Set the verbosity level
  -c CONFIG, --config CONFIG
                        Path to config file
  --version             show program's version number and exit

Time format options: yyyy (2016), yyyy-mm (2016-01), yyyy-mm-dd (2016-01-01),
yyyymmdd (20160101), yyyymmddThh (20160101T12), yyyy-mm-ddThh:mm:ss-hh:mm

Configuration file


$ vim ~/.dnsdb.ini



$ vim ~/.dnsdb.ini



$ dnsdb -n
$ dnsdb -i -f csv


Pull requests are welcome; for major changes, please open an issue first to discuss what you would like to change.

Please make sure to create and update tests as appropriate.



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dnsdb-0.2.5.tar.gz (13.1 kB view hashes)

Uploaded source

Built Distribution

dnsdb-0.2.5-py3-none-any.whl (13.1 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page