scottycwilsono/threat-intel-toolkit

# Threat Intel 工具包 一个用于查询威胁情报 API 以支持安全调查和事件响应的命令行工具和 Claude Desktop MCP 服务器。 目前支持：**AbuseIPDB**（IP 信誉） · **VirusTotal**（多引擎分析） · **Shodan**（主机丰富信息） ## 功能介绍 通过三个独立的威胁情报源查询 IP 地址，并返回综合判定结果： **AbuseIPDB** — 众包滥用数据库： - 滥用置信度评分（0–100） - 社区报告总数 - 国家和 ISP **VirusTotal** — 约 70+ 个杀毒软件和威胁情报引擎： - 恶意 / 可疑 / 安全的引擎数量 **Shodan** — 主动互联网扫描器（真实主机数据）： - 开放端口和运行中的服务 - 操作系统（如检测到） - 主机名 - 已知漏洞（CVE） - 最近扫描日期 **综合判定** — MALICIOUS、SUSPICIOUS 或 CLEAN，对所有来源使用 OR 逻辑。任意来源均可提升判定等级；没有任何单一来源能够单独为 IP 洗白。 API 密钥的安全解析机制 — 优先使用 macOS Keychain，并以 `.env` 文件作为回退方案。密钥从不硬编码或提交至源代码控制系统。 ## 环境要求 - Python 3.11+ - macOS（用于 Keychain 集成）或任何使用 `.env` 回退方案的操作系统 - 一个 [AbuseIPDB](https://www.abuseipdb.com) API 密钥 — 免费版包含每天 1,000 次查询 - 一个 [VirusTotal](https://www.virustotal.com) API 密钥 — 免费版包含每分钟 4 次请求 - 一个 [Shodan](https://www.shodan.io) API 密钥 — 免费版包含基本的主机查询 ## 安装 ``` git clone https://github.com/scottycwilsono/threat-intel-toolkit.git cd threat-intel-toolkit python -m venv venv source venv/bin/activate pip install -r requirements.txt ``` ## API 密钥配置 **选项 1 — macOS Keychain（推荐）** 密钥由操作系统加密存储，从不以明文形式写入磁盘： ``` # AbuseIPDB security add-generic-password -s abuseipdb -a api_key -w YOUR_ABUSEIPDB_KEY # VirusTotal security add-generic-password -s threat-intel-toolkit -a virustotal -w YOUR_VT_KEY # Shodan security add-generic-password -s threat-intel-toolkit -a shodan -w YOUR_SHODAN_KEY ``` **选项 2 — `.env` 文件（回退方案）** 在项目根目录创建一个 `.env` 文件。该文件已通过 `.gitignore` 排除在 git 之外： ``` ABUSEIPDB_API_KEY=your_abuseipdb_key_here VIRUSTOTAL_API_KEY=your_virustotal_key_here SHODAN_API_KEY=your_shodan_key_here ``` ## 使用方法 ### CLI ``` python lookup.py --ip ``` **示例：** ``` python lookup.py --ip 185.220.101.45 ``` ### Claude Desktop (MCP) 完成配置（见下文）后，只需用纯英语向 Claude 提问即可： Claude 将自动调用 `check_ip` 或 `check_ip_quick` 并内联返回结果。 ## Claude Desktop 配置 `mcp_server.py` 将该工具包暴露为一个 MCP 服务器，以便 Claude Desktop 能够将您的查询函数作为工具调用。 **1. 找到您的 venv Python 路径**（在激活 venv 的情况下）： ``` which python3 ``` **2. 编辑 Claude Desktop 配置：** ``` vim ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` 将 `mcpServers` 块添加到任何现有键旁边： ``` { "mcpServers": { "threat-intel-toolkit": { "command": "/path/to/your/venv/bin/python3", "args": ["/path/to/threat-intel-toolkit/mcp_server.py"] } } } ``` **3. 验证 JSON：** ``` python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` **4. 重启 Claude Desktop。** 该服务器将作为连接器显示在 Claude Desktop 中。连接成功后，只需用纯英语向 Claude 提问——它将自动调用 `check_ip` 或 `check_ip_quick`。 **故障排除：** 如果服务器未显示，请检查日志： ``` ls ~/Library/Logs/Claude/ ``` 常见原因：Python 路径错误、配置中的 JSON 语法错误、venv 中缺少 `mcp` 包。 ## 输出示例 ``` Querying AbuseIPDB, VirusTotal, and Shodan for 185.220.101.45... IP: 185.220.101.45 ════════════════════════════════════════════ ABUSEIPDB Score: 100/100 Reports: 4,321 Country: DE ISP: Franken-Backbone by Michael Bredel VIRUSTOTAL Malicious: 18/94 engines Suspicious: 0/94 engines Clean: 71/94 engines SHODAN Ports: 22, 80, 443 Services: OpenSSH, nginx OS: Unknown Hostnames: mail.example.com Vulns: None detected Last Seen: 2024-01-14 OVERALL VERDICT: MALICIOUS ⚠️ ════════════════════════════════════════════ ``` 如果 Shodan 没有某个 IP 的扫描数据： ``` SHODAN No data available ``` ## 安全设计决策 | 决策 | 原因 | |---|---| | Keychain 优于 `.env` | API 密钥从不以明文形式写入磁盘 | | 强制使用 HTTPS | 防止密钥以明文形式通过网络发送 | | Shodan 密钥位于查询参数中 | Shodan 的 API 设计限制——已在代码中注明；TLS 仍在传输过程中对其加密 | | 设置请求超时 | 防止在自动化事件响应工作流中发生脚本挂起 | | 失败时返回退出码 | SOAR 剧本和 Shell 流水线依赖退出码运行 | | 错误输出中不包含密钥片段 | 防止在日志中意外泄露机密 | | Shodan 404 = 无数据，而非失败 | 缺少扫描数据属于正常信息反馈，而非错误 | ## 路线图 - [x] AbuseIPDB IP 信誉查询 - [x] VirusTotal 多引擎 IP 分析 - [x] Shodan 主机丰富信息 - [x] Claude Desktop MCP 服务器集成 - [ ] 从文件进行批量 IP 查询 - [ ] 用于 SIEM/SOAR 集成的 JSON 输出标志 ## 许可证 MIT

标签：AbuseIPDB, API集成, Ask搜索, Claude Desktop, ESC4, IP信誉查询, MCP服务器, OSINT, Python, SOC工具, VirusTotal, 可观测性, 多源情报融合, 威胁情报, 安全运营, 密码管理, 开发者工具, 恶意IP检测, 扫描框架, 数据统计, 无后门, 漏洞发现, 端口扫描, 网络安全, 赛博安全, 隐私保护