Metadata-Version: 2.1
Name: dnsdb-python
Version: 1.1.3
Summary: An unofficial Farsight Security DNSDB client
Home-page: https://domainaware.github.io/dnsdb-python
Author: Sean Whalen
Author-email: whalenster@gmail.com
License: Apache 2.0
Keywords: DNS,passive,DNS,Farsight Security,DNSDB
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.0
Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Dist: requests
Requires-Dist: python-dateutil
Requires-Dist: dateparser
Requires-Dist: click

============
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
- 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

.. code-block:: bash

    sudo -H pip3 install -U dnsdb-python

To install the latest development version, run

.. code-block:: bash

    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``.

See also
--------
- `DNSDB Community Edition`_
- `DNSDB API reference`_

.. _Farsight Security's DNSDB: https://www.farsightsecurity.com/solutions/dnsdb/
.. _DNSDB Community Edition: https://www.farsightsecurity.com/dnsdb-community-edition/
.. _DNSDB API reference: https://api.dnsdb.info/

