Repositórios de Regras em Git (Elastic, Wazuh, Sigma)

Nota da pasta de Detection-as-Code do capítulo 18, sobre Detection Engineering e Automação.
Estuda a estrutura e a operação de repositórios de regras de detecção, com exemplos reais dos projetos Elastic, Wazuh e Sigma HQ.
Dialoga com os princípios de DaC da primeira nota da pasta, com a conversão de Sigma na pasta de Pipeline de Detecção e com o controle AUT.3 do framework CTH.

1. Contexto e Posicionamento na Biblioteca

As duas notas anteriores estabeleceram por que tratar detecção como código e como organizar o ciclo de vida de cada regra, e esta nota desce para o objeto concreto que sustenta a prática: o repositório Git. O repositório é a fonte da verdade do catálogo, e o desenho da estrutura de diretórios, das convenções de commit e do processo de revisão determina a qualidade operacional do programa de detecção tanto quanto a qualidade individual das regras.

A nota usa três projetos públicos como referência de arquitetura, porque eles operam em escala real e expõem decisões que o time interno enfrentará: o repositório de regras da Elastic, o ruleset do Wazuh e o repositório Sigma HQ. Estudar como milhares de regras vivem nesses repositórios, com revisão, testes e integração contínua públicos, é o caminho mais rápido para desenhar um repositório interno maduro, adaptando padrões em vez de inventar do zero.

2. Estrutura Geral de um Repositório de Detecções

Todo repositório de detecções maduro separa três zonas: as regras em si, o material de validação e a infraestrutura de processo. As regras ficam organizadas por uma dimensão estável, tipicamente a fonte de log, a tática ATT&CK ou o produto de destino, e a escolha deve considerar como o time busca regras no dia a dia. O material de validação inclui dados sintéticos, corpus de regressão e configurações de lint, e a infraestrutura de processo inclui templates de pull request, actions da CI e documentação de contribuição.

O exemplo abaixo mostra uma estrutura interna típica, que sintetiza os padrões observados nos projetos públicos. A estrutura assume regras em Sigma na raiz do catálogo e detecções nativas por plataforma em pastas específicas, um compromisso comum em ambientes multiplataforma.

