Exportador de métricas de Docker Scout

Tabla de contenidos

Docker Scout expone un endpoint HTTP de métricas que te permite recopilar datos de vulnerabilidades y políticas de Docker Scout utilizando Prometheus o Datadog. Con esto, puedes crear tus propios paneles de Docker Scout autohospedados para visualizar las métricas de la cadena de suministro.

Métricas

El endpoint de métricas expone las siguientes métricas:

Métrica	Descripción	Etiquetas (Labels)	Tipo
`scout_stream_vulnerabilities`	Vulnerabilidades en un flujo (stream)	`streamName`, `severity`	Gauge
`scout_policy_compliant_images`	Imágenes que cumplen con una política en un flujo	`id`, `displayName`, `streamName`	Gauge
`scout_policy_evaluated_images`	Total de imágenes evaluadas frente a una política en un flujo	`id`, `displayName`, `streamName`	Gauge

Flujos (Streams)
En Docker Scout, el concepto de flujos es un superconjunto de los entornos. Los flujos incluyen todos los entornos de ejecución que hayas definido, así como el flujo especial latest-indexed. El flujo latest-indexed contiene la etiqueta subida (y analizada) más recientemente para cada repositorio.
Los flujos son principalmente un concepto interno en Docker Scout, con la excepción de los datos expuestos a través de este endpoint de métricas.

Crear un token de acceso

Para exportar métricas de tu organización, primero asegúrate de que tu organización esté registrada en Docker Scout. Luego, crea un Token de Acceso Personal (PAT): un token secreto que permite al exportador autenticarse con la API de Docker Scout.

El PAT no requiere ningún permiso específico, pero debe ser creado por un usuario que sea propietario (owner) de la organización de Docker. Para crear un PAT, sigue los pasos descritos en Crear un token de acceso.

Una vez que hayas creado el PAT, guárdalo en un lugar seguro. Deberás proporcionar este token al exportador al recopilar las métricas.

Prometheus

Esta sección describe cómo recopilar datos del endpoint de métricas utilizando Prometheus.

Añadir una tarea para tu organización

En el archivo de configuración de Prometheus, añade una nueva tarea (job) para tu organización. La tarea debe incluir la siguiente configuración; reemplaza ORG con el nombre de tu organización:

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

La dirección en el campo targets se establece con el nombre de dominio de la API de Docker Scout, api.scout.docker.com. Asegúrate de que no haya ninguna regla de cortafuegos que impida al servidor comunicarse con este endpoint.

Añadir autenticación por token portador (bearer token)

Para recopilar métricas del endpoint del exportador de Docker Scout utilizando Prometheus, debes configurar Prometheus para que use el PAT como un token portador (bearer token). El exportador requiere que el PAT se envíe en la cabecera Authorization de la solicitud.

Actualiza el archivo de configuración de Prometheus para incluir el bloque de configuración authorization. Este bloque define el PAT como un token portador almacenado en un archivo:

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

El contenido del archivo debe ser el PAT en texto plano:

dckr_pat_...

Si estás ejecutando Prometheus en un contenedor de Docker o en un pod de Kubernetes, monta el archivo en el contenedor utilizando un volumen o un secreto.

Finalmente, reinicia Prometheus para aplicar los cambios.

Proyecto de ejemplo de Prometheus

Si no tienes un servidor Prometheus configurado, puedes ejecutar un proyecto de ejemplo utilizando Docker Compose. El ejemplo incluye un servidor Prometheus que recopila métricas para una organización de Docker registrada en Docker Scout, junto con Grafana con un panel preconfigurado para visualizar las métricas de vulnerabilidades y políticas.

Clona la plantilla inicial para arrancar un conjunto de servicios de Compose para recopilar y visualizar el endpoint de métricas de Docker Scout:
$ git clone [email protected]:dockersamples/scout-metrics-exporter.git $ cd scout-metrics-exporter/prometheus
Crea un token de acceso de Docker y almacénalo en un archivo de texto plano en /prometheus/prometheus/token bajo el directorio de la plantilla.
token
$ echo $DOCKER_PAT > ./prometheus/token

