Docker Scout metrics exporter
Docker Scout exposes a metrics HTTP endpoint that lets you scrape vulnerability and policy data from Docker Scout, using Prometheus. With this you can create your own, self-hosted Docker Scout dashboards for visualizing supply chain metrics.
Metrics
The metrics endpoint exposes the following metrics:
Metric | Description | Labels | Type |
---|---|---|---|
scout_stream_vulnerabilities | Vulnerabilities in a stream | streamName , severity | Gauge |
scout_policy_compliant_images | Compliant images for a policy in a stream | id , displayName , streamName | Gauge |
scout_policy_evaluated_images | Total images evaluated against a policy in a stream | id , displayName , streamName | Gauge |
Streams
In Docker Scout, the streams concept is a superset of environments. Streams include all runtime environments that you've defined, as well as the special
latest-indexed
stream. Thelatest-indexed
stream contains the most recently pushed (and analyzed) tag for each repository.Streams is mostly an internal concept in Docker Scout, with the exception of the data exposed through this metrics endpoint.
Creating an access token
To export metrics from your organization, first make sure your organization is enrolled in Docker Scout. Then, create a Personal Access Token (PAT) - a secret token that allows the exporter to authenticate with the Docker Scout API.
The PAT does not require any specific permissions, but it must be created by a user who is an owner of the Docker organization. To create a PAT, follow the steps in Create an access token.
Once you have created the PAT, store it in a secure location. You will need to provide this token to the exporter when scraping metrics.
Configure Prometheus
Add a job for your organization
In the Prometheus configuration file, add a new job for your organization.
The job should include the following configuration;
replace ORG
with your organization name:
scrape_configs:
- job_name: <ORG>
metrics_path: /v1/exporter/org/<ORG>
scheme: https
static_configs:
- targets:
- api.scout.docker.com
The address in the targets
field is set to the domain name of the Docker Scout API, api.scout.docker.com
.
Make sure that there's no firewall rule in place preventing the server from communicating with this endpoint.
Scrape interval
By default, Prometheus scrapes the metrics every 15 seconds.
You can change the scrape interval by setting the scrape_interval
field in the Prometheus configuration file at the global or job level.
A scraping interval of 60 minutes or higher is recommended.
Because of the own nature of vulnerability data, the metrics exposed through this API are unlikely to change at a high frequency. For this reason, the metrics endpoint has a 60-minute cache by default. If you set the scrape interval to less than 60 minutes, you will see the same data in the metrics for multiple scrapes during that time window.
Add bearer token authentication
To scrape metrics from the Docker Scout Exporter endpoint using Prometheus, you need to configure Prometheus to use the PAT as a bearer token.
The exporter requires the PAT to be passed in the Authorization
header of the request.
Update the Prometheus configuration file to include the authorization
configuration block.
This block defines the PAT as a bearer token stored in a file:
scrape_configs:
- job_name: $ORG
authorization:
type: Bearer
credentials_file: /etc/prometheus/token
The content of the file should be the PAT in plain text:
dckr_pat_...
If you are running Prometheus in a Docker container or Kubernetes pod, mount the file into the container using a volume or secret.
Finally, restart Prometheus to apply the changes.
Sample project
If you don't have a Prometheus server set up, you can run a sample project using Docker Compose. The sample includes a Prometheus server that scrapes metrics for a Docker organization enrolled in Docker Scout, alongside Grafana with a pre-configured dashboard to visualize the vulnerability and policy metrics.
Clone the starter template for bootstrapping a set of Compose services for scraping and visualizing the Docker Scout metrics endpoint:
$ git clone git@github.com:dockersamples/scout-metrics-exporter.git
Create a Docker access token and store it in a plain text file at
prometheus/token
under the template directory.token$ echo $DOCKER_PAT > ./prometheus/token
In the Prometheus configuration file at
prometheus/prometheus.yml
, replaceORG
in themetrics_path
property on line 6 with the namespace of your Docker organization.prometheus/prometheus.yml1 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> scheme: https static_configs: - targets: - api.scout.docker.com authorization: type: Bearer credentials_file: /etc/prometheus/token
Start the compose services.
docker compose up -d
This command starts two services: the Prometheus server and Grafana. Prometheus scrapes metrics from the Docker Scout endpoint, and Grafana visualizes the metrics using a pre-configured dashboard.
To stop the demo and clean up any resources created, run:
docker compose down -v
Access to Prometheus
After starting the services, you can access the Prometheus expression browser by visiting http://localhost:9090. The Prometheus server runs in a Docker container and is accessible on port 9090.
After a few seconds, you should see the metrics endpoint as a target in the Prometheus UI at http://localhost:9090/targets.
Viewing the metrics in Grafana
To view the Grafana dashboards, go to
http://localhost:3000/dashboards,
and sign in using the credentials defined in the Docker Compose file (username: admin
, password: grafana
).
The dashboards are pre-configured to visualize the vulnerability and policy metrics scraped by Prometheus.
Revoke an access token
If you suspect that your PAT has been compromised or is no longer needed, you can revoke it at any time. To revoke a PAT, follow the steps in the Create and manage access tokens.
Revoking a PAT immediately invalidates the token, and prevents Prometheus from scraping metrics using that token. You will need to create a new PAT and update the Prometheus configuration to use the new token.