AnonymousSingh-007/Phish_Byte

一个用于**电子邮件钓鱼检测**的 PyTorch 模型。采用三阶段级联推理：低成本的规则评分器处理明显案例，一个小型 MLP 处理不确定案例，深度结构分析处理最困难的案例。该模型随机初始化并在钓鱼数据集上从头开始训练——没有使用预训练语言模型。 ``` from phishbyte import PhishByteEngine engine = PhishByteEngine() verdict = engine.analyze(raw_email_string) print(verdict.label) # 'phishing' print(verdict.probability) # 0.9412 print(verdict.confidence) # 'high' print(verdict.layer_used) # 1 — decided at the cheap layer print(verdict.feature_weights) # {'domain_mismatch': 1.0, 'spf_fail': 1.0, ...} ``` ## 为什么使用级联，而不是单一分类器 大多数生产级电子邮件安全系统每天处理数百万封邮件。当 80% 的钓鱼尝试会触发明显的规则（如发件人域不匹配、SPF 失败、可疑的 TLD）时，对每一封邮件都运行神经网络是浪费资源的。Phish_Byte 会将这些邮件路由到快速路径。MLP 仅在处理更困难的部分时才会触发。 这意味着你可以在输出中验证两件事： - **`verdict.layer_used`** 告诉你是由规则单独决定，还是必须运行神经网络。这对于成本报告很有用。 - **`verdict.feature_weights`** 确切地显示哪些信号被触发。它不是一个黑盒。 各层之间的阈值不是硬编码的。它们通过 ROC 分析在留出的验证集上进行校准——钓鱼阈值设定为保持 ≥95% 精确率的最低阈值，而正常阈值设定为在合法邮件上保持 ≥95% 召回率的最高阈值。训练后运行 `python train/calibrate_thresholds.py` 以便为你自己的数据集重新生成它们。 ## 架构 ``` raw email │ ▼ ┌──────────────────────────────────┐ │ Layer 1 — rule scorers │ always runs │ • domain consistency │ ~1ms per email │ • SPF validation │ │ • URL / anchor analysis │ │ • body urgency + obfuscation │ └──────────────┬───────────────────┘ │ calibrated gate │ uncertain ─► ┌──────────────────────────────────┐ │ Layer 2 — MLP │ only when uncertain │ 15-d feature vector │ ~5ms per email on GPU │ 2 hidden layers, sigmoid │ trained from scratch │ + post-hoc SHAP attribution │ └──────────────┬───────────────────┘ │ calibrated gate │ uncertain ─► ┌──────────────────────────────────┐ │ Layer 3 — deep structural │ rare path │ • redirect chain depth │ network calls │ • WHOIS domain age │ ~200ms+ │ • ASN / geo reputation │ └──────────────────────────────────┘ │ ▼ PhishVerdict ``` ## 安装 ``` git clone https://github.com/AnonymousSingh-007/Phish_Byte.git cd Phish_Byte py -3.11 -m venv venv .\venv\Scripts\Activate.ps1 # Windows # source venv/bin/activate # Linux / Mac pip install -r requirements.txt # GPU 用户：安装支持 CUDA 的 PyTorch（RTX 50 series / Blackwell） pip install torch --index-url https://download.pytorch.org/whl/cu128 ``` 验证 GPU 是否被检测到： ``` python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))" # 预期：True NVIDIA GeForce RTX 5050 Laptop GPU ``` ## 用法 ### CLI ``` python cli.py --demo # built-in phishing sample python cli.py --file suspicious.eml # analyse a .eml file python cli.py # paste raw email, Ctrl+Z to submit python cli.py --demo --json # JSON output for scripting ``` ### Python API ``` from phishbyte import PhishByteEngine engine = PhishByteEngine() # 加载原始电子邮件（包含 headers） with open("suspicious.eml") as f: verdict = engine.analyze(f.read()) if verdict.label == "phishing" and verdict.confidence == "high": quarantine(email) ``` ### 输出 schema ``` PhishVerdict( label = "phishing", # "phishing" | "legitimate" probability = 0.94, # P(phish) in [0, 1] confidence = "high", # "high" | "medium" | "low" layer_used = 1, # 1 | 2 | 3 — which layer decided feature_weights = { # which signals fired "domain_mismatch": 1.0, "spf_fail": 1.0, "http_ratio": 0.8, }, detail = "...", # human-readable summary ) ``` ## 训练你自己的模型 ``` # 1. 训练 MLP python train/train.py # 2. 在验证集上校准置信度阈值 python train/calibrate_thresholds.py # 3. 验证引擎是否加载了所有内容 python cli.py --demo ``` 默认的 `train.py` 在合成数据上运行以验证 pipeline。为了获得真实性能，请将其指向带标签的 CSV： ``` python train/train.py --data data/ceas2008.csv ``` CSV 格式：两列，`email_text`（包含标头的完整原始电子邮件）和 `label`（`0` 代表合法，`1` 代表钓鱼）。CEAS-2008 和 Enron 垃圾邮件语料库不包含在 repo 中——有关下载说明，请参阅 `train/README.md`。 ## 基准测试 在 CEAS-2008 上的真实数据集评估待定。一旦训练完成，下表将被填充： | 指标 | 合成数据 | CEAS-2008 | |--------|-----------|-----------| | 准确率 | TBD | TBD | | 精确率 | TBD | TBD | | 召回率 | TBD | TBD | | F1 score | TBD | TBD | | ROC-AUC | TBD | TBD | | Layer 1 覆盖率 | TBD | TBD | | 平均推理延迟 | TBD | TBD | | 吞吐量 | TBD | TBD | Layer 1 覆盖率是指在不调用 MLP 的情况下决定结果的电子邮件百分比。越高越好——这意味着在部署时每封邮件消耗的计算资源更少。 ## 这不是什么 - **不是语言模型。** 没有 transformer，没有 embedding 查找，没有任何类型的预训练权重。Layer 2 的 MLP 是随机初始化的，并在由 Layer 1 生成的 15 维特征向量上从头开始训练。 - **不是垃圾邮件过滤器。** 垃圾邮件和钓鱼邮件有重叠，但它们是不同的问题。Phish_Byte 旨在防范凭据窃取、账户盗用和冒充攻击。 - **不是绝对可靠的。** 置信度是在验证集上校准的，但针对这些特定特征设计的新型攻击模式和对抗性邮件仍可能绕过检测。请将其作为纵深防御体系中的一个信号，而不是唯一的关卡。 ## Repo 布局 ``` Phish_Byte/ ├── phishbyte/ │ ├── engine.py # cascading engine, threshold gates │ ├── verdict.py # PhishVerdict dataclass │ ├── calibration.py # ROC-based threshold learning │ ├── extractors/ # Layer 1 rule scorers │ │ ├── domain.py │ │ ├── urls.py │ │ └── spf.py │ └── model/ │ ├── mlp.py # Layer 2 PyTorch MLP │ └── weights/ # trained weights + thresholds.json ├── train/ │ ├── train.py # MLP training loop │ ├── calibrate_thresholds.py │ └── synthetic_data.py # synthetic emails for pipeline testing ├── cli.py # command-line interface └── requirements.txt ``` ## 路线图 - [x] Layer 1 规则评分器 - [x] Layer 2 的 PyTorch MLP - [x] 基于 ROC 的阈值校准 - [x] 具有每项特征归因的判定对象 - [x] GPU 支持 (CUDA 12.8 / Blackwell) - [ ] CEAS-2008 训练 + 基准测试表 - [ ] 经过温度缩放的校准概率 - [ ] Layer 3 深度结构检查（包含重试 / 超时 / 回退） - [ ] 特征向量缓存（在多次训练运行之间跳过重新提取） - [ ] 发布到 PyTorch Hub - [ ] 发布到 HuggingFace Hub (`PyTorchModelHubMixin`) - [ ] 浏览器扩展封装 ## 许可证 MIT — 详见 [`LICENSE`](LICENSE)。

标签：Apex, Python, PyTorch, Vectored Exception Handling, 凭据扫描, 无后门, 机器学习, 网络安全, 逆向工具, 邮件安全, 钓鱼检测, 隐私保护