Em um cenário de ameaças em constante evolução, as operações de segurança estão chegando a um ponto crítico. Com o aumento da velocidade e da complexidade das ameaças, as equipes se expandem e os ambientes gerenciados se multiplicam. Normalmente, as abordagens manuais para o gerenciamento de regras se tornam um gargalo. É aqui que entra o Detections as Code (DaC), não apenas como uma ferramenta, mas como uma metodologia.

A metodologia DaC aplica práticas de desenvolvimento de software à criação, gestão e implementação de regras de detecção de segurança. Ao tratar as regras de detecção como código, possibilita o controle de versões, testes automatizados e processos de implantação, aprimorando a colaboração, a consistência e a agilidade na resposta a ameaças. O DaC simplifica o ciclo de vida das regras de detecção, garantindo detecções de alta qualidade por meio de revisões por pares e testes automatizados. Essa metodologia também auxilia no cumprimento dos requisitos de gerenciamento de mudanças e promove uma postura de segurança madura.

Por isso, estamos entusiasmados em compartilhar as últimas atualizações do detection-rules da Elastic, nosso repositório aberto para escrever, testar e gerenciar regras de detecção de segurança na Elastic, que também permite que você crie sua própria estrutura de Detecções como Código (DaC). Continue a leitura para ver exemplos de implementação em destaque usando funcionalidades estendidas e o anúncio do workshop gratuito Detections as Code da Elastic.

Elastic Security DaC: A jornada da versão alfa à disponibilidade geral

Com a funcionalidade agora disponível no repositório detection-rules , os usuários podem gerenciar todas as suas regras de detecção como código, revisar ajustes de regras, testar e validar regras automaticamente e automatizar a implantação de regras em seus ambientes.

Pré-2024: Uso interno do DaC pela Elastic

A equipe de engenharia de detecção e pesquisa de ameaças da Elastic criou e utilizou o repositório de regras de detecção para desenvolver, testar, gerenciar e liberar regras pré-construídas, seguindo os princípios DaC (Design-Action-Controller) – revisando as regras em equipe, automatizando seus testes e sua liberação. O repositório também possui uma CLI interativa para criar regras, permitindo que os engenheiros comecem a trabalhar nas regras imediatamente.

Com o crescente interesse da comunidade de segurança nos princípios de "como código" e com as APIs de segurança da Elastic já permitindo que os usuários implementassem suas soluções personalizadas de Detecção como código, a Elastic decidiu estender a funcionalidade do repositório de regras de detecção para permitir que nossos usuários se beneficiassem de nossas ferramentas e os auxiliasse na criação de seus processos de Detecção como Código (DaC).

Aqui estão os principais marcos do desenvolvimento do DaC da Elastic, focado no usuário, desde a versão alfa até a disponibilidade geral.

Maio de 2024: Lançamento da versão alfa de novos recursos "faça você mesmo"

Nosso repositório de regras de detecção é ajustado para uso do cliente, permitindo o gerenciamento de regras personalizadas, a adaptação do conjunto de testes às necessidades do usuário e o gerenciamento de ações e exceções juntamente com as regras.

Principais adições:

• Suporte para diretório de regras personalizadas
• Selecione qual teste executar com base em suas necessidades.
• Suporte para exceções e ações

Publicamos também um guia abrangente sobre Detecções como Código, com exemplos de implementação com o Elastic Security usando o repositório detection-rules .

Agosto de 2024: O recurso "Faça você mesmo" agora está em versão beta.

A funcionalidade foi ampliada para permitir a importação e exportação de regras personalizadas entre o Elastic Security e o repositório, além de oferecer mais opções de configuração e funcionalidade de versionamento para regras personalizadas.

Novas funcionalidades adicionadas:

• Importação/exportação em massa de regras personalizadas (com base nas APIs do Elastic Security)
• Testes unitários, validação e esquemas totalmente configuráveis.
• Bloqueio de versão para regras personalizadas

Março - Agosto de 2025: geralmente disponíveis e com suporte.

Utilizando o DaC com o Elastic Security 8.18 e versões superiores:

