CLI reference

MemDiver exposes a single memdiver console script with 20 subcommands. This page is auto-generated from the argparse parser — every flag listed here matches the installed version.

Common flags

Most subcommands accept:

-v, --verbose — enable DEBUG logging.
-o PATH, --output PATH — write JSON results to PATH.

The experiment subcommand additionally requires the optional memdiver[experiment] extra (pulls in frida-tools + memslicer). The LLDB backend is installed via your OS package manager.

MemDiver — Memory dump analysis platform

usage: memdiver [-h]
                {ui,analyze,scan,mcp,batch,web,app,consensus,consensus-begin,consensus-add,consensus-finalize,search-reduce,brute-force,n-sweep,emit-plugin,export,import,import-dir,verify,experiment}
                ...

Positional Arguments

command: Possible choices: ui, analyze, scan, mcp, batch, web, app, consensus, consensus-begin, consensus-add, consensus-finalize, search-reduce, brute-force, n-sweep, emit-plugin, export, import, import-dir, verify, experiment

Sub-commands

ui

Launch interactive Marimo UI

memdiver ui [-h] [extra_args ...]

Positional Arguments

extra_args: Default: []

analyze

Analyze library directories

memdiver analyze [-h] --phase PHASE --protocol-version PROTOCOL_VERSION
                 [--keylog-filename KEYLOG_FILENAME] [--template TEMPLATE]
                 [--max-runs MAX_RUNS] [--normalize] [--no-expand] [-o OUTPUT]
                 [-v]
                 library_dirs [library_dirs ...]

Positional Arguments

library_dirs: Library directory paths

Named Arguments

--phase

Lifecycle phase

--protocol-version

Protocol version

--keylog-filename

Default: 'keylog.csv'

--template

Default: 'Auto-detect'

--max-runs

Default: 10

--normalize

Default: False

--no-expand

Skip key expansion

Default: False

-o, --output

Output JSON file

-v, --verbose

Default: False

scan

Scan dataset root

memdiver scan [-h] --root ROOT [--keylog-filename KEYLOG_FILENAME]
              [--protocols [PROTOCOLS ...]] [-o OUTPUT] [-v]

Named Arguments

--root: Dataset root path
--keylog-filename: Default: 'keylog.csv'
--protocols: Protocol names to scan
-o, --output: Output JSON file
-v, --verbose: Default: False

mcp

Start MCP server for AI integration

memdiver mcp [-h] [--sse] [--port PORT] [-v]

Named Arguments

--sse

Use SSE transport instead of stdio

Default: False

--port

SSE port (default: 8080)

Default: 8080

-v, --verbose

Default: False

batch

Run batch analysis from config

memdiver batch [-h] --config CONFIG [-w WORKERS] [-o OUTPUT]
               [--output-format {json,jsonl}] [-v]

Named Arguments

--config

Batch config JSON file

-w, --workers

Number of parallel workers (default: 1)

Default: 1

-o, --output

Output file

--output-format

Possible choices: json, jsonl

Output format (overrides config); default: from config or ‘json’

-v, --verbose

Default: False

web

Launch FastAPI + React web application

memdiver web [-h] [--port PORT]

Named Arguments

--port

Server port (default: 8080)

Default: 8080

app

Launch legacy NiceGUI application

memdiver app [-h]

consensus

Build consensus matrix from dumps

memdiver consensus [-h] [--normalize] [--min-length MIN_LENGTH] [--align]
                   [--block-size BLOCK_SIZE]
                   [--alignment-bytes ALIGNMENT_BYTES] [--density DENSITY]
                   [--convergence] [--max-fp MAX_FP] [-o OUTPUT] [-v]
                   dumps [dumps ...]

Positional Arguments

dumps: Dump file paths or directories

Named Arguments

--normalize

ASLR-aware normalization

Default: False

--min-length

Minimum region length (default: 16)

Default: 16

--align

Apply alignment filtering to KEY_CANDIDATE regions

Default: False

--block-size

Alignment block size (default: 32)

Default: 32

--alignment-bytes

Memory alignment (default: 16)

Default: 16

--density

Alignment density threshold (default: 0.75)

Default: 0.75

--convergence

Run convergence sweep

Default: False

