yusufkuzey95/Phishing-Triage-Cli

# 钓鱼邮件分诊 CLI 一个自动化对可疑邮件进行初步分诊的命令行工具。将其指向一个 `.eml` 文件，它将解析邮件，提取入侵指标 (IOC)，根据 威胁情报服务检查这些 指标，并生成包含推理过程和建议 SOC 操作的钓鱼可能性报告。 本项目作为一个学习项目构建，旨在演示实用的 SOC 分析师工作流。 ## 功能 1. **解析** `.eml` 邮件文件 —— 发件人、主题、关键标头和正文。 2. **提取 IOC** —— 在标头和正文中发现的 URL 和 IP 地址。 3. **丰富 IOC** —— 查询 VirusTotal 和 AbuseIPDB API 获取信誉数据。 4. **报告** —— 分诊摘要：钓鱼可能性判定、背后的推理过程以及 建议的分析师操作。 ## 状态 ✅ 功能已全部完成。里程碑： - [x] M0 — 项目脚手架与规范 - [x] M1 — 解析 `.eml` 文件 - [x] M2 — 提取 IOC (URL + IP) - [x] M3 — 通过 VirusTotal + AbuseIPDB 丰富 IOC - [x] M4 — 分诊报告与评分 - [x] M5 — 优化 (CLI flags、测试、文档) - [x] M6 — 可选 Web UI (Flask) - [x] M7 — 可选 AI 摘要 (Claude API) ## 设置 ``` # 克隆仓库，然后创建并激活虚拟环境 py -m venv .venv .venv\Scripts\Activate.ps1 # Windows PowerShell # 安装依赖 pip install -r requirements.txt # 配置 API keys copy .env.example .env # then edit .env and add your keys ``` API 密钥从本地 `.env` 文件中读取（已被 git-ignore）。从 [VirusTotal](https://www.virustotal.com/) 和 [AbuseIPDB](https://www.abuseipdb.com/) 获取免费密钥。 ## 用法 ``` # 全面分诊（解析、提取 IOCs、通过 APIs 丰富信息、评分） python -m phishing_triage samples/phishing_sample.eml # 快速离线运行 — 跳过 API 调用（无需 keys） python -m phishing_triage samples/phishing_sample.eml --no-enrich # 机器可读的 JSON 输出（用于自动化/管道） python -m phishing_triage samples/phishing_sample.eml --json # 添加简明英语 AI 摘要（可选；需要 ANTHROPIC_API_KEY） python -m phishing_triage samples/phishing_sample.eml --ai-summary # 帮助 python -m phishing_triage --help ``` ### 输出示例  ``` ================================================================ PHISHING TRIAGE REPORT ================================================================ File : samples/phishing_sample.eml From : PayPal Security Subject: Your account has been limited - action required VERDICT: High phishing likelihood (score 13) Reasoning: [+2] SPF check failed (sending server not authorized for the domain) [+1] DKIM not valid (dkim=none) [+3] DMARC failed (message fails the domain owner's anti-spoofing policy) [+2] From domain (paypa1-alerts.com) does not match Return-Path domain (sketchy-mailer.ru) [+2] Reply-To domain (account-verify-help.com) differs from From domain (paypa1-alerts.com) [+3] IP 185.220.101.45 has high AbuseIPDB score (100, 116 reports) Indicators of compromise (defanged): URL: hxxp://paypa1-alerts[.]com/verify?id=8842 URL: hxxps://secure-paypa1[.]account-verify-help[.]com/login IP : 203[.]0[.]113[.]77 IP : 185[.]220[.]101[.]45 Recommended actions: - Do NOT click any links or open attachments. - Quarantine/delete the email from all recipient mailboxes. - Block the malicious domains and IPs at the mail gateway/firewall. - Search mail logs for other recipients of the same campaign. - Escalate to the incident-response process. ``` ## Web UI (可选) 包含一个轻量级的 Flask 前端，用于快速的视觉演示。它是 CLI 使用的**相同引擎**之上的一个薄 层 —— 它解析粘贴的邮件并调用 完全相同的 `build_report()` 函数，因此没有重复的逻辑。 ``` pip install flask # only needed for the web UI python app.py # then open http://127.0.0.1:5000 ``` 粘贴邮件的**原始源码**（例如 Gmail → *显示原始邮件*）并点击 Analyze。 访问 `http://127.0.0.1:5000/?demo=1` 可立即查看内置的示例报告。  ## 评分机制 每个检测器都会提供加权后的 `(points, reason)` 信号；总分将映射到一个判定结果。 没有单一信号能决定结果 —— 判定基于**证据的权重**，这与分析师的 推理方式一致。*干净* 的信誉结果绝不会降低分数，因为全新的钓鱼 URL 只是未被编目（"zero-day"），并不能证明其是安全的。 | 信号来源 | 示例 | |---|---| | 邮件认证 | SPF / DKIM / DMARC 失败 | | 域名一致性 | `From` 与 `Return-Path` 与 `Reply-To` 不匹配 | | IOC 信誉 | 高 AbuseIPDB 分数、被 VirusTotal 标记的 URL | 判定阈值：**High** ≥ 6，**Medium** ≥ 3，否则为 **Low**。 ## AI 摘要 (可选) 使用 `--ai-summary`（以及 `ANTHROPIC_API_KEY`），该工具将调用 Claude API 将报告转化为 2-4 句用于工单的简明英语摘要。LLM **起辅助作用，而非做出决定** —— 确定性加权分数仍然是 事实来源，因此判定结果保持可审计。为了限制 prompt-injection 风险， 模型接收的是*结构化的发现*（而非原始邮件），并被要求将该 内容视为数据而非指令。如果没有密钥，该工具将像以前一样运行。 ## 测试 ``` python -m pytest ``` 测试套件完全离线运行 —— 网络调用已被 mock，因此测试时不需要 API 密钥。 ## 技术 Python 3.13 · 标准库 `email` 解析器 · `requests` · `python-dotenv` · `pytest` · `flask` (可选 Web UI) · `anthropic` (可选 AI 摘要) ## 许可证 基于 [MIT License](LICENSE) 发布。

标签：Flask, Python, SOC运营, 威胁情报, 安全规则引擎, 开发者工具, 无后门, 逆向工具, 钓鱼邮件分析