Santamon

Sidecar ligero de detección para macOS Santa que evalúa la telemetría de Endpoint Security localmente con reglas CEL y reenvía solo las señales de detección coincidentes a un servidor backend.

Experimental. Creado para laboratorios domésticos y flotas pequeñas. Versión temprana: se esperan errores y cambios en la API.

Qué Hace

Santamon lee el flujo de telemetría protobuf de Santa, evalúa las reglas de detección mediante expresiones CEL y envía señales de seguridad a un backend. La telemetría bruta permanece en el endpoint; solo se reenvían las detecciones.

Capacidades principales:

• Detección local: las reglas basadas en CEL evalúan eventos en el dispositivo
• Tres tipos de reglas: coincidencia simple, correlación por ventana de tiempo, línea base (primera aparición)
• Linaje de procesos: opcionalmente adjunta árboles de procesos completos a las señales de ejecución
• Estado integrado: BoltDB realiza un seguimiento de correlaciones, datos de primera aparición y cola de señales
• Envío resiliente: procesamiento por lotes concurrente, lógica de reintentos, interruptor de circuito

¿Por qué Santamon?

Santamon es un sidecar de detección para Santa, no otro cliente ESF.

Crear una herramienta ESF personalizada requiere los entitlements restringidos de Apple, perfiles de aprovisionamiento y un manejo cuidadoso de eventos de Endpoint Security de alto volumen. Santa ya hace esto y está probada en producción.

El valor de Santamon:

• Reutiliza Santa como capa de sensor ESF (sin entitlements adicionales)
• Ejecuta reglas localmente cerca de los datos, en lugar de transmitir todo
• Estado ligero mediante BoltDB para correlaciones y deduplicación
• Bajo costo de infraestructura: solo envía detecciones de alta señal

Santa se encarga del trabajo pesado de ingerir eventos de Endpoint Security de manera confiable y segura; Santamon se centra en la lógica de detección y la calidad de las señales.

Arquitectura

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)

Flujo de datos:

1. Watcher supervisa el directorio spool de Santa (/var/db/santa/spool/new/) en busca de nuevos archivos protobuf
2. Decoder lee y descomprime mensajes protobuf de los archivos spool
3. Rules Engine evalúa eventos contra expresiones CEL (reglas simples, de correlación y de línea base)
4. Signal Generator crea señales ricas en contexto para las coincidencias de reglas (con árboles de procesos opcionales)
5. Shipper agrupa y envía señales al backend mediante HTTPS con lógica de reintentos e interruptor de circuito
6. State DB persiste el estado de correlación, el seguimiento de líneas base, la cola de señales y el diario de spool

Ciclo de vida del spool:

• Los archivos spool sin detecciones se eliminan tras procesarlos para evitar que el spool de Santa se llene
• Los archivos que produjeron detecciones se archivan en santa.archive_dir (predeterminado: /var/lib/santamon/spool_hits)
• Las señales incluyen la ruta del spool archivado cuando está disponible para que puedas recuperar el protobuf si es necesario

Linaje de procesos:

• Caché en memoria del historial reciente de ejecución de procesos
• Permite el contexto completo del árbol de procesos para detecciones de ejecución
• TTL: 1 hora | Máx.: 50 000 entradas (desalojo LRU)
• Sesión de arranque aislada (sin ascendencia entre arranques)
• Consulta RULES.md para su uso

Requisitos

• macOS 15.4+ (algunos tipos de telemetría como tcc_modification requieren macOS 15+)
• Santa con telemetría protobuf de northpolesec/santa
  • Consulta la documentación de telemetría de Santa
  • Configuración de ejemplo: configs/examples/santa-config.mobileconfig
• Go 1.23+ (para compilar desde el código fuente)

Instalación

1. Configurar Santa para telemetría protobuf

Santa debe configurarse para escribir eventos protobuf. Usa el perfil de configuración proporcionado:

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

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

3. Instalar en todo el sistema

sudo make install

Esto instala:

• Binario: /usr/local/bin/santamon
• Configuración: /etc/santamon/config.yaml y rules.yaml
• LaunchDaemon: /Library/LaunchDaemons/com.santamon.plist
• Directorio de estado: /var/lib/santamon/

4. Configurar backend y clave de API

Edita /etc/santamon/config.yaml:

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

Establece la clave de API en el plist del 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. Iniciar

# Start service
sudo make start

# Monitor logs
make logs

Configuración

Configuración principal: /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

Consulta configs/santamon.yaml para conocer todas las opciones con comentarios detallados.

Reglas de detección

Las reglas son expresiones CEL que evalúan eventos de Santa. Se admiten tres tipos: simple, correlación y línea base.

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

Organización de reglas: un solo archivo (/etc/santamon/rules.yaml) o estructura de directorio de múltiples archivos.

Valida antes de implementar:

santamon rules validate

Consulta RULES.md para obtener una guía completa.

Backend

Santamon requiere un backend para recibir señales. Se incluye un backend FastAPI mínimo en backend/.

Qué hace:

• Recibe señales mediante POST /ingest (requiere clave de API)
• Almacena señales en una base de datos SQLite
• Proporciona API de consulta (GET /signals, GET /stats)
• Realiza un seguimiento del estado del agente mediante heartbeats (POST /agents/heartbeat)
• Interfaz web para la gestión de señales

Inicio rápido:

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

Consulta backend/README.md.

Comandos 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

Documentación

• RULES.md - Guía para escribir reglas de detección
• SECURITY.md - Consideraciones de seguridad y resiliencia del agente
• backend/README.md - Guía de implementación del backend
• configs/santamon.yaml - Referencia completa de configuración
• configs/rules.yaml - Reglas de detección de ejemplo