REST API を使用したソフトウェア部品表ファイルのアップロード

API を使用してソフトウェア部品表ファイルをアップロードする前に、次の情報を確認してください。

REST API の使用

API を使用して SBOM をアップロードするには、sn_sbom_core.sbom_ingest ロールが必要です。

アップロード API。

この API は、SBOM ファイル (CycloneDX / SPDX) をインスタンスにアップロードして取り込む際に使用されます。

SBOM Core v4.0 では、以下がサポートされています。

• CycloneDx の XML と JSON (バージョン 1.0～1.6)。
• SPDX の JSON (バージョン 2.2～2.3)
• 注:

  32 MB 以上のファイルの場合、正しく読み込まれない場合があります。

HTTP メソッド：(POST)

API URL：<host_name>/api/sbom/core/upload

注:

<host_name> は ServiceNow インスタンス名です。

以下の要求パラメーターはすべてオプションです。要求本文は SBOM ファイルのコンテンツとなります。開発プロセスの一環で DevOps を使用している場合、「requestedBy」の値を「devops」にする必要があります。DevOps の一般的な情報については、「DevOps SBOM ファイルの ソフトウェア部品表 のアップロード」を参照してください。「requestedby」の値が「devops」(開発運用) の場合、次のパラメーターが必須となります。

• buildId
• lifecycleStage

さらに、「requestedBy」が「devops」の場合、「fetchVulenrabilityInfo」と「fetchPackageInfo」のデータが含まれます。

• buildId：送信する文字列
• lifecycleStage：2 つの値 (「production」または「pre_production」)
• fetchVulenrabilityInfo：t/f
• fetchPackageInfo：t/f

要求パラメーター	可能な値	説明
productModelId	Sys ID	指定された SBOMのルートアプリケーションでマッピングする製品モデルの Sys ID。
businessApplicationId	Sys ID	指定された SBOM のルートアプリケーションでマッピングするビジネスアプリケーションの Sys ID。
businessApplicationName (非推奨)	ビジネスアプリケーション名	指定された SBOMのルートアプリケーションでマッピングするビジネスアプリケーションの名前。
sbomSource	たとえば、 Veracodeなどの製品	SBOMファイルのソース。
requestedBy	メソドロジーツールやメソドロジー名。「Jenkins」など。「devops」を使用する場合、「buildId」と「lifecycleStage」は必須です。	アップロード要求者
buildId	要求者が送信する文字列。	SBOMビルドのビルド ID。
lifecycleStage	「production」または「pre_production」	エンティティのライフサイクルステージ。
fetchVulenrabilityInfo	t/f (正/誤)	「true」の場合、脆弱性インテリジェンス統合がトリガーされます。
fetchPackage 情報	t/f (正/誤)	「true」の場合、パッケージインテリジェンス統合がトリガーされます。

アップロード API 応答:「status」の成功/失敗、「message」(文字列)、「bomRecordId」(アップロード API を介して返される SBOM の Sys ID) が含まれていました。

{

"result": {

"status": "success",

"message": "Queued for processing.",

"bomRecordId": "f207059b4393c290629aa597cbb8f247"

}

}

ステータス API

この API を使用して、取り込みのキューに入れられている SBOM のステータスやサマリーを取得します。

• API URL：/api/sbom/core/upload/status
• HTTP メソッド (GET)

要求パラメーター	可能な値	説明
bomRecordId	Sys ID	アップロード API を介して返される SBOM レコード ID です。これにより SBOM アップロードが正常に行われます。

ステータス API のデフォルトの応答例。

{
   "result": {
      "bomRecordId": "0407c0fea3e70a505df340f5251e617e",
      "uploadStatus": "processed",
      "additionalInfoStatus": "not_requested",
      "uploadSummary": {
         "components": {
            "added": 0,
            "removed": 0,
            "total": 70
         }
       }
    } 
}

追加のパラメーターを使用したステータス API 応答の例。当該 SBOM の fetchVulenrabilityInfo を要求した場合、応答の一部として脆弱性のブレークダウンを取得できます。

