Detection Rules

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

Overview of this repository

Detection Rules には、静的なルールファイルだけが含まれているわけではありません。このリポジトリには、Detections-as-Code パイプラインの構築、Python でのユニットテスト、Kibana の Detection Engine との統合のためのコードも含まれています。

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

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 も実行する必要がある場合があります。

コントリビューションガイドには、Detection Rules に貢献する際に create-rule コマンドと test コマンドを使用して新しいルールを作成・テストする方法が記載されています。

より高度なコマンドラインインターフェース (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 の下でライセンスされています。これらのルールは、Elastic Security アプリケーション内の Detection Engine のコンテキストで使用するように設計されています。Elastic Cloud マネージドサービスまたは全機能セットを含む Elastic Stack ソフトウェアのデフォルトディストリビューションを使用している場合、検出エンジンに最初に移動したときに最新のルールを入手できます。

MIT や Apache 2.0 など、すでにライセンスを持つ別のリポジトリからルールをインポートしたい場合があります。ライセンスが Elastic License v2 でのサブライセンスを許可している限り、これは歓迎されます。これらのライセンス表示は NOTICE.txt に保持し、他のすべてのルールと同様に Elastic License v2 としてサブライセンスします。また、Elastic のリポジトリにコードを貢献する前に、Contributor License Agreement への署名もお願いしています。

Questions? Problems? Suggestions?

Detection Engine についてもっと知りたいですか? Kibana の概要を確認してください。
このリポジトリには、まだリリースされていない新規および更新されたルールが含まれています。スタックでリリースされた最新のルールセットについては、Prebuilt rule reference を参照してください。
誤検知やその他の種類のバグを報告する場合は、GitHub の issue を作成し、既存の issue がないか先に確認してください。
Detection Rules についてサポートが必要ですか? Security Discuss Forum に issue を投稿するか、Slack ワークスペース内の #security-detection-rules チャンネルで質問してください。
DaC 固有のケースについては、サポートとスコープのドキュメントを参照してください。

detection-rules dev-v2.1.0

カテゴリ