dnsdb-python¶

A full-featured unofficial Python client and CLI for Farsight Security’s DNSDB passive DNS service.

Features¶

Easy to use Python class covers all DNSDB API endpoints and options
Supports hosted and self-hosted instances of DNSDB
Full CLI
Python 2 and 3 support
Parses multiple human date formats for time filtering
- 7 days
- 7d
- 2019-05-20
- 1 month
- 1m
Automatically converts UNIX epoch timestamps to ISO 8601 timestamps
Normalize timestamp fields for sensor and zone file observations
Sort by any field
Multiple output formats
- Text (DNS master file format)
- CSV
- JSON

CLI¶

Usage: dnsdb [OPTIONS] COMMAND [ARGS]...

  An unofficial Farsight Security DNSDB client

Options:
  --version  Show the version and exit.
  --verbose  Enable verbose logging.
  --help     Show this message and exit.

Commands:
  forward  Forward DNS lookup.
  inverse  Inverse DNS lookup.
  quotas   Show the API quotas for your API key and exit.

Usage: dnsdb forward [OPTIONS] OWNER_NAME

  Forward DNS lookup.

Options:
  -t, --rrtype TEXT               Filter results by DNS resource record type.
                                  [default: ANY]
  -b, --bailiwick TEXT            Filter results by DNS bailiwick.
  --first-seen-before TEXT        Only show results first seen before this
                                  date.
  --first-seen-after TEXT         Only show results first seen after this
                                  date.
  --last-seen-before TEXT         Only show results last seen before this
                                  date.
  --last-seen-after TEXT          Only show results last seen after this date.
  -l, --limit INTEGER             Limit the number of results to this number.
  -s, --sort [count|first_seen|last_seen|rrname|rrtype|bailiwick|rdata|source]
                                  Sort JSON results by this field.
  -r, --reverse                   Reverse the sorting.
  -f, --format [text|json|csv]    Set the screen output format.  [default:
                                  text]
  -o, --output FILE               One or more output file paths that end in
                                  .csv, .json,  or .txt (suppresses screen
                                  output).
  --help                          Show this message and exit.

Usage: dnsdb inverse [OPTIONS] [name|ip|raw] VALUE

  Inverse DNS lookup.

Options:
  -t, --rrtype TEXT               Filter results by DNS resource record type.
                                  [default: ANY]
  --first-seen-before TEXT        Only show results first seen before this
                                  date.
  --first-seen-after TEXT         Only show results first seen after this
                                  date.
  --last-seen-before TEXT         Only show results last seen before this
                                  date.
  --last-seen-after TEXT          Only show results last seen after this date.
  -l, --limit INTEGER             Limit the number of results to this number.
  -s, --sort [count|first_seen|last_seen|rrname|rrtype|bailiwick|rdata|source]
                                  Sort JSON results by this field.
  -r, --reverse                   Reverse the sorting.
  -f, --format [text|json|csv]    Set the screen output format.  [default:
                                  text]
  -o, --output FILE               One or more output file paths that end in
                                  .csv, .json,  or .txt (suppresses screen
                                  output).
  --help                          Show this message and exit.

Installation¶

To install the latest stable version, run

sudo -H pip3 install -U dnsdb-python

To install the latest development version, run

sudo -H pip3 install -U git+https://github.com/domainaware/dnsdb-python.git

Store your API key as an environment variable named DNSDB_KEY.

If you are using a self-hosted instance of DNSDB, store the URL root as an environment variable named DNSDB_ROOT.

Python API¶

An unofficial Farsight Security DNSDB client

exception dnsdb.BadRequest[source]¶: Raised then a request is improperly formatted

class dnsdb.DNSDBAPI(api_key=None, client_name=None, client_version=None, url_root='https://api.dnsdb.info')[source]¶

A Python interface to the Farsight Security DNSDB API ..

forward_lookup(owner_name, rrtype='ANY', bailiwick=None, first_seen_before=None, first_seen_after=None, last_seen_before=None, last_seen_after=None, limit=None, sort_by=None, reverse=False)[source]¶

Performs a forward DNS lookup

Parameters

owner_name (str) – The DNS Owner Name
rrtype (str) – The DNS Resource Record type
bailiwick (str) – The DNS bailiwick
first_seen_before (str) – Filter results first seen before this date
first_seen_after (str) – Filter results first seen after this date
last_seen_before (str) – Filter results last seen before this date
last_seen_after (str) – Filter results first seen before after date
limit (int) – The maximum number of results to return
sort_by – An optional field to sort by
reverse (bool) – Reverse the sorting

Returns

Results as a Python list, or as text in DNS master file format if return_text is True

inverse_lookup(_type, value, rrtype=None, first_seen_before=None, first_seen_after=None, last_seen_before=None, last_seen_after=None, limit=None, sort_by=None, reverse=None)[source]¶

Performs a inverse DNS lookup

Parameters

_type (str) –
One of the following:
- name: A DNS domain name (use * as a wildcard)
- ip: An IPv4 or IPv6 address, range, or CIDR notation
- raw: An even number of hexadecimal digits
value (str) – The rdata value to search for
rrtype (str) – The DNS Resource Record type
first_seen_before (str) – Filter results first seen before this date
first_seen_after (str) – Filter results first seen after this date
last_seen_before (str) – Filter results last seen before this date
last_seen_after (str) – Filter results first seen before after date
limit (int) – The maximum number of results to return
sort_by – An optional field to sort by
reverse (bool) – Reverse the sorting

Returns

Results as a Python list, or as text in DNS master file format if return_text is True

exception dnsdb.DNSDBAPIError[source]¶: Raised when an error is returned by DNSDB

exception dnsdb.InvalidAPIKey[source]¶: Raised when the API key is invalid, or the client IP address is not authorized for the account

exception dnsdb.QuotaExceeded[source]¶

Raised when the API quota limit has been exceeded

For time-based quotas: The API key daily quota limit is exceeded. The quota will automatically replenish, usually at the start of the next day.

For block-based quotas: The block quota is exhausted. You may need to purchase a larger quota.

For burst rate secondary quotas: There were too many queries within the burst window. The window will automatically reopen at its end.

exception dnsdb.ServerSideError[source]¶: Raised when a server side error occurs

exception dnsdb.TooManyConnections[source]¶: Raised when the limit of number of concurrent connections is exceeded

exception dnsdb.UnauthorizedAPIKey[source]¶: Raised when the API key is not authorized (usually indicates the block quota is expired)

dnsdb.dnsdb_results_to_csv(results)[source]¶

Converts DNSDB results to CSV format

Parameters: results (dict) – DNSDB results
Returns: Results in CSV format
Return type: str

dnsdb.dnsdb_results_to_json(results)[source]¶

Converts DNSDB results to pretty JSON

Parameters: results (dict) – DNSDB results
Returns: Results as a JSON string
Return type: str

dnsdb.dnsdb_results_to_text(results)[source]¶

Converts DNSDB results to text in DNS master File format

Parameters: results (dict) – DNSDB results
Returns: DNS master file content
Return type: str

dnsdb-python¶

Features¶

CLI¶

Installation¶

Python API¶

See also¶