0xInitZer0/MalStat

# MalStat MalStat 是一个用于 Windows 可执行文件的静态 PE 恶意软件分类工具包。它从 EXE、DLL 和 SYS 文件中提取结构特征，应用校准的机器学习分类器，并生成可解释的 JSON 和 HTML 报告，而无需执行样本。  ## 为什么存在这个仓库 这个仓库是 MalStat 项目的干净公共运行时仓库。 它故意包含： - `src/` 和 `scripts/` 下的规范源代码； - `models/` 下的最小运行时模型包； - 运行时模板和配置文件，用于推理； - 为用户提供自己的本地数据集的训练和评估代码路径。 它故意不包含私有数据集、训练/评估输出或位于此仓库之外的独立作者端课程文档文件夹。 ## 关键功能 - 不运行它们即可对 Windows PE 文件进行静态分析。 - 在文件、头部、部分、导入、字符串、资源、操作码和可选声誉层中进行特征提取。 - 包含规范模型工件的自定义 `LightGBM` 推理。 - 单文件和批量工作流程的 JSON 和 HTML 报告。 - 提供本地干净训练子集后可重复训练。 - 用于阈值选择、错误审查和针对本地工件的外部保留检查的评估工具。  ## 仓库布局 ``` . |- configs/ Runtime and evaluation configuration |- data/ Local ignored workspace for private datasets and generated dataset artifacts |- models/ Canonical runtime model bundle only |- scripts/ CLI entry points for analysis, dataset building, training, and evaluation |- src/ Core project implementation |- templates/ HTML report template(s) |- tests/ Minimal smoke tests for CI |- CHANGELOG.md Release notes |- Dockerfile Reproducible container runtime |- README.md This document |- VERSION Repository release version `- requirements.txt Exact tested dependency set ``` ## 位置和内容 ### 运行时和推理 - `scripts/analyze_file.py` 分析单个文件。 - `scripts/analyze_directory.py` 分析目录树。 - `src/inference/` 包含运行时分析路径。 - `src/reporting/` 渲染可解释的输出有效载荷。 ### 数据集和训练 - `scripts/build_dataset.py` 从聚合数据集存储中提取和追加行。 - `scripts/export_clean_training_subset.py` 导出干净的监督子集。 - `scripts/train_model.py` 训练规范分类器。 - `scripts/evaluate_model.py` 构建详细的评估报告。 - `src/training/` 和 `src/evaluation/` 包含训练和评估逻辑。 ### 发布的工件 - `models/calibrated_model.pkl` 是规范发布的分类器。 - `models/preprocessor.pkl` 是规范的特征预处理器。 - `models/feature_columns.json` 确定了预期的特征顺序。 ### 运行时生成 - `reports/` 用于生成的分析输出，并且故意被 git 忽略。 - `data/` 是本地工作区域，用于私有数据集和导出的训练子集，并且故意被 git 忽略。 - `models/` 下的非运行时文件，如实验日志、评估报告、预测表和最佳快照，故意被 git 忽略。 ## 系统要求 - Python `3.13.x` - `pip` 和 `venv` - `requirements.txt` 中固定的平台支持的轮子 - 足够的磁盘空间用于模型工件、生成的报告和可选数据集增长 该项目分析 Windows PE 文件，但工具本身可以从非 Windows 主机运行，因为它执行静态解析而不是样本执行。 ## 快速入门 ### 1. 创建虚拟环境 #### PowerShell ``` python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip setuptools wheel python -m pip install -r requirements.txt ``` #### Bash ``` python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip setuptools wheel python -m pip install -r requirements.txt ``` ### 2. 验证已发布的 CLI 入口点 ``` python scripts/analyze_file.py --help python scripts/analyze_directory.py --help python scripts/train_model.py --help python scripts/evaluate_model.py --help ``` ### 3. 运行第一次分析 分析单个文件： ``` python scripts/analyze_file.py "C:\path\to\sample.exe" ``` 递归分析目录： ``` python scripts/analyze_directory.py "C:\path\to\samples" --recursive --no-html ``` 默认情况下，生成的输出写入 `reports/`，这是故意被 Git 忽略的。 VirusTotal 查询默认禁用。仅当您明确需要远程哈希声誉查询并已配置 `VT_API_KEY` 到环境或 `.env` 中时，才添加 `--enable-virustotal`。 ## 第一次运行工作流程 ### 单文件推理 ``` python scripts/analyze_file.py "C:\path\to\sample.exe" --json-out sample.analysis.json --html-out sample.analysis.html ``` ### 批量推理 ``` python scripts/analyze_directory.py "C:\path\to\samples" --recursive --output-root reports\batch_analysis\run01 ``` ### 从新文件或目录构建数据集行 这些数据集和训练工作流程需要 `data/` 下的私有本地数据集工作空间；它们不是公共运行时包的一部分。 ``` python scripts/build_dataset.py "C:\path\to\samples" --source manual --label 0 --label-confidence high ``` ### 导出干净的监督训练子集 ``` python scripts/export_clean_training_subset.py ``` ### 重新训练规范分类器 ``` python scripts/train_model.py ``` ### 重新构建评估报告 ``` python scripts/evaluate_model.py ``` ## 可选工具 此仓库在没有以下工具的情况下也可以工作。仅在需要相关工作流程时安装它们。 ### FLOSS FLOSS 改进了混淆样本的字符串提取。 Windows 上的首选安装方法： 1. 从官方 Mandiant FLARE-FLOSS 发布页面下载独立可执行文件。 2. 将 `floss.exe` 放在您的 `PATH` 中，或者将其放置在已知工具目录中，并相应地配置您的环境。 替代 Python 软件包安装： ``` python -m pip install flare-floss ``` ### VirusTotal VirusTotal 查询是可选的。 - 在您的环境或本地 `.env` 文件中设置 `VT_API_KEY`。 - 将 `--enable-virustotal` 添加到 `scripts/analyze_file.py`、`scripts/analyze_directory.py`、`scripts/main_extractor.py`、`scripts/build_dataset.py` 或 `scripts/backfill_dataset_features.py`，当您明确需要远程哈希查询时。 - 不设置标志以保持分析完全本地化。 ### SHAP 仅当您需要针对训练模型的额外后处理解释时使用 SHAP。 ``` python -m pip install shap ``` ### Plotly 和 Kaleido 使用 Plotly 进行更丰富的交互式绘图，并使用 Kaleido 进行静态图像导出。 ``` python -m pip install plotly kaleido ``` ### PyTorch PyTorch 是可选的，并且仅在您添加实验性神经基线时相关。 当可能时，使用官方安装选择器，因为 CPU 和 CUDA 轮子根据平台而有所不同。 典型的仅 CPU 安装示例： ``` python -m pip install torch --index-url https://download.pytorch.org/whl/cpu ``` ## 包含在此仓库中的规范快照 - 规范模型版本：`20260525T112232Z` - 规范分类器：`lightgbm` - 规范操作阈值：`0.454123` - 发布的仓库版本：`0.1.0` ## 可重复性 此仓库包括几个可重复性控制： - `requirements.txt` 锁定了确切的测试 Python 软件包版本。 - `VERSION` 是仓库发布的唯一真相来源。 - `CHANGELOG.md` 记录了仓库级别的发布说明。 - `Dockerfile` 提供了可重复的运行时容器。 - GitHub Actions 验证安装、CLI 帮助路径、烟雾测试和 Docker 可构建性。 ## CI/CD 此仓库包含： - `CI` 工作流程：安装固定的依赖项，运行烟雾测试，验证 CLI 入口点，并构建 Docker 图像。 - `Release` 工作流程：验证 Git 标签是否与 `VERSION` 匹配，创建源存档，并将其附加到 GitHub 发布。 ## 发布纪律 使用此发布流程进行干净的 GitHub 发布： 1. 更新代码和文档。 2. 使用语义版本控制更新 `VERSION`，例如 `0.2.0`。 3. 将发布说明添加到 `CHANGELOG.md`。 4. 提交发布更改。 5. 将发布标记为 `vX.Y.Z`，例如 `v0.2.0`。 6. 将标签推送到触发发布工作流程。 ## 最小维护清单 - 保持 `requirements.txt` 锁定。 - 将生成的输出排除在版本控制之外。 - 为每次发布更新 `CHANGELOG.md`。 - 在更改模型工件后重新运行烟雾测试。 - 将 `models/calibrated_model.pkl`、`models/preprocessor.pkl` 和 `models/feature_columns.json` 作为发布的运行时合同处理。 ## 典型输出示例  在成功运行单个文件后，您应该期望： - JSON 分析有效载荷； - 可选的 HTML 报告； - 在终端中打印的摘要，包括结论、概率、阈值、模型名称和模型版本。 ## 范围说明 MalStat 是一个静态分类工具。它旨在优先考虑和解释可疑的 PE 文件，而不是像完整的生产级防病毒引擎那样具有动态解包、实时遥测或企业响应编排功能。 ``` :+xXX$$$$$$$$$Xx: ++++;;;+xXxxXXXXXXXXX$$&$X+ ::::;+xXXX$$$XXXxxx++xX$$$$$$$&&$; .::+$&&&$$&&&$$$$$$$XX$$X;;;x$$X$$$$&&$x :;X&&&&&&$$XXXXXXxxXxxxxxXxxxx+:;x$$$$$$&&&X: :x&&&&&$$$xxxxxx+++++;;;;;;++++++xx:;x&&$&$$&&&$; :X&&&&&$$XXXxx++xX;++++x:::::::::;+x;++;+X&&$&$$&&&X: .x&&&&&&$$Xxxxx+;;;X+;;;;x:::::::::;;:;;+++;x$&&&$$$&&$X :$&&$X+X$XX$xx++;;::+x:;;;+:::::::::X;::::+;+++X&&$&$$&&&$; .x&&&: +x+xX$X$+;;;;:::x:;;++::::::::X+::::::;;:++x&&$&$$$&&$+ .$&&$ xxxXxxxX;;::::;x:;;++:::::::x;:::::::::;;+;x&&$&$$$&&$$ .$&&$ :++Xx;xx:::::x++;;++::::::++:::::::::::;;;+x$&$&$$$&&Xx .$&&& .;;+;xX:x+:::;:;x;;+;:::::xx::::::::::::::+;;X&&$&$$$&&$X .$&&&. .;;;;;+;x;X;::::::::;:::::++::::::::::::::::+x+x&&$&$$$&&$+ X&&&$. ;:;;;::+:::.:::::::.;:;:::::::::::::::::X$+:;;;xX&&&$$$&&$$: ;&&&&X$Xx. ::;;;::::: ;;:::::+;;+++::::::::::::x$+:+$X:;+;X$&$&$$$&&XX .$&&&+ ;+xx;;;;:::::. ..:::::x:;+;::;:::::.:;Xx:;x$;::::;;+X&$&&$$$&&X+ +&&&X. ; .;;$Xx+::::. ...::::x;++;::::;::.:;;:+$+::::::::+:x&&$&$$$&&XX .$&&&x. ;. .;:;+:;:::;.. ..::::;;:;;::::::;::::xx:::::::::::+:x$&$&$&$$&$X; ;&&&&;:.; .;::;:x:::;: ...::::+;;;;:::::::::::::::::::::::::;+X&$$&$$$&$X+ +&&&$. ::.:;::;::::+:. ...:::.x:;;::::.::::;::::::::::::::::+;X$&$&$$$&&XX x&&&X:.:::.;::::::;::.. ...::::x:;;:::::::::;::::::::::::::::;:X$&$&$&$$&XX .X&&&x;::::.:::;;::+::. . ...:::;x:+;::::::.:::+:::+XXXXX$X$$$;::XX&$&$&$$&XX. .$&&&x;:::::xxx;::::::....:;;:;xxxXx;::::::::::X::::;;;;:;;;;;:::xX$$&X$$&&XX: .$&&&x;;+;::::;;;:::::....:x+xxx$XXXXXXXXXXXxxxxxx+;;;;;;;;;;+:::XX$$&X&$$&XX: .$&&&x::x;::++xx;::;::.......::+x+xxx+++++++xxxXx++X&&$$$$$$$$;::X$$$&$&$$&XX. .X&&&X:;;;:::::::::;::........:xX;++;:::::::::;;:;;;;;;;;;:::::;;X$&$&X$$$&Xx .x&&&&XXx+;:::+X+:::+:........::::;;::::::::::;::::::::::::::::+;X$&$&$$$&&Xx x&&&$xxxxx+X$;:X+:::;::::....::::::::::::.::::.:.:::::.:::::::;+$&$$$$$$&$x; ;&&&&&$$$$X;xX+:x+::;::::::..:::::.::::::::;;:..:+Xx:::::::::+:x&&$&$&$&&$x: .X&&&&$$XX$X;;$x::::::+::::...:::.::::::::;::::;+:::x$+:::::;;;X&&$&$$$&&Xx ;&&&&&&$XxX$+:+xX;:::::;:........::...:;;......;$XXx;;X$+::;.X&&$&$$X$&$x; :x&&&&$$$$xX+;X;:::;:::::;:::......::+:....::::::;x;+$$++;;:+X&&$&X$$&&x+ ;$&&&&&$$x+$x::::;x:X:::::::::;:::::::::::::::::::;x:::;;:;X&&$&$$X&&X+ +&&&&&&$X$+;:::;X:$;:x...........:::::+::::::::::::;x;;;.X$&$&$$X$&$+: :+$&&&&$$X+;;:;X:x::$;:..:x;.:....::::X$:::::::::::::;;:X$&&$&X$$&&+; :x$&&&&&$X+;;X;x+;xx.....x+.$:..::::.:XX;::::::::::;;:x$&&$$X$$&$+; :x$&&&&&$$+&;Xx+:x;.....x+.X;..::::::;+&x::::::::x+:X$&$$&XX$&&+; .XX&&&&&$Xx+xx;;x:::...x++;;..:::::::+:xX:::::+;:+X&&$$$XX$&$+. +x$&&&&$XXx;;X::.....++$;x.:::::::::x:+$;:;;::X$&&X&$$X$&X; :xx$&&&&$X++;:::::::x+x:X::::::::::x;:;+;;:+$&&$$$XXX&&+. +xx$&$&&$X+++;::::xx;:X::::::::::;+;X;;;X$&$$&XXX$&X: +XxX&&$$$xx++;;++;:::::::;++;;:x+;:xX$&$X&XXX$&X; ;XXxX$$$$Xx++x++x;;;+;;;;+x+;;+X$$$X$$XXX&&X: ;+XXX++x$$$XXxxxx+x+x+.:xX$$&$XX&XXx$&&+ ;xxxXXXXXxxxxxxX$$$$$$XXXX$XxX$&$; xXXxxx+xxxx++xX$$XxxxX$&$+ .;xX$$$$$$$$Xx;. ```

标签：Homebrew安装, 多模态安全, 逆向工具