用于快速IOC分析（IP、域名、CVE）的Python CLI工具，使用6个免费威胁情报API。输出：彩色编码的Excel、JSON、CSV。使用：VT、Shodan、AbuseIPDB。
🚀 荣登官方 Awesome OSINT 仓库推荐列表。
ThreatLens 是一款单一命令行工具，统一了最受信赖的免费 OSINT 来源中的威胁情报查询。无需将 IP 粘贴到五个不同的网站，ThreatLens 会并行查询所有来源，规范化结果，并给出清晰的判定结论 —— 无论是在终端中，还是在精美的、带颜色编码的 Excel/JSON/CSV 报告中。
专为 SOC 分析师、事件响应人员、威胁猎手，以及任何希望在不离开 shell 的情况下快速、可靠地丰富 IOC 的人而构建。
# 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 查询）开箱即用，无需 API 密钥。 其他所有 API 都提供免费层级，注册时间不到 2 分钟 —— 请参阅下方的 API 密钥。
pip install --require-hashes -r requirements.lock
threat_intel_tool/
├── main.py # CLI entry point & argument parser
├── requirements.txt # Runtime dependencies
├── requirements-dev.txt # Dev/CI tooling (ruff, bandit, pip-audit, pip-tools)
├── requirements.lock # Pinned lockfile with SHA-256 hashes
├── pytest.ini # pytest configuration (marks, etc.)
├── config/
│ └── keys.env # API keys (copy from keys.env.example)
├── output/ # Generated reports land here
├── src/
│ ├── engine.py # Main orchestrator (collect → enrich → report)
│ ├── models.py # IOC & EnrichmentResult dataclasses
│ ├── storage.py # SQLite cache & investigation history
│ ├── parsers/
│ │ └── ioc_parser.py # Regex-based IOC extractor with validation
│ ├── enrichers/
│ │ ├── base.py # Abstract base — safe HTTP client (redirect-block, budget, retry)
│ │ ├── registry.py # Enricher dispatcher
│ │ ├── abuseipdb.py # AbuseIPDB (IP)
│ │ ├── virustotal.py # VirusTotal (IP / Domain / URL / Hash)
│ │ ├── otx.py # AlienVault OTX (IP / Domain / URL / Hash)
│ │ ├── shodan.py # Shodan (IP)
│ │ ├── urlscan.py # URLScan.io (URL / Domain)
│ │ └── nvd.py # NVD / NIST (CVE — no key required)
│ ├── reporters/
│ │ ├── excel_reporter.py # Color-coded Excel reports
│ │ ├── other_reporters.py # JSON & CSV output
│ │ └── terminal_display.py # Rich terminal tables
│ └── utils/
│ ├── config.py # API key loader & runtime config
│ ├── logger.py # Rich logging setup
│ ├── banner.py # ASCII banner
│ ├── quota.py # Per-run request budget (thread-safe)
│ └── security.py # IOC validation, formula neutralisation, secret redaction
└── tests/
├── conftest.py # pytest fixtures & --run-e2e flag
├── test_core.py # IOC parser, verdict logic, cache round-trip (34 tests)
├── test_enrichers.py # BaseEnricher HTTP edge-cases — mock only (9 tests)
├── test_reporters.py # Excel/CSV formula protection + SQLite integration (17 tests)
└── test_cli_e2e.py # Full CLI run against real NVD API (opt-in, --run-e2e)
设计原则
src/enrichers/ 中新增一个继承 BaseEnricher 的文件。无需在其他地方做任何修改。BaseEnricher.get() 在一处强制执行仅 HTTPS、主机白名单、重定向阻止、429/Retry-After 处理以及请求预算上限。config/keys.env 读取，并回退到系统环境变量。--delay）让你保持在每个 API 的免费层级限制内。result.errors 中；单个 API 失败绝不会拖垮整个扫描。=、+、-、@ 前缀）进行了中和。# Run all unit and integration tests (no network required)
pytest tests/ -v --ignore=tests/test_cli_e2e.py
# With coverage report
pytest tests/ -v --ignore=tests/test_cli_e2e.py --cov=src --cov-report=term-missing
# Run the end-to-end CLI test (makes a real NVD request)
pytest tests/test_cli_e2e.py --run-e2e -v
终端：
╭──────────────────────────── IOC Collection ─────────────────────────────╮
│ Found 4 IOCs to investigate │
│ CVE: 1 Domain: 1 Hash: 1 IP: 1 │
╰──────────────────────────────────────────────────────────────────────────╯
✓ Active APIs: abuseipdb, virustotal, otx, shodan, urlscan, nvd
🌐 IP Address Results
┌─────────────────┬──────────────┬──────────┬─────────┬────────────────────┐
│ IP Address │ Verdict │ Abuse % │ Country │ ISP / Org │
├─────────────────┼──────────────┼──────────┼─────────┼────────────────────┤
│ 45.33.32.156 │ Suspicious │ 42 │ US │ Linode │
└─────────────────┴──────────────┴──────────┴─────────┴────────────────────┘
⚠️ CVE Results
┌──────────────────┬──────────┬──────┬──────────────┐
│ CVE ID │ Severity │ CVSS │ Published │
├──────────────────┼──────────┼──────┼──────────────┤
│ CVE-2021-44228 │ Critical │ 10.0 │ 2021-12-10 │
└──────────────────┴──────────┴──────┴──────────────┘
Excel 报告： 多工作表工作簿，带颜色编码的判定（🔴 恶意 · 🟡 可疑 · 🟢 干净），保存至 output/ThreatLens_Report_<timestamp>.xlsx
有想法？提交 issue —— 欢迎贡献和建议。
欢迎并感谢贡献！
git checkout -b feature/my-featurepytest tests/ -v --ignore=tests/test_cli_e2e.py 通过且 ruff check . 无问题新的丰富器、错误修复、文档改进和测试覆盖都是很好的首次贡献 —— 请参阅 架构 了解丰富器的结构。
本项目采用 PolyForm Noncommercial License 1.0.0 许可。
你可以自由地出于个人、教育或研究目的使用、研究、修改和分享此代码。未经作者事先书面许可，不得用于商业用途（[email protected]）。
本工具仅供教育和授权安全测试目的使用。用户需自行负责遵守所集成 API 的服务条款以及所有适用法律。作者不承担任何责任，也不对本程序造成的任何误用、非法活动或损害负责。
如果 ThreatLens 为你节省了时间，不妨给它一个 ⭐ —— 这能帮助其他人发现这个项目。
|
为什么选择 ThreatLens
|
不适用于
|
| 功能 | 详情 |
|---|
| 🎯 IOC 类型 | IP、域名、URL、文件哈希（MD5 / SHA1 / SHA256）、CVE |
| 🔌 集成的 API | AbuseIPDB、VirusTotal、AlienVault OTX、Shodan、URLScan.io、NVD |
| 📄 日志解析 | 自动从任意日志或文本文件中提取所有 IOC 类型 |
| 📊 报告 | Excel（带颜色编码）、JSON、CSV |
| 💾 本地缓存 | 带可配置 TTL 的 SQLite 缓存 —— 跳过对已知 IOC 的重复查询 |
| 🛡️ 安全 | 重定向阻止、主机白名单、日志中 API 密钥脱敏、电子表格公式中和 |
| 🔒 锁定文件 | requirements.lock 带 SHA-256 哈希，确保可复现安装 |
| 💻 CLI 体验 | Rich 进度条、彩色表格和清晰的判定摘要 |
| 🧩 架构 | 模块化丰富器、类型化模型、严格的关注点分离 |
| ✅ 已测试 | 使用 pytest 的 60 个单元与集成测试；通过 GitHub Actions 进行 CI |
| ⚡ 弹性 | 单个 API 失败绝不会阻塞其他 API —— 错误被隔离并记录 |
| 基本的单 IOC 查询 |
| 在一次运行中混合搭配多种 IOC 类型 |
| 直接从原始日志批量调查 |
| 用于管道的机器可读输出 |
| 将丰富限制为选定的来源 |
| 一次运行生成 Excel + JSON + CSV |
| 通过 NIST NVD 进行 CVE 丰富（免费，无需密钥） |
| 用于故障排除的完整请求/响应日志 |
| 标志 | 描述 |
|---|
-i, --ip | 要调查的 IP 地址 |
-d, --domain | 要调查的域名 |
-s, --hash | 文件哈希 —— MD5 / SHA1 / SHA256 |
-c, --cve | CVE ID，例如 CVE-2021-44228 |
--file | 用于自动提取 IOC 的日志/文本文件路径 |
--apis | 将丰富限制为特定的 API 集合 |
--format | 输出格式：excel（默认）| json | csv | all |
--output | 保存报告的目录（默认：./output） |
--no-report | 仅将结果打印到终端，不保存文件 |
--cache-path | 本地缓存的 SQLite 路径（默认：.threatlens/investigations.db） |
--cache-ttl | 缓存生存时间（秒）（默认：3600） |
--no-cache | 完全绕过本地缓存 |
--max-requests | 每次运行的外部 API 调用上限（默认：250） |
--max-iocs | 每次运行的最大唯一 IOC 数（默认：1000） |
--allow-private-iocs | 允许私有/回环 IP（默认禁用） |
--delay | API 调用之间的延迟，用于限流调优 |
-v, --verbose | 启用调试日志 |
| 提供商 | 注册 | 免费层级 |
|---|
| AbuseIPDB | 免费 | 1,000 次查询/天 |
| VirusTotal | 免费 | 4 请求/分钟 · 500 请求/天 |
| AlienVault OTX | 免费 | 无限制（公开情报源） |
| Shodan | 免费 | 有限查询 |
| URLScan.io | 免费 | 5,000 请求/天（搜索免费） |
| NVD / NIST | 可选 | 无需密钥 |
| 测试文件 | 覆盖范围 |
|---|
test_core.py | IOC 解析器（所有类型 + 边界情况）、判定逻辑、SQLite 缓存往返 |
test_enrichers.py | BaseEnricher.get() —— 重定向阻止、预算耗尽、429+Retry-After、日志中 API 密钥脱敏、非 JSON 响应、无效 JSON、主机白名单、HTTP 方案阻止 |
test_reporters.py | Excel 与 CSV 公式注入中和（7 种前缀变体）、数值透传、SQLite TTL 过期、upsert、调查记录 |
test_cli_e2e.py | 完整子进程运行：python main.py -c CVE-2021-44228 --apis nvd --format json → 退出码 0、有效 JSON、正确判定 |
| 控制项 | 实现 |
|---|
| 仅 HTTPS | BaseEnricher.get() 在发起请求前拒绝任何非 https:// URL |
| 主机白名单 | 每个丰富器声明 allowed_hosts；对未知主机的请求会被静默丢弃 |
| 重定向阻止 | 所有请求使用 allow_redirects=False |
| 429 / Retry-After | 单次自动重试，遵循 Retry-After 头（上限 15 秒） |
| 请求预算 | --max-requests 硬性限制每次运行的 API 调用总数 |
| API 密钥脱敏 | 异常和日志行中的原始密钥值被替换为 [REDACTED] |
| 公式注入 | 所有 Excel 和 CSV 单元格值都通过 spreadsheet_value() 进行净化 |
| IOC 验证 | 每个 CLI 提供的 IOC 在丰富前都经过验证和规范化 |
| 私有 IP 防护 | 默认拒绝私有/回环地址（使用 --allow-private-iocs 覆盖） |
| 依赖审计 | CI 中运行 pip-audit；requirements.lock 固定所有哈希以确保可复现安装 |