Investigate IPs, domains, hashes, and CVEs across 6 free threat intel APIs — without switching between browser tabs.

Quick Start · Usage · Architecture · API Keys · Screenshots · Contributing

🚀 Proudly featured in the official Awesome OSINT repository.

📖 Overview

ThreatLens is a single command-line tool that unifies threat intelligence lookups across the most trusted free OSINT sources. Instead of pasting an IP into five different websites, ThreatLens queries them all in parallel, normalizes the results, and gives you a clear verdict — in the terminal, or in a polished, color-coded Excel/JSON/CSV report.

Built for SOC analysts, incident responders, threat hunters, and anyone who wants fast, reliable IOC enrichment without leaving the shell.

Why ThreatLens

One command instead of five browser tabs
Auto-extracts IOCs straight out of raw logs
A single failing/rate-limited API never blocks the rest
Works entirely on free API tiers
Local SQLite cache — repeated lookups are instant
Request budget cap prevents runaway API spend

Not for

Real-time/streaming detection pipelines
Paid/enterprise-only intel feeds
Replacing a full SIEM or SOAR platform

✨ Features

Feature	Details
🎯 IOC Types	IP, Domain, URL, File Hash (MD5 / SHA1 / SHA256), CVE
🔌 Integrated APIs	AbuseIPDB, VirusTotal, AlienVault OTX, Shodan, URLScan.io, NVD, CISA KEV, EPSS
📄 Log Parsing	Auto-extract IOCs from plain text/log files, plus native support for Zeek, Suricata `eve.json`, Sysmon (JSON), and generic JSONL
🧭 CVE Decision Cards	Deterministic, explainable Patch / Isolate / Monitor / Not affected recommendation per CVE, driven by CISA KEV, EPSS, CVSS, and correlated asset exposure
🗂️ Asset Inventory	Import a CSV of hosts/IPs with criticality and internet-facing status; correlated against CVE results
📤 SIEM Export	Opt-in export to Splunk HEC, Elastic `_bulk`, and Microsoft Sentinel (modern Logs Ingestion API)
🧾 Evidence Packs	ZIP export of an investigation with a SHA-256 manifest for basic chain-of-custody
📊 Reports	Excel (color-coded), JSON, CSV
💾 Local Cache	SQLite cache with configurable TTL — skip re-querying known IOCs, plus a cached CISA KEV feed (24h TTL)
🛡️ Security	Redirect blocking, host allow-listing, API-key redaction in logs, spreadsheet-formula neutralisation, CSV/log DoS limits
🔒 Lockfile	`requirements.lock` with SHA-256 hashes for reproducible installs
💻 CLI Experience	Rich progress bars, colored tables, and a clean verdict summary
🧩 Architecture	Modular enrichers/parsers/exporters, typed models, strict separation of concerns
✅ Tested	155 unit & integration tests with `pytest`; CI via GitHub Actions
⚡ Resilient	One failing API or SIEM destination never blocks the others — errors are isolated and logged

🚀 Quick Start

# 1. Clone & install
git clone https://github.com/AbdaullahAG/threatlens.git
cd threatlens
pip install -r requirements.txt

# 2. Configure your API keys
cp config/keys.env.example config/keys.env
# → edit config/keys.env and fill in your keys

# 3. Run your first scan
python main.py -i 45.33.32.156

💡 NVD (CVE lookups) works out of the box with no API key. Every other API offers a free tier that takes under 2 minutes to sign up for — see API Keys below.

Reproducible install (with locked dependencies)

pip install --require-hashes -r requirements.lock

🧰 Usage

`# Investigate a single IP python main.py -i 45.33.32.156`	Basic single-IOC lookup
`# Investigate multiple IOC types at once python main.py -i 45.33.32.156 -d malware.example.com \ -s d41d8cd98f00b204e9800998ecf8427e -c CVE-2021-44228`	Mix and match IOC types in one run
`# Parse a log file — all IOCs auto-extracted python main.py --file /var/log/apache2/access.log`	Bulk investigate straight from raw logs
`# Output JSON instead of Excel python main.py -i 8.8.8.8 --format json`	Machine-readable output for pipelines
`# Use only specific APIs python main.py -i 8.8.8.8 --apis abuseipdb virustotal`	Restrict enrichment to selected sources
`# Generate every report format at once python main.py --file access.log --format all`	Excel + JSON + CSV in a single run
`# Lookup a CVE — no API key needed python main.py -c CVE-2021-44228 --apis nvd --format json`	CVE enrichment via NIST NVD (free, no key)
`# Verbose / debug mode python main.py -i 8.8.8.8 -v`	Full request/response logging for troubleshooting
`# Check a CVE against CISA KEV + EPSS, with an asset-aware decision python main.py -c CVE-2021-44228 --apis nvd cisa_kev epss \ --import-assets assets.csv --decision-cards`	Patch / Isolate / Monitor / Not-affected recommendation
`# Parse a Suricata eve.json and export to Splunk python main.py --file eve.json --log-format suricata \ --export splunk`	SOC log ingestion → SIEM export
`# Build a hash-manifested evidence pack for the investigation python main.py -i 45.33.32.156 --evidence-pack`	ZIP with a SHA-256 manifest for chain-of-custody

See all CLI flags

Most Popular

ThreatLens

📖 Overview

✨ Features

🚀 Quick Start

Reproducible install (with locked dependencies)

🧰 Usage