elastic/detection-rulesDesenvolva, valide e publique regras de detecção SIEM para o Elastic Security, com ferramentas de CLI em Python, análise de KQL, integração com Kibana e consultas de threat hunting empacotadas.
Detection Rules é o lar das regras usadas pelo Elastic Security. Este repositório é usado para o desenvolvimento, manutenção, testes, validação e lançamento de regras para o Detection Engine do Elastic Security.
Este repositório foi anunciado pela primeira vez no blog da Elastic, Elastic Security abre repositório público de regras de detecção. Para conteúdo adicional, consulte o webinar complementar, Elastic Security: apresentando o repositório público para regras de detecção.
Detection Rules contém mais do que apenas arquivos de regras estáticos. Este repositório também contém código para construir pipelines de detecções como código, testes unitários em Python e integração com o Detection Engine no Kibana.
Embora as regras possam ser adicionadas criando manualmente arquivos .toml, não recomendamos isso. Este repositório também consiste em um módulo Python que auxilia na criação de regras e nos testes unitários. Supondo que você tenha Python 3.12+, execute o comando abaixo para instalar as dependências usando o makefile:
✗ make
python3.12 -m pip install --upgrade pip setuptools
Looking in indexes: https://pypi.org/simple
Requirement already satisfied: pip in /opt/homebrew/lib/python3.12/site-packages (24.0)
Requirement already satisfied: setuptools in /opt/homebrew/lib/python3.12/site-packages (69.1.1)
python3.12 -m venv ./env/detection-rules-build
./env/detection-rules-build/bin/pip install --upgrade pip setuptools
Looking in indexes: https://pypi.org/simple
Requirement already satisfied: pip in ./env/detection-rules-build/lib/python3.12/site-packages (24.0)
Collecting setuptools
Using cached setuptools-69.1.1-py3-none-any.whl.metadata (6.2 kB)
Using cached setuptools-69.1.1-py3-none-any.whl (819 kB)
Installing collected packages: setuptools
Successfully installed setuptools-69.1.1
Installing kql and kibana packages...
...
Ou instale as dependências usando o seguinte comando:
$ pip3 install ".[dev]"
Collecting jsl==0.2.4
Downloading jsl-0.2.4.tar.gz (21 kB)
Collecting jsonschema==3.2.0
Downloading jsonschema-3.2.0-py2.py3-none-any.whl (56 kB)
|████████████████████████████████| 56 kB 318 kB/s
Collecting requests==2.22.0
Downloading requests-2.22.0-py2.py3-none-any.whl (57 kB)
|████████████████████████████████| 57 kB 1.2 MB/s
Collecting Click==7.0
Downloading Click-7.0-py2.py3-none-any.whl (81 kB)
|████████████████████████████████| 81 kB 2.6 MB/s
...
Observação: os pacotes kibana e kql não estão disponíveis no PyPI e devem ser instalados a partir do diretório lib. O pacote hunting tem dependências opcionais a serem instaladas com pip3 install ".[hunting]".
# Instale a partir do repositório
pip3 install git+https://github.com/elastic/detection-rules.git#subdirectory=lib/kibana
pip3 install git+https://github.com/elastic/detection-rules.git#subdirectory=lib/kql
# Ou localmente para desenvolvimento
pip3 install lib/kibana lib/kql
Lembre-se de ativar seu ambiente virtual, se estiver usando um. Se instalado via make, o ambiente virtual associado é criado em env/detection-rules-build/.
Se você estiver tendo problemas com um ambiente Python 3.12, consulte a seção relevante no nosso guia de solução de problemas.
Para confirmar se tudo foi instalado corretamente, execute com a flag --help
$ python -m detection_rules --help
Usage: detection_rules [OPTIONS] COMMAND [ARGS]...
Commands for detection-rules repository.
Options:
-D, --debug / -N, --no-debug Print full exception stacktrace on errors
-h, --help Show this message and exit.
Commands:
build-limited-rules Import rules from json, toml, or Kibana exported rule file(s), filter out unsupported ones, and write to output NDJSON file.
build-threat-map-entry Build a threat map entry.
create-rule Create a detection rule.
custom-rules Commands for supporting custom rules.
dev Commands related to the Elastic Stack rules release lifecycle.
es Commands for integrating with Elasticsearch.
export-rules-from-repo Export rule(s) and exception(s) into an importable ndjson file.
generate-rules-index Generate enriched indexes of rules, based on a KQL search, for indexing/importing into elasticsearch/kibana.
import-rules-to-repo Import rules from json, toml, or yaml files containing Kibana exported rule(s).
kibana Commands for integrating with Kibana.
mass-update Update multiple rules based on eql results.
normalize-data Normalize Elasticsearch data timestamps and sort.
rule-search Use KQL or EQL to find matching rules.
test Run unit tests over all of the rules.
toml-lint Cleanup files with some simple toml formatting.
typosquat Commands for generating typosquat detections.
validate-all Check if all rules validates against a schema.
validate-rule Check if a rule staged in rules dir validates against a schema.
view-rule View an internal rule or specified rule file.
Observação:
<venv_directory>\Scripts\pywin32_postinstall.py -install, dependendo da sua versão do Python.O guia de contribuição descreve como usar os comandos create-rule e test para criar e testar uma nova regra ao contribuir para o Detection Rules.
Para uso mais avançado da interface de linha de comando (CLI), consulte o guia de CLI.
Aceitamos suas contribuições para o Detection Rules! Antes de contribuir, familiarize-se com este repositório, sua estrutura de diretórios e nossa filosofia sobre a criação de regras. Quando estiver pronto para contribuir, leia o guia de contribuição para aprender como transformamos ideias de detecção em regras de produção e validamos com testes.
O repositório Detection Rules inclui uma série de comandos para ajudar a gerenciar regras com uma filosofia "as code" (como código). Recomendamos começar pela nossa documentação específica sobre DaC para estratégias e informações de configuração recomendadas. No entanto, se preferir ir direto ao ponto, consulte nossa documentação local sobre detecções como código e a documentação sobre gerenciamento de regras personalizadas para obter informações sobre como configurar este repositório para uso com regras personalizadas, seguido pela nossa documentação de CLI para obter informações sobre nossos comandos de importação e exportação de regras.
As automações de Red Team (RTAs), usadas para emular técnicas de atacantes e verificar as regras, podem ser encontradas no repositório dedicado - Cortado.
Tudo neste repositório — regras, código, etc. — está licenciado sob a Elastic License v2. Essas regras foram projetadas para serem usadas no contexto do Detection Engine dentro do aplicativo Elastic Security. Se você estiver usando nosso serviço gerenciado Elastic Cloud ou a distribuição padrão do software Elastic Stack que inclui o conjunto completo de recursos gratuitos, você receberá as regras mais recentes na primeira vez em que navegar até o detection engine.
Ocasionalmente, podemos querer importar regras de outro repositório que já possuam uma licença, como MIT ou Apache 2.0. Isso é bem-vindo, desde que a licença permita a sublicença sob a Elastic License v2. Mantemos esses avisos de licença em NOTICE.txt e sublicenciamos sob a Elastic License v2 com todas as outras regras. Também exigimos que os contribuidores assinem um Contrato de Licença de Contribuidor antes de contribuir com código para qualquer repositório da Elastic.
| pasta | descrição |
|---|
detection_rules/ | Módulo Python para análise, validação e empacotamento de regras |
etc/ | Arquivos diversos, como esquemas e arquivos de configuração do ECS e Beats |
hunting/ | Diretório raiz onde o pacote e as consultas de threat hunting são armazenados |
kibana/ | Biblioteca Python para lidar com chamadas de API para o Kibana e o Detection Engine |
kql/ | Biblioteca Python para analisar e validar a Kibana Query Language |
rules/ | Diretório raiz onde as regras são armazenadas |
rules_building_block/ | Diretório raiz onde as regras de building block são armazenadas |
tests/ | Código Python para testes unitários das regras |