ノードリファレンス (Pro)
注: Rules Engine 2.0 は DefectDojo Pro 限定の機能です。
Rules Engine 2.0には、4つのカテゴリにわたって25個のノードが搭載されています。このページではそのすべてを解説します。
特に断りがない限り、ノードは1つの入力を受け取り、out と呼ばれる1つの出力を生成し、受け取ったすべてのアイテムをその出力へと渡します。これはノードを連結する際に重要です。検出事項ノードは検出事項を変更してからアイテムを次へ渡すため、連続して並んだ複数のノードがすべて適用されます。
トリガー
すべてのグラフにはトリガーがちょうど1つあり、実行を開始できるのはトリガーだけです。3種類のトリガーはすべて検出事項アイテムを生成し、いずれも生成する検出事項を絞り込むScopeを持ちます。スコープの仕組みについてはルールの作成を参照してください。
検出事項イベント時
trigger.finding
検出事項が作成、更新、クローズ、または再オープンされたときに実行されます。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Event | created | このルールを起動させる検出事項の変更種別: created、updated、closed、reopened、またはこの4つすべてを対象とする any。 |
| Scope | 空 | このルールが対象とする検出事項。空の場合は、ルールの所有者が閲覧できるすべての検出事項が対象になります。 |
イベントによって指定された検出事項は、グラフに入る前にスコープと照合されます。つまりイベントがいつを決定し、スコープがどれを決定します。
スケジュールで実行
trigger.schedule
スケジュールに従い、スコープ内のすべての検出事項を走査します。スケジュールはルール上で設定し、15分刻みの時刻に限定されます。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Scope | 空 | このルールが対象とする検出事項。 |
手動実行
trigger.manual
ルール上でRunを押すと、スコープ内のすべての検出事項を走査します。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Scope | 空 | このルールが対象とする検出事項。 |
ロジック
If / フィルター
filter.if
条件に基づいて、各アイテムをtrueまたはfalseの分岐へ振り分けます。これは出力を2つ持つ唯一のノードであり、グラフを分岐させる手段です。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Conditions | 空 | 各行はパス、演算子、値で構成されます。条件を参照してください。 |
| Match | all | すべての条件を満たす必要があるか(all)、いずれか1つで良いか(any)。 |
条件リストが空の場合、すべてのアイテムがtrue分岐へ渡されます。どちらの分岐も接続は任意です。false分岐を未接続のままにすると、条件を満たさなかったアイテムは単に破棄されます。
上限
flow.limit
最初のN件のアイテムを通過させ、残りを破棄します。ルールをテストする際の安全弁として、また1回の実行で生成できるチケットやメッセージの件数に上限を設けるために便利です。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Keep First | 100 | 通過させるアイテムの件数。 |
実行内で重複排除
flow.dedupe_batch
キーごとに最初のアイテムを保持し、同じキーを持つ後続のアイテムを破棄します。この処理は実行単位でスコープされるため、1回の実行内でのみ重複排除が行われ、実行をまたいだ重複排除は行われません。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Key Path | finding.hash_code | 重複を識別する値を持つアイテムパス。 |
よくある使い方は finding.component_name を指定し、検出事項ごとではなく影響を受けたコンポーネントごとに1回だけ通知することです。
検出事項
これらのノードは検出事項を変更します。すべての変更は、それを行ったルール、実行、ノードに紐付けられ、検出事項の来歴(provenance)タイムラインに表示されます。
深刻度を設定
finding.set_severity
深刻度を設定し、それに合わせてSLA日付と優先度を再計算します。
| 設定 | 選択肢 |
|---|---|
| Severity | Critical, High, Medium, Low, Info |
フィールドを設定
finding.set_field
テキストフィールドに値を設定、追記、または先頭に追加します。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Field | なし | component_name、component_version、cvssv3、cwe、description、file_path、impact、mitigation、service、title のいずれか。 |
| Mode | set | set、append、または prepend。CVSSv3ベクターは置き換えのみ可能です。 |
| Value | なし | 書き込むテキスト。{{finding.title}} のようなプレースホルダーに対応しています。 |
ステータスを設定
finding.set_status
検出事項を指定したステータスに移行します。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Status | なし | active, inactive, verified, unverified, false_positive, mitigated, reopen。 |
| Note | 空 | ステータス変更に合わせて記録される任意のメモ。 |
タグを追加
finding.add_tags
検出事項にタグを追加します。既存のタグはそのまま保持されます。
| 設定 | 備考 |
|---|---|
| Tags | カンマ区切り。{{product.name}} のようなプレースホルダーに対応しているため、検出事項のデータを使ってタグ付けできます。 |
メモを追加
finding.add_note
検出事項にメモを追加します。
| 設定 | 備考 |
|---|---|
| Note | メモの本文。プレースホルダーに対応しています。 |
所有者を設定
finding.set_owners
グループを検出事項の担当にします。
| 設定 | 備考 |
|---|---|
| Group | これらの検出事項を所有するグループ。 |
レビュアーを設定
finding.set_reviewers
選択したユーザーによる検出事項のレビューを開始します。
| 設定 | 備考 |
|---|---|
| Reviewers | これらの検出事項をレビューすべき1人以上のユーザー。 |
リスクを受容
finding.risk_accept
検出事項をシンプルリスク受容するか、リスク受容レコードに追加します。
| 設定 | デフォルト | 備考 |
|---|---|---|
| How | simple | simple は検出事項にシンプルリスク受容を設定します。acceptance はリスク受容レコードに追加します。 |
| Accepted | オン | simple の場合に表示されます。オフにするとリスク受容を解除します。 |
| Risk Acceptance | なし | acceptance の場合に表示されます。これらの検出事項をどのリスク受容に追加するか。 |
緩和ポリシーを設定
finding.set_mitigation_policy
検出事項が是正される際の緩和ポリシーを設定します。
| 設定 | 備考 |
|---|---|
| Mitigation Policy | 適用するポリシー。 |
優先度を変更
finding.set_priority
優先度を設定するか、算術的に調整します。これは計算された優先度を上書きします。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Operation | set | set、add、subtract、multiply、divide。 |
| Value | なし | 設定する優先度、または調整量。 |
リスクを設定
finding.set_risk
計算されたリスクを上書きして設定します。
| 設定 | 選択肢 |
|---|---|
| Risk | Low, Medium, Needs Action, Urgent |
送信(Egress)
送信ノードは、DefectDojoの外へ出ていくノードです。いずれも何かを送信する前に配信を記録し、いずれもルールのSimulateまたはLiveモードに従います。
このうちいくつかは同じOne Message per Findingの選択肢を提供します。オフの場合、ノードはバッチ全体を説明する1件のメッセージを、深刻度の内訳と件数上限付きの検出事項一覧とともに送信します。オンの場合、検出事項ごとに1件のメッセージを送信します。
検出事項ごとに1件のメッセージを送信するノードは、デフォルトでは1回の実行につき1,000件の送信で停止し、送信されなかった検出事項の件数を記した、目に見えるスキップを記録します。設定を参照してください。
チャネルが利用できない場合
送信ノードは、Slackトークン、Microsoft Teams Webhook、JIRA設定、ライセンス済みコネクタなど、ルールの外部にある何かに依存しています。それが欠けているか無効化されている場合、ノードは動作できません。Rules Engine 2.0は黙って失敗するのではなく、3つの異なるタイミングでそれを知らせます。
- パレット内では、利用できないノードはキャンバスにドラッグする前に、その旨と理由がマークされています。
- 保存時には、利用できないノードを含むグラフは拒否されます。これは、誰かがその場にいて別のノードを選び直せるタイミングです。
- 実行時には、配信は失敗ではなく、理由が添えられたスキップになります。Slackが有効な状態で保存されたルールは、誰かがSlackを無効化した日にエラーを出し始めるべきではありません。正直な記録とは、Slackが無効であることを伝えるスキップされた配信のことです。
JIRA課題を作成
ticket.jira
検出事項に対応するJIRA課題を作成または更新します。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Skip Findings That Already Have an Issue | オン | 既にJIRA課題を持つ検出事項はそのままにします。 |
| Update an Existing Issue | オフ | 上記のスキップがオフの場合に表示されます。既に課題を持つ検出事項もプッシュされ、JIRAが更新されます。 |
サマリー、説明、優先度はこのノードではなく、製品のJIRA設定から取得されます。そのため、ルールが作成するチケットは、push all issuesによって作成されるものと同一です。
ダウンストリームチケットを作成
ticket.downstream
ダウンストリームコネクタを通じてチケットを作成または更新します。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Issue Trackers | auto | auto はエンゲージメントまたは製品に割り当てられた課題トラッカーを使用します。mapping は特定の1つのマッピングを対象にします。 |
| Issue Tracker Mapping | なし | mapping の場合に表示されます。どのマッピングへプッシュするか。 |
| Operation | create | チケットをcreateするか、既存のものをupdateするか。既存のチケットがない状態でのupdateは、新規作成になります。 |
| Skip Findings That Already Have a Ticket | オン | 対象のマッピングに既にチケットを持つ検出事項はそのままにします。 |
このルールは、割り当ての自動プッシュ設定を置き換えます。深刻度やアクティブのみのフィルターはここでは再適用されません。既にチケットが存在する検出事項は、そのチケットがどのように作成されたかにかかわらずスキップされます。
Slackメッセージを送信
notify.slack
メッセージングコネクタを介してSlackチャネルに投稿します。接続情報にはボットトークンが含まれます。System Settings配下のインスタンス全体のSlack設定は使用されず、フォールバックにもなりません。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Connection | なし | この種類のメッセージングコネクタ。必須。 |
| Destination | 空 | 接続が選択されると表示されます。フィールドは接続先のベンダーによって異なります。 |
| One Message per Finding | オフ | オフの場合、バッチ全体について1件のメッセージを送信します。 |
| Message | {{finding.severity}}: {{finding.title}} ({{product.name}}) | 検出事項ごとにレンダリングされます。 |
| Findings Listed in the Digest | 10 | バッチメッセージの場合に表示されます。メッセージが「他に何件あるか」を示す前に列挙する検出事項の件数。 |
Microsoft Teamsメッセージを送信
notify.msteams
メッセージングコネクタを介してカードを投稿します。接続情報にはPower AutomateのワークフローURLが含まれます。System Settings配下のインスタンス全体のTeams Webhookは使用されず、フォールバックにもなりません。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Connection | なし | この種類のメッセージングコネクタ。必須。 |
| Destination | 空 | 接続が選択されると表示されます。フィールドは接続先のベンダーによって異なります。 |
| One Message per Finding | オフ | オフの場合、バッチ全体について1件のカードを送信します。 |
| Message | {{finding.severity}}: {{finding.title}} ({{product.name}}) | 検出事項ごとにレンダリングされます。 |
| Findings Listed in the Digest | 10 | バッチメッセージの場合に表示されます。 |
メールを送信
notify.email
メッセージングコネクタを介して、固定のアドレスリストにメールを送信します。宛先は接続先のDestinationです。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Connection | なし | この種類のメッセージングコネクタ。必須。 |
| Destination | 空 | 接続が選択されると表示されます。フィールドは接続先のベンダーによって異なります。 |
| Subject | [DefectDojo] {{ctx.count}} finding(s) from rule {{ctx.rule_name}} | メッセージごとに1回レンダリングされます。 |
| Body | {{ctx.findings_html}} を含むHTML本文 | HTML形式。{{ctx.findings_html}} が検出事項の一覧をレンダリングします。 |
| One Message per Finding | オフ | オフの場合、バッチ全体について1件のメールを送信します。 |
| Findings Listed in the Body | 25 | {{ctx.findings_html}} が「他に何件あるか」を示す前に列挙する検出事項の件数。 |
Webhookを呼び出す
notify.webhook
Webhookエンドポイントに対してJSONをPOSTします。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Webhook Endpoint | なし | 設定済みの通知Webhook。そのカスタムヘッダーがリクエストとともに送信されます。 |
| URL | 空 | エンドポイントが選択されていない場合に表示されます。POST先。 |
| 上記のいずれか一方が必須です。 | ||
| Signing Secret | 空 | 本文に X-DefectDojo-Signature: sha256=HMAC として署名します。 |
| One Message per Finding | オフ | オフの場合、バッチ全体を1回のリクエストでPOSTします。 |
知っておくべきことが2つあります。ここに入力した署名シークレットはルールとともに保存されるため、機密性の高いものについては設定済みのエンドポイントとその専用ヘッダーを使うことをお勧めします。また、ルールによって呼び出されたWebhookは、そのエンドポイント自体のヘルスステータスを変更することはないため、ルールが失敗しても通知Webhookが無効化されることはありません。
自由入力のURLは保存時に検証されます。何が拒否されるか、またプライベートアドレスを許可する方法については設定を参照してください。
アプリ内アラートを発行
notify.alert
バッチに関するアプリ内アラートを作成します。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Title | Rules Engine 2.0: {{ctx.rule_name}} | バッチ全体について1回レンダリングされます。 |
| Description | {{ctx.count}} finding(s) matched the rule {{ctx.rule_name}}. | バッチ全体について1回レンダリングされます。 |
| Recipients | 空 | ユーザー名をカンマ区切りで指定します。空の場合は管理者にアラートが送られます。 |
受信者は自身のRules Engine Match通知設定を通じて、これを引き続き制御できます。そのため、アラートがユーザーの通知設定を回避することはありません。
レポートを生成
report.generate
テンプレートからレポートを生成します。このノードに到達した検出事項に範囲が限定され、ダウンロードリンクをアナウンスすることもできます。
| 設定 | デフォルト | 備考 |
|---|---|---|
| Report Template | なし | どのテンプレートから生成するか。必須。 |
| Format | pdf | pdf または html。 |
| Findings Included | batch_findings | batch_findings は、このノードに到達した検出事項にレポートを限定します。template_default はテンプレート自身のフィルターを使用させます。 |
| Announce Over | なし | レポート生成後にダウンロードリンクを投稿するメッセージングコネクタ。アナウンスしない場合は空のままにします。 |
| Announce To | 空 | 接続が選択されると表示されます。その接続の送信先(Slackチャネル ID、メールアドレスなど)。 |
| Announcement | Report ready: {{ctx.report_url}} | アナウンスする場合に表示されます。{{ctx.report_url}} がダウンロードリンクです。 |
batch_findings は、スケジュール実行のレポートにはできない、ルールならではのことです。まさに今マッチした検出事項についてレポートできます。
アナウンスはレポート生成とは別の、独自の配信として記録されるため、レポートの生成は成功しつつアナウンスだけが失敗した、という状況も個別に確認できます。