テスト (Pro)

Organizations → Assets → Engagements → TESTS → Findings

概要#

テストとは、アセット内の欠陥を発見するために実行される1回以上のスキャン実行を格納するコンテナです。テストはDefectDojoのオブジェクト階層の中で最も末端かつ最も細かい単位であり、セキュリティツールの実行や手動評価の結果として得られる検出事項を格納するコンテナであると同時に、そうした検出事項がどのような文脈で発見されたか(どのツールが報告したか、そのツールが最後に実行されたのはいつかなど)という情報も付加します。

テストの例としては、以下のようなものが挙げられます。

• 静的アプリケーションセキュリティテスト
• 動的アプリケーションセキュリティテスト
• ソフトウェア構成分析
• コンテナセキュリティスキャン
• インフラストラクチャ/ネットワークスキャン
• 手動での侵入テスト
• CI/CDパイプラインスキャン

テストタイプ#

DefectDojoでテストを作成する方法はいくつかあり、ベンダー固有のパーサー(Burp、OWASP ZAP、Acunetix、Invictiなど)、Generic Findings Import、Universal Parser、Connectorsが含まれます。

これらの方法は、設定や重複排除の戦略に応じて、新しいテストを作成することも、既存のテストに検出事項を再インポートすることもできます。

それぞれの方法はスキャンデータの解析と取り込み方が主に異なりますが、最終的にはいずれも検出事項がテストに関連付けられる結果となります。

パーサー#

パーサーとは、特定のスキャン出力形式(XML、JSON、CSVなど)を処理し、DefectDojo内部の検出事項モデルにマッピングするコンポーネントです。スキャン結果がインポートされると、DefectDojoは選択されたパーサーを使用して検出事項を抽出し、新規作成または既存のテストに関連付けます。

Generic Findings Import#

特定のツール用のネイティブパーサーが存在しない場合、Generic Findings Importを使用すると、元のソースにかかわらず標準化されたJSONまたはCSVスキーマを使って検出事項をインポートできます。

DefectDojoは提供されたデータを解析し、新しいテストを作成する(または既存のテストにインポートする)とともに、検出事項を関連付けます。レポートの任意項目であるtypeフィールドに基づいて、対応するテストタイプも作成されます。typeが省略されている場合(またはスキャンタイプと同じ場合)、テストタイプは「Generic Findings Import」になります。typeが指定されている場合は「{type} Scan (Generic Findings Import)」という形式になります(すでに「(Generic Findings Import)」というサフィックスで終わっているtypeはそのまま使用されます)。

Universal Parser#

Universal Parserを使用すると、任意の入力データをDefectDojoの検出事項モデルにどのようにマッピングするかをユーザーが定義できます。パーサーを設定してスキャンデータをアップロードすると、DefectDojoはマッピングルールを適用して検出事項を抽出し、テストを作成(または既存のテストを更新)し、そのテストに検出事項を関連付けます。

Connectors#

Connectorsを使用すると、外部ツールからの脆弱性データをAPI呼び出しによって自動的に取り込み、整理できます。設定が完了すると、コネクタはスキャン結果を取得し、データを解析して、その設定に応じて新しいテストを作成するか既存のテストを更新します。その後、検出事項が対応するテストに関連付けられます。

テスト作成メカニズムの比較#

取り込み方法にかかわらず、DefectDojo内のすべてのスキャンデータは最終的にテストに関連付けられた検出事項として表現され、テストが実行単位およびライフサイクル追跡の単位として機能します。

テストデータ#

テストは、各テスト実施のさまざまな要素を記録するのに役立つ多様なメタデータを保持します。例えば以下のようなものです。

• テストのタイトル/名前
• テストタイプ
• テストの説明/メモ
• 開始日と終了日
• テストが実行された環境(Development、Staging、Pre-Production、Productionなど)
• バージョン/ブランチ/ビルドID/コミットハッシュ
• APIスキャン設定
• テストに関連する担当者
• 後の監査や再インポートに使用できる追加ファイル
• 親となるエンゲージメント、アセット、組織
• インポートおよび再インポートの履歴

各テストはインポート履歴を保持しており、そのテストに関連するすべてのスキャンのインポートと再インポートが記録されます。各履歴項目には、スキャン日、バージョン、ブランチ、コミットハッシュ、ビルドIDなどのメタデータが含まれます。

この履歴により、同一テスト内での複数回のスキャン実行にわたるトレーサビリティが確保されます。

権限#

1つのエンゲージメント内には複数のテストを格納でき、エンゲージメントはアセット内に格納されます。そのため、アセットへのアクセス権があれば、そのアセット内のすべてのテスト(およびエンゲージメント)へのアクセスが自動的に許可されます。テストは独自のアクセス制御リストを持ちません。

