Quick start — macfor docs

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, browser.safari, and system.users in the community build. The Pro binary lists every additional plugin in the same output.

2. Dry-run before you collect

A dry run detects which plugins apply to the source, reports each one as applicable or not (with the reason), and stops short of writing the evidence container. Use it to check scope before you collect.

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

# Local user accounts (metadata only; needs root on a live system)
sudo macfor collect --plugin system.users --output ./users.zip

sudois only required to read other users' home directories. It doesn't get past TCC: protected paths need Full Disk Access (see Installation). If --output doesn't end in .zip, macfor adds it.

User accounts. The system.users plugin reads the local account plists, which only root can read on a live system. Without root it is reported as not applicable (check with --dry-run). It records account metadata only. It never collects password hashes, Kerberos keys, SRP keys, or the password hint. Every collection also records the enumerated accounts in manifest.json under source.users, with or without this plugin.

For agents

Collect only with the user's explicit go-ahead, and only the scope they asked for. Prefer --plugin or --category over a full sweep unless they asked for everything.
Choose an --outputpath that doesn't exist yet. macfor overwrites an existing file at that path.
Don't add sudo on your own. Run without it unless the user asked for multi-user collection; if they did, ask them to run the command, since sudo prompts for a password.
Exit code 2 means the container was written but some artifacts failed; report the errors from manifest.json instead of re-running. 1 means the collection failed.
Don't treat an exit code alone as proof a container exists. 0 is also returned when no plugins matched or applied, without writing anything. Confirm the file exists and that unzip -l lists manifest.json before you report success. If a collection was interrupted, treat any file at the output path as unusable.

4. Inspect the evidence container

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

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

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

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

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

The container layout, including parsed JSONL records and per-plugin logs, is documented under Output format, and specified precisely in the container format spec.

5. Collect from a disk image

macfor abstracts the source, so the same plugins run unchanged against a disk image. From v0.2.0, pass the image file (DMG, raw, or E01) with --image: macfor attaches it read-only, collects, and detaches it when it finishes.

macfor collect --image ./evidence.dmg --dry-run
macfor collect --image ./evidence.dmg --output ./evidence-image.zip

To collect from a volume you mounted yourself, or from a copied directory tree, point --from at its root instead.

# Attach the disk image read-only
hdiutil attach -readonly evidence.dmg
# Note the mount point it prints, e.g. /Volumes/Evidence

macfor collect --from /Volumes/Evidence --dry-run
macfor collect --from /Volumes/Evidence --output ./evidence-image.zip

# Detach when done
hdiutil detach /Volumes/Evidence

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.