Detection as Code com Elastic Security

Nota do Capítulo 18, pasta de Frameworks de Detecção.
Demonstra a implementação concreta de Detection as Code no Elastic Security, cobrindo o repositório detection-rules, o formato TOML das regras, os testes unitários e de integração e o pipeline de release.
Dialoga com a ADS da pasta, que define o conteúdo dos documentos, e com o capítulo 19, cujo ciclo purple consome a esteira para validar regras automaticamente.

1. Contexto e Posicionamento na Biblioteca

A expressão Detection as Code, DaC, designa a prática de tratar cada detecção como artefato de software: versionada em controle de código, revisada por pares, testada automaticamente e entregue ao ambiente por pipeline, e nunca criada ou alterada diretamente na interface da plataforma. Esta nota concretiza a prática no Elastic Security, uma das implantações de referência do mercado, porque a Elastic mantém publicamente o repositório de regras de detecção que alimenta as regras predefinidas do produto, e esse repositório é uma aula aberta de engenharia de detecção.

O posicionamento na biblioteca é o de implementação que dá corpo aos frameworks da pasta. A ADS define o que cada documento de detecção precisa conter, a Hunting-to-Detection Bridge define como caças viram regras, e a esteira DaC define onde tudo isso vive e como chega em produção. Sem a esteira, os frameworks viram documento bom intencionado; com ela, viram processo de engenharia com evidência, bloqueio de merge e histórico auditável.

A escolha do Elastic Security como estudo de caso também serve de modelo transferível. O desenho adotado pela Elastic, com regras declarativas em formato de texto, suíte de testes, interface de linha de comando e releases alinhados às versões do stack, é replicável em outras plataformas com adaptações de formato, e os princípios desta nota valem para qualquer SIEM ou EDR que exponha regras via API. A nota cobre o repositório, o formato TOML, os testes, o pipeline de release, o fluxo de contribuição interna e as limitações honestas da prática.

2. O Repositório detection-rules

O repositório público da Elastic reúne as regras predefinidas do Elastic Security, e é a fonte que abastece os pacotes de regras entregues com o produto. Cada regra é um arquivo TOML com a consulta, os metadados e o mapeamento ATT&CK, e o repositório traz em volta do código a infraestrutura completa que um time interno precisa para operar detecções em escala: ferramenta de linha de comando escrita em Python, suíte de testes, rotinas de validação sintática e de consistência de metadados, e o processo de release que empacota as regras por versão do stack.

Quatro componentes do repositório merecem estudo detalhado por quem vai implementar DaC no ambiente.

• Arquivos de regra em TOML: cada regra é declarativa e legível por humano, com a consulta em EQL, KQL, Lucene ou Threat Match, e os metadados que a plataforma consome, do risco à severidade.
• Interface de linha de comando: o módulo Python do repositório concentra operações de lint, teste, autenticação no Kibana e importação e exportação de regras, e é essa CLI que o pipeline interno reaproveita.
• Suíte de testes: testes unitários validam sintaxe, tipos e consistência de metadados, e testes de integração sobem um Elasticsearch real com dados de exemplo para provar que a consulta casa com o evento esperado.
• Processo de release: as regras são versionadas e empacotadas em cadência alinhada às versões do stack, com changelog e compatibilidade explícitas por regra.

A lição de arquitetura que o repositório ensina é a separação entre a lógica da detecção e a infraestrutura de entrega. A regra sabe o que observar, e o pipeline sabe como testar e entregar. Times que misturam as duas responsabilidades acabam com regras que só funcionam na máquina do autor, e o repositório da Elastic é a referência pública de como manter as duas coisas separadas e versionadas.

3. Anatomia de uma Regra em TOML

O formato TOML organiza a regra em duas seções principais, metadados e corpo da regra, e o exemplo a seguir mostra um arquivo completo para uma detecção de dump de LSASS via comsvcs.dll. O exemplo é didático e reduzido, e o leitor encontrará no repositório campos adicionais de threshold, building block e exceções, mas a estrutura essencial é exatamente a do fragmento.

[metadata]
creation_date = "2025/03/12"
maturity = "production"
updated_date = "2025/09/02"
min_stack_version = "8.14.0"

[rule]
author = ["Equipe de Detecção"]
description = """
Detecta criação de dump de memória do LSASS via MiniDumpW da comsvcs.dll
por processo fora das ferramentas de backup homologadas.
"""
from = "now-6m"
index = ["logs-endpoint.process.*", "winlogbeat-*"]
language = "eql"
name = "LSASS MiniDump via comsvcs.dll"
risk_score = 73
rule_id = "6e4b1a2c-8f31-4d7e-9a55-01c2f3b4d5e6"
severity = "high"
tags = ["OS: Windows", "Tactic: Credential Access", "ADS: DETEC-0051"]
type = "eql"
query = '''
process where event.action == "start" and
  process.pe.original_file_name == "comsvcs.dll" and
  process.command_line : "*MiniDump*"
'''

