0xv1n/macnoiseErweiterbarer Generator für MacOS-Systemtelemetrie.
<div style="text-align: center;">
<img src="https://assets.kitploit.com/production/public/readmes/12216/015e563e6db740a8025fff16e60052d282eafc29855ed07fd23f58cd1a3fc0e5.png" alt="Description of image" style="max-width: 100%; height: auto; display: block; margin: 0 auto;">
</div>
---
[](https://github.com/0xv1n/macnoise/actions/workflows/ci.yaml)
[](https://github.com/0xv1n/macnoise/releases/latest)
# 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](https://0xv1n.github.io/posts/macnoise/).
## Schnellstart
```bash
# 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
| Kategorie | Beschreibung |
|----------|-------------|
| `network` | TCP-Verbindungen, HTTP, Listener, Reverse Shells, DNS und TLS |
| `process` | Exakte Ausführung, Signalzustellung, Dylib-Injection, Gatekeeper-Bypass und osascript |
| `file` | Begrenzte Discovery, literale Lese-/Kopiervorgänge, Erstellung, Änderung, Archivierung, Verbergen und Decoy-Verschlüsselung |
| `tcc` | TCC-Berechtigungs-Probes mit exakten Anforderungen an Full Disk Access, Kontakte, Bedienungshilfen oder Bildschirmaufnahme |
| `credential` | Zugriff auf den nativen Credential-Store |
| `volume` | Erstellung von Disk-Images und Lebenszyklus gemounteter Volumes |
| `service` | Launchd-Enumeration, LaunchAgent/Daemon-Persistenz, Cron, Shell-Profil und Login Items |
| `plist` | Erstellung und Änderung von Plists |
| `evasion` | Log-Löschung, Timestomping, Entfernung der History und Maskerade |
Siehe den generierten [Modulkatalog](https://github.com/0xv1n/macnoise/blob/main/docs/module-catalog.md) 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
| Flag | Standard | Beschreibung |
|------|---------|-------------|
| `--format` | `human` | Ausgabeformat: `human` oder `jsonl` |
| `--output` | (keine) | Ausgabe in Datei schreiben (zusätzlich zu stdout) |
| `--verbose` | false | Ausführliche Ausgabe einschließlich Cleanup-Fehlern |
| `--dry-run` | false | Aktionen ohne Ausführung vorab anzeigen |
| `--no-cleanup` | false | Modulartefakte an Ort und Stelle belassen (siehe unten) |
| `--timeout` | `30` | Timeout pro Modul in Sekunden |
| `--audit-log` | (keine) | OCSF 1.7.0-Audit-Datensätze in eine JSONL-Datei schreiben |
| `--config` | (keine) | Standardwerte aus einer YAML-Konfigurationsdatei laden |
| `--run-id` | generiert | Korrelationsbezeichner für diesen Lauf festlegen |
### Szenario-Datenfluss
Szenariodateien verwenden `version: 1`. Eingaben und Modulausgaben sind typisiert, und ein späterer Schritt referenziert sie mit expliziten Mappings statt String-Interpolation:
```yaml
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:
```bash
./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](https://schema.ocsf.io/) JSONL.
```bash
./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:
| `outcome` | Bedeutung | Menschlicher Marker |
|---|---|---|
| `executed` | Die Aktion lief und tat, was das Modul behauptet | `[+]` |
| `denied` | Die Aktion lief und die Umgebung verweigerte sie | `[-]` |
| `indeterminate` | Die Aktion lief, aber es kann nichts geschlossen werden | `[?]` |
| `error` | MacNoise selbst konnte die Aktion nicht ausführen | `[!]` |
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](https://github.com/0xv1n/macnoise/blob/main/CONTRIBUTING.md#primitive-modules).
## Modulreferenz
Der generierte [Modulkatalog](https://github.com/0xv1n/macnoise/blob/main/docs/module-catalog.md) ist die maßgebliche Referenz für Namen, Parameter, Ausgaben, Ereignistypen, Berechtigungen und ATT&CK-Mappings. Kategoriehinweise erklären Plattformverhalten und operative Grenzen:
| Kategorie | README |
|----------|--------|
| `network` | [modules/network/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/network/README.md) |
| `process` | [modules/process/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/process/README.md) |
| `file` | [modules/file/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/file/README.md) |
| `tcc` | [modules/tcc/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/tcc/README.md) |
| `credential` | [modules/credential/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/credential/README.md) |
| `volume` | [modules/volume/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/volume/README.md) |
| `service` | [modules/service/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/service/README.md) |
| `plist` | [modules/plist/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/plist/README.md) |
| `evasion` | [modules/evasion/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/evasion/README.md) |
## Szenarien
Szenarien verketten Module zu geordneten Sequenzen – eine einzelne YAML-Datei, die ein mehrstufiges Intrusionsmuster gegen deine Erkennungen abspielt.
| Datei | Beschreibung |
|------|-------------|
| `network_only.yaml` | Zusammengesetzte TCP-, Listener-, DNS-, HTTP-Beacon- und HTTP-Exfiltrationsoperationen |
| `edr_validation.yaml` | Umfassende EDR-Erkennungsabdeckung |
| `full_sweep.yaml` | Alle Kategorien |
| `lazarus_group.yaml` | Lazarus Group: Dylib-Injection, Diensterkennung, Reverse Shell, LaunchAgent-Persistenz |
| `amos_atomic_stealer.yaml` | AMOS / Atomic Stealer: MaaS-Infostealer, Gatekeeper-Bypass, Keychain-Dump, ZIP-Exfiltration, Backdoor-Persistenz |
| `clickfix.yaml` | ClickFix: obfuskierter Einzeiler, in Terminal eingefügt, Base64-Dekodierung, Fetch der zweiten Stufe, LaunchAgent-Persistenz |
| `ransomware.yaml` | Ransomware-Auswirkung: Klartext-Decoys platzieren, verschlüsseln, dann eine Lösegeldforderung hinterlassen |
| `discovery.yaml` | Zusammengesetzte argv-basierte Rezepte zur System-, Konto-, Netzwerk- und Sicherheitssoftware-Erkennung |
| `process_chain.yaml` | Dreiprocess-Shell-Kette, aufgebaut aus einem expliziten Argumentvektor |
| `file_flow.yaml` | Verbundener Ablauf aus Erstellen, Ändern, begrenzter Discovery, Lesen, Kopieren und Archivieren |
| `mounted_execution.yaml` | Erstellen und Ausführen einer Payload von einem beobachteten Disk-Image-Mountpunkt |
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:**
```bash
./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:**
```yaml
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](https://github.com/0xv1n/macnoise/blob/main/docs/templates/scenario.yaml) 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](https://github.com/0xv1n/macnoise/blob/main/docs/migration-v1.md) lesen. Es ordnet jedes entfernte Modul zu und beschreibt die Änderungen an Szenario, JSONL und Go-API.
## Mitwirken
Siehe [CONTRIBUTING.md](https://github.com/0xv1n/macnoise/blob/main/CONTRIBUTING.md) für die Pfade für Primitives, Szenarien und Kernänderungen.
Releases sind automatisiert – [release-please](https://github.com/googleapis/release-please) erstellt eine neue Version direkt aus deinem [Conventional Commit](https://www.conventionalcommits.org/)-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.