threatpivot

Multi-source IOC enrichment and pivot tool for threat intelligence analysts. No Docker. No server. pip install threatpivot and go.

Why threatpivot exists

Every CTI and SOC analyst knows the workflow: receive one suspicious domain, open eight browser tabs, copy-paste the IOC into each tool, manually combine the results, and write a verdict. It takes 10–15 minutes per IOC.

threatpivot does all of that in under 5 seconds from your terminal.

It is built for the individual analyst — not a team that can afford a shared IntelOwl server. pip install, add your free API keys, and every IOC lookup runs 8 sources in parallel with a weighted confidence verdict and a finished report you can paste straight into a ticket.

Install

pip install threatpivot

Quickstart

# Single IOC — auto-detects type
pivot lookup evil-domain.com
pivot lookup 185.220.101.45
pivot lookup 44d88612fea8a8f36de82e1278abb02f

# Defanged IOCs work natively
pivot lookup 'login-microsoft[.]com'
pivot lookup 'hxxps://evil[.]com/payload.exe'

# Output formats
pivot lookup evil.com --output markdown
pivot lookup evil.com --output json
pivot lookup evil.com --output html --save report.html
pivot lookup evil.com --output stix --save bundle.json

# Bulk enrichment from file (one IOC per line)
pivot batch iocs.txt
pivot batch iocs.txt --output csv --save results.csv

# Campaign mode — group IOCs into an investigation
pivot campaign new "phishing-campaign-2024"
pivot campaign add "phishing-campaign-2024" evil.com
pivot campaign add "phishing-campaign-2024" 185.220.101.45
pivot campaign report "phishing-campaign-2024" --output html

# Configure API keys interactively
pivot configure

# See which sources are active
pivot providers

# Pipeline mode — exit code 1 if malicious
pivot lookup "$IOC" --fail-on-malicious

Sources

All sources are free. There is no Pro tier. No paywalled providers.

How confidence scoring works

threatpivot does not simply count how many sources flagged an IOC. Each source has a weight based on its reliability and signal strength:

Final verdict thresholds:

Privacy & security

• Private and reserved IPs (RFC1918, loopback, link-local) are never sent to external APIs
• API keys are stored in ~/.config/threatpivot/config.toml and never appear in output, logs, or --json mode
• All external requests use HTTPS with certificate verification
• Defanged inputs are validated before refanging to prevent injection

Exit codes

Use both flags together for a strict security gate:

pivot lookup "$IOC" --fail-on-malicious --fail-on-error

Adding a source

Every source is a self-contained class. Inherit BaseSource, implement _query() and confidence_weight(), register in sources/__init__.py, and open a PR. See CONTRIBUTING.md.

Contributing

Contributions welcome. Good first issues are tagged in the GitHub tracker. Sources we don't yet cover: MalwareBazaar, SecurityTrails, Censys.

License

MIT — see LICENSE.