概要

このリポジトリには、Corelight または Zeek のログを Elastic Common Schema (ECS) の命名標準に変換し、Elastic Stack デプロイメントに格納するために必要なものがすべて含まれています。2019年に Elastic Common Schema と同じ年に最初にリリースされたこのリポジトリは、今もなお積極的にメンテナンスされ、更新されています。

200を超えるさまざまなログとメトリクス をサポートしており、すべての環境をサポートしつつ、各固有の環境をサポートするために必要なオプションや望ましいオプションをカスタマイズできるように設計されています。
すべての環境をサポートすることに多大な努力が払われると同時に、各固有かつ個別のデプロイメントに合わせて必要なオプションと望ましいオプションをカスタマイズできるようになっています。

このリポジトリは主に次の2つの要素で構成されています:

1. Elasticsearch インデックステンプレート、コンポーネントテンプレート、ILM ポリシー、設定、マッピング
2. このリポジトリのインストーラースクリプトと、対応する Ingest Pipelines または Logstash Pipelines

ライセンス

ファイルと自動化スクリプトは、BSD ライセンスの下でオープンソースです。詳細は COPYINGを参照してください。

インストール手順

スクリプトを実行する前に、すべてのセクションをお読みください。

1. 要件
2. カスタマイズ
3. インストール
4. インストール後

1. 要件

• このリポジトリの corelight_ecs.py スクリプトを使用すること。ファイル全体にはスクリプトによって置き換えられる数百の変数があるため、テンプレートとパイプラインを手動でインストールすることはサポートされていません。
• Python 3.6 以上
• Elasticsearch バージョン 8.x 以上
• Logstash を使用する場合は、Logstash バージョン 8.x 以上。またはまだ 7.x の場合 は 7.17 以上
• Elasticsearch データストリームのインデックス戦略

2. カスタマイズ

インデックス設定、マッピング、エイリアス、ILM ポリシーのカスタマイズを推奨します。そのため、スクリプトは多くの種類のカスタマイズをサポートできるように設計されています（詳細は下記）。
必要ないカスタマイズも多いですが、ないよりはあった方が良いでしょう。独自のシャード数/レプリカ数と ILM ポリシーを使用することを常にお勧めしますが、それ以外はあまりカスタマイズする必要はないはずです。ただし、すべてのデプロイメントでインデックステンプレート、インジェストパイプライン、Logstash パイプラインの多くの項目を通常どおりカスタマイズしている場合は、その機能を引き続き利用できます。

• カスタムインデックス名
  スクリプトがこれを尋ね、更新が必要なテンプレート、Logstash パイプライン、またはインジェストパイプラインを自動的に更新します。
• インデックス設定
  • シャード数
  • レプリカ数
  • 他のインデックス設定の上書き
  • 設定部分のコンポーネントテンプレートで適切と思われるその他の項目
• インデックスマッピング
  • Elasticsearch インデックスフィールドマッピングの上書き
  • マッピング部分のコンポーネントテンプレートで適切と思われるその他の項目
• ILM ポリシー
  • カスタム ILM ポリシー
• インデックスエイリアス
  • 後方互換性のためや無効化するためのインデックスパターンのエイリアス
• カスタムインジェストパイプライン
  • Corelight のインジェストパイプラインが呼び出される前に、Corelight のインジェストパイプラインを一切変更せずに独自のカスタムインジェストパイプラインを呼び出す機能
  • すべての Corelight のインジェストパイプラインが呼び出された後に、Corelight のインジェストパイプラインを一切変更せずに独自のカスタムインジェストパイプラインを呼び出す機能
• カスタム Logstash パイプラインは、英数字の並び順がより前になるファイルを作成し、同じディレクトリに配置するだけです。

詳細については、以下の各セクションを参照してください。

カスタムインデックスオプション

カスタムインデックス名

データストリームにカスタムのインデックス名/パターンを選択したい場合は、スクリプトが確認を求めます。これにより、独自のインデックス命名規則を選択できます。たとえば、次のように選択できます:

• logs-corelight.conn-default
• ecs-corelight.conn-default
• call_it_what_you_will.conn-default
• logs-corelight.conn-remotesite1

