elastic/detection-rulesDesarrolla, valida y publica reglas de detección SIEM para Elastic Security, con herramientas CLI de Python, parseo de KQL, integración con Kibana y consultas de threat hunting empaquetadas.
Detection Rules es el hogar de las reglas utilizadas por Elastic Security. Este repositorio se utiliza para el desarrollo, mantenimiento, pruebas, validación y publicación de reglas para el Motor de Detección de Elastic Security.
Este repositorio se anunció por primera vez en la publicación del blog de Elastic, Elastic Security abre un repositorio público de reglas de detección. Para contenido adicional, consulte el seminario web que lo acompaña, Elastic Security: Presentación del repositorio público de reglas de detección.
Detection Rules contiene más que simples archivos de reglas estáticas. Este repositorio también contiene código para crear canalizaciones de detección como código, pruebas unitarias en Python e integración con el Motor de Detección en Kibana.
Aunque las reglas se pueden agregar creando manualmente archivos .toml, no lo recomendamos. Este repositorio también consta de un módulo de Python que ayuda en la creación de reglas y las pruebas unitarias. Suponiendo que tenga Python 3.12+, ejecute el siguiente comando para instalar las dependencias usando el 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...
...
O instale las dependencias usando el siguiente 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
...
Nota: Los paquetes kibana y kql no están disponibles en PyPI y deben instalarse desde el directorio lib. El paquete hunting tiene dependencias opcionales que se instalan con pip3 install ".[hunting].
# Install from the repository
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
# Or locally for development
pip3 install lib/kibana lib/kql
Recuerde asegurarse de activar su entorno virtual si está usando uno. Si instaló mediante make, el entorno virtual asociado se crea en env/detection-rules-build/. Si tiene problemas con un entorno Python 3.12, consulte la sección correspondiente en nuestra guía de solución de problemas.
Para confirmar que todo se instaló correctamente, ejecute con la opción --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.
Nota:
<venv_directory>\Scripts\pywin32_postinstall.py -install según su versión de Python.La guía de contribución describe cómo usar los comandos create-rule y test para crear y probar una nueva regla al contribuir a Detection Rules.
Para un uso más avanzado de la interfaz de línea de comandos (CLI), consulte la guía de CLI.
¡Damos la bienvenida a tus contribuciones a Detection Rules! Antes de contribuir, familiarízate con este repositorio, su estructura de directorios y nuestra filosofía sobre la creación de reglas. Cuando estés listo para contribuir, lee la guía de contribución para aprender cómo convertimos las ideas de detección en reglas de producción y las validamos con pruebas.
El repositorio Detection Rules incluye una serie de comandos para ayudar a gestionar reglas con una filosofía «como código». Recomendamos comenzar con nuestra documentación específica de DaC para conocer las estrategias y la configuración recomendada. Sin embargo, si prefieres ir directamente al grano, consulta nuestra documentación local de detecciones como código y la documentación de reglas personalizadas para obtener información sobre cómo configurar este repositorio para usarlo con reglas personalizadas, y luego nuestra documentación de CLI para obtener información sobre los comandos para importar y exportar reglas.
Las automatizaciones de Red Team (RTA) utilizadas para emular técnicas de atacantes y verificar las reglas se pueden encontrar en el repositorio dedicado: Cortado.
Todo en este repositorio (reglas, código, etc.) está licenciado bajo la Licencia Elastic v2. Estas reglas están diseñadas para usarse en el contexto del Motor de Detección dentro de la aplicación Elastic Security. Si usas nuestro servicio gestionado Elastic Cloud o la distribución predeterminada del software Elastic Stack que incluye el conjunto completo de funciones gratuitas, obtendrás las últimas reglas la primera vez que navegues al motor de detección.
Ocasionalmente, es posible que queramos importar reglas de otro repositorio que ya tengan una licencia, como MIT o Apache 2.0. Esto es bienvenido, siempre que la licencia permita la sublicencia bajo la Licencia Elastic v2. Mantenemos esos avisos de licencia en NOTICE.txt y sublicenciamos bajo la Licencia Elastic v2 junto con todas las demás reglas. También exigimos a los contribuyentes que firmen un Acuerdo de Licencia de Contribuyente antes de contribuir con código a cualquier repositorio de Elastic.
| folder | description |
|---|
detection_rules/ | Módulo de Python para el análisis, validación y empaquetado de reglas |
etc/ | Archivos diversos, como esquemas de ECS y Beats, y archivos de configuración |
hunting/ | Directorio raíz donde se almacenan el paquete y las consultas de caza de amenazas |
kibana/ | Biblioteca de Python para manejar las llamadas API a Kibana y al Motor de Detección |
kql/ | Biblioteca de Python para analizar y validar el Lenguaje de Consulta de Kibana |
rules/ | Directorio raíz donde se almacenan las reglas |
rules_building_block/ | Directorio raíz donde se almacenan las reglas de bloques de construcción |
tests/ | Código de Python para pruebas unitarias de reglas |