<span class="broken-link" title="Nota nao encontrada no vault">rule.threat</span>
framework = "MITRE ATT&CK"

<span class="broken-link" title="Nota nao encontrada no vault">rule.threat.technique</span>
id = "T1003.001"
name = "LSASS Memory"

[rule.threat.technique.tactic]
id = "TA0006"
name = "Credential Access"

Três detalhes do formato explicam por que ele funciona como espinha de DaC. O campo rule_id é a identidade permanente da regra, e é por ele que o pipeline reconhece atualizações, evitando duplicação ao sincronizar com o Kibana. O bloco de threat carrega o mapeamento ATT&CK de forma estruturada, o que permite gerar camadas de Navigator e relatórios de cobertura por script, consumindo o método da pasta de métricas. E a tag de referência à ADS amarra o arquivo técnico ao documento de intenção, mantendo os dois sob o mesmo histórico de versão.

A disciplina de metadados é o que transforma o repositório em catálogo consultável. Campos como maturity, min_stack_version e as tags padronizadas não são enfeite, e sim os campos que o lint valida e que os painéis do programa consomem. A prática recomendada é definir o dicionário de tags no início do projeto, com convenção de prefixos, porque tags improvisadas multiplicam rapidamente e deixam de agregar valor de consulta.

4. Testes Unitários e de Integração

A suíte de testes é o que separa DaC de regras versionadas sem garantia, e a implantação da Elastic dá o padrão de duas camadas. Os testes unitários verificam cada arquivo de regra de forma estática: sintaxe TOML válida, campos obrigatórios presentes, consulta parseável na linguagem declarada, mapeamento ATT&CK consistente com a taxonomia e tags aderentes ao dicionário. São rápidos, rodam em cada commit e bloqueiam o merge na primeira violação, o que impede que regra malformada chegue a qualquer ambiente.

Os testes de integração respondem à pergunta que o lint não consegue: a consulta casa com o evento real. A rotina sobe um Elasticsearch com dados de exemplo que reproduzem a técnica alvo, executa a consulta da regra e verifica que o evento esperado é retornado, e que eventos benignos de controle não são. É a mesma lógica do pipeline de validação descrito no capítulo em emulação, e no caso da Elastic os datasets de exemplo de cada regra vivem no próprio repositório, o que permite testar a regra sem infraestrutura de endpoint.

• Testes unitários por commit: bloqueiam sintaxe, metadados e mapeamento inválidos, com tempo de execução em minutos.
• Testes de integração por pull request: provam que a consulta casa com o dataset de exemplo da técnica, com Elasticsearch efêmero provisionado pelo CI.
• Testes de regressão agendados: reexecutam a suíte contra versões novas do stack e dos datasets, capturando quebra silenciosa de consulta por mudança de esquema.

A camada de regressão agendada é a que mais protege o programa no longo prazo, porque consultas que casavam deixam de casar quando o esquema dos índices muda, e nada no lint captura isso. Times que implantam apenas as duas primeiras camadas descobrem quebras meses depois, no incidente, e a lição operacional é simples: a suíte completa roda na esteira, e a esteira roda sempre, e não só quando alguém lembra.

5. Pipeline de Release e Integração com Kibana

O pipeline de release transporta as regras do repositório até o Kibana sem intervenção manual, e o desenho da Elastic oferece duas lições principais. A primeira é a cadência alinhada ao stack: as regras predefinidas são empacotadas e publicadas em releases com compatibilidade declarada por versão, evitando o problema clássico de regra que depende de campos que a versão instalada não produz. A segunda é a entrega de atualizações como pacote versionado, com changelog por regra, o que permite ao operador avaliar cada mudança antes de aplicar, em vez de receber mutações silenciosas da plataforma.

No ambiente interno, o pipeline típico replica essa filosofia com etapas enxutas, e o fragmento a seguir ilustra um fluxo de CI para o repositório de detecções de um time. O desenho assume um repositório próprio derivado das práticas da Elastic, com pastas de regras e de testes, e usa a CLI do repositório oficial para lint e sincronização, reaproveitando o que o upstream já resolve.

name: deteccoes-ci
on:
  pull_request:
    paths: ["regras/**/*.toml", "testes/**"]
jobs:
  validacao:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Lint das regras
        run: python -m detection_rules lint regras/
      - name: Testes unitários
        run: python -m pytest testes/unitarios
      - name: Testes de integração
        run: python -m pytest testes/integracao --ambiente=efemero
  entrega:
    needs: validacao
    if: github.ref == 'refs/heads/main'
    steps:
      - name: Import para Kibana de homologação
        run: python -m detection_rules kibana-sync --space homolog
      - name: Import para Kibana de produção
        run: python -m detection_rules kibana-sync --space producao

O desenho acima incorpora a decisão de implantação mais debatida em DaC: homologação antes de produção. Regras em produção alimentam fila de analistas, e regra nova mal calibrada custa atenção humana imediata, por isso o padrão maduro envia o merge primeiro para um espaço de homologação com a mesma telemetria e a mesma normalização, observa volume e ruído por um ciclo curto e promove para produção. Times com volume baixo podem comprimir a homologação em horas, e times com frota grande não devem pulá-la.

