YaCnDehfuli/VolMemLyzer3-CLI_forensic_tool
GitHub: YaCnDehfuli/VolMemLyzer3-CLI_forensic_tool
一款模块化的 Volatility 3 内存取证工具包，支持并行插件执行、ML 就绪特征提取和渐进式 DFIR 分诊分析。
Stars: 0 | Forks: 0
# VolMemLyzer (易失性内存分析器)
[](LICENSE)
**技术焦点：** DFIR 自动化 · 易失性内存分析 · Volatility 3 · 并发提取 · IoC 关联 · 分析师分诊
**VolMemLyzer** 是一个模块化的内存取证工具包，它通过三个互补的工作流封装了 **Volatility 3**：
1. **Run 模式** – 便捷的“Volatility 即服务”：并行运行插件、缓存输出，并为下游代码保持工件命名/目录的可预测性。
2. **Extract 模式** – 基于注册表的**特征提取**，从插件输出中进行提取，经扁平化处理并保持稳定 (CSV/JSON)，适用于 ML pipeline。
3. **Analyze 模式** – 渐进式的 **DFIR 分诊**工作流（基本环境 → 进程 → 注入 → 网络 → 持久化），具有清晰且由 Rich 渲染的表格。
VolMemLyzer 旨在为希望在自己的代码库中无摩擦运行的研究人员**和分析师**释放 Volatility 的全部潜力——而不仅仅是从 Volatility 的 CLI 中运行。
## 目录
- [快速开始（兼容性垫片）](#quickstart-compatibility-shim)
- [为什么选择 v3（一览）](#why-v3-at-a-glance)
- [核心功能](#key-capabilities)
- [工作原理](#how-it-fits-together)
- [环境要求](#requirements)
- [安装](#installation)
- [CLI 用法 (volmemlyzer)](#cli-usage-volmemlyzer)
- [全局选项](#global-options)
- [analyze](#analyze)
- [run](#run)
- [extract](#extract)
- [特征目录（索引）](#feature-catalog-index)
- [list](#list)
- [Python API](#python-api)
- [工件、格式与缓存](#artifacts-formats--caching)
- [性能提示](#performance-tips)
- [故障排除](#troubleshooting)
- [路线图](#roadmap)
- [许可证](#license)
- [团队成员](#team-members)
- [鸣谢](#acknowledgement)
## 快速开始（兼容性垫片）
关于 `main.py`（兼容性垫片）的提醒：保留一个小型的 `main.py` **仅**是为了向后兼容旧文档/脚本。它接受传统的参数，并在每次运行时生成一个**单一的聚合特征文件**。
如果您不需要此遗留入口点，可以删除 `main.py`。保留它不会导致偏差，因为它会直接调用库。
**首选接口：** 使用打包的 CLI 命令 `volmemlyzer`（见下文）。
- CSV → `/features/output.csv`（每个镜像一行）
- JSON → `/features/output.json`
### 使用 `main.py` 快速开始
**处理单个转储文件**
```
python main.py \
-f /path/to/images/IMAGE.mem \
-o ./out \
-V /path/to/volatility3/vol.py
```
**批量处理文件夹中的转储文件（递归）**
```
python main.py \
-f /path/to/images/ \
-o ./out \
-V /path/to/volatility3/vol.py
```
该工具会写入 **`out/features/output.csv`**，其中**每个镜像一行**。
通过跳过繁重的插件来**加快分诊速度**（如果不使用 --drop 或 --plugins，将运行 plugins.py 中的所有插件）。示例：
```
python main.py -f ./mem -o ./out -V ./volatility3/vol.py \
-D "dumpfiles,filescan,mftscan,driverscan,mutantscan,modscan,netscan,poolscanner,symlinkscan,callbacks,deskscan,devicetree,driverirp,drivermodule,windowstations"
```
**遗留选项 (main.py)**
```
-f, --memdump Path to a memory image OR a folder of images (required)
-o, --output Output directory for artifacts & features (required)
-V, --volatility Path to Volatility3's vol.py (required)
-D, --drop Comma-separated plugin list to skip (e.g., "filescan,modscan")
-P, --plugins Comma-separated plugin list to include
-F, --format csv|json (default: csv)
-j, --jobs Parallel workers
--no-cache Ignore cached plugin outputs
```
## 为什么选择 v3（一览）
- **模块化架构**（Runner → Registry → Pipeline → Analysis/TUI → CLI），您可以只导入需要的部分。
- **对研究人员友好的 UX**：并行插件执行、缓存和（在可能的情况下）输出格式转换以避免重新运行、稳定的工件命名，以及针对 ML 的每镜像一行 **FeatureRow**。
- **DFIR 分诊工作流**：主观但具备可解释性的步骤，带有清晰的表格（得益于 **Rich**）。
- **稳定、扁平的特征**：跨镜像的列名一致，稳健的 null 处理，清晰的 `plugin.metric` 命名。
## 核心功能
- **运行 Volatility 3 插件**支持：
- 并行执行 (`-j/--jobs`),
- 每个插件单独设置超时，
- 每次运行选择渲染器，
- 缓存重用，并可选择转换为所需格式（见下方说明）。
- 完整的端到端 pipeline，能够自动解析 Volatility 路径（作为服务运行）
- 通过提取器函数的**注册表**从选定插件中**提取特征**：
- 每次运行扁平化为单个 **CSV/JSON** 文件（**每个镜像一行**），
- 命名一致的 ML 就绪特征，
- 具备依赖感知能力的插件调度。
- 以多步骤 DFIR 概览的形式**执行分析**（可输出为 JSON）：
- 0 基本环境 (`windows.info`)
- 1 进程 (`pslist`+ `psscan`+ `psxview`+ `pstree` + 交叉检查)
- 2 注入 (`malfind`)
- 3 网络 (`netscan`)
- 4 持久化 (注册表/任务 : `scheduled_tasks` + `userassist` +`hivelist/hivescan`)
## 工作原理
```
CLI ──► Pipeline ──► VolRunner (vol.py) ──► artifacts/*.json|jsonl|csv|txt
│
├─► Extractors (registry) ──► FeatureRow rows → output.csv
│
└─► OverviewAnalysis (steps) ──► Rich tables / JSON summary
```
- **VolRunner** 构建/执行 `vol.py` 命令，并以可预测的方式命名输出：
`/_.`，出错时还会有 `<…>.stderr.txt`。
- **Pipeline** 负责编排并行运行、缓存，以及（在支持的情况下）格式转换，以避免仅仅为了更改格式而重新运行插件。
- **ExtractorRegistry** 将插件规范（`windows.pslist`、依赖项、默认渲染器/超时）绑定到 Python 提取器函数。默认情况下会添加所有可用的 Volatility 插件。
- **OverviewAnalysis** 实现了分诊步骤；**TerminalUI** (Rich) 打印具有学术风格的表格，并带有雅致的左侧装饰条。
## 环境要求
- Python **3.9+**
- 本地检出/安装的 **Volatility 3**；您需要使用 `--vol-path`（或 `VOL_PATH` 环境变量）为 VolMemLyzer 指定 `vol.py` 的路径。
VolMemLyzer **不会导入** Volatility；它将作为子进程**调用**它。
- Python 包（如果您使用 `pip install` 则会自动安装）：
- `pandas`, `numpy`, `python-dateutil`, `tqdm`, `rich`
**零摩擦的 Volatility 路径（无需 --vol-path）：**
在 v3 中，如果您不传递 --vol-path，VolMemLyzer 会按以下顺序自动解析 Volatility 3：(1) 您提供的任何明确提示（--vol-path 或 VOL_PATH 环境变量）；(2) 当前环境中的可导入模块——它会启动 python -m volatility3；(3) 您 PATH 中的 vol 控制台脚本；(4) 一些常见的本地 vol.py 位置。这消除了路径寻找和虚拟环境带来的困扰，因此大多数用户都可以使用合理的默认值运行单行命令，而高级用户仍然可以通过提供 --vol-path 来指定特定的检出路径。最终的结果是一个更简洁、更快的 CLI，它减少了错误，并且完全不依赖硬编码的文件系统路径。
## 安装
### 从源码安装（推荐）
```
git clone https://github.com/YaCnDehfuli/VolMemLyzer3-CLI_forensic_tool.git
cd VolMemLyzer3-CLI_forensic_tool
pip install -e .
# 或者，不进行打包：
pip install -r requirements.txt
python -m volmemlyzer.cli --help or volmemlyzer --help
```