forgehk/phish-forge

# 钓鱼邮件分析工具 []() [](LICENSE) ## 功能介绍 将原始邮件（`.eml`）交给 `phish-forge`，它会返回结构化的判定结果： ``` phish-forge analyze samples/phishing_sample.eml ``` ``` phish-forge verdict: PHISHING (score 78/100) Headers ! SPF fail (sender 199.x.x.x not in spf for paypal.com) ! DKIM none (no signature) ! DMARC fail (alignment failed) ! From display 'PayPaI Security' (capital-I instead of capital-L) URLs (3 found) ! http://paypa1.com-secure-login.tk/verify typosquat + .tk TLD ! https://bit.ly/3xyZ123 link shortener hides destination - https://paypal.com/legal legitimate Body heuristics ! urgency_language "Your account will be locked in 24 hours" ! credential_request "click here to verify your password" ! generic_greeting "Dear Customer," Verdict: PHISHING — high confidence ``` ## 重要性说明 在安全运营中心（SOC）流程中，真正的钓鱼检测需要结合以下四个方面： 1. **头部认证** — SPF/DKIM/DMARC 是否实际匹配？ 2. **URL 信誉** — 目标地址是已知的钓鱼域名、拼写错误模仿域名、短链接，还是同形异义字？ 3. **内容启发式分析** — 紧急性语言、索取凭证的模板、显示名与信封发件人不匹配。 4. **可选的 LLM 分析** — 用于启发式方法可能遗漏的情况（语气、社会工程学模式）。 `phish-forge` 是一个将以上四方面串联起来的学习练习。对于 **SOC 分析师 / 蓝队** 面试很有用，因为它演示了在 Splunk、Elastic 或任何 SIEM 关联规则中你会实现的逻辑。 ## 安装与运行 ``` pip install phish-forge # 命令行界面 phish-forge analyze suspicious.eml phish-forge analyze suspicious.eml --json | jq . # HTTP 服务（通过 curl 投递邮件，集成到 SOAR playbook） phish-forge serve --port 8000 curl -F "file=@suspicious.eml" http://localhost:8000/analyze ``` ## 架构设计 ``` ┌─────────────────────────┐ │ phish-forge CLI │ │ / FastAPI app │ └────────────┬────────────┘ ▼ ┌─────────────────────────┐ │ EML parser │ (stdlib email module) │ headers · body · urls │ └────────────┬────────────┘ ▼ ┌─────────────────┬─────────────┴────────────┬──────────────────┐ ▼ ▼ ▼ ▼ ┌────────┐ ┌───────────────┐ ┌─────────────┐ ┌──────────────┐ │ header │ │ URL scorer │ │ body hcheck │ │ LLM verdict │ │ auth │ │ shortener / │ │ urgency, │ │ (optional) │ │ (SPF/ │ │ typosquat / │ │ cred req, │ │ │ │ DKIM/ │ │ homoglyph / │ │ generic │ │ │ │ DMARC) │ │ .tk/.ml/.gq │ │ greeting │ │ │ └────┬───┘ └───────┬───────┘ └──────┬──────┘ └──────┬───────┘ └────────────────┴───────────────┬────────┴──────────────────┘ ▼ ┌──────────────────────────┐ │ weighted score 0-100 │ │ verdict: phishing / │ │ suspicious / benign │ └──────────────────────────┘ ``` 每个模块都可独立测试；评分器是一个简单的加权求和，方便您进行调优。 ## 当前已实现的启发式规则 **URL 启发式规则**（每条规则都是一个信号——合并为每个 URL 的评分）： - 顶级域名（TLD）在高风险列表上（`.tk`、`.ml`、`.gq`、`.cf`、`.zip`、`.mov`） - URL 中包含 IP 地址 - 常见域名拼写错误模仿（与知名品牌 Levenshtein 距离 ≤ 1） - 同形异义字混淆（例如 `paypaI` 使用大写 I，`аpple` 使用西里尔字母 'а'） - 主机名是短链接服务（`bit.ly`、`tinyurl`、`t.co`、`goo.gl` 等） - 主机名与可见链接文本不匹配（锚文本与 href 不匹配） - 路径关键词（`verify`、`secure`、`account-update`、`login-reset`） **邮件正文启发式规则：** - 紧急性语言（`24 hours`、`immediately`、`account locked`、`final notice`） - 索取凭证的语言（`enter your password`、`verify your login`） - 通用称呼语（`Dear Customer`、`Dear Sir/Madam`） - Reply-to 与 From 地址不匹配 - 纯文本与 HTML 内容不一致 **邮件头部启发式规则：** - 解析 SPF / DKIM / DMARC 的 `Authentication-Results` - `From:` 显示名与信封 `Return-Path:` 不匹配 - 可疑的 `Received:` 链（私有 IP 伪造公网跳数、来源国变化） ## API 模式 ``` phish-forge serve ``` 然后： ``` POST /analyze Content-Type: multipart/form-data; boundary=... (eml file) → 200 OK { "verdict": "phishing", "score": 78, "headers": { ... }, "urls": [ ... ], "body_signals": [ ... ] } ``` 可以将其集成到 SOAR 运行手册中，或者从 Slack 机器人接收表单调用它。 ## 路线图 - [x] 头部 / URL / 正文启发式规则 - [x] 命令行界面（CLI）+ FastAPI - [x] 用于 SOAR 集成的 JSON 输出 - [ ] 可插拔的 LLM 判定解释器（Anthropic / OpenAI） - [ ] 附件沙箱检测（PE / Office 宏检测） - [ ] URL 主机名的 WHOIS 注册时间检查 - [ ] 实时信誉查询（Google Safe Browsing、PhishTank、URLhaus） - [ ] STIX 2.1 威胁指标导出 ## 许可证 [MIT](LICENSE) *由 [@forgehk](https://github.com/forgehk) 构建 — [DarkForge AI](https://darkforgeai.com)*

标签：AV绕过, DKIM验证, DMARC验证, FastAPI, Python, SPF验证, URL声誉, URL评分, 启发式分析, 大语言模型分析, 头部取证, 安全运营中心工具, 文档结构分析, 无后门, 检测引擎, 正文启发式分析, 电子邮件安全, 网络安全, 逆向工具, 邮件分析, 邮件取证, 邮件安全检测, 钓鱼检测, 钓鱼邮件分析器, 隐私保护