本頁面由 Cloud Translation API 翻譯而成。

自動掃描 Node.js 套件

本文說明如何啟用 Container Scanning API、將映像檔推送至 Artifact Registry，以及查看映像檔中發現的安全漏洞清單。

Artifact Analysis 會將安全漏洞資訊儲存為附註。每當某個映像檔有相關聯的註記時，系統便會建立相對應的例項。詳情請參閱總覽和定價文件。

事前準備

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry and Container Scanning APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry and Container Scanning APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

在 Artifact Registry 中建立 Docker 存放區，並將含有 npm 程式碼的容器映像檔推送至存放區。如果您不熟悉 Artifact Registry，請參閱 Docker 快速入門導覽課程。

查看映像檔安全漏洞

將新的映像檔上傳至 Artifact Registry 時，Artifact Analysis 會掃描這些映像檔。這項掃描會擷取容器中套件的相關資訊。

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 Container Analysis API，查看 Artifact Registry 中映像檔的安全漏洞例項。如果映像檔有安全漏洞，您就可以取得詳細資料。

Artifact Analysis 只會更新過去 30 天內推送或提取的映像檔中繼資料。30 天後，中繼資料將不再更新，結果也會過時。此外，Artifact Analysis 會封存過時逾 90 天的中繼資料，且這些中繼資料不會顯示在 Google Cloud 控制台、gcloud 或 API 中。如要重新掃描中繼資料已過時或已封存的映像檔，請提取該映像檔。重新整理中繼資料最多可能需要 24 小時才能完成。

在 Google Cloud 控制台中查看發生次數

如要查看映像檔中的安全漏洞：

取得存放區清單。

開啟「Repositories」(存放區) 頁面
在存放區清單中，按一下存放區。
在圖片清單中，按一下圖片名稱。

每個映像檔摘要的安全漏洞總數會顯示在「Vulnerabilities」(安全漏洞) 資料欄中。
如要查看映像檔的安全漏洞清單，請按一下「Vulnerabilities」(安全漏洞) 資料欄中的連結。

「掃描結果」部分會顯示掃描的套件類型摘要、安全漏洞總數、有修正檔的安全漏洞、沒有修正檔的安全漏洞，以及有效嚴重程度。

安全漏洞表格會列出每個安全漏洞的常見安全漏洞與資料外洩風險 (CVE) 名稱、實際嚴重程度、常見安全漏洞評分系統 (CVSS) 分數、修正 (如有)、內含安全漏洞的套件名稱，以及套件類型。您可以篩選及排序這些檔案，依副檔名檢查特定檔案、目錄或檔案類型。 Google Cloud 主控台會在表格中顯示最多 1200 個網頁的安全性弱點。
如要查看特定 CVE 的詳細資料，請按一下 CVE 名稱。
如要查看安全漏洞發生詳細資料，例如版本號碼和受影響的位置，請在安全漏洞名稱的資料列中，按一下「查看」或「查看已修正」。如果安全漏洞尚未修正，連結文字會顯示「查看」；如果安全漏洞已修正，連結文字則會顯示「查看已修正」。

使用 gcloud 查看發生次數

如要查看 Artifact Registry 中映像檔的例項，請執行 gcloud artifacts docker images list 指令：

gcloud artifacts docker images list --show-occurrences \
    LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

其中：

LOCATION 是存放區的區域或多區域位置。
PROJECT_ID 是您的 Google Cloud 控制台專案 ID。
REPOSITORY 是儲存映像檔的存放區名稱。
IMAGE_ID 是存放區中的映像檔名稱。您無法使用此指令指定圖片標記。

根據預設，這項指令會傳回最近 10 個映像檔。如要顯示不同數量的圖片，請使用 --show-occurrences-from 旗標。舉例來說，下列指令會傳回最近 25 張圖片：

gcloud artifacts docker images list --show-occurrences-from=25 \
    us-central1-docker.pkg.dev/my-project/my-repo/my-image

輸出內容大致如下：