テストへのアクセス#

テストはDefectDojoのUIのさまざまなセクションからアクセスできます。

• サイドバー

• エンゲージメント内

• アセットの上部バー

• 検出事項ビュー内のメタデータテーブル

テストの操作#

テストの作成#

スキャンデータがエンゲージメントに直接インポートされると、そのスキャンデータを含む新しいテストが自動的に作成されます。また、今後のエンゲージメントを計画する目的や、追跡・修復が必要な手動入力のセキュリティ検出事項のために、あらかじめテストを作成しておくこともできます。

手動ワークフロー#

テストを作成するには、それを格納するエンゲージメントと、そのエンゲージメントを格納するアセットが必要です。その後、テストを作成する方法はいくつかあります。

• サイドバーのManageサブセクション内のTestsから
  • New Testフォームを入力する際に、そのテストを紐付ける既存のエンゲージメントを選択する必要があります。

• アセットビュー右上の設定ドロップダウンから
  • Import Scanでは、Import Scanフォームにスキャンファイルが追加されると自動的にテストが作成されます。そのテストを既存のエンゲージメントに紐付けるか、新しいエンゲージメントを作成・命名して新しいテストを格納するかを選択できます。
    • Import Scanフォームの入力時に、バージョン、ブランチタグ、コミットハッシュ、ビルドIDなどのメタデータを追加できます。これはテストビューのImport Historyセクションに反映されます。

• エンゲージメントビュー右上の設定ドロップダウンから
  • Import Scanはアセットの場合と同じワークフローに従いますが、Import Scanをクリックしたエンゲージメント内に自動的にテストオブジェクトが配置されます。
  • Add Testはテストオブジェクトを作成しますが、そのテスト自体にスキャンをアップロードすることは必須ではありません。これは、今後のテストを計画する目的や、追跡・修復が必要な手動入力のセキュリティ検出事項に有用です。

Add Testを選択し、後でスキャン結果を手動でテストにインポートしたい場合は、テストを開いてテストの設定内のReimport Findingsボタン、または検出事項テーブル内のReimport Scanボタンをクリックすることで実行できます。

自動化されたワークフロー#

自動化されたワークフローでは、スキャンのインポート処理の一部としてプログラム的にテストを作成できるため、パイプラインは事前に手動でテストを作成することなく結果をアップロードできます。

APIまたはCLIを使ってスキャン結果をインポートする際、testの代わりにengagementを指定することで、新しいテストを自動的に作成できます。

API#

curl -X POST "https://<your-instance>/api/v2/import-scan/"
-H "Authorization: Token <api_key>"
-F "engagement=45"
-F "scan_type=ZAP Scan"
-F "file=@report.xml"

上記の場合、指定されたエンゲージメントの下に新しいテストが作成され、スキャン結果がそのテストに関連付けられます。

代わりにtest IDが指定された場合、スキャン結果は既存のテストに追加されます。これは再インポートのワークフローでよく見られるパターンです。

CLI#

DefectDojo CLIを使用する場合、この動作は指定された引数に基づいて自動的に処理されます。

defectdojo-cli import
–engagement-id 45
–scan-type "ZAP Scan"
GOog –file report.xml

上記の場合、engagement-idを指定すると新しいテストが作成され、test-idを指定すると既存のテストが再利用され、そのテストにスキャン結果が再インポートされます。

必須フラグの詳細については、DefectDojo-CLIを参照してください。

テストの編集#

テストは、歯車メニューからEdit Testをクリックすることで編集できます。編集可能なフィールドはすべて、テスト作成時にも利用できます。

テストの削除#

テストの削除は、テストの設定からDelete Testを選択することで行えます。この操作は元に戻せません。

テストを削除すると、そのテストに含まれるすべての検出事項も削除されます。

スキャン結果の再インポート(UI)#

既存のテストに新しいデータを追加するには、追加先のテストを開いて、テストの設定内のReimport Findingsボタン、または検出事項テーブル内のReimport Scanボタンをクリックします。

Reimport Scanフォームの入力時には、再インポートするスキャンのメタデータ(バージョン、ブランチタグ、コミットハッシュ、ビルドIDなど)を更新するオプションがあります。これらの変更はテストビューのImport Historyセクションに反映され、以前のスキャンインポート時の同様のメタデータも併せて表示されます。

例えば下のスクリーンショットでは、最初のインポートとその後の再インポートの間に、ブランチタグ、ビルドID、コミットハッシュ、バージョンがすべて手動で更新されています。

直近に再インポートされたスキャンのメタデータを編集するには、エンゲージメントビュー右上にある歯車アイコンをクリックし、「Edit Test」を選択します。編集できるのは直近のインポートのメタデータのみです。

