macnoise v0.5.0
Générateur extensible de télémétrie système MacOS.
MacNoise
MacNoise génère de la télémétrie macOS réelle : connexions réseau, écritures de fichiers, lancements de processus, mutations de plist, sondes TCC, et plus encore. Pointez-le vers une machine exécutant votre 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
# Compilation (ajoutez build-amd64 / build-arm64 pour la compilation croisée vers Darwin, ou release pour les deux)
make build
# Liste des modules disponibles
./macnoise list
# Exécution d'un module unique
./macnoise run net_connect --param target=127.0.0.1 --param port=8080
# Aperçu sans exécution
./macnoise run svc_launch_agent --dry-run
# Exécution de tous les modules réseau
./macnoise run --category network
# Exécution d'un scénario
./macnoise scenario configs/scenarios/edr_validation.yaml
# Émission d'une sortie JSONL structurée
./macnoise run --category file --format jsonl --output /tmp/events.jsonl
Catégories de télémétrie
| Catégorie | Description | Modules |
|---|---|---|
network | Connexions sortantes, DNS, balisage, écouteurs, shells inversés, TLS, exfiltration | net_connect, net_listen, net_beacon, net_revshell, net_dns, net_dns_exfil, net_tls, net_exfil |
process | Lancement de processus, envoi de signaux, injection de dylib, découverte, contournement de Gatekeeper, osascript | proc_spawn, proc_signal, proc_inject, proc_discovery, proc_gatekeeper, proc_osascript |
file | Création de fichiers, modification, lectures de fichiers d'identifiants et de trousseaux, archivage, masquage | file_create, file_modify, file_browser_creds, file_cred_files, file_keychain_copy, file_archive, file_hide |
tcc | Sondes de permissions TCC (FDA, Contacts, Trousseau, Accessibilité, Enregistrement d'écran) | tcc_fda, tcc_contacts, tcc_keychain, tcc_accessibility, tcc_screen_recording |
endpoint_security | Déclencheurs d'événements du framework ES, y compris le montage de .dmg et l'exécution de charge utile | es_file, es_process, es_mount |
service | Persistance LaunchAgent/Daemon, cron, profil shell, éléments de connexion | svc_launch_agent, svc_launch_daemon, svc_cron, svc_shell_profile, svc_login_item |
plist | Création et modification de plist | plist_create, plist_modify |
xpc | Énumération des services XPC | xpc_enumerate |
evasion | Contournement de défense : effacement des journaux, timestomping, suppression de l'historique | evade_log_clear |
Commandes
macnoise run <module> [--param key=val ...] Exécute un module spécifique
macnoise run --category <cat> Exécute tous les modules d'une catégorie
macnoise run --all Exécute tous les modules
macnoise list [--category <cat>] Liste les modules
macnoise info <module> Affiche les détails du module, les paramètres, MITRE
macnoise scenario <file.yaml> Exécute un scénario YAML
macnoise categories Liste les catégories avec leurs compteurs
macnoise version Affiche la version
Options globales
| Option | Défaut | Description |
|---|---|---|
--format | human | Format de sortie : human ou jsonl |
--output | (aucun) | Écrit la sortie dans un fichier (en plus de stdout) |
--verbose | false | Sortie détaillée incluant les erreurs de nettoyage |
--dry-run | false | Aperçu des actions sans exécution |
--no-cleanup | false | Laisse les artefacts du module en place (voir ci-dessous) |
--timeout | 30 | Délai d'expiration par module en secondes |
--audit-log | (aucun) | Écrit les enregistrements d'audit OCSF 1.7.0 dans un fichier JSONL |
--config | (aucun) | Charge les valeurs par défaut depuis un fichier de configuration YAML |
Laisser des artefacts en place
Par défaut, chaque module s'annule lui-même lorsqu'il se termine. C'est généralement ce que vous souhaitez, 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 saute 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 fait le ménage. Utilisez macnoise info <module> pour voir ce qu'un module donné crée.
Vous êtes responsable 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 ont été exécutés, les résultats des prérequis/nettoyages, et les correspondances MITRE, au format OCSF 1.7.0 JSONL.
./macnoise scenario configs/scenarios/amos_atomic_stealer.yaml --audit-log /tmp/audit.jsonl
Chaque événement de télémétrie porte un outcome en plus de success (schéma 1.1). success indique si MacNoise a fonctionné ; outcome indique ce qui est arrivé à l'action qu'il a tentée :
outcome | Signification | Marqueur humain |
|---|---|---|
executed | L'action s'est exécutée et a fait ce que le module prétend | [+] |
denied | L'action s'est exécutée et l'environnement l'a refusée | [-] |
indeterminate | L'action s'est exécutée, mais aucune conclusion ne peut être tirée | [?] |
error | MacNoise lui-même a échoué à mener l'action à bien | [!] |
Une sonde TCC refusée ou un balisage vers un C2 mort est la télémétrie que cet outil existe pour générer, donc ceux-ci restent success: true et sont distingués par outcome. Seul error définit success: false. Dans le journal d'audit, la même valeur apparaît à unmapped.outcome, car le statut OCSF status enregistre une action refusée et un outil défaillant de manière identique.
Le journal d'audit s'ouvre en mode ajout, donc les enregistrements de plusieurs exécutions s'accumulent dans un seul fichier pour une analyse par lots. Si vous ajoutez un module et souhaitez savoir comment un nouveau type d'événement est classifié dans OCSF, voir CONTRIBUTING.md.
Référence des modules
La documentation des modules se trouve aux côtés de chaque catégorie :
| Catégorie | README |
|---|---|
network | modules/network/README.md |
process | modules/process/README.md |
file | modules/file/README.md |
tcc | modules/tcc/README.md |
endpoint_security | modules/endpoint_security/README.md |
service | modules/service/README.md |
plist | modules/plist/README.md |
xpc | modules/xpc/README.md |
evasion | modules/evasion/README.md |
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.
| Fichier | Description |
|---|---|
network_only.yaml | Tous les modules réseau |
edr_validation.yaml | Couverture complète de détection EDR |
full_sweep.yaml | Toutes les catégories |
lazarus_group.yaml | Groupe Lazarus : injection de dylib, découverte de services, shell inversé, persistance plist |
amos_atomic_stealer.yaml | AMOS / Atomic Stealer : infostealer MaaS, contournement de Gatekeeper, extraction du trousseau, exfiltration ZIP, persistance backdoor |
clickfix.yaml | ClickFix : one-liner obfusqué collé dans Terminal, décodage base64, récupération de la seconde étape, persistance LaunchAgent |
Les deux scénarios APT suivent des séquences d'intrusion réelles documentées, technique par technique — chaque fichier YAML cite le renseignement sur les menaces réel sur lequel il est construit et annote chaque étape avec la technique MITRE qu'il exerce, donc commencez-y pour la ventilation complète plutôt qu'un récit ici.
Aperçu d'abord :
./macnoise scenario configs/scenarios/<scenario>.yaml --dry-run
Recoupement 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 :
name: Mon scénario personnalisé
steps:
- module: net_connect
params:
target: "192.168.1.1"
port: "443"
- category: file
params:
base_dir: "/tmp/test"
Contribution
Voir CONTRIBUTING.md pour l'ajout de nouveaux modules, le style de code, et le processus complet de PR.
Les versions sont automatisées — release-please crée 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 journal des modifications.
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 avez une autorisation écrite explicite de tester. Les auteurs déclinent toute responsabilité en cas d'utilisation abusive.
Politique sur le code IA
Les contributions de code IA sont les bienvenues, mais veuillez garder à l'esprit que la revue de code sera actuellement un processus dirigé par des humains, ce qui signifie qu'il n'y a qu'une quantité limitée de code que nous pouvons examiner. Veuillez limiter les PR à un correctif spécifique ou à un nouveau module de télémétrie. Les PR avec des modifications étendues seront probablement fermées.