---

MacNoise

MacNoise generates real macOS telemetry: network connections, file writes, process spawns, plist mutations, TCC probes, and more. Point it at a machine running your EDR, SIEM, or firewall stack and see what actually fires - not what the vendor datasheet claims will fire.

For background on the motivation and design, see the release blog post.

Quick Start

# Build (add build-amd64 / build-arm64 to cross-compile for Darwin, or release for both)
make build

# List available modules
./macnoise list

# Run a single module
./macnoise run net_connect --param target=127.0.0.1 --param port=8080

# Preview without executing
./macnoise run svc_launch_agent --dry-run

# Run all network modules
./macnoise run --category network

# Run a scenario
./macnoise scenario configs/scenarios/edr_validation.yaml

# Emit structured JSONL output
./macnoise scenario configs/scenarios/file_flow.yaml --format jsonl --output /tmp/events.jsonl

Telemetry Categories

Category	Description
network	TCP connections, HTTP, listeners, reverse shells, DNS, and TLS
process	Exact execution, signal delivery, dylib injection, Gatekeeper bypass, and osascript
file	Bounded discovery, literal reads/copies, creation, modification, archiving, hiding, and decoy encryption
tcc	TCC permission probes with exact Full Disk Access, Contacts, Accessibility, or Screen Recording requirements
credential	Native credential-store access
volume	Disk-image creation and mounted-volume lifecycle
service	Launchd enumeration, LaunchAgent/Daemon persistence, cron, shell profile, and Login Items
plist	Plist creation and modification
evasion	Log clearing, timestomping, history removal, and masquerading

See the generated module catalog for every module, parameter, output, event type, privilege, and ATT&CK mapping.

Commands

macnoise run <module> [--param key=val ...]   Run a specific module
macnoise run --category <cat>                 Run all modules in a category
macnoise run --all                            Run all modules
macnoise list [--category <cat>]              List modules
macnoise info <module>                        Show module details, params, MITRE
macnoise scenario <file.yaml> [--input key=val] [--report report.json]
                                                Run a YAML scenario
macnoise categories                           List categories with counts
macnoise version                              Print version

Global Flags

Flag	Default	Description
--format	human	Output format: human or jsonl
--output	(none)	Write output to file (in addition to stdout)
--verbose	false	Verbose output including cleanup errors
--dry-run	false	Preview actions without executing
--no-cleanup	false	Leave module artifacts in place (see below)
--timeout	30	Per-module timeout in seconds
--audit-log	(none)	Write OCSF 1.7.0 audit records to a JSONL file
--config	(none)	Load defaults from a YAML config file
--run-id	generated	Set the correlation identifier for this run

Scenario dataflow

Scenario files use version: 1. Inputs and module outputs are typed, and a later step references them with explicit mappings rather than string interpolation:

version: 1
name: Archive one generated artifact
on_error: stop
inputs:
  content:
    type: string
    required: true
steps:
  # Custom modules declare these outputs through OutputSpecs.
  - id: create
    module: custom_create
    params:
      content:
        input: content
  - id: archive
    module: custom_archive
    params:
      source:
        output: create.path
outputs:
  archive:
    output: archive.path

Only outputs declared by a module can be referenced. Local scenarios can be reused with an include step; includes are relative, cannot traverse above the root scenario directory, are cycle-checked, and are limited to eight levels. MacNoise validates the complete graph before execution, gives the run one private workspace, and cleans invoked modules in reverse order. Use --input content=value to supply inputs and --report report.json for the versioned execution report.

Leaving Artifacts In Place

By default every module reverses itself when it finishes. That is usually what you want, but it means a detection only ever sees the install event. To validate that your stack detects the persistence itself - a LaunchAgent sitting in ~/Library/LaunchAgents, a cron entry, a modified shell profile - the artifact has to still be there when the scan runs:

./macnoise run svc_launch_agent --no-cleanup

Each module that skips cleanup prints a line naming itself, and the audit log records cleanup_result: skipped rather than ok, so a run that left persistence behind is never mistaken for one that tidied up. Use macnoise info <module> to see what a given module creates.

You are responsible for removing these yourself. Re-running the same module without the flag will clean up only what that run created, not what a previous --no-cleanup run left behind.

Audit Logging

MacNoise writes two separate streams. Telemetry events - what your EDR/SIEM actually sees - go to stdout or --output. A second, optional stream records what MacNoise itself did: which modules ran, prereq/cleanup outcomes, and MITRE mappings, in OCSF 1.7.0 JSONL.

./macnoise scenario configs/scenarios/amos_atomic_stealer.yaml --audit-log /tmp/audit.jsonl

Every telemetry event carries one authoritative outcome and one typed subject (schema 2.0). The outcome says what happened to the action MacNoise attempted, while the subject identifies the file, process, network endpoint, service, or resource involved:

outcome	Meaning	Human marker
executed	The action ran and did what the module claims	[+]
denied	The action ran and the environment refused it	[-]
indeterminate	The action ran, but nothing can be concluded	[?]
error	MacNoise itself failed to carry the action out	[!]

A denied TCC probe or a beacon to a dead C2 is the telemetry this tool exists to generate, so it is distinct from error, which means MacNoise itself failed. The audit log records the same value at unmapped.outcome. Parameters declared sensitive are replaced with [REDACTED] in managed audit records and command-line identity.

The audit log opens in append mode, so records from multiple runs pile up in one file for batch analysis. If you're adding a module and want to know how a new event type gets classified into OCSF, see CONTRIBUTING.md.

Module Reference

The generated module catalog is the authoritative reference for names, parameters, outputs, event types, privileges, and ATT&CK mappings. Category notes explain platform behavior and operational boundaries: