mac-dump

A macOS memory-forensics toolkit focused on logical memory acquisition, with physical acquisition where the platform still allows it.

Logical vs. physical: logical acquisition reads memory through operating system APIs (e.g. a process's virtual address space); physical acquisition images raw RAM by physical address. On modern macOS — and especially on Apple Silicon — physical acquisition from software is largely locked down, so the primary, portable capability here is logical (per-process). Tools like LiME and MacPmem are physical acquisition tools; only the Intel kext path below is comparable to them.

mac-dump provides three acquisition paths:

Tool	Type	What it captures	Where it works
client/procdump	Logical	A process's virtual memory (task_for_pid/mach_vm_read)	Apple Silicon & Intel
client/macdump + kext/	Physical	Full physical RAM via a /dev/pmem kernel extension	Intel Macs (SIP relaxed)
tools/vmdump.py	Physical (guest)	Full physical RAM of a running VM via QEMU/UTM QMP	Any host running the target as a guest

Analysis helpers in tools/ inspect and carve the results, and outputs are compatible with Volatility 3.

Contents

• Legal & ethical use
• Scope, legality, and hard limits
• Requirements
• Build
• Intel: physical RAM (macdump + kext)
• Apple Silicon: per-process acquisition (procdump)
• Analysis tools (tools/)
• How it works
• Contributing
• Credits / prior art

---

⚠️ Legal & ethical use

This is defensive / forensic tooling for digital forensics and incident response (DFIR), malware analysis, memory-forensics research, teaching, and CTFs. Use it only on:

• machines you own, or
• systems you are explicitly authorized in writing to examine.

Acquiring the memory of a computer you do not own or have permission to analyze may be illegal. Memory images routinely contain passwords, encryption keys, and personal data — store and transmit them accordingly, and destroy them when your authorized engagement ends. You are responsible for how you use this software. The authors provide it "as is" with no warranty (see LICENSE).

⚠️ Scope, legality, and hard limits

• Intended use: digital forensics / incident response (DFIR), malware analysis, memory-forensics research, teaching, and CTFs — on machines you own or are authorized to examine. Memory can contain passwords, keys, and personal data; handle dumps accordingly.
• Intel only. Full physical RAM acquisition on Apple Silicon (M1/M2/M3…) has no supported software path due to kernel/hardware protections. Do not expect this to work there.
• Kexts are deprecated. Apple is phasing out kernel extensions. This project is educational/research tooling, not something you can casually ship signed.
• You must relax platform security to load a self-built kext (see below).

Requirements

• An Intel Mac (or Intel macOS VM) you control.
• Xcode + Command Line Tools (xcode-select --install).
• To load the kext, SIP configured to allow unsigned/self-signed kexts:
  1. Boot into Recovery (⌘R).
  2. Run csrutil enable --without kext or csrutil disable (research VMs).
  3. On T2 Macs, also lower Secure Boot to "Reduced Security" and allow kexts in Startup Security Utility.
  4. Reboot. Re-enable SIP when you're done.

Never disable SIP on a machine you rely on day-to-day. Use a dedicated VM.

Build

make            # builds client/macdump and kext/pmem.kext

or individually:

make -C client
make -C kext

Load the kext

sudo chown -R root:wheel kext/pmem.kext
sudo kmutil load -p kext/pmem.kext      # modern (Big Sur+)
# or, older systems:
sudo kextload kext/pmem.kext
ls -l /dev/pmem                          # should appear, mode 0400 root

Unload when finished:

sudo kmutil unload -b com.macdump.pmem   # or: sudo kextunload kext/pmem.kext

Acquire memory

# LiME format to a file (default) — feed this to Volatility
sudo ./client/macdump -o mem.lime

# Raw padded image (holes zero-filled)
sudo ./client/macdump -f raw -o mem.raw

# Over the network (acquire from another host): listen on TCP 4444
sudo ./client/macdump -o tcp:4444
# ...then on the analyst box:  nc <target-ip> 4444 > mem.lime

# Inspect the physical memory map without dumping
sudo ./client/macdump --map

Analyze with Volatility 3:

vol -f mem.lime windows.info   # or the appropriate mac plugins

Apple Silicon: per-process acquisition (procdump)

Apple Silicon exposes no software path to physical RAM (see the design note below), so on those machines procdump captures a single process's virtual address space instead — enough for most malware/live-response work.

make -C client procdump      # builds procdump (works on AS and Intel)

sudo ./client/procdump -l               # list processes
sudo ./client/procdump -p <PID> -o proc.dump
./client/procdump -p self -o self.dump  # dump ourselves (no privileges needed)

Output is a self-describing container (MPD1 header + region index + region bytes); see client/procdump_fmt.h.

Getting a task port for another process

task_for_pid() on Apple Silicon is gated. To dump a process other than your own you need one of:

• root + SIP disabled (research VM), or
• the private com.apple.system-task-ports entitlement (Apple-granted), or
• for a debuggable, same-user target: sign procdump with the com.apple.security.cs.debugger entitlement and the target with com.apple.security.get-task-allow. This works with SIP enabled and without root — it's the standard local-debugging path.

make -C client sign          # ad-hoc-signs procdump with cs.debugger
./tests/run_test.sh          # end-to-end proof: dumps a debuggable victim

Use ad-hoc signing (codesign -s -) for local testing. Signing with an Apple Development certificate but no provisioning profile can make macOS refuse (and on some systems delete) the binary at launch.

Analysis tools (tools/)

mpd_export.py — inspect and carve procdump MPD1 containers:

python3 tools/mpd_export.py info    proc.dump          # header summary
python3 tools/mpd_export.py regions proc.dump          # list captured regions
python3 tools/mpd_export.py extract proc.dump out/     # carve regions to raw files
python3 tools/mpd_export.py strings proc.dump --min 8  # ASCII strings w/ addresses

vmdump.py — full guest RAM acquisition from a QEMU/UTM VM (the practical "physical RAM" route on Apple Silicon: image the OS while it runs as a guest). Uses QEMU's QMP dump-guest-memory to write a Volatility-readable ELF core:

python3 tools/vmdump.py detect                          # find running QEMU VMs
python3 tools/vmdump.py status --qmp /tmp/vm.qmp
python3 tools/vmdump.py dump   --qmp /tmp/vm.qmp -o guest.elf
vol -f guest.elf ...                                    # analyze in Volatility 3

Start the VM with a QMP socket, e.g. -qmp unix:/tmp/vm.qmp,server,nowait (UTM: add that to the VM's extra QEMU arguments).

How it works

• The kext registers a BSD character device via cdevsw_add + devfs_make_node.
• read()/pread() on /dev/pmem map the requested physical page with IOMemoryDescriptor::withOptions(..., kIOMemoryTypePhysical64), then uiomove it to userland. Reads are done one page at a time.
• The physical memory map is parsed from the EFI memory map in the kernel boot_args. MMIO / unusable ranges are reported as holes and are never physically touched (reading device MMIO can hang the machine); the client zero-fills them so offsets stay aligned to physical addresses.
• macdump reads only the DRAM-backed ranges and wraps each in a LiME segment header, or produces a contiguous zero-padded raw image.

See DESIGN.md for the on-device protocol and format details.

Caveats / known-fragile bits

• boot_args EFI-map parsing may need per-version tuning. The struct layout is stable on Intel but not a public KPI. If the map comes back empty the kext falls back to permissive mode (allows reads anywhere) and the client uses hw.memsize — usable on a clean VM but riskier on bare metal with MMIO holes.
• Acquisition is not atomic; the system keeps running while you dump (same limitation as LiME).

Contributing

Contributions are welcome, especially:

• hardening the Intel kext's boot_args EFI-map parsing across macOS versions,
• a Volatility 3 layer/plugin for the procdump MPD1 container,
• UTM/QEMU quick-start recipes and testing for vmdump.py.

Please keep the project's defensive/forensic scope in mind (see Legal & ethical use). Open an issue to discuss larger changes first. By contributing you agree your work is licensed under the MIT License.

Credits / prior art

Design follows LiME (504ensicsLabs) and MacPmem/OSXPmem (Google Rekall). This is an independent, from-scratch implementation for learning purposes.

License

MIT — see LICENSE.