omobolajiadeyan/phishguard-ai

# PhishGuard AI [](https://github.com/omobolajiadeyan/phishguard-ai/actions/workflows/tests.yml) [](https://github.com/omobolajiadeyan/phishguard-ai/actions/workflows/codeql.yml) [](https://github.com/omobolajiadeyan/phishguard-ai/releases) [](LICENSE) [](https://github.com/omobolajiadeyan) [](CONTRIBUTING.md) [](https://github.com/omobolajiadeyan/phishguard-ai/forks) [](https://github.com/omobolajiadeyan/phishguard-ai/releases) 一个可解释的钓鱼检测引擎，通过特征工程和启发式风险评分实时分析 URL 和电子邮件。它完全离线运行，无需任何 API key。 由 [Omobolaji Adeyan](https://github.com/omobolajiadeyan) 创建并维护，他是一名网络安全工程师，专注于实用的 Python 安全工具、威胁检测和安全自动化。 之所以开发此工具，是因为大多数钓鱼检测工具要么是黑盒云服务，要么需要昂贵的 ML 训练 pipeline。PhishGuard 完全在离线环境下运行，并能准确解释*为什么*它会标记某些内容。 ## 工作原理 PhishGuard 不仅依赖于黑名单，还会从 URL 和电子邮件内容中提取行为和结构特征，然后应用一个可解释的、人工调优的启发式模型。当前的权重参考了常见的钓鱼指标，并受回归测试保护；它们尚未作为统计训练模型进行验证。 **分析的 URL 特征：** - 域名熵（随机生成的域名得分较高） - URL 中包含 IP 地址（几乎总是恶意的） - 可疑的 TLD（`.xyz`, `.tk`, `.ml`, `.ga`, `.click`） - 钓鱼关键词密度（`verify`, `suspended`, `account`, `secure` 等） - 子域名深度、路径深度、数字比例、特殊字符密度 - Punycode 和 Unicode 主机名指标，作为上下文进行保守加权 **分析的电子邮件特征：** - 紧迫性语言（`action required`, `account suspended`, `verify now`） - 链接和 URL 密度 - 全大写单词的使用 - 提及附件 - 感叹号频率 - 来自受信任接收方的可选 SPF, DKIM 和 DMARC 结果 ## 功能 - 实时 URL 和电子邮件评分，并输出概率 - 从文件批量扫描 URL 列表 - 可解释的结果 —— 查看哪些特征触发了警报 - 三级判定：`SAFE`, `SUSPICIOUS`, `PHISHING` - 导出 JSON 以集成到 SOC 工作流中 - 导出 SARIF 2.1.0 用于 GitHub Code Scanning 和 CI 安全 pipeline - 零依赖 —— 纯 Python 标准库 - 离线运行 —— 不向外部发送任何数据 ## 一分钟体验 [一分钟演示](docs/QUICK_DEMO.md) 对比了合法和可疑的输入，展示了可解释的特征细分，并在不使用真实钓鱼基础设施的情况下导出了检测结果。  请参阅[项目证据](docs/PROJECT_EVIDENCE.md)，了解带有日期的基准测试结果、发布和贡献证据、可复现的演示，以及当前指标所能确立范围的明确限制。 [观看 18 秒的安全演示视频](https://github.com/omobolajiadeyan/phishguard-ai/releases/download/v0.4.0/phishguard-demo.mp4)。 ## 安装说明 直接从 GitHub Releases 安装经过验证的 `v0.5.1` wheel： ``` python -m pip install \ https://github.com/omobolajiadeyan/phishguard-ai/releases/download/v0.5.1/phishguard_ai-0.5.1-py3-none-any.whl phishguard --help ``` 该版本还包括源代码归档文件、`SHA256SUMS` 以及已签名的构建来源。请查看 [v0.5.1 发布页面](https://github.com/omobolajiadeyan/phishguard-ai/releases/tag/v0.5.1) 了解下载和验证详情。 ## GitHub Action 使用稳定的 Marketplace 版本在 CI 中扫描 URL： ``` - name: Scan URL with PhishGuard AI uses: omobolajiadeyan/phishguard-ai@v0.5.1 with: url: https://example.com sarif-output: phishguard-results.sarif ``` 请查看 [GitHub Marketplace 列表](https://github.com/marketplace/actions/phishguard-ai-phishing-detector) 了解可用的输入参数和版本选择。 对于开发环境，请从克隆的仓库中安装： ``` git clone https://github.com/omobolajiadeyan/phishguard-ai.git cd phishguard-ai python --version # Python 3.10+ required python -m pip install . python -m unittest discover -s tests -v ``` 安装后会提供一个 `phishguard` 命令。在开发环境中，仍然支持直接运行源文件。 ## 用法 ``` # 分析单个 URL phishguard url "http://paypa1-secure-login.xyz/verify" # 带 feature breakdown 的分析 phishguard url "https://google.com" --verbose # 分析电子邮件 phishguard email \ --subject "URGENT: Your account has been suspended" \ --body "Click here immediately to verify your account or it will be deleted." \ --authentication-results "mx.example; spf=fail; dkim=fail; dmarc=fail" # 批量扫描 URL 列表 phishguard batch data/urls.txt # 在传统终端或 CI 日志中使用仅包含 ASCII 字符的输出 python phishguard.py url "https://google.com" --plain python phishguard.py batch data/urls.txt --no-unicode # 将结果导出为 JSON phishguard batch data/urls.txt --output results.json # 将 actionable findings 导出为 SARIF 2.1.0 phishguard batch data/urls.txt \ --format sarif \ --output phishguard.sarif ``` 请参阅 [GitHub Code Scanning 指南](docs/GITHUB_CODE_SCANNING.md)，获取使用 GitHub 官方 SARIF 上传 action 的可直接复制的工作流。 请参阅[电子邮件 JSON 和 SARIF 示例](docs/EMAIL_OUTPUT_EXAMPLES.md)，了解生成的 SPF, DKIM 和 DMARC 输出及其身份验证信任边界。 请参阅[检测模型文档](docs/DETECTION_MODEL.md)，了解特征语义、局限性以及更改评分所需的证据。 ## 可复现的基准测试 使用以下命令运行公开安全的 URL 回归测试用例： ``` python tools/evaluate_url_benchmark.py python tools/evaluate_url_benchmark.py data/public_benchmark_urls.jsonl ``` 该命令会报告有序的预测结果、混淆矩阵计数、精确率、召回率和误报率。这些是用于检测回归的测试指标，而不是总体准确率或校准估计值。请参阅 [基准测试文档](docs/BENCHMARK.md)，了解有关合成测试用例、经授权的 URL-Phish 衍生切片、脱敏处理和报告规则。 ## 示例输出 ``` PHISHGUARD AI AI-powered phishing detection ──────────────────────────────────────────────────────────── URL : http://paypa1-secure-login.xyz/verify Verdict : PHISHING Risk : ████████████████████ 94.2% Feature breakdown: url_length : 38 has_ip_address : 0 suspicious_tld : 1 * phishing_keywords : 2 * has_https : 0 * url_entropy : 3.84 * ``` ## 架构 ``` phishguard-ai/ ├── phishguard.py # CLI entrypoint — commands: url, email, batch ├── email_auth.py # SPF, DKIM, and DMARC result parsing ├── features.py # Feature extraction (URL + email) ├── model.py # Weighted scoring model + sigmoid normalisation ├── reporting.py # Native JSON and SARIF 2.1.0 serialization ├── data/ │ └── urls.txt # Sample URLs for batch testing └── README.md ``` ## 项目领导 - **创建者和主要维护者：** [Omobolaji Adeyan](https://github.com/omobolajiadeyan) - **LinkedIn：** [linkedin.com/in/oeadeyan](https://www.linkedin.com/in/oeadeyan) - **安全联系方式：** [omobolaji.adeyan@gmail.com](mailto:omobolaji.adeyan@gmail.com) ## 作者 **Omobolaji Adeyan** - 网络安全工程师 [GitHub](https://github.com/omobolajiadeyan) ## 许可证和引用 PhishGuard AI 采用 [MIT 许可证](LICENSE)。可以使用 [CITATION.cff](CITATION.cff) 中的元数据来引用本项目。

标签：GitHub Action, Python, 威胁情报, 开发者工具, 搜索语句（dork）, 无后门, 逆向工具, 钓鱼检测