圖片輸出範例

  {
      "name": "projects/my-project/locations/us-central1/occurrences/22d3edfb-34f2-4d3f-be08-fd90c549f010",
      "resource": {
        "uri": "https://us-central1-docker.pkg.dev/my-project/my-repo/golang-nginx@sha256:5b54ef20748417ccdb0b87afedf98c44e699e2f59bd6cv48cbdc1ca2e72c80e3"
      },
      "noteName": "projects/my-project/locations/us-central1/notes/CVE-2005-2541",
      "kind": "VULNERABILITY",
      "createTime": "2025-01-21T15:57:01.238832Z",
      "updateTime": "2025-01-21T15:57:01.238832Z",
      "vulnerability": {
        "severity": "CRITICAL",
        "cvssScore": 10,
        "packageIssue": [
          {
            "affectedLocation": {
              "cpeUri": "cpe:/o:debian:debian_linux:12",
              "package": "tar",
              "version": {
                "name": "1.34+dfsg",
                "revision": "1.2+deb12u1",
                "kind": "NORMAL"
              }
            },
            "fixedLocation": {
              "cpeUri": "cpe:/o:debian:debian_linux:12",
              "package": "tar",
              "version": {
                "kind": "MAXIMUM"
              }
            },
            "packageType": "OS",
            "effectiveSeverity": "LOW",
            "file_location": [
                {
                "file_path": "/var/lib/dpkg/status",
                "layerDetails": {
                  "index": 0,
                  "diffID": "sha256:123",
                  "buildCommand": "FROM golang:example_sha256",
                  "BaseImages": [
                    {
                      "name": "library/golang",
                    },
                  ],
                },
              },
            ],
          }
        ],
        "shortDescription": "CVE-2005-2541",
        "longDescription": "NIST vectors: AV:N/AC:L/Au:N/C:C/I:C/A:C",
        "relatedUrls": [
          {
            "url": "https://security-tracker.debian.org/tracker/CVE-2005-2541",
            "label": "More Info"
          }
        ],
        "effectiveSeverity": "LOW",
        "cvssVersion": "CVSS_VERSION_2",
        "cvssV2": {
          "baseScore": 10,
          "attackVector": "ATTACK_VECTOR_NETWORK",
          "attackComplexity": "ATTACK_COMPLEXITY_LOW",
          "authentication": "AUTHENTICATION_NONE",
          "confidentialityImpact": "IMPACT_COMPLETE",
          "integrityImpact": "IMPACT_COMPLETE",
          "availabilityImpact": "IMPACT_COMPLETE"
        }
      }
    }

查看映像檔標記的安全漏洞

如要查看映像檔標記的安全漏洞，請輸入下列其中一個指令：

gcloud artifacts docker images describe \
    LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID:TAG \
    --show-package-vulnerability

或

gcloud artifacts docker images describe \
    LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@sha256:HASH \
    --show-package-vulnerability

其中：

LOCATION 是存放區的區域或多區域位置。
PROJECT_ID 是您的 Google Cloud 控制台專案 ID。
REPOSITORY 是儲存映像檔的存放區名稱。
IMAGE_ID 是存放區中的映像檔名稱。
TAG 是您要取得相關資訊的映像檔標記。
HASH 是映像檔摘要。

Artifact Analysis 會傳回結果，包括 packageType。

篩選安全漏洞例項

如要篩選安全漏洞例項，請使用 --occurrence-filter 參數：

gcloud artifacts docker images list --show-occurrences \
    LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID \
    --occurrence-filter=FILTER_EXPRESSION

其中：

LOCATION 是存放區的區域或多區域位置。
PROJECT_ID 是您的 Google Cloud 控制台專案 ID。
REPOSITORY 是儲存映像檔的存放區名稱。
IMAGE_ID 是存放區中的映像檔名稱。
FILTER_EXPRESSION 是採用篩選安全漏洞例項一文所述格式的篩選器運算式範例。

查看特定層的安全漏洞

您可以使用 layerDetails 欄位，判斷哪個特定層引進了有安全漏洞的套件，並查看該層的其他資訊。舉例來說，請參考以下圖片的 layerDetails 輸出內容：

  "layerDetails": {
    "index": 0,
    "diffID": "sha256:123",
    "buildCommand": "FROM golang:example_sha256",
    "BaseImages": [
      {
        "name": "library/golang",
      },
    ],
  }

輸出內容顯示容器映像檔中的層索引為 0，層雜湊為 sha256:123。用於建構這個層的 Docker 建構指令是 FROM golang:example_sha256，這個層也會出現在 library/golang 基本映像檔中。

使用 API 查看發生次數

如何取得專案的例項清單：

 curl -X GET -H "Content-Type: application/json" -H \
    "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences

如何取得專案的安全漏洞匯總資料：

 curl -X GET -H "Content-Type: application/json" -H \
    "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences:vulnerabilitySummary

如要取得特定例項的詳細資料：

 curl -X GET -H "Content-Type: application/json" -H \
    "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences/OCCURRENCE_ID

在 Cloud Build 中查看安全漏洞

如果您使用 Cloud Build，也可以在 Google Cloud 控制台的「安全性洞察」側邊面板中查看映像檔安全漏洞。

「安全性深入分析」側邊面板會顯示儲存在 Artifact Registry 中的構件建構安全性資訊總覽。如要進一步瞭解側邊面板，以及如何使用 Cloud Build 協助保護軟體供應鏈，請參閱「查看建構作業安全性洞察資訊」。

篩選例項

您可以在 gcloud 指令和 Artifact Analysis API 中使用篩選字串，在查看之前先篩選例項。下列各節說明支援的搜尋篩選器。

查看特定類型的例項

你可以使用 kind 值，依發生類型篩選。請參閱可用的種類。

以下範例說明如何篩選映像檔的部署例項：

gcloud

在 gcloud CLI 中執行下列指令：

gcloud artifacts docker images list --show-occurrences \
    --occurrence-filter='kind="DEPLOYMENT"' --format=json \
    LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

其中：

DEPLOYMENT 是例項的種類。
LOCATION 是存放區的區域或多區域位置。
PROJECT_ID 是您的 Google Cloud 控制台專案 ID。
REPOSITORY 是儲存映像檔的存放區名稱。
IMAGE_ID 是存放區中的映像檔名稱。

API

在 API 查詢中，使用下列篩選運算式：

kind="DEPLOYMENT" AND resourceUrl="RESOURCE_URL"

其中：

DEPLOYMENT 是例項的種類。
RESOURCE_URL 是圖片的完整網址，格式為 https://LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@sha256:HASH。

您可以使用 hasPrefix 函式，以更廣泛的範圍進行篩選。

舉例來說，下列篩選器可針對多個圖片擷取特定種類的例項：

kind="NOTE_KIND" AND has_prefix(resourceUrl, "RESOURCE_URL_PREFIX")

其中：

RESOURCE_URL_PREFIX：指定資源網址中的子字串。
- 如要篩選圖片的所有版本，請省略圖片摘要。請使用下列格式：https://LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@
- 如要篩選專案中的所有映像檔，請只指定資源位置和專案。請使用下列格式：https://LOCATION-docker.pkg.dev/PROJECT_ID/

查看安全漏洞例項

如要擷取映像檔的安全漏洞例項清單，可以依 VULNERABILITY 例項類型篩選。

gcloud

在 gcloud CLI 中執行下列指令：

gcloud artifacts docker images list \
    --show-occurrences \
    --occurrence-filter='kind="VULNERABILITY"' \
    --format=json \
    LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

其中：

VULNERABILITY 是例項的種類。
LOCATION 是存放區的區域或多區域位置。
PROJECT_ID 是您的 Google Cloud 控制台專案 ID。
REPOSITORY 是儲存映像檔的存放區名稱。
IMAGE_ID 是存放區中的映像檔名稱。

API

在 API 查詢中，使用下列篩選運算式：

GET https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences?filter=kind%3D%22VULNERABILITY%22%20AND%20resourceUrl%3D%22ENCODED_RESOURCE_URL%22

其中：

ENCODED_RESOURCE_URL 是圖片的編碼路徑。如要瞭解編碼，請參閱網址編碼。

如要進一步瞭解如何使用 API，請參閱 projects.occurrences.get。

依套裝組合類型篩選

如要將安全漏洞掃描結果限制為一種套件類型，請執行下列 gcloud CLI 指令：

  gcloud artifacts docker images list /
      --show-occurrences /
      --occurrence-filter='kind="VULNERABILITY" AND packageType="PACKAGE_TYPE"' /
      LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

其中：

