Разрабатывайте, проверяйте и публикуйте правила обнаружения SIEM для Elastic Security, с инструментами Python CLI, разбором KQL, интеграцией с Kibana и готовыми запросами для поиска угроз.
Detection Rules — это хранилище правил, используемых Elastic Security. Этот репозиторий используется для разработки, сопровождения, тестирования, проверки и выпуска правил для Detection Engine — механизма обнаружения Elastic Security.
Впервые этот репозиторий был анонсирован в блоге Elastic: Elastic Security открывает публичный репозиторий правил обнаружения. Дополнительные материалы см. в сопутствующем вебинаре Elastic Security: представление публичного репозитория правил обнаружения.
Detection Rules содержит не только статические файлы правил. В этом репозитории также находится код для создания конвейеров Detections-as-Code, модульного тестирования на Python и интеграции с Detection Engine в Kibana.
| folder | description |
|---|---|
detection_rules/ | Python-модуль для разбора, проверки и упаковки правил |
etc/ | Прочие файлы, например схемы ECS и Beats, а также файлы конфигурации |
hunting/ | Корневой каталог, где хранятся пакет и запросы для охоты за угрозами |
kibana/ | Python-библиотека для работы с API-вызовами к Kibana и Detection Engine |
kql/ | Python-библиотека для разбора и проверки Kibana Query Language |
rules/ | Корневой каталог, где хранятся правила |
rules_building_block/ | Корневой каталог, где хранятся building block правила (правила-строительные блоки) |
tests/ | Python-код для модульного тестирования правил |
Хотя правила можно добавлять, вручную создавая .toml-файлы, мы не рекомендуем так делать. Этот репозиторий также содержит Python-модуль, который помогает создавать правила и проводить модульное тестирование. Если у вас установлен Python 3.12+, выполните приведённую ниже команду, чтобы установить зависимости с помощью 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...
...
Или установите зависимости с помощью следующей команды:
$ 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].
# 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, обратитесь к соответствующему разделу в нашем руководстве по устранению неполадок.
Чтобы убедиться, что всё установлено правильно, выполните команду с флагом --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.
Примечание:
<venv_directory>\Scripts\pywin32_postinstall.py -install.Руководство по внесению вклада описывает, как использовать команды create-rule и test для создания и тестирования нового правила при внесении вклада в Detection Rules.
Более продвинутое использование интерфейса командной строки (CLI) описано в руководстве по CLI.
Мы приветствуем ваш вклад в Detection Rules! Прежде чем вносить вклад, пожалуйста, ознакомьтесь с этим репозиторием, его структурой каталогов и нашей философией создания правил. Когда будете готовы внести вклад, прочитайте руководство по внесению вклада, чтобы узнать, как мы превращаем идеи обнаружения в готовые правила и проверяем их с помощью тестирования.
Репозиторий Detection Rules включает ряд команд, которые помогают управлять правилами в соответствии с философией «как код». Мы рекомендуем начать с нашей документации, специфичной для DaC, где описаны стратегии и рекомендуемые настройки. Если же вы предпочитаете сразу перейти к делу, обратитесь к нашей локальной документации по detections as code и документации по пользовательским правилам, чтобы узнать, как настроить этот репозиторий для работы с пользовательскими правилами, а затем к документации по CLI для получения информации о командах импорта и экспорта правил.
Red Team Automations (RTA), используемые для эмуляции действий атакующих и проверки правил, находятся в отдельном репозитории — Cortado.
Всё в этом репозитории — правила, код и т.д. — лицензировано в соответствии с Elastic License v2. Эти правила предназначены для использования в контексте Detection Engine в приложении Elastic Security. Если вы используете наш управляемый сервис Elastic Cloud или стандартный дистрибутив Elastic Stack, включающий полный набор бесплатных функций, вы получите последние правила при первом переходе в механизм обнаружения.
Время от времени мы можем импортировать правила из другого репозитория, у которых уже есть лицензия, например MIT или Apache 2.0. Это приветствуется, если лицензия допускает сублицензирование в соответствии с Elastic License v2. Мы сохраняем такие уведомления о лицензиях в NOTICE.txt и сублицензируем их на условиях Elastic License v2 наравне со всеми остальными правилами. Мы также требуем от участников подписания Соглашения о лицензии на вклад перед внесением кода в любой из репозиториев Elastic.