ルールの作成 (Pro)
注: Rules Engine 2.0 は DefectDojo Pro 専用の機能です。
ルールはキャンバス上で構築します。パレットからノードをドラッグして配線し、それぞれをサイドパネルで設定します。このページでは、どのノードを使う場合でも共通するプロセスの部分を扱います。ノード自体については Node Reference を参照してください。
エディター
Rules Engine 2.0 > All Rules を開き、New Rule を選択するか、既存のルールを開いて編集します。
パレットは4つのカテゴリーにグループ分けされており、これは一般的なグラフの中を項目が流れていく順序でもあります。
| カテゴリー | ノードの役割 |
|---|---|
| Triggers | ルールがいつ起動するか、どの Finding が入ってくるかを決定します。グラフごとにちょうど1つです。 |
| Logic | 流れてくる項目のルーティング、制限、重複排除を行います。 |
| Findings | Finding を変更します。 |
| Egress | チケット、メッセージ、レポートなど、外部に何かを送信します。 |
パレットはエンジン自体から生成されているため、エディターに表示される内容は常にエンジンが実行できる内容そのものです。
グラフのルール
グラフは保存時、およびすべての実行前に検証されます。次のすべてを満たしている必要があります。
- 少なくとも1つのノードを持つこと。
- トリガーノードをちょうど1つ持つこと。
- すべてのノードが、一意で空でない、100文字以下の id を持つこと。
- すべてのノードが、エンジンが認識するタイプであること。
- すべてのエッジが、実在する2つのノードを接続していること。
- 循環を含まないこと。
何も配線されていないノードは合法です。空の入力リストで実行され、通常は何もしないことを意味します。
複数の入力エッジを持つノードは、それらすべての出力を連結して受け取ります。
保存前のプレビュー
Preview は、現在キャンバス上にあるグラフをドライランし、それが生成するであろうノードごとのトレースを表示します。各ノードに入った項目数、各出力から出ていった項目数、そして各ノードが何を変更したはずかがわかります。
Preview は、シミュレーションではなく実際のエンジンを実行し、その後すべてをロールバックします。何も書き込まれず、Run も記録されず、Egress はルールのモードに関わらず Simulate するよう強制されます。これは、条件が意図した通りに一致しているかを確認する最も速い方法です。
Preview は、高速さを保つために処理対象の Finding 件数に上限がある唯一の実行です。切り詰めが発生した場合はトレースにその旨が記載されます。実際の Run にはそのような上限はありません。
トリガーとスコープ
すべてのグラフは、3種類のトリガーのいずれかから始まります。
- On Finding Event は、Finding が作成、更新、クローズ、再オープンされたときにルールを起動します。そのうちどれにするかはノードの Event 設定で選択します。4つすべてを対象にするには
anyを指定します。 - On a Schedule は、繰り返しスケジュールで Finding を走査します。
- Manual Run は、ルール上で Run を押したときに Finding を走査します。
スコープ
3種類のトリガーはすべて Scope を受け取り、スコープはルールが対象とする範囲を絞り込む手段です。これは従来の Rules Engine が使うのと同じフィルター語彙であり、Finding とその周辺オブジェクトにまたがるおよそ60種類のフィルターです。そのため、そちらで既に書き方を知っているフィルターは、ここでも同じ意味を持ちます。
スコープについて理解しておく価値のある点が2つあります。
- スコープは認可の上に適用されるものであり、認可の代わりにはなりません。 ルールはその所有者として実行されるため、スコープは既に認可された Finding の集合をさらに絞り込みます。スコープを空のままにすることは「インスタンス内のすべての Finding」を意味するのではなく、「ルール所有者が閲覧できるすべての Finding」を意味します。
- 無効なスコープは、範囲を広げるのではなく Run を失敗させます。 フィルターのキーが存在しない場合や、フィルターが黙って破棄してしまうような値である場合、Run はエラーになります。何もしないルールは復旧可能です。インスタンス内のすべての Finding を静かに編集してしまうルールは復旧できません。
イベントトリガーの場合、スコープは第2の関門として機能します。イベントに含まれる Finding はスコープと照合され、それを通過したものだけがグラフに入ります。
スケジューリング
トリガーが On a Schedule であるルールは、ルール自身からスケジュールを設定します。スケジュールの設定には、ルールの編集と同じ権限である Rule Edit が必要です。スケジュールトリガーのルールは、スケジュールが設定されるまで一切何もしないためです。
スケジュールは15分刻みの時刻に限られます。cron 式の分フィールドは 0、15、30、45 のいずれかでなければなりません。
有効な例:
0 * * * * every hour, on the hour
15 9 * * * every day at 09:15
0 15 * * 1 every Monday at 15:00
30 2 * * * every day at 02:30Finding データの参照
ルール内の2箇所、conditions と templates は、そこを流れる item から値を読み取ります。どちらも同じドットパス記法を使います。
finding.severity
finding.title
finding.vulnerability_ids.0
product.name
product_type.name
test.scan_type
ctx.rule_name解決できないパスは、エラーではなく値なしという結果になります。
利用可能なフィールド
各 item は、固定された Finding フィールドの集合を保持します。この一覧はいわば契約であり、意図的な場合にのみ変更されます。
| グループ | フィールド |
|---|---|
| 識別情報 | id, title, hash_code, unique_id_from_tool |
| 深刻度とスコアリング | severity, numerical_severity, cvssv3, cvssv3_score, epss_score, epss_percentile, priority, risk, risk_score |
| テキスト | description, mitigation, impact |
| ステータス | active, verified, false_p, duplicate, is_mitigated, out_of_scope, risk_accepted, under_review |
| 日付 | date, mitigated, last_status_update, sla_expiration_date |
| 位置情報 | file_path, line, component_name, component_version, service |
| 分類 | cwe, vulnerability_ids, tags |
finding に加えて、各 item は test(id, title, scan_type)、engagement(id, name)、product(id, name)、product_type(id, name)、そして ctx を保持します。
日付は ISO-8601 形式の文字列です。これは意図的な設計で、gt や lt がテキストとして正しく順序付けできることを意味します。そのため 2026-07-28 は 2026-01-01 より正しく大きいと判定されます。
priority、risk、risk_score は Pro の優先度付け機能から得られます。まだスコアリングされていない Finding には、これらの値は存在しません。
Conditions
If / Filter ノードは、条件行のリストを保持します。各行はパス、演算子、値から構成されます。Match は、すべての行を満たす必要があるか(all)、いずれか1つでよいか(any)を決定します。
| 演算子 | 意味 |
|---|---|
eq | 等しい |
neq | 等しくない |
contains | 含む |
not_contains | 含まない |
in | いずれかに一致する |
not_in | いずれにも一致しない |
gt | より大きい |
gte | 以上 |
lt | より小さい |
lte | 以下 |
startswith | で始まる |
endswith | で終わる |
exists | 設定されている |
not_exists | 設定されていない |
比較は緩やかです。まず数値として比較を試み、それが失敗した場合はトリムされた大文字小文字を区別しないテキストとして比較されます。そのため finding.severity eq high と書かれた条件は、深刻度が High である Finding に一致します。これはほとんどの場合、作成者の意図通りです。
Transforms
条件行は、比較する前に読み取った値を後処理できます。
| Transform | 効果 |
|---|---|
int | 整数 |
float | 小数 |
str | テキスト |
first | リストの最初の要素 |
list | リストとして扱う |
join | カンマ区切りで結合 |
upper | 大文字化 |
lower | 小文字化 |
strip | 前後の空白を除去 |
cwe_int | CWE 番号 |
severity | 正規化された深刻度。これにより、スキャナーごとに異なる critical、error、warning のような値が DefectDojo の5段階の深刻度にマッピングされます |
numerical_severity | 順序比較のための、ソート可能な深刻度コード |
Templates
メッセージ、メモ、タイトル、値としてラベル付けされた設定であれば、{{ path }} プレースホルダーを使用でき、item ごとに解決されます。
{{finding.severity}}: {{finding.title}} ({{product.name}})値のないパスは空文字列としてレンダリングされます。リストはカンマ区切りでレンダリングされます。
Templates は、Run 自体に関する詳細を保持する ctx ブロックも参照できます。利用可能なキーはノードによって異なりますが、共通するものは次の通りです。
| プレースホルダー | 意味 |
|---|---|
{{ctx.rule_name}} | ルールの名前 |
{{ctx.count}} | メッセージが対象とする Finding の件数 |
{{ctx.trigger}} | Run を開始したイベント |
{{ctx.findings_html}} | email ノードにおける、レンダリングされた Finding のリスト |
{{ctx.report_url}} | report ノードにおける、ダウンロードリンク |
{{ctx.template_name}} | report ノードにおける、レポートテンプレート名 |
Templates は単純な置換にすぎません。ルール設定のどこにも、式の評価、コードの実行、オブジェクトへの属性アクセスは存在しません。
ルールを安全にテストする
何かを送信するルールについて推奨される手順は次の通りです。
- グラフを構築し、項目数が正しく見えるまで Preview を使います。
- 保存します。新しいルールは無効な状態で作成されます。
- モードを Simulate のままにしてルールを有効化します。
- 実行させ、Deliveries を確認して、記録されたペイロードが意図した通りであるかを確認します。
- モードを Live に切り替えます。
Simulate は部分的な実行ではありません。グラフ内のすべての Finding の編集は、Simulate モードでも実際に行われます。抑止されるのは外向きの送信だけです。