A integração com o Kibana depende das APIs de gestão de regras, que a CLI do repositório usa para importar, atualizar e exportar. A exportação merece destaque operacional: ela permite puxar de volta para o repositório qualquer mudança feita na interface, e o pipeline pode agendar uma exportação comparativa que falha quando detecta divergência entre o ambiente e o repositório, o que encerra a prática de ajustes manuais na UI, a maior fonte de dessincronização em programas DaC.

6. Fluxo de Contribuição Interna

O fluxo interno de trabalho replica o modelo de contribuição open source, e a sua força está na padronização das etapas. A proposta nasce de uma ADS preenchida ou de uma promoção de caça, o autor abre branch com a regra em TOML e o dataset de teste, o CI roda lint e suíte completa, a revisão de pares analisa intenção e técnica com o documento ADS ao lado, e o merge dispara a entrega pelo pipeline. O roteiro a seguir detalha as etapas que garantem qualidade sem travar o ritmo do time.

• Proposta: issue descreve a detecção com referência à ADS ou ao documento de promoção, e o autor cria branch nomeado pelo ID da detecção.
• Implementação: arquivo TOML na pasta de regras, dataset de exemplo na pasta de testes e atualização do changelog interno, tudo no mesmo pull request.
• Revisão: um engenheiro valida técnica e metadados, e um analista valida intenção operacional, prioridade e custo de triagem, espelhando a revisão cruzada da ADS.
• Merge e entrega: pipeline importa para homologação, observa o ciclo acordado e promove para produção, com changelog no pull request como registro.

O dataset de exemplo que acompanha cada regra é o detalhe que eleva o fluxo acima de um checklist. Com o dataset no repositório, o teste de integração prova a consulta contra o evento esperado em cada pull request, e o time acumula progressivamente uma biblioteca de telemetria sintética cobrindo as técnicas do catálogo, que depois serve às emulações do capítulo 19 e às rotinas de regressão. Cada regra entregue deixa o ambiente de teste mais rico para a próxima, e esse acúmulo é um dos retornos compostos da prática.

7. Limitações e Erros Comuns de Operação

A prática tem limitações reais que o planejamento precisa absorver. O catálogo predefinido da Elastic entrega melhorias em cadência de release, e o time interno que customiza regras upstream herda o trabalho de reconciliar suas mudanças com as atualizações oficiais, o que recomenda o padrão de overlay: regras oficiais importadas como vêm, e customizações vivendo em arquivos próprios derivados, de modo que a atualização nunca sobrescreva trabalho local. Regras de funcionalidades reservadas a licenças específicas também limitam o que ambientes com licenciamento básico podem implantar, e o formato TOML tem curva de aprendizado própria para analistas acostumados a criar regras em interface gráfica.

• Criar regra direto na interface e sincronizar depois, quebrando a premissa do repositório como fonte única e gerando divergência que a exportação comparativa teria capturado.
• Copiar regra upstream e customizá-la no lugar, perdendo a capacidade de receber atualizações oficiais sem conflito manual recorrente.
• Pular datasets de teste para agilizar, entregando consultas nunca provadas contra evento real e transferindo o teste para a fila de triagem.
• Tratar o lint como obstáculo e contorná-lo, enfraquecendo o dicionário de metadados que sustenta os relatórios de cobertura e o catálogo.
• Rodar a suíte só quando conveniente, abrindo janela para quebras silenciosas por mudança de esquema que a regressão agendada teria capturado.

O erro de maior custo acumulado é o primeiro da lista, e por isso a ferramenta de governança mais valiosa da prática é a exportação comparativa agendada, que transforma divergência entre ambiente e repositório em falha visível de build. Com ela ativa, o repositório volta a ser a verdade, e a interface do Kibana vira o que deve ser, janela de consulta e observação, e não editor de produção.

8. Integração com o Restante da Biblioteca

Na pasta, a esteira DaC é a infraestrutura que os outros frameworks pressupõem: a ADS vive no repositório como documento lado a lado com o TOML, a ponte de promoção entrega seus artefatos por pull request e as métricas de qualidade são calculadas por script a partir dos metadados e do histórico de versões. O catálogo deixa de ser tabela manual e passa a ser vista gerada sobre o repositório, sempre sincronizada com a realidade implantada.

Com o capítulo 19, a conexão fecha o ciclo purple: cada regra nova chega em produção já validada contra o dataset da técnica, e o ciclo purple mensal reexecuta as emulações contra a frota real, comparando resultado com a promessa do teste de integração e abrindo pull requests de correção quando a realidade diverge. Com os capítulos de cobertura e de BAS, a esteira fornece o destino das lacunas encontradas, transformando relatório de gap em merge de regra, que é a única forma sustentável de converter medição em melhoria permanente.