• Suporta gerenciamento de regras pré-configuradas. Você pode exportar todas as regras predefinidas do Elastic Security e armazená-las junto com suas regras personalizadas.
• Adicionada a funcionalidade de filtragem por regras para exportação.

Paralelamente aos esforços do DaC, também lançamos novos recursos do Terraform (V0.12.0 e V0.13.0) entre outubro e dezembro de 2025, permitindo que os usuários do Terraform gerenciem regras de detecção e exceções.

Com essa base estabelecida, vamos explorar os recursos poderosos disponíveis para otimizar seu processo de engenharia de detecção.

Funcionalidade DaC de regras de detecção em destaque

Houve algumas adições interessantes desde nossa última publicação sobre o DaC, que detalharemos a seguir.

Filtros adicionais

A funcionalidade de filtro disponível ao exportar regras do Kibana foi ampliada para permitir que você defina com precisão quais regras sincronizar no DaC. Aqui estão as novas bandeiras:

Vamos considerar um exemplo de quando você deseja organizar regras por fonte de dados e exportar as regras da AWS para uma pasta específica. Neste caso, vamos usar a filtragem por tags para fontes de dados e exportar todas as regras com a tag Data Source AWS :

python -m detection_rules kibana export-rules -d dac_test/rules #add rules to the dac_test/rules folder
-sv #strip the version fields from all rules
-cro #export only custom rules
-eq "alert.attributes.tags: "Data Source: AWS"" # export only rules with "Data Source: AWS" tag

Consulte a documentação do Kibana para obter informações sobre filtragem de strings de consulta para a chamada de API subjacente usada aqui e a chamada de API para listar todas as regras de detecção para obter exemplos de campos disponíveis para construir o filtro de consulta.

Estrutura de pastas personalizada

No repositório detection-rules, usamos uma estrutura de pastas baseada em plataforma, integração e informações do MITRE ATT&CK. Isso nos ajuda na organização e no desenvolvimento de regras. Este não é, de forma alguma, o único método de organização. Você pode organizar suas regras por cliente, data ou fonte, por exemplo. Isso pode variar bastante dependendo do seu caso específico.

Quer utilize este processo de exportação ou a organização manual, uma vez que as suas regras estejam numa localização ou estrutura de pastas à sua escolha, pode manter essa estrutura local mesmo ao reexportar as regras. É importante observar que as novas regras precisam ser inseridas manualmente no local desejado. O mecanismo local de carregamento de regras detecta onde as regras estão localizadas para saber onde colocá-las. Caso a regra não exista, o diretório de saída especificado será utilizado para inserir as novas regras. Para usar o carregamento de regras locais para atualizar regras existentes, use o sinalizador --load-rule-loading / -lr para os comandos kibana export-rules e import-rules-to-repo . Essas flags permitem que você utilize as pastas locais especificadas em seu config.yaml.

Vejamos um exemplo com as regras organizadas em pastas da seguinte forma:

rule_dirs:
- rules
my_test_rule.toml
- another_rules_dir
high_number_of_process_and_or_service_terminations.toml

Especificaremos o seguinte no arquivo config.yaml :

rule_dirs:
- rules
- another_rules_dir

Com a nova opção -lr , as atualizações de regras do Kibana agora usarão esses caminhos adicionais em vez de exportar diretamente para o diretório especificado.

Executar python -m detection_rules kibana --space test_local export-rules -d dac_test/rules/ -sv -ac -e -lr,exportará as regras do espaço test_local , my_test_rule.toml será gravado em dac_test/rules/, pois já estava em disco lá, e high_number_of_process_and_or_service_terminations.toml será gravado em dac_test/another_rules_dir/.

