0x4d31/santamonAgente di rilevamento leggero per macOS basato sulla telemetria di Endpoint Security di Santa.
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.
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:
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:
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.
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:
/var/db/santa/spool/new/) per nuovi file protobufCiclo di vita dello spool:
santa.archive_dir (predefinito: /var/lib/santamon/spool_hits)Albero dei processi:
tcc_modification richiedono macOS 15+)configs/examples/santa-config.mobileconfigSanta 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
git clone https://github.com/0x4d31/santamon.git
cd santamon
make build
sudo make install
Questo installa:
/usr/local/bin/santamon/etc/santamon/config.yaml e rules.yaml/Library/LaunchDaemons/com.santamon.plist/var/lib/santamon/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>
# Avvia il servizio
sudo make start
# Monitora i log
make logs
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.
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"] &&
// Esclude shell interattive
!(
event.execution.instigator.executable.path.startsWith("/bin/bash") ||
event.execution.instigator.executable.path.startsWith("/bin/zsh") ||
event.execution.instigator.executable.path.startsWith("/bin/sh")
) &&
// Esclude helper di Homebrew / gestori pacchetti che usano legittimamente curl frequentemente
!(
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: "Processo che tocca più archivi di credenziali"
description: "Un singolo processo accede a 3+ archivi di credenziali entro 5 minuti."
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: "Prima esecuzione di binario non firmato da percorsi utente"
description: "Prima volta che un binario non firmato viene eseguito da percorsi /Users."
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
Organizzazione delle regole: File singolo (/etc/santamon/rules.yaml) o struttura di directory multi-file.
Convalida prima di distribuire:
santamon rules validate
Vedi RULES.md per una guida completa.
Santamon richiede un backend per ricevere i segnali. Un backend FastAPI minimale è incluso in backend/.
Cosa fa:
POST /ingest (richiede chiave API)GET /signals, GET /stats)POST /agents/heartbeat)Avvio rapido:
cd backend
pip install fastapi uvicorn
# Imposta chiave API
export SANTAMON_API_KEY="your-key-here"
# Esegui (usa HTTPS se cert.pem esiste, altrimenti HTTP)
python backend.py
Vedi backend/README.md.
# Esegui agente (primo piano, modalità verbosa)
santamon run --verbose
# Convalida regole
santamon rules validate
# Mostra stato
santamon status
# Operazioni sul database
santamon db stats # Mostra statistiche
santamon db compact # Compatta database
# Versione
santamon version