MemSlicer

A memory acquisition tool that captures process memory snapshots into the MSL (Memory Slice) binary format. Supports multiple debugger backends (Frida, GDB, LLDB) and targets across Windows, Linux, macOS, Android, and iOS. Designed for forensic analysis, reverse engineering, and security research.

---

Features

• Pluggable backends: Frida (local, USB, remote), GDB (MI3 protocol), LLDB (Python API)
• Investigation mode: Captures system-wide context — process tables, network connections, file handles, boot time, OS details
• AEAD encryption: AES-256-GCM with Argon2id key derivation (default in investigation mode)
• MSL binary format with region metadata, module info, and page-level granularity
• Compression support: zstd, lz4, or none
• BLAKE3 integrity chain across all blocks
• Region filtering by memory protection, address range, or path patterns
• Page-level acquisition with quality assessment
• RWX region detection for forensic analysis
• Progress reporting with per-region and per-page statistics
• Companion log file captures all debug output regardless of verbosity flag
• Cross-platform OS information collection for forensic context

---

Installation

pip install memslicer

This installs memslicer with all backends (Frida, GDB, LLDB).

From Source

git clone git@github.com:MemorySlice/memslicer.git
cd memslicer
pip install -e .

Requires Python >= 3.10. Backend-specific requirements:

• Frida: A compatible Frida agent on the target device (for USB/remote targets)
• GDB: gdb binary with MI3 support (installed separately)
• LLDB: LLDB Python module on PYTHONPATH (typically via Xcode on macOS)

---

Usage

Basic Examples

Dump a process by name (Frida backend, default):

memslicer chrome

Dump a process by PID:

memslicer 1234

Specify output file and compression:

memslicer chrome -o chrome_dump.msl -c zstd

Linux

Dump a local process using Frida (default backend):

memslicer 1234

Use GDB backend (no Frida dependency required):

memslicer 1234 -b gdb

Investigation mode with full system context (encrypted by default):

memslicer 1234 -I -v

This captures process tables, network connections, file handles, boot time, hostname, and OS details from /proc alongside the memory dump. The output is encrypted with AES-256-GCM; you will be prompted for a passphrase.

Investigation mode without encryption:

memslicer 1234 -I --no-encrypt

Android

Dump a process on a USB-connected Android device (requires Frida server on device):

memslicer com.example.app -U

Override OS detection if auto-detection fails:

memslicer com.example.app -U --os android

Investigation mode on Android (captures system properties, process table, network state):

memslicer com.example.app -U -I

Connect to a remote Frida server on Android (e.g., over Wi-Fi):

memslicer com.example.app -R 192.168.1.10:27042 --os android

Dump by PID on a USB Android device:

memslicer 12345 -U --os android -o app_dump.msl -c zstd

macOS / iOS

Use LLDB backend on macOS (no Frida needed):

memslicer 1234 -b lldb

Dump a process on a USB-connected iOS device (jailbroken, Frida):

memslicer SpringBoard -U --os ios -I

Windows

Dump a local process on Windows:

memslicer 1234 -b gdb

Or with Frida:

memslicer notepad.exe

Common Workflows

Forensic capture with full debug log:

memslicer 4892 -v -o evidence.msl -c zstd

Investigation mode with encryption (default):

memslicer 4892 -I -o investigation.msl

Capture only readable and writable regions:

memslicer chrome --filter-prot rw-

Capture a specific address range:

memslicer chrome --filter-addr 0x7fff00000000-0x7fffffffffff

Include regions without read permission (for completeness):

memslicer chrome --include-unreadable

Limit region size and set a per-read timeout:

memslicer chrome --max-region-size 104857600 --read-timeout 30

---

CLI Reference

Usage: memslicer [OPTIONS] TARGET

  Dump process memory to MSL format.

  TARGET is a PID (integer) or process name (string).

  Supports 4 acquisition modes:
    Analysis unencrypted (default), Analysis encrypted (-E),
    Investigation encrypted (-I, default), Investigation unencrypted (-I --no-encrypt).

