adiallo10/phishing-email-analyzer

# 钓鱼邮件分析器 这是一款命令行工具，用于分析原始邮件的钓鱼行为，提取妥协指标（IOC），并生成一个**透明、可解释的风险评分** —— 评分中的每一项都对应着一个通俗易懂的理由，因此评估结果完全可审计。 核心分析过程**零第三方依赖**，且完全离线运行。 可选的 Claude (Anthropic) 集成可以将分析结果转化为面向非技术用户的友好说明，但这并非必需功能。 ## 开发初衷 钓鱼攻击仍然是排名第一的初始访问媒介。分析师每天都在对可疑邮件进行分类处理，而非技术人员也需要关于如何应对的、清晰且无专业术语的指导。这款工具兼顾两者：既能为 SOC 提供严谨的、基于规则的评估结果，也能为其他人提供可选的 AI 说明。 ## 功能特性 - **RFC-822 解析** — 解析主题、发件人、Reply-To、Return-Path、正文（优先提取 `text/plain`，若不存在则回退至保留链接的剥离版 HTML）以及附件。 - **身份验证检查** — 对来自 `Authentication-Results` 标头的 SPF / DKIM / DMARC 结果进行标准化处理。 - **发件人分析** — 检测 Reply-To / Return-Path 域名不匹配以及显示名称的**品牌仿冒**（如 PayPal、Microsoft、IRS、各大银行等）。 - **链接分析** — 识别 URL 缩短服务、原始 IP 链接、punycode/同形异义词域名，以及发件人与链接域名不匹配的情况。 - **IOC 提取与去活处理** — 提取 URL、域名和 IP，并将其进行**去活渲染**（如 `hxxp://evil[.]com`），确保分享时的安全性。 - **高风险附件** — 标记可执行文件/宏/压缩包等类型的附件。 - **可解释的评分系统** — 提供 0–100 的评分，并列出按权重排序的发现列表及明确的评估结论（低 / 中 / 高 / 严重）。 - **可选的 AI 说明** — `--ai-provider anthropic` 会在设置了 `ANTHROPIC_API_KEY` 时调用 Claude API；否则将使用确定性的本地解释器。 ## 安装 ``` # 从项目根目录 pip install -e . # 可选 extras pip install -e ".[ai]" # Claude-powered explanations ``` 无需安装即可尝试 —— 您可以直接将其作为模块运行。 ## 使用方法 ``` # 分析已保存的 .eml 文件 python -m phishing_analyzer -i sample_data/phishing.eml --explain # 通过 stdin 传入 email cat sample_data/legit.eml | python -m phishing_analyzer --explain # Machine-readable JSON（非常适合 pipelines / SIEM ingest） python -m phishing_analyzer -i sample_data/phishing.eml --json # 使用 Claude API 进行解释 export ANTHROPIC_API_KEY=sk-... python -m phishing_analyzer -i sample_data/phishing.eml --explain --ai-provider anthropic ``` 如果已完成安装，也可以直接使用 `phishing-analyzer` 命令。 当评估结论为**低**时，进程退出码为 `0`；若存在可疑或更严重的情况，退出码则为 `1`，这非常适合在脚本中组合使用。 ### Web UI（可选） 一个小型的 Flask 应用为非技术用户提供了一个粘贴框和清晰的报告： ``` pip install -e ".[web]" flask --app app run # 打开 http://127.0.0.1:5000 ``` 该 Web UI 只是同一核心引擎上的一层薄封装 —— 应用本身不包含任何检测逻辑。 ### 示例 ``` Phishing Email Analysis ============================================================ From: service@paypa1-secure.com Subject: Urgent: Your account has been suspended - verify immediately Risk: CRITICAL (100/100) Verdict: Very likely phishing — do not interact. Report and delete. Auth: SPF=fail DKIM=fail DMARC=fail Findings [+25] (sender) Reply-To domain (mail.ru) differs from From (paypa1-secure.com) [+22] (impersonation) Claims to be 'paypal' but sender domain is paypa1-secure.com [+20] (authentication) DMARC check failed [+18] (link) Link points to a raw IP address ... ``` ## 评分机制说明 每项检测都会提供一个加权的**发现**。各项权重相加并被限制在 0–100 的范围内： | 信号 | 权重 | | ---------------------------------------- | -----: | | Reply-To 域名 ≠ From 域名 | 25 | | 品牌仿冒 (显示名称 vs. 域名) | 22 | | DMARC 失败 | 20 | | 高风险附件 | 20 | | 原始 IP 或 punycode 链接 | 18 | | SPF / DKIM 失败 | 15 | | 紧迫性 / 诱饵话术 | 4–15 | | URL 缩短服务 | 12 | | 链接域名 ≠ 发件人域名 | 10 | 风险等级划分：**低** < 20 · **中** 20–44 · **高** 45–69 · **严重** ≥ 70。 ## 测试 ``` python -m unittest discover -s tests -v ``` 18 个单元测试覆盖了 IOC 提取、邮件解析（包括纯 HTML 邮件）以及端到端分析器的评估结论。 ## 项目结构 ``` phishing_analyzer/ parser.py # raw email -> normalized ParsedEmail auth.py # SPF / DKIM / DMARC header parsing iocs.py # IOC extraction + defanging helpers analyzer.py # rule-based, explainable risk scoring explain.py # local + optional Claude explanations report.py # colored report / JSON rendering cli.py # command-line interface app.py # optional Flask web UI templates/ # web UI template sample_data/ # example phishing + legitimate emails tests/ # unit tests ``` ## 我是如何使用 Claude 的 我将 Claude 视为一个**翻译层，而非检测器**。风险评估结果 100% 由确定性规则（SPF/DKIM/DMARC、发件人不匹配、IOC 分析）决定，因此保持了可审计性和可测试性。Claude 的唯一任务是将结构化的分析结果转化为 2-3 叆平静、无专业术语的话，让非技术人员能够据此采取行动。 具体如下： - **结构化提示词，杜绝虚构事实。** 提示词（详见 [`explain.py`](phishing_analyzer/explain.py)）仅传入引擎已生成的分析结果，并指示 Claude 不得捏造细节。 - **优雅降级。** 如果未设置 `ANTHROPIC_API_KEY` 或未安装 SDK，工具会自动回退到确定性的本地解释器 —— 因此该功能是一项附加福利，绝不会成为依赖项。 - **模型选择。** 使用 `claude-3-5-haiku`，以提供适合分类处理工作流的快速、低成本的摘要。 - **Claude 在开发过程中的辅助作用：** 协助起草品牌仿冒名单和诱饵关键词库，并对邮件解析器中的边缘情况进行压力测试。 ## 免责声明 这是一款用于教育和辅助分析师的启发式分类辅助工具 —— 并非绝对保证。请始终遵循您所在组织的应急响应流程。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：Flask, Python, SOC分析工具, 威胁情报, 开发者工具, 无后门, 电子邮件安全, 逆向工具, 钓鱼邮件分析