macnoise

<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>

---

[![CI](https://github.com/0xv1n/macnoise/actions/workflows/ci.yaml/badge.svg)](https://github.com/0xv1n/macnoise/actions/workflows/ci.yaml)
[![Release](https://img.shields.io/github/v/release/0xv1n/macnoise)](https://github.com/0xv1n/macnoise/releases/latest)

# MacNoise

MacNoise genera telemetria macOS reale: connessioni di rete, scritture su file, spawn di processi, mutazioni di plist, probe TCC e altro ancora. Puntalo verso una macchina che esegue il tuo stack EDR, SIEM o firewall e osserva cosa si attiva realmente - non ciò che la scheda tecnica del fornitore dichiara che si attiverà.

Per il contesto sulle motivazioni e sul design, consulta il [post del blog di rilascio](https://0xv1n.github.io/posts/macnoise/).

## Avvio Rapido

```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
```

## Categorie di Telemetria

| Categoria | Descrizione |
|----------|-------------|
| `network` | Connessioni TCP, HTTP, listener, reverse shell, DNS e TLS |
| `process` | Esecuzione esatta, invio di segnali, iniezione di dylib, bypass di Gatekeeper e osascript |
| `file` | Scoperta limitata, letture/copie letterali, creazione, modifica, archiviazione, occultamento e cifratura di esche |
| `tcc` | Probe dei permessi TCC con requisiti esatti di Full Disk Access, Contatti, Accessibilità o Registrazione Schermo |
| `credential` | Accesso nativo al credential-store |
| `volume` | Creazione di immagini disco e ciclo di vita dei volumi montati |
| `service` | Enumerazione di Launchd, persistenza LaunchAgent/Daemon, cron, profilo shell e Login Items |
| `plist` | Creazione e modifica di plist |
| `evasion` | Cancellazione dei log, timestomping, rimozione della cronologia e mascheramento |

Consulta il [catalogo dei moduli](https://github.com/0xv1n/macnoise/blob/main/docs/module-catalog.md) generato per ogni modulo, parametro, output, tipo di evento, privilegio e mappatura ATT&CK.

## Comandi

```
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
```

### Flag Globali

| Flag | Predefinito | Descrizione |
|------|---------|-------------|
| `--format` | `human` | Formato di output: `human` o `jsonl` |
| `--output` | (nessuno) | Scrivi l'output su file (oltre che su stdout) |
| `--verbose` | false | Output dettagliato inclusi gli errori di pulizia |
| `--dry-run` | false | Anteprima delle azioni senza esecuzione |
| `--no-cleanup` | false | Lascia gli artefatti del modulo sul posto (vedi sotto) |
| `--timeout` | `30` | Timeout per modulo in secondi |
| `--audit-log` | (nessuno) | Scrivi i record di audit OCSF 1.7.0 su un file JSONL |
| `--config` | (nessuno) | Carica i valori predefiniti da un file di configurazione YAML |
| `--run-id` | generato | Imposta l'identificatore di correlazione per questa esecuzione |

### Flusso di dati degli scenari

I file di scenario usano `version: 1`. Gli input e gli output dei moduli sono tipizzati, e uno
step successivo li referenzia con mappature esplicite anziché con l'interpolazione
di stringhe:

```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
```

Solo gli output dichiarati da un modulo possono essere referenziati. Gli scenari locali possono essere
riutilizzati con uno step `include`; gli include sono relativi, non possono risalire oltre
la directory radice dello scenario, sono controllati per cicli e sono limitati a otto livelli.
MacNoise valida il grafo completo prima dell'esecuzione, assegna all'esecuzione un
workspace privato e pulisce i moduli invocati in ordine inverso. Usa
`--input content=value` per fornire gli input e `--report report.json` per il
report di esecuzione versionato.

## Lasciare gli Artefatti sul Posto

Per impostazione predefinita ogni modulo si annulla al termine. Di solito è ciò che vuoi, ma significa che una detection vede solo l'evento di *installazione*. Per validare che il tuo stack rilevi la persistenza stessa - un LaunchAgent che risiede in `~/Library/LaunchAgents`, una voce cron, un profilo shell modificato - l'artefatto deve essere ancora lì quando viene eseguita la scansione:

```bash
./macnoise run svc_launch_agent --no-cleanup
```

Ogni modulo che salta la pulizia stampa una riga che lo nomina, e il log di audit registra `cleanup_result: skipped` anziché `ok`, così un'esecuzione che ha lasciato persistenza dietro di sé non viene mai confusa con una che ha ripulito. Usa `macnoise info <module>` per vedere cosa crea un dato modulo.

**Sei responsabile della loro rimozione.** Rieseguire lo stesso modulo senza il flag pulirà solo ciò che quell'esecuzione ha creato, non ciò che una precedente esecuzione con `--no-cleanup` ha lasciato dietro di sé.

## Audit Logging

MacNoise scrive due flussi separati. Gli eventi di telemetria - ciò che il tuo EDR/SIEM vede effettivamente - vanno su stdout o su `--output`. Un secondo flusso opzionale registra ciò che MacNoise stesso ha fatto: quali moduli sono stati eseguiti, gli esiti di prerequisiti/pulizia e le mappature MITRE, in JSONL [OCSF 1.7.0](https://schema.ocsf.io/).

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

Ogni evento di telemetria porta un unico `outcome` autorevole e un unico `subject` tipizzato (schema 2.0). L'outcome dice cosa è successo all'azione tentata da MacNoise, mentre il subject identifica il file, il processo, l'endpoint di rete, il servizio o la risorsa coinvolti:

| `outcome` | Significato | Indicatore umano |
|---|---|---|
| `executed` | L'azione è stata eseguita e ha fatto ciò che il modulo dichiara | `[+]` |
| `denied` | L'azione è stata eseguita e l'ambiente l'ha rifiutata | `[-]` |
| `indeterminate` | L'azione è stata eseguita, ma non si può concludere nulla | `[?]` |
| `error` | MacNoise stesso non è riuscito a portare a termine l'azione | `[!]` |

Una probe TCC negata o un beacon verso un C2 morto è la telemetria che questo strumento esiste per generare, quindi è distinta da `error`, che significa che MacNoise stesso ha fallito. Il log di audit registra lo stesso valore in `unmapped.outcome`. I parametri dichiarati sensibili vengono sostituiti con `[REDACTED]` nei record di audit gestiti e nell'identità della riga di comando.

Il log di audit si apre in modalità append, quindi i record di più esecuzioni si accumulano in un unico file per l'analisi in batch. Se stai aggiungendo un modulo e vuoi sapere come un nuovo tipo di evento viene classificato in OCSF, consulta [CONTRIBUTING.md](https://github.com/0xv1n/macnoise/blob/main/CONTRIBUTING.md#primitive-modules).

## Riferimento dei Moduli

Il [catalogo dei moduli](https://github.com/0xv1n/macnoise/blob/main/docs/module-catalog.md) generato è il riferimento autorevole per nomi, parametri, output, tipi di evento, privilegi e mappature ATT&CK. Le note di categoria spiegano il comportamento della piattaforma e i confini operativi:

| Categoria | 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) |

## Scenari

Gli scenari concatenano i moduli in sequenze ordinate - un singolo file YAML che riproduce un pattern di intrusione multi-stadio contro le tue detection.

| File | Descrizione |
|------|-------------|
| `network_only.yaml` | Operazioni composte di TCP, listener, DNS, beacon HTTP ed esfiltrazione HTTP |
| `edr_validation.yaml` | Copertura completa delle detection EDR |
| `full_sweep.yaml` | Tutte le categorie |
| `lazarus_group.yaml` | Lazarus Group: iniezione di dylib, scoperta dei servizi, reverse shell, persistenza LaunchAgent |
| `amos_atomic_stealer.yaml` | AMOS / Atomic Stealer: infostealer MaaS, bypass di Gatekeeper, dump del keychain, esfiltrazione ZIP, persistenza backdoor |
| `clickfix.yaml` | ClickFix: one-liner offuscato incollato nel Terminale, decodifica base64, fetch di secondo stadio, persistenza LaunchAgent |
| `ransomware.yaml` | Impatto ransomware: prepara esche in chiaro, cifrale, poi rilascia una nota di riscatto |
| `discovery.yaml` | Ricette composte di scoperta di sistema, account, rete e software di sicurezza basate su argv |
| `process_chain.yaml` | Catena shell a tre processi costruita da un vettore di argomenti esplicito |
| `file_flow.yaml` | Flusso connesso di creazione, modifica, scoperta limitata, lettura, copia e archiviazione |
| `mounted_execution.yaml` | Crea ed esegue un payload da un punto di mount di un'immagine disco osservato |

I due scenari APT seguono sequenze di intrusione reali documentate, tecnica per tecnica - ogni file YAML cita l'effettiva threat intel da cui è costruito e annota ogni step con la tecnica MITRE che esercita, quindi inizia da lì per la ripartizione completa anziché da un racconto qui.

**Prima dry-run:**
```bash
./macnoise scenario configs/scenarios/<scenario>.yaml --dry-run
```

**Correla con il tuo SIEM/EDR:** ogni commento di step nomina la tecnica che dovrebbe attivare. Nessun alert corrispondente dopo un'esecuzione reale è una lacuna nella tua copertura.

**Scrivere i tuoi:**
```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"
```

I parametri vengono verificati rispetto al tipo dichiarato di ciascun modulo: stringa, intero, booleano,
path o lista, prima dell'anteprima o dell'esecuzione. Nomi sconosciuti e valori non validi
vengono rifiutati. `on_error` è predefinito a `stop`. Impostalo a `continue` solo quando una
sweep di copertura dovrebbe tentare le invocazioni dei moduli successivi dopo un fallimento.

Parti dal [template di scenario](https://github.com/0xv1n/macnoise/blob/main/docs/templates/scenario.yaml) per input tipizzati, output e flusso di dati connesso.

## Compatibilità con la Versione 1

La versione 1.0 definisce i comandi e i flag CLI supportati, i nomi e i contratti dei moduli, lo schema di scenario 1, lo schema di telemetria 2.0 e lo schema del report di scenario 1.0. Modifiche future incompatibili a queste interfacce richiedono un nuovo rilascio major.

Gli utenti esistenti dovrebbero leggere [Migrating from v0.6.0 to v1.0.0](https://github.com/0xv1n/macnoise/blob/main/docs/migration-v1.md). Mappa ogni modulo rimosso e descrive le modifiche allo scenario, al JSONL e all'API Go.

## Contribuire

Consulta [CONTRIBUTING.md](https://github.com/0xv1n/macnoise/blob/main/CONTRIBUTING.md) per i percorsi di primitive, scenario e modifiche al core.

I rilasci sono automatizzati - [release-please](https://github.com/googleapis/release-please) crea una nuova versione direttamente dal titolo della tua PR [Conventional Commit](https://www.conventionalcommits.org/), quindi `feat: add net_tls module` o `fix: correct beacon jitter` è sia il titolo della tua PR che la voce del changelog.

## Disclaimer

MacNoise è destinato a test di sicurezza **autorizzati**, validazione EDR e detection engineering su sistemi che possiedi o per cui hai esplicito permesso scritto di testare. Gli autori non si assumono alcuna responsabilità per uso improprio.

## Politica sul Codice AI

I contributi di codice AI vanno bene, ma tieni presente che la revisione del codice sarà attualmente un processo guidato da esseri umani, il che significa che c'è un limite alla quantità di codice che possiamo revisionare. Limita le PR a una correzione specifica o a un nuovo modulo di telemetria. Le PR con modifiche estese saranno probabilmente chiuse.