0xv1n/macnoiseGenerador extensible de telemetría del sistema macOS.
<div style="text-align: center;">
<img src="https://assets.kitploit.com/production/public/readmes/12216/015e563e6db740a8025fff16e60052d282eafc29855ed07fd23f58cd1a3fc0e5.png" alt="Descripción de la imagen" 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 genera telemetría real de macOS: conexiones de red, escrituras de archivos, creación de procesos, mutaciones de plist, sondeos de TCC y más. Apúntalo a una máquina que ejecute tu stack de EDR, SIEM o firewall y observa qué se dispara realmente, no lo que la hoja de datos del proveedor afirma que se disparará.
Para conocer los antecedentes sobre la motivación y el diseño, consulta la [publicación del blog de lanzamiento](https://0xv1n.github.io/posts/macnoise/).
## Inicio 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
```
## Categorías de telemetría
| Categoría | Descripción |
|----------|-------------|
| `network` | Conexiones TCP, HTTP, listeners, reverse shells, DNS y TLS |
| `process` | Ejecución exacta, entrega de señales, inyección de dylib, bypass de Gatekeeper y osascript |
| `file` | Descubrimiento acotado, lecturas/copias literales, creación, modificación, archivado, ocultación y cifrado de señuelos |
| `tcc` | Sondeos de permisos TCC con requisitos exactos de Full Disk Access, Contacts, Accessibility o Screen Recording |
| `credential` | Acceso nativo al almacén de credenciales |
| `volume` | Creación de imágenes de disco y ciclo de vida de volúmenes montados |
| `service` | Enumeración de Launchd, persistencia de LaunchAgent/Daemon, cron, perfil de shell y Login Items |
| `plist` | Creación y modificación de plist |
| `evasion` | Limpieza de logs, timestomping, eliminación de historial y enmascaramiento |
Consulta el [catálogo de módulos](https://github.com/0xv1n/macnoise/blob/main/docs/module-catalog.md) generado para ver cada módulo, parámetro, salida, tipo de evento, privilegio y mapeo 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 globales
| Flag | Predeterminado | Descripción |
|------|---------|-------------|
| `--format` | `human` | Formato de salida: `human` o `jsonl` |
| `--output` | (ninguno) | Escribir la salida en un archivo (además de stdout) |
| `--verbose` | false | Salida detallada, incluidos errores de limpieza |
| `--dry-run` | false | Previsualizar acciones sin ejecutarlas |
| `--no-cleanup` | false | Dejar los artefactos del módulo en su lugar (ver más abajo) |
| `--timeout` | `30` | Tiempo de espera por módulo en segundos |
| `--audit-log` | (ninguno) | Escribir registros de auditoría OCSF 1.7.0 en un archivo JSONL |
| `--config` | (ninguno) | Cargar valores predeterminados desde un archivo de configuración YAML |
| `--run-id` | generado | Establecer el identificador de correlación para esta ejecución |
### Flujo de datos de escenarios
Los archivos de escenario usan `version: 1`. Las entradas y salidas de los módulos están tipadas, y un paso posterior las referencia con mapeos explícitos en lugar de interpolación de cadenas:
```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 se pueden referenciar las salidas declaradas por un módulo. Los escenarios locales se pueden reutilizar con un paso `include`; las inclusiones son relativas, no pueden atravesar por encima del directorio raíz del escenario, se comprueban ciclos y están limitadas a ocho niveles. MacNoise valida el grafo completo antes de la ejecución, asigna a la ejecución un espacio de trabajo privado y limpia los módulos invocados en orden inverso. Usa `--input content=value` para proporcionar entradas y `--report report.json` para el informe de ejecución versionado.
## Dejar artefactos en su lugar
De forma predeterminada, cada módulo se revierte a sí mismo cuando termina. Normalmente eso es lo que quieres, pero significa que una detección solo ve el evento de *instalación*. Para validar que tu stack detecta la persistencia en sí misma —un LaunchAgent que reside en `~/Library/LaunchAgents`, una entrada de cron, un perfil de shell modificado— el artefacto tiene que seguir ahí cuando se ejecute el escaneo:
```bash
./macnoise run svc_launch_agent --no-cleanup
```
Cada módulo que omite la limpieza imprime una línea nombrándose a sí mismo, y el registro de auditoría registra `cleanup_result: skipped` en lugar de `ok`, de modo que una ejecución que dejó persistencia atrás nunca se confunde con una que limpió. Usa `macnoise info <module>` para ver qué crea un módulo determinado.
**Eres responsable de eliminarlos tú mismo.** Volver a ejecutar el mismo módulo sin el flag limpiará solo lo que esa ejecución creó, no lo que dejó atrás una ejecución anterior con `--no-cleanup`.
## Registro de auditoría
MacNoise escribe dos flujos separados. Los eventos de telemetría —lo que tu EDR/SIEM ve realmente— van a stdout o a `--output`. Un segundo flujo opcional registra lo que hizo MacNoise en sí: qué módulos se ejecutaron, los resultados de prerequisitos/limpieza y los mapeos MITRE, en JSONL de [OCSF 1.7.0](https://schema.ocsf.io/).
```bash
./macnoise scenario configs/scenarios/amos_atomic_stealer.yaml --audit-log /tmp/audit.jsonl
```
Cada evento de telemetría lleva un `outcome` autoritativo y un `subject` tipado (esquema 2.0). El outcome indica qué le ocurrió a la acción que MacNoise intentó, mientras que el subject identifica el archivo, proceso, endpoint de red, servicio o recurso implicado:
| `outcome` | Significado | Marcador humano |
|---|---|---|
| `executed` | La acción se ejecutó e hizo lo que el módulo afirma | `[+]` |
| `denied` | La acción se ejecutó y el entorno la rechazó | `[-]` |
| `indeterminate` | La acción se ejecutó, pero no se puede concluir nada | `[?]` |
| `error` | MacNoise en sí falló al llevar a cabo la acción | `[!]` |
Un sondeo TCC denegado o un beacon hacia un C2 muerto es la telemetría que esta herramienta existe para generar, por lo que es distinto de `error`, que significa que MacNoise en sí falló. El registro de auditoría registra el mismo valor en `unmapped.outcome`. Los parámetros declarados como sensibles se reemplazan con `[REDACTED]` en los registros de auditoría gestionados y en la identidad de la línea de comandos.
El registro de auditoría se abre en modo append, por lo que los registros de múltiples ejecuciones se acumulan en un solo archivo para análisis por lotes. Si estás añadiendo un módulo y quieres saber cómo se clasifica un nuevo tipo de evento en OCSF, consulta [CONTRIBUTING.md](https://github.com/0xv1n/macnoise/blob/main/CONTRIBUTING.md#primitive-modules).
## Referencia de módulos
El [catálogo de módulos](https://github.com/0xv1n/macnoise/blob/main/docs/module-catalog.md) generado es la referencia autoritativa para nombres, parámetros, salidas, tipos de eventos, privilegios y mapeos ATT&CK. Las notas de categoría explican el comportamiento de la plataforma y los límites operativos:
| Categoría | 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) |
## Escenarios
Los escenarios encadenan módulos en secuencias ordenadas: un único archivo YAML que reproduce un patrón de intrusión de múltiples etapas contra tus detecciones.
| Archivo | Descripción |
|------|-------------|
| `network_only.yaml` | Operaciones compuestas de TCP, listener, DNS, beacon HTTP y exfiltración HTTP |
| `edr_validation.yaml` | Cobertura integral de detección de EDR |
| `full_sweep.yaml` | Todas las categorías |
| `lazarus_group.yaml` | Lazarus Group: inyección de dylib, descubrimiento de servicios, reverse shell, persistencia con LaunchAgent |
| `amos_atomic_stealer.yaml` | AMOS / Atomic Stealer: infostealer MaaS, bypass de Gatekeeper, volcado de keychain, exfiltración ZIP, persistencia de backdoor |
| `clickfix.yaml` | ClickFix: one-liner ofuscado pegado en Terminal, decodificación base64, obtención de segunda etapa, persistencia con LaunchAgent |
| `ransomware.yaml` | Impacto de ransomware: preparar señuelos en texto plano, cifrarlos y luego dejar una nota de rescate |
| `discovery.yaml` | Recetas compuestas de descubrimiento de sistema, cuentas, red y software de seguridad basadas en argv |
| `process_chain.yaml` | Cadena de shell de tres procesos construida a partir de un vector de argumentos explícito |
| `file_flow.yaml` | Flujo conectado de creación, modificación, descubrimiento acotado, lectura, copia y archivado |
| `mounted_execution.yaml` | Crear y ejecutar un payload desde un punto de montaje de imagen de disco observado |
Los dos escenarios de APT siguen secuencias de intrusión reales documentadas, técnica por técnica: cada archivo YAML cita la inteligencia de amenazas real a partir de la cual está construido y anota cada paso con la técnica MITRE que ejercita, así que empieza por ahí para el desglose completo en lugar de una repetición aquí.
**Dry-run primero:**
```bash
./macnoise scenario configs/scenarios/<scenario>.yaml --dry-run
```
**Referencia cruzada con tu SIEM/EDR:** cada comentario de paso nombra la técnica que debería activar. Ninguna alerta coincidente tras una ejecución real es una brecha en tu cobertura.
**Escribir el tuyo propio:**
```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"
```
Los parámetros se comprueban contra el tipo declarado de cada módulo: string, integer, boolean, path o list, antes de la previsualización o la ejecución. Los nombres desconocidos y los valores inválidos se rechazan. `on_error` es `stop` de forma predeterminada. Establécelo en `continue` solo cuando un barrido de cobertura deba intentar invocaciones posteriores de módulos tras un fallo.
Empieza desde la [plantilla de escenario](https://github.com/0xv1n/macnoise/blob/main/docs/templates/scenario.yaml) para entradas tipadas, salidas y flujo de datos conectado.
## Compatibilidad con la versión 1
La versión 1.0 define los comandos y flags de CLI compatibles, los nombres y contratos de los módulos, el esquema de escenario 1, el esquema de telemetría 2.0 y el esquema de informe de escenario 1.0. Los futuros cambios incompatibles en esas interfaces requieren una nueva versión mayor.
Los usuarios existentes deberían leer [Migrar de v0.6.0 a v1.0.0](https://github.com/0xv1n/macnoise/blob/main/docs/migration-v1.md). Asigna cada módulo eliminado y describe los cambios en escenarios, JSONL y la API de Go.
## Contribuir
Consulta [CONTRIBUTING.md](https://github.com/0xv1n/macnoise/blob/main/CONTRIBUTING.md) para las rutas de primitivas, escenarios y cambios en el núcleo.
Las versiones están automatizadas: [release-please](https://github.com/googleapis/release-please) genera una nueva versión directamente a partir del título de tu PR con [Conventional Commit](https://www.conventionalcommits.org/), por lo que `feat: add net_tls module` o `fix: correct beacon jitter` es tanto el título de tu PR como tu entrada del changelog.
## Descargo de responsabilidad
MacNoise está destinado a pruebas de seguridad **autorizadas**, validación de EDR e ingeniería de detección en sistemas que posees o para los que tienes permiso escrito explícito de probar. Los autores no asumen ninguna responsabilidad por el uso indebido.
## Política de código de IA
Las contribuciones de código de IA están bien, pero ten en cuenta que la revisión de código va a ser actualmente un proceso liderado por humanos, lo que significa que solo podemos revisar una cantidad limitada de código. Limita los PR a una corrección específica o a un nuevo módulo de telemetría. Los PR con cambios extensos probablemente se cerrarán.