Разрабатывайте, проверяйте и публикуйте правила обнаружения SIEM для Elastic Security, с инструментами Python CLI, разбором KQL, интеграцией с Kibana и готовыми запросами для поиска угроз.
[![Supported Python versions](https://img.shields.io/badge/python-3.12+-yellow.svg)](https://www.python.org/downloads/)
[![Unit Tests](https://github.com/elastic/detection-rules/workflows/Unit%20Tests/badge.svg)](https://github.com/elastic/detection-rules/actions)
[![Chat](https://img.shields.io/badge/chat-%23security--detection--rules-blueviolet)](https://ela.st/slack)
[![ATT&CK navigator coverage](https://img.shields.io/badge/ATT&CK-Navigator-red.svg)](https://ela.st/detection-rules-navigator-trade)

# Detection Rules

Detection Rules — это хранилище правил, используемых Elastic Security. Этот репозиторий используется для разработки, сопровождения, тестирования, проверки и выпуска правил для Detection Engine — механизма обнаружения Elastic Security.

Впервые этот репозиторий был анонсирован в блоге Elastic: [Elastic Security открывает публичный репозиторий правил обнаружения](https://elastic.co/blog/elastic-security-opens-public-detection-rules-repo). Дополнительные материалы см. в сопутствующем вебинаре [Elastic Security: представление публичного репозитория правил обнаружения](https://www.elastic.co/webinars/introducing-the-public-repository-for-detection-rules).


## Table of Contents
- [Detection Rules](#detection-rules)
  - [Table of Contents](#table-of-contents)
  - [Overview of this repository](#overview-of-this-repository)
  - [Getting started](#getting-started)
  - [How to contribute](#how-to-contribute)
  - [Detections as Code (DaC)](#detections-as-code-dac)
  - [RTAs](#rtas)
  - [Licensing](#licensing)
  - [Questions? Problems? Suggestions?](#questions-problems-suggestions)


## Overview of this repository

Detection Rules содержит не только статические файлы правил. В этом репозитории также находится код для создания конвейеров Detections-as-Code, модульного тестирования на Python и интеграции с Detection Engine в Kibana.

| folder | description |
|------------------------------------------------ |------------------------------------------------------------------------------------ |
| [`detection_rules/`](https://github.com/elastic/detection-rules/blob/main/detection_rules)           | Python-модуль для разбора, проверки и упаковки правил                            |
| [`etc/`](https://github.com/elastic/detection-rules/blob/main/detection_rules/etc)                   | Прочие файлы, например схемы ECS и Beats, а также файлы конфигурации              |
| [`hunting/`](https://github.com/elastic/detection-rules/blob/main/hunting)                        | Корневой каталог, где хранятся пакет и запросы для охоты за угрозами              |
| [`kibana/`](https://github.com/elastic/detection-rules/blob/main/lib/kibana)                         | Python-библиотека для работы с API-вызовами к Kibana и Detection Engine           |
| [`kql/`](https://github.com/elastic/detection-rules/blob/main/lib/kql)                               | Python-библиотека для разбора и проверки Kibana Query Language                    |
| [`rules/`](https://github.com/elastic/detection-rules/blob/main/rules)                               | Корневой каталог, где хранятся правила                                           |
| [`rules_building_block/`](https://github.com/elastic/detection-rules/blob/main/rules_building_block) | Корневой каталог, где хранятся building block правила (правила-строительные блоки) |
| [`tests/`](https://github.com/elastic/detection-rules/blob/main/tests)                               | Python-код для модульного тестирования правил                                    |


## Getting started

Хотя правила можно добавлять, вручную создавая `.toml`-файлы, мы не рекомендуем так делать. Этот репозиторий также содержит Python-модуль, который помогает создавать правила и проводить модульное тестирование. Если у вас установлен Python 3.12+, выполните приведённую ниже команду, чтобы установить зависимости с помощью makefile:

```console
✗ 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...
...
```


Или установите зависимости с помощью следующей команды:
```console
$ 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
...
```

Примечание: пакеты `kibana` и `kql` недоступны на PyPI и должны устанавливаться из каталога `lib`. Пакет `hunting` имеет опциональные зависимости, которые устанавливаются командой `pip3 install ".[hunting]`.

```console

# 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
```

Не забывайте активировать ваше виртуальное окружение, если вы его используете. При установке через `make` соответствующее виртуальное окружение создаётся в `env/detection-rules-build/`. Если у вас возникли проблемы с использованием окружения Python 3.12, обратитесь к соответствующему разделу в нашем [руководстве по устранению неполадок](https://github.com/elastic/detection-rules/blob/main/Troubleshooting.md).

Чтобы убедиться, что всё установлено правильно, выполните команду с флагом `--help`
```console
$  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.
```

Примечание:
- Если вы используете виртуальное окружение, активируйте его перед выполнением указанной выше команды.
- Если вы используете Windows, в зависимости от версии Python вам также может потребоваться выполнить `<venv_directory>\Scripts\pywin32_postinstall.py -install`.

[Руководство по внесению вклада](https://github.com/elastic/detection-rules/blob/main/CONTRIBUTING.md) описывает, как использовать команды `create-rule` и `test` для создания и тестирования нового правила при внесении вклада в Detection Rules.

Более продвинутое использование интерфейса командной строки (CLI) описано в [руководстве по CLI](https://github.com/elastic/detection-rules/blob/main/CLI.md).

## How to contribute

Мы приветствуем ваш вклад в Detection Rules! Прежде чем вносить вклад, пожалуйста, ознакомьтесь с этим репозиторием, его [структурой каталогов](#overview-of-this-repository) и нашей [философией](https://github.com/elastic/detection-rules/blob/main/PHILOSOPHY.md) создания правил. Когда будете готовы внести вклад, прочитайте [руководство по внесению вклада](https://github.com/elastic/detection-rules/blob/main/CONTRIBUTING.md), чтобы узнать, как мы превращаем идеи обнаружения в готовые правила и проверяем их с помощью тестирования.

## Detections as Code (DaC)

Репозиторий Detection Rules включает ряд команд, которые помогают управлять правилами в соответствии с философией «как код». Мы рекомендуем начать с нашей [документации, специфичной для DaC](https://dac-reference.readthedocs.io/en/latest/), где описаны стратегии и рекомендуемые настройки. Если же вы предпочитаете сразу перейти к делу, обратитесь к нашей локальной [документации по detections as code](https://github.com/elastic/detection-rules/blob/main/docs-dev/detections-as-code.md) и [документации по пользовательским правилам](https://github.com/elastic/detection-rules/blob/main/docs-dev/custom-rules-management.md), чтобы узнать, как настроить этот репозиторий для работы с пользовательскими правилами, а затем к [документации по CLI](https://github.com/elastic/detection-rules/blob/main/CLI.md) для получения информации о командах импорта и экспорта правил.

## RTAs

Red Team Automations (RTA), используемые для эмуляции действий атакующих и проверки правил, находятся в отдельном репозитории — [Cortado](https://github.com/elastic/cortado).


## Licensing

Всё в этом репозитории — правила, код и т.д. — лицензировано в соответствии с [Elastic License v2](https://github.com/elastic/detection-rules/blob/main/LICENSE.txt). Эти правила предназначены для использования в контексте Detection Engine в приложении Elastic Security. Если вы используете наш [управляемый сервис Elastic Cloud](https://www.elastic.co/cloud/) или стандартный дистрибутив Elastic Stack, включающий [полный набор бесплатных функций](https://www.elastic.co/subscriptions), вы получите последние правила при первом переходе в механизм обнаружения.

Время от времени мы можем импортировать правила из другого репозитория, у которых уже есть лицензия, например MIT или Apache 2.0. Это приветствуется, если лицензия допускает сублицензирование в соответствии с Elastic License v2. Мы сохраняем такие уведомления о лицензиях в `NOTICE.txt` и сублицензируем их на условиях Elastic License v2 наравне со всеми остальными правилами. Мы также требуем от участников подписания [Соглашения о лицензии на вклад](https://www.elastic.co/contributor-agreement) перед внесением кода в любой из репозиториев Elastic.

## Questions? Problems? Suggestions?

- Хотите узнать больше о Detection Engine? Ознакомьтесь с [обзором](https://www.elastic.co/guide/en/security/current/detection-engine-overview.html) в Kibana.
- Этот репозиторий содержит новые и обновлённые правила, которые ещё не выпущены. Чтобы увидеть последний набор правил, выпущенных вместе со стеком, обратитесь к [справочнику предустановленных правил](https://www.elastic.co/guide/en/security/current/prebuilt-rules-downloadable-updates.html).
- Если вы хотите сообщить о ложном срабатывании или другой ошибке, создайте issue на GitHub, предварительно проверив, нет ли уже подобного.
- Нужна помощь с Detection Rules? Опубликуйте issue или задайте вопрос на нашем [форуме Security Discuss](https://discuss.elastic.co/c/security/) или в канале **#security-detection-rules** в [Slack-рабочем пространстве](https://www.elastic.co/blog/join-our-elastic-stack-workspace-on-slack).
- По специфическим вопросам, касающимся DaC, обратитесь к нашей [документации по поддержке и области применения](https://github.com/elastic/detection-rules/blob/main/docs-dev/detections-as-code.md#support-and-scope) для получения дополнительной информации.
Скачать инструмент
Популярное

detection-rules
