Docker Scout 指标导出器

Docker Scout 公开了一个指标 HTTP 端点，允许您使用 Prometheus 或 Datadog 从 Docker Scout 中抓取漏洞和策略数据。通过此功能，您可以创建自己的自托管 Docker Scout 仪表板，用于可视化供应链指标。

指标

指标端点公开以下指标

流

在 Docker Scout 中，流（streams）概念是 环境 的超集。流包括您定义的所有运行时环境，以及特殊的 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，请使用卷或 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 的纯文本文件中。

   令牌

   $ 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

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

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

在 Grafana 中查看指标

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

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

Datadog

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

本指南假设您拥有 Datadog 账户和 Datadog API 密钥。请参阅 Datadog 文档 以开始使用。

配置 Datadog 代理

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

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

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

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 密钥和 Datadog 站点。

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

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

2. 创建 Docker 访问令牌 并将其存储在模板目录下 /datadog/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 套接字挂载到容器。这在作为容器运行时需要获取准确的主机名（此处有更多详细信息）。

   它还会挂载代理的配置文件和 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
   

如果配置正确，当您运行代理的状态命令时，您应该在“正在运行的检查”下看到 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。

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

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

抓取间隔

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

要更改抓取间隔

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

撤销访问令牌

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

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