Santamon

Sidecar de detecção leve para macOS, voltado para o Santa, que avalia a telemetria do Endpoint Security localmente com regras CEL e encaminha apenas os sinais de detecção correspondentes para um servidor backend.

Experimental. Construído para laboratórios domésticos e pequenas frotas. Versão inicial – espere bugs e mudanças na API.

O Que Ele Faz

O Santamon lê o fluxo de telemetria protobuf do Santa, avalia regras de detecção usando expressões CEL e envia sinais de segurança para um backend. A telemetria bruta permanece no endpoint — apenas as detecções são encaminhadas.

Principais recursos:

• Detecção local: regras baseadas em CEL avaliam eventos no dispositivo
• Três tipos de regras: correspondência simples, correlação por janela de tempo, linha de base (primeira ocorrência)
• Linhagem de processos: opcionalmente anexa árvores de processos completas aos sinais de execução
• Estado embutido: o BoltDB rastreia correlações, dados de primeira ocorrência e fila de sinais
• Envio resiliente: agrupamento concorrente, lógica de repetição e disjuntor

Por que o Santamon?

O Santamon é um sidecar de detecção para o Santa, não outro cliente ESF.

Construir uma ferramenta ESF personalizada exige os entitlements restritos da Apple, perfis de provisionamento e o tratamento cuidadoso de eventos de Endpoint Security em alto volume. O Santa já faz isso e é testado e comprovado em produção.

O valor do Santamon:

• Reutiliza o Santa como camada de sensor ESF (sem entitlements adicionais)
• Executa regras localmente, perto dos dados, em vez de transmitir tudo
• Estado leve via BoltDB para correlações e deduplicação
• Baixo custo de infraestrutura - envia apenas detecções de alto sinal

O Santa cuida da parte pesada da ingestão de eventos de Endpoint Security de forma confiável e segura; o Santamon foca na lógica de detecção e na qualidade do sinal.

Arquitetura

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)

Fluxo de dados:

1. O Watcher monitora o diretório de spool do Santa (/var/db/santa/spool/new/) em busca de novos arquivos protobuf
2. O Decoder lê e descomprime mensagens protobuf dos arquivos de spool
3. O Rules Engine avalia eventos contra expressões CEL (regras simples, de correlação e de linha de base)
4. O Signal Generator cria sinais ricos em contexto para correspondências de regras (com árvores de processos opcionais)
5. O Shipper agrupa e envia sinais para o backend via HTTPS com lógica de repetição e disjuntor
6. O State DB persiste o estado de correlação, o rastreamento de linha de base, a fila de sinais e o diário de spool

Ciclo de vida do spool:

• Arquivos de spool sem detecções são excluídos após o processamento para evitar que o spool do Santa encha
• Arquivos que produziram detecções são arquivados em santa.archive_dir (padrão: /var/lib/santamon/spool_hits)
• Os sinais incluem o caminho do spool arquivado quando disponível, para que você possa recuperar o protobuf se necessário

Linhagem de Processos:

• Cache em memória do histórico recente de execução de processos
• Permite contexto completo de árvore de processos para detecções de execução
• TTL: 1 hora | Máx: 50 mil entradas (despejo LRU)
• Sessão de inicialização isolada (sem ancestralidade entre inicializações)
• Consulte RULES.md para uso

Requisitos

• macOS 15.4+ (alguns tipos de telemetria, como tcc_modification, exigem macOS 15+)
• Santa com telemetria protobuf do northpolesec/santa
  • Consulte a documentação de telemetria do Santa
  • Exemplo de configuração: configs/examples/santa-config.mobileconfig
• Go 1.23+ (para compilar a partir do código-fonte)

Instalação

1. Configure o Santa para Telemetria Protobuf

O Santa deve ser configurado para gravar eventos protobuf. Use o perfil de configuração fornecido:

# 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. Compile o Santamon

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

3. Instale em Todo o Sistema

sudo make install

Isso instala:

• Binário: /usr/local/bin/santamon
• Config: /etc/santamon/config.yaml e rules.yaml
• LaunchDaemon: /Library/LaunchDaemons/com.santamon.plist
• Diretório de estado: /var/lib/santamon/

4. Configure o Backend e a Chave de API

Edite /etc/santamon/config.yaml:

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

Defina a chave de API no plist do 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. Inicie

# Start service
sudo make start

# Monitor logs
make logs

Configuração

Configuração 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

Consulte configs/santamon.yaml para ver todas as opções com comentários detalhados.

Regras de Detecção

As regras são expressões CEL que avaliam eventos do Santa. Três tipos suportados: simples, correlação e linha de 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

Organização das regras: arquivo único (/etc/santamon/rules.yaml) ou estrutura de diretórios com vários arquivos.

Valide antes de implantar:

santamon rules validate

Consulte RULES.md para obter um guia completo.

Backend

O Santamon exige um backend para receber sinais. Um backend FastAPI mínimo está incluído em backend/.

O que ele faz:

• Recebe sinais via POST /ingest (exige chave de API)
• Armazena sinais no banco de dados SQLite
• Fornece API de consulta (GET /signals, GET /stats)
• Acompanha a saúde do agente por meio de heartbeats (POST /agents/heartbeat)
• Interface web para gerenciamento de sinais

Início 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

Consulte 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

Documentação

• RULES.md - Guia de escrita de regras de detecção
• SECURITY.md - Considerações de segurança e resiliência do agente
• backend/README.md - Guia de implantação do backend
• configs/santamon.yaml - Referência completa de configuração
• configs/rules.yaml - Exemplos de regras de detecção