--max-fp

FP target for convergence (default: 0)

Default: 0

-o, --output

Output JSON file

-v, --verbose

Default: False

consensus-begin

Create a new incremental consensus session on disk

memdiver consensus-begin [-h] --state STATE --size SIZE [-v]

Named Arguments

--state: Path to session state JSON
--size: Consensus width in bytes
-v, --verbose: Default: False

consensus-add

Fold one dump into an existing incremental consensus session

memdiver consensus-add [-h] --state STATE [-v] dump

Positional Arguments

dump: Path to a .dump or .msl file

Named Arguments

--state: Path to session state JSON
-v, --verbose: Default: False

consensus-finalize

Materialize variance + classifications from a session

memdiver consensus-finalize [-h] --state STATE [-o OUTPUT] [-v]

Named Arguments

--state: Path to session state JSON
-o, --output: Output JSON file
-v, --verbose: Default: False

search-reduce

Reduce candidate set: variance → alignment → entropy

memdiver search-reduce [-h] --state STATE --reference-dump REFERENCE_DUMP
                       [--alignment ALIGNMENT] [--block-size BLOCK_SIZE]
                       [--density-threshold DENSITY_THRESHOLD]
                       [--min-variance MIN_VARIANCE]
                       [--entropy-window ENTROPY_WINDOW]
                       [--entropy-threshold ENTROPY_THRESHOLD]
                       [--min-region MIN_REGION] -o OUTPUT [-v]

Named Arguments

--state: Path to consensus state JSON
--reference-dump: One dump file used for per-region entropy sampling
--alignment: Default: 8
--block-size: Default: 32
--density-threshold: Default: 0.5
--min-variance: Default: 3000.0
--entropy-window: Default: 32
--entropy-threshold: Default: 4.5
--min-region: Default: 16
-o, --output: Output candidates.json
-v, --verbose: Default: False

brute-force

Iterate candidates through a user oracle script

memdiver brute-force [-h] --candidates CANDIDATES --dump DUMP --oracle ORACLE
                     [--oracle-config ORACLE_CONFIG] [--key-sizes KEY_SIZES]
                     [--stride STRIDE] [--jobs JOBS] [--first-hit]
                     [--state STATE] [--top-k TOP_K] -o OUTPUT [-v]

Named Arguments

--candidates

candidates.json from search-reduce

--dump

Reference dump file

--oracle

Path to user Python oracle script

--oracle-config

Optional TOML config passed to build_oracle

--key-sizes

Comma-separated key sizes in bytes

Default: '32'

--stride

Default: 8

--jobs

Default: 1

--first-hit

Stop at the first verified candidate (default: exhaustive)

Default: False

--state

Consensus state path (attaches neighborhood variance)

--top-k

Default: 10

-o, --output

Output hits.json

-v, --verbose

Default: False

n-sweep

Sweep N=1..N_max; emit survivor-count curve + oracle hits

memdiver n-sweep [-h] --runs-dir RUNS_DIR [--dump-glob DUMP_GLOB]
                 [--n-values N_VALUES] [--alignment ALIGNMENT]
                 [--block-size BLOCK_SIZE]
                 [--density-threshold DENSITY_THRESHOLD]
                 [--min-variance MIN_VARIANCE]
                 [--entropy-window ENTROPY_WINDOW]
                 [--entropy-threshold ENTROPY_THRESHOLD]
                 [--min-region MIN_REGION] --oracle ORACLE
                 [--oracle-config ORACLE_CONFIG] [--key-sizes KEY_SIZES]
                 [--stride STRIDE] [--first-hit] --output-dir OUTPUT_DIR [-v]

Named Arguments

--runs-dir

Directory containing run_* subdirs

--dump-glob

Glob under each run

Default: '*.msl'

--n-values

Default: '1,3,5,10,20,30,50,75,100'

--alignment

Default: 8

--block-size

Default: 32

--density-threshold

Default: 0.5

--min-variance

Default: 3000.0

--entropy-window

Default: 32

--entropy-threshold

Default: 4.5

--min-region

Default: 16

--oracle

Path to user oracle script

--oracle-config

Optional TOML config

--key-sizes

Default: '32'

--stride

Default: 8

--first-hit

