srini-cybersec/threathunter

# ThreatHunter     ThreatHunter 是一个命令行 OSINT 富化工具，它针对给定的妥协指标 (IOC) 查询多个威胁情报 API，并生成带有评分且具有可操作性的报告。它支持 IPv4/IPv6 地址、域名、URL 和文件哈希 (MD5, SHA-1, SHA-256)，并且无需 API 密钥即可对指标进行分类和结构分析——仅在获取实时威胁情报时才需要密钥。 ## 功能 - **多源 IOC 富化** — 根据IOC类型查询 VirusTotal, AbuseIPDB, Shodan, AlienVault OTX, URLScan.io 和 ThreatFox。 - **自动 IOC 类型分类** — 在无外部依赖的情况下检测 IPv4, IPv6, 域名, URL, MD5, SHA-1 和 SHA-256。 - **威胁评分算法 (0-100)** — VirusTotal 最多贡献 60 分，AbuseIPDB 最多贡献 30 分，OTX 最多贡献 20 分，最终得分映射为 `MALICIOUS / SUSPICIOUS / LOW_RISK / CLEAN` 结论。 - **带有 TTL 的基于磁盘的响应缓存** — API 响应以 MD5 哈希为键持久化为 JSON 文件；可配置的 TTL 避免了冗余的 API 调用。 - **线程安全的速率限制** — 令牌桶限制器在所有来源中强制执行可配置的每秒请求数上限。 - **从 IOC 文件进行批量富化** — 从纯文本文件处理数千个指标，支持注释和空行。 - **JSON, CSV 和 HTML 报告生成** — 每次运行都会生成机器可读和人类可读的输出。 - **丰富的终端输出** — 使用 Rich 库渲染带有颜色编码的结论表、进度指示器和关联摘要。 - **Docker 容器化** — 支持通过环境变量注入，单条命令完成 Docker 构建和运行。 ## 架构 ``` graph LR A[CLI Input] --> B[IOC Classifier] B --> C[IOCAnalyzer] C --> D[VirusTotal API] C --> E[AbuseIPDB API] C --> F[Shodan API] C --> G[AlienVault OTX] C --> H[URLScan.io] C --> I[ThreatFox] C --> J[ResponseCache] D & E & F & G & H & I --> K[ThreatCorrelator] K --> L[Reporter] L --> M[JSON/CSV/HTML] ``` 查看 [`docs/architecture.md`](docs/architecture.md) 获取完整的 ASCII 图表、组件描述、数据流、缓存策略、速率限制细节以及评分算法的分解说明。 ## 安装 ### 标准安装 ``` # 1. 克隆仓库 git clone https://github.com/your-org/threathunter.git cd threathunter # 2. 安装依赖 pip install -r requirements.txt # 3. 配置 API 密钥 cp .env.example .env # 编辑 .env 并填写您要使用的源的密钥 ``` ### Docker ``` docker build -t threathunter . docker run --env-file .env threathunter enrich 8.8.8.8 ``` ## API 密钥 所有密钥均为可选。未提供密钥的来源将被静默跳过。 | 来源 | 环境变量 | 免费套餐 | 更多信息 | |--------|----------------------|-----------|-----------| | VirusTotal | `VT_API_KEY` | 免费 (500 次/天) | virustotal.com | | AbuseIPDB | `ABUSEIPDB_API_KEY` | 免费 (1,000 次/天) | abuseipdb.com | | Shodan | `SHODAN_API_KEY` | 付费 (~$49/月) | shodan.io | | AlienVault OTX | `OTX_API_KEY` | 免费 (无限次) | otx.alienvault.com | | URLScan.io | `URLSCAN_API_KEY` | 免费 (100 次扫描/天) | urlscan.io | | ThreatFox | `THREATFOX_API_KEY` | 免费 | threatfox.abuse.ch | ## 使用 ``` # 无需 API 调用即可分类 IOC 类型 python -m src.main classify 8.8.8.8 # 丰富单个 IP python -m src.main enrich 8.8.8.8 # 丰富多个 IOC python -m src.main enrich 8.8.8.8 malware.com d41d8cd98f00b204e9800998ecf8427e # 丰富所有报告格式 python -m src.main enrich 8.8.8.8 --output all # 从文件批量丰富 python -m src.main bulk --file iocs.txt # 清除缓存 python -m src.main cache clear # Docker docker run --env-file .env threathunter enrich 8.8.8.8 ``` ### `enrich` 命令选项 | 标志 | 默认值 | 描述 | |------|---------|-------------| | `--output`, `-o` | `json` | 报告格式：`json`, `csv`, `html` 或 `all` | | `--out-dir` | `./reports` | 报告文件的保存目录 | | `--no-cache` | 关闭 | 绕过磁盘缓存并始终获取最新结果 | ### `bulk` 命令选项 | 标志 | 默认值 | 描述 | |------|---------|-------------| | `--file`, `-f` | 必填 | IOC 列表文件的路径 | | `--out-dir` | `./reports` | 报告文件的保存目录 | | `--no-cache` | 关闭 | 绕过磁盘缓存 | ## IOC 文件格式 纯文本格式，每行一个 IOC。以 `#` 开头的行和空行将被忽略。在保留插入顺序的同时，会移除重复的条目。 ``` # ThreatHunter IOC 列表 # 生成日期：2026-05-04 # 已知恶意 IP 1.2.3.4 5.6.7.8 # 可疑域名 malware-c2.example.com phishing-kit.example.net # 文件哈希 (MD5) d41d8cd98f00b204e9800998ecf8427e # SHA-256 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 ``` ## 报告输出 ### JSON 包含每个 IOC 的完整富化数据 (包括 `sources` 中的原始 API 响应) 以及关联摘要。 ``` { "summary": { "total": 3, "by_verdict": {"MALICIOUS": 1, "CLEAN": 2}, "by_type": {"ipv4": 2, "domain": 1}, "avg_score": 26.67, "top_threats": [...] }, "iocs": [ { "ioc": "1.2.3.4", "type": "ipv4", "verdict": "MALICIOUS", "threat_score": 80, "sources": { "virustotal": {...}, "abuseipdb": {...} } } ] } ``` ### CSV 具有 `ioc, type, verdict, threat_score` 列的扁平文件。适合导入到 SIEM 平台、电子表格或进行进一步脚本处理。 ### HTML 一个独立的暗色主题页面，包含汇总统计信息 (IOC 总数、恶意数量、可疑数量、平均分数) 以及带颜色编码的结论表。无外部 CSS 或 JavaScript 依赖——适合离线查看或作为电子邮件附件。 ## 开发 ### 运行测试 ``` # 所有测试及覆盖率报告 pytest tests/ -v --cov=src --cov-report=term-missing # 仅单元测试 pytest tests/test_core.py -v # 仅集成测试 pytest tests/test_integration.py -v ``` ### 代码检查和格式化 ``` # 使用 Black 格式化 black src/ tests/ examples/ # 使用 Ruff 进行 Lint ruff check src/ tests/ examples/ # 使用 mypy 进行类型检查 mypy src/ ``` ### 安全扫描 ``` # 常见安全问题的静态分析 bandit -r src/ # 依赖漏洞扫描 safety check ``` ### 运行演示 (无需 API 密钥) ``` python examples/demo.py ``` ## 安全考量 - **API 密钥**完全从环境变量中加载。切勿将包含敏感信息的 `.env` 文件提交到版本控制。此仓库中的 `.gitignore` 默认排除了 `.env`。 - **缓存文件**包含原始 API 响应，其中可能包含敏感的威胁情报数据。默认缓存位置 (`/tmp/threathunter_cache`) 在大多数系统上是临时的，但运维人员应确保在共享环境中该位置不允许可被全局读取。 - **IOC 文件解析**在评估前会去除每行的首尾空格；不会对用户提供的输入执行 shell 解释或 `eval` 操作。 - **HTTP 请求**使用带有可配置超时 (`THREATHUNTER_TIMEOUT`，默认为 30 秒) 的 `requests.Session`，以防止无限期阻塞。 - **速率限制**在每次出站请求之前强制执行，以防止因违反速率限制而导致 API 密钥被意外吊销。 - **无硬编码凭证** — 代码库通过了 `bandit` 高严重级别的安全扫描，且未发现任何与机密泄露相关的结果。 ## 贡献 1. 派生 (Fork) 该仓库并创建一个功能分支： `git checkout -b feature/my-improvement` 2. 进行更改，添加或更新测试，并确保所有测试通过： `pytest tests/ -v` 3. 运行代码检查器和格式化工具： `ruff check src/ tests/ && black src/ tests/` 4. 开启一个带有清晰更改描述及其背后动机的 Pull Request。 5. 所有 Pull Request 必须维持或提高测试覆盖率，并通过 CI。 请遵循现有的代码风格 (类型注解、公共方法的 docstring、禁止使用裸 `except` 子句)。 ## 许可证 MIT License — 查看 [LICENSE](LICENSE) 了解全文。 Copyright (c) 2026 ThreatHunter Contributors

标签：AbuseIPDB, Ask搜索, CSV报告, Cyber Threat Intelligence, Docker, ESC4, FTP漏洞扫描, HTML报告, HTTP/HTTPS抓包, IOC丰富, IP 地址批量处理, JSON报告, OSINT, Python, SOC工具, ThreatFox, ThreatHunter, Typosquatting检测, VirusTotal, XSS, 域名信誉, 威胁分析, 威胁情报, 威胁评分, 安全报告生成, 安全编排, 安全规则引擎, 安全防御评估, 库, 应急响应, 开发者工具, 态势感知, 恶意IP检测, 数字取证与事件响应, 文件哈希分析, 无后门, 沙箱集成, 漏洞发现, 漏洞情报, 端点安全, 网络信息收集, 网络威胁, 网络安全, 自动化侦查工具, 补丁管理, 请求拦截, 逆向工具, 隐私保护, 黑名单检查