Isso pode ser particularmente útil se você tiver as mesmas regras em diferentes configurações de subpastas para diferentes clientes. Por exemplo, digamos que você tenha suas regras divididas por plataforma e integração, semelhante à estrutura de pastas de regras pré-configuradas da Elastic. Para seus clientes, SOCs ou equipes de busca de ameaças, ter as regras organizadas nessas pastas de plataforma/integração pode ser o mecanismo mais útil para gerenciá-las. No entanto, sua equipe de segurança da informação ou equipe principal de engenharia de detecção pode preferir gerenciar as regras por iniciativa ou autor da regra, de forma que todas as regras pelas quais um indivíduo ou equipe específica é responsável estejam organizadas em um só lugar. Agora, com os sinalizadores de carregamento de regras locais, você pode simplesmente ter dois arquivos de configuração e as regras duplicadas em cada estrutura. Ao exportar atualizações para as regras, você usará a variável de ambiente para selecionar o arquivo de configuração apropriado e exportar as atualizações das regras. Essas atualizações serão então aplicadas às regras existentes, mantendo a estrutura de diretórios.

Diversas atualizações de carregamento local

Além disso, adicionamos dois novos recursos menores, projetados para auxiliar os usuários que estão adicionando informações locais aos arquivos TOML e ao esquema das regras de detecção. São elas:

1. Suporte para datas locais a partir de arquivos locais, onde a data local será mantida a partir do arquivo original.
2. Aprimoramentos no recurso de geração automática para herdar tipos conhecidos de esquemas existentes.

O componente de data local pode ser útil quando se deseja um controle mais manual sobre o campo de data no arquivo. Sem usar a opção de substituição, a data será baseada em quando o conteúdo da regra do Kibana foi exportado. Usando a flag --local-creation-date , a data não será atualizada quando o conteúdo do arquivo for reexportado.

A geração automática de esquemas foi atualizada para herdar os tipos de outros índices/integrações, caso estejam presentes. Isso proporciona um esquema potencialmente mais preciso, além de reduzir a necessidade de atualizações manuais posteriores. Por exemplo, você tem uma regra que usa o índice “new-integration*” com os seguintes campos:

• host.os.type.new_field
• dll.Ext.relative_file_creation_time
• process.name.okta.thread

Em vez de cada um desses campos ser adicionado ao esquema com um tipo padrão, seus tipos são herdados de esquemas existentes. Neste caso, os tipos para dll.Ext.relative_file_creation_time e process.name.okta.thread são herdados.

{
  "new-integration*": {
    "dll.Ext.relative_file_creation_time": "double",
    "host.os.type.new_field": "keyword",
    "process.name.okta.thread": "keyword"
  }
}

Para ver como usar isso com seus tipos de dados personalizados, consulte a seção "Uso de esquemas personalizados" na parte "Exemplos de implementação" deste blog.

Ampliando os exemplos de uso

Abaixo, você encontrará mais exemplos de implementações de DaC. Estes não se concentram na adição de novas funcionalidades, mas aprofundam os tópicos que vemos sendo discutidos na comunidade.

Vale ressaltar que os recursos de Detecção como Código são fornecidos como componentes que podem ser usados para criar uma implementação personalizada para o processo e a arquitetura escolhidos. Ao implementar o DaC em seu ambiente de produção, trate-o como um processo de engenharia e siga as melhores práticas.

Implementação de DaC com GitLab

Quando analisamos as implementações de DaC, normalmente elas giram em torno do uso de algum tipo de produto CI/CD para executar automaticamente o gerenciamento de regras com base em um determinado gatilho. Esses gatilhos variam consideravelmente dependendo da configuração desejada, especificamente da fonte autorizada das regras e do estado desejado do seu sistema de controle de versão (VCS). Para uma análise muito mais aprofundada de algumas dessas considerações, consulte nosso Material de Referência de DaC. Abaixo, um exemplo simples usando o GitLab como provedor de VCS e seu sistema de CI/CD integrado por meio do GitLab Actions.

stages:                # Define the pipeline stages
  - sync               # Add a 'sync' stage

sync-to-production:    # Define a job named 'sync-to-production'
  stage: sync          # Assign this job to the 'sync' stage
  image: python:3.12   # Use the Python 3.12 Docker image
  variables:
    CUSTOM_RULES_DIR: $CUSTOM_RULES_DIR    # Set custom rules env var
  script:                                  # List of commands to run 
    - python -m pip install --upgrade pip  # Upgrade pip
    - pip cache purge                      # Clear pip cache
    - pip install .[dev]                   # Install package w/ dev deps
    - |  # Multi-line command to import rules                                        
      FLAGS="-d ${CUSTOM_RULES_DIR}/rules/ --overwrite -e -ac"
      python -m detection_rules kibana --space production import-rules $FLAGS
  environment:
    name: production   # Specify deployment environment as 'production'
  only:
    refs:
      - main           # Run this job only on the 'main' branch
    changes:
      - '**/*.toml'    # Run this job only if .toml files have changed

