Santamon

Sidecar de détection macOS léger pour Santa qui évalue la télémétrie Endpoint Security localement avec des règles CEL et transmet uniquement les signaux de détection correspondants à un serveur backend.

Expérimental. Conçu pour les laboratoires maison et les petits parcs. Version précoce – attendez-vous à des bugs et à des changements d'API.

Ce qu'il fait

Santamon lit le flux de télémétrie protobuf de Santa, évalue les règles de détection à l'aide d'expressions CEL et envoie les signaux de sécurité à un backend. La télémétrie brute reste sur l'endpoint—seules les détections sont transmises.

Fonctionnalités principales :

• Détection locale : les règles basées sur CEL évaluent les événements sur l'appareil
• Trois types de règles : correspondance simple, corrélation par fenêtre temporelle, baseline (première apparition)
• Filiation des processus : possibilité d'attacher des arborescences de processus complètes aux signaux d'exécution
• État embarqué : BoltDB suit les corrélations, les données de première apparition et la file d'attente des signaux
• Envoi résilient : traitement par lots concurrent, logique de réessai, disjoncteur

Pourquoi Santamon ?

Santamon est un sidecar de détection pour Santa, pas un autre client ESF.

Construire un outil ESF personnalisé nécessite les entitlements restreints d'Apple, des profils de provisionnement et une gestion minutieuse des événements Endpoint Security à haut volume. Santa fait déjà cela et est éprouvé en production.

La valeur de Santamon :

• Réutilise Santa comme couche de capteur ESF (aucun entitlement supplémentaire)
• Exécute les règles localement au plus près des données, au lieu de tout diffuser en continu
• État léger via BoltDB pour les corrélations et la déduplication
• Faible coût d'infrastructure - ne transmet que les détections à fort signal

Santa s'occupe du gros du travail d'ingestion des événements Endpoint Security de manière fiable et sûre ; Santamon se concentre sur la logique de détection et la qualité des signaux.

Architecture

Santa Spool → Watcher → Decoder → Rules Engine → Signal Generator → Shipper → Backend
                 ↓                      ↓
                ┌────────────────────────┐
                │ State DB (BoltDB)      │
                │ • Correlation windows  │
                │ • Baseline tracking    │
                │ • Signal queue         │
                └────────────────────────┘
                Process lineage: in-memory cache (1h TTL, 50K max)

Flux de données :

1. Watcher surveille le répertoire spool de Santa (/var/db/santa/spool/new/) pour les nouveaux fichiers protobuf
2. Decoder lit et décompresse les messages protobuf des fichiers spool
3. Rules Engine évalue les événements par rapport aux expressions CEL (règles simples, de corrélation et de baseline)
4. Signal Generator crée des signaux riches en contexte pour les correspondances de règles (avec arborescences de processus optionnelles)
5. Shipper regroupe et envoie les signaux au backend via HTTPS avec logique de réessai et disjoncteur
6. State DB persiste l'état de corrélation, le suivi de baseline, la file d'attente des signaux et le journal spool

Cycle de vie du spool :

• Les fichiers spool sans détection sont supprimés après traitement pour éviter de remplir le spool de Santa
• Les fichiers ayant produit des détections sont archivés dans santa.archive_dir (par défaut : /var/lib/santamon/spool_hits)
• Les signaux incluent le chemin du spool archivé lorsque disponible afin que vous puissiez récupérer le protobuf si nécessaire

Filiation des processus :

• Cache en mémoire de l'historique récent des exécutions de processus
• Permet un contexte complet d'arborescence de processus pour les détections d'exécution
• TTL : 1 heure | Max : 50 000 entrées (éviction LRU)
• Session de démarrage isolée (aucune ascendance entre les démarrages)
• Voir RULES.md pour l'utilisation

Prérequis

• macOS 15.4+ (certains types de télémétrie comme tcc_modification nécessitent macOS 15+)
• Santa avec télémétrie protobuf de northpolesec/santa
  • Voir documentation télémétrie Santa
  • Exemple de configuration : configs/examples/santa-config.mobileconfig
• Go 1.23+ (pour compiler depuis les sources)

Installation

1. Configurer Santa pour la télémétrie protobuf

Santa doit être configuré pour écrire des événements protobuf. Utilisez le profil de configuration fourni :

# Review and customize, then install via System Settings
open configs/examples/santa-config.mobileconfig

# Verify
santactl status | grep "Log Type"
# Should show: Log Type | protobuf

2. Compiler Santamon

git clone https://github.com/0x4d31/santamon.git
cd santamon
make build

3. Installer à l'échelle du système

sudo make install

Ceci installe :

• Binaire : /usr/local/bin/santamon
• Configuration : /etc/santamon/config.yaml et rules.yaml
• LaunchDaemon : /Library/LaunchDaemons/com.santamon.plist
• Répertoire d'état : /var/lib/santamon/

4. Configurer le backend et la clé API

Modifiez /etc/santamon/config.yaml :

shipper:
  endpoint: "https://your-backend.example.com:8443/ingest"
  api_key: "${SANTAMON_API_KEY}"

Définissez la clé API dans le plist du LaunchDaemon :

# Generate strong API key
openssl rand -hex 32

