macnoise

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 run --category file --format jsonl --output /tmp/events.jsonl

Telemetry Categories

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>                 Run a YAML scenario
macnoise categories                           List categories with counts
macnoise version                              Print version

Global Flags

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 an outcome alongside success (schema 1.1). success says whether MacNoise worked; outcome says what happened to the action it attempted:

A denied TCC probe or a beacon to a dead C2 is the telemetry this tool exists to generate, so those stay success: true and are told apart by outcome. Only error sets success: false. In the audit log the same value appears at unmapped.outcome, since OCSF status records a refused action and a broken tool identically.

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

Module documentation lives alongside each category:

Scenarios

Scenarios chain modules into ordered sequences - a single YAML file that replays a multi-stage intrusion pattern against your detections.

The two APT scenarios follow real documented intrusion sequences, technique by technique - each YAML file cites the actual threat intel it's built from and annotates every step with the MITRE technique it exercises, so start there for the full breakdown rather than a retelling here.

Dry-run first:

./macnoise scenario configs/scenarios/<scenario>.yaml --dry-run

Cross-reference with your SIEM/EDR: each step comment names the technique it should trigger. No matching alert after a real run is a gap in your coverage.

Writing your own:

name: My Custom Scenario
steps:
  - module: net_connect
    params:
      target: "192.168.1.1"
      port: "443"
  - category: file
    params:
      base_dir: "/tmp/test"

Contributing

See CONTRIBUTING.md for adding new modules, code style, and the full PR process.

Releases are automated - release-please cuts a new version straight from your Conventional Commit PR title, so feat: add net_tls module or fix: correct beacon jitter is both your PR title and your changelog entry.

Disclaimer

MacNoise is intended for authorized security testing, EDR validation, and detection engineering on systems you own or have explicit written permission to test. The authors assume no liability for misuse.

AI Code Policy

AI Code contributions are fine, but please keep in mind that code review is currently going to be a human-led process which means there is only so much code we can review. Please limit PRs to a specific fix, or new telemetry module. PRs with extensive changes are likely going to be closed.