🌐 ユニバーサルパーサー (Pro)

注: ユニバーサルパーサーはDefectDojo Proでのみご利用いただけます。

ユニバーサルパーサーはすべてのDefectDojo Proインスタンスで有効になっており、特に有効化の操作は必要ありません。詳細については発表プレゼンテーションをご覧ください。

ユニバーサルパーサーについて#

DefectDojoには、セキュリティチームがデータを取り込む際に役立つ、定期的に更新される豊富なパーサーライブラリがあります。しかし、ユーザーが使用しているツールがパーサーでサポートされていなかったり、パーサーとは異なる方法でDefectDojoモデルにデータをインポートしたいと考えたりする場合があります。

DefectDojoのユニバーサルパーサーは、サポートされていないレポート形式を使用しているユーザーに、あらゆるJSON、CSV、またはXMLファイルをインポートしてマッピングするための手段を提供するものです。

ユニバーサルパーサーとは:

• 内部ツールが生成するレポートなど、コミュニティパーサーが存在しないファイル形式を迅速にサポートする手段
• コミュニティパーサーが古い場合や、希望する形式で検出事項を構造化しない場合でも、データの取り込みを支援するツール
• ツールのレポートを「Generic Findings Import」スキャンタイプが想定するCSV/JSON形式に変換するためのカスタムスクリプトに代わる手段
• コーディング不要、最小限の設定で誰でも簡単に使えるよう設計されたもの

ユニバーサルパーサーではないもの:

• オープンソースパーサー、コネクタ、または入念に調整された「Generic Findings Import」レポートの包括的な代替手段
• 検出事項を構造化するための、微妙な分岐ロジックを扱える機能

ユニバーサルパーサーの設定はPro UIでのみ利用可能ですが、旧UIまたはAPI経由であれば、既存のユニバーサルパーサーを使ってスキャンをインポートすることは可能です。

ステップ1: 新しいユニバーサルパーサーの作成#

新しいユニバーサルパーサーは、ナビゲーションバーの「Import」セクションにある「New Universal Parser」ボタンをクリックするか、「Add Findings」ページ上のリンクから作成できます。

最初の画面では、スキャンファイルとパーサー名の入力を求められます。

ファイルは以下の条件を満たす必要があります。

• 認識可能な拡張子を持っていること(サポートされているファイル拡張子については以下を参照してください)
• 実際のレポートを代表するのに十分な、検出事項らしきオブジェクトを含んでいること — つまり、すべてのオプションフィールドに値が含まれているもの
• およそ1〜2MBを超えないこと — これを超えると、メリットなくファイルの解析に時間がかかるだけになります

パーサー名は、この新しいパーサー用のTest_Typeを作成する際に使用されます。新しく作成したユニバーサルパーサーは、「Add Findings」ページのスキャンタイプのドロップダウンに「Universal Parser - MyCustomParser」のような名前で表示されます。インポート時にスキャンタイプを選択する際の混乱を防ぐため、パーサー名は一意である必要があります。

ステップ2: 検出事項フィールドのマッピング#

サンプルのスキャンファイルをアップロードし、パーサー名を選択して「Next」をクリックすると、次のページでこのユニバーサルパーサーがインポート実行時に検出事項フィールドをどのように入力するかを設定できます。右側には、DefectDojoの検出事項フィールド(出力フィールド)の一覧が表示されます。各出力フィールドの左側にあるドロップダウンメニューから、スキャンファイルの構造内のどの項目(入力フィールド)をその出力フィールドに使用するかを選択できます。

例:

次のようなJSON形式のスキャンファイルをアップロードした場合:

{
    "findings": [
        {
            "title": "Finding 1 Title",
            "description": "Finding 1 Description",
            "severity": "CRITICAL",
            "CVE": "CVE-2025-12345",
            ...
        },
        {
            "title": "Finding 2 Title",
            "description": "Finding 2 Description",
            "severity": "LOW",
            "CVE": "CVE-2025-54321",
            ...
        },
        ...

    ]
}

入力ファイルの構造に基づいて検出された一意のフィールドが、その種類を示すアイコンとともに(判別可能な場合)階層構造で表示されます。そこから、「Title」出力フィールドを入力するドロップダウンメニューで「title」入力フィールドを選択したり、「Description」出力フィールドには「description」入力フィールドを選択したりすることができます。

入力フィールド名は出力フィールド名と一致している必要はなく、また、スキャンファイルにDefectDojoのすべての出力フィールドに対応する項目がなくても構いません。

マッピング可能な検出事項フィールド#

以下の表は、入力フィールドをマッピングできるDefectDojoの検出事項フィールド(出力フィールド)をすべて示しています。スキャンファイルにこれらすべてに対応する項目があるとは限りません — 存在するものだけをマッピングしてください。

• Required(必須) — この出力フィールドには、パーサーを保存する前に少なくとも1つの入力フィールドをマッピングする必要があります。
• Accepts multiple inputs(複数入力可) — この出力フィールドは複数の入力フィールドから値を取り込めます。複数マッピングした場合、各値はその入力フィールド名を見出しとして表示されます(複数選択フィールドを参照してください)。

注: 上記の例では、CVE入力フィールドは脆弱性ID出力フィールドにマッピングされます — DefectDojoには文字通り「CVE」という名前の検出事項フィールドは存在しません。

必須フィールド#

以下の出力フィールドには入力フィールドのマッピングが必要です。

• タイトル
• 深刻度
• 説明

深刻度について#

ユニバーサルパーサーは、「CRITICAL」「Critical」「cRiTiCaL」など、DefectDojoの深刻度の大文字小文字の違いをすべて受け入れ、検出事項に適用します。DefectDojoの深刻度に一致しない値はすべて「Info」に置き換えられます。これは、現在のパーサーやコネクタの動作と同様です。不明な値は一般的に「Info」にマッピングされます。

複数選択フィールド#

一部の出力フィールドは複数の入力フィールドを受け付けます。複数の入力フィールドを選択した場合、それぞれのフィールドの値は、その入力フィールド名を見出しとして表示されます。

例

description

これは入力ファイル内の「description」というフィールドから取得されました

detailed_description

これは入力ファイル内の「detailed_description」というフィールドから取得されました

ステップ3: 検出事項のプレビュー#

入力フィールドから出力フィールドへのマッピングを選択したら、「Next」ボタンをクリックすると、選択した設定でDefectDojoにインポートした場合に入力ファイルの検出事項がどのように表示されるかのプレビューを確認できます。一部のフィールドには、そのフィールドがどのようにレンダリングされるかをMarkDownで完全に確認できる「expand」ボタンが隣に表示されます。プレビューは入力ファイルの最初の25件の検出事項のみをレンダリングしますが、スキャンファイル全体で検出された検出事項の総数も確認できます。

プレビューが期待通りでない場合は、「Back」ボタンを押してマッピングを調整できます。設定に満足したら、「Submit」ボタンをクリックして新しいユニバーサルパーサーを作成します。この操作によってインポートが自動的に実行されることはありません。

ユニバーサルパーサーが作成されると、「Add Findings」ページにリダイレクトされ、ステップ1で提供したサンプルファイルの構造に一致するスキャンファイルをアップロードしてインポートできるようになります。

ユニバーサルパーサー設定に関するその他の注意事項#

適切な入力フィールドの選択#

ベンダーによってスキャンレポートの形式は大きく異なり、中にはDefectDojoの検出事項モデルにより近くマッピングできるものもあります。DefectDojoは受け入れる内容についてかなりの柔軟性を持たせていますが、入力から出力への変換の過程で検出事項が破損しないよう、ある程度の構造を課す必要があります。オプションの入力フィールドには対応できますが、「グローバル」フィールドや、検出事項オブジェクトの数と異なる回数出現するフィールドは受け付けません。

例#

{
    "scan_type": "MyToolScan", // <- There is only one instance of this field, which doesn't match the number of findings
    "findings": [
        {
            "title": "Finding 1 Title",
            "description": "Finding 1 Description",
            "severity": "CRITICAL",
            "CVE": "CVE-2025-12345", // <- This optional field only appears in Finding 1 - that's okay!
            ...
        },
        {
            "title": "Finding 2 Title",
            "description": "Finding 2 Description",
            "severity": "CRITICAL",
            ...  // <- While there is no "CVE" field here, we can still query for it and simply default to a null value
        },
        ... 5 more findings ...
    ],
    "global_details": [
        {
            "nested_detail": "Global detail 1"
        },
        {
            "nested_detail": "Global detail 2" // <- The number of "global_details" objects (2) does not match the number of individual finding objects (7)
        }

    ]
}

