giorgosrsss/Phishguard
GitHub: giorgosrsss/Phishguard
一款结合启发式规则与机器学习的钓鱼 URL 检测与威胁评分工具，提供实时分类和人类可读的决策解释。
Stars: 0 | Forks: 0
# PhishGuard — 钓鱼 URL 分类器
一个混合型钓鱼 URL 检测器，结合了手工制作的启发式规则与机器学习分类器（scikit-learn `RandomForest`）。给定任何 URL，它会返回一个介于 0.0（良性）和 1.0（几乎确定为钓鱼）之间的钓鱼可能性分数，并提供影响该决策的信号的人类可读解释。
## 为什么是混合模式？
- **启发式规则** 可以瞬间捕获明显的问题，且不需要训练数据。诸如原始 IP 主机、punycode、authority 部分包含 `@`、可疑的 TLD 以及品牌关键词堆砌等都是很容易识别的目标。
- **ML 模型** 在你输入标注数据后，能够学习启发式规则遗漏的细微统计模式（token 分布、熵、字符类别比率等）。
CLI 会返回启发式分数、模型分数以及一个综合判定结果。
## 工作原理
### 推理数据流
当你调用 `classify(url)`（或 `phishguard scan `）时，URL 会经过下方的 pipeline。启发式评分器和 ML 模型在**相同**的 feature vector 上运行，它们的分数会被融合为一个单一判定。
```
flowchart LR
URL([URL string]) --> NORM[Normalize URL
add scheme if missing] NORM --> PARSE[Parse with urllib + tldextract
→ scheme, host, domain root,
subdomain, suffix, path, query, port] PARSE --> FEAT[Extract 31 features
lengths · counts · ratios · entropy
IP / punycode / TLD / shortener flags
phishing-keyword & brand-impersonation counts] FEAT --> HEUR[Heuristic scorer
15 weighted rules → logistic] FEAT --> ML[RandomForest model
predict_proba] HEUR --> HSCORE[Heuristic score
0.0 – 1.0] HEUR --> SIGNALS[Human-readable signals
e.g. "suspicious TLD .tk"] ML --> MSCORE[Model score
0.0 – 1.0] HSCORE --> BLEND[Blender
0.4 × heuristic + 0.6 × model] MSCORE --> BLEND BLEND --> THRESH{Verdict thresholds} THRESH -->|≥ 0.80| V1[PHISHING] THRESH -->|≥ 0.55| V2[SUSPICIOUS] THRESH -->|≥ 0.30| V3[LIKELY BENIGN] THRESH -->|else| V4[BENIGN] V1 --> RESULT([Result
score · verdict · signals]) V2 --> RESULT V3 --> RESULT V4 --> RESULT SIGNALS --> RESULT classDef io fill:#e1f5ff,stroke:#0277bd,color:#01579b classDef heur fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c classDef ml fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20 classDef blend fill:#fff9c4,stroke:#f57f17,color:#e65100 class URL,RESULT io class HEUR,HSCORE,SIGNALS heur class ML,MSCORE ml class BLEND,THRESH blend ``` 如果没有可用的已训练模型，pipeline 会优雅地降级为仅使用启发式分数——你仍然会得到一个有用的判定结果，只是缺少了统计层。 ### 训练数据流 `phishguard train --data` 会运行一次此 pipeline，以生成一个可供推理路径加载的序列化模型。
```
flowchart LR
CSV([CSV
url, label]) --> LOAD[Load & validate
require url + label columns] LOAD --> EXTRACT[Extract 31 features
per URL] EXTRACT --> SPLIT[Stratified 80 / 20
train / test split] SPLIT --> FIT[RandomForestClassifier
n_estimators=200
class_weight=balanced] FIT --> EVAL[Evaluate
accuracy · precision · recall · F1
+ feature importances] FIT --> SAVE([joblib.dump
models/phishguard.joblib]) classDef io fill:#e1f5ff,stroke:#0277bd,color:#01579b class CSV,SAVE io ``` ### 模块映射 | 模块 | 职责 | | --- | --- | | `phishguard.features` | URL 解析 + 31 维特征提取（纯函数，无 I/O） | | `phishguard.heuristics` | 加权规则评分器 + 信号解释 | | `phishguard.model` | scikit-learn 封装：训练、保存、加载、预测 | | `phishguard.classifier` | 融合两者的高级 `classify()` | | `phishguard.cli` | `phishguard` 命令（`scan` / `train` / `features`） | ## 提取的特征 词汇/结构特征： - URL、主机名、路径、查询的长度 - `.`、`-`、`/`、`?`、`=`、`&`、`@`、数字、特殊字符的数量 - 数字比率、字母比率、特殊字符比率 - 主机名和完整 URL 的香农熵 - 子域名数量、最长 token 长度 主机信号： - 主机名是原始 IPv4 / IPv6 地址 - 包含 punycode (`xn--`) - 使用非标准端口 - TLD 位于可疑名单中（例如 `.zip`、`.tk`、`.cf`、`.gq`、`.ml`） - 已知的 URL 缩短域名 内容信号： - 钓鱼关键词（`login`、`verify`、`secure`、`account`、`update`、`bank` 等） - 位于注册域名之外的品牌冒充 token（`paypal`、`apple`、`microsoft` 等） - 路径/查询中的十六进制编码字符 - scheme 之后的双斜杠 ## 快速开始 ``` # 1. 安装（在迭代时 editable mode 很方便） pip install -e . # 2. 在捆绑的 seed dataset 上训练模型 phishguard train --data data/seed_dataset.csv --out models/phishguard.joblib # 3. 评估 URL phishguard scan "http://paypa1-login.security-update.tk/verify?id=42" # 4. 训练后 phishguard scan "http://paypa1-login.security-update.tk/verify?id=42" --model models/phishguard.joblib ``` 输出示例： ``` URL: http://paypa1-login.security-update.tk/verify?id=42 Heuristic score : 0.82 (HIGH) Model score : 0.91 (HIGH) Blended verdict : 0.87 PHISHING Top signals: + suspicious TLD (.tk) + phishing keyword in path: 'verify' + brand impersonation token outside registered domain: 'paypal' + high hostname entropy (3.71) + uses HTTP, not HTTPS ``` ## 库用法 ``` from phishguard import classify result = classify("http://paypa1-login.security-update.tk/verify?id=42") print(result.score, result.verdict, result.signals) ``` ## 在你自己的数据上进行训练 训练器接受包含 `url` 和 `label`（1 = 钓鱼，0 = 良性）两列的 CSV。可以直接使用的公开数据集： - [PhishTank](https://www.phishtank.com/developer_info.php)（钓鱼样本） - [Tranco list](https://tranco-list.eu/)（良性热门网站） - [Mendeley phishing dataset](https://data.mendeley.com/datasets/h3cgnj8hft) ``` phishguard train --data path/to/your.csv --out models/phishguard.joblib ``` ## 项目布局 ``` phishing-url-classifier/ ├── src/phishguard/ │ ├── __init__.py # public API: classify(), Result │ ├── features.py # URL feature extraction │ ├── heuristics.py # rule-based scorer + signal explanations │ ├── model.py # scikit-learn wrapper (train / load / predict) │ ├── cli.py # `phishguard` command │ └── data.py # dataset loading helpers ├── data/seed_dataset.csv # tiny labelled dataset to bootstrap training ├── tests/ # pytest suite ├── pyproject.toml └── requirements.txt ``` ## 免责声明 此工具用于**防御性研究和教育**。它会产生误报和漏报。不要在生产环境中将其作为拦截流量的唯一关卡。请将其与信誉源（Google Safe Browsing、PhishTank 等）以及人工审核结合使用。
add scheme if missing] NORM --> PARSE[Parse with urllib + tldextract
→ scheme, host, domain root,
subdomain, suffix, path, query, port] PARSE --> FEAT[Extract 31 features
lengths · counts · ratios · entropy
IP / punycode / TLD / shortener flags
phishing-keyword & brand-impersonation counts] FEAT --> HEUR[Heuristic scorer
15 weighted rules → logistic] FEAT --> ML[RandomForest model
predict_proba] HEUR --> HSCORE[Heuristic score
0.0 – 1.0] HEUR --> SIGNALS[Human-readable signals
e.g. "suspicious TLD .tk"] ML --> MSCORE[Model score
0.0 – 1.0] HSCORE --> BLEND[Blender
0.4 × heuristic + 0.6 × model] MSCORE --> BLEND BLEND --> THRESH{Verdict thresholds} THRESH -->|≥ 0.80| V1[PHISHING] THRESH -->|≥ 0.55| V2[SUSPICIOUS] THRESH -->|≥ 0.30| V3[LIKELY BENIGN] THRESH -->|else| V4[BENIGN] V1 --> RESULT([Result
score · verdict · signals]) V2 --> RESULT V3 --> RESULT V4 --> RESULT SIGNALS --> RESULT classDef io fill:#e1f5ff,stroke:#0277bd,color:#01579b classDef heur fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c classDef ml fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20 classDef blend fill:#fff9c4,stroke:#f57f17,color:#e65100 class URL,RESULT io class HEUR,HSCORE,SIGNALS heur class ML,MSCORE ml class BLEND,THRESH blend ``` 如果没有可用的已训练模型，pipeline 会优雅地降级为仅使用启发式分数——你仍然会得到一个有用的判定结果，只是缺少了统计层。 ### 训练数据流 `phishguard train --data
url, label]) --> LOAD[Load & validate
require url + label columns] LOAD --> EXTRACT[Extract 31 features
per URL] EXTRACT --> SPLIT[Stratified 80 / 20
train / test split] SPLIT --> FIT[RandomForestClassifier
n_estimators=200
class_weight=balanced] FIT --> EVAL[Evaluate
accuracy · precision · recall · F1
+ feature importances] FIT --> SAVE([joblib.dump
models/phishguard.joblib]) classDef io fill:#e1f5ff,stroke:#0277bd,color:#01579b class CSV,SAVE io ``` ### 模块映射 | 模块 | 职责 | | --- | --- | | `phishguard.features` | URL 解析 + 31 维特征提取（纯函数，无 I/O） | | `phishguard.heuristics` | 加权规则评分器 + 信号解释 | | `phishguard.model` | scikit-learn 封装：训练、保存、加载、预测 | | `phishguard.classifier` | 融合两者的高级 `classify()` | | `phishguard.cli` | `phishguard` 命令（`scan` / `train` / `features`） | ## 提取的特征 词汇/结构特征： - URL、主机名、路径、查询的长度 - `.`、`-`、`/`、`?`、`=`、`&`、`@`、数字、特殊字符的数量 - 数字比率、字母比率、特殊字符比率 - 主机名和完整 URL 的香农熵 - 子域名数量、最长 token 长度 主机信号： - 主机名是原始 IPv4 / IPv6 地址 - 包含 punycode (`xn--`) - 使用非标准端口 - TLD 位于可疑名单中（例如 `.zip`、`.tk`、`.cf`、`.gq`、`.ml`） - 已知的 URL 缩短域名 内容信号： - 钓鱼关键词（`login`、`verify`、`secure`、`account`、`update`、`bank` 等） - 位于注册域名之外的品牌冒充 token（`paypal`、`apple`、`microsoft` 等） - 路径/查询中的十六进制编码字符 - scheme 之后的双斜杠 ## 快速开始 ``` # 1. 安装（在迭代时 editable mode 很方便） pip install -e . # 2. 在捆绑的 seed dataset 上训练模型 phishguard train --data data/seed_dataset.csv --out models/phishguard.joblib # 3. 评估 URL phishguard scan "http://paypa1-login.security-update.tk/verify?id=42" # 4. 训练后 phishguard scan "http://paypa1-login.security-update.tk/verify?id=42" --model models/phishguard.joblib ``` 输出示例： ``` URL: http://paypa1-login.security-update.tk/verify?id=42 Heuristic score : 0.82 (HIGH) Model score : 0.91 (HIGH) Blended verdict : 0.87 PHISHING Top signals: + suspicious TLD (.tk) + phishing keyword in path: 'verify' + brand impersonation token outside registered domain: 'paypal' + high hostname entropy (3.71) + uses HTTP, not HTTPS ``` ## 库用法 ``` from phishguard import classify result = classify("http://paypa1-login.security-update.tk/verify?id=42") print(result.score, result.verdict, result.signals) ``` ## 在你自己的数据上进行训练 训练器接受包含 `url` 和 `label`（1 = 钓鱼，0 = 良性）两列的 CSV。可以直接使用的公开数据集： - [PhishTank](https://www.phishtank.com/developer_info.php)（钓鱼样本） - [Tranco list](https://tranco-list.eu/)（良性热门网站） - [Mendeley phishing dataset](https://data.mendeley.com/datasets/h3cgnj8hft) ``` phishguard train --data path/to/your.csv --out models/phishguard.joblib ``` ## 项目布局 ``` phishing-url-classifier/ ├── src/phishguard/ │ ├── __init__.py # public API: classify(), Result │ ├── features.py # URL feature extraction │ ├── heuristics.py # rule-based scorer + signal explanations │ ├── model.py # scikit-learn wrapper (train / load / predict) │ ├── cli.py # `phishguard` command │ └── data.py # dataset loading helpers ├── data/seed_dataset.csv # tiny labelled dataset to bootstrap training ├── tests/ # pytest suite ├── pyproject.toml └── requirements.txt ``` ## 免责声明 此工具用于**防御性研究和教育**。它会产生误报和漏报。不要在生产环境中将其作为拦截流量的唯一关卡。请将其与信誉源（Google Safe Browsing、PhishTank 等）以及人工审核结合使用。
标签：Apex, scikit-learn, 威胁情报, 安全规则引擎, 开发者工具, 机器学习, 网络安全, 逆向工具, 钓鱼检测, 隐私保护