barlettab/phishing-machine-learning-cyber

# 使用 Machine Learning 进行钓鱼检测 数据科学项目 + API 部署，旨在**将 URL 分类为合法或钓鱼**。 ## 1. 引言 *网络钓鱼* 依然是全球最主要且最动态的网络安全攻击媒介之一，它利用社会工程学来欺骗用户，窃取机密凭证、财务数据或感染企业网络。传统上，安全解决方案依赖于两种极端的方法：要么使用静态封锁列表（*黑名单*）——这无法检测在几分钟内产生的新威胁；要么要求加载并完整扫描页面的 HTML 代码，这会给分析服务器本身带来高昂的计算成本、响应延迟（*network overhead*）和安全风险。 本项目提出开发一个智能的 Machine Learning pipeline，用于实时、自动地对恶意 URL 进行分类。它从两个数据工程视角来解决这个问题：一个是基于页面完整信息（包括源代码）的传统分析场景；另一个是优化的生产场景（*仅限 URL*），能够在用户与可疑网站建立连接之前，立即对风险进行分类。 ## 2. 项目目标 这项工作的核心目的是评估实现一个智能、敏捷的网络安全系统的可行性和成本效益。具体而言，目标分为： * **开发端到端分类 pipeline：** 执行完整的数据科学生命周期，包括探索性数据分析 (EDA)、对包含 10,000 个平衡样本的数据集进行严格的预处理，以及监督学习算法（Regressão Logística、Decision Tree 和 Random Forest）的训练、调参和评估。 * **映射 URL 混淆模式：** 从统计学角度识别哪些文本属性（如点号的数量、路径长度、子域、直接 IP 地址的存在以及敏感词）在区分合法链接和恶意链接时具有最大的区分能力。 * **评估鲁棒性与延迟的权衡：** 开展对比实验，以量化在完全移除从页面 HTML 获取的丰富特征时预测性能的损失，评估仅分析 URL 字符串是否能维持稳健的统计指标（如 ROC-AUC 和 Recall）。 * **构建优化的生产原型：** 实现一个功能完备且模块化的语法特征提取模块（`feature_extractor.py`），集成到超低延迟的 **FastAPI** API 中，模拟可操作的业务规则和风险级别，以便进行实时的自动化决策。 ## 3. 项目结构 ``` phishing-machine-learning-cyber/ ├── api/ │ ├── main.py # endpoints FastAPI │ ├── predictor.py # carga do modelo e predição │ ├── schemas.py # schema da requisição │ └── requirements.txt # dependências ├── data/ │ ├── dataset.csv # base principal │ ├── dictionary.md # dicionário de dados │ ├── output/ # artefatos da modelagem completa │ | ├── models/ | | └── train_test/ │ └── output_API/ # artefatos da modelagem URL-only e API │ | ├── models/ | | └── train_test/ ├── modules/ │ └── feature_extractor.py # extração de features estruturais da URL ├── notebooks/ │ ├── 01_eda.ipynb │ ├── 02_preprocessamento.ipynb │ ├── 03_modelagem.ipynb │ ├── 04_avaliacao.ipynb │ ├── 06_avaliacaoURL.ipynb │ ├── 07_comparacao_final.ipynb │ └── 08_testingURL.ipynb └── Dockerfile ``` ## 4. 数据集与字典 - 主要基础：`data/dataset.csv` - 变量字典：`data/dictionary.md` 数据集包含用于二分类（`CLASS_LABEL`）的 URL/页面的词法和结构属性： - `0` = 合法 - `1` = 钓鱼 ## 5. Notebooks ### 🥎 `01_eda.ipynb` — 探索性数据分析 此阶段的主要目标是了解数据集的整体结构，从而指导接下来与预处理和预测建模相关的步骤。 #### EDA 发现： - **维度：** 10,000 条记录和 50 个属性。 - **数据类型：** 由 47 个 `int64` 类型的变量和 3 个 `float64` 类型的变量组成。 - **完整性：** 数据高度一致，缺失值为 0%，且无重复项。 - 该数据集恰好包含 5,000 条合法 URL 记录和 5,000 条欺诈 URL 记录。 - 50/50 的平衡比例消除了对重采样技术的需求，并避免了模型中的偏差。 - 变量 `HttpsInHostname` 在整个数据集中呈现相同的值，不具备区分能力。 ### 🥎 `02_preprocessamento.ipynb` — 预处理 核心目标是对在探索性数据分析 (EDA) 阶段识别出的数据应用结构化处理和转换。主要操作包括： - 移除不相关或无变异性的变量。 - 分离解释变量与目标变量。 - 以分层抽样的方式将数据集划分为训练集 (80%) 和测试集 (20%)。 - 对变量应用尺度归一化，以满足特定模型（如 Regressão Logística）的需求。 - 导出并保存最终处理好的数据集和缩放器 对象，以供将来使用。 ### 🥎 `03_modelagem.ipynb` — 使用所有特征进行训练 此阶段的主要目的是应用 Machine Learning 算法对 URL（合法 vs. 恶意）进行二分类。因此，由于其在结构、可解释性和泛化能力方面的互补特性，选择了三种不同的算法： - **Regressão Logística：** 作为基础的线性模型 使用。用于测试该问题是否可以通过假设属性的影响纯粹是成比例或可叠加的来解决（例如：URL 越长，成为攻击的可能性就越大）。该模型输入了由 StandardScaler 归一化的数据。 - **Decision Tree：** 之所以被选中，是因为它具有极高的可解释性，并且能够在页面的结构属性之间创建非线性的分层规则和更复杂的行为模式。 - **Random Forest：** 作为一种稳健的 ensemble 方法（树的集合）实现，旨在最大化泛化能力并减轻单棵树固有的过拟合 风险。 *注意：该 notebook 使用 joblib 库系统地保存了所有微调过的模型。生成的文件被定向输出到项目的输出文件夹 (../data/output/models/) 中。* ### 🥎 `04_avaliacao.ipynb` — 评估（完整模型） 此阶段旨在通过指标对比、混淆矩阵和误差解释（FP/FN）来衡量和比较先前微调过的分类模型的性能。 #### 指标结果 | 模型 | Accuracy | Precision | Recall | F1-Score | ROC-AUC | | :--- | :---: | :---: | :---: | :---: | :---: | | **Random Forest** | **0.9860** | **0.9841** | **0.9880** | **0.9860** | **0.9990** | | **Decision Tree** | 0.9650 | 0.9678 | 0.9620 | 0.9649 | 0.9649 | | **Regressão Logística** | 0.9520 | 0.9593 | 0.9440 | 0.9516 | 0.9841 | ### 🥎 `05_modelagemURL.ipynb` — 仅使用与 URL 相关的特征进行训练 仅使用直接从 URL 中提取的属性来训练相同的 Machine Learning 算法，完全忽略依赖于网页结构分析或 HTML 代码的变量。通过这种方式，评估这种简化的方法是否能够保持良好的预测能力，从而应用于轻量级监控系统或高性能的自动分类 API。 *注意：该 notebook 对特定且已归一化的新数据集（如 X_train_scaled_url.csv 和 X_test_scaled_url.csv）进行了最终保存，并将其定向输出到一个名为 ../data/output_API/ 的文件夹中。* ### 🥎 `06_avaliacaoURL.ipynb` — 评估（仅限 URL） 在仅使用从 URL 字符串中提取的属性的约束下评估预测模型，完全忽略来自页面 HTML 的任何信息。 #### 指标结果 | 模型 | Accuracy | Precision | Recall | F1-Score | ROC-AUC | | :--- | :---: | :---: | :---: | :---: | :---: | | **Random Forest** | **0.900** | **0.8861** | **0.9180** | **0.9018** | **0.9626** | | **Decision Tree** | 0.8695 | 0.8516 | 0.8950 | 0.8727 | 0.8708 | | **Regressão Logística** | 0.8500 | 0.8314 | 0.8780 | 0.8541 | 0.9143 | 该 notebook 在结论中指出，结果表明 URL 的文本属性能够捕捉到非常相关的钓鱼行为模式。这验证了最初的假设：构建一个超轻量级、超低延迟的生产级 API 是完全可行的，通过舍弃 HTML 来换取速度和大规模的计算节省。 ### 🥎 `07_comparacao_final.ipynb` — 总结 通过对比两种建模场景下每种算法在使用和不使用与页面 HTML 代码相关的特征时的性能，量化简化系统的成本效益。 #### 结果 - 属性数量的急剧减少对算法的预测性能产生的影响小得惊人。 - Random Forest 模型巩固了其作为本项目最佳且最具弹性的算法的地位：它的 ROC-AUC 指数仅下降了 3.61%（在完整模型中从 0.9990 降至仅限 URL 模型中的 0.9629）。这证明该问题的大部分区分能力已经存在于链接字符串本身的构成中。 - 在仅限 URL 的受限场景下，Random Forest 模型保持了 91.80% 的 Recall（相比之下，在完整场景中获得的为 98.40%）。这意味着，即使不花费资源去打开或阅读恶意网站的哪怕一行 HTML 代码，该模型仍然能够通过正确识别 10 次钓鱼攻击中的 9 次来保护系统。 - 除了速度之外，这还增加了一层物理安全性，因为 pipeline 仅分析提供的文本，从而减轻了在扫描过程中在自动化基础设施上执行或加载恶意代码的风险。 ### 🥎 `08_testingURL.ipynb` - 展示了优化方案（仅使用从 URL 字符串中提取的属性）的实际测试阶段和生产环境模拟。 ## 6. Notebooks 中生成的模型和工件 序列化 的模型等包括： - `data/output/models/logistic_regression.pkl` - `data/output/models/decision_tree.pkl` - `data/output/models/random_forest.pkl` - `data/output_API/models/log_model_url.pkl` - `data/output_API/models/tree_model_url.pkl` - `data/output_API/models/rf_model_url.pkl` 还包括一些辅助工件，如为了可复现性而保存的缩放器和训练/测试数据集。 ## 7. 特征提取脚本 此文件 `modules/feature_extractor.py` 的核心目标是作为本项目 API 的实时数据处理层（特征工程）。它将原始文本字符串（链接）转换为一个标准化的数值字典，使 Machine Learning 模型能够立即对其进行解释和分类。代码在不向互联网发出任何 HTTP 请求的情况下分析 URL 的语法特征，从而确保 pipeline 的最大速度和计算安全性。 ## 8. 欺诈 URL 预测 API API 采用 FastAPI 实现，接收原始 URL，导入 `feature_extractor.py` 脚本，加载使用纯 URL 属性训练的 Random Forest 模型，并在 JSON 返回中提供可操作的业务规则。 ### 状态 endpoint - `GET /` - 返回：指示 API 处于活动状态的消息。 ### 推断 endpoint - `POST /predict` - Body (JSON): ``` { "url": "https://exemplo.com/login" } ``` ### 预期响应 - 已评估的 URL - 分类（`Legítima`、`Suspeita`、`Phishing`） - 类别概率 - 风险级别（`Baixo Risco`、`Risco Moderado`、`Alto Risco`） 风险分类基于预测的钓鱼概率： - `< 0.30` → 🟢 Baixo Risco - `0.30 a < 0.60` → 🟡 Risco Moderado - `>= 0.60` → 🔴 Alto Risco ## 9. API 使用的 URL 特征 API 的推断使用在 `modules/feature_extractor.py` 中实现的结构属性提取。 主要变量组： - URL 结构（点号、子域、长度、路径层级等） - 混淆/可疑信号（`@`、`%`、`#`、数字、双斜杠等） - HTTPS 的使用 - 使用 IP 代替域名 - 域名出现在 URL 不常见部分的情况 生产环境中使用的最终特征列在 `api/predictor.py` 中（列表 `url_features`）。 ## 10. 如何在本地运行 API ### 选项 A — Python + Uvicorn #### 第 1 步：安装依赖项 ``` pip install -r api/requirements.txt ``` #### 第 2 步：设置环境变量 ``` export PYTHONPATH=. export MODEL_PATH=data/output_API/models/rf_model_url.pkl ``` #### 第 3 步：启动 API ``` uvicorn api.main:app --reload --host 0.0.0.0 --port 8000 ``` #### 第 4 步：访问 - 交互式文档：`http://localhost:8000/docs` -健康检查：`http://localhost:8000/` ### 选项 B — Docker ``` docker build -t phishing-api . docker run --rm -p 8000:8000 phishing-api ``` `Dockerfile` 已经将 `MODEL_PATH` 配置为： `/app/data/output_API/models/rf_model_url.pkl` ## 11. 使用 Docker 进行容器化 为了隔离预测 API，确保结果的可复现性，并减轻生产环境中依赖冲突的风险（例如不同环境间 Scikit-Learn 版本的差异），本应用程序使用 **Docker** 进行了打包。 镜像基于轻量级的 Python 发行版 (`python:3.10-slim`) 进行配置，最大程度地减小了部署工件的最终大小，并降低了服务器的受攻击面。 ## 12. 局限性与后续步骤 ### 局限性 - 依赖于特定的数据集。 - 可能存在钓鱼模式的时间漂移。 - 绝大多数为静态方法（URL 特征）。 ### 建议的后续步骤 - 使用新数据库进行外部验证。 - 建立监控和定期重新训练的例程。 - 正式的特征存储/模型版本控制。 - 具备可观测性（日志、指标、警报）的部署。 - 创建浏览器扩展程序或与安全网关集成。 ## 13. 致谢 这是一个将 Machine Learning 应用于网络安全的实际项目，重点关注钓鱼检测并通过 API 提供推断服务。

标签：Apex, AV绕过, Docker, FastAPI, 安全防御评估, 机器学习, 特征工程, 网络安全, 请求拦截, 逆向工具, 钓鱼检测, 隐私保护