macnoise

<div style="text-align: center;">
  <img src="https://assets.kitploit.com/production/public/readmes/12216/015e563e6db740a8025fff16e60052d282eafc29855ed07fd23f58cd1a3fc0e5.png" alt="Descrição da imagem" 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

O MacNoise gera telemetria real do macOS: conexões de rede, gravações de arquivos, criação de processos, mutações de plist, sondagens de TCC e muito mais. Aponte-o para uma máquina executando sua pilha de EDR, SIEM ou firewall e veja o que realmente dispara - não o que a ficha técnica do fornecedor afirma que vai disparar.

Para contexto sobre a motivação e o design, consulte o [post do blog de lançamento](https://0xv1n.github.io/posts/macnoise/).

## Início Rápido

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

## Categorias de Telemetria

| Categoria | Descrição |
|----------|-------------|
| `network` | Conexões TCP, HTTP, listeners, reverse shells, DNS e TLS |
| `process` | Execução exata, entrega de sinais, injeção de dylib, bypass do Gatekeeper e osascript |
| `file` | Descoberta limitada, leituras/cópias literais, criação, modificação, arquivamento, ocultação e criptografia de iscas |
| `tcc` | Sondagens de permissão TCC com requisitos exatos de Acesso Total ao Disco, Contatos, Acessibilidade ou Gravação de Tela |
| `credential` | Acesso nativo ao armazenamento de credenciais |
| `volume` | Criação de imagem de disco e ciclo de vida de volume montado |
| `service` | Enumeração do Launchd, persistência via LaunchAgent/Daemon, cron, perfil de shell e Itens de Login |
| `plist` | Criação e modificação de plist |
| `evasion` | Limpeza de logs, timestomping, remoção de histórico e mascaramento |

Consulte o [catálogo de módulos](https://github.com/0xv1n/macnoise/blob/main/docs/module-catalog.md) gerado para cada módulo, parâmetro, saída, tipo de evento, privilégio e mapeamento ATT&CK.

## Comandos

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

### Flags Globais

| Flag | Padrão | Descrição |
|------|---------|-------------|
| `--format` | `human` | Formato de saída: `human` ou `jsonl` |
| `--output` | (nenhum) | Grava a saída em arquivo (além do stdout) |
| `--verbose` | false | Saída detalhada, incluindo erros de limpeza |
| `--dry-run` | false | Pré-visualiza as ações sem executá-las |
| `--no-cleanup` | false | Deixa os artefatos do módulo no lugar (veja abaixo) |
| `--timeout` | `30` | Timeout por módulo em segundos |
| `--audit-log` | (nenhum) | Grava registros de auditoria OCSF 1.7.0 em um arquivo JSONL |
| `--config` | (nenhum) | Carrega padrões de um arquivo de configuração YAML |
| `--run-id` | gerado | Define o identificador de correlação para esta execução |

### Fluxo de dados de cenários

Arquivos de cenário usam `version: 1`. Entradas e saídas de módulos são tipadas, e um
passo posterior as referencia com mapeamentos explícitos em vez de interpolação
de strings:

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

Apenas saídas declaradas por um módulo podem ser referenciadas. Cenários locais podem ser
reutilizados com um passo `include`; os includes são relativos, não podem atravessar acima
do diretório raiz do cenário, são verificados quanto a ciclos e são limitados a oito níveis.
O MacNoise valida o grafo completo antes da execução, concede à execução um
workspace privado e limpa os módulos invocados em ordem reversa. Use
`--input content=value` para fornecer entradas e `--report report.json` para o
relatório de execução versionado.

## Deixando Artefatos no Lugar

Por padrão, todo módulo se reverte quando termina. Isso geralmente é o que você quer, mas significa que uma detecção só vê o evento de *instalação*. Para validar que sua pilha detecta a persistência em si - um LaunchAgent em `~/Library/LaunchAgents`, uma entrada de cron, um perfil de shell modificado - o artefato precisa ainda estar lá quando a varredura for executada:

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

Cada módulo que pula a limpeza imprime uma linha nomeando a si mesmo, e o log de auditoria registra `cleanup_result: skipped` em vez de `ok`, para que uma execução que deixou persistência para trás nunca seja confundida com uma que fez a limpeza. Use `macnoise info <module>` para ver o que um determinado módulo cria.

**Você é responsável por removê-los por conta própria.** Reexecutar o mesmo módulo sem a flag limpará apenas o que aquela execução criou, não o que uma execução anterior com `--no-cleanup` deixou para trás.

## Registro de Auditoria

O MacNoise grava dois fluxos separados. Eventos de telemetria - o que seu EDR/SIEM realmente vê - vão para stdout ou `--output`. Um segundo fluxo opcional registra o que o próprio MacNoise fez: quais módulos foram executados, resultados de pré-requisitos/limpeza e mapeamentos MITRE, em JSONL [OCSF 1.7.0](https://schema.ocsf.io/).

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

Todo evento de telemetria carrega um `outcome` autoritativo e um `subject` tipado (schema 2.0). O outcome diz o que aconteceu com a ação que o MacNoise tentou, enquanto o subject identifica o arquivo, processo, endpoint de rede, serviço ou recurso envolvido:

| `outcome` | Significado | Marcador humano |
|---|---|---|
| `executed` | A ação foi executada e fez o que o módulo afirma | `[+]` |
| `denied` | A ação foi executada e o ambiente a recusou | `[-]` |
| `indeterminate` | A ação foi executada, mas nada pode ser concluído | `[?]` |
| `error` | O próprio MacNoise falhou em executar a ação | `[!]` |

Uma sondagem TCC negada ou um beacon para um C2 morto é a telemetria que esta ferramenta existe para gerar, então é distinta de `error`, que significa que o próprio MacNoise falhou. O log de auditoria registra o mesmo valor em `unmapped.outcome`. Parâmetros declarados como sensíveis são substituídos por `[REDACTED]` em registros de auditoria gerenciados e na identidade da linha de comando.

O log de auditoria abre em modo de anexação, então registros de múltiplas execuções se acumulam em um único arquivo para análise em lote. Se você está adicionando um módulo e quer saber como um novo tipo de evento é classificado no OCSF, consulte [CONTRIBUTING.md](https://github.com/0xv1n/macnoise/blob/main/CONTRIBUTING.md#primitive-modules).

## Referência de Módulos

O [catálogo de módulos](https://github.com/0xv1n/macnoise/blob/main/docs/module-catalog.md) gerado é a referência autoritativa para nomes, parâmetros, saídas, tipos de evento, privilégios e mapeamentos ATT&CK. As notas de categoria explicam o comportamento da plataforma e os limites operacionais:

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

## Cenários

Cenários encadeiam módulos em sequências ordenadas - um único arquivo YAML que reproduz um padrão de intrusão multiestágio contra suas detecções.

| Arquivo | Descrição |
|------|-------------|
| `network_only.yaml` | Operações compostas de TCP, listener, DNS, beacon HTTP e exfiltração HTTP |
| `edr_validation.yaml` | Cobertura abrangente de detecção de EDR |
| `full_sweep.yaml` | Todas as categorias |
| `lazarus_group.yaml` | Lazarus Group: injeção de dylib, descoberta de serviços, reverse shell, persistência via LaunchAgent |
| `amos_atomic_stealer.yaml` | AMOS / Atomic Stealer: infostealer MaaS, bypass do Gatekeeper, dump de keychain, exfiltração via ZIP, persistência de backdoor |
| `clickfix.yaml` | ClickFix: one-liner ofuscado colado no Terminal, decodificação base64, busca de segundo estágio, persistência via LaunchAgent |
| `ransomware.yaml` | Impacto de ransomware: preparar iscas em texto simples, criptografá-las e então deixar uma nota de resgate |
| `discovery.yaml` | Receitas compostas de descoberta de sistema, conta, rede e software de segurança baseadas em argv |
| `process_chain.yaml` | Cadeia de shell de três processos construída a partir de um vetor de argumentos explícito |
| `file_flow.yaml` | Fluxo conectado de criação, modificação, descoberta limitada, leitura, cópia e arquivamento |
| `mounted_execution.yaml` | Cria e executa um payload a partir de um ponto de montagem de imagem de disco observado |

Os dois cenários de APT seguem sequências reais de intrusão documentadas, técnica por técnica - cada arquivo YAML cita a threat intel real a partir da qual foi construído e anota cada passo com a técnica MITRE que ele exercita, então comece por lá para a análise completa em vez de uma recontagem aqui.

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

**Faça referência cruzada com seu SIEM/EDR:** cada comentário de passo nomeia a técnica que ele deve disparar. Nenhum alerta correspondente após uma execução real é uma lacuna na sua cobertura.

**Escrevendo o seu próprio:**
```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"
```

Os parâmetros são verificados em relação ao tipo declarado de cada módulo - string, integer, boolean,
path ou list - antes da pré-visualização ou execução. Nomes desconhecidos e valores inválidos
são rejeitados. `on_error` tem como padrão `stop`. Defina como `continue` apenas quando uma
varredura de cobertura deve tentar invocações posteriores de módulos após uma falha.

Comece pelo [template de cenário](https://github.com/0xv1n/macnoise/blob/main/docs/templates/scenario.yaml) para entradas tipadas, saídas e fluxo de dados conectado.

## Compatibilidade com a Versão 1

A Versão 1.0 define os comandos e flags de CLI suportados, nomes e contratos de módulos, schema de cenário 1, schema de telemetria 2.0 e schema de relatório de cenário 1.0. Mudanças futuras incompatíveis nesses interfaces exigem uma nova versão principal.

Usuários existentes devem ler [Migrando de v0.6.0 para v1.0.0](https://github.com/0xv1n/macnoise/blob/main/docs/migration-v1.md). Ele mapeia cada módulo removido e descreve as mudanças de cenário, JSONL e API Go.

## Contribuindo

Consulte [CONTRIBUTING.md](https://github.com/0xv1n/macnoise/blob/main/CONTRIBUTING.md) para os caminhos de primitivas, cenários e mudanças no núcleo.

As releases são automatizadas - o [release-please](https://github.com/googleapis/release-please) cria uma nova versão diretamente a partir do título do seu PR seguindo [Conventional Commit](https://www.conventionalcommits.org/), então `feat: add net_tls module` ou `fix: correct beacon jitter` é tanto o título do seu PR quanto a entrada do seu changelog.

## Aviso Legal

O MacNoise destina-se a testes de segurança **autorizados**, validação de EDR e engenharia de detecção em sistemas que você possui ou tem permissão escrita explícita para testar. Os autores não assumem nenhuma responsabilidade por uso indevido.

## Política de Código de IA

Contribuições de Código de IA são bem-vindas, mas tenha em mente que a revisão de código atualmente será um processo liderado por humanos, o que significa que há um limite para quanto código podemos revisar. Por favor, limite os PRs a uma correção específica ou a um novo módulo de telemetria. PRs com mudanças extensas provavelmente serão fechados.