Quick start

1. Confirm the binary loads its plugins

macfor list plugins

# Filter by category
macfor list plugins --category browser

# Machine-readable
macfor list plugins --json

You should see shell.history and browser.safari in the community build. The Pro binary lists every additional plugin in the same output.

2. Dry-run before you collect

A dry run resolves every artifact path on the source, reports which ones exist, and stops short of writing the evidence container. Use it to validate scope and surface missing permissions early.

macfor collect --dry-run

# Limit to one plugin
macfor collect --plugin browser.safari --dry-run

# Limit to a category (browser, communication, system, …)
macfor collect --category browser --dry-run

3. Run a real collection

# Everything the binary supports
sudo macfor collect --output ./evidence-$(date +%Y%m%d-%H%M%S).zip

# Just browser artifacts
sudo macfor collect --category browser --output ./browser-evidence.zip

# Just one plugin
sudo macfor collect --plugin shell.history --output ./shell.zip

sudo is only required when collecting from accounts other than the current user, or when reading paths protected by TCC.

4. Inspect the evidence container

The output is a deterministic ZIP. Top-level files give you the forensic context you need before unpacking artifacts:

unzip -l evidence-20260503-1130.zip | head -20

# Manifest with collection metadata
unzip -p evidence-20260503-1130.zip manifest.json | jq .source

# Per-file SHA-256 hashes
unzip -p evidence-20260503-1130.zip hashes.json | jq .

# Chain-of-custody log
unzip -p evidence-20260503-1130.zip chain-of-custody.json | jq .

The container layout, including parsed JSONL records and per-plugin logs, is documented under Output format.

5. Collect from a disk image

macfor abstracts the source — point it at a mounted image and the same plugins run unchanged.

# Attach a disk image read-only first
hdiutil attach -readonly -nomount evidence.dmg
# (use diskutil to mount the volume read-only at /Volumes/Evidence)

macfor collect \
  --source image:/Volumes/Evidence \
  --output ./evidence-image.zip

You're done

The container is now safe to hand off to an analyst, attach to a ticket, or import into macfor-analyze. Next, browse the plugin reference to learn what each collector pulls and where it lives on disk.