detection-rules/
|-- rules/
|   |-- sigma/
|   |   |-- windows/
|   |   |   |-- execution/
|   |   |   |   `-- powershell_download_cradle.yml
|   |   |   |-- persistence/
|   |   |   `-- lateral_movement/
|   |   |-- linux/
|   |   |-- cloud/
|   |   `-- network/
|   |-- native/
|   |   |-- elastic/
|   |   `-- splunk/
|   `-- custom/            # regras específicas do ambiente
|-- tests/
|   |-- synthetic/
|   |   `-- windows/execution/powershell_download_cradle.json
|   `-- regression/
|-- pipelines/
|   |-- convert_to_kql.yml
|   `-- convert_to_spl.yml
|-- docs/
|   |-- CONTRIBUTING.md
|   |-- detection_template.md
|   `-- pr_checklist.md
|-- .github/workflows/
|   |-- lint.yml
|   |-- test.yml
|   `-- deploy.yml
`-- README.md

A organização por produto de log primeiro e tática depois reflete o modo como a telemetria se agrupa: regras de execução do Windows compartilham campos e falsos positivos típicos, e agrupá-las facilita o tuning em conjunto. A pasta custom guarda regras com dependências do ambiente, como nomes internos de contas e serviços, separada das regras portáveis que poderiam ser compartilhadas externamente.

3. O Repositório Elastic Detection-Rules

O repositório da Elastic, conhecido como detection-rules, é a fonte das regras integradas do motor de detecção do Elastic Security, com milhares de regras escritas em TOML com consultas KQL ou EQL embutidas. Cada arquivo de regra declara metadados completos, incluindo severidade, risco calculado, mapeamento ATT&CK e notas de investigação, e o repositório inclui o código Python que empacota e publica as regras nas versões do produto.

Três decisões de arquitetura merecem atenção do leitor interno. Primeira, o uso de TOML com consultas como strings permite validação programática forte e geração de documentação automática, ao custo de legibilidade um pouco menor que YAML. Segunda, o repositório carrega testes por regra, com eventos sintéticos que comprovam o disparo, e a CI pública executa essas verificações em cada pull request, modelo que a nota de testes deste capítulo explora. Terceira, o versionamento segue o ciclo de release do produto, o que mostra o caso em que regras e plataforma versionam juntas, diferente do modelo interno onde o catálogo versiona independente da plataforma.

O modelo de contribuição da Elastic também é instrutivo: contribuições externas passam por pull request com template, assinatura de acordo de licença e revisão dos engenheiros do time, e as issues são triadas com rótulos por tática e por fonte de dados. O time interno pode espelhar esse processo com ferramentas mais simples, mantendo o template de PR e a triagem por rótulos, que organizam o backlog de manutenção das regras próprias.

4. O Ruleset do Wazuh

O Wazuh distribui seu ruleset em XML, com decoders e rules separados, e o repositório wazuh-ruleset expõe a estrutura que times que usam o Wazuh como SIEM conhecem bem. As regras dependem de decoders, que normalizam os logs brutos em campos nomeados, e essa camada extra de tradução é a grande lição do caso Wazuh: a qualidade da detecção depende tanto do parser quanto da lógica, e um repositório maduro de detecções precisa versionar e testar os dois juntos.

O fluxo de contribuição do ruleset para o ambiente interno segue o padrão: identificar o log não parseado ou o comportamento sem regra, escrever o decoder quando necessário com testes de exemplo do evento real, escrever a regra com nível de severidade adequado e submeter tudo no mesmo pull request, pois decoder sem regra e regra sem decoder não são unidades de mudança independentes. A prática de incluir o evento de log bruto como teste no pull request, prática visível nas contribuições do projeto, é diretamente transplantável para o repositório interno.

Uma diferença operacional importante do Wazuh é que as regras são recarregadas pelo gerenciador a cada sincronização, e a estratégia de deploy comum usa branches por ambiente com sincronização controlada, modelo que a nota de deploy automatizado deste capítulo contrapõe ao deploy por pipeline com estados declarados. Times que operam o Wazuh com agentes distribuídos precisam ainda considerar a latência de propagação do ruleset para os managers ao planejar o tempo entre merge e efeito em produção.

5. O Repositório Sigma HQ

O Sigma HQ é o repositório comunitário central de regras no formato Sigma, com milhares de regras organizadas por fonte de log e amplamente usadas como ponto de partida para catálogos internos. O formato Sigma, tratado em profundidade na nota de conversão da pasta de Pipeline de Detecção, expressa a lógica de detecção de forma independente de plataforma, e o repositório mostra o estado da arte em metadados de regra: title, id com UUID, status, description, references, author, date, tags ATT&CK, falsepositives e level.

A estrutura do Sigma HQ separa as regras por categoria de logsource, como process_creation, web e file_event, e depois por produto, como windows, linux e macos, uma dimensão diferente das outras organizações vistas antes e a mais adequada para catálogos escritos em Sigma, porque cada categoria implica um conjunto de campos e uma semântica de detecção próprios. A CI do repositório valida cada arquivo contra o schema oficial e executa checagens de qualidade que recusam regras sem os metadados mínimos, e esse é o padrão de lint que o time interno deve replicar desde o primeiro dia.

Para o ambiente interno, o Sigma HQ cumpre dois papéis complementares. Como fornecedor de conteúdo, as regras do projeto podem ser sincronizadas para um submódulo ou diretório separado, com filtro por relevância e testes no ambiente próprio, evitando editar regras de terceiros inline, o que atrapalharia sincronizações futuras. Como referência de padrão, o repositório é o guia de estilo de fato para metadados e nomenclatura, e o guia de contribuição interno deve citá-lo como base.

6. Convenções de Commit e Processo de Pull Request

Convenções de commit e PR são o que transforma um monte de arquivos em um histórico navegável, e a regra prática é simples: um commit corresponde a uma mudança com propósito único, e a mensagem explica o porquê, não o quê. O padrão de commits convencionais com escopo funciona bem para detecções, pois dá filtro imediato no histórico e na geração de changelogs.

Convenções de commit para repositório de detecções
feat(sigma/windows): nova regra para abuso de certutil com URL externa
fix(sigma/cloud): corrige campo errado na regra de role takeover no AWS
tune(elastic): reduz falsos positivos da regra de beaconing com baseline
docs(tests): adiciona corpus de regressão para regras de file_event
chore(deps): atualiza pySigma para 0.1.x e ajusta backends

Formato: <tipo>(<escopo>): <resumo em minúsculas, até 72 caracteres>
Tipos: feat, fix, tune, deprec, docs, test, chore
O corpo do commit cita ticket ou relatório quando houver.

O pull request é a unidade de revisão, e o template do PR deve cobrar o contexto mínimo que o revisor precisa. Um template enxuto cobra a descrição da detecção, a técnica ATT&CK, o resultado dos testes da pipeline e a lista de falsos positivos previstos, e o exemplo abaixo mostra um PR preenchido como referência prática.

Título: feat(sigma/windows): nova regra para abuso de certutil com URL externa

## O que esta detecção observa
Certutil com parâmetro urlcache ou verifyctl apontando para host externo,
padrão usado para download de carga em intrusões, com contexto de processo.

## Mapeamento ATT&CK
Defense Evasion, T1105 Ingress Tool Transfer (via ferramenta legítima).

## Resultado da pipeline
- lint e schema: aprovados
- teste sintético: dispara no evento T1105 injetado
- regressão 30 dias: 12 disparos, 11 esperados (downloads de artefatos
  internos pela equipe de implantação), 1 em investigação

## Falsos positivos previstos
Downloads autorizados por time de implantação, cobertos por filtro de
grupo de service accounts documentado na regra.

## Checklist do revisor
- [ ] Lógica corresponde ao desenho anexo
- [ ] Mapeamento ATT&CK conferido com a documentação
- [ ] Fonte de dados existe no inventário de telemetria
- [ ] Metadados completos e nomenclatura correta
- [ ] Testes suficientes para o nível de severidade

7. Code Review de Detecções e Linting

A revisão de código de detecção combina o olhar de engenharia de software com o olhar de analista, e o revisor precisa responder três famílias de perguntas: a lógica está correta e robusta, a regra é operacionalmente sustentável e a regra agrega valor ao catálogo. A família de sustentabilidade costuma ser a mais negligenciada: regra que executa consulta proibitivamente cara no motor, que gera volume acima da capacidade de triagem ou que duplica detecção existente derruba a saúde do catálogo mesmo com lógica impecável.

O linting automatiza a parte mecânica da revisão e deixa o revisor concentrado no julgamento. Para catálogos Sigma, a ferramenta sigma-cli com o comando check valida o schema, checa campos obrigatórios, verifica padrões de nomenclatura e sinaliza construções propensas a erro, e checagens complementares em yamllint e no validador do formato nativo escolhido completam a barreira. A regra de operação é que nenhuma checagem automática pode ser ignorada por exceção manual: se o lint está errado, corrige-se o lint ou a regra, nunca se pula a checagem.

O branching deve ser o mais simples possível: trunk-based, com a branch principal protegida, exigindo PR aprovado e pipeline verde para merge, e branches de trabalho curtas vivendo poucos dias. Branches de release e ambientes por branch complicam sem ganho, porque o deploy por estágio é responsabilidade da pipeline e dos ambientes do provedor de CI, não da estrutura de branches, e a nota de deploy automatizado mostra esse desenho em detalhe.

Dois recursos de plataforma completam o processo com custo mínimo. O CODEOWNERS do provedor de Git define revisores obrigatórios por caminho, garantindo que regras de cloud, por exemplo, sejam sempre revisadas pelo especialista do domínio mesmo quando o autor é de outro time. Os rótulos de triagem, como tática ATT&CK, severidade e tipo de mudança, transformam o histórico em catálogo consultável e alimentam métricas do programa, como proporção de novas regras por tática no trimestre, direta ligação com o controle MAP da biblioteca.

8. Erros Comuns e Pontos de Atenção

• Estrutura por data ou por autor: organizar pastas por mês de criação ou por engenheiro destrói a navegabilidade, porque o leitor busca por comportamento e fonte, não por cronologia. Escolha dimensão estável e documente a escolha no README.
• Copiar regras do Sigma HQ sem validação local: regras comunitárias assumem campos e nomenclatura que variam com a configuração local de coleta, e a validação com dados do ambiente antes de habilitar em produção é inegociável.
• Editar regras de terceiros inline: alterar arquivo sincronizado de projeto externo gera conflitos eternos na próxima sincronização. Manter camadas separadas, upstream em diretório próprio e overrides em pasta custom com herança documentada.
• PR gigante com dezenas de regras: revisor não consegue julgar cinquenta regras de uma vez e aprova por fadiga, e o histórico perde granularidade para rollback. Limite prático de cinco a dez regras por PR.
• Histórico reescrito em branches compartilhadas: forçar push na principal destrói a rastreabilidade que justifica o DaC, e a proteção de branch com rejeição de force push é configuração básica desde o primeiro dia.
• Lint permissivo demais: desligar checagens que atrapalham regras antigas cobra o preço futuro em silêncio. Corrigir a regra antiga, mesmo custando uma tarde, preserva a barreira de qualidade que o lint existe para sustentar.
• Revisão sem acesso ao desenho: aprovado de PR sem ler o documento de desenho, o revisor julga só a sintaxe e deixa passar lógica correta sobre fonte errada. O template de PR anexa o desenho, e a nota de DDLC desta pasta define por quê.

9. Integração com o Restante da Biblioteca

A nota seguinte desta pasta detalha os testes que a CI dos repositórios aqui estudados executa, e as checagens de lint citadas aparecem na prática como os primeiros estágios da pipeline descrita lá. Na pasta de Pipeline de Detecção, a conversão de Sigma consome diretamente o catálogo em Sigma estruturado segundo esta nota, e o deploy automatizado operacionaliza o branching e a proteção de branch aqui definidos.

No restante da biblioteca, o controle AUT.3 do framework CTH descreve a automação de detecção cujo repositório é o alicerce, o controle DAT.1 e DAT.4 fornecem o inventário de telemetria que o revisor cruza ao validar fontes de dados, e a nota de consultas e linguagens do capítulo 9 apresenta os dialetos que aparecem nas regras nativas. Para times que operam Wazuh, o capítulo 15 traz os controles de coleta de logs cuja qualidade determina a eficácia dos decoders, e o exercício integrado do SOC do capítulo 16 pode ser executado com o fluxo de PR desta nota como trilha de trabalho.