0xlam/PhishSage

# PhishSage PhishSage 是一个轻量级钓鱼分析工具包，用于解析原始邮件、检查邮件头、通过多层启发式分析链接和域名，并输出结构化的 JSON 结果，以便进行快速、自动化的调查。 []() []() []() ## 1. 核心功能 PhishSage 旨在保持极简，专注于以下核心功能： * **邮件头分析** * 提取规范化的发件人相关邮件头（From、Reply-To、Return-Path、Message-ID） * 从 Authentication-Results 中解析 SPF、DKIM 和 DMARC 结果 * 对 From、Reply-To 和 Return-Path 执行对齐检查 * 验证 Message-ID 域名的一致性 * 检测 Reply-To 和 Return-Path 邮件头中免费邮件提供商的使用情况 * 通过比较 Date 邮件头和第一个 Received 跃点来检查时间戳的合理性 * 查询 WHOIS 域名年龄，并标记新注册或即将过期的域名 * 验证发件人相关域名的 MX 记录 * 为发件人相关域名查询 Spamhaus DBL * 将所有发现汇总为带有合并警报的结构化 JSON * **附件处理** * 列出附件的 MIME 类型和大小 * 安全地提取附件（避免覆盖） * 计算哈希值（MD5、SHA1、SHA256） * 通过 SHA256 进行可选的 VirusTotal 扫描 * 使用 YARA 规则扫描附件（单文件、多文件或目录；递归并过滤出有效的 .yar/.yara 文件） * 详细模式显示匹配的字符串及其偏移量和十六进制数据 * **链接 / URL 分析** * 从邮件正文或邮件头中提取 URL * 检测使用原始 IP 地址而非域名的 URL * 标记可疑或不常见的顶级域名 (TLD) * 识别过多或嵌套的子域名，忽略常见的子域名（例如 "www"） * 识别短链接（bit.ly、tinyurl.com 等） * 计算域名和子域名的 Shannon 熵，以发现混淆行为 * 执行 SSL/TLS 证书检查（颁发者、有效期、域名匹配、过期时间） * 通过 WHOIS 查询域名年龄，并标记新注册或即将过期的域名 * VirusTotal URL 查询以获取威胁情报 * 可选的重定向链跟踪，以揭示隐藏的目标地址 * 检查仅包含数字的可注册域名 * 检测使用常被滥用的网络平台和服务的 URL * 标记具有过深路径的 URL ## 2. 安装 ``` # 选项 A: 从 GitHub 安装 git clone https://github.com/0xlam/PhishSage.git cd PhishSage python3 -m venv venv # Linux / macOS source venv/bin/activate # Windows (PowerShell) venv\Scripts\Activate.ps1 pip install -e . # --------------------------------------------------- # 选项 B: 从 PyPI 安装 pip install phishsage # --------------------------------------------------- # (可选) 配置 VirusTotal API key # Linux / macOS export VIRUSTOTAL_API_KEY="your_virustotal_api_key" # Windows (PowerShell) setx VIRUSTOTAL_API_KEY "your_virustotal_api_key" ``` ## 3. 命令行界面使用 PhishSage 提供了一个具有三种主要模式的命令行界面：`headers`、`attachments` 和 `links`。`headers` 和 `links` 模式以 JSON 格式输出结果，而 `attachments` 模式仅生成人类可读的摘要。 ### 主要帮助信息 ``` phishsage -h ``` **输出：** ``` usage: phishsage [-h] {headers,attachments,links} ... PhishSage positional arguments: {headers,attachments,links} headers Analyze email headers for anomalies or indicators attachments Analyze or extract attachments links Analyze links in email content options: -h, --help show this help message and exit ``` ### 邮件头分析 ``` phishsage headers -h ``` **选项：** ``` usage: phishsage headers [-h] -f FILE [--heuristics] [--enrich [{mx,spamhaus,domain_age,all} ...]] [--json] options: -h, --help show this help message and exit -f, --file FILE Email file to analyze (.eml) --heuristics Analyze headers for suspicious patterns and anomalies --enrich [{mx,spamhaus,domain_age,all} ...] Add threat-intel enrichment to header analysis (mx, spamhaus, domain_age). Requires --heuristics. --json Output full details in JSON format ``` ### 附件处理 ``` phishsage attachments -h ``` **选项：** ``` usage: phishsage attachments [-h] -f FILE [--list] [--extract DIR] [--hash] [--vt-scan] [--yara PATH [PATH ...]] [--yara-verbose] [--json] options: -h, --help show this help message and exit -f, --file FILE Email file to analyze (.eml) --list List attachments only --extract DIR Extract attachments to specified directory --hash Compute hashes (MD5, SHA1, SHA256) for each attachment --vt-scan Check attachments against VirusTotal by SHA256 --yara PATH [PATH ...] Scan attachments with YARA rules. Paths can be files or directories; directories are scanned recursively for .yar/.yara files. --yara-verbose Show detailed string matches and offsets when YARA rules hit --json Output full details in JSON format ``` ### 链接 / URL 分析 ``` phishsage links -h ``` **选项：** ``` usage: phishsage links [-h] -f FILE [--extract] [--vt-scan] [--check-redirects] [--heuristics] [--enrich [{all,domain_age,certificate,virustotal,redirects} ...]] [--json] options: -h, --help show this help message and exit -f, --file FILE Email file to analyze (.eml) --extract Extract URLs from the email body --vt-scan Query VirusTotal for URL reputation --check-redirects Follow HTTP redirects and show chain --heuristics Run phishing detection heuristics (use --enrich to add extra data) --enrich [{all,domain_age,certificate,virustotal,redirects} ...] Add extra analysis to heuristics (requires --heuristics) --json Output full details in JSON format ``` ## 4. 配置 PhishSage 将配置值存储在项目配置文件 (`config.toml`) 或环境变量中。您可以安全调整的主要项目包括： * `VIRUSTOTAL_API_KEY` — 用于 VirusTotal 扫描的 API 密钥。 * `MAX_REDIRECTS` — 检查重定向链时要遵循的最大重定向次数。 * `THRESHOLD_YOUNG`、`THRESHOLD_EXPIRING` — 域名年龄/过期阈值（以天为单位）。早于 `THRESHOLD_YOUNG` 或在 `THRESHOLD_EXPIRING` 天内过期的域名将被标记为潜在可疑域名。 * `ABUSABLE_PLATFORM_DOMAINS`、`SUSPICIOUS_TLDS`、`SHORTENERS` — 用于 URL/链接分析的启发式列表。 * `SUBDOMAIN_THRESHOLD`、`TRIVIAL_SUBDOMAINS` — 用于子域名启发式分析，以识别过多或有意义的子域名。 * `FREE_EMAIL_DOMAINS` — 可能表明是临时或低信任度地址的免费电子邮件提供商。 * `DATE_RECEIVED_DRIFT_MINUTES` — 邮件头中 `Date` 头与第一个 `Received` 跃点之间允许的最大时间差（以分钟为单位）。 *注意：只有在您了解对误报和整体检测准确性的潜在影响时，才修改阈值或启发式列表。* ## 5. 范围与局限性 * **专注的功能：** PhishSage 不是一个完整的邮件取证套件。它优先考虑启发式分析、快速分类和丰富信息，而不是深入的取证分析。 * **依赖网络的检查：** WHOIS、VirusTotal、MX 和 SSL 检查依赖于外部服务；由于连接问题或 API 限制，结果可能会有所不同或失败。 * **附件处理：** 目前仅限于列出、提取、散列和可选的 VirusTotal 扫描。完整的启发式附件分析将在未来的版本中引入。 * **输出格式：** 默认情况下输出人类易读的格式。使用 `--json` 获取所有模式的详细结构化数据。 * **预期用途：** 专为调查支持和信息丰富而设计。不适用于生产邮件系统中的自动拦截或执行。 * **不断发展的覆盖范围：** 各部分当前的检查功能有限；未来的版本中将添加更多的启发式规则和增强的分析功能。 ## 6. 贡献 欢迎对 PhishSage 作出贡献！您可以通过以下方式帮助改进项目： * 为邮件头、附件和链接添加或完善启发式检查。 * 扩展 `config.toml` 中的列表。 * 改进解析、规范化或输出处理。 * 报告错误或提出改进建议。 在提交更改之前，请确保它们已经过充分测试，并保持代码的清晰性、安全性和可靠性。我们特别感谢那些能增强检测覆盖率、减少误报或改善可用性的贡献。

标签：Ask搜索, DKIM验证, DMARC验证, DNS信息、DNS暴力破解, DNS解析, MD5, MIT许可, Python, Python安全, SHA256, SOC自动化, SPF验证, URL分析, VirusTotal, WHOIS查询, YARA规则, 协议探测, 域名信誉, 威胁情报, 库, 应急响应, 开发者工具, 开源项目, 恶意链接检测, 无后门, 电子邮件安全, 网络安全, 逆向工具, 邮件分类, 邮件取证, 邮件头分析, 钓鱼分析, 钓鱼检测, 附件分析, 隐私保护