Hiroki-Tomimatsu/mlscan

# mlscan **一个用于 EMBER2024 静态 ML 恶意软件扫描器的单文件 CLI 前端。** `mlscan.py` 将 EMBER2024 研究套件——`thrember` 特征提取器以及随 KDD 2025 论文发布的 14 个预训练 LightGBM 模型——转化为一个可用的命令行工具。一条命令即可提供恶意/正常判决、在 2,538 个类别中的家族归属、多标签属性分析（行为 / 打包器 / 漏洞 / APT 组 / 文件属性）以及基于 SHAP 的可解释性，输出结构化 JSON 以供下游流水线使用。 无需服务器。无需云端。无需样本外传。所有内容均在本地针对公共 EMBER2024 模型运行。 ## 存在的原因 EMBER2024 提供了两样东西：`thrember` 特征提取器和 14 个 `.model` 文件。它**并未**提供大多数人真正需要的粘合逻辑： - 加载全部 14 个 LightGBM 模型， - 将 2,568 维特征向量输入每个模型， - 集成投票生成判决， - 格式化 Top-N 家族预测， - 融合五个一对一多标签分类头， - 计算并分类 SHAP 贡献， - 同时将上述内容渲染为人类可读的终端输出**和**机器可读的 JSON， - 在不崩溃的前提下处理 Windows `cp932` 控制台编码。 研究者发布模型后就停止了。实践者最终只能编写私有的一次性脚本。`mlscan.py` 就是缺失的中间层——单个文件、最小依赖、可复现输出。 ## 功能特性 ### 四个分析层级，按需开启 | 层级 | 标志 | 功能说明 | |------|------|----------| | **1. 判决** | *(始终启用)* | 运行 Win64 / PE / 通用恶意-正常分类头。平均得分，与 0.5 阈值比较，并报告集成投票（例如 `3/3 恶意`）以及 ASCII 置信度条。 | | **2. 家族** | `--family` | 2,538 类家族分类器。返回 Top-N 候选（默认 10）及其置信度。若存在标签映射，则自动解析为可读的家族名称。 | | **3. 属性** | `--attrib` | 五个一对一多标签分类头——行为、打包器、漏洞、APT 组、文件属性——并行预测。由于是 OvR，单一样本可同时被标记为例如 *已打包 × 数据窃取 × APT 相关*。 | | **4. SHAP** | `--shap` | 通过 LightGBM 内置的 SHAP 计算每个特征的贡献（无需额外包），聚合为 12 个可解释类别。也可展示 Top-N 单个特征贡献，例如 *“StringExtractor 特征 #X 使判决偏向 −0.3 logit。”* | 默认仅运行第 1 层；按需添加标志即可加深分析。`--all-layers` 可一次性启用全部层级。 ### 支持的文件类型 Win32 / Win64 / .NET / ELF / APK / PDF —— 通过 `--type` 可选。每种类型在可用时使用家族专用分类头，否则回退到通用 PE 头。 ### 输出模式 - **终端**：格式化、感知颜色、兼容 cp932 的输出，便于快速阅读。 - **JSON**：`--json <路径>` 写入完整结果——包含判决、集成分数、家族 Top-N、带有每标签分数的 OvR 标签、SHAP 类别总计以及每个特征的贡献。设计为可管道传输、比对或导入下游分析。 ### 极简足迹 仅 `mlscan.py` 一个文件。依赖项：`thrember`、`lightgbm`、`numpy`。仅此而已。SHAP 通过 LightGBM 的内部贡献 API 计算，因此无需独立的 `shap` 包。 ## 安装 ``` # 1. 依赖项 pip install thrember lightgbm numpy # 2. 克隆此仓库 git clone https://github.com//mlscan.git cd mlscan # 3. 从官方 EMBER2024 发布版本下载 EMBER2024 模型包（14 个 .model 文件） # 并将其放置在 ./models/ 目录下 # （或使用 --models-dir 参数指定 mlscan.py 的路径） ``` 建议使用 Python 3.10 或更高版本。 ## 用法 ### 基础——仅判决 ``` python mlscan.py sample.exe --type win64 ``` ### 全部层级 ``` python mlscan.py sample.exe --type win64 --all-layers ``` ### 选择性层级 ``` # 仅家族归属 python mlscan.py sample.exe --type win64 --family # 仅属性 python mlscan.py sample.exe --type win64 --attrib # SHAP 扩展特征详情与 JSON 导出 python mlscan.py sample.exe --type win32 --shap --top 50 --json result.json ``` ### 批量分类 `mlscan.py` 适合标准输出且优先使用 JSON，因此可自然与 shell 循环和 `parallel` 结合： ``` find ./samples -type f -name '*.exe' | \ parallel -j 8 'python mlscan.py {} --type win64 --all-layers --json {.}.json' ``` ### 完整选项参考 ``` positional: path Path to the sample file required: --type {win32,win64,dotnet,elf,apk,pdf} File family. Selects specialized models. layers: --family Enable Layer 2 (family classification) --attrib Enable Layer 3 (attribute multi-label heads) --shap Enable Layer 4 (SHAP interpretation) --all-layers Enable layers 2, 3, and 4 output: --top N Top-N cutoff for family and SHAP features (default: 10) --json PATH Write full structured result to PATH --models-dir PATH Directory containing the 14 EMBER2024 .model files --quiet Suppress non-result terminal output ``` ## 示例输出 ``` ════════════════════════════════════════════════════════════════ mlscan.py v3.1 — EMBER2024 frontend sample: loader_v3.exe (type: win64, size: 142,336 bytes) ════════════════════════════════════════════════════════════════ [Layer 1] Malicious / Benign win64 ████████████████░░░░ 0.812 ● malicious pe █████████████████░░░ 0.847 ● malicious all ██████████████░░░░░░ 0.703 ● malicious ───────────────────────────────────────── ENSEMBLE: 3/3 malicious mean=0.787 verdict: MALICIOUS [Layer 2] Family (top 10) 1. trojan.redline 0.2841 2. stealer.raccoon 0.1017 3. trojan.formbook 0.0884 ... [Layer 4] SHAP categories (sorted by |contribution|) StringExtractor +0.412 ByteHistogram +0.187 SectionInfo +0.094 ImportsInfo −0.051 ... ``` （JSON 输出以完整细节镜像此结构。） ## 使用场景 **红队预检。** 你刚刚编译了一个新的加载器，想在触碰目标前了解静态 ML 层的检测情况。向在线多 AV 服务提交是错误的做法——未公开的技巧会在数小时内进入厂商特征库。`mlscan.py` 完全在本地运行，使用许多厂商所依赖的同一公共模型。 **事件响应分类。** 批量导入数百个候选样本，运行 `mlscan.py --all-layers --json` 循环，按判决 × APT 分数排序。仅深入分析感兴趣的长尾样本。 **ML 研究基线。** 当论文声称“我们使用 EMBER2024 评估”时，这是实现该目标的 reproducible 方法。`--shap` 输出提供可解释性挂钩，用于论证为何某项规避或防御会移动分数。 **教学与工作坊。** 四层结构清晰地映射到教学弧线：浅层判决 → 家族 → 属性 → 可解释性。学生能看到每个阶段，而非一个黑盒的“恶意 = 真”。 ## 相关研究 本工具是与一项关于 EMBER2024 在构建卫生变换下的规避行为的定量研究同步开发的： 该论文中的每一幅图与每一个数字均源自 `mlscan.py --shap --json` 输出，因此读者可借助本仓库与一组测试二进制文件在本地复现所有结果。 研究发现的简要版本：综合应用标准构建卫生措施（动态 CRT、`/Brepro`、嵌入清单、版本信息资源等）可使 EMBER2024 判决从恶意翻转为良性，在 10/10 个加载器样本中实现约 0.4 的安全余量（低于 0.5 阈值）。外部加载的加载器即使投递 35 MB 的真实 Sliver C2 植入仍保持良性。资源嵌入的加载器存在边界：logit 随嵌入载荷大小大致呈对数线性增长，在约 1 MB 附近跨越阈值。SHAP 分解显示字节统计类别对大小呈单调线性响应，而结构元数据类别响应非单调；主要效应可归因于 `StringExtractor` 单独。 若你使用本工具或基于论文结果进行构建，欢迎提供指针与批评。 ## 预期用途与免责声明 `mlscan.py` 是用于静态 ML 恶意软件研究、红队自评估、事件响应分类和教学的本机分析工具。它不进行任何利用、不传播恶意软件、也不向任何外部服务提交样本。 请仅对已获授权分析的文件使用本工具。该工具生成的结果——包括低分、良性判决或“遗漏”预测——仅反映某一特定公共机器学习模型家族的行为，并非对任何文件的一般安全性声明。不要将 `mlscan.py` 输出作为清除样本、发布二进制文件或做出下游安全决策的唯一依据。 本项目与 Elastic、CrowdStrike 或 EMBER / EMBER2024 作者并无关联。 ## 许可证 MIT。参见 `LICENSE`。 ## 感谢 - 感谢 EMBER / EMBER2024 作者与贡献者发布数据集、特征提取器与训练模型。 - 感谢 LightGBM 与 NumPy 维护者。 - 感谢所有对该工具早期草案提出反馈的人——它因此变得更好。

标签：Apex, API安全, APT, CLI, cp932编码, EMBER2024, JSON输出, KDD 2025, LightGBM, Python, SHAP, WiFi技术, Win64 PE, 二分类, 云安全监控, 加壳检测, 单文件脚本, 可解释性, 多标签分类, 开源安全工具, 文件属性, 族分类, 无后门, 本地推理, 机器学习, 漏洞分析, 特征提取, 管道集成, 终端工具, 路径探测, 逆向工具, 逆向工程平台, 集成学习, 静态分析