Default: False

--output-dir

Directory for report.{json,md,html}

-v, --verbose

Default: False

emit-plugin

Emit a Volatility3 plugin from a brute-force hit neighborhood

memdiver emit-plugin [-h] --hit HIT --reference REFERENCE --name NAME
                     [--hit-index HIT_INDEX] [--description DESCRIPTION]
                     [--variance-threshold VARIANCE_THRESHOLD] -o OUTPUT [-v]

Named Arguments

--hit: hits.json from brute-force
--reference: Reference dump file
--name: Plugin class / rule name
--hit-index: Default: 0
--description
--variance-threshold: Max variance for static bytes (default: 3000). Lower values produce more wildcards → more cross-session robust patterns.
-o, --output: Output .py file path
-v, --verbose: Default: False

export

Export pattern as YARA/JSON/Volatility3

memdiver export [-h] [--offset OFFSET] [--length LENGTH] [--auto]
                [--context CONTEXT] [--name NAME]
                [--format {yara,json,volatility3,vol3}]
                [--min-static-ratio MIN_STATIC_RATIO] [--align] [-o OUTPUT]
                [-v]
                dumps [dumps ...]

Positional Arguments

dumps: Dump file paths or directories

Named Arguments

--offset

Region offset (hex or decimal)

--length

Region length in bytes

--auto

Auto-detect largest KEY_CANDIDATE region

Default: False

--context

Bytes of context around auto-detected region (default: 32)

Default: 32

--name

Pattern name

Default: 'memdiver_pattern'

--format

Possible choices: yara, json, volatility3, vol3

Default: 'volatility3'

--min-static-ratio

Minimum static byte ratio (default: 0.3)

Default: 0.3

--align

Use alignment-filtered candidates for auto-detection

Default: False

-o, --output

Output file path

-v, --verbose

Default: False

import

Import raw .dump to .msl

memdiver import [-h] [-o OUTPUT] [--pid PID] [--keylog KEYLOG] [-v] dump_file

Positional Arguments

dump_file: Raw dump file path

Named Arguments

-o, --output

Output .msl file path

--pid

Process ID

Default: 0

--keylog

Keylog file for key hints

-v, --verbose

Default: False

import-dir

Import all dumps in a directory

memdiver import-dir [-h] -o OUTPUT_DIR [--keylog-filename KEYLOG_FILENAME]
                    [-v]
                    run_dir

Positional Arguments

run_dir: Run directory path

Named Arguments

-o, --output-dir: Output directory
--keylog-filename: Default: 'keylog.csv'
-v, --verbose: Default: False

verify

Verify candidate key via decryption

memdiver verify [-h] --offset OFFSET [--length LENGTH] --ciphertext-hex
                CIPHERTEXT_HEX [--iv-hex IV_HEX] [--cipher CIPHER] [-o OUTPUT]
                [-v]
                dump

Positional Arguments

dump: Dump file path

Named Arguments

--offset

Candidate key offset (hex or decimal)

--length

Key length (default: 32)

Default: 32

--ciphertext-hex

Known ciphertext (hex)

--iv-hex

IV (hex, default: 0x00010203…0f)

--cipher

Cipher name

Default: 'AES-256-CBC'

-o, --output

Output JSON file

-v, --verbose

Default: False

experiment

Run full dump-and-analyze experiment

memdiver experiment [-h] --target TARGET [--num-runs NUM_RUNS] [--tools TOOLS]
                    [--output-dir OUTPUT_DIR] [--convergence]
                    [--max-fp MAX_FP]
                    [--export-format {yara,json,volatility3}] [-o OUTPUT] [-v]

Named Arguments

--target

Target script path (e.g., aes_sample_process.py)

--num-runs

Number of dump iterations per tool (default: 30)

Default: 30

--tools

Comma-separated dump tools (default: auto-detect)

--output-dir

Output directory (default: ./experiment_output)

Default: experiment_output

--convergence

Run convergence sweep after dumping

Default: False

--max-fp

FP target for convergence (default: 0)

Default: 0

--export-format

Possible choices: yara, json, volatility3

Auto-export format (default: volatility3)

Default: 'volatility3'

-o, --output

Output JSON results file

-v, --verbose

Default: False