Elastic Security 向けの SIEM 検出ルールを開発・検証・公開するためのツール。Python CLI ツール、KQL パース、Kibana 統合、パッケージ化された脅威ハンティングクエリを備えています。
[![Supported Python versions](https://img.shields.io/badge/python-3.12+-yellow.svg)](https://www.python.org/downloads/)
[![Unit Tests](https://github.com/elastic/detection-rules/workflows/Unit%20Tests/badge.svg)](https://github.com/elastic/detection-rules/actions)
[![Chat](https://img.shields.io/badge/chat-%23security--detection--rules-blueviolet)](https://ela.st/slack)
[![ATT&CK navigator coverage](https://img.shields.io/badge/ATT&CK-Navigator-red.svg)](https://ela.st/detection-rules-navigator-trade)

# Detection Rules

Detection Rules は、Elastic Security で使用されるルールの本拠地です。このリポジトリは、Elastic Security の Detection Engine 向けルールの開発、保守、テスト、検証、リリースに使用されます。

このリポジトリは、Elastic のブログ記事 [Elastic Security opens public detection rules repo](https://elastic.co/blog/elastic-security-opens-public-detection-rules-repo) で初めて発表されました。追加のコンテンツについては、併設のウェビナー [Elastic Security: Introducing the public repository for detection rules](https://www.elastic.co/webinars/introducing-the-public-repository-for-detection-rules) を参照してください。


## Table of Contents
- [Detection Rules](#detection-rules)
  - [Table of Contents](#table-of-contents)
  - [Overview of this repository](#overview-of-this-repository)
  - [Getting started](#getting-started)
  - [How to contribute](#how-to-contribute)
  - [Detections as Code (DaC)](#detections-as-code-dac)
  - [RTAs](#rtas)
  - [Licensing](#licensing)
  - [Questions? Problems? Suggestions?](#questions-problems-suggestions)


## Overview of this repository

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

| folder                                          |  description                                                                        |
|------------------------------------------------ |------------------------------------------------------------------------------------ |
| [`detection_rules/`](https://github.com/elastic/detection-rules/blob/main/detection_rules)           | Python module for rule parsing, validating and packaging                            |
| [`etc/`](https://github.com/elastic/detection-rules/blob/main/detection_rules/etc)                   | Miscellaneous files, such as ECS and Beats schemas and configuration files          |
| [`hunting/`](https://github.com/elastic/detection-rules/blob/main/hunting)                        | Root directory where threat hunting package and queries are stored                  |
| [`kibana/`](https://github.com/elastic/detection-rules/blob/main/lib/kibana)                         | Python library for handling the API calls to Kibana and the Detection Engine        |
| [`kql/`](https://github.com/elastic/detection-rules/blob/main/lib/kql)                               | Python library for parsing and validating Kibana Query Language                     |
| [`rules/`](https://github.com/elastic/detection-rules/blob/main/rules)                               | Root directory where rules are stored                                               |
| [`rules_building_block/`](https://github.com/elastic/detection-rules/blob/main/rules_building_block) | Root directory where building block rules are stored                                |
| [`tests/`](https://github.com/elastic/detection-rules/blob/main/tests)                               | Python code for unit testing rules                                                  |


## Getting started

ルールは手動で `.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) を参照してください。

## How to contribute

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) を読んで、検出アイデアを本番ルールに変え、テストで検証する方法を学んでください。

## Detections as Code (DaC)

Detection Rules リポジトリには、「コードとして」の哲学でルールを管理するのに役立つ多数のコマンドが含まれています。戦略と推奨セットアップ情報については、[DaC 固有のドキュメント](https://dac-reference.readthedocs.io/en/latest/) から始めることをお勧めします。すぐに始めたい場合は、カスタムルールでこのリポジトリを設定する方法についてはローカルの [detections as code ドキュメント](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 (RTA) は、専用リポジトリ - [Cortado](https://github.com/elastic/cortado) にあります。


## Licensing

このリポジトリ内のすべて（ルール、コードなど）は、[Elastic License v2](https://github.com/elastic/detection-rules/blob/main/LICENSE.txt) の下でライセンスされています。これらのルールは、Elastic Security アプリケーション内の Detection Engine のコンテキストで使用するように設計されています。[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 のリポジトリにコードを貢献する前に、[Contributor License Agreement](https://www.elastic.co/contributor-agreement) への署名もお願いしています。

## Questions? Problems? Suggestions?

- Detection Engine についてもっと知りたいですか? Kibana の[概要](https://www.elastic.co/guide/en/security/current/detection-engine-overview.html)を確認してください。
- このリポジトリには、まだリリースされていない新規および更新されたルールが含まれています。スタックでリリースされた最新のルールセットについては、[Prebuilt rule reference](https://www.elastic.co/guide/en/security/current/prebuilt-rules-downloadable-updates.html) を参照してください。
- 誤検知やその他の種類のバグを報告する場合は、GitHub の issue を作成し、既存の issue がないか先に確認してください。
- Detection Rules についてサポートが必要ですか? [Security Discuss Forum](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) を参照してください。
ツールをダウンロード
人気

detection-rules