ユニバーサルパーサーを保存した後#

ユニバーサルパーサーに関連付けられたTest_Typeを編集して、以下を変更できます。

• 「active」かどうか。無効にすると、「Add Findings」ページの「Scan Type」ドロップダウンにオプションとして表示されなくなります
• 検出事項を「static」または「dynamic」としてマークするかどうか
• 「Enterprise Settings」で、ユニバーサルパーサーの同一ツール内および複数ツール間の重複排除ハッシュコード、および再インポートハッシュコードを調整できます。デフォルトでは、必須項目であるタイトル、深刻度、説明を使用して、同一ツール内の重複排除および再インポートハッシュコードのみが設定されます。

ライフサイクル: 作成、無効化、再有効化#

ユニバーサルパーサーのライフサイクルは作成のみであり、UI上での編集や削除はできません。パーサーが作成されると、フィールドマッピングの設定は変更できず、パーサー自体もUIから削除できません — これは意図的な設計であり、ユニバーサルパーサーの設定は、既存の検出事項、テスト、インポート履歴から参照される可能性があるTest_Typeレコードに紐付いているためです。

UIからできる操作は次のとおりです。

• パーサーを無効化すると、インポート時の「Scan Type」ドロップダウンに表示されなくなります。サイドバーのImport → Universal Parserを開くと、すべてのユニバーサルパーサーが表示されるので、「Active」をオフに切り替えてください。(あるいは、対応するTest_Typeを編集して「active」のチェックを外すこともできます。)無効化されたパーサーはAdd Findingsページのスキャンタイプの選択肢には表示されなくなりますが、このパーサーで既にインポート済みのテストには影響がなく、引き続き機能します。
• 同じ画面で「Active」を再度オンに切り替えることで、パーサーを再有効化できます。
• 上記のセクションで説明したTest_Typeフィールド(active/inactive、static/dynamic、重複排除ハッシュコード)を編集できます。

スキャナーのレポート形式が変更された場合の推奨ワークフロー#

パーサーが作成されると、フィールドマッピングの設定はロックされるため、元となるスキャナーの形式変更に対応する標準的なワークフローは、古いパーサーを編集しようとするのではなく、新しいパーサーへ切り替えることです。

1. 新しいレポート形式のサンプルを使用して新しいユニバーサルパーサーを作成します(ステップ1を参照)。元の名前にv2や日付などを追加して、区別できる名前を付けてください。
2. CI/CDパイプラインまたはUIのワークフローで新規インポートを新しいパーサーのスキャンタイプに切り替えます。
3. 新しいパーサーが期待通りの検出事項を生成することを確認したら、古いパーサーを無効化します。古いパーサーで既にインポートされたテストはDefectDojo内に残り、引き続きトリアージできます。新規インポートのみが新しいパーサーに振り分けられます。

パーサー設定を完全に削除する必要がある場合(例えば、機密性の高いフィールド名が含まれている場合など)は、にお問い合わせください。

深刻度マッピングに関する注意事項#

ユニバーサルパーサーには、設定可能な深刻度マッピングフィールドはありません。深刻度は次のルールに従って自動的にマッピングされます。

• DefectDojoの深刻度の大文字小文字の違いはすべて受け入れられます — CRITICAL、Critical、cRiTiCaL、criticalはすべて重大にマッピングされます。High、Medium、Low、Infoについても同様です。
• DefectDojoの5つの深刻度のいずれにも一致しない値は情報にマッピングされます。

この動作は、DefectDojoのすべてのパーサー(組み込みパーサー、コネクタ、ユニバーサルパーサー)で共通です。

取り込もうとしているスキャナーが、DefectDojoと一致しない深刻度ラベル(「warning」「note」や数値のCVSSスコアなど)を使用している場合、ユニバーサルパーサーはそれらの一致しない値をすべて情報にマッピングします。異なるマッピングが必要な場合、現時点での最善の回避策は、アップロード前(例えばCIパイプライン内)に深刻度の値を事前に変換し、DefectDojoが受け取る値が既にDefectDojoの5つの深刻度名のいずれかになるようにすることです。