VULNERABILITY 是例項的種類。
PACKAGE_TYPE 是應用程式語言套件類型。可用的類型包括：COMPOSER、GO、MAVEN、NPM、NUGET、PYTHON、RUBYGEMS 和 RUST。
LOCATION 是存放區的區域或多區域位置。
PROJECT_ID 是您的 Google Cloud 控制台專案 ID。
REPOSITORY 是儲存映像檔的存放區名稱。
IMAGE_ID 是存放區中的映像檔名稱。您無法使用此指令指定圖片標記。

查看與特定記事相關聯的圖片

您可以擷取與特定註記 ID 相關聯的資源清單。舉例來說，您可以使用特定 CVE 安全漏洞來列出映像檔。

如要列出專案中與特定註記相關聯的的所有映像檔，請使用下列篩選器運算式：

gcloud

gcloud artifacts docker images list /
    --show-occurrences /
    --occurrence-filter='noteProjectId="goog-vulnz" AND noteId="NOTE_ID"' /
    LOCATION-docker.pkg.dev/PROJECT_ID

其中：

goog-vulnz 是 Artifact Analysis 漏洞分析的 PROVIDER_PROJECT_ID。如果您在自訂專案中使用構件分析，可以將這個值替換為自己的供應商專案 ID。
LOCATION 是存放區的區域或多區域位置。
PROJECT_ID 是您的 Google Cloud 控制台專案 ID。
NOTE_ID 是註記的 ID。舉例來說，當您在構件分析掃描結果中看到安全性漏洞時，通常會使用類似 CVE-2019-12345 的 CVE ID 格式。

API

GET https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences?filter=noteProjectId%3D%22goog-vulnz%22%20AND%20resourceUrl%3D%22ENCODED_RESOURCE_URL%22%20AND%20noteId%3D%22NOTE_ID%22

其中：

goog-vulnz 是 Artifact Analysis 漏洞分析的 PROVIDER_PROJECT_ID。如果您在自訂專案中使用構件分析，可以將這個值替換為自己的供應商專案 ID。
ENCODED_RESOURCE_URL 是圖片的編碼路徑。如要瞭解編碼，請參閱網址編碼。
NOTE_ID 是註記的 ID。舉例來說，當您在構件分析掃描結果中看到安全性漏洞時，通常會使用類似 CVE-2019-12345 的 CVE ID 格式。

如要查看特定註記的特定映像檔，請使用下列篩選器運算式：

gcloud

gcloud artifacts docker images list /
    --show-occurrences /
    --occurrence-filter='noteProjectId="goog-vulnz" AND noteId="NOTE_ID"' /
    LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

地點

LOCATION 是存放區的區域或多區域位置。
PROJECT_ID 是您的 Google Cloud 控制台專案 ID。
REPOSITORY 是儲存映像檔的存放區名稱。
IMAGE_ID 是存放區中的映像檔名稱。您無法使用此指令指定圖片標記。

API

在 API 查詢中，加入下列篩選運算式：

resourceUrl="RESOURCE_URL" AND noteProjectId="goog-vulnz" \
AND noteId="NOTE_ID"

其中：

RESOURCE_URL 是圖片的完整網址，格式為 https://LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@sha256:HASH。
goog-vulnz 是 Artifact Analysis 漏洞分析的 PROVIDER_PROJECT_ID。如果您在自訂專案中使用構件分析，可以將這個值替換為自己的供應商專案 ID。
NOTE_ID 是註記的 ID。安全性相關註記的格式通常為 CVE-2019-12345。

後續步驟

使用 Pub/Sub 通知，接收安全漏洞和其他中繼資料的通知。
您可以使用 Kritis Signer 和 Voucher，在建構管道中建立二進位授權認證。這些工具可根據安全漏洞掃描結果建立二進位授權認證。詳情請參閱「透過 Kritis Signer 建立認證」或「透過 Voucher 建立認證」。

自動掃描 Node.js 套件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

查看映像檔安全漏洞

在 Google Cloud 控制台中查看發生次數

使用 gcloud 查看發生次數

圖片輸出範例

查看映像檔標記的安全漏洞

篩選安全漏洞例項

查看特定層的安全漏洞

使用 API 查看發生次數

在 Cloud Build 中查看安全漏洞

篩選例項

查看特定類型的例項

gcloud

API

查看安全漏洞例項

gcloud

API

依套裝組合類型篩選

查看與特定記事相關聯的圖片

gcloud

API

gcloud

API

後續步驟

自動掃描 Node.js 套件