その後、インジェストパイプラインまたは Logstash パイプラインを選択した場合は、必要なすべてのインデックステンプレートも更新されます。 Corelight のログは他のすべてのタイプの ECS データと連携し、logs-* などの Kibana データビュー内から使用できるように設定されているため、デフォルトを変更することはお勧めしません。

マルチテナント環境（MSSP/CSSP や異なるネットワークなど）では、スクリプトのプロンプトでデータストリームの組織部分を選択できるだけでなく（上記の3つの例では default の部分）、filebeat や他の方法で data_stream.namespace を設定するか、パイプラインをフックする場合、パイプラインはその変数がすでに設定されている場合に上書きしないよう尊重するように設定されています。namespace が Elasticsearch がインデックス名として許可する値に設定されていることを確認してください（時々気づきにくい一般的な間違いです）。

使用されるインデックスパターンと各ログのデフォルトは Google Sheet で確認できます。また、各ログの event.category、event.kind などの追加情報も一部記載されています。

カスタムインデックス設定（例: シャードとレプリカ）

各インデックステンプレートは、インデックス設定を上書きするために使用できるコンポーネントテンプレートを呼び出すように指定されています。 したがって、独自のインデックス設定を使用するためにリポジトリのインデックステンプレートを変更する必要はありません。

以下のコンポーネントテンプレートを作成するか、インストール後に変更してください。変更可能なコンポーネントテンプレートの名前は次のとおりです:

すべてのログをカバーする場合（5つのカテゴリに分割）:

• corelight-ecs-component-metric_log-base-settings@custom
• corelight-ecs-component-parse_failures-base-settings@custom
• corelight-ecs-component-protocol_log-base-settings@custom
• corelight-ecs-component-system_log-base-settings@custom
• corelight-ecs-component-unknown_log-base-settings@custom

上記に加えて、より具体的な設定が必要になることが多い個別のログをカバーする場合:

• corelight-ecs-component-protocol_log-conn-base-settings@custom
• corelight-ecs-component-protocol_log-dns-base-settings@custom
• corelight-ecs-component-protocol_log-files-base-settings@custom
• corelight-ecs-component-protocol_log-http-base-settings@custom
• corelight-ecs-component-protocol_log-smb-base-settings@custom
• corelight-ecs-component-protocol_log-smtp-base-settings@custom
• corelight-ecs-component-protocol_log-ssl-base-settings@custom
• corelight-ecs-component-protocol_log-suricata_corelight-base-settings@custom
• corelight-ecs-component-protocol_log-syslog-base-settings@custom
• corelight-ecs-component-protocol_log-various-base-settings@custom

インデックスマッピング（例: フィールド）のカスタマイズ

各インデックステンプレートは、フィールドタイプやフィールド名などのインデックスマッピングを上書きするために使用できるコンポーネントテンプレートを呼び出すように指定されています。 したがって、独自のインデックスマッピングを使用するためにリポジトリのインデックステンプレートを変更する必要はありません。

以下のコンポーネントテンプレートを作成するか、インストール後に変更してください。変更可能なコンポーネントテンプレートの名前は次のとおりです:

すべてのログをカバーする場合（5つのカテゴリに分割）:

• corelight-ecs-component-metric_log-mappings@custom
• corelight-ecs-component-parse_failures-mappings@custom
• corelight-ecs-component-protocol_log-mappings@custom
• corelight-ecs-component-system_log-mappings@custom
• corelight-ecs-component-unknown_log-mappings@custom

上記に加えて、より具体的な設定が必要になることが多い個別のログをカバーする場合:

• corelight-ecs-component-protocol_log-conn-mappings@custom
• corelight-ecs-component-protocol_log-dns-mappings@custom
• corelight-ecs-component-protocol_log-files-mappings@custom
• corelight-ecs-component-protocol_log-http-mappings@custom
• corelight-ecs-component-protocol_log-smb-mappings@custom
• corelight-ecs-component-protocol_log-smtp-mappings@custom
• corelight-ecs-component-protocol_log-ssl-mappings@custom
• corelight-ecs-component-protocol_log-suricata_corelight-mappings@custom
• corelight-ecs-component-protocol_log-syslog-mappings@custom
• corelight-ecs-component-protocol_log-various-mappings@custom