Options:
  -b, --backend [frida|gdb|lldb]  Debugger backend. [default: frida]
  -o, --output PATH               Output .msl file path.
  -c, --compress [none|zstd|lz4]  Compression algorithm. [default: none]
  -U, --usb                       Connect to a USB device (Frida only).
  -R, --remote HOST:PORT          Connect to a remote Frida server (Frida only).
  --os [windows|linux|macos|android|ios]
                                  Override automatic OS detection.
  --filter-prot TEXT              Filter regions by protection (e.g. 'rw-', 'r--').
  --filter-addr TEXT              Filter regions by address range (e.g. '0x1000-0x2000').
  -v, --verbose                   Enable verbose/debug output.
  --read-timeout FLOAT            Per-read timeout in seconds. [default: 10]
  --include-unreadable            Include memory regions with no read permission.
  --max-region-size INT           Skip regions larger than this size (0 = no limit).
  -I, --investigation             Investigation mode: capture system-wide context.
  -E, --encrypt                   Enable AEAD encryption (AES-256-GCM + Argon2id).
  --no-encrypt                    Disable encryption (overrides -I default).
  --passphrase TEXT               Encryption passphrase (prompted if not provided).
  --help                          Show this message and exit.

---

Output Format

MemSlicer writes memory snapshots to the MSL (Memory Slice) binary format. Each file contains:

• A file header with format version, target metadata, and capture timestamp
• Process identity block (ppid, session ID, start time, executable path, command line)
• Module list with base addresses, sizes, and paths
• Per-region records with base address, size, protection flags, and page-level data
• BLAKE3 integrity chain across all blocks
• Optional compressed data blocks (zstd or lz4)
• Optional AEAD encryption (AES-256-GCM + Argon2id)

When investigation mode (-I) is enabled, the MSL file additionally contains:

• System context: boot time, hostname, domain, OS detail string
• System-wide process table (all running processes)
• Network connection table (TCP/UDP, IPv4/IPv6)
• File handle table (open file descriptors for the target process)

A companion .log file is written alongside every .msl file and contains the full debug output of the capture session, regardless of whether -v was passed.

Example Output Summary

MemSlicer - Dumping chrome -> chrome_1773528836.msl
Backend: frida | Compression: none | Device: local
Progress: [##################################################] 100.00% Complete
  Regions : 2621/4199 (1578 filtered out)
            1578 no read permission (use --include-unreadable to include)
  Pages   : 12,500/12,800 captured (97.7%)
  Bytes   : 51,200,000 / 52,428,800 readable (97.7%)
  Modules : 142
  Duration: 12.34s
  File    : chrome_1773528836.msl (48,234,567 bytes)
  Log     : chrome_1773528836.msl.log
  Quality : GOOD (page-level: 97.7%)

---

Architecture

src/memslicer/
  cli.py                         CLI entry point (click)
  acquirer/
    engine.py                    Backend-agnostic acquisition engine
    bridge.py                    DebuggerBridge protocol definition
    frida_bridge.py              Frida backend
    gdb_bridge.py                GDB/MI3 backend
    lldb_bridge.py               LLDB Python API backend
    frida_acquirer.py            Backward-compatible Frida wrapper
    investigation.py             InvestigationCollector protocol
    platform_detect.py           OS and architecture detection
    region_filter.py             Region filtering logic
    collectors/
      __init__.py                Factory: create_collector()
      linux.py                   Linux collector (/proc)
      android.py                 Android collector (SELinux-aware + system properties)
      darwin.py                  macOS collector (sysctl, ps, lsof)
      ios.py                     iOS collector (sandbox-aware, SystemVersion.plist)
      windows.py                 Windows collector (wmic, tasklist, netstat)
      frida_remote.py            Remote collector via Frida JS RPC
      fallback.py                NullCollector for unsupported platforms
      constants.py               Shared constants (protocols, handle types)
  msl/
    writer.py                    MSL file writer
    encryption.py                AES-256-GCM + Argon2id encryption
    constants.py                 Format constants and enumerations
    integrity.py                 BLAKE3 integrity chain
    types.py                     MSL data types
  utils/
    protection.py                Memory protection parsing
    padding.py                   Alignment utilities
    timestamps.py                Timestamp helpers

---

Development

Setup

git clone git@github.com:MemorySlice/memslicer.git
cd memslicer
pip install -e ".[dev]"

Dev dependencies include pytest, pytest-cov, and ruff.

Running Tests

pytest

With coverage:

pytest --cov=memslicer --cov-report=term-missing

Linting

ruff check src/
ruff format src/

---

Dependencies

Package	Version	Purpose
frida-tools	>=12.0	Frida backend and agent
blake3	>=0.4	BLAKE3 integrity checksums
click	>=8.0	CLI framework
zstandard	>=0.20	Zstd compression
lz4	>=4.0	LZ4 compression
cryptography	>=42.0	AES-256-GCM encryption
argon2-cffi	>=23.1	Argon2id key derivation

---

License

Apache 2.0