antwnakys/phish-analyzer

# 🎣 phish-analyzer     一款**AI 辅助的网络钓鱼电子邮件分析器**。它通过快速的本地启发式方法从电子邮件中提取危险信号指标，然后使用 **Claude** 给出判定结果—— **phishing（钓鱼）/ suspicious（可疑）/ legitimate（合法）**——并附带推理过程和建议的操作。 ``` Phishing analysis ================================================ From : PayPal Security Subject : Urgent: Your account has been suspended - verify within 24 hours Links : 2 Red flags: Reply-To differs from From domain; urgency language; credential language; link uses a raw IP address; visible link text does not match its real destination Heuristic risk: HIGH (score 13) → Verdict : PHISHING (confidence: high) → Reasoning : The sender domain 'paypa1-secure.xyz' impersonates PayPal (note the '1' for 'l'), the visible link says paypal.com but points to a raw IP, and the message manufactures urgency to rush the victim. These are textbook phishing techniques. → Action : Do not click any links. Delete and report as phishing. ``` ## 为什么采用两阶段？ 网络钓鱼检测包含确定性的部分和需要主观判断的部分，因此该工具将其分为两部分： 1. **提取（本地、即时、免费）。** 解析电子邮件并提取出关键信号——发件人与回复地址（reply-to）不匹配、紧急性和索要凭证的语言、基于 IP 的链接、URL 缩短器、可疑的 TLD、**链接文本与实际目的地不匹配**，以及高风险附件。此过程完全离线运行，可处理任意数量的数据。 2. **判断（AI）。** 将这些信号以及正文摘要交给 Claude，由它结合上下文进行权衡——识别出正则表达式无法捕捉的品牌冒充、托辞和语气——并返回**结构化的 JSON 判定结果**。 这反映了真实的邮件安全 pipeline 的工作方式：先经过低成本的过滤器，仅在需要细致分析的地方才使用昂贵的模型。 ## 它检测的内容 | 信号 | 为什么可疑 | | --- | --- | | Reply-To ≠ From 域名 | 回复会被重定向到攻击者 | | 链接文本 ≠ 实际目的地 | 显示为“paypal.com”，但实际上指向其他地方 | | 原始 IP 或缩短的链接 | 隐藏真实目的地 | | 可疑的 TLD（`.xyz`, `.top`, …） | 攻击者偏爱的廉价、一次性域名 | | 制造紧急气氛的语言 | “suspended（暂停）”、“within 24 hours（24小时内）”——施加压力迫使快速行动 | | 索要凭证/支付的语言 | 大多数网络钓鱼的目的 | | 高风险附件（`.exe`, `.js`, …） | 恶意软件投递 | ## 使用方法 ``` # 分析邮件文件（如果设置了 key，则提供 AI 判定）： python -m phishguard samples/phishing.eml # 通过 stdin 传入邮件： cat suspicious.eml | python -m phishguard - # 仅 Heuristics — 完全离线，无需 API key： python -m phishguard --no-ai samples/phishing.eml ``` 使用 `export ANTHROPIC_API_KEY=sk-ant-...` 设置你的密钥。如果未设置，该工具将自动回退到使用启发式风险评估并提示你。对于中/高风险的情况，**退出代码为非零值**，因此它可以作为邮件过滤器或 pipeline 的拦截闸门。 ## 运行测试 ``` pip install -r requirements.txt # for the anthropic SDK pip install pytest pytest ``` 测试套件**完全离线运行**：提取功能基于原始电子邮件字符串进行测试，而 AI 层则使用模拟 client 进行测试——无需 API 密钥或网络连接。 ## 项目结构 ``` phish-analyzer/ ├── phishguard/ │ ├── extract.py # parse email + pull heuristic indicators (stdlib only) │ ├── analyze.py # Claude verdict via structured output │ └── cli.py # command-line interface ├── tests/ # pytest suite (network mocked) └── samples/ # a phishing example and a legitimate one ``` ## 注意事项与道德声明 - 启发式规则是透明且可调的（参见 `extract.py` 中的词汇表和 TLD 集合）。 - 除了将标记出的信号和摘要发送给 Claude API 进行分析外，电子邮件不会被发送到任何其他地方；API 密钥从环境变量中读取，绝不硬编码在代码中。 - 仅供分析您自己的邮件。这是一款防御性工具。 ## 许可证 [MIT](LICENSE) — 可免费使用、学习和在此基础上进行构建。

标签：AI辅助分析, Claude API, Python, 启发式规则, 安全规则引擎, 无后门, 逆向工具, 邮件分析, 钓鱼检测