Skip to main content
Help the Python Software Foundation raise $60,000 USD by December 31st!  Building the PSF Q4 Fundraiser

Client for the PassiveTotal REST API

Project description

Build Status


Python client for RiskIQ’s PassiveTotal API services

passivetotal provides a Python client library implementation into RiskIQ API services. The library currently provides support for the following services:

  • Passive DNS queries and filters
  • WHOIS queries (search and details)
  • SSL Certificates (search and details)
  • Account configuration
  • Site actions (tagging, classifying, etc.)

Command-line scripts

The following command line scripts are installed with the library:

  • pt-config: utility to set or query API configuration options for the library (username and API key).
  • pt-info: client to query for your local account information and services.
  • pt-client: primary client to issue queries against PassiveTotal services including passive DNS, WHOIS, SSL certificates, etc.

See the Usage section for more information.


From the downloaded source distribution:

$ python install

Or from PyPI:

$ pip install passivetotal [--upgrade]

The package depends on the Python Requests library. If Requests is not installed, it will be installed as a dependency.


First-time setup requires configuring your API token and private key for authentication:

$ pt-config setup <USERNAME> <API_KEY>

At any time, the current API configuration parameters can be queried using the same utility:

$ pt-config show

Configuration parameters are stored in $HOME/.config/passivetotal/api_config.json.


Our libraries support Python 3 through futures. On certain platforms, this causes issues when doing upgrades of the library. When performing an update, use the following:

sudo pip install passivetotal –upgrade –ignore-installed six


Every command-line script has several sub-commands that may be passed to it. The commands usage may be described with the -h/--help option.

For example:

$ pt-client -h
usage: pt-client [-h] {action,pdns,whois,ssl} ...

PassiveTotal Command Line Client

positional arguments:
    pdns                Query passive DNS data
    whois               Query WHOIS data
    ssl                 Query SSL certificate data
    action              Query and input feedback

optional arguments:
  -h, --help            show this help message and exit

Every sub-command has further help options::

$ pt-client pdns -h
usage: pt-client pdns [-h] --query QUERY [--sources SOURCES [SOURCES ...]]
                      [--end END] [--start START] [--timeout TIMEOUT]
                      [--unique] [--format {json,text,csv,stix,table,xml}]

optional arguments:
  -h, --help            show this help message and exit
  --query QUERY, -q QUERY
                        Query for a domain, IP address or wildcard
  --sources SOURCES [SOURCES ...]
                        CSV string of passive DNS sources
  --end END, -e END     Filter records up to this end date (YYYY-MM-DD)
  --start START, -s START
                        Filter records from this start date (YYYY-MM-DD)
  --timeout TIMEOUT, -t TIMEOUT
                        Timeout to use for passive DNS source queries
  --unique              Use this to only get back unique resolutons
  --format {json,text,csv,stix,table,xml}
                        Format of the output from the query

All commands will have the --format option to return raw responses in a number of different formats, which often contain more information than present in the default, human readable format.


For more information you can find documentation in the ‘docs’ directory, check the Github wiki, or readthedocs.

Project details

Download files

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

Files for passivetotal, version 1.0.31
Filename, size File type Python version Upload date Hashes
Filename, size passivetotal-1.0.31-py2-none-any.whl (24.0 kB) File type Wheel Python version py2 Upload date Hashes View
Filename, size passivetotal-1.0.31-py3-none-any.whl (24.0 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size passivetotal-1.0.31.tar.gz (16.4 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page