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"] &&

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

Regelorganisation: Einzelne Datei (/etc/santamon/rules.yaml) oder mehrdateiige Verzeichnisstruktur.

Vor der Bereitstellung validieren:

santamon rules validate

Siehe RULES.md für eine umfassende Anleitung.

Backend

Santamon benötigt ein Backend zum Empfangen von Signalen. Ein minimales FastAPI-Backend ist in backend/ enthalten.

Was es tut:

• Empfängt Signale über POST /ingest (API-Schlüssel erforderlich)
• Speichert Signale in einer SQLite-Datenbank
• Stellt eine Abfrage-API bereit (GET /signals, GET /stats)
• Verfolgt den Agentenstatus über Heartbeats (POST /agents/heartbeat)
• Web-UI für die Signalverwaltung

Schnellstart:

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

Siehe backend/README.md.

CLI-Befehle

# 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

Dokumentation

• RULES.md – Leitfaden zum Schreiben von Erkennungsregeln
• SECURITY.md – Sicherheitsaspekte und Agent-Resilienz
• backend/README.md – Leitfaden zur Bereitstellung des Backends
• configs/santamon.yaml – Vollständige Konfigurationsreferenz
• configs/rules.yaml – Beispiel-Erkennungsregeln