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