检测规则

Detection Rules 是 Elastic Security 所用规则的大本营。该仓库用于 Elastic Security 检测引擎（Detection Engine）规则的开发、维护、测试、验证和发布。

该仓库最初在 Elastic 的博客文章中宣布：Elastic Security 开放公共检测规则仓库。更多内容，请参阅随附的网络研讨会：Elastic Security：公共检测规则仓库介绍。

目录

• 检测规则
  • 目录
  • 仓库概述
  • 快速开始
  • 如何贡献
  • 检测即代码 (DaC)
  • RTAs
  • 许可证
  • 疑问？问题？建议？

仓库概述

Detection Rules 不仅仅是静态规则文件的集合。该仓库还包含用于构建检测即代码（Detections-as-Code）流水线、使用 Python 进行单元测试以及与 Kibana 中的检测引擎集成的代码。

folder	description
detection_rules/	用于规则解析、验证和打包的 Python 模块
etc/	杂项文件，例如 ECS 和 Beats 模式以及配置文件
hunting/	存储威胁狩猎包和查询的根目录
kibana/	用于处理对 Kibana 和检测引擎 API 调用的 Python 库
kql/	用于解析和验证 Kibana 查询语言的 Python 库
rules/	存储规则的根目录
rules_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.

注意：

• 如果您使用虚拟环境，请在运行上述命令之前确保已激活它。
• 如果使用 Windows，根据您的 Python 版本，您可能还需要运行 <venv_directory>\Scripts\pywin32_postinstall.py -install。

贡献指南 描述了在向 Detection Rules 贡献时，如何使用 create-rule 和 test 命令来创建和测试新规则。

有关更高级的命令行界面（CLI）用法，请参阅 CLI 指南。

如何贡献

我们欢迎您为 Detection Rules 做出贡献！在贡献之前，请先熟悉本仓库、其目录结构以及我们关于规则创建的理念。当您准备好贡献时，请阅读贡献指南，了解我们如何将检测想法转化为正式规则并通过测试进行验证。

检测即代码 (DaC)