Docker Scout メトリクスエクスポーター

Docker Scout は、Prometheus または Datadog を使用して脆弱性やポリシーデータをスクレイプできるメトリクス HTTP エンドポイントを公開しています。これを使用して、サプライチェーンメトリクスを視覚化するためのセルフホスト型 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 内では主に内部的な概念ですが、このメトリクスエンドポイントを介してのみデータが公開されます。

アクセストークンの作成

組織のメトリクスをエクスポートするには、まず Organization が Docker Scout に登録されていることを確認してください。その後、パーソナルアクセストークン（PAT）を作成します。このトークンを使用してエクスポーターが Docker Scout API に認証できます。

PAT に特定の権限は不要ですが、Docker Organization のオーナーによって作成される必要があります。PAT を作成する手順については、アクセストークンの作成を参照してください。

PAT を作成したら安全な場所に保存してください。メトリクスをスクレイプする際にこのトークンをエクスポーターに提供する必要があります。

Prometheus

このセクションでは、Prometheus を使用してメトリクスエンドポイントをスクレイプする方法を説明します。

Organization 用のジョブを追加する

Prometheus の設定ファイルに Organization 用の新しいジョブを追加します。以下の設定を含め、ORG を Organization 名に置き換えてください：

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 トークン認証の追加

Prometheus を使用して Docker Scout エクスポーターエンドポイントからメトリクスをスクレイプするには、PAT を Bearer トークンとして設定する必要があります。

Prometheus 設定ファイルに authorization 設定ブロックを追加します。このブロックでは、PAT をファイルに保存された Bearer トークンとして定義します。

scrape_configs:
  - job_name: $ORG
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/token

ファイルの内容は平文の PAT です：

dckr_pat_...

Prometheus を Docker コンテナや Kubernetes Pod で実行する場合、ファイルをボリュームやシークレットとしてコンテナにマウントします。

最後に、Prometheus を再起動して変更を適用します。

Prometheus サンプルプロジェクト

Prometheus サーバーが設定されていない場合、サンプルプロジェクトを Docker Compose を使用して実行できます。このサンプルには、Docker Scout に登録された Docker Organization のメトリクスをスクレイプする Prometheus サーバーと、脆弱性およびポリシーメトリクスを視覚化するための 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 Organization のネームスペースに置き換えます。

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 の 2 つのサービスが起動します。Prometheus は Docker Scout エンドポイントからメトリクスをスクレイプし、Grafana はプリセットされたダッシュボードを使用してメトリクスを視覚化します。

デモを停止し、作成されたリソースをクリーンアップするには、以下のコマンドを実行します：

docker compose down -v

Prometheus のアクセス

サービスを開始した後、http://localhost:9090 にアクセスして Prometheus のエクスプレッションブラウザを使用できます。Prometheus サーバーは Docker コンテナ内で実行され、ポート 9090 でアクセス可能です。

数秒後、Prometheus UI の http://localhost:9090/targets でメトリクスエンドポイントがターゲットとして表示されます。

Docker Scout メトリクスエクスポーターの Prometheus ターゲット

Grafana でメトリクスを表示

Grafana ダッシュボードを表示するには、http://localhost:3000/dashboards にアクセスし、Docker Compose ファイルに定義された認証情報（ユーザー名: admin, パスワード: grafana）でサインインします。

Grafana の脆弱性ダッシュボード

Grafana のポリシーダッシュボード

これらのダッシュボードは、Prometheus によってスクレイプされた脆弱性およびポリシーメトリクスを視覚化するために事前設定されています。

Datadog

このセクションでは、Datadog を使用してメトリクスエンドポイントをスクレイプする方法を説明します。Datadog は、カスタマイズ可能なエージェントを実行して監視用のデータを取得し、利用可能なエンドポイントからメトリクスをスクレイプします。

このガイドでは、Datadog アカウントと API キーが必要です。詳細についてはDatadog ドキュメントを参照してください。

Datadog エージェントの設定

メトリクスを収集するには、OpenMetrics チェック用のエージェント設定ファイルを編集する必要があります。エージェントをコンテナとして実行する場合、このファイルは /etc/datadog-agent/conf.d/openmetrics.d/conf.yaml にマウントする必要があります。

以下の例では、以下を指定しています：

Docker Organization dockerscoutpolicy の OpenMetrics エンドポイント
収集したメトリクスに追加する namespace
エージェントがスクレイプするメトリクス（scout_*）
Docker PAT をベアラートークンとして使用する 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>

⚠️

重要

上記の設定例で <TOKEN> プレースホルダーを置き換えないでください。そのままにしてください。Docker PAT が Datadog エージェントに指定されたファイルシステムパスに正しくマウントされていることを確認してください。このファイルを conf.yaml として保存し、エージェントを再起動します。

エージェント設定ファイルの openmetrics_endpoint プロパティを編集し、収集する Docker Organization のネームスペースで dockerscoutpolicy を置き換えてください。

Datadog サンプルプロジェクト

Datadog サーバーが設定されていない場合、サンプルプロジェクトを Docker Compose で実行できます。このサンプルには、Docker Scout に登録された Docker Organization のメトリクスをスクレイプする 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 ソケットをマウントします。これは、コンテナで実行する際の正確なホスト名取得に必要です（詳細はこちら）。

/datadog/config.yaml ファイルで、openmetrics_endpoint プロパティ内の <ORG> プレースホルダーをメトリクスを収集する Docker Organization のネームスペースに置き換えます。
```
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 の名前空間で収集されます。

Datadog メトリクスサマリー

以下のスクリーンショットは、特定のストリームに対する脆弱性やポリシー準拠のグラフを含む Datadog ダッシュボードの例を示しています。

Datadog ダッシュボード1

Datadog ダッシュボード2

グラフの線が平坦に見えるのは、脆弱性の性質（頻繁には変化しない）と、日付ピッカーで短い時間間隔を選択したためです。

スクレイプ間隔

デフォルトでは、Prometheus と Datadog は 15 秒間隔でメトリクスをスクレイプします。脆弱性データの性質上、この API で公開されるメトリクスは高頻度で変化する可能性が低いため、メトリクスエンドポイントにはデフォルトで 60 分のキャッシュが設定されています。したがって、スクレイプ間隔は 60 分以上に設定することを推奨します。

スクレイプ間隔を変更するには：

Prometheus: 設定ファイルの scrape_interval フィールドをグローバルまたはジョブレベルで設定します。
Datadog: Datadog エージェント設定ファイルの min_collection_interval プロパティを設定します。詳細はDatadog ドキュメントを参照してください。

アクセストークンの取り消し

PAT が漏洩した可能性がある場合や、もはや不要になった場合は、いつでも PAT を取り消すことができます。PAT を取り消すには、アクセストークンの作成と管理の手順に従ってください。

PAT の取り消しはすぐにトークンを無効にし、Prometheus がそのトークンを使用してメトリクスを収集するのを防ぎます。新しい PAT を作成し、Prometheus の設定を更新して新しいトークンを使用する必要があります。

脆弱性例外の管理イメージ詳細ビュー