Docker Scout 指标导出器

Docker Scout 暴露了一个指标 HTTP 端点，使您能够通过 Prometheus 或 Datadog 抓取 Docker Scout 中的漏洞和策略数据。借助该功能，您可以构建自己的、自托管的 Docker Scout 仪表板，以可视化供应链指标。

指标

指标端点公开以下指标：

指标	描述	标签	类型
`scout_stream_vulnerabilities`	流中的漏洞	`streamName`, `severity`	Gauge
`scout_policy_compliant_images`	流中策略的合规镜像	`id`, `displayName`, `streamName`	Gauge
`scout_policy_evaluated_images`	在流中根据策略评估的镜像总数	`id`, `displayName`, `streamName`	Gauge

流
在 Docker Scout 中，流（streams）概念是环境（environments）的超集。流包含您已定义的所有运行时环境，以及特殊的 latest-indexed 流。 latest-indexed 流包含每个镜像仓库中最近推送（并已完成分析）的标签。
Streams 主要是 Docker Scout 中的一个内部概念，唯一的例外是通过此指标端点暴露的数据。

创建访问令牌

若要从您的组织导出指标，请首先确保您的组织已注册 Docker Scout。接着，创建一个个人访问令牌（PAT）——一种允许导出器对 Docker Scout API 进行身份验证的密钥令牌。

PAT 不需要任何特定权限，但必须由 Docker 组织的管理员（owner）创建。要创建 PAT，请按照以下步骤操作：创建访问令牌。

创建个人访问令牌（PAT）后，请将其存储在安全位置。在抓取指标时，您需要向导出器提供此令牌。

Prometheus

本节介绍如何使用 Prometheus 抓取指标端点。

为您的组织添加任务

在 Prometheus 配置文件中，为您的组织添加一个新任务。该任务应包含以下配置；请将 ORG 替换为您的组织名称：

scrape_configs:
  - job_name: <ORG>
    metrics_path: /v1/exporter/org/<ORG>/metrics
    scheme: https
    static_configs:
      - targets:
          - api.scout.docker.com

targets 字段中的地址已设置为 Docker Scout API 的域名 api.scout.docker.com。请确保服务器与该端点通信时，未被任何防火墙规则阻止。

添加承载令牌身份验证

要使用 Prometheus 抓取 Docker Scout Exporter 端点的指标，您需要配置 Prometheus，使其将 PAT 作为承载令牌（bearer token）使用。该导出器要求在请求的 Authorization 头部中传递 PAT。

更新 Prometheus 配置文件，以包含 authorization 配置块。该配置块将 PAT 定义为存储在文件中的承载令牌（bearer token）：

scrape_configs:
  - job_name: $ORG
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/token

文件内容应为纯文本格式的 PAT（个人访问令牌）：

dckr_pat_...

如果您在 Docker 容器或 Kubernetes Pod 中运行 Prometheus，请使用卷或密钥将该文件挂载到容器中。

最后，重启 Prometheus 以应用更改。

Prometheus 示例项目

如果您尚未设置 Prometheus 服务器，可以使用 Docker Compose 运行一个示例项目。该示例包含一个 Prometheus 服务器，用于抓取已加入 Docker Scout 的 Docker 组织的指标数据，以及一个预配置了漏洞和策略指标可视化仪表盘的 Grafana。

克隆起始模板，以引导一组用于抓取和可视化 Docker Scout 指标端点的 Compose 服务：

$ git clone git@github.com:dockersamples/scout-metrics-exporter.git
$ cd scout-metrics-exporter/prometheus

创建 Docker 访问令牌并将其存储在模板目录下的 /prometheus/prometheus/token 的纯文本文件中。
令牌
$ echo $DOCKER_PAT > ./prometheus/token

在 /prometheus/prometheus/prometheus.yml 处的 Prometheus 配置文件中，将第 6 行 metrics_path 属性中的 ORG 替换为您的 Docker 组织的命名空间。

prometheus/prometheus.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
global:
  scrape_interval: 60s
  scrape_timeout: 40s
