PassiveTotal

2.5.9 verified Fri May 01 auth: no python

Python client library for the RiskIQ PassiveTotal and Illuminate API (version 2.5.9). Provides access to passive DNS, WHOIS, SSL certificates, trackers, articles, malware, attack surface intelligence, vulnerability intelligence, and more. Release cadence is irregular with minor bugfix and feature releases.

pip install passivetotal

Common errors

error ModuleNotFoundError: No module named 'passivetotal' ↓

cause The package is named 'passivetotal' but some tutorials mistakenly use 'passivetotal2' or 'pt-client'.

fix

Run pip install passivetotal.

error AttributeError: module 'passivetotal' has no attribute 'Client' ↓

cause Trying to import Client from the top-level module incorrectly.

fix

Use from passivetotal import Client.

error passivetotal.exception.AnalyzerError: Hostname could not be resolved ↓

cause The hostname provided does not resolve to any IP address.

fix

Check the hostname or handle the exception with try/except.

Warnings

deprecated The `analyzer` module is experimental and may change in future releases. Avoid relying on internal details. ↓

fix Use the lower-level `Client` methods (e.g., `client.get_enrichment(...)`) for stable access.

gotcha Client credentials are read from `~/.passivetotal/config` by default if not provided. If the file is present but malformed, import may fail silently. ↓

fix Always pass username and api_key explicitly, or set PT_USERNAME and PT_API_KEY environment variables.

gotcha Hostname resolution may throw `AnalyzerError` if the hostname cannot be resolved to an IP. This error is not documented in all versions. ↓

fix Catch `passivetotal.exception.AnalyzerError` when accessing analyzer objects.

gotcha The `certificates` property on `Hostname` uses a substring search across both subjectAlternativeNames and subjectCommonName. Results may include certificates not exactly matching the hostname. ↓

fix Filter results further or use the `certificates_search` method with more specific parameters.

Imports

Client
wrong
```
import passivetotal
```
correct
```
from passivetotal import Client
```
Client is not a top-level module; must be imported explicitly.
analyzer
wrong
```
from passivetotal.analyzer import *
```
correct
```
from passivetotal import analyzer
```
Avoid star imports; import the module and use analyzer.Hostname, etc.

Hostname

wrong

from passivetotal import Hostname

correct

from passivetotal.analyzer import Hostname

Hostname is inside the analyzer submodule, not top-level.

Quickstart

Initialize client with credentials, then query a hostname for passive DNS resolutions.

from passivetotal import Client
from passivetotal.analyzer import Hostname

# Credentials: use environment variables or config file
client = Client(username=os.environ.get('PT_USERNAME', ''), api_key=os.environ.get('PT_API_KEY', ''))

# Resolve a hostname query
hostname = Hostname('passivetotal.org', client=client)
print(hostname.resolutions)