En el archivo de configuración de Prometheus en /prometheus/prometheus/prometheus.yml, reemplaza ORG en la propiedad metrics_path en la línea 6 con el espacio de nombres de tu organización de 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

Inicia los servicios de Compose.
$ docker compose up -d
Este comando inicia dos servicios: el servidor Prometheus y Grafana. Prometheus recopila métricas del endpoint de Docker Scout y Grafana visualiza las métricas utilizando un panel preconfigurado.

Para detener la demostración y limpiar cualquier recurso creado, ejecuta:

$ docker compose down -v

Acceso a Prometheus

Después de iniciar los servicios, puedes acceder al explorador de expresiones de Prometheus visitando http://localhost:9090. El servidor Prometheus se ejecuta en un contenedor de Docker y es accesible en el puerto 9090.

Después de unos segundos, deberías ver el endpoint de métricas como un objetivo (target) en la interfaz de usuario de Prometheus en http://localhost:9090/targets.

Objetivo de Prometheus del exportador de métricas de Docker Scout

Visualizar las métricas en Grafana

Para ver los paneles de Grafana, ve a http://localhost:3000/dashboards e inicia sesión utilizando las credenciales definidas en el archivo Docker Compose (usuario: admin, contraseña: grafana).

Los paneles están preconfigurados para visualizar las métricas de vulnerabilidades y políticas recopiladas por Prometheus.

Datadog

Esta sección describe cómo recopilar datos del endpoint de métricas utilizando Datadog. Datadog recopila datos para monitorización ejecutando un agente (agent) personalizable que examina los endpoints disponibles para cualquier métrica expuesta. Los chequeos de OpenMetrics y Prometheus están incluidos en el agente, por lo que no necesitas instalar nada más en tus contenedores o hosts.

Esta guía asume que tienes una cuenta de Datadog y una clave de API de Datadog. Consulta la documentación de Datadog para comenzar.

Configurar el agente de Datadog

Para comenzar a recopilar las métricas, deberás editar el archivo de configuración del agente para el chequeo de OpenMetrics. Si estás ejecutando el agente como un contenedor, dicho archivo debe estar montado en /etc/datadog-agent/conf.d/openmetrics.d/conf.yaml.

El siguiente ejemplo muestra una configuración de Datadog que:

Especifica el endpoint de OpenMetrics apuntando a la organización de Docker dockerscoutpolicy.
Un espacio de nombres (namespace) con el que se prefijarán todas las métricas recopiladas.
Las métricas que deseas que el agente recopile (scout_*).
Una sección auth_token para que el agente de Datadog se autentique en el endpoint de métricas utilizando un PAT de Docker como token portador (Bearer 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>

Important
No reemplaces el marcador de posición <TOKEN> en el ejemplo de configuración anterior. Debe permanecer tal como está. Únicamente asegúrate de que el PAT de Docker esté correctamente montado en el agente de Datadog en la ruta del sistema de archivos especificada. Guarda el archivo como conf.yaml y reinicia el agente.

Al crear tu propia configuración del agente de Datadog, asegúrate de editar la propiedad openmetrics_endpoint para apuntar a tu organización, reemplazando dockerscoutpolicy con el espacio de nombres de tu organización de Docker.

Proyecto de ejemplo de Datadog

Si no tienes un servidor Datadog configurado, puedes ejecutar un proyecto de ejemplo utilizando Docker Compose. El ejemplo incluye un agente de Datadog, ejecutándose como un contenedor, que recopila métricas para una organización de Docker registrada en Docker Scout. Este proyecto de ejemplo asume que tienes una cuenta de Datadog, una clave de API y un sitio de Datadog.

Clona la plantilla inicial para arrancar un servicio de Datadog con Compose para recopilar datos del endpoint de métricas de Docker Scout:
$ git clone [email protected]:dockersamples/scout-metrics-exporter.git $ cd scout-metrics-exporter/datadog
Crea un token de acceso de Docker y almacénalo en un archivo de texto plano en /datadog/token bajo el directorio de la plantilla.
token
$ echo $DOCKER_PAT > ./token

En el archivo /datadog/compose.yaml, actualiza las variables de entorno DD_API_KEY y DD_SITE con los valores de tu despliegue de Datadog.

datadog-agent:
  container_name: datadog-agent
  image: gcr.io/datadoghq/agent:7
  environment:
    - DD_API_KEY=${DD_API_KEY} # ej. 1b6b3a42...
    - DD_SITE=${DD_SITE} # ej. 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

La sección volumes monta el socket de Docker desde el host al contenedor. Esto es necesario para obtener un nombre de host preciso cuando se ejecuta como un contenedor (más detalles aquí).

También monta el archivo de configuración del agente y el token de acceso de Docker.

Edita el archivo /datadog/config.yaml reemplazando el marcador de posición <ORG> en la propiedad openmetrics_endpoint con el espacio de nombres de la organización de Docker para la que deseas recopilar métricas.
instances: - openmetrics_endpoint: "https://api.scout.docker.com/v1/exporter/org/<<ORG>>/metrics" namespace: "scout-metrics-exporter" # ...
Inicia los servicios de Compose.
$ docker compose up -d

Si está configurado correctamente, deberías ver el chequeo de OpenMetrics bajo los chequeos en ejecución (Running Checks) al ejecutar el comando de estado del agente, cuya salida debería verse similar a:

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)

