使用 VEX 建立例外

目錄

漏洞可利用性交換 (VEX) 是一個標準格式，用於在軟體包或產品的上下文中記錄漏洞。Docker Scout 支援 VEX 文件，以便為映象中的漏洞建立例外。

注意

您還可以使用 Docker Scout 儀表板或 Docker Desktop 建立例外。GUI 提供了一個使用者友好的介面來建立例外，並且可以輕鬆管理多個映象的例外。它還允許您一次為多個映象或整個組織建立例外。更多資訊，請參閱使用 GUI 建立例外。

前提條件

要使用 OpenVEX 文件建立例外，您需要

VEX 介紹

VEX 標準由美國網路安全和基礎設施安全域性 (CISA) 的工作組定義。VEX 的核心是可利用性評估。這些評估描述了產品中給定 CVE 的狀態。VEX 中可能的漏洞狀態有

  • 不受影響：不需要對該漏洞進行任何修復。
  • 受影響：建議採取措施修復或解決該漏洞。
  • 已修復：這些產品版本包含該漏洞的修復。
  • 調查中：尚不確定這些產品版本是否受該漏洞影響。將在後續版本中提供更新。

VEX 有多種實現和格式。Docker Scout 支援 OpenVex 實現。無論具體實現如何，核心思想是一致的：提供一個框架來描述漏洞的影響。無論實現如何，VEX 的關鍵元件包括

VEX 文件
一種安全公告，用於儲存 VEX 宣告。文件的格式取決於具體實現。
VEX 宣告
描述產品中漏洞的狀態，是否可利用，以及是否有方法修復該問題。
理由和影響
根據漏洞狀態，宣告包含理由或影響宣告，描述為什麼產品受或不受影響。
行動宣告
描述如何修復或減輕漏洞。

vexctl 示例

以下示例命令建立一個 VEX 文件，說明：

  • 此 VEX 文件描述的軟體產品是 Docker 映象 example/app:v1
  • 映象包含 npm 包 express@4.17.1
  • npm 包受已知漏洞 CVE-2022-24999 影響
  • 映象不受該 CVE 影響，因為在此映象執行的容器中，易受攻擊的程式碼從未被執行
$ vexctl create \
  --author="author@example.com" \
  --product="pkg:docker/example/app@v1" \
  --subcomponents="pkg:npm/express@4.17.1" \
  --vuln="CVE-2022-24999" \
  --status="not_affected" \
  --justification="vulnerable_code_not_in_execute_path" \
  --file="CVE-2022-24999.vex.json"

以下是此示例中選項的說明

--author
VEX 文件作者的電子郵件。
--product
Docker 映象的包 URL (PURL)。PURL 是一種標準化格式的映象識別符號，在 PURL 規範中定義。

Docker 映象 PURL 字串以 pkg:docker 型別字首開頭，後跟映象倉庫和版本（映象標籤或 SHA256 摘要）。與映象標籤（其中版本指定方式如 example/app:v1）不同，在 PURL 中，映象倉庫和版本由 @ 分隔。

--subcomponents
映象中易受攻擊包的 PURL。在此示例中，漏洞存在於 npm 包中，因此 --subcomponents PURL 是 npm 包名稱和版本的識別符號 (pkg:npm/express@4.17.1)。

如果同一個漏洞存在於多個包中，vexctl 允許您在單個 create 命令中多次指定 --subcomponents 標誌。

您也可以省略 --subcomponents，在這種情況下 VEX 宣告將適用於整個映象。

--vuln
VEX 宣告針對的 CVE ID。
--status
這是漏洞的狀態標籤。這描述了軟體（--product）和 CVE（--vuln）之間的關係。OpenVEX 中狀態標籤的可能值有
  • not_affected
  • affected
  • fixed
  • under_investigation

在此示例中，VEX 宣告斷言 Docker 映象不受該漏洞影響 (not_affected)。not_affected 狀態是唯一導致 CVE 抑制（即 CVE 從分析結果中過濾掉）的狀態。其他狀態對於文件記錄很有用，但不能用於建立例外。有關所有可能狀態標籤的更多資訊，請參閱 OpenVEX 規範中的 狀態標籤。

--justification
合理解釋 not_affected 狀態標籤，說明產品為何不受該漏洞影響。在此情況下，給出的理由是 vulnerable_code_not_in_execute_path，表明該漏洞無法在該產品的使用場景下被執行。

在 OpenVEX 中，狀態理由可以有以下五種可能值

  • component_not_present
  • vulnerable_code_not_present
  • vulnerable_code_not_in_execute_path
  • vulnerable_code_cannot_be_controlled_by_adversary
  • inline_mitigations_already_exist

有關這些值及其定義的更多資訊，請參閱 OpenVEX 規範中的 狀態理由。

--file
VEX 文件輸出的檔名

JSON 文件示例

這是此命令生成的 OpenVEX JSON

{
  "@context": "https://openvex.dev/ns/v0.2.0",
  "@id": "https://openvex.dev/docs/public/vex-749f79b50f5f2f0f07747c2de9f1239b37c2bda663579f87a35e5f0fdfc13de5",
  "author": "author@example.com",
  "timestamp": "2024-05-27T13:20:22.395824+02:00",
  "version": 1,
  "statements": [
    {
      "vulnerability": {
        "name": "CVE-2022-24999"
      },
      "timestamp": "2024-05-27T13:20:22.395829+02:00",
      "products": [
        {
          "@id": "pkg:docker/example/app@v1",
          "subcomponents": [
            {
              "@id": "pkg:npm/express@4.17.1"
            }
          ]
        }
      ],
      "status": "not_affected",
      "justification": "vulnerable_code_not_in_execute_path"
    }
  ]
}

理解 VEX 文件應該如何結構化可能有些費力。 OpenVEX 規範描述了文件和宣告的格式以及所有可能的屬性。有關完整詳情，請參閱該規範，瞭解有關可用欄位以及如何建立結構良好的 OpenVEX 文件的更多資訊。

要了解有關 vexctl CLI 工具的可用標誌和語法以及如何安裝它，請參閱 vexctl GitHub 倉庫。

驗證 VEX 文件

要測試您建立的 VEX 文件是否結構良好併產生預期結果，請使用帶有 `--vex-location` 標誌的 `docker scout cves` 命令，以便使用 CLI 將 VEX 文件應用於本地映象分析。

以下命令呼叫本地映象分析，該分析使用 `--vex-location` 標誌，幷包含指定位置中的所有 VEX 文件。在此示例中，CLI 被指示在當前工作目錄中查詢 VEX 文件。

$ docker scout cves <IMAGE> --vex-location .

docker scout cves 命令的輸出會顯示結果，其中考慮了在 `--vex-location` 位置下找到的任何 VEX 宣告。例如，狀態被標記為 not_affected 的 CVE 會從結果中過濾掉。如果輸出似乎沒有考慮 VEX 宣告，這表明 VEX 文件可能以某種方式無效。

需要注意的事項包括

  • Docker 映象的 PURL 必須以 pkg:docker/ 開頭，後跟映象名稱。
  • 在 Docker 映象 PURL 中，映象名稱和版本由 @ 分隔。名為 example/myapp:1.0 的映象具有以下 PURL：pkg:docker/example/myapp@1.0。
  • 記得指定 author（這是 OpenVEX 中的必填欄位）
  • OpenVEX 規範描述瞭如何以及何時在 VEX 文件中使用 justification、impact_statement 和其他欄位。以不正確的方式指定這些欄位會導致文件無效。請確保您的 VEX 文件符合 OpenVEX 規範。

將 VEX 文件附加到映象

當您建立了 VEX 文件後，可以透過以下方式將其附加到您的映象

VEX 文件一旦新增到映象就無法移除。對於作為證明附加的文件，您可以建立一個新的 VEX 文件並再次將其附加到映象。這樣做會覆蓋之前的 VEX 文件（但不會移除證明本身）。對於 VEX 文件已嵌入映象檔案系統的映象，您需要重建映象才能更改 VEX 文件。

證明

要將 VEX 文件作為證明附加，您可以使用 `docker scout attestation add` CLI 命令。使用證明是將例外附加到映象時的推薦選項。

您可以將證明附加到已推送到登錄檔的映象。您不需要再次構建或推送映象。此外，將例外作為證明附加到映象意味著使用者可以直接從登錄檔檢查映象的例外。

將證明附加到映象

  1. 構建映象並將其推送到登錄檔。

    $ docker build --provenance=true --sbom=true --tag <IMAGE> --push .

  2. 將例外作為證明附加到映象。

    $ docker scout attestation add \
  --file <cve-id>.vex.json \
  --predicate-type https://openvex.dev/ns/v0.2.0 \
  <IMAGE>

    此命令的選項包括

    • --file：VEX 文件的位置和檔名
    • --predicate-type：OpenVEX 的 in-toto predicateType

映象檔案系統

將 VEX 文件直接嵌入到映象檔案系統中是個不錯的選擇，如果您在構建映象之前就已經知道這些異常。這相對來說也很簡單；只需在 Dockerfile 中使用 COPY 命令將 VEX 文件複製到映象中即可。

這種方法的缺點是您以後無法更改或更新異常。映象層是不可變的，因此您放入映象檔案系統中的任何內容都會永久存在。將文件作為證明附加則提供了更好的靈活性。

注意

對於包含證明的映象，嵌入在映象檔案系統中的 VEX 文件將不被考慮。如果您的映象包含任何證明，Docker Scout 將僅在證明中查詢異常，而不會在映象檔案系統中查詢。

如果您想使用嵌入在映象檔案系統中的 VEX 文件，則必須從映象中移除證明。請注意，映象可能會自動新增來源（provenance）證明。為確保映象不新增任何證明，您可以在構建映象時使用 --provenance=false 和 --sbom=false 標誌明確停用 SBOM 和來源證明。

要將 VEX 文件嵌入到映象檔案系統中，請在映象構建過程中使用 COPY 命令將檔案複製到映象中。以下示例展示瞭如何將構建上下文中的 .vex/ 目錄下的所有 VEX 文件複製到映象中的 /var/lib/db 目錄。

# syntax=docker/dockerfile:1

FROM alpine
COPY .vex/* /var/lib/db/

VEX 文件的檔名必須匹配 *.vex.json 的全域性模式。檔案儲存在映象檔案系統中的任何位置都可以。

請注意，複製的檔案必須是最終映象檔案系統的一部分。對於多階段構建，文件必須在最終階段中保留。

頁面選項