chandrusrilaktech/malware-detection-ml

# 使用机器学习进行恶意软件检测 用于将 Windows PE 文件（`.exe`/`.dll`）分类为良性或恶意，并识别恶意软件家族的静态分析 ML pipeline，根据 FYP 提案（`Malware_ML_FYP_Proposal_removed (1).pdf`）实施。绝不执行任何文件——所有特征均来自解析 PE 结构和读取原始字节。 ## 项目状态与提案对比 已完成和待完成的工作，映射至提案的交付物（§8）和目标（§3）——在将项目视为可提交状态之前，请先检查此项。 | # | 交付物（提案 §8） | 状态 | |---|---|---| | 1 | 带标签的 PE 数据集 (CSV) | `data/processed/benign_features.csv`, `combined_features.csv`, `family_features.csv` | | 2 | 特征提取脚本 | `src/features/pe_features.py` | | 3 | 训练模型 — RF, XGBoost, SVM, KNN | 二分类和多分类家族变体均位于 `models/` 中 | | 4 | 评估报告（notebook + PDF 导出） | `notebooks/evaluation_report.ipynb` 存在，但**尚未执行**（无保存的输出）且**目前不存在 PDF 导出**——请在提交前运行并导出（参见下文步骤 6） | | 5 | 可用原型（CLI 或 web UI） | Streamlit 应用，`app/streamlit_app.py` —— 二分类 + 家族分类、模型比较、特征解释 | | 6 | 最终项目报告（PDF，≥8,000 字） | 仅存在 `reports/final_report_outline.md` —— 这是一个逐节的大纲，**并非已写好的报告**。这仍需要撰写。 | | 7 | 源代码仓库 (GitHub) | 此文件夹**尚未成为 git 仓库**（`.gitignore` 已存在并准备就绪，但从未运行过 `git init`，没有任何内容被提交或推送） | 已满足的目标（§3）：超过了 ≥95% 的二分类准确率目标（Random Forest / XGBoost 在留出测试集上约为 99.8%，参见 `reports/metrics_binary.csv`）；比较了所有 4 种所需算法；家族分类涵盖了所有 7 个指定家族以及良性类别；特征重要性通过静态图表（`reports/feature_importance_*.png`）和应用内的交互式方式进行了可视化。一个部分存在的缺口：AUC-ROC 仅针对二分类任务进行了计算（`reports/metrics_family.csv` 没有 `auc_roc` 列）——多分类 AUC 需要尚未实现的一对多平均方案（one-vs-rest averaging scheme）。 ## 快速设置（自动化） `setup.ps1` (Windows) / `setup.sh` (Linux/macOS) 一次性运行下方的整个 pipeline —— venv、依赖项、数据集构建、针对二分类和家族任务的训练 + 评估以及测试。两者均为幂等的（可安全重新运行；已完成的步骤会被跳过），并且绝不会触碰 MalwareBazaar/真实恶意软件。 Windows: ``` .\setup.ps1 # full setup, skips steps whose output already exists .\setup.ps1 -SkipEmber # if data/ember/ember2018 is already populated .\setup.ps1 -RunApp # also launch the Streamlit app when done .\setup.ps1 -Force # redo every step regardless of existing output ``` 运行 `Get-Help .\setup.ps1 -Full` 获取所有参数。 Linux/macOS: ``` chmod +x setup.sh # one-time, grants the execute bit ./setup.sh # full setup, skips steps whose output already exists ./setup.sh --skip-ember # if data/ember/ember2018 is already populated ./setup.sh --run-app # also launch the Streamlit app when done ./setup.sh --force # redo every step regardless of existing output ./setup.sh --help # all options ``` 需要 `PATH` 中存在 `python3.11`（或解析为 3.11 的 `python3`）——例如在 macOS 上使用 `brew install python@3.11`。此脚本已经过仔细审查，但尚未在真实的 Linux/macOS 机器上进行执行测试（此环境仅限 Windows）——如果有什么在你的系统上无法顺利运行，请告诉我，我会修复它。 下方的手动分步版本通篇使用 Windows 路径语法（与 `setup.ps1` 的逻辑一致）——在 Linux/macOS 上，请根据该部分顶部的注释，将 `.\venv\Scripts\python.exe` 替换为 `./venv/bin/python`（等等）。当你想要逐个运行/检查某个阶段，而不是运行完整的自动化脚本时，这适用于任何平台。 ## 设置（全新机器，手动） 需要 Python 3.11。`python-magic-bin`（间接用于文件类型嗅探）根据 `requirements.txt` 仅在 Windows 上安装；在 Linux/macOS 上，如果你依赖该路径，则还需要系统的 `libmagic` 包。 **从仓库根目录（即此 README 所在的文件夹）运行下方的每一条命令**——多个命令使用相对路径（`app/streamlit_app.py`, `data/processed/...`），只有在根目录下才能正确解析。如果出现“找不到文件”错误，请先 `cd` 进入仓库根目录。 ``` # 从 repo 根目录 — 创建一个全新的 venv（如果 venv/ 已存在则跳过） py -3.11 -m venv venv .\venv\Scripts\python.exe -m pip install --upgrade pip .\venv\Scripts\pip.exe install -r requirements.txt # 完整性检查 .\venv\Scripts\python.exe -c "import pefile, sklearn, xgboost, streamlit; print('ok')" ``` macOS/Linux 等效操作：`python3.11 -m venv venv`，然后执行 `./venv/bin/pip install -r requirements.txt`，并在下方使用 `./venv/bin/python` / `./venv/bin/streamlit` 代替 `.\venv\Scripts\...` 路径。 下方每条命令都通过路径直接调用 venv 的解释器，因此无需单独“激活” venv——无论你是否运行过 `Activate.ps1`，这都能同样生效。 ## Pipeline（按此顺序运行） 模型已被 gitignore 忽略（`models/*.pkl`），因此在全新克隆的仓库副本中，`models/` 是空的，并且在你完成下方的步骤 1–4（二分类）和 3b（家族）之前，应用会显示“未找到已训练的模型”。 ### 1. 收集良性样本（安全，无需下载） 解析干净的 Windows 系统二进制文件作为良性类别。 ``` .\venv\Scripts\python.exe -m src.data_collection.collect_benign ``` 写入 `data/processed/benign_features.csv`。 ### 2. 获取 EMBER 2018 恶意特征（安全 —— 预先提取，无原始恶意软件） ``` # ~1.7GB 下载量，在网络断开时支持断点续传/重试 — 需要明确确认 .\venv\Scripts\python.exe -m src.data_collection.download_ember --yes ``` 解压至 `data/ember/ember2018/*.jsonl`。注意：`train_features_0.jsonl` 全部为良性（标签 0）——恶意行存在于分片 1–5 中。 然后构建合并的训练集： ``` .\venv\Scripts\python.exe -m src.data_collection.build_combined_dataset --malicious-rows 5000 --shard train_features_1.jsonl ``` 这会将 EMBER 的 JSON 记录扁平化为与 `pe_features.py` 相同的列 schema，并与 `benign_features.csv` 拼接。在 `build_combined_dataset.py` 中**故意丢弃了几个字段**（`SOURCE_ARTIFACT_COLUMNS`, `HISTOGRAM_COLUMNS`），因为事实证明它们在 EMBER 的 JSON 和 `pefile` 的原始解析之间无法进行比较（字符串与整数编码、标志计数与位掩码、全文件与标头窗口直方图）——基于它们进行训练会通过检测是哪个 pipeline 生成了某一行，而不是检测真实的恶意软件信号，从而得出毫无意义的 100% 准确率。完整说明请参见该文件中的注释以及 `reports/final_report_outline.md` 第 6 节。 ### 3. （可选，高风险）通过 MalwareBazaar 获取真实恶意软件样本 **下载活跃恶意软件。** 在运行前请完整阅读 `src/data_collection/download_malwarebazaar.py`——它需要防病毒排除项或隔离的 VM（参见提案第 10 节），以及你自己的免费 API key： ``` $env:MB_API_KEY = "your-key-here" .\venv\Scripts\python.exe -m src.data_collection.download_malwarebazaar --i-understand-the-risk --limit-per-family 50 ``` 样本保存为受密码保护的 zip 文件（密码为 `infected`），并且绝不会在此仓库中被任何程序解压或执行。 ### 3b. 多分类家族分类（7 个家族 + 良性） EMBER 的 `avclass` 字段提供了一个*具体的*恶意软件家族名称（例如 `zbot`, `gandcrab`），而不是提案界定的宽泛类别（第 2.3 节），因此 `src/features/ember_loader.py` 通过 `FAMILY_NAME_MAP` 将约 60 个已知的家族名称映射到 Ransomware/Trojan/Worm/Spyware/Adware/Rootkit/Backdoor（尽力而为，有些家族确实属于多个类别——参见该 dict 上方的注释）。构建跨所有 7 个类别的均衡样本并进行训练/评估： ``` .\venv\Scripts\python.exe -m src.data_collection.build_combined_dataset --mode family --per-family-cap 400 --output data/processed/family_features.csv .\venv\Scripts\python.exe -m src.evaluation.evaluate --data data/processed/family_features.csv --task family ``` 上方的 `evaluate` 调用既会进行评估，*也会*训练并将家族模型保存至 `models/*_family.pkl`（它在内部调用了与步骤 4 相同的训练例程）——你不需要单独执行 `train_models --task family`，尽管如果你想在不生成评估图表的情况下进行训练，`python -m src.training.train_models --data data/processed/family_features.csv --task family` 也可以工作。 Rootkit 家族名称在 EMBER 的 avclass 顶级分布中很少见，因此预计 Rootkit 行数会远少于每家族 400 个的上限——请在报告中将其作为类别不平衡的局限性予以说明，而不是将所有 7 个家族视为具有同等良好的代表性。 ### 4. 训练模型（二分类） ``` .\venv\Scripts\python.exe -m src.training.train_models --data data/processed/combined_features.csv --task binary ``` 保存 `models/_binary.pkl`。 ### 5. 评估（二分类） ``` .\venv\Scripts\python.exe -m src.evaluation.evaluate --data data/processed/combined_features.csv --task binary ``` 将指标 + 混淆矩阵 + ROC 曲线 + 特征重要性图表写入 `reports/`。 ### 6. 评估报告 notebook（交付物 4） ``` .\venv\Scripts\jupyter.exe nbconvert --to notebook --execute --inplace notebooks/evaluation_report.ipynb ``` 这实际上会运行 notebook 的单元格（它们为两个任务调用 `evaluate_models`）并将输出保存到 `.ipynb` 文件本身中。跳过此步骤将使 notebook 不含任何输出单元格，这也就是你运行它之前它一直处于的状态。 然后导出为 PDF。`jupyter nbconvert --to pdf` 需要 LaTeX 工具链（例如 Windows 上的 MiKTeX，其他地方的 `mactex`/`texlive`），这**不**包含在 `requirements.txt` 中，且默认未安装——如果你有，请直接使用它： ``` .\venv\Scripts\jupyter.exe nbconvert --to pdf notebooks/evaluation_report.ipynb ``` 如果你不想仅仅为此安装 LaTeX 发行版，请改为导出为 HTML，并使用任何已安装的 Chrome/Edge 将其打印为 PDF（两者都提供了 `--print-to-pdf` 标志，已在 Windows 上验证可正常工作）： ``` .\venv\Scripts\jupyter.exe nbconvert --to html notebooks/evaluation_report.ipynb & "C:\Program Files\Google\Chrome\Application\chrome.exe" --headless=new --print-to-pdf="notebooks/evaluation_report.pdf" "notebooks/evaluation_report.html" ``` （注意：`requirements.txt` 固定了 `mistune<3.1` 的版本——`nbconvert==7.16.4` 在 `mistune>=3.1` 上会引发 `AttributeError: 'MathBlockParser' object has no attribute 'parse_axt_heading'` 错误。如果你遇到该错误，请重新运行 `pip install -r requirements.txt` 以获取指定的版本。） ### 7. 运行原型 **从仓库根目录运行**（参见上方的注释），否则将找不到 `app/streamlit_app.py`： ``` .\venv\Scripts\streamlit.exe run app/streamlit_app.py ``` 上传 `.exe`/`.dll`，即可获得带有置信度的二分类判定、恶意软件家族猜测（如果已训练家族模型）、模型比较表，以及提取特征的通俗语言分解。主页还包含“关于此项目”和“认识模型”部分，在你上传任何内容之前解释该工具及其四种算法。 ### 8. 运行测试 ``` .\venv\Scripts\python.exe -m pytest tests/ ``` ## 仓库布局 ``` src/features/ PE feature extraction (pe_features.py) + EMBER loader src/data_collection/ benign collector, EMBER downloader, MalwareBazaar downloader src/training/ model training (RF, XGBoost, SVM, KNN) src/evaluation/ metrics, plots app/ Streamlit prototype (binary + family classification) notebooks/ evaluation report notebook reports/ generated metrics/plots/final report (gitignored) models/ trained .pkl models (gitignored) data/ datasets (gitignored — never commit real samples) setup.ps1 automated full setup (Windows) setup.sh automated full setup (Linux/macOS) ``` ## 安全说明 - 所有分析均为静态分析。任何阶段都不会执行 PE 文件。 - 如果你运行了 MalwareBazaar 步骤，`data/raw/malicious/` 将包含真实恶意软件——请将其视为危险品，使其脱离版本控制（已被 gitignore 忽略），并且不要在隔离环境之外解压这些 zip 文件。

标签：Apex, Kubernetes, NoSQL, Python, Streamlit, Windows PE, XGBoost, 云安全监控, 无后门, 机器学习, 访问控制, 逆向工具, 静态分析