VolMemLyzer (Volatile Memory Analyzer)

VolMemLyzer is a modular memory forensics toolkit that wraps Volatility 3 with three complementary workflows:

1. Run mode – ergonomic “Volatility-as-a-service”: run plugins in parallel, cache outputs, and keep artifact naming/dirs predictable for downstream code.
2. Extract mode – registry-driven feature extraction from plugin outputs, flattened and stable (CSV/JSON) for ML pipelines.
3. Analyze mode – a stepwise DFIR triage workflow (bearings → processes → injections → network → persistence) with clear, Rich-rendered tables.

VolMemLyzer aims to unlock Volatility’s full potential for researchers and analysts who want frictionless runs inside their own codebases—not just from Volatility’s CLI.

---

Table of contents

• Quickstart (Compatibility Shim)
• Why v3 (at a glance)
• Key capabilities
• How it fits together
• Requirements
• Installation
• CLI usage (volmemlyzer)
  • Global options
  • analyze
  • run
  • extract
  • Feature Catalog (Index)
  • list
• Python API
• Artifacts, formats & caching
• Performance tips
• Troubleshooting
• Roadmap
• License
• Team Members
• Acknowledgement

---

Quickstart (Compatibility Shim)

Heads up about main.py (compatibility shim): A small main.py is included only for backward compatibility with older docs/scripts. It accepts the legacy flags and produces a single aggregated features file per run. If you don't need this legacy entry point, you can remove main.py. Keeping it won't cause drift because it calls the library directly.

Preferred interface: use the packaged CLI command volmemlyzer (see below).

• CSV → <outdir>/features/output.csv (one row per image)
• JSON → <outdir>/features/output.json

Quickstart with main.py

Process a single dump

python main.py \
  -f /path/to/images/IMAGE.mem \
  -o ./out \
  -V /path/to/volatility3/vol.py

Batch a folder of dumps (recursive)

python main.py \
  -f /path/to/images/ \
  -o ./out \
  -V /path/to/volatility3/vol.py

The tool writes out/features/output.csv with one row per image.

Speed up triage by skipping heavy plugins (Not using the --drop or --plugins will result in running all plugins in the plugins.py). example:

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"

