Docker Scout metrics exporter

Docker Scout exposes a metrics HTTP endpoint that lets you scrape vulnerability and policy data from Docker Scout, using Prometheus or Datadog. 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:

Example, by severity or package type:

          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    id,displayName,streamName    Gauge
                                a stream

👉 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:

You can create a personal access token (PAT) to use as an alternative to your password for Docker CLI authentication.

Compared to passwords, PATs provide the following advantages:

• You can investigate when the PAT was last used and then disable or delete it if you find any suspicious activity.

• When using an access token, you can’t perform any admin activity on the account, including changing the password. It protects your account if your computer is compromised.

Access tokens are also valuable for building integrations, as you can issue multiple tokens, one for each integration, and revoke them at any time.

🌟 Create an access token

1. Sign in to Docker Hub.

2. Select your avatar in the top-right corner and from the drop-down menu select Account settings.

3. Select the Security tab and then New Access Token.

4. Add a description for your token. Use something that indicates the use case or purpose of the token.

5. Set the access permissions. The access permissions are scopes that set restrictions in your repositories. For example, for Read & Write permissions, an automation pipeline can build an image and then push it to a repository. However, it can not delete the repository.

6. Select Generate and then copy the token that appears on the screen and save it. You won’t be able to retrieve the token once you close this prompt.

🌟 Use an access token

You can use an access token in place of your password when you sign in using Docker CLI.

Sign in from your Docker CLI client with the following command, replacing YOUR_USERNAME with your Docker ID:

$ docker login --username YOUR_USERNAME

When prompted for a password, enter your personal access token instead of a password.

Note: If you have two-factor authentication (2FA) enabled, you must use a personal access token when logging in from the Docker CLI. 2FA is an optional, but more secure method of authentication.

🌟Modify existing tokens

You can rename, activate, deactivate, or delete a token as needed.

1. Access your tokens under Account settings > Security.

2. Select a token and then select Delete or Edit, or use the actions menu on the far right of a token row to bring up the edit screen. You can also select multiple tokens to delete at once.

3. After modifying the token, select Save.

🌟 Auto-generated tokens

When you sign in to your Docker account with Docker Desktop, Docker Desktop generates an authentication token on your behalf. When you interact with Docker Hub using the Docker CLI, the CLI uses this token for authentication. The token scope has Read, Write, and Delete access. If your Docker Desktop session expires, the token is automatically removed locally.

You can have up to 5 auto-generated tokens associated with your account. These are deleted and created automatically based on usage and creation dates. You can also delete your auto-generated tokens as needed.

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.

👉 Setting Up Docker Scout Metrics Exporter

🌟 Install Docker Scout Metrics Exporter:

You can often find it on Docker Hub or GitHub. Use the appropriate command to pull the image.

$ docker pull <docker-scout-metrics-exporter-image>

🌟 Configure the Exporter:

Configuration is typically done via environment variables or a configuration file. Ensure you have the necessary credentials and API keys to access Docker Scout.

🌟 Run the Exporter:

Use docker run to start the exporter container, passing in the necessary configuration.

$ docker run -d \
  -e DOCKER_SCOUT_API_KEY=<your-api-key> \
  -e OTHER_CONFIGS=<other-configs> \
  <docker-scout-metrics-exporter-image>

🌟 Integrate with Monitoring Systems:

• Set up Prometheus to scrape metrics from the exporter.

• Add the endpoint to your Prometheus configuration.

$ scrape_configs:
  - job_name: 'docker_scout_metrics'
    static_configs:
      - targets: ['<exporter-host>:<exporter-port>']

🌟 Visualize Metrics:

Use Grafana to create dashboards that visualize the metrics collected by Prometheus.