Isso é muito semelhante a outros recursos integrados de CI/CD de outros sistemas de controle de versão baseados em Git, como GitLab e Gitea. A principal diferença reside na sintaxe que determina o evento desencadeador. Os comandos DaC, como kibana import-rules , seriam os mesmos independentemente do VCS. Neste exemplo, estamos sincronizando regras do nosso fork do repositório detection-rules com o nosso Espaço de Produção do Kibana. Isso se baseia em uma série de decisões anteriores, como, por exemplo, exigir que os testes unitários sejam aprovados antes de mesclar as atualizações de regras e que as regras no servidor principal estejam prontas para produção. Para uma explicação detalhada, baseada no Github, dessas considerações para essa abordagem específica, confira nosso vídeo de demonstração.

Dicas e exemplos de testes unitários personalizados

Ao considerar o DaC como uma funcionalidade a ser adicionada ao seu conjunto de ferramentas de detecção, a configuração da CI/CD e da infraestrutura básica deve ser vista como o primeiro passo em um processo contínuo para melhorar a qualidade e a utilidade de suas regras. Um dos principais objetivos de se ter ferramentas "como código" é adicionar a capacidade de personalizar ainda mais as ferramentas de acordo com suas necessidades e ambiente.

Um exemplo disso é o teste unitário para regras. Além dos testes de funcionalidade básica, alguns outros testes unitários existentes reforçam considerações específicas do Elastic em relação ao desempenho e otimização de regras, bem como à organização de metadados e à marcação. Isso ajuda os engenheiros de detecção e os pesquisadores de ameaças a manterem a consistência no desenvolvimento de suas regras. Com base nesse exemplo, pode-se considerar a adição de testes unitários personalizados de acordo com as necessidades específicas de cada pessoa.

Para ilustrar isso, considere um ambiente de Centro de Operações de Segurança (SOC, na sigla em inglês), onde há diversos analistas responsáveis por diferentes domínios e tarefas. Quando um alerta é gerado no SIEM, pode não ser imediatamente óbvio quem deve lidar com a correção ou qual(is) equipe(s) precisam ser informadas sobre o incidente. Identificar as regras com uma etiqueta de equipe: por exemplo Team: Windows Servers De forma semelhante à maneira como a Elastic usa tags para fontes de dados, pode fornecer ao SOC um ponto de contato diretamente no alerta para quem pode ajudar na remediação.

Em nosso ambiente DaC, podemos criar rapidamente um novo módulo de teste para aplicar isso a todas as regras personalizadas (ou pré-configuradas também). Para este teste, vamos impor a presença da tag Team: <some name> em todas as regras de produção que não foram criadas pela Elastic. No repositório detection-rules, nossos testes são gerenciados por meio do conjunto de testes Python chamado pytest e, como tal, os testes de unidade são organizados em módulos Python (arquivos) e classes e funções subsequentes nesses arquivos na pasta tests/ . Para adicionar testes, basta adicionar classes ou funções aos arquivos existentes ou criar um novo. Em geral, recomendamos a criação de novos arquivos de teste para que você possa receber atualizações dos testes existentes da Elastic sem precisar mesclar as diferenças.

Começaremos criando um novo arquivo Python chamado test_custom_rules.py no diretório tests/ com o seguinte conteúdo:

# test_custom_rules.py

"""Unit Tests for Custom Rules."""

from .base import BaseRuleTest


