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 中，“流”的概念是环境的超集。“流”包括你定义的所有运行时环境，以及特殊的latest-indexed流。latest-indexed流包含每个仓库中最近推送（和分析）的标签。
除了通过此指标端点公开的数据外，“流”主要是在 Docker Scout 中的内部概念。

创建访问令牌

要从你的组织导出指标，首先确保你的组织已注册 Docker Scout。然后，创建一个个人访问令牌 (PAT) - 一个秘密令牌，允许导出器使用 Docker Scout API 进行身份验证。

PAT 不需要任何特定权限，但必须由 Docker 组织所有者创建。要创建 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 作为承载令牌。导出器需要将 PAT 传递到请求的Authorization标头中。

更新 Prometheus 配置文件以包含authorization配置块。此块将 PAT 定义为存储在文件中的承载令牌

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

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

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

docker compose down -v

访问 Prometheus

启动服务后，您可以通过访问https://#:9090访问 Prometheus 表达式浏览器。Prometheus 服务器运行在 Docker 容器中，可在 9090 端口访问。

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

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

在 Grafana 中查看指标

要查看 Grafana 仪表板，请访问https://#: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 配置，它

指定了针对dockerscoutpolicy Docker 组织的 OpenMetrics 端点
所有收集的指标都将以其为前缀的namespace
您希望代理抓取的metrics（scout_*）
一个auth_token部分，用于 Datadog 代理使用 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 代理即可。将文件保存为conf.yaml并重新启动代理。

创建您自己的 Datadog 代理配置时，请确保编辑openmetrics_endpoint属性以定位您的组织，方法是用您的 Docker 组织的命名空间替换dockerscoutpolicy。

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 socket 装载到容器中。当作为容器运行时，这对于获取准确的主机名是必需的（此处了解更多详情）。

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

编辑/datadog/config.yaml文件，方法是用您要收集指标的 Docker 组织的命名空间替换openmetrics_endpoint属性中的占位符<ORG>。

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

启动组合服务。
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_metrics_exporter命名空间下收集以scout_开头的所有公开指标。

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

图表中的线条看起来平坦的原因是漏洞本身的特性（它们不会经常更改）以及在日期选择器中选择的较短时间间隔。

抓取间隔

默认情况下，Prometheus 和 Datadog 以 15 秒的间隔抓取指标。由于漏洞数据的自身特性，通过此 API 公开的指标不太可能高频变化。因此，指标端点默认具有 60 分钟的缓存，这意味着建议抓取间隔为 60 分钟或更长。如果将抓取间隔设置为少于 60 分钟，则在该时间窗口内，您将在多个抓取中看到相同的数据。

更改抓取间隔

Prometheus：在 Prometheus 配置文件的全局或作业级别设置scrape_interval字段。
Datadog：在 Datadog 代理配置文件中设置min_collection_interval属性，请参阅 Datadog 文档。

撤销访问令牌

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

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