raghubirrajmahato15/HackDev-PhishGuard

# HackDev-PhishGuard [](https://github.com/raghubirrajmahato15/HackDev-PhishGuard/actions/workflows/test.yml) 启发式 + 仿冒/同形异义字检测 + 域名年龄 + 可选机器学习钓鱼 URL 检测器。 **HackDev** 开源网络安全工具包的一部分。 ## 功能 - **启发式评分引擎**（始终可用，无额外依赖）：URL 长度、子域名计数、IP 地址主机、`@` 掩码 技巧、已知 URL 缩短服务、可疑 TLD、可疑关键词、过多的连字符、punycode、数字密集型域名 - **仿冒/同形异义字检测**：基于从零开始的 Levenshtein 编辑距离实现，结合同形异义字规范化（`0`→`o`， `1`→`l`，`rn`→`m`），与精选的约 50 个主要品牌域名列表进行比对——能够标记 `paypa1.com` 或 `g00gle.com` 等近似错误，同时不会标记真实的品牌域名本身 - **域名年龄查询**：通过免费的 RDAP 协议（无需 API key）实现；最近注册的域名（典型的钓鱼信号） 会增加风险评分；对于不提供 RDAP 的注册局或在任何查询失败时，会平稳降级为仅使用启发式检测 - **可选的 ML 层**（`--ml` 标志）：在包含留出测试集的 800 个合成数据集上训练 `RandomForestClassifier`， 报告准确率/精确率/召回率和特征重要性；将 ML 概率与启发式评分结合；如果 scikit-learn/joblib 或训练好的模型不可用，则会平稳降级 - **批量扫描**（`--file urls.txt`），并提供判定结果直方图摘要 - **CLI 子命令**：`scan` 和 `train`；支持 JSON 和文本输出；文件输出；详细日志记录 ## 安装 ``` git clone https://github.com/raghubirrajmahato15/HackDev-PhishGuard.git cd HackDev-PhishGuard pip install -r requirements.txt ``` 启发式 + 仿冒评分仅需标准库。域名年龄查询需要 `requests`； `--ml`/`train` 层需要 `scikit-learn`、`joblib` 和 `numpy`（均为可选——在没有它们的情况下 该工具会平稳降级）。 ## 用法 扫描单个 URL： ``` python phishguard.py scan "http://paypa1-secure-login.top/verify/account" ``` 扫描 URL 列表，输出带有判定直方图的 JSON，并写入文件： ``` python phishguard.py scan --file urls.txt --format json -o results.json ``` 训练并使用 ML 层： ``` python phishguard.py train --samples 800 python phishguard.py scan "http://192.168.1.5/secure/signin" --ml ``` 跳过 RDAP 域名年龄查询（速度更快，完全离线）： ``` python phishguard.py scan "https://example.com" --no-domain-age ``` 仿冒 + 可疑 TLD URL 的 JSON 输出示例： ``` { "results": [ { "url": "http://paypa1-secure-login.top/verify/account", "score": 44, "verdict": "suspicious", "reasons": [ "Suspicious top-level domain", "Suspicious keyword(s) in host/path: account, login, secure, verify", "Multiple hyphens in domain (2)" ], "ml_score": null, "typosquat_matches": [], "domain_age_days": null } ], "histogram": { "suspicious": 1 } } ``` `train` 输出示例： ``` Trained on 640 samples (160 held out for testing). Accuracy: 0.981 Precision: 0.975 Recall: 0.988 Feature importances: num_suspicious_keywords 0.3226 length 0.2747 ... Model saved to .../phishguard_model.joblib ``` ## CLI 标志参考 | 标志 | 子命令 | 描述 | |---|---|---| | `url`（位置参数） | `scan` | 要扫描的单个 URL（或使用 `--file`） | | `--file FILE` | `scan` | 包含 URL 的文本文件路径，每行一个，用于批量扫描 | | `--ml` | `scan` | 启用 ML 评分层（如果不可用，则回退到仅使用启发式检测） | | `--no-domain-age` | `scan` | 跳过 RDAP 域名年龄查询 | | `-o, --output PATH` | `scan` | 将结果写入文件而不是 stdout | | `--format {text,json}` | `scan` | 输出格式（默认：`text`） | | `--samples N` | `train` | 合成训练样本的数量（默认：`800`） | | `-v, --verbose` | all | 启用详细（DEBUG 级别）日志记录 | | `--version` | — | 显示版本并退出 | ## 项目布局 ``` phishguard.py Thin CLI entrypoint hackdev_phishguard/ features.py URL feature extraction (pure, shared by heuristic + ML) heuristic.py Weighted risk scoring typosquat.py Levenshtein + homoglyph brand-domain comparison domain_age.py RDAP domain-age lookup ml.py Synthetic dataset, RandomForest train/predict cli.py argparse wiring, orchestration, batch histogram tests/ pytest suite ``` ## 测试 ``` pip install -r requirements-dev.txt pytest -q ``` 涵盖特征提取、启发式评分的确定性、针对已知距离的 Levenshtein 实现、同形异义字规范化、 对已知近似错误的仿冒检测（能正确识别且不标记真实的品牌域名）、使用模拟 HTTP 响应的 RDAP 域名年龄查询 （成功、格式错误、HTTP 失败、网络异常），以及 ML 训练/预测往返测试（如果未安装 scikit-learn，则 通过 `pytest.importorskip` 平稳跳过）。 ## 法律声明 PhishGuard 是一种防御性威胁检测辅助工具，旨在为安全分析师和研究人员提供支持。它**不能保证** URL 的安全性或恶意性，且每一层（启发式、仿冒、域名年龄、ML）都可能产生误报和漏报。在采取任何 行动之前，应始终结合人工审查和其他威胁情报来源来印证该工具的发现。

标签：Apex, Python, URL检测, 反网络钓鱼, 安全规则引擎, 无后门, 机器学习, 网络安全, 逆向工具, 隐私保护