Santamon

Leichtgewichtiger macOS-Erkennungs-Sidecar für Santa, der Endpoint-Security-Telemetrie lokal mit CEL-Regeln auswertet und nur übereinstimmende Erkennungssignale an einen Backend-Server weiterleitet.

Experimentell. Entwickelt für Home-Labs und kleine Flotten. Frühe Veröffentlichung – mit Fehlern und API-Änderungen ist zu rechnen.

Was es tut

Santamon liest den Protobuf-Telemetriestream von Santa, wertet Erkennungsregeln mithilfe von CEL-Ausdrücken aus und sendet Sicherheitssignale an ein Backend. Die Roh-Telemetrie bleibt auf dem Endpoint – nur Erkennungen werden weitergeleitet.

Kernfunktionen:

• Lokale Erkennung: CEL-basierte Regeln werten Ereignisse auf dem Gerät aus
• Drei Regeltypen: Einfacher Abgleich, Korrelation über Zeitfenster, Baseline (Erstsichtung)
• Prozessherkunft: Optional vollständige Prozessbäume an Ausführungssignale anhängen
• Eingebetteter Zustand: BoltDB verfolgt Korrelationen, Erstsichtungsdaten und Signalwarteschlange
• Robuste Zustellung: Paralleles Batching, Wiederholungslogik, Circuit Breaker

Warum Santamon?

Santamon ist ein Erkennungs-Sidecar für Santa, kein weiterer ESF-Client.

Die Entwicklung eines eigenen ESF-Tools erfordert die eingeschränkten Entitlements von Apple, Provisioning-Profile und einen sorgfältigen Umgang mit hochvolumigen Endpoint-Security-Ereignissen. Santa erledigt das bereits und ist in der Produktion bewährt.

Der Nutzen von Santamon:

• Nutzt Santa als ESF-Sensorschicht (keine zusätzlichen Entitlements)
• Führt Regeln lokal in der Nähe der Daten aus, anstatt alles zu streamen
• Leichtgewichtiger Zustand über BoltDB für Korrelationen und Deduplizierung
• Geringe Infrastrukturkosten – versendet nur Erkennungen mit hohem Signalwert

Santa übernimmt die schwere Arbeit der zuverlässigen und sicheren Erfassung von Endpoint-Security-Ereignissen; Santamon konzentriert sich auf Erkennungslogik und Signalqualität.

Architektur

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)

Datenfluss:

1. Watcher überwacht das Spool-Verzeichnis von Santa (/var/db/santa/spool/new/) auf neue Protobuf-Dateien
2. Decoder liest und dekomprimiert Protobuf-Nachrichten aus Spool-Dateien
3. Rules Engine wertet Ereignisse anhand von CEL-Ausdrücken aus (einfache Regeln, Korrelations- und Baseline-Regeln)
4. Signal Generator erstellt kontextreiche Signale für Regelübereinstimmungen (optional mit Prozessbäumen)
5. Shipper bündelt Signale und sendet sie per HTTPS an das Backend, mit Wiederholungslogik und Circuit Breaker
6. State-DB speichert Korrelationszustand, Baseline-Verfolgung, Signalwarteschlange und Spool-Journal

Spool-Lebenszyklus:

• Spool-Dateien ohne Erkennungen werden nach der Verarbeitung gelöscht, damit sich der Spool von Santa nicht füllt
• Dateien, die Erkennungen erzeugt haben, werden in santa.archive_dir archiviert (Standard: /var/lib/santamon/spool_hits)
• Signale enthalten bei Verfügbarkeit den Pfad der archivierten Spool-Datei, damit du das Protobuf bei Bedarf abrufen kannst

Prozessherkunft:

• In-Memory-Cache der letzten Prozessausführungshistorie
• Ermöglicht vollständigen Prozessbaum-Kontext für Ausführungserkennungen
• TTL: 1 Stunde | Max: 50K Einträge (LRU-Verdrängung)
• Boot-Sitzung isoliert (keine Abstammung über Boot-Sitzungen hinweg)
• Siehe RULES.md zur Verwendung

Anforderungen

• macOS 15.4+ (einige Telemetriearten wie tcc_modification erfordern macOS 15+)
• Santa mit Protobuf-Telemetrie von northpolesec/santa
  • Siehe Dokumentation zur Santa-Telemetrie
  • Beispielkonfiguration: configs/examples/santa-config.mobileconfig
• Go 1.23+ (zum Erstellen aus dem Quellcode)

Installation

1. Santa für Protobuf-Telemetrie konfigurieren

Santa muss so konfiguriert werden, dass Protobuf-Ereignisse geschrieben werden. Verwende das mitgelieferte Konfigurationsprofil:

# 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. Santamon erstellen

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

3. Systemweit installieren

sudo make install

Dies installiert:

• Binary: /usr/local/bin/santamon
• Konfiguration: /etc/santamon/config.yaml und rules.yaml
• LaunchDaemon: /Library/LaunchDaemons/com.santamon.plist
• Zustandsverzeichnis: /var/lib/santamon/

4. Backend und API-Schlüssel konfigurieren

Bearbeite /etc/santamon/config.yaml:

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

Setze den API-Schlüssel in der LaunchDaemon-Plist:

# 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. Starten

# Start service
sudo make start

# Monitor logs
make logs

Konfiguration

Hauptkonfiguration: /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

Siehe configs/santamon.yaml für alle Optionen mit ausführlichen Kommentaren.

Erkennungsregeln

Regeln sind CEL-Ausdrücke, die Santa-Ereignisse auswerten. Drei Typen werden unterstützt: einfach, Korrelation und 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"] &&