Metadata-Version: 2.4
Name: threatpivot
Version: 0.1.0
Summary: Multi-source IOC enrichment and pivot tool for threat intelligence analysts — no Docker, no server, pip install and go
Project-URL: Homepage, https://github.com/H3NRYBAIT/threatpivot
Project-URL: Documentation, https://github.com/H3NRYBAIT/threatpivot/docs
Project-URL: Bug Tracker, https://github.com/H3NRYBAIT/threatpivot/issues
Project-URL: Source Code, https://github.com/H3NRYBAIT/threatpivot
Author: Abdullah Hassan
License: MIT
License-File: LICENSE
Keywords: cti,cybersecurity,dfir,enrichment,ioc,osint,pivot,security,soc,threat-intelligence
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mmh3>=4.1.0
Requires-Dist: platformdirs>=4.2.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-whois>=0.9.4
Requires-Dist: pyvis>=0.3.2
Requires-Dist: rich>=13.7.0
Requires-Dist: stix2>=3.0.0
Requires-Dist: toml>=0.10.2
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: hatchling>=1.24.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=5.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# threatpivot

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

[![PyPI version](https://badge.fury.io/py/threatpivot.svg)](https://badge.fury.io/py/threatpivot)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

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

```bash
pip install threatpivot
```

---

## Quickstart

```bash
# 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

| Source | IOC Types | Key Required | Free Tier |
|--------|-----------|--------------|-----------|
| VirusTotal | All | Yes | 500/day |
| AbuseIPDB | IP | Yes | 1,000/day |
| ThreatFox | All | Yes | Unlimited |
| urlscan.io | Domain, URL | No | Unlimited public |
| AlienVault OTX | All | Yes | Unlimited |
| Shodan | IP | Yes | Limited |
| GreyNoise | IP | Yes | Community tier |
| crt.sh | Domain | No | Unlimited |
| URLhaus | All | No | Unlimited |

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:

| Source | Weight | Rationale |
|--------|--------|-----------|
| VirusTotal | 35% | 70+ AV engines, highest signal |
| ThreatFox | 25% | Community-verified C2 data |
| AbuseIPDB | 20% | Volume of abuse reports |
| OTX | 10% | Community quality varies |
| urlscan | 5% | Passive, lower confidence |
| Others | 5% | Context/pivot value |

Final verdict thresholds:

| Score | Verdict |
|-------|---------|
| ≥ 0.65 | MALICIOUS |
| ≥ 0.30 | SUSPICIOUS |
| > 0.00 | CLEAN |
| 0.00 | UNKNOWN |

---

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

| Code | Meaning |
|------|---------|
| 0 | Success — verdict may be clean, suspicious, or unknown |
| 1 | `--fail-on-malicious` set and verdict was MALICIOUS |
| 2 | Bad input — unrecognised IOC type or config error |
| 3 | `--fail-on-error` set and at least one source returned no answer |

Use both flags together for a strict security gate:

```bash
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.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](LICENSE).
