Santamon

Sidecar di rilevamento macOS leggero per Santa che valuta la telemetria Endpoint Security localmente con regole CEL e inoltra solo i segnali di rilevamento corrispondenti a un server backend.

Sperimentale. Realizzato per home lab e flotte ridotte. Versione iniziale – ci si aspettano bug e modifiche all’API.

Cosa fa

Santamon legge il flusso di telemetria protobuf di Santa, valuta le regole di rilevamento usando espressioni CEL e invia i segnali di sicurezza a un backend. La telemetria grezza rimane sul dispositivo – solo i rilevamenti vengono inoltrati.

Funzionalità principali:

• Rilevamento locale: le regole basate su CEL valutano gli eventi sul dispositivo
• Tre tipi di regole: corrispondenza semplice, correlazione temporale, baseline (prima occorrenza)
• Albero dei processi: possibilità di allegare l’albero completo dei processi ai segnali di esecuzione
• Stato incorporato: BoltDB tiene traccia delle correlazioni, dei dati di prima occorrenza e della coda dei segnali
• Invio resiliente: raggruppamento concorrente, logica di ripetizione, circuit breaker

Perché Santamon?

Santamon è un sidecar di rilevamento per Santa, non un altro client ESF.

Creare uno strumento ESF personalizzato richiede entitlements Apple vincolati, profili di provisioning e una gestione attenta degli eventi Endpoint Security ad alto volume. Santa fa già questo ed è testato in produzione.

Il valore di Santamon:

• Riutilizza Santa come layer sensore ESF (nessun entitlement aggiuntivo)
• Esegue le regole localmente vicino ai dati, invece di inviare tutto in streaming
• Stato leggero tramite BoltDB per correlazioni e deduplicazione
• Costo infrastrutturale basso – invia solo i rilevamenti ad alto segnale

Santa si occupa del lavoro pesante di ingestione affidabile e sicura degli eventi Endpoint Security; Santamon si concentra sulla logica di rilevamento e sulla qualità del segnale.

Architettura

Santa Spool → Watcher → Decoder → Rules Engine → Signal Generator → Shipper → Backend
                 ↓                      ↓
                ┌────────────────────────┐
                │ State DB (BoltDB)      │
                │ • Correlazioni         │
                │ • Tracciamento baseline│
                │ • Coda segnali         │
                └────────────────────────┘
                Albero processi: cache in memoria (TTL 1h, max 50K)

Flusso dei dati:

1. Watcher monitora la directory spool di Santa (/var/db/santa/spool/new/) per nuovi file protobuf
2. Decoder legge e decomprime i messaggi protobuf dai file spool
3. Rules Engine valuta gli eventi rispetto alle espressioni CEL (regole semplici, di correlazione, baseline)
4. Signal Generator crea segnali ricchi di contesto per le corrispondenze delle regole (con alberi dei processi opzionali)
5. Shipper raggruppa e invia i segnali al backend via HTTPS con logica di ripetizione e circuit breaker
6. State DB persiste lo stato delle correlazioni, il tracciamento baseline, la coda dei segnali e il journal dello spool

Ciclo di vita dello spool:

• I file spool senza rilevamenti vengono cancellati dopo l’elaborazione per evitare che lo spool di Santa si riempia
• I file che hanno prodotto rilevamenti vengono archiviati in santa.archive_dir (predefinito: /var/lib/santamon/spool_hits)
• I segnali includono il percorso dello spool archiviato quando disponibile, in modo da poter recuperare il protobuf se necessario

Albero dei processi:

• Cache in memoria della cronologia recente delle esecuzioni dei processi
• Consente il contesto completo dell’albero dei processi per i rilevamenti di esecuzione
• TTL: 1 ora | Max: 50K voci (espulsione LRU)
• Sessione di avvio isolata (nessuna ascendenza tra riavvii)
• Vedi RULES.md per l’utilizzo

Requisiti

• macOS 15.4+ (alcuni tipi di telemetria come tcc_modification richiedono macOS 15+)
• Santa con telemetria protobuf da northpolesec/santa
  • Vedi documentazione telemetria Santa
  • Configurazione di esempio: configs/examples/santa-config.mobileconfig
• Go 1.23+ (per compilare dai sorgenti)

Installazione

1. Configura Santa per la Telemetria Protobuf

Santa deve essere configurato per scrivere eventi protobuf. Usa il profilo di configurazione fornito:

# Rivedi e personalizza, poi installa tramite Impostazioni di Sistema
open configs/examples/santa-config.mobileconfig

# Verifica
santactl status | grep "Log Type"
# Dovrebbe mostrare: Log Type | protobuf

2. Compila Santamon

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

3. Installa a livello di sistema

sudo make install

Questo installa:

• Binario: /usr/local/bin/santamon
• Configurazione: /etc/santamon/config.yaml e rules.yaml
• LaunchDaemon: /Library/LaunchDaemons/com.santamon.plist
• Directory di stato: /var/lib/santamon/

4. Configura Backend e Chiave API

Modifica /etc/santamon/config.yaml:

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

Imposta la chiave API nel plist del LaunchDaemon:

# Genera una chiave API forte
openssl rand -hex 32

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

# Aggiungi sotto EnvironmentVariables:
<key>SANTAMON_API_KEY</key>
<string>your-generated-key-here</string>

5. Avvia

# Avvia il servizio
sudo make start

# Monitora i log
make logs

Configurazione

Config 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"      # Posizione spool di Santa
  archive_dir: "/var/lib/santamon/spool_hits"  # Archivia i file spool che hanno prodotto allarmi
  stability_wait: "2s"                  # Attendi prima di leggere nuovi file

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

state:
  db_path: "/var/lib/santamon/state.db"
  sync_writes: true                     # Fsync dopo le scritture (più sicuro ma più lento)

  first_seen:
    max_entries: 10000                  # Cache LRU per regole baseline

  windows:
    max_events: 1000                    # Eventi massimi per finestra di correlazione

shipper:
  batch_size: 100                       # Segnali per lotto
  flush_interval: "30s"                 # Tempo tra gli svuotamenti
  timeout: "10s"                        # Timeout richiesta HTTP
  tls_skip_verify: false                # MAI true in produzione

Vedi configs/santamon.yaml per tutte le opzioni con commenti dettagliati.

Regole di Rilevamento

Le regole sono espressioni CEL che valutano gli eventi di Santa. Tre tipi supportati: semplice, correlazione e baseline.

rules:
  - id: SM-014
    title: "Processo non interattivo che invoca curl/wget"
    description: |
      Processo non terminale, non di gestione pacchetti che esegue curl o wget.
    expr: |
      kind == "execution" &&
      event.execution.target.executable.path in ["/usr/bin/curl", "/usr/bin/wget"] &&