{
 "result": {

  "bomRecordId": "93af349b4393c290629aa597cbb8f258",

  "uploadStatus": "processed",

  "additionalInfoStatus": "complete",

  "uploadSummary": {

    "components": {
 
     "added": 0,

     "removed": 0,

     "total": 3

   },

   "vulnerabilityInfo": {

    "critical": 0,

    "high": 0,

    "medium": 0,

    "low": 0,

    "none": 0

   }

  },

  "buildId": "1"

 }

}

当該 SBOM の fetchPackageInfo を要求した場合、応答の一部として「古い」および「破棄」カウントを取得できます。

SBOM が正常に処理された後、アップロードされたレコードを表示する場所は、使用しているアプリケーションにより異なります。

• SBOM Response を使用している場合、BOM エンティティレコードは、SBOM ワークスペースの BOM キューモジュールの [SBOM 取り込みステータス] リストに表示されます。
• SBOM Core を使用している場合は、次に移動します: SBOM Core > BOM 取り込みステータス.

サポートされている SBOM 標準と一般的な使用情報の強化

SBOM Core v4.0 では、以下がサポートされています。

• CycloneDx の XML と JSON (バージョン 1.0～1.6)。
• SPDX の JSON (バージョン 2.2～2.3)
• 注:

  32 MB 以上のファイルの場合、正しく読み込まれない場合があります。

SBOM Core v4.0 以降、v1.0～1.6 の CycloneDx 標準をサポートするために、次の機能が拡張されました。

• CycloneDX SBOM ファイルの追加情報を (sn_sbom_core.collect_properties) プロパティでインポートします。このプロパティはデフォルトで非アクティブ化されています。一般的にサポートされていない情報をインポートするには、このプロパティを有効にします。これらのプロパティからインポートされた情報は、次の SBOM コンポーネントプロパティ [sn_sbom_comp_property] テーブルにアップロードされます。
  • アップロードされた SBOM ファイル
  • メタデータ
  • 個々の脆弱性
  • コンポーネント
• CycloneDX v1.4 以降、SBOM ファイルの宣言および締結ライセンスに関するインポート済みのコンポーネントデータが、次の 2 つの新しいライセンスフィールドに表示されます。
  • 宣言済み
  • 締結
• SBOM 構文解析のサポートが、以下の CycloneDX コンポーネントタイプに拡張されました。
  • バージョン 1.5：プラットフォーム、データ、デバイス ドライバー、機械学習モデル
  • バージョン 1.6：暗号化

SBOM Core v3.0 では、以下がサポートされています。

• CycloneDx の XML と JSON ( v1.4 以前)
• SPDX の JSON (v2.3 以前)

呼び出し元ユーザーが適切に認証されており、ServiceNow インスタンスで sn_sbom_core.sbom_ingest ロールを持っている場合は、インスタンスの外部から API にアクセスして SBOM データをアップロードすることができます。

データはアップロードされた後、解析されます。データの解析前に、次の要件が検証されます。

• 受信データにおいて、JSON または XML が有効であることを確認します。
• BOM 形式がサポートされている。SBOM Core v2.1 以降、CycloneDX (JSON や XML) および SPDX (XML) 形式がサポートされています。
• データを解析できるように、最小限のフィールドが利用可能である。

これらのチェックの検証後に、部品表 [sn_sbom_doc] テーブルにエントリが作成され、受信 SBOM データが添付ファイルとして含まれます。

Process BOM fileビジネスルールは、レコードの挿入とデータの解析の結果として自動的にトリガーされます。

注:

このビジネスルールは、SBOM Core のインストール時にデフォルトでアクティブになります。

SBOM にリストされているすべてのコンポーネントには、type が定義されています。

• SBOM ファイルがアップロードされているコンポーネントは、BOM エンティティと見なされます。
• type=library としてリストされているコンポーネントは、サードパーティコンポーネントと見なされます。

関連概念

• ソフトウェア部品表ワークスペースでのレポートとダッシュボードの表示

関連タスク

• ソフトウェア部品表ファイルのアップロードステータスを表示