Rules Engine 2.0 について (Pro)

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

Rules Engine 2.0 は、ビジュアルな自動化ビルダーです。フィルターとフラットなアクションのリストの代わりに、ルールはグラフとして構成されます。グラフは、ルールがいつ起動するかを決めるトリガーノードと、その後の処理内容を指定する任意の数のロジックノード、Finding ノード、Egress ノードが配線されたものです。

Rules Engine 2.0 には Pro UI からのみアクセスできます。

Rules Engine と比べて追加されるもの#

従来の Rules Engine は、1つのフィルターに一致するすべての Finding に対して、順序付けられたアクションのリストを適用します。Rules Engine 2.0 はこの機能を維持しつつ、次の4つを追加します。

• 分岐。 If / Filter ノードは、項目を true 分岐と false 分岐に振り分けます。これにより、1つのルールを2つに分割することなく、Critical の Finding をそれ以外と異なる方法で扱うことができます。
• Egress。 ルールは DefectDojo の外部にアクションを送信できます。JIRA の課題やダウンストリームのチケットの起票、Slack や Microsoft Teams への投稿、メールの送信、Webhook の呼び出し、アプリ内アラートの発生、レポートの生成などが可能です。
• トレーサビリティ。 すべての実行はノードごとに Run として記録され、すべての送信は Delivery として記録されます。Delivery には、何が送信され、どこへ送られ、どのように終了したかが正確に記録されます。
• Simulate モード。 ルールは、実際には何も送信せずに、送信するはずだった内容を正確に記録できます。これにより、外部に影響を与える前にルールを安全にテストできます。

両方のエンジンは並行して動作します。Rules Engine 2.0 を有効にしても、既存のルールが無効化されたり変換されたりすることはありません。ルールを移行したい場合のために converter が用意されています。

Rules Engine 2.0 の有効化#

Rules Engine 2.0 はベータ版であり、デフォルトでは無効になっています。スーパーユーザーが、Cloud インスタンス・On-Premise インスタンスの両方で Settings > Feature Flags から有効化します。Feature Flags を参照してください。

フラグが有効になると、サイドバーに Rules Engine 2.0 セクションが表示され、次の3つのページが含まれます。

アクセス権限#

アクセスは、従来の Rules Engine と共有される2つのグローバルロール権限によって制御されます。

• サイドバーのセクションおよびその配下のすべてを閲覧するには Rule View が必要です。
• 作成、変更、実行、削除、変換、所有権の取得、リプレイを行うには Rule Edit が必要です。

Rule Edit は管理者権限に近いものです。ルールの作成者は、そのルールの所有者が閲覧できる任意の Finding にアクセスでき、また出力を外部システムに向けることができるため、慎重に付与してください。

概念#

ルールとグラフ#

ルールは、名前、説明、所有者、モード、有効/無効の切り替え、そしてグラフから構成されます。グラフはノードとその間のエッジの集合です。トリガーノードをちょうど1つ含む必要があり、循環を含んではいけません。それ以外はすべて自由です。ノードを何にも接続しないままにしておくこともでき、その場合はそのノードは処理対象が何もない状態で実行されるだけです。

新しいルールは常に無効な状態で作成されるため、ルールを有効にすることは意図的な操作になります。

Item#

グラフのエッジに沿って流れるのはitemです。これは、1つの Finding とその周辺コンテキストの JSON スナップショットです。

{
  "finding":      { "id": 1234, "title": "...", "severity": "High", "...": "..." },
  "test":         { "id": 12, "title": "...", "scan_type": "..." },
  "engagement":   { "id": 5,  "name": "..." },
  "product":      { "id": 3,  "name": "..." },
  "product_type": { "id": 1,  "name": "..." },
  "ctx":          { "trigger": "finding.created", "depth": 0, "source": "app" }
}

条件やメッセージテンプレートは、この構造内のパス、例えば finding.severity や product.name に対して記述します。全フィールドの一覧は Building Rules にあります。

所有者#

すべてのルールは所有者として実行されます。ルールは、その所有者が閲覧できる Finding だけを、製品の他の箇所と同じ認可の仕組みを通じて見ます。ここから生じる2つの帰結を知っておく価値があります。

• ルール所有者のアクセス権を制限すると、ルールも制限されます。
• ルールの所有者アカウントが削除されると、そのルールには所有者がいなくなり、何にも一致せず何も実行しなくなります。新しい所有者を割り当てるか、ルール一覧から Take Ownership を使うことで復旧できます。

モード: Simulate または Live#

モードはノードごとではなく、ルールごとに設定します。

• Simulate(デフォルト)は、あらゆる Finding の編集を含め、グラフ全体を実際に実行しますが、Egress ノードは送信するはずだった内容を記録するだけで、そこで止まります。DefectDojo の外には何も出ていきません。
• Live は実際に送信を行います。

Simulate による送信も、simulated としてマークされ、完全なペイロードとともに Deliveries の台帳に表示されます。これが、ルールを外部に公開する前にレビューするための想定された方法です。

モードは意図的にルール全体に適用されます。一部の送信は本物で残りはそうではない、というグラフは、2つのルールに分けるよりも判断が難しくなります。

Run#

ルールの1回の実行が Run です。Run には、それをトリガーしたイベント、ステータス、ノードごとのトレース、そしてエラーが記録されます。1つのルールは同時に1つの Run しか進行できないため、実行中のルールは自分自身と競合するのではなくキューに入ります。

Delivery#

すべての外向きの副作用は、ネットワーク呼び出しが発生する前に、Deliveries 台帳の1行として書き込まれます。この行には、ペイロード、解決された送信先、ステータス、リトライ回数、そして送信先から返ってきた内容が保持されます。スキップも記録されるため、「ルールが何もしなかった」ことと「Finding が既にチケット化されていたためルールが何もしなかった」ことを区別できます。

来歴(Provenance)#

ルールが Finding に加えたすべての変更は、そのルール、Run、そして変更を行ったノードに紐づけて記録されます。このタイムラインは Finding 自体で確認できるため、ルール定義を読まなくても「この Finding はなぜ変更されたのか」に答えられます。

スケール#

ルールは、そのスコープに一致するすべてを処理します。1回の Run が扱える Finding の件数に上限はありません。カバレッジではなくメモリ使用量を一定に保つため、チャンク単位で処理を進めます。上限があるのは Preview だけで、切り詰めが発生した場合はその旨が通知されます。

保持期間#

Run と Delivery は、デフォルトでどちらも180日間保持された後に削除されます。製品は、保持期間の長さとレコードが削除される日付を暗黙のままにせず表示し、両方の期間は設定可能です。Configuration を参照してください。

次に読むべきページ#

• Building Rules では、エディター、トリガー、スコープ、条件、テンプレートについて説明しています。
• Node Reference では、25個すべてのノードについて説明しています。
• Runs では、実行、トレース、カスケード、制限について説明しています。
• Deliveries では、チャネル、ステータス、リトライ、リプレイについて説明しています。
• Converting from Rules Engine では、既存のルールを移行する方法について説明しています。
• Configuration では、デプロイメントレベルの設定について説明しています。