スキャン結果の再インポート(API/CLI)#

CI/CDパイプラインを通じてテストが作成または更新される場合、パイプライン実行時のメタデータを含めることで、テストをスキャン対象のコードに適切に紐付けることができます。これにより、以下のようなことが可能になります。

• スキャン結果を特定のコミットやブランチに関連付ける。
• コードの変更に伴って検出事項がどのように推移するかを追跡する。
• 2つのスキャンが同じバージョンのコードに対するものか、異なるバージョンのものかを把握することで重複排除を改善する。
• どのコードがいつスキャンされたかを正確に示すことで、監査可能性をサポートする。

DefectDojoのCLIとAPIは、インポートまたは再インポート時にこれらの値を受け付けます。これによりスキャンインポートの一部として保存され、テストのインポート履歴に反映されます。このメタデータは、コミットハッシュや、CI/CD実行に関連するリポジトリ情報を特定するために使用できます。

サポートされているメタデータフィールド#

APIとCLIは、再インポート時に含めることができる定義済みのメタデータフィールドをサポートしています。以下の通りです。

• tags
• version
• build_id
• branch_tag
• commit_hash
• scan_date
• minimum_severity
• active / verifiedフラグ

これらのフィールドは、再インポート操作時に文脈的なメタデータを付与するための主要な仕組みです。

自動化されたパイプラインでは、最もよく指定されるメタデータは以下の通りです。

• build_id(CIジョブの識別子)
• commit_hash(ソース管理の参照情報)
• branch_tag(ブランチまたは環境のコンテキスト)
• tags(nightly、staging、productionなど)

これらのフィールドにより、手動での介入を必要とせずにスキャン間のトレーサビリティが確保されます。

メタデータはReimport Scanフォームから手動で更新することもできますが、ほとんどの自動化された環境では、ビルドプロセスの一部として/api/v2/reimport-scan/エンドポイントを直接呼び出すか、DefectDojo CLI(defectdojo-cli reimport)を使用してこれを処理します。この方法により、パイプラインは再インポート時にメタデータを自動的に付与できます。

メタデータを伴うAPI再インポート#

curl -X POST "https://<your-instance>/api/v2/reimport-scan/"
-H "Authorization: Token <api_key>"
-F "test=123"
-F "scan_type=ZAP Scan"
-F "file=@report.xml"
-F "tags=nightly,api-scan"
-F "version=1.4.2"
-F "build_id=jenkins-842"
-F "branch_tag=main"
-F "commit_hash=a1b2c3d4"

メタデータを伴うCLI再インポート#

defectdojo-cli import
–test-id 123
–scan-type “ZAP Scan”
–file report.xml
–tag nightly
–tag api
–build-id jenkins-842
–branch main
–commit a1b2c3d4

CLIは同じAPIエンドポイントに直接マッピングされ、同じメタデータフィールドのセットをサポートします。

再インポート時にメタデータを扱う際には、いくつか注意すべき制約があります。

• APIおよびCLIは事前定義されたパラメータのみをサポートします。再インポート時にカスタムのキーバリュー形式のメタデータを追加することはできません。
• スキャンタイプやパーサーによっては、スキャンファイル自体から追加のメタデータが抽出される場合があります。
• 再インポート時に指定されたメタデータは、UI上での手動編集のようにテストオブジェクトへ直接反映されるわけではありません。

メタデータ、再インポート、スケジュールスキャン#

スキャンは、cronジョブなどによって定期的な間隔で実行されるようスケジュールすることもできます。スケジュールされたスキャンはリポジトリの活動に紐付いていないため、スクリプト自体が明示的に付与しない限り、コミットハッシュやブランチ名などのメタデータは意味を持ちません。とはいえ、単一のテスト内でセキュリティ体制の継続的な記録を維持したい場合は、再インポートを使用することが依然として有用です。

再インポートと重複排除#

テスト内でスキャンを再インポートすることは、効果的な重複排除の基本です。スキャン結果が同じテストに再インポートされると、次のようになります。

• 既存の検出事項が更新される場合があります
• 重複する検出事項が抑制される場合があります
• 一致するものが見つからない場合は新しい検出事項が作成されます

この動作は、設定された重複排除ルールとスキャンタイプに依存します。

既存のテストに再インポートする代わりに新しいテストを作成すると、検出事項が更新されるのではなく重複して作成される可能性があります。

再インポートとインポートの違い#

再インポートは、主に次のような場合に使用されます。

• 同一のターゲットに対して繰り返しスキャンを実行する場合
• 検出事項が時間の経過とともにどのように変化するかを追跡する場合
• アプリケーションのセキュリティ体制を継続的に把握する場合

一方、インポート(新しいテストの作成)は、一度限り、または独立したスキャン実行に適しています。