Detection Rules は、Elastic Security で使用されるルールの本拠地です。このリポジトリは、Elastic Security の Detection Engine 向けルールの開発、保守、テスト、検証、リリースに使用されます。
このリポジトリは、Elastic のブログ記事 Elastic Security opens public detection rules repo で初めて発表されました。追加のコンテンツについては、併設のウェビナー Elastic Security: Introducing the public repository for detection rules を参照してください。
Detection Rules には、静的なルールファイルだけが含まれているわけではありません。このリポジトリには、Detections-as-Code パイプラインの構築、Python でのユニットテスト、Kibana の Detection Engine との統合のためのコードも含まれています。
ルールは手動で .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 も実行する必要がある場合があります。コントリビューションガイド には、Detection Rules に貢献する際に create-rule コマンドと test コマンドを使用して新しいルールを作成・テストする方法が記載されています。
より高度なコマンドラインインターフェース (CLI) の使用方法については、CLI ガイド を参照してください。
Detection Rules への貢献を歓迎します! 貢献する前に、このリポジトリ、そのディレクトリ構造、およびルール作成に関する私たちの哲学をよく理解してください。貢献の準備ができたら、コントリビューションガイド を読んで、検出アイデアを本番ルールに変え、テストで検証する方法を学んでください。
Detection Rules リポジトリには、「コードとして」の哲学でルールを管理するのに役立つ多数のコマンドが含まれています。戦略と推奨セットアップ情報については、DaC 固有のドキュメント から始めることをお勧めします。すぐに始めたい場合は、カスタムルールでこのリポジトリを設定する方法についてはローカルの detections as code ドキュメント と カスタムルールドキュメント を、ルールのインポートおよびエクスポート用コマンドについては CLI ドキュメント を参照してください。
攻撃者のテクニックをエミュレートしてルールを検証するために使用される Red Team Automations (RTA) は、専用リポジトリ - Cortado にあります。
このリポジトリ内のすべて（ルール、コードなど）は、Elastic License v2 の下でライセンスされています。これらのルールは、Elastic Security アプリケーション内の Detection Engine のコンテキストで使用するように設計されています。Elastic Cloud マネージドサービス または全機能セットを含む Elastic Stack ソフトウェアのデフォルトディストリビューションを使用している場合、検出エンジンに最初に移動したときに最新のルールを入手できます。
MIT や Apache 2.0 など、すでにライセンスを持つ別のリポジトリからルールをインポートしたい場合があります。ライセンスが Elastic License v2 でのサブライセンスを許可している限り、これは歓迎されます。これらのライセンス表示は NOTICE.txt に保持し、他のすべてのルールと同様に Elastic License v2 としてサブライセンスします。また、Elastic のリポジトリにコードを貢献する前に、Contributor License Agreement への署名もお願いしています。
| folder | description |
|---|
detection_rules/ | Python module for rule parsing, validating and packaging |
etc/ | Miscellaneous files, such as ECS and Beats schemas and configuration files |
hunting/ | Root directory where threat hunting package and queries are stored |
kibana/ | Python library for handling the API calls to Kibana and the Detection Engine |
kql/ | Python library for parsing and validating Kibana Query Language |
rules/ | Root directory where rules are stored |
rules_building_block/ | Root directory where building block rules are stored |
tests/ | Python code for unit testing rules |