class TestCustomRules(BaseRuleTest):
    """Test custom rules for given criteria."""

    def test_custom_rule_team_tag(self):
        """Unit test that all custom rules have a Team: <team_name> tag."""
        tag_format = "Team: <team_name>"
        for rule in self.all_rules:
            if "Elastic" not in rule.contents.data.author:
                tags = rule.contents.data.tags
                if tags:
                    self.assertTrue(
                        any(tag.startswith("Team: ") for tag in tags),
                        f"Custom rule {rule.contents.data.rule_id} does not have a {tag_format} tag",
                    )
                else:
                    raise AssertionError(
                        f"Custom rule {rule.contents.data.rule_id} does not have any tags, include a {tag_format} tag"
                    )

Agora, cada regra não elástica deverá ter uma etiqueta no padrão especificado para que a equipe responsável pela correção possa atribuí-la a ela. Exemplo Team: Team A.

Utilização de esquemas personalizados

A capacidade da Elastic de trazer seus próprios tipos de dados também se estende aos nossos recursos de DaC (Data Cloud Application). Por exemplo, vamos dar uma olhada em alguns esquemas personalizados para protocolos de rede. Naturalmente, os diversos dados que você possui em sua infraestrutura podem ser consultados por suas regras, e também é importante aproveitar a validação e os testes aplicáveis a quaisquer regras personalizadas nesses tipos de dados. É aí que os esquemas personalizados se tornam úteis.

Ao validarmos consultas, a consulta é analisada em seus respectivos campos e os tipos desses campos são comparados com o que é fornecido em um determinado esquema (por exemplo, Esquema ECS, integração da AWS para dados da AWS, etc.). Para tipos de dados personalizados, o processo segue o mesmo caminho de validação, com a possibilidade de extrair dados de esquemas personalizados definidos localmente. Esses arquivos de esquema podem ser criados manualmente como um ou mais arquivos JSON; no entanto, se você já tiver alguns dados de exemplo em sua infraestrutura, poderá aproveitá-los e usá-los como validação, gerando seus esquemas automaticamente.

Supondo que você já tenha uma pasta de regras personalizadas configurada (caso contrário, consulte as instruções), você pode ativar a geração automática de esquema adicionando auto_gen_schema_file: <path_to_your_json_file> ao seu arquivo de configuração. Isso irá gerar um arquivo de esquema no local especificado, que será usado para adicionar entradas para cada combinação de campo e índice. O arquivo será atualizado durante qualquer comando em que o conteúdo das regras seja validado em relação a um esquema, incluindo import-rules-to-repo, kibana export-rules, view-rule e outros. Isso também adicionará automaticamente a configuração ao seu arquivo stack-schema-map.yaml ao usar um diretório de regras e uma configuração personalizados.

Com esse poder, vem uma responsabilidade maior para os revisores de regras, já que qualquer campo usado na consulta é imediatamente considerado válido e adicionado ao esquema. Uma forma de mitigar o risco é utilizar um espaço de desenvolvimento que tenha acesso aos dados. Na solicitação de pull request, é possível então incluir um link para uma execução bem-sucedida da consulta com validação em nível de pilha dos seus tipos de dados. Uma vez aprovado, você pode remover a adição auto_gen_schema_file da configuração e agora terá um esquema válido conhecido com base em seus dados personalizados. Isso fornece uma base para que outros autores de regras possam desenvolver a partir dela, conforme necessário, e mantém a validação da verificação de tipo.

Saiba mais sobre DaC e experimente você mesmo

Você pode experimentar em primeira mão a funcionalidade Detections as Code (DaC) da Elastic Security com nosso treinamento interativo em Instruqt. Este treinamento oferece uma maneira simples de explorar os principais recursos do DaC em um ambiente de teste pré-configurado, eliminando a necessidade de configuração manual. Experimente!

Se você estiver implementando o DaC, compartilhe sua experiência, faça perguntas e ajude outras pessoas no canal do DaC no Slack da comunidade.

Teste do Elastic Security

Para experimentar todos os benefícios que a Elastic oferece aos engenheiros de detecção, inicie seu teste gratuito do Elastic Security. Acesse elastic.co/security para saber mais.

O lançamento e o tempo de amadurecimento de todos os recursos ou funcionalidades descritos neste artigo permanecem a exclusivo critério da Elastic. Os recursos ou funcionalidades não disponíveis no momento poderão não ser entregues ou não chegarem no prazo previsto.