MacNoise

MacNoise erzeugt echte macOS-Telemetrie: Netzwerkverbindungen, Dateischreibvorgänge, Prozessstarts, Plist-Mutationen, TCC-Probes und mehr. Richte es auf eine Maschine mit deinem EDR-, SIEM- oder Firewall-Stack und sieh, was tatsächlich ausgelöst wird – nicht, was das Datenblatt des Anbieters behauptet.

Hintergrund zu Motivation und Design findest du im Release-Blogbeitrag.

Schnellstart

# 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

Telemetriekategorien

Siehe den generierten Modulkatalog für jedes Modul, jeden Parameter, jede Ausgabe, jeden Ereignistyp, jede Berechtigung und jedes ATT&CK-Mapping.

Befehle

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

Globale Flags

Szenario-Datenfluss

Szenariodateien verwenden version: 1. Eingaben und Modulausgaben sind typisiert, und ein späterer Schritt referenziert sie mit expliziten Mappings statt 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

Nur von einem Modul deklarierte Ausgaben können referenziert werden. Lokale Szenarien können mit einem include-Schritt wiederverwendet werden; Includes sind relativ, können nicht über das Stammverzeichnis des Szenarios hinausgehen, werden auf Zyklen geprüft und sind auf acht Ebenen begrenzt. MacNoise validiert den vollständigen Graphen vor der Ausführung, gibt dem Lauf einen privaten Workspace und bereinigt aufgerufene Module in umgekehrter Reihenfolge. Verwende --input content=value, um Eingaben bereitzustellen, und --report report.json für den versionierten Ausführungsbericht.

Artefakte an Ort und Stelle belassen

Standardmäßig macht jedes Modul seine Änderungen rückgängig, wenn es fertig ist. Das ist normalerweise gewünscht, bedeutet aber, dass eine Erkennung nur das Installations-Ereignis sieht. Um zu validieren, dass dein Stack die Persistenz selbst erkennt – einen LaunchAgent in ~/Library/LaunchAgents, einen Cron-Eintrag, ein geändertes Shell-Profil –, muss das Artefakt noch vorhanden sein, wenn der Scan läuft:

./macnoise run svc_launch_agent --no-cleanup

Jedes Modul, das das Cleanup überspringt, gibt eine Zeile mit seinem eigenen Namen aus, und das Audit-Log zeichnet cleanup_result: skipped statt ok auf, sodass ein Lauf, der Persistenz hinterlassen hat, niemals mit einem verwechselt wird, der aufgeräumt hat. Verwende macnoise info <module>, um zu sehen, was ein bestimmtes Modul erstellt.

Du bist dafür verantwortlich, diese selbst zu entfernen. Ein erneutes Ausführen desselben Moduls ohne das Flag bereinigt nur das, was dieser Lauf erstellt hat, nicht das, was ein vorheriger --no-cleanup-Lauf hinterlassen hat.

Audit-Logging

MacNoise schreibt zwei separate Streams. Telemetrieereignisse – was dein EDR/SIEM tatsächlich sieht – gehen nach stdout oder --output. Ein zweiter, optionaler Stream zeichnet auf, was MacNoise selbst getan hat: welche Module liefen, Ergebnisse von Voraussetzungen/Cleanup und MITRE-Mappings, in OCSF 1.7.0 JSONL.

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

Jedes Telemetrieereignis trägt ein maßgebliches outcome und ein typisiertes subject (Schema 2.0). Das Outcome sagt, was mit der von MacNoise versuchten Aktion geschehen ist, während das Subject die beteiligte Datei, den Prozess, den Netzwerkendpunkt, den Dienst oder die Ressource identifiziert:

Eine verweigerte TCC-Probe oder ein Beacon zu einem toten C2 ist die Telemetrie, für deren Erzeugung dieses Tool existiert, daher unterscheidet sie sich von error, was bedeutet, dass MacNoise selbst fehlgeschlagen ist. Das Audit-Log zeichnet denselben Wert unter unmapped.outcome auf. Als sensibel deklarierte Parameter werden in verwalteten Audit-Datensätzen und in der Kommandozeilen-Identität durch [REDACTED] ersetzt.

