パーサーリファレンス
プレビュー
Lakewatchは プライベート プレビュー段階です。アクセスをリクエストするには、Databricksアカウントチームにお問い合わせください。
パーサーは、セキュリティ ログ ソースの出力列を記述する YAML ドキュメントです。パーサーはバージョン管理され、Unity Catalogカタログとスキーマに格納されます。パーサーを編集すると不変の新しいバージョンが追加されるため、バージョンをピン留めしているデータソースは、後の編集の影響を受けません。このページでは、Lakewatchが受け入れるパーサー構文について説明します。
ドキュメント構造
description: Product audit events # what this log source is
fields:
- name: event_name
type: STRING
required: true
validate:
in: ['sale', 'buy']
- name: source_ip
type: STRING
observables: [ip]
- name: actor
type: VARIANT
fields:
- name: id
type: STRING
observables: [actor_id]
time:
coalesce:
- path: published
time_formats: ['#rfc3339']
ここで示すように、description を YAML で指定するか、パーサーを作成するときに UI で設定できます（推奨）。
イベント時刻
すべてのパーサーは time 列を生成します。これは、LakewatchクラスターのイベントTimestampです。fieldsのフィールドではなく、トップレベルの time ブロックで定義する必要があります。それがないカスタムパーサーは拒否されます。Lakewatchは常に time 列を生成し、常に TIMESTAMP であるため、その name、type、または required を設定しません。fieldsに time フィールドを追加しないでください。この名前はトップレベルの time ブロックが生成する列用に予約されており、それをフィールドとして宣言するパーサーは拒否されます。
最上位のtimeブロックは、coalesceリストを受け取ります。これはLakewatchが順番に評価するソースの優先順位付きリストで、null以外の最初の値を使用します。すべてのソースがnullの場合、Lakewatchは取り込み時刻にフォールバックし、lw_meta.missing_timestampをtrueに設定します。各ソースは以下のいずれかです。
-
パス : ソースロケーションから値を読み取ります:
YAMLtime:
coalesce:
- path: published
time_formats: ['#rfc3339'] -
正規表現を含むパス : 正規表現を使用してソース場所から値を抽出します。
YAMLtime:
coalesce:
- path: raw_message
regexp: '<pattern>'
match_group_index: 1 # which capture group holds the value; defaults to 1
time_formats: ['#unix']
time_formats TIMESTAMPフィールドと同じ形式セットとパターンを使用します。「Timestamp」を参照してください。
time はフィールドではないため、分類には使用されません。イベントが一致するためにソースイベント時間フィールドが存在することを要求するには、fields の required フィールドとして追加します。
フィールド属性
属性 | 適用対象 | 説明 |
|---|---|---|
| すべてのフィールド | 出力列名。また、 |
| すべてのフィールド | 出力列のタイプ。サポートされているデータ型を参照してください。 |
| すべてのフィールド |
|
| すべてのフィールド |
|
| すべてのフィールド | フィールドの説明。検出ルールの作成に役立つように表示されます。 |
|
| Timestampを解析するための形式のリスト。Timestampを参照してください。 |
|
| 単一のバリデーター。バリデーターを参照してください。 |
|
| 抽出する可観測項目の種別（1つ以上）。「可観測項目」を参照してください。 |
|
| ネストされたコンテンツから観測可能要素を抽出するためのキーマッチングルール。「観測可能要素をスキャンする」を参照してください。 |
|
| 入れ子になったフィールド定義。 |
|
| 配列の要素定義。 |
サポートされている型
STRING、BOOLEAN、TINYINT (BYTE)、SMALLINT (SHORT)、INT (INTEGER)、BIGINT (LONG)、FLOAT (REAL)、DOUBLE、DECIMAL(p,s)、TIMESTAMP、TIMESTAMP_LTZ、TIMESTAMP_NTZ、DATE、BINARY、VARIANT、STRUCT、およびARRAY。
上記のタイプのみがサポートされています。入れ子になったオブジェクトをモデル化するには、内部のfieldsでVARIANTを使用します。VARIANTは、パーサーを破壊することなく、追加の宣言されていないフィールドを許容します。
STRUCT と VARIANT のどちらかを選択する
STRUCT と VARIANT は両方ともネストされたデータをモデル化しますが、正反対のトレードオフを行います。STRUCT は事前に形状を宣言します。メンバーとその型をリストし、パースされた列は宣言した内容を正確に保持します。VARIANT は生で半構造化された値をそのまま保持し、クエリー時にパスによって読み取ります（例：try_variant_get）。VARIANT の下に fields を宣言することもできますが、それはそれらのパスに検証と観測可能性を添付するだけで、値の残りの部分を削除するわけではありません。
形状が分かっていて、安定した型付きコントラクトが必要な場合はSTRUCTを使用します。
- シェイプはパーサーの仕様内に存在するため、バージョン管理およびレビューの対象となります。クエリー、検出、ダッシュボードは各メンバーを既知の型として読み取るため、ソースデータが変更されても壊れません。
- 読み取りのコストは低くなります。
STRUCTは実際の型付きカラムで、ドット表記でアクセスでき、Sparkによってプルーニングされます。一方、VARIANTは読み取りのたびにデコードされます。 - コストは厳格さです。宣言しないものはすべて破棄され、形状が変更されたらパーサーを更新する必要があります。
形状が不明な場合、変化している場合、またはモデルフィールドごとにモデリングするには大きすぎる場合は、 VARIANTを使用します。
- スキーマの変更を自動的に追跡します。AWS CloudTrailやOktaなどのソースは、パーサーを変更せずにフィールドを追加します。
- これは、あるイベントではオブジェクトであり別のイベントでは文字列であるパスなど、混在または競合するシェイプを処理します。これは単一の
STRUCT型では表現できません。 - 後で再処理するために元のペイロードを保持し、データを先に書き込んでから後でモデル化できるようにします。
- 各フィールドを宣言せずに、数百のフィールドを持つペイロードにスケールします。
- コストは、取り込み時に型指定や検証が行われないため、クエリーのたびにフィールドを抽出するコストを支払うことです。一般的なパターンは、クエリーで最も頻繁に使用する少数のフィールドを型付きフィールドに昇格させることです。
Timestamp
TIMESTAMPフィールドは、time_formatsにリストされている形式で解析され、順番に試行され、 parse_timestampが使用されます。各エントリは、定義済みの形式キーワードまたはリテラルSpark日時パターンです。
エントリ | 意味 |
|---|---|
| RFC 3339ファミリ。 |
| 定義済みの他のフォーマットキーワード。 |
| 数値の Unix Timestamp (秒単位)。ミリ秒単位の値が検出されません。 |
| リテラルパターン。 |
解析が過度に許容的にならないように、Logsで実際に使用されている形式を一覧表示します。
バリデーター
バリデーターは、STRING フィールドの条件をアサートします。次のいずれかのみを使用してください：
バリデーター | trueの場合 |
|---|---|
| 値は、リストされた文字列のいずれかです。 |
| 値が一覧表示されている文字列のいずれでもありません。 |
| この値には、リストされている部分文字列が少なくとも1つ含まれています。 |
| 値にリストされている部分文字列が含まれていません。 |
可観測項目
フィールドにobservablesでマークを付けると、その値が脅威ハンティングのために共有lw_observables列に抽出されます。各観測可能なタイプは、特定の種類の値をキャプチャし、lw_observablesの1つ以上のフィールドにデータを入力します。
可観測項目 | キャプチャ | 入力先 |
|---|---|---|
| IPv4またはIPv6アドレス |
|
| ドメイン名 |
|
| ホスト名、または値がIPの場合はIPアドレス |
|
| URLのホスト（ホスト名またはIP） |
|
| MD5、SHA-1、およびSHA-256ハッシュ |
|
| AWS ARN、およびアカウントID、インスタンスID、Eメール、ユーザー名 |
|
| 12桁のAWSアカウントID |
|
| EC2インスタンスID |
|
| リクエスト ID またはトレース ID |
|
| ユーザー名 |
|
| メールアドレスと、そのユーザー名部分 |
|
|
|
|
| MACアドレス |
|
| アクタID |
|
| シリアル番号 |
|
| 次のようなCVE識別子 |
|
| リソースタグ |
|
| MITRE ATT&CK手法ID。例： |
|
lw_observables は、すべての解析済みテーブルに追加され、観測可能なタイプごとに1つのARRAY<STRING>フィールドを持つLakewatch管理のSTRUCT列です。Lakewatchは各フィールドの値を正規化、重複排除、ソートし、無効な値をスキップします。値のないフィールドは[]です。この列は、パーサーが観測可能な項目を宣言しない場合でも、すべてのイベントに存在します。
可観測項目をスキャンする
VARIANTフィールドでオプションのscan_for_observables属性を使用すると、fieldsで宣言されていないコンテンツを含め、ネストされた値のどこにあるキーからでも観測可能を抽出できます。その属性は、他のフィールド タイプでは有効ではありません。
抽出する各観測可能型を明示的なマッチャーオブジェクトにマップします。マッチャーは equals、 ends_with、および contains を使用できます。各キーはキー名文字列の配列を受け入れます。キーのマッチングでは、大文字と小文字は区別されません。
- name: request
type: VARIANT
scan_for_observables:
ip:
equals: [sourceIp, destinationIp]
ends_with: [IpAddress]
contains: [clientIp]
email:
equals: [principalEmail]
ends_with: [Email]
LakewatchはVARIANTの値のキーを再帰的に検証します。キーが構成されたルールと一致すると、Lakewatchはその監視対象タイプの候補値を検証し、有効な値をlw_observablesの対応するフィールドに追加します。一致はパーサーのルールのみを使用します。Lakewatchは組み込みの一致ルールを追加しません。
入れ子フィールドと配列フィールド
ネストされたオブジェクトには fields と共に VARIANT を使用し、リストには element と共に ARRAY を使用します。要素はフィールドのように定義されますが、 name 、 required 、または path はありません：
- name: resources
type: ARRAY
path: resources
element:
type: VARIANT
fields:
- name: accountId
type: STRING
observables: [aws_account_id]
- name: source_ips
type: ARRAY
path: sourceIps
element:
type: STRING
observables: [ip]
分類
データソースには複数のパーサーを添付できます。各着信イベントは、宣言された順序でパーサーと照合され、最初に一致したパーサーに格納されます。イベントは、必要なフィールドが存在し、型指定されたフィールドが宣言された型に変換され、すべてのバリデーターが合格したときに一致します。一致しないイベントは、パイプラインを失敗させるのではなく、デッドレターセンチネルにルーティングされます。
組み込みパーサーおよびカスタムパーサー
Lakewatchは、一般的なセキュリティログソースの 組み込みパーサー を提供しており、カバーされていないソースやカスタマイズしたいソースに対して カスタムパーサー を作成できます。どちらも、前述のYAML形式を使用します。
組み込みパーサーの検出と検査
パーサーをデータソースにアタッチすると、利用可能な組み込みパーサーを参照し、ソースに一致するものを選択できます。組み込みパーサーをアタッチする前に検査して、生成される列（フィールド、型、バリデーター、オブザーバブル）を確認し、取り込むイベントと一致することを確認できます。
組み込みパーサーは読み取り専用です。カスタマイズするには、パーサーの クローン アクションを使用して、組み込みパーサーの定義からシードされた編集可能なカスタムパーサーを作成してから、それを調整して保存します。クローン作成は、定義を新しいカスタムパーサー（バージョン1）にコピーするUI上の便宜機能です。これはサーバーサイドのクローン操作ではなく、組み込みパーサー自体は変更されません。
カスタムパーサーの作成
カスタムパーサーを作成するには、上記の形式でYAMLドキュメントを提供し、それをUnity Catalogのカタログとスキーマに保存します。パーサーを作成すると、定義がバージョン1として保存され、作成者がパーサーの所有者として記録されます。
フィールドを慎重に定義してください。パーサーに一致しないイベントは、パイプラインを失敗させるのではなく、デッドレターセンチネルにルーティングされるためです。値が宣言された型に変換されないイベント、またはバリデーターに失敗したイベントは、パーサーと一致しません。
バージョン管理と削除
パーサーを編集すると、新しい不変バージョンが追加されます。既存のバージョンが変更されることはなく、バージョン番号が再利用されることもありません。サーバーは、新しいバージョンごとにシーケンスの次の番号を割り当てます。パーサーの所有者のみがバージョンを追加できます。
データソースは特定のバージョンをピン留めするため、明示的に変更するまでそのバージョンを使用し続けます。パーサーのバージョンの変更を参照してください。
カスタムパーサー全体を削除すると、そのバージョンがすべて削除されます。個々のバージョンを削除する操作はありません。パーサーを削除できるのは所有者のみです。また、いずれかのデータソースがパーサーのいずれかのバージョンを参照している間は、削除がブロックされます。削除する前に、パーサーを使用しているすべてのデータソースからそのパーサーをデタッチして（各データソースを別のパーサーに変更してその変更を保存する）、パーサーを削除します。
制限事項
パーサー ドキュメントは最大256 KBです。