Docker Scout 指标导出器

目录

Docker Scout 暴露了一个 HTTP 指标端点，你可以使用 Prometheus 或 Datadog 从中抓取 Docker Scout 的漏洞和策略数据。借助此端点，你可以创建自己的自托管 Docker Scout 仪表盘，用于可视化供应链指标。

指标

该指标端点暴露以下指标

指标描述标签类型
scout_stream_vulnerabilities流中的漏洞streamName, severityGauge
scout_policy_compliant_images流中符合策略的镜像id, displayName, streamNameGauge
scout_policy_evaluated_images流中针对策略评估的总镜像数id, displayName, streamNameGauge

流

在 Docker Scout 中，流概念是环境的超集。流包括你定义的所有运行时环境，以及特殊的 latest-indexed 流。latest-indexed 流包含每个仓库最近推送（和分析）的标签。

流在 Docker Scout 中主要是一个内部概念，除了通过此指标端点暴露的数据外。

创建访问令牌

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

PAT 不需要任何特定权限，但必须由作为 Docker 组织所有者的用户创建。要创建 PAT，请按照创建访问令牌中的步骤进行操作。

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

Prometheus

本节描述如何使用 Prometheus 抓取指标端点。

为你的组织添加一个 job

在 Prometheus 配置文件中，为你的组织添加一个新 job。该 job 应包含以下配置；将 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。确保没有防火墙规则阻止服务器与此端点通信。

添加 Bearer token 认证

要使用 Prometheus 抓取 Docker Scout 导出器端点的指标，你需要配置 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，使用卷或 secret 将文件挂载到容器中。

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

Prometheus 示例项目

如果你没有设置 Prometheus 服务器，可以使用 Docker Compose 运行一个示例项目。该示例包含一个 Prometheus 服务器，用于抓取已注册 Docker Scout 的 Docker 组织的指标，以及一个预配置的 Grafana 仪表盘，用于可视化漏洞和策略指标。

  1. 克隆入门模板，用于引导一组 Compose 服务，以抓取和可视化 Docker Scout 指标端点

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

  2. 创建 Docker 访问令牌并将其存储在模板目录下的 /prometheus/prometheus/token 文件中。

    token
    $ echo $DOCKER_PAT > ./prometheus/token

  3. 在 /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

  4. 启动 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 Key。请参考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 token 向 Metrics 端点进行认证。
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 属性以针对你的组织，方法是将 dockerscoutpolicy 替换为你 Docker 组织的命名空间。

Datadog 示例项目

如果你没有设置 Datadog 服务器，可以使用 Docker Compose 运行一个示例项目。该示例包含一个作为容器运行的 Datadog 代理，用于抓取已注册 Docker Scout 的 Docker 组织的指标。此示例项目假设你拥有 Datadog 账户、API key 和 Datadog site。

  1. 克隆入门模板，用于引导一个 Datadog Compose 服务，以抓取 Docker Scout 指标端点

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

  2. 创建 Docker 访问令牌并将其存储在模板目录下的 /datadog/token 文件中。

    token
    $ echo $DOCKER_PAT > ./token

  3. 在 /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 访问令牌。

  4. 编辑 /datadog/config.yaml 文件，将 openmetrics_endpoint 属性中的占位符 <ORG> 替换为你想要收集指标的 Docker 组织的命名空间。

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

  5. 启动 Compose 服务。

    docker compose up -d

如果配置正确，当你运行代理的状态命令时，你应该能在 Running Checks 下看到 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_metrics_summary

以下截图显示了 Datadog 面板示例，其中包含有关特定 流 的漏洞和策略合规性的图表。

datadog_dashboard_1
datadog_dashboard_2

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

抓取间隔

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

如何更改抓取间隔

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

撤销访问令牌

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

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

页面选项