Legacy options (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

---

Why v3 (at a glance)

• Modular architecture (Runner → Registry → Pipeline → Analysis/TUI → CLI) so you can import only the pieces you need.
• Research-friendly UX: parallel plugin execution, caching & (where possible) output conversion to avoid reruns, stable artifact naming, and one-row-per-image FeatureRow for ML.
• DFIR triage workflow: opinionated but explainable steps with clean tables (thanks to Rich).
• Stable, flat features: consistent columns across images, robust null handling, clear plugin.metric naming.

---

Key capabilities

• Run Volatility 3 plugins with:

  • parallelism (-j/--jobs),
  • per-plugin timeouts,
  • per-run renderer choice,
  • cache reuse with optional conversion to the needed format (see notes below).
  • Complete end-to-end pipeline capable of automatic resolving of the volatility path (Runs as service)

• Extract features from selected plugins via a registry of extractor functions:

  • flatten to a single CSV/JSON file per run (one row per image),
  • ML-ready features with consistent naming,
  • dependency-aware scheduling of plugins.

• Perform an analysis as a multi-step DFIR overview (which can be outputted in json):

  • 0 Bearings (windows.info)
  • 1 Processes (pslist+ psscan+ psxview+ pstree + cross-checks)
  • 2 Injections (malfind)
  • 3 Network (netscan)
  • 4 Persistence (registry/tasks : scheduled_tasks + userassist +hivelist/hivescan)

---

How it fits together

CLI ──► Pipeline ──► VolRunner (vol.py) ──► artifacts/*.json|jsonl|csv|txt
                    │
                    ├─► Extractors (registry) ──► FeatureRow rows → output.csv
                    │
                    └─► OverviewAnalysis (steps) ──► Rich tables / JSON summary

• VolRunner builds/executes vol.py commands and names outputs predictably:
  <outdir>/<imagebase>_<plugin>.<ext> plus <…>.stderr.txt on errors.
• Pipeline orchestrates parallel runs, caching, and (when supported) format conversion to avoid re-running a plugin just to change formats.
• ExtractorRegistry binds a plugin spec (windows.pslist, deps, default renderer/timeout) to a Python extractor function. All available volatility plugins are added by default
• OverviewAnalysis implements the triage steps; TerminalUI (Rich) prints academic-style tables with a tasteful left accent bar.

---

Requirements

• Python 3.9+
• A local checkout/installation of Volatility 3; you will point VolMemLyzer at vol.py using --vol-path (or VOL_PATH env).
  VolMemLyzer does not import Volatility; it invokes it as a subprocess.
• Python packages (installed automatically if you use pip install):
  • pandas, numpy, python-dateutil, tqdm, rich

Tested primarily with Windows images (e.g., .vmem, .raw, .dmp, .bin). Other OSes may work where Volatility supports them.

Zero-friction Volatility path (no --vol-path needed): In v3, if you don’t pass --vol-path, VolMemLyzer automatically resolves Volatility 3 in this order: (1) any explicit hint you provided (--vol-path or the VOL_PATH env var); (2) an importable module in the current environment — it launches python -m volatility3; (3) the vol console script on your PATH; and (4) a few common local vol.py locations. This removes path-hunting and venv confusion, so most users can run one-line commands with sane defaults, while power users can still pin a specific checkout by supplying --vol-path. The result is a cleaner, faster CLI with fewer errors and zero reliance on hard-coded filesystem paths.

---

Installation

From PyPI (recommended once published)

pip install volmemlyzer
# then the CLI is available as:
volmemlyzer --help

<!-- you should see the help page like this:  -->

From source (develop/editable)

git clone https://github.com/<you>/volmemlyzer.git
cd volmemlyzer
pip install -e .
# or, without packaging:
pip install -r requirements.txt
python -m volmemlyzer.cli --help or volmemlyzer --help

<!-- **Environment knobs (optional):** - `VOL_PATH` – default path to `vol.py` - `VMY_RENDERER` – default renderer (e.g., `json`) - `VMY_TIMEOUT` – default timeout in seconds (0 disables) - `VMY_LOG` – log level (`INFO`, `DEBUG`, …) -->

---

<!-- ## CLI usage (volmemlyzer) The packaged CLI exposes **analysis**, **run**, **features**, and **list** subcommands. ### Global options ``` --vol-path PATH Path to volatility3 vol.py Optional(env: VOL_PATH) except when no vol.py is detected by volmemlyzer --renderer NAME Volatility output renderer format (json/jsonl/csv/pretty/quick/none : **json default**) --timeout SECONDS Per-plugin timeout (default : 0 disables) -j, --jobs N Parallel workers (default : 0.5 * of available CPUs) --log-level LEVEL CRITICAL|ERROR|WARNING|INFO|DEBUG ``` ### `analysis` Run DFIR triage steps over one image. ```bash volmemlyzer \ --vol-path "C:\tools\volatility3\vol.py" --renderer json --timeout 600 -j 4 \ analysis -i "D:\dumps\host.vmem" -o "D:\dumps\.volmemlyzer" \ --steps 0,1,2,3,4,5,6 --json "D:\dumps\reports\host.overview.json" \ --no-cache ``` Options: - `-i/--image` (required): memory image file - `-o/--outdir`: artifacts directory (default is created near the image) - `--steps` (comma list or aliases: `bearings|info`, `processes|proc|ps`, `injections|malfind`, `network|net|netscan`, `persistence|reg|tasks`, `kernel`, `report`) - `--json`: write the step summary to a JSON file - `--high-level`: when supported, show only the highest-risk findings - `--no-cache`: ignore cached plugin outputs ### `run` Run raw Volatility plugins (parallel, cached, selected renderer). ```bash volmemlyzer \ --vol-path /opt/volatility3/vol.py --renderer json -j 6 \ run -i /cases/win10.raw -o /cases/.volmemlyzer \ --plugins pslist,pstree,psscan --no-cache ``` Options: - `-i/--image` (required): memory image file - `-o/--outdir`: artifacts directory (default near the image) - `--renderer`: renderer for this run (`json|jsonl|csv|pretty|quick|none`) - `--plugins`: comma list to include - `--drop`: comma list to exclude - `--no-cache`: ignore cached outputs **Output:** The CLI prints the art