使用 VEX 创建例外

目录

Vulnerability Exploitability eXchange (VEX) 是一种用于在软件包或产品的上下文中记录漏洞的标准格式。Docker Scout 支持 VEX 文档来为镜像中的漏洞创建例外。

注意

您还可以使用 Docker Scout Dashboard 或 Docker Desktop 创建例外。GUI 提供了一个用户友好的界面来创建例外，并且易于管理多个镜像的例外。它还允许您一次性为多个镜像或整个组织创建例外。有关更多信息，请参阅使用 GUI 创建例外。

先决条件

要使用 OpenVEX 文档创建例外，您需要

  • 最新版本的 Docker Desktop 或 Docker Scout CLI 插件
  • vexctl 命令行工具。
  • 必须启用 containerd 镜像存储
  • 对存储镜像的注册表仓库的写入权限

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 中状态标签的可能值为
  • 未受影响
  • 受影响
  • 已修复
  • 正在调查中

在此示例中，VEX 声明断言 Docker 镜像“未受漏洞影响”。not_affected 状态是唯一导致 CVE 抑制的状态，其中 CVE 从分析结果中过滤掉。其他状态对于文档编制很有用，但它们不适用于创建例外。有关所有可能的状态标签的更多信息，请参阅 OpenVEX 规范中的状态标签。

--justification
证明 not_affected 状态标签的合理性，说明产品为何不受漏洞影响。在此情况下，给出的理由是 vulnerable_code_not_in_execute_path，表示漏洞不能在产品使用时执行。

在 OpenVEX 中，状态理由可以有以下五个可能值之一

  • 组件不存在
  • 易受攻击的代码不存在
  • 易受攻击的代码不在执行路径中
  • 易受攻击的代码无法被攻击者控制
  • 已存在内联缓解措施

有关这些值及其定义的更多信息，请参阅 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 文档是否格式正确并产生预期结果，请使用 docker scout cves 命令并带有 --vex-location 标志，以使用 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 文X 文档。

证明

要将 VEX 文档作为证明附加，您可以使用 docker scout attestation add CLI 命令。在使用 VEX 时，使用证明是为镜像附加例外推荐的选项。

您可以将证明附加到已推送到注册表的镜像。您无需再次构建或推送镜像。此外，将例外作为证明附加到镜像意味着使用者可以直接从注册表检查镜像的例外。

要将证明附加到镜像

  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 中将 VEX 文档 COPY 到镜像中即可。

这种方法的缺点是您以后无法更改或更新例外。镜像层是不可变的，因此您放入镜像文件系统中的任何内容都将永远存在。将文档作为证明附加可提供更好的灵活性。

注意

嵌入在镜像文件系统中的 VEX 文档不会被视为具有证明的镜像。如果您的镜像有**任何**证明，Docker Scout 将只在证明中查找例外，而不会在镜像文件系统中查找。

如果要使用嵌入在镜像文件系统中的 VEX 文档，则必须从镜像中删除证明。请注意，可能会自动为镜像添加出处证明。为确保不向镜像添加任何证明，您可以在构建镜像时使用 --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 全局模式匹配。文件存储在镜像文件系统上的哪个位置无关紧要。

请注意，复制的文件必须是最终镜像文件系统的一部分。对于多阶段构建，文档必须保留在最终阶段。

© . This site is unofficial and not affiliated with Kubernetes or Docker Inc.