MacNoise

MacNoise génère de la télémétrie macOS réelle : connexions réseau, écritures de fichiers, créations de processus, mutations de plist, sondes TCC, et plus encore. Pointez-le vers une machine exécutant votre pile EDR, SIEM ou pare-feu et observez ce qui se déclenche réellement - pas ce que la fiche technique du fournisseur prétend déclencher.

Pour le contexte sur la motivation et la conception, voir le billet de blog de la version.

Démarrage rapide

# 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

Catégories de télémétrie

Voir le catalogue de modules généré pour chaque module, paramètre, sortie, type d'événement, privilège et mappage ATT&CK.

Commandes

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

Options globales

Flux de données des scénarios

Les fichiers de scénario utilisent version: 1. Les entrées et les sorties de module sont typées, et une étape ultérieure y fait référence avec des mappages explicites plutôt qu'une interpolation de chaînes :

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

Seules les sorties déclarées par un module peuvent être référencées. Les scénarios locaux peuvent être réutilisés avec une étape include ; les inclusions sont relatives, ne peuvent pas remonter au-dessus du répertoire racine du scénario, sont vérifiées pour les cycles et sont limitées à huit niveaux. MacNoise valide le graphe complet avant l'exécution, attribue à l'exécution un espace de travail privé unique et nettoie les modules invoqués dans l'ordre inverse. Utilisez --input content=value pour fournir des entrées et --report report.json pour le rapport d'exécution versionné.

Laisser les artefacts en place

Par défaut, chaque module s'inverse lorsqu'il se termine. C'est généralement ce que vous voulez, mais cela signifie qu'une détection ne voit jamais que l'événement d'installation. Pour valider que votre pile détecte la persistance elle-même - un LaunchAgent résidant dans ~/Library/LaunchAgents, une entrée cron, un profil shell modifié - l'artefact doit encore être présent lorsque l'analyse s'exécute :

./macnoise run svc_launch_agent --no-cleanup

Chaque module qui ignore le nettoyage affiche une ligne le nommant, et le journal d'audit enregistre cleanup_result: skipped plutôt que ok, afin qu'une exécution ayant laissé une persistance derrière elle ne soit jamais confondue avec une exécution ayant nettoyé. Utilisez macnoise info <module> pour voir ce qu'un module donné crée.

Il vous incombe de les supprimer vous-même. Réexécuter le même module sans l'option ne nettoiera que ce que cette exécution a créé, pas ce qu'une exécution précédente avec --no-cleanup a laissé derrière elle.

Journalisation d'audit

MacNoise écrit deux flux distincts. Les événements de télémétrie - ce que votre EDR/SIEM voit réellement - vont vers stdout ou --output. Un second flux, optionnel, enregistre ce que MacNoise lui-même a fait : quels modules se sont exécutés, les résultats des prérequis/nettoyages et les mappages MITRE, au format JSONL OCSF 1.7.0.

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

Chaque événement de télémétrie porte un outcome faisant autorité et un subject typé (schéma 2.0). L'outcome indique ce qui est arrivé à l'action tentée par MacNoise, tandis que le subject identifie le fichier, le processus, le point de terminaison réseau, le service ou la ressource impliqués :

Une sonde TCC refusée ou un beacon vers un C2 mort est la télémétrie que cet outil existe pour générer, elle est donc distincte de error, qui signifie que MacNoise lui-même a échoué. Le journal d'audit enregistre la même valeur à unmapped.outcome. Les paramètres déclarés sensibles sont remplacés par [REDACTED] dans les enregistrements d'audit gérés et l'identité en ligne de commande.

Le journal d'audit s'ouvre en mode ajout, de sorte que les enregistrements de plusieurs exécutions s'accumulent dans un seul fichier pour une analyse par lots. Si vous ajoutez un module et voulez savoir comment un nouveau type d'événement est classé dans OCSF, voir CONTRIBUTING.md.

Référence des modules

Le catalogue de modules généré est la référence faisant autorité pour les noms, paramètres, sorties, types d'événements, privilèges et mappages ATT&CK. Les notes de catégorie expliquent le comportement de la plateforme et les limites opérationnelles :

Scénarios

Les scénarios enchaînent les modules en séquences ordonnées - un seul fichier YAML qui rejoue un schéma d'intrusion multi-étapes contre vos détections.

Les deux scénarios APT suivent de véritables séquences d'intrusion documentées, technique par technique - chaque fichier YAML cite le renseignement sur les menaces réel à partir duquel il est construit et annote chaque étape avec la technique MITRE qu'il exerce, donc commencez par là pour la ventilation complète plutôt qu'un récit ici.

Dry-run d'abord :

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

Recoupez avec votre SIEM/EDR : chaque commentaire d'étape nomme la technique qu'il devrait déclencher. Aucune alerte correspondante après une exécution réelle est une lacune dans votre couverture.

Écrire le vôtre :

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"

Les paramètres sont vérifiés par rapport au type déclaré de chaque module : chaîne, entier, booléen, chemin ou liste, avant la prévisualisation ou l'exécution. Les noms inconnus et les valeurs invalides sont rejetés. on_error vaut stop par défaut. Ne le définissez sur continue que lorsqu'une passe de couverture doit tenter des invocations de modules ultérieurs après un échec.

Partez du modèle de scénario pour les entrées typées, les sorties et le flux de données connecté.

Compatibilité de la version 1

La version 1.0 définit les commandes et options CLI prises en charge, les noms et contrats des modules, le schéma de scénario 1, le schéma de télémétrie 2.0 et le schéma de rapport de scénario 1.0. Les futures modifications incompatibles de ces interfaces nécessitent une nouvelle version majeure.

Les utilisateurs existants devraient lire Migrating from v0.6.0 to v1.0.0. Il mappe chaque module supprimé et décrit les changements de scénario, JSONL et API Go.

Contribuer

Voir CONTRIBUTING.md pour les parcours de primitive, de scénario et de modification du cœur.

Les versions sont automatisées - release-please publie une nouvelle version directement à partir du titre de votre PR Conventional Commit, donc feat: add net_tls module ou fix: correct beacon jitter est à la fois votre titre de PR et votre entrée de changelog.

Avertissement

MacNoise est destiné aux tests de sécurité autorisés, à la validation EDR et à l'ingénierie de détection sur des systèmes que vous possédez ou pour lesquels vous disposez d'une autorisation écrite explicite de tester. Les auteurs n'assument aucune responsabilité en cas de mauvaise utilisation.

Politique relative au code IA

Les contributions de code IA sont acceptées, mais gardez à l'esprit que la revue de code sera actuellement un processus mené par des humains, ce qui signifie que nous ne pouvons examiner qu'une quantité limitée de code. Veuillez limiter les PR à un correctif spécifique ou à un nouveau module de télémétrie. Les PR avec des changements étendus seront probablement fermées.