カスタム ILM ポリシー戦略

各インデックステンプレートは、独自の保持期間を設定するために ILM ポリシーを上書きできるコンポーネントテンプレートを呼び出すように指定されています。 したがって、独自の ILM ポリシーを使用するためにリポジトリのインデックステンプレートを変更する必要はありません。

以下のコンポーネントテンプレートを作成するか、インストール後に変更してください。変更可能なコンポーネントテンプレートの名前は次のとおりです:

すべてのログをカバーする場合（5つのカテゴリに分割）:

• corelight-ecs-component-metric_log-ilm-settings@custom
• corelight-ecs-component-parse_failures-ilm-settings@custom
• corelight-ecs-component-protocol_log-ilm-settings@custom
• corelight-ecs-component-system_log-ilm-settings@custom
• corelight-ecs-component-unknown_log-ilm-settings@custom

これらは、上記に加えて、より具体的な設定が必要になることが多い個別のログをカバーします:

• corelight-ecs-component-protocol_log-conn-ilm-settings@custom
• corelight-ecs-component-protocol_log-dns-ilm-settings@custom
• corelight-ecs-component-protocol_log-files-ilm-settings@custom
• corelight-ecs-component-protocol_log-http-ilm-settings@custom
• corelight-ecs-component-protocol_log-smb-ilm-settings@custom
• corelight-ecs-component-protocol_log-smtp-ilm-settings@custom
• corelight-ecs-component-protocol_log-ssl-ilm-settings@custom
• corelight-ecs-component-protocol_log-suricata_corelight-ilm-settings@custom
• corelight-ecs-component-protocol_log-syslog-ilm-settings@custom
• corelight-ecs-component-protocol_log-various-ilm-settings@custom

カスタムインデックスエイリアス

各インデックステンプレートは、インデックスエイリアスを上書きするために使用できるコンポーネントテンプレートを呼び出すように指定されています。 したがって、独自のインデックスエイリアスを使用するためにリポジトリのインデックステンプレートを変更する必要はありません。

以下のコンポーネントテンプレートを作成するか、インストール後に変更してください。変更可能なコンポーネントテンプレートの名前は次のとおりです:

すべてのログをカバーする場合（5つのカテゴリに分割）:

• corelight-ecs-component-metric_log-aliases@custom
• corelight-ecs-component-parse_failures-aliases@custom
• corelight-ecs-component-protocol_log-aliases@custom
• corelight-ecs-component-system_log-aliases@custom
• corelight-ecs-component-unknown_log-aliases@custom

これらは、上記に加えて、より具体的な設定が必要になることが多い個別のログをカバーします:

• corelight-ecs-component-protocol_log-conn-aliases@custom
• corelight-ecs-component-protocol_log-dns-aliases@custom
• corelight-ecs-component-protocol_log-files-aliases@custom
• corelight-ecs-component-protocol_log-http-aliases@custom
• corelight-ecs-component-protocol_log-smb-aliases@custom
• corelight-ecs-component-protocol_log-smtp-aliases@custom
• corelight-ecs-component-protocol_log-ssl-aliases@custom
• corelight-ecs-component-protocol_log-suricata_corelight-aliases@custom
• corelight-ecs-component-protocol_log-syslog-aliases@custom
• corelight-ecs-component-protocol_log-various-aliases@custom

カスタムインジェストパイプライン

カスタム冒頭インジェストパイプラインのキャッチオール

インジェストパイプラインの先頭で、Corelight のパイプラインが呼び出される前に、corelight-ecs-main-pipeline@custom という名前のインジェストパイプラインを使用する機能があります。 Corelight のパイプラインが呼び出される前に行いたい処理がある場合は、その名前でインジェストパイプラインを作成できます。 パイプラインを作成しない場合、この関数はそれを静かにスキップするため、任意です。

カスタム最終インジェストパイプラインのキャッチオール

インジェストパイプラインの末尾で、すべての Corelight パイプラインが呼び出された後に、corelight-ecs-postprocess-final-main-pipeline@custom という名前のインジェストパイプラインを使用する機能があります。 Corelight のパイプラインが呼び出される前に行いたい処理がある場合は、その名前でインジェストパイプラインを作成できます。 パイプラインを作成しない場合、この関数はそれを静かにスキップするため、任意です。