# Edit LaunchDaemon
sudo nano /Library/LaunchDaemons/com.santamon.plist

# Add under EnvironmentVariables:
<key>SANTAMON_API_KEY</key>
<string>your-generated-key-here</string>

5. Démarrer

# Start service
sudo make start

# Monitor logs
make logs

Configuration

Configuration principale : /etc/santamon/config.yaml

agent:
  id: "${HOSTNAME}"

shipper:
  endpoint: "https://backend.example.com:8443/ingest"
  api_key: "${SANTAMON_API_KEY}"

santa:
  spool_dir: "/var/db/santa/spool"      # Santa spool location
  archive_dir: "/var/lib/santamon/spool_hits"  # Archive spool files that produced alerts
  stability_wait: "2s"                  # Wait before reading new files

rules:
  path: "/etc/santamon/rules.yaml"      # File or directory

state:
  db_path: "/var/lib/santamon/state.db"
  sync_writes: true                     # Fsync after writes (safer but slower)

  first_seen:
    max_entries: 10000                  # LRU cache for baseline rules

  windows:
    max_events: 1000                    # Max events per correlation window

shipper:
  batch_size: 100                       # Signals per batch
  flush_interval: "30s"                 # Time between flushes
  timeout: "10s"                        # HTTP request timeout
  tls_skip_verify: false                # NEVER true in production

Voir configs/santamon.yaml pour toutes les options avec commentaires détaillés.

Règles de détection

Les règles sont des expressions CEL qui évaluent les événements Santa. Trois types sont pris en charge : simple, corrélation et baseline.

rules:
  - id: SM-014
    title: "Non-interactive process invoking curl/wget"
    description: |
      Non-terminal, non-package-manager process launching curl or wget.
    expr: |
      kind == "execution" &&
      event.execution.target.executable.path in ["/usr/bin/curl", "/usr/bin/wget"] &&

      // Exclude interactive shells
      !(
        event.execution.instigator.executable.path.startsWith("/bin/bash") ||
        event.execution.instigator.executable.path.startsWith("/bin/zsh") ||
        event.execution.instigator.executable.path.startsWith("/bin/sh")
      ) &&

      // Exclude Homebrew / package-manager helpers that legitimately use curl frequently
      !(
        event.execution.instigator.executable.path.startsWith("/opt/homebrew/") ||
        event.execution.instigator.executable.path.contains("/Homebrew/")
      )
    severity: high
    tags: ["T1105", "command-and-control"]
    extra_context: ["event.execution.args"]
    include_process_tree: true
    enabled: true

correlations:
  - id: SM-COR-001
    title: "Process touching multiple credential stores"
    description: "Single process accessing 3+ credential stores within 5 minutes."
    expr: |
      kind == "file_access" &&
      event.file_access.policy_name in [
        "ChromeCookies", "CometCookies", "SSHPrivateKeys",
        "BrowserPasswords", "KeychainDB"
      ]
    window: "5m"
    group_by: ["event.file_access.instigator.executable.path"]
    count_distinct: "event.file_access.policy_name"
    threshold: 3
    severity: critical
    tags: ["T1539", "T1552", "credential-access"]
    enabled: true

baselines:
  - id: SM-BASE-001
    title: "First-time unsigned binary executed from user paths"
    description: "First time an unsigned binary executes from /Users paths."
    expr: |
      kind == "execution" &&
      event.execution.decision == DECISION_ALLOW &&
      event.execution.target.executable.path.startsWith("/Users/") &&
      (
        !has(event.execution.target.code_signature) ||
        !has(event.execution.target.code_signature.team_id) ||
        event.execution.target.code_signature.team_id == ""
      )
    track: ["event.execution.target.executable.cdhash"]
    learning_period: "720h"
    severity: high
    tags: ["T1204.002", "initial-access"]
    enabled: true

Organisation des règles : fichier unique (/etc/santamon/rules.yaml) ou structure de répertoire multifichier.

Valider avant le déploiement :

santamon rules validate

Voir RULES.md pour un guide complet.

Backend

Santamon nécessite un backend pour recevoir les signaux. Un backend FastAPI minimal est inclus dans backend/.

Ce qu'il fait :

• Reçoit les signaux via POST /ingest (nécessite une clé API)
• Stocke les signaux dans une base de données SQLite
• Fournit une API de requête (GET /signals, GET /stats)
• Suit la santé des agents via des heartbeats (POST /agents/heartbeat)
• Interface Web pour la gestion des signaux

Démarrage rapide :

cd backend
pip install fastapi uvicorn

# Set API key
export SANTAMON_API_KEY="your-key-here"

# Run (uses HTTPS if cert.pem exists, otherwise HTTP)
python backend.py

Voir backend/README.md.

Commandes CLI

# Run agent (foreground, verbose mode)
santamon run --verbose

# Validate rules
santamon rules validate

# Show status
santamon status

# Database operations
santamon db stats      # Show statistics
santamon db compact    # Compact database

# Version
santamon version

Documentation

• RULES.md - Guide d'écriture des règles de détection
• SECURITY.md - Considérations de sécurité et résilience de l'agent
• backend/README.md - Guide de déploiement du backend
• configs/santamon.yaml - Référence complète de la configuration
• configs/rules.yaml - Exemples de règles de détection