Das Audit-Log wird im Append-Modus geöffnet, sodass sich Datensätze aus mehreren Läufen für die Batch-Analyse in einer Datei ansammeln. Wenn du ein Modul hinzufügst und wissen möchtest, wie ein neuer Ereignistyp in OCSF klassifiziert wird, siehe CONTRIBUTING.md.

Modulreferenz

Der generierte Modulkatalog ist die maßgebliche Referenz für Namen, Parameter, Ausgaben, Ereignistypen, Berechtigungen und ATT&CK-Mappings. Kategoriehinweise erklären Plattformverhalten und operative Grenzen:

Szenarien

Szenarien verketten Module zu geordneten Sequenzen – eine einzelne YAML-Datei, die ein mehrstufiges Intrusionsmuster gegen deine Erkennungen abspielt.

Die beiden APT-Szenarien folgen echten dokumentierten Intrusionssequenzen, Technik für Technik – jede YAML-Datei zitiert die tatsächlichen Threat-Intel-Quellen, auf denen sie basiert, und annotiert jeden Schritt mit der MITRE-Technik, die er ausübt. Beginne dort für die vollständige Aufschlüsselung statt mit einer Nacherzählung hier.

Zuerst Dry-Run:

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

Mit deinem SIEM/EDR abgleichen: Jeder Schrittkommentar nennt die Technik, die er auslösen soll. Kein passender Alarm nach einem echten Lauf ist eine Lücke in deiner Abdeckung.

Eigene Szenarien schreiben:

version: 1
name: My Custom Scenario
on_error: stop
steps:
  - module: net_connect
    params:
      target: "192.168.1.1"
      port: 443
  - module: file_create
    params:
      base_dir: "/tmp/test"

Parameter werden vor der Vorschau oder Ausführung gegen den deklarierten Typ jedes Moduls (String, Integer, Boolean, Pfad oder Liste) geprüft. Unbekannte Namen und ungültige Werte werden abgelehnt. on_error ist standardmäßig stop. Setze es nur dann auf continue, wenn ein Coverage-Sweep nach einem Fehler spätere Modulaufrufe versuchen soll.

Beginne mit der Szenario-Vorlage für typisierte Eingaben, Ausgaben und verbundenen Datenfluss.

Version-1-Kompatibilität

Version 1.0 definiert die unterstützten CLI-Befehle und -Flags, Modulnamen und -verträge, Szenario-Schema 1, Telemetrie-Schema 2.0 und Szenario-Report-Schema 1.0. Zukünftige inkompatible Änderungen an diesen Schnittstellen erfordern ein neues Major-Release.

Bestehende Nutzer sollten Migrating from v0.6.0 to v1.0.0 lesen. Es ordnet jedes entfernte Modul zu und beschreibt die Änderungen an Szenario, JSONL und Go-API.

Mitwirken

Siehe CONTRIBUTING.md für die Pfade für Primitives, Szenarien und Kernänderungen.

Releases sind automatisiert – release-please erstellt eine neue Version direkt aus deinem Conventional Commit-PR-Titel, sodass feat: add net_tls module oder fix: correct beacon jitter sowohl dein PR-Titel als auch dein Changelog-Eintrag ist.

Haftungsausschluss

MacNoise ist für autorisiertes Sicherheitstesting, EDR-Validierung und Detection Engineering auf Systemen gedacht, die dir gehören oder für die du eine ausdrückliche schriftliche Testgenehmigung hast. Die Autoren übernehmen keine Haftung für Missbrauch.

KI-Code-Richtlinie

KI-Code-Beiträge sind in Ordnung, aber bitte bedenke, dass Code-Review derzeit ein von Menschen geführter Prozess ist, was bedeutet, dass wir nur begrenzt viel Code prüfen können. Bitte beschränke PRs auf eine bestimmte Fehlerbehebung oder ein neues Telemetriemodul. PRs mit umfangreichen Änderungen werden wahrscheinlich geschlossen.