Para una lista completa de opciones, echa un vistazo a este archivo de configuración de ejemplo para el chequeo genérico de OpenMetrics.

Visualizar tus datos

Una vez que el agente está configurado para recopilar métricas de Prometheus, puedes utilizarlas para construir gráficos, paneles y alertas completos en Datadog.

Ve a tu página de resumen de métricas (Metric summary page) para ver las métricas recopiladas de este ejemplo. Esta configuración recopilará todas las métricas expuestas que comiencen con scout_ bajo el espacio de nombres scout_metrics_exporter.

Las siguientes capturas de pantalla muestran ejemplos de un panel de Datadog que contiene gráficos sobre vulnerabilidades y cumplimiento de políticas para un flujo específico (stream).

La razón por la que las líneas en los gráficos se ven planas se debe a la propia naturaleza de las vulnerabilidades (no cambian con mucha frecuencia) y al corto intervalo de tiempo seleccionado en el selector de fechas.

Intervalo de recopilación (Scrape interval)

De forma predeterminada, Prometheus y Datadog recopilan métricas a un intervalo de 15 segundos. Debido a la propia naturaleza de los datos de vulnerabilidades, es poco probable que las métricas expuestas a través de esta API cambien a una alta frecuencia. Por esta razón, el endpoint de métricas tiene una caché de 60 minutos de forma predeterminada, lo que significa que se recomienda un intervalo de recopilación de 60 minutos o superior. Si estableces el intervalo de recopilación en menos de 60 minutos, verás los mismos datos en las métricas para múltiples recopilaciones durante esa ventana de tiempo.

Para cambiar el intervalo de recopilación:

Prometheus: establece el campo scrape_interval en el archivo de configuración de Prometheus a nivel global o a nivel de tarea (job).
Datadog: establece la propiedad min_collection_interval en el archivo de configuración del agente de Datadog, consulta la documentación de Datadog.

Revocar un token de acceso

Si sospechas que tu PAT se ha visto comprometido o ya no es necesario, puedes revocarlo en cualquier momento. Para revocar un PAT, sigue los pasos descritos en Crear y gestionar tokens de acceso.

Revocar un PAT invalida inmediatamente el token y evita que Prometheus recopile métricas utilizando ese token. Deberás crear un nuevo PAT y actualizar la configuración de Prometheus para utilizar el nuevo token.

¿En qué te puedo ayudar?

Exportador de métricas de Docker Scout