scrape_configs:
  - job_name: Docker Scout policy
    metrics_path: /v1/exporter/org/<ORG>/metrics
    scheme: https
    static_configs:
      - targets:
          - api.scout.docker.com
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/token

启动 compose 服务。
docker compose up -d
此命令启动两个服务：Prometheus 服务器和 Grafana。 Prometheus 从 Docker Scout 端点抓取指标数据， Grafana 则使用预配置的仪表板对这些指标进行可视化展示。

要停止演示并清理创建的任何资源，请运行：

docker compose down -v

访问 Prometheus

启动服务后，您可以通过访问以下地址来使用 Prometheus 表达式浏览器：http://localhost:9090。 Prometheus 服务器运行在 Docker 容器中，可通过 9090 端口访问。

几秒钟后，您应在 Prometheus UI 的http://localhost:9090/targets中看到该指标端点作为一个目标。

Docker Scout metrics exporter Prometheus target — Docker Scout 指标导出器 Prometheus 目标

在 Grafana 中查看指标

要查看 Grafana 仪表板，请访问 http://localhost:3000/dashboards，并使用 Docker Compose 文件中定义的凭据登录（用户名：admin，密码：grafana）。

Vulnerability dashboard in Grafana — Grafana 中的漏洞仪表盘

Policy dashboard in Grafana — Grafana 中的策略仪表板

仪表板已预先配置，用于可视化 Prometheus 抓取的漏洞和策略指标。

Datadog

本部分介绍如何使用 Datadog 抓取指标端点。 Datadog 通过运行可自定义的代理来拉取监控数据，该代理会抓取所有可用端点中的公开指标。 OpenMetrics 和 Prometheus 检查已包含在代理中，因此您无需在容器或主机上安装其他组件。

本指南假定您已拥有 Datadog 账户及 Datadog API 密钥。如需开始使用，请参阅 Datadog 文档。

配置 Datadog 代理

要开始收集指标，您需要编辑代理的 OpenMetrics 检查配置文件。如果您将代理作为容器运行，则该文件必须挂载到 /etc/datadog-agent/conf.d/openmetrics.d/conf.yaml。

以下示例展示了一个 Datadog 配置，该配置：

指定指向 Docker 组织 dockerscoutpolicy 的 OpenMetrics 端点
一个 namespace，所有收集的指标将以此为前缀
您 metrics希望代理抓取的（scout_*）
一个用于 Datadog 代理向指标端点进行身份验证的 auth_token 部分，使用 Docker PAT 作为 Bearer 令牌。

instances:
  - openmetrics_endpoint: "https://api.scout.docker.com/v1/exporter/org/dockerscoutpolicy/metrics"
    namespace: "scout-metrics-exporter"
    metrics:
      - scout_*
    auth_token:
      reader:
        type: file
        path: /var/run/secrets/scout-metrics-exporter/token
      writer:
        type: header
        name: Authorization
        value: Bearer <TOKEN>

重要
请勿替换先前配置示例中的 <TOKEN> 占位符。该占位符必须保持原样不变。只需确保 Docker PAT 已正确挂载至 Datadog Agent 的指定文件系统路径中即可。将文件保存为 conf.yaml 并重启 Agent。

在创建您自己的 Datadog 代理配置时，请确保编辑 openmetrics_endpoint 属性以指向您的组织，通过将 dockerscoutpolicy 替换为您的 Docker 组织的命名空间。

Datadog 示例项目

如果您尚未设置 Datadog 服务器，可以使用 Docker Compose 运行一个示例项目。该示例包含一个 Datadog 代理（以容器形式运行），用于抓取已加入 Docker Scout 的 Docker 组织的指标数据。本示例项目假设您已拥有 Datadog 账户、API 密钥及 Datadog 站点。

克隆启动模板，用于快速搭建用于抓取 Docker Scout 指标端点的 Datadog Compose 服务：

$ git clone git@github.com:dockersamples/scout-metrics-exporter.git
$ cd scout-metrics-exporter/datadog

