Detection Rules

Detection Rules est le référentiel des règles utilisées par Elastic Security. Ce dépôt est utilisé pour le développement, la maintenance, les tests, la validation et la publication des règles du moteur de détection d'Elastic Security.

Ce dépôt a été annoncé pour la première fois dans l'article de blog d'Elastic, Elastic Security ouvre un dépôt public de règles de détection. Pour plus de contenu, voir le webinaire qui l'accompagne, Elastic Security : présentation du dépôt public des règles de détection.

Table des matières

Detection Rules

Vue d'ensemble de ce dépôt

Detection Rules ne contient pas uniquement des fichiers de règles statiques. Ce dépôt contient également du code pour construire des pipelines Detections-as-code, pour les tests unitaires en Python et pour l'intégration avec le moteur de détection dans Kibana.

folder	description
`detection_rules/`	Module Python pour l'analyse, la validation et l'empaquetage des règles
`etc/`	Fichiers divers, tels que les schémas ECS et Beats et les fichiers de configuration
`hunting/`	Répertoire racine où sont stockés le package et les requêtes de threat hunting
`kibana/`	Bibliothèque Python pour gérer les appels API vers Kibana et le moteur de détection
`kql/`	Bibliothèque Python pour analyser et valider le Kibana Query Language
`rules/`	Répertoire racine où sont stockées les règles
`rules_building_block/`	Répertoire racine où sont stockées les règles de type building block
`tests/`	Code Python pour les tests unitaires des règles

Pour commencer

Bien que des règles puissent être ajoutées en créant manuellement des fichiers .toml, nous ne le recommandons pas. Ce dépôt contient également un module Python qui facilite la création de règles et les tests unitaires. Si vous disposez de Python 3.12+, exécutez la commande ci-dessous pour installer les dépendances à l'aide du 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 installez les dépendances à l'aide de la commande suivante :

$ 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
...

Remarque : les packages kibana et kql ne sont pas disponibles sur PyPI et doivent être installés depuis le répertoire lib. Le package hunting possède des dépendances optionnelles à installer avec 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

N'oubliez pas d'activer votre environnement virtuel si vous en utilisez un. Si vous avez installé via make, l'environnement virtuel associé est créé dans env/detection-rules-build/. Si vous rencontrez des difficultés avec un environnement Python 3.12, consultez la section correspondante de notre guide de dépannage.

Pour confirmer que tout a été correctement installé, exécutez la commande avec l'option --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.

Remarque :

Si vous utilisez un environnement virtuel, assurez-vous de l'activer avant d'exécuter la commande ci-dessus.
Sous Windows, vous devrez peut-être également exécuter <venv_directory>\Scripts\pywin32_postinstall.py -install selon votre version de Python.

Le guide de contribution explique comment utiliser les commandes create-rule et test pour créer et tester une nouvelle règle lorsque vous contribuez à Detection Rules.

Pour une utilisation plus avancée de l'interface en ligne de commande (CLI), reportez-vous au guide CLI.

Comment contribuer

Nous accueillons volontiers vos contributions à Detection Rules ! Avant de contribuer, veuillez vous familiariser avec ce dépôt, sa structure de répertoires et notre philosophie concernant la création de règles. Lorsque vous êtes prêt à contribuer, lisez le guide de contribution pour apprendre comment nous transformons les idées de détection en règles de production et les validons par des tests.

Detections as Code (DaC)

Le dépôt Detection Rules comprend un certain nombre de commandes pour aider à gérer les règles selon une philosophie « as code ». Nous recommandons de commencer par notre documentation spécifique DaC pour les stratégies et les informations de configuration recommandées. Cependant, si vous préférez vous lancer directement, consultez notre documentation sur les détections as code et notre documentation sur les règles personnalisées pour savoir comment configurer ce dépôt pour une utilisation avec des règles personnalisées, puis notre documentation CLI pour plus d'informations sur nos commandes d'import et d'export de règles.

RTAs

Les Red Team Automations (RTAs) utilisées pour émuler les techniques des attaquants et vérifier les règles se trouvent dans un dépôt dédié - Cortado.

Licence

Tout ce qui se trouve dans ce dépôt — règles, code, etc. — est sous licence Elastic License v2. Ces règles sont conçues pour être utilisées dans le contexte du moteur de détection au sein de l'application Elastic Security. Si vous utilisez notre service géré Elastic Cloud ou la distribution par défaut du logiciel Elastic Stack qui comprend l'ensemble complet des fonctionnalités gratuites, vous obtiendrez les dernières règles dès votre première visite dans le moteur de détection.

Occasionnellement, nous pouvons souhaiter importer des règles d'un autre dépôt qui possèdent déjà une licence, comme MIT ou Apache 2.0. Cela est bienvenu, tant que la licence autorise la sous-licence sous Elastic License v2. Nous conservons ces avis de licence dans NOTICE.txt et accordons une sous-licence sous Elastic License v2 avec toutes les autres règles. Nous exigeons également des contributeurs qu'ils signent un accord de licence de contributeur avant de contribuer du code à tout dépôt Elastic.

Questions ? Problèmes ? Suggestions ?

Vous voulez en savoir plus sur le moteur de détection ? Consultez la vue d'ensemble dans Kibana.
Ce dépôt comprend des règles nouvelles et mises à jour qui n'ont pas encore été publiées. Pour voir les dernières règles publiées avec la stack, consultez la référence des règles préconstruites.
Si vous souhaitez signaler un faux positif ou un autre type de bogue, veuillez créer une issue GitHub et vérifier d'abord s'il en existe déjà une.
Besoin d'aide avec Detection Rules ? Publiez une issue ou posez vos questions sur notre forum Security Discuss ou sur le canal #security-detection-rules de l'espace de travail Slack.
Pour les cas spécifiques à DaC, veuillez consulter notre documentation sur le support et le périmètre pour plus d'informations.

Lire plus

detection-rules dev-v2.1.0

Catégories