开发、验证并发布适用于 Elastic Security 的 SIEM 检测规则，提供 Python CLI 工具、KQL 解析、Kibana 集成以及打包好的威胁狩猎查询。
[](https://www.python.org/downloads/)
[](https://github.com/elastic/detection-rules/actions)
[](https://ela.st/slack)
[](https://ela.st/detection-rules-navigator-trade)
# 检测规则
Detection Rules 是 Elastic Security 所用规则的大本营。该仓库用于 Elastic Security 检测引擎（Detection Engine）规则的开发、维护、测试、验证和发布。
该仓库最初在 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)。
## 目录
- [检测规则](#detection-rules)
- [目录](#table-of-contents)
- [仓库概述](#overview-of-this-repository)
- [快速开始](#getting-started)
- [如何贡献](#how-to-contribute)
- [检测即代码 (DaC)](#detections-as-code-dac)
- [RTAs](#rtas)
- [许可证](#licensing)
- [疑问？问题？建议？](#questions-problems-suggestions)
## 仓库概述
Detection Rules 不仅仅是静态规则文件的集合。该仓库还包含用于构建检测即代码（Detections-as-Code）流水线、使用 Python 进行单元测试以及与 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) | 用于处理对 Kibana 和检测引擎 API 调用的 Python 库 |
| [`kql/`](https://github.com/elastic/detection-rules/blob/main/lib/kql) | 用于解析和验证 Kibana 查询语言的 Python 库 |
| [`rules/`](https://github.com/elastic/detection-rules/blob/main/rules) | 存储规则的根目录 |
| [`rules_building_block/`](https://github.com/elastic/detection-rules/blob/main/rules_building_block) | 存储构建块规则的根目录 |
| [`tests/`](https://github.com/elastic/detection-rules/blob/main/tests) | 用于规则单元测试的 Python 代码 |
## 快速开始
虽然可以通过手动创建 `.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) 描述了在向 Detection Rules 贡献时，如何使用 `create-rule` 和 `test` 命令来创建和测试新规则。
有关更高级的命令行界面（CLI）用法，请参阅 [CLI 指南](https://github.com/elastic/detection-rules/blob/main/CLI.md)。
## 如何贡献
我们欢迎您为 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)，了解我们如何将检测想法转化为正式规则并通过测试进行验证。
## 检测即代码 (DaC)
Detection Rules 仓库包含许多命令，帮助用户以「即代码」的理念管理规则。我们建议从我们的 [DaC 专项文档](https://dac-reference.readthedocs.io/en/latest/)开始，了解相关策略和推荐设置信息。不过，如果您更想直接上手，可以查看本地的[检测即代码文档](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，RTAs）可在专门的仓库 [Cortado](https://github.com/elastic/cortado) 中找到。
## 许可证
本仓库中的所有内容——规则、代码等——均根据 [Elastic License v2](https://github.com/elastic/detection-rules/blob/main/LICENSE.txt) 获得许可。这些规则设计用于 Elastic Security 应用程序中的检测引擎。如果您使用我们的 [Elastic Cloud 托管服务](https://www.elastic.co/cloud/)或包含[全套免费功能](https://www.elastic.co/subscriptions)的 Elastic Stack 软件默认发行版，您将在首次进入检测引擎时获得最新规则。
偶尔，我们可能需要从其他已包含许可证（如 MIT 或 Apache 2.0）的仓库导入规则。只要许可证允许在 Elastic License v2 下进行再许可，我们都欢迎。我们会将这些许可证声明保存在 `NOTICE.txt` 中，并与其他所有规则一起按 Elastic License v2 进行再许可。我们还要求贡献者在向任何 Elastic 仓库贡献代码之前签署[贡献者许可协议](https://www.elastic.co/contributor-agreement)。
## 疑问？问题？建议？
- 想了解更多关于检测引擎的信息？请查看 Kibana 中的[概述](https://www.elastic.co/guide/en/security/current/detection-engine-overview.html)。
- 本仓库包含尚未发布的新规则和更新规则。要查看随技术栈发布的最新规则集，请参阅[预构建规则参考](https://www.elastic.co/guide/en/security/current/prebuilt-rules-downloadable-updates.html)。
- 如果您想报告误报或其他类型的错误，请先检查是否已有相关 issue，然后创建一个 GitHub issue。
- 需要有关 Detection Rules 的帮助？在我们的[安全讨论论坛](https://discuss.elastic.co/c/security/)发布 issue 或提问，或在 [Slack 工作区](https://www.elastic.co/blog/join-our-elastic-stack-workspace-on-slack)中的 **#security-detection-rules** 频道里提问。
- 对于 DaC 特定场景，请参阅我们的[支持与范围文档](https://github.com/elastic/detection-rules/blob/main/docs-dev/detections-as-code.md#support-and-scope)了解更多信息。