Docker Scout 指标导出器

Docker Scout 公开了一个指标 HTTP 端点，可让您抓取漏洞以及来自 Docker Scout 的策略数据（使用 Prometheus 或 Datadog）。有了这个 You 可以创建您自己的、自托管的 Docker Scout 仪表板来可视化供应链指标。

指标

指标终端节点公开以下指标：

度量	描述	标签	类型
`scout_stream_vulnerabilities`	流中的漏洞	`streamName`,`severity`	轨距
`scout_policy_compliant_images`	流中策略的合规镜像	`id`, ,`displayNamestreamName`	轨距
`scout_policy_evaluated_images`	根据流中的策略评估的镜像总数	`id`, ,`displayNamestreamName`	轨距

流
在 Docker Scout 中，流概念是环境的超集。 Streams 包括您定义的所有运行时环境，以及 Special Stream。流包含每个存储库最近推送（和分析）的标签。latest-indexedlatest-indexed
Streams 主要是 Docker Scout 中的一个内部概念，但通过此 Metrics 终端节点公开的数据除外。

创建访问令牌

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

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

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

普罗米修斯

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

为您的组织添加作业

在 Prometheus 配置文件中，为您的组织添加新作业。该作业应包括以下配置; 替换为您的组织名称：ORG

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

字段中的地址设置为 Docker Scout API 的域名。确保没有阻止服务器与此终端节点通信的防火墙规则。targetsapi.scout.docker.com

添加不记名令牌身份验证

要使用 Prometheus 从 Docker Scout Exporter 终端节点抓取指标，您需要将 Prometheus 配置为使用 PAT 作为不记名令牌。导出程序要求在请求的标头中传递 PAT。Authorization

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

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，具有预配置的仪表板来可视化漏洞和策略指标。

克隆用于引导一组 Compose 服务的 starter 模板用于抓取和可视化 Docker Scout 指标终端节点：
$ 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 配置文件中，将第 6 行的属性替换为 Docker 组织的命名空间。/prometheus/prometheus/prometheus.ymlORGmetrics_path

普罗米修斯/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 访问。

几秒钟后，您应该会在 http://localhost:9090/targets 上的 Prometheus UI。

Docker Scout metrics exporter Prometheus target — Docker Scout metrics exporter Prometheus 目标

在 Grafana 中查看指标

要查看 Grafana 控制面板，请转到 http://localhost:3000/dashboards、并使用 Docker Compose 文件中定义的凭据（username：， password：）登录。admingrafana

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

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

控制面板经过预配置，可直观显示 Prometheus 抓取的漏洞和策略指标。

数据狗

本节介绍如何使用 Datadog 抓取指标终端节点。 Datadog 通过运行可自定义的代理来提取数据进行监控 endpoints 的 intent 来执行任何公开的指标。OpenMetrics 和 Prometheus 检查包括包含在代理中，因此您无需在容器或主机。

本指南假定您有一个 Datadog 账户和一个 Datadog API 密钥。指 Datadog 文档以开始使用。

配置 Datadog 代理

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

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

指定以 Docker 组织为目标的 OpenMetrics 端点dockerscoutpolicy
A，所有收集的指标都将以namespace
您希望代理抓取的指标 （scout_*)
Datadog 代理对 Metrics 进行身份验证的部分端点，使用 Docker PAT 作为 Bearer 令牌。auth_token

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>

重要
不要替换上一个配置中的占位符例。它必须保持原样。仅确保 Docker PAT 正确挂载到指定文件系统路径中的 Datadog 代理中。保存 file as 并重新启动代理。<TOKEN>conf.yaml

在创建自己的 Datadog 代理配置时，请确保通过替换为 Docker 组织的命名空间来编辑属性以定位您的组织。openmetrics_endpointdockerscoutpolicy

Datadog 示例项目

如果您没有设置 Datadog 服务器，则可以使用 Docker Compose 运行示例项目。该示例包括一个 Datadog 代理，作为容器，用于抓取在 Docker 中注册的 Docker 组织的指标侦察员。此示例项目假定您有一个 Datadog 账户、一个 API 密钥、以及 Datadog 站点。

克隆用于引导 Datadog Compose 服务的入门模板抓取 Docker Scout 指标端点：

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

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

在文件中，更新和环境变量替换为 Datadog 部署的值。/datadog/compose.yamlDD_API_KEYDD_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

该部分将 Docker 套接字从主机挂载到容器。这是在作为容器（更多详细信息在这里）。volumes

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

通过替换具有 Docker 命名空间的属性要为其收集指标的组织。/datadog/config.yaml<ORG>openmetrics_endpoint

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

启动 Compose 服务。
docker compose up -d

如果配置正确，您应该会在 Running （正在运行）下看到 OpenMetrics 检查当您运行代理的 status 命令时进行检查，其输出应如下所示自：

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 图形、控制面板和警报。

进入 Metric summary （指标摘要）页面，查看从此示例中收集的指标。此配置将收集所有公开的量度从开始在 namespace 下。scout_scout_metrics_exporter

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

图表中的线条看起来平坦的原因是漏洞（它们不会经常变化）和较短的时间间隔在日期选取器中选中。

刮擦间隔

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

要更改抓取间隔：

Prometheus：在 Prometheus 配置中设置字段文件。scrape_interval
Datadog：在 Datadog 代理中设置属性配置文件，请参阅 Datadog 文档。min_collection_interval

撤销访问令牌

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

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