カスタム冒頭インジェストパイプラインのパース失敗キャッチオール

インジェストパイプラインの on_failure キャッチオール（インジェストパイプライン障害時）の先頭で、Corelight のパイプラインが呼び出される前に、corelight-ecs-parse_failures-pipeline@custom という名前のインジェストパイプラインを使用する機能があります。 Corelight のパイプラインが呼び出される前に行いたい処理がある場合は、その名前でインジェストパイプラインを作成できます。 パイプラインを作成しない場合、この関数はそれを静かにスキップするため、任意です。

カスタム最終インジェストパイプラインのパース失敗キャッチオール

インジェストパイプラインの末尾で、すべての Corelight パイプラインが呼び出された後に、corelight-ecs-postprocess-final-main-pipeline@custom という名前のインジェストパイプラインを使用する機能があります。 Corelight のパイプラインが呼び出される前に行いたい処理がある場合は、その名前でインジェストパイプラインを作成できます。 パイプラインを作成しない場合、この関数はそれを静かにスキップするため、任意です。

3. インストール

スクリプトの使用方法

git clone https://github.com/corelight/ecs-templates
cd ecs-templates
python3 corelight_ecs.py

スクリプト引数

• --no-color: ログの色を無効にします。
• --debug: デバッグレベルのログを有効にします。
• --es-default-timeout=10: elasticsearch への接続を待機するデフォルトのタイムアウトを変更します。
• --es-default-retry=2: elasticsearch への接続を再試行するデフォルトの回数を変更します。
• --git-repository=corelight: elasticsearch への接続を再試行するデフォルトの回数を変更します。
• --git-branch=main: elasticsearch への接続を再試行するデフォルトの回数を変更します。

4. インストール後

Logstash

一部の値は、お使いの環境に合わせてインストール後に変更が必要な場合があります。これには、elasticsearch 接続用のカスタム認証局、Kafka の各種トピックなどが含まれます。 elasticsearch 出力には 20 を超えるオプションがあり、5 つの異なる入力には 60 を超えるオプションがあるため、インストーラーはそれらすべてを提供、プロンプト表示、検証することはありません。 ただし、サポートとして、スクリプトはどのファイルを変更すべきかを指示します。 また、あらゆるものを完全自動化するユーザーのために、サンプルスクリプト が用意されており、インストール後にファイル内の値を変更し、同時に使用される変数の行のコメントを解除するプロセスを自動化できることを示しています。

テンプレートのカスタマイズ

詳細については、カスタマイズ セクションを参照してください。

Corelight センサー設定 - Elastic Exporter

• Corelight アプライアンスやテストなどのために、インジェストパイプラインに到達するためだけのインデックスパターンを使用するには、プレフィックスを temporary_corelight_routing_index に設定します。
• システムインデックスを無効にする
• データストリームを有効にする - バージョンに応じて、エクスポーターのチェックボックスか、詳細設定で bro.export.elasticsearch.use_data_streams を有効にできます。

変更履歴 WIP

リポジトリの完全な変更履歴については、changelog.md ファイルを参照してください。

やることリスト WIP

リポジトリのやることの完全なリストについては、todo.md ファイルを参照してください。

バージョニング

このリポジトリのバージョニングは、サポートしている Elastic Common Schema (ECS) のバージョンに基づいています。 各ログに次のフィールドが追加されます:

• labels.corelight.ecs_version
• labels.corelight.ecs_method
• labels.corelight.ecs_method_version

GitHub リポジトリ定義

Elasticsearch テンプレート（このリポジトリ）

https://github.com/corelight/ecs-templates

• Elasticsearch インデックステンプレート、コンポーネントテンプレート、ILM ポリシー、設定、マッピング
• インストールスクリプト

Logstash パイプライン

https://github.com/corelight/ecs-logstash-mappings

• Logstash パイプライン設定

インジェストパイプライン

https://github.com/corelight/ecs-mapping

• インジェストパイプライン設定

Kibana ダッシュボードとビジュアライゼーション

https://github.com/corelight/ecs-dashboards

Kibana セキュリティルールとアラート

https://github.com/corelight/Elasticsearch_rules