設定 (Pro)

注: Rules Engine 2.0 は DefectDojo Pro 専用の機能です。

Rules Engine 2.0 は、そのままの状態で動作します。このページの設定は、スループット、保持期間、または送信先ネットワークポリシーを調整する必要があるデプロイメント向けのものです。これらはすべて、他の DefectDojo の設定と同じ方法で適用されます(設定 を参照)。

Rules Engine 2.0 は、従来の Rules Engine とは別に設定されます。両エンジンの間でチューニングは共有されないため、DD_RULES_ENGINE_* の設定は Rules Engine 2.0 に影響を与えず、DD_RULES_V2_* の設定は従来のエンジンに影響を与えません。

DD_RULES_V2_EVENT_BATCH=(int, 500),
DD_RULES_V2_CHUNK_SIZE=(int, 1000),
DD_RULES_V2_STALLED_AFTER_MINUTES=(int, 30),
DD_RULES_V2_RUN_TIME_LIMIT_MINUTES=(int, 360),
DD_RULES_V2_ALLOW_PRIVATE_EGRESS=(bool, False),
DD_RULES_V2_DELIVERY_RETENTION_DAYS=(int, 180),
DD_RULES_V2_RUN_RETENTION_DAYS=(int, 180),
DD_RULES_V2_ENVELOPE_TEXT_MAX_CHARS=(int, 8000),
DD_RULES_V2_MAX_PER_ITEM_SENDS=(int, 1000),

スループット#

イベントごとの Finding 数(DD_RULES_V2_EVENT_BATCH)#

デフォルト: 500。

1つのイベントが保持する Finding id の数です。イベントは非同期の境界を越えるため、軽量なメッセージであり続けられるだけの小ささに保たれています。大きな書き込みは複数のイベントに分散され、それぞれが個別の Run になります。

この値を上げると、より大きく、より少ない数の Run が生成されます。下げると、より小さく、より多くの Run が生成されます。

チャンクごとの Finding 数(DD_RULES_V2_CHUNK_SIZE)#

デフォルト: 1000。

1回の Run が一度にメモリ上に保持する Finding の数です。Run はチャンク単位で処理されるため、これはメモリ調整用の値であり、ルールが処理する対象の上限ではありません。ルールは常に、そのスコープに一致するすべてを処理します。

1つの envelope は Finding あたりおよそ2.7KBであるため、デフォルト値では一度に数メガバイトを保持します。この値を上げるとメモリと引き換えにラウンドトリップの回数が減り、下げるとその逆になります。

Envelope のテキスト上限(DD_RULES_V2_ENVELOPE_TEXT_MAX_CHARS)#

デフォルト: 8000。0に設定すると無効化されます。

item が保持する description、mitigation、impact の文字数です。

この3つのフィールドが envelope のサイズの大部分を占めます。この上限は、非常に大きな description を持つ Finding という例外的なケースのために存在します。そのようなケースでは、1チャンク分がチャンクサイズから想定されるよりもはるかに大きくなってしまいます。この上限は十分に余裕を持って設定されているため、通常のインスタンスで意識されることはありません。

これは conditions と templates から見える内容にも影響することに注意してください。非常に長い description の末尾に対して一致させる条件は、この上限を超えたテキストを見ることができません。

Run のライフタイム#

停止判定までの時間(DD_RULES_V2_STALLED_AFTER_MINUTES)#

デフォルト: 30。

Run が放棄されたものとみなされ、エラーとしてマークされ、ルールごとのロックが解放されるまでに、heartbeat なしで経過してよい時間です。

Run は各チャンクの後に heartbeat を記録するため、この時間は開始時点からではなく、最後の heartbeat からの経過時間として測定されます。これにより、まだ進行中の長い走査がクラッシュしたワーカーと誤認されることはなく、この時間を短く保つことができます。

Run の実行時間の上限(DD_RULES_V2_RUN_TIME_LIMIT_MINUTES)#

デフォルト: 360(6時間)。

ワーカーが Run を強制終了するまでに、1回の Run が取り得る最長時間です。

これは、決して終わらないルールがワーカースロットとそのルールの実行ロックを保持し続けることを防ぐための保護策です。非常に大きなスコープに対するチャンク単位の走査は、このエンジンが想定して作られたワークロードであるため、意図的に余裕を持たせた値になっています。

保持期間#

この機能が肥大化させる3つのテーブルは、2つのジョブによって制限されます。どちらもデフォルトは180日で、どちらも 0 を指定すると削除処理(pruning)を完全に無効化できます。

保持期間は暗黙のままにされず、製品内で明示されます。API は保持期間の長さと、あるレコードが削除される日付の両方を返し、Run や Delivery を表示するページにもその内容が一文で示されます。日付は読み取り時に計算されるため、期間を変更するとすぐに反映され、新しいレコードだけに適用されるわけではありません。

DD_RULES_V2_DELIVERY_RETENTION_DAYS#

デフォルト: 180。

完了した delivery を保持する日数です。

これはこの機能の中で最も速く肥大化するテーブルです。Finding ごとの egress ノードは、Simulate モードを含め、1回の Run につきチャンク分の行を書き込みます。より長い送信監査証跡が必要であれば値を上げ、ボリュームが問題になる場合は値を下げてください。

DD_RULES_V2_RUN_RETENTION_DAYS#

デフォルト: 180。

完了した run を、そのノードごとの行および Finding の来歴(provenance)とともに保持する日数です。

run 側は delivery 側よりも速く肥大化します。これは、provenance が Run ごと・変更ノードごと・Finding ごとに1行生成されるためです。大きなスコープに対して1時間ごとに実行されるルールは、これを大量に生成します。

delivery をまだ保持している run は、それらが削除されるまで保持されます。そのため、run の保持期間を delivery の保持期間より短く設定しても、孤立したレコードが生じることはありません。

送信先の検証#

2つのノード設定は、設定済みのオブジェクトからではなく、自由入力のテキストとして送信先を受け取ります。Call a Webhook の URL と、Send an Email の To です。どちらもルールの保存時に検証されます。

Webhook の URL については、次の通りです。

• http と https のみが受け付けられます。それ以外のスキームは即座に拒否されます。
• URL にはホストが含まれている必要があります。
• デフォルトでは、loopback、link-local、private、reserved、multicast のいずれかのアドレスに解決されるホストは拒否されます。

メールアドレスについては、空のアドレスは拒否され、改行を含むアドレス(ヘッダーインジェクションに該当します)も拒否されます。

このネットワークチェックが存在する理由は、リクエストを送信するワーカーが通常クラスター内部に存在し、ルールの作成者本人よりもはるかに広い範囲の内部ネットワークに到達できてしまうためです。このチェックがなければ、自由入力の URL はリクエストフォージェリのプリミティブになり得ます。メタデータサービスや内部の管理用ポートを指定すれば、その応答が delivery の台帳を通じて返ってきてしまいます。

これは唯一の制御手段ではなく、多層防御の一環です。Rule Edit はいずれにせよ管理者権限に近いものです。それでもこのチェックがある価値はあります。過剰に付与されたロール1つの被害範囲が「任意の内部 HTTP エンドポイントの読み取り」にならないようにするためであり、また、タイプミスが送信時の接続エラーとしてではなく、保存時にわかりやすいメッセージとして失敗するようにするためです。

プライベートアドレスの許可(DD_RULES_V2_ALLOW_PRIVATE_EGRESS)#

デフォルト: オフ。

ネットワークアドレスのチェックを無効化し、Webhook が loopback、link-local、private の各アドレスに投稿できるようにします。スキームと形式の検証は引き続き適用されます。

プライベートアドレス上の何かに対して実際に Webhook を送る必要がある場合はこれを有効にしてください。自己ホスト型のチャットや Webhook レシーバーは、通常これに該当します。

Finding ごとの送信上限#

DD_RULES_V2_MAX_PER_ITEM_SENDS#

デフォルト: 1000。0に設定すると上限を撤廃できます。

1つの egress ノードが1回の Run で記録する、Finding ごとの送信回数の最大値です。

One Message per Finding が有効になっているノードは、Finding ごとに1つの delivery 行と1つのキュー投入タスクを生成します。Run には item 数の上限がないため、非常に広いスコープを持ち、かつ Finding ごとの送信が有効なルールは、この設定がなければ、両方とも無制限になってしまいます。

この上限を超えると、ノードは送信しなかった Finding の件数を示す可視化されたスキップを記録します。Run を失敗させることはなく、また黙って停止することもありません。

関連する設定#

一部の Rules Engine 2.0 ノードは、独自の設定ではなくシステム全体のインテグレーション設定を使用します。

• Send a Slack Message はシステムの Slack トークンを使用し、ノードでチャンネルが指定されていない場合はシステムの Slack チャンネルにフォールバックします。
• Send a Microsoft Teams Message は、システム設定の Microsoft Teams webhook を使用します。
• Create a JIRA Issue は、summary、description、priority について、その製品の JIRA 設定を使用します。
• Raise an In-App Alert は、各受信者自身の Rules Engine Match 通知設定に従います。