Detection Rules

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

Впервые этот репозиторий был анонсирован в блоге Elastic: Elastic Security открывает публичный репозиторий правил обнаружения. Дополнительные материалы см. в сопутствующем вебинаре Elastic Security: представление публичного репозитория правил обнаружения.

Detection Rules

Overview of this repository

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

Getting started

Хотя правила можно добавлять, вручную создавая .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.

Примечание:

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

Руководство по внесению вклада описывает, как использовать команды create-rule и test для создания и тестирования нового правила при внесении вклада в Detection Rules.

Более продвинутое использование интерфейса командной строки (CLI) описано в руководстве по CLI.

How to contribute

Мы приветствуем ваш вклад в Detection Rules! Прежде чем вносить вклад, пожалуйста, ознакомьтесь с этим репозиторием, его структурой каталогов и нашей философией создания правил. Когда будете готовы внести вклад, прочитайте руководство по внесению вклада, чтобы узнать, как мы превращаем идеи обнаружения в готовые правила и проверяем их с помощью тестирования.

Detections as Code (DaC)

Репозиторий Detection Rules включает ряд команд, которые помогают управлять правилами в соответствии с философией «как код». Мы рекомендуем начать с нашей документации, специфичной для DaC, где описаны стратегии и рекомендуемые настройки. Если же вы предпочитаете сразу перейти к делу, обратитесь к нашей локальной документации по detections as code и документации по пользовательским правилам, чтобы узнать, как настроить этот репозиторий для работы с пользовательскими правилами, а затем к документации по CLI для получения информации о командах импорта и экспорта правил.

RTAs

Red Team Automations (RTA), используемые для эмуляции действий атакующих и проверки правил, находятся в отдельном репозитории — Cortado.

Licensing

Всё в этом репозитории — правила, код и т.д. — лицензировано в соответствии с Elastic License v2. Эти правила предназначены для использования в контексте Detection Engine в приложении Elastic Security. Если вы используете наш управляемый сервис Elastic Cloud или стандартный дистрибутив Elastic Stack, включающий полный набор бесплатных функций, вы получите последние правила при первом переходе в механизм обнаружения.

Время от времени мы можем импортировать правила из другого репозитория, у которых уже есть лицензия, например MIT или Apache 2.0. Это приветствуется, если лицензия допускает сублицензирование в соответствии с Elastic License v2. Мы сохраняем такие уведомления о лицензиях в NOTICE.txt и сублицензируем их на условиях Elastic License v2 наравне со всеми остальными правилами. Мы также требуем от участников подписания Соглашения о лицензии на вклад перед внесением кода в любой из репозиториев Elastic.

Questions? Problems? Suggestions?

Хотите узнать больше о Detection Engine? Ознакомьтесь с обзором в Kibana.
Этот репозиторий содержит новые и обновлённые правила, которые ещё не выпущены. Чтобы увидеть последний набор правил, выпущенных вместе со стеком, обратитесь к справочнику предустановленных правил.
Если вы хотите сообщить о ложном срабатывании или другой ошибке, создайте issue на GitHub, предварительно проверив, нет ли уже подобного.
Нужна помощь с Detection Rules? Опубликуйте issue или задайте вопрос на нашем форуме Security Discuss или в канале #security-detection-rules в Slack-рабочем пространстве.
По специфическим вопросам, касающимся DaC, обратитесь к нашей документации по поддержке и области применения для получения дополнительной информации.

`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-код для модульного тестирования правил

detection-rules

Популярное