shahbaaz-devsec/PhishHunter

# PhishHunter ## 概述 **PhishHunter** 是一款独立的 Python CLI 工具，专为 SOC 分析师和安全专业人员设计，用于对可疑钓鱼邮件进行端到端取证分析。它将邮件头取证、DNS 记录分析、TLS 证书验证、URL/附件情报以及加权风险评分集成到一个命令行界面中——生成分析师级别的 JSON 和 HTML 报告。 该工具旨在 Kali Linux 及任何装有 **Python 3.10 或更高版本** 且 **无需任何强制性外部依赖** 的类 Unix 系统上运行——整个流程仅使用 Python 的标准库，外加一些无需注册的可选免费公共 API。 ## 核心功能 ### 邮件取证 - 端到端解析 `.eml` 文件 —— 完整头信息、多部分正文、附件 - **接收链分析** —— 自下而上追踪邮件经过的每一跳路径 - **发件人 IP 提取** —— 识别邮件的真实来源服务器 - **认证结果解读** —— 从头信息读取 SPF、DKIM 和 DMARC 结果 - **欺骗启发式检测** —— 显示名称与本地部分不匹配、Reply-To 异常、Return-Path 不匹配 - **品牌冒用检测** —— 标记声称来自 Microsoft、Google、银行等但来自无关域的邮件 ### DNS 记录取证 - 通过 **DNS-over-HTTPS** 进行全面 DNS 查询 —— 主要使用 Cloudflare `1.1.1.1`，备用 `8.8.8.8` - 所有记录类型：**A, AAAA, MX, TXT, NS, CNAME, SOA, PTR, SRV, CAA** - **邮件认证策略提取** —— 解析 SPF 强度（严格/软性/宽松）、DMARC 策略（`p=none|quarantine|reject`） - **DKIM 选择器探测** —— 测试常见选择器（`default`, `google`, `selector1`, `k1`, `s1`, `mail` 等） - **发件人 IP 的反向 DNS** —— 根据声称的发件人域验证 PTR 记录 ### TLS / SSL 证书取证 - 通过端口 443 原始套接字**实时获取证书** - 解析主题、颁发者、有效期、主题备用名称（SANs）、序列号 - **主机名匹配验证** —— 对照证书的 CN/SAN - **计算证书剩余有效天数** —— 并设置临界/警告阈值 - 通过 [crt.sh](https://crt.sh) 进行**证书透明度查询** —— 查找历史证书和仿冒域名 - **可选的 SSL Labs 集成** —— 用于等级查询（速度较慢，需要 `--ssllabs` 标志） ### URL 与域名情报 - 从 HTML 和纯文本邮件正文中提取 URL - **URLhaus** 信誉查询（abuse.ch，免费） - **可选的 VirusTotal** 集成（需要免费 API 密钥） - **RDAP** 域名年龄检查 —— 标记新注册域名（`< 30 天`） - 域名仿冒、同形异义字符攻击、可疑顶级域（`.xyz`, `.top`, `.click` 等）的启发式检测 ### 附件分析 - 计算每个附件的 **SHA-256 和 MD5** 哈希值 - **香农熵** —— 检测加壳/加密/压缩的有效载荷 - **高风险扩展名检测** —— `.exe`, `.scr`, `.iso`, `.lnk`, `.hta`, 启用宏的 Office 文档等 - **密码保护压缩文件检测**（ZIP 文件） ### 风险评分与报告 - **加权 0-100 风险评分** —— 综合邮件头取证、URL 信誉、附件风险、DNS 认证态势、TLS 发现、品牌冒用以及正文关键词密度 - **五级风险分类**：`MINIMAL` → `LOW` → `MEDIUM` → `HIGH` → `CRITICAL` - **脱敏 IOC 输出** —— URL 和 IP 以分析师安全格式呈现（`hxxps://evil[.]com`） - **JSON 报告** —— 机器可读，适用于 SOAR 集成 - **HTML 报告** —— 暗色主题的分析师仪表盘，包含风险指示器、认证表格、DNS 记录、TLS 发现以及精选调查工具链接 - **批量处理** —— 一次运行分析整个目录的 `.eml` 文件 - **内置自检** —— 使用嵌入的钓鱼样本验证流程 ## 使用场景 - **SOC 一/二线分析师** 分拣上报的钓鱼邮件 - **事件响应人员** 调查商业电子邮件入侵（BEC）案件 - **威胁情报团队** 从钓鱼活动中提取 IOC - **安全研究人员** 研究钓鱼基础设施（NS 枢纽、证书透明度） - **网络安全教育者和学生** 学习邮件取证实践 - **个人用户** 在点击前验证可疑邮件 ## 要求 | 要求 | 版本 | 备注 | |---|---|---| | **Python** | 3.10 或更高 | 使用现代类型提示、数据类 | | **操作系统** | Linux、macOS、Windows 上的 WSL | 在 Kali Linux 2024.x / 2025.x 上测试 | | **网络** | 互联网访问 | 可选 —— 使用 `--no-dns --no-tls` 时工具可离线工作 | | **外部库** | 无需 | 纯 Python 标准库 | | **可选：VirusTotal API 密钥** | 免费套餐 | 通过 VirusTotal 启用 URL/文件信誉查询 | ## 安装说明 ### 选项 1 —— 从 GitHub 克隆（推荐） ``` git clone https://github.com/shahbaaz-devsec/phishhunter.git cd phishhunter chmod +x phishhunter.py python3 phishhunter.py --self-test ``` ### 选项 2 —— 直接下载 ``` wget https://raw.githubusercontent.com/shahbaaz-devsec/phishhunter/main/phishhunter.py chmod +x phishhunter.py python3 phishhunter.py --self-test ``` ### 选项 3 —— 系统级安装（可选） 克隆后，安装为系统命令： ``` sudo cp phishhunter.py /usr/local/bin/phishhunter sudo chmod +x /usr/local/bin/phishhunter # 现在可从任何地方使用 phishhunter --self-test phishhunter suspicious.eml ``` ## 快速开始 ``` # 1. 运行内置自检（验证流水线） python3 phishhunter.py --self-test # 2. 分析可疑邮件 python3 phishhunter.py suspicious.eml # 3. 打开生成的 HTML 报告 xdg-open phish-hunter-reports/suspicious.html ``` ## 详细用法 ### 分析单封邮件 ``` python3 phishhunter.py path/to/email.eml ``` 输出： - `./phish-hunter-reports/email.json` —— 完整的机器可读取证数据 - `./phish-hunter-reports/email.html` —— 分析师级别的可视化报告 - `./phish-hunter-reports/email_attachments/` —— 提取的附件，用于分拣 ### 批量分析目录 ``` python3 phishhunter.py --batch ./phishing_samples/ --format html ``` 处理目录中的每个 `.eml` 和 `.msg` 文件，为每个文件生成报告，并在结束时打印摘要表格。 ### 快速模式（无 DNS，无 TLS） 适用于气隔环境或快速批量分拣： ``` python3 phishhunter.py email.eml --no-dns --no-tls ``` ### 配合 VirusTotal 集成 ``` python3 phishhunter.py email.eml --vt-key YOUR_FREE_VT_API_KEY ``` 在 [virustotal.com](https://www.virustotal.com) 获取免费密钥。 ### 最大深度（较慢 —— 包含 SSL Labs） ``` python3 phishhunter.py email.eml --ssllabs ``` 为每个发件人域名添加 SSL Labs 等级查询。每个域名约增加 60 秒。 ## 命令行参考 ``` usage: phishhunter [-h] [--batch DIR] [--output OUTPUT] [--format {json,html,both}] [--vt-key KEY] [--timeout TIMEOUT] [--no-dns] [--no-dkim-probe] [--no-tls] [--ssllabs] [--self-test] [--quiet] [--version] [file] positional arguments: file Path to a .eml (or .msg) email file options: -h, --help Show help message and exit --batch DIR Analyse all .eml files in a directory --output, -o OUTPUT Output directory (default: ./phish-hunter-reports) --format, -f {json,html,both} Report format(s) (default: both) --vt-key KEY VirusTotal API key (optional) --timeout TIMEOUT HTTP request timeout in seconds (default: 15) --no-dns Disable DNS forensics (faster, less complete) --no-dkim-probe Skip DKIM selector probing --no-tls Disable TLS certificate forensics --ssllabs Run SSL Labs grade lookup (slow ~60s per domain) --self-test Run built-in self-validation test --quiet, -q Suppress banner and verbose output --version, -V Show version ``` ## 输出报告 ### JSON 报告 完整的取证数据结构，包括： - 邮件元数据和头信息 - 所有提取的 URL 及其信誉数据 - 所有附件及其哈希值和熵 - 发件人和 URL 域的 DNS 记录 - TLS 证书详情和证书透明度数据 - 欺骗和品牌冒用指标 - 最终加权风险评分及贡献因素 非常适合 SOAR 摄取、SIEM 富化或进一步自动化处理。 ### HTML 报告 可视化的分析师仪表盘，包含： - 风险评分仪表 - 头信息分析表 - 接收跳数追踪 - 每个调查域的 DNS 取证 - TLS 证书分解及主机名匹配验证 - URL 分析表（包含 VirusTotal 和 URLhaus 列） - 附件哈希值和熵 - 精选的调查工具链接，用于进一步追踪 设计用于包含在事件工单和干系人沟通中。 ## 架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ PhishHunter Pipeline │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Input: .eml / .msg file │ │ │ │ │ ▼ │ │ ┌─────────────┐ Parse headers, bodies, attachments │ │ │ EmailParser │ │ │ └─────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────┐ SPF/DKIM/DMARC, Received hops, │ │ │ HeaderForensics │ spoof indicators, originating IP │ │ └──────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────┐ Extract URLs from HTML and text │ │ │ URLExtractor │ │ │ └──────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ URLhaus + optional VirusTotal + │ │ │ URLChecker │ RDAP domain age + heuristics │ │ └─────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────┐ SHA-256/MD5 hashes, Shannon entropy, │ │ │ AttachmentTriage │ risky extension detection │ │ └──────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ A/AAAA/MX/TXT/NS/CNAME/SOA/PTR/ │ │ │ DNSAnalyzer │ SRV/CAA + SPF/DKIM/DMARC parsing │ │ └─────────────┘ via Cloudflare + Google DoH │ │ │ │ │ ▼ │ │ ┌───────────────────────┐ Live cert + crt.sh transparency │ │ │ TLSCertificateAnalyzer│ + optional SSL Labs grade │ │ └───────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ Weighted risk scoring across │ │ │ PhishingScorer │ 7 dimensions + level classification │ │ └─────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────┐ JSON + HTML reports │ │ │ ReportGenerator │ │ │ └──────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ## 使用的免费公共源 所有外部服务均免费，**无需 API 密钥**（VirusTotal 除外，为可选）： | 服务 | 用途 | 需要 API 密钥 | |---|---|---| | **Cloudflare DNS over HTTPS** | DNS 记录查询 | 否 | | **Google DNS over HTTPS** | DNS 备用 | 否 | | **URLhaus (abuse.ch)** | URL 信誉 | 否 | | **RDAP.org** | 域名年龄 / WHOIS 替代 | 否 | | **crt.sh** | 证书透明度日志 | 否 | | **SSL Labs** | TLS 等级查询 | 否（有速率限制） | | **VirusTotal** | URL/文件信誉 | **可选**（免费套餐） | ## 示例输出 ``` ====================================================================== PhishHunter — Analysing: suspicious_microsoft_alert.eml ====================================================================== ┌─ EMAIL FORENSICS ────────────────────────────────────────────────────┐ Risk Score: 78.5/100 (CRITICAL) From: "Microsoft Security" Subject: URGENT: Your account has been suspended Originating IP: 185.220.101.45 SPF / DKIM / DMARC: fail / none / fail URLs: 3 (2 suspicious) Attachments: 1 (1 suspicious) ┌─ DNS FORENSICS (3 domains queried) ─────────────────────────────────┐ ● microsoft-secure.xyz (auth strength: 5/100) A : 185.220.101.45 MX : 10 mail.cheaphost.ru SPF : MISSING DMARC : MISSING DKIM : 0 selectors found ⚠ No SPF record — domain easily spoofable ⚠ No DMARC record — receivers cannot verify policy ┌─ TLS / CERT FORENSICS (2 domains) ──────────────────────────────────┐ ● microsoft-secure.xyz [ok] Subject : CN=microsoft-secure.xyz Issuer : Let's Encrypt Expires : in 89 days Hostname : matches crt.sh : 14 certificates, 12 unique names 🎭 Brand Impersonation Detected: - Brand impersonation: display name claims 'microsoft' but sender domain is microsoft-secure.xyz 🚩 Key Indicators: - Authentication failures: 2 - Display name 'Microsoft Security' does not match local part 'support' - DNS: sender domain microsoft-secure.xyz has no SPF record - DNS: sender domain microsoft-secure.xyz has no DMARC policy - TLS: brand-looking domain microsoft-secure.xyz uses free Let's Encrypt cert — common phishing pattern ``` ## 局限性 PhishHunter 设计用于**静态分析**，并具有以下有意限制： - **无 URL 爆破**：URL 会根据信誉数据库进行检查，但不会实际访问。如需动态分析，请手动使用 Any.Run、Hybrid Analysis 或 URLScan.io。 - **无恶意软件沙箱分析**：附件会被哈希化并进行静态分析。如需行为分析，请提交至专用沙箱。 - **无实时邮件网关集成**：这是一款离线分析工具。与 Microsoft 365、Proofpoint 或 Mimecast 集成需要额外连接器。 - **无 SOAR 编排**：JSON 输出与 SOAR 兼容，但 PhishHunter 本身不编排响应操作。 - **DKIM 探测基于选择器**：如果某个域使用非常见的 DKIM 选择器，工具可能无法检测到。探测覆盖了精心策划的常见选择器列表。 - **SSL Labs 有速率限制**：免费的 SSL Labs API 有严格的速率限制；批量使用 SSL Labs 并不现实。 - **有限的 `.msg` 解析**：虽然 CLI 接受 `.msg` 文件，但完整的 Outlook MSG 格式解析需要额外依赖。为获得最佳结果，请在分析前将 MSG 转换为 EML。 ## 路线图 计划中的增强功能（无特定顺序）： - [ ] 通过 `extract-msg` 集成支持 `.msg` 文件 - [ ] STIX 2.1 IOC 导出，用于威胁情报共享 - [ ] MISP 集成，用于 IOC 提交 - [ ] Cisco Talos 和 IBM X-Force Exchange 信誉集成 - [ ] AbuseIPDB 集成，用于发件人 IP 信誉 - [ ] 通过 YAML 配置文件配置评分权重 - [ ] 通过 `oletools` 提取邮件附件宏 - [ ] 通过 `pdfid` / `pdf-parser` 检测 PDF 恶意对象 - [ ] 可选的富终端界面（使用 `rich` 库） - [ ] 容器化版本（Docker） - [ ] 批量报告聚合和趋势仪表盘 欢迎对以上任何功能做出贡献 —— 请参阅 [贡献指南](#contributing)。 ## 贡献指南 欢迎贡献、报告错误和提出功能请求。 ### 报告错误 创建 issue 时，请包含： - PhishHunter 版本（`python3 phishhunter.py --version`） - Python 版本（`python3 --version`） - 操作系统及版本 - 使用的完整命令 - 完整的错误输出或意外行为 - 适用的已清理邮件样本（移除所有 PII） ### 提交拉取请求 1. Fork 仓库 2. 创建功能分支（`git checkout -b feature/your-feature`） 3. 进行修改并包含清晰的提交信息 4. 针对自检进行测试（`python3 phishhunter.py --self-test`） 5. 创建拉取请求并描述更改内容 ## 作者 **Mohammad Shahbaaz Ahmed** 网络安全与自动化工程师 - **GitHub**: [github.com/shahbaaz-devsec](https://github.com/shahbaaz-devsec) - **LinkedIn**: [linkedin.com/in/mohammad-shahbaaz-ahmed-138a423bb](https://www.linkedin.com/in/mohammad-shahbaaz-ahmed-138a423bb) 教育背景： - **网络安全与道德黑客** 执行研究生文凭 —— 印度理工学院鲁尔基分校 - **网络安全管理** 全球 MBA —— 日内瓦SSBM商学院 职业背景涵盖后端自动化、AI 工作流工程和薪资系统集成——目前正转向安全运营，专注于自动化增强的 SOC 工作流。 ## 许可证 本项目仅供**教育和授权的 SOC 使用**。 允许： - 为个人和教育目的使用、学习和修改代码 - 在您合法拥有或有权分析的电子邮件上运行该工具 - 在安全培训、CTF 和学术研究中使用该工具 **不得**： - 使用此工具骚扰、监视或攻击他人 - 分析您无权访问的电子邮件 - 未经作者书面许可出售或重新品牌化此工具 作者对滥用行为不承担任何责任。使用风险自负，并遵守您所在司法管辖区的适用法律。 ## 致谢 本工具的实现得益于这些免费的公共社区及其维护者： - **abuse.ch** —— 感谢 [URLhaus](https://urlhaus.abuse.ch) 和威胁情报共享 - **Cloudflare** —— 感谢在 `1.1.1.1` 提供免费公共 DNS-over-HTTPS - **Google Public DNS** —— 感谢在 `8.8.8.8` 提供免费公共 DNS-over-HTTPS - **Sectigo** —— 感谢 [crt.sh](https://crt.sh) 证书透明度搜索服务 - **Qualys** —— 感谢 [SSL Labs](https://www.ssllabs.com) 服务器测试 API - **VirusTotal** —— 感谢免费的信誉 API - **RDAP.org** —— 感谢现代的 WHOIS 替代协议 - **MXToolbox**、**EasyDMARC** 以及更广泛的电子邮件安全社区提供的文档和标准

**PhishHunter v1.0** —— *一封一封钓鱼邮件，精心打造。* 由 [Mohammad Shahbaaz Ahmed](https://github.com/shahbaaz-devsec) 用心制作 ⭐ 如果这个工具对您有帮助，请考虑给仓库点个星

标签：DFIR工具, DNS分析, masscan, SOC工具, TLS验证, 入侵防御系统, 取证报告, 威胁情报, 威胁情报平台, 威胁猎捕, 安全运营, 开发者工具, 扫描框架, 数字取证, 文档结构分析, 漏洞发现, 电子邮件取证, 电子邮件安全研究, 网络安全, 自动化脚本, 逆向工具, 邮件头分析, 邮件安全, 钓鱼分析, 钓鱼检测, 防御性安全工具, 隐私保护, 风险评分