创建 Docker 访问令牌并将其存储在模板目录下的 /datadog/token 的纯文本文件中。
令牌
$ echo $DOCKER_PAT > ./token

在 /datadog/compose.yaml 文件中，使用您的 Datadog 部署对应的值更新 DD_API_KEY 和 DD_SITE 环境变量。

  datadog-agent:
    container_name: datadog-agent
    image: gcr.io/datadoghq/agent:7
    environment:
      - DD_API_KEY=${DD_API_KEY} # e.g. 1b6b3a42...
      - DD_SITE=${DD_SITE} # e.g. datadoghq.com
      - DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./conf.yaml:/etc/datadog-agent/conf.d/openmetrics.d/conf.yaml:ro
      - ./token:/var/run/secrets/scout-metrics-exporter/token:ro

volumes 部分将主机的 Docker 套接字挂载到容器中。这是在以容器方式运行时获取准确主机名所必需的（此处了解更多详情）。

它还会挂载代理的配置文件和 Docker 访问令牌。

通过将 /datadog/config.yaml 文件中的占位符 <ORG> 替换为您要收集指标的 Docker 组织的命名空间，来编辑该文件。

instances:
  - openmetrics_endpoint: "https://api.scout.docker.com/v1/exporter/org/<<ORG>>/metrics"
    namespace: "scout-metrics-exporter"
# ...

启动 compose 服务。
docker compose up -d

如果配置正确，当您运行代理的状态命令时，应会在“运行中的检查”中看到 OpenMetrics 检查，其输出应类似于：

openmetrics (4.2.0)
-------------------
  Instance ID: openmetrics:scout-prometheus-exporter:6393910f4d92f7c2 [OK]
  Configuration Source: file:/etc/datadog-agent/conf.d/openmetrics.d/conf.yaml
  Total Runs: 1
  Metric Samples: Last Run: 236, Total: 236
  Events: Last Run: 0, Total: 0
  Service Checks: Last Run: 1, Total: 1
  Average Execution Time : 2.537s
  Last Execution Date : 2024-05-08 10:41:07 UTC (1715164867000)
  Last Successful Execution Date : 2024-05-08 10:41:07 UTC (1715164867000)

有关选项的完整列表，请参阅此示例配置文件，适用于通用 OpenMetrics 检查。

可视化您的数据

一旦代理配置为获取 Prometheus 指标，您即可利用这些指标构建全面的 Datadog 图表、仪表板和告警。

进入您的指标摘要页面以查看从此示例收集的指标。此配置将收集以scout_开头的所有公开指标，并将其置于scout_metrics_exporter命名空间下。

以下屏幕截图展示了包含有关特定流的漏洞和策略合规性图表的Datadog仪表板示例。

折线图中线条看似平直的原因在于漏洞本身的特性（漏洞通常不会频繁变化），以及日期选择器中所选的时间间隔较短。

抓取间隔

默认情况下，Prometheus 和 Datadog 以 15 秒的间隔抓取指标数据。由于漏洞数据本身的特性，通过此 API 暴露的指标数据不太可能频繁变化。因此，该指标端点默认启用了 60 分钟的缓存机制，建议将抓取间隔设置为 60 分钟或更长。若将抓取间隔设置为小于 60 分钟，则在该时间窗口内多次抓取时，您将看到相同的指标数据。

要更改抓取间隔：

Prometheus：在 Prometheus 配置文件的全局或作业级别设置 scrape_interval 字段。
Datadog：在 Datadog Agent 配置文件中设置 min_collection_interval 属性，详见 Datadog 文档。

撤销访问令牌

如果您怀疑您的个人访问令牌（PAT）已被泄露或不再需要，可随时将其撤销。要撤销个人访问令牌，请按照创建和管理访问令牌中的步骤操作。

撤销个人访问令牌（PAT）会立即使其失效，并阻止 Prometheus 使用该令牌抓取指标数据。您需要创建一个新的 PAT，并更新 Prometheus 配置以使用新令牌。