Docker Scout 指標匯出器

Docker Scout 公開了一個指標 HTTP 端點，允許您使用 Prometheus 或 Datadog 從 Docker Scout 中抓取漏洞和策略資料。透過此功能，您可以建立自己的自託管 Docker Scout 儀表板，用於視覺化供應鏈指標。

指標

指標端點公開以下指標

指標	描述	Labels	型別
`scout_stream_vulnerabilities`	流中的漏洞	`streamName`, `severity`	計數器
`scout_policy_compliant_images`	流中策略的合規映象	`id`, `displayName`, `streamName`	計數器
`scout_policy_evaluated_images`	流中針對策略評估的總映象數	`id`, `displayName`, `streamName`	計數器

流
在 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，用於視覺化漏洞和策略指標。

克隆啟動模板，用於引導一組 Compose 服務，以抓取和視覺化 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/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

啟動服務後，您可以透過訪問 https://:9090 訪問 Prometheus 表示式瀏覽器。Prometheus 伺服器在 Docker 容器中執行，可透過埠 9090 訪問。

幾秒鐘後，您應該在 Prometheus UI 的 https://:9090/targets 處看到指標端點作為目標。

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 配置，它：

指定 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 站點。

克隆啟動模板，用於引導 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/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 檔案，將 openmetrics_endpoint 屬性中的佔位符 <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。

圖表中線條看起來平坦的原因是漏洞本身的性質（它們不經常變化）以及日期選擇器中選擇的時間間隔較短。

圖表中線條看起來平坦的原因是漏洞本身的性質（它們不經常變化）以及日期選擇器中選擇的時間間隔較短。

抓取間隔

預設情況下，Prometheus 和 Datadog 以 15 秒的間隔抓取指標。由於漏洞資料本身的性質，透過此 API 公開的指標不太可能高頻率更改。因此，指標端點預設具有 60 分鐘的快取，這意味著建議抓取間隔為 60 分鐘或更長。如果將抓取間隔設定為小於 60 分鐘，您將在該時間視窗內多次抓取時看到相同的指標資料。

要更改抓取間隔

Prometheus：在全域性或作業級別的 Prometheus 配置檔案中設定 scrape_interval 欄位。
Datadog：在 Datadog 代理配置檔案中設定 min_collection_interval 屬性，請參閱Datadog 文件。

撤銷訪問令牌

如果您懷疑您的 PAT 已被洩露或不再需要，您可以隨時撤銷它。要撤銷 PAT，請按照建立和管理訪問令牌中的步驟進行操作。

撤銷 PAT 會立即使令牌失效，並阻止 Prometheus 使用該令牌抓取指標。您需要建立一個新的 PAT 並更新 Prometheus 配置以使用新令牌。