|
| 1 | +--- |
| 2 | +title: Docker Scout metrics exporter |
| 3 | +description: | |
| 4 | + Learn how to scrape data from Docker Scout using Prometheus to create your own |
| 5 | + vulnerability and policy dashboards wiht Grafana |
| 6 | +keywords: scout, exporter, prometheus, grafana, metrics, dashboard, api, compose |
| 7 | +--- |
| 8 | + |
| 9 | +Docker Scout exposes a metrics HTTP endpoint that lets you scrape vulnerability |
| 10 | +and policy data from Docker Scout, using Prometheus. With this you can create |
| 11 | +your own, self-hosted Docker Scout dashboards for visualizing supply chain |
| 12 | +metrics. |
| 13 | + |
| 14 | +## Metrics |
| 15 | + |
| 16 | +The metrics endpoint exposes the following metrics: |
| 17 | + |
| 18 | +| Metric | Description | Labels | Type | |
| 19 | +| ------------------------------- | --------------------------------------------------- | --------------------------------- | ----- | |
| 20 | +| `scout_stream_vulnerabilities` | Vulnerabilities in a stream | `streamName`, `severity` | Gauge | |
| 21 | +| `scout_policy_compliant_images` | Compliant images for a policy in a stream | `id`, `displayName`, `streamName` | Gauge | |
| 22 | +| `scout_policy_evaluated_images` | Total images evaluated against a policy in a stream | `id`, `displayName`, `streamName` | Gauge | |
| 23 | + |
| 24 | +> **Streams** |
| 25 | +> |
| 26 | +> In Docker Scout, the streams concept is a superset of [environments](./integrations/environment/_index.md). |
| 27 | +> Streams include all runtime environments that you've defined, |
| 28 | +> as well as the special `latest-indexed` stream. |
| 29 | +> The `latest-indexed` stream contains the most recently pushed (and analyzed) tag for each repository. |
| 30 | +> |
| 31 | +> Streams is mostly an internal concept in Docker Scout, |
| 32 | +> with the exception of the data exposed through this metrics endpoint. |
| 33 | +{ .tip } |
| 34 | + |
| 35 | +## Creating an access token |
| 36 | + |
| 37 | +To export metrics from your organization, first make sure your organization is enrolled in Docker Scout. |
| 38 | +Then, create a Personal Access Token (PAT) - a secret token that allows the exporter to authenticate with the Docker Scout API. |
| 39 | + |
| 40 | +The PAT does not require any specific permissions, but it must be created by a user who is an owner of the Docker organization. |
| 41 | +To create a PAT, follow the steps in [Create an access token](/security/for-developers/access-tokens/#create-an-access-token). |
| 42 | + |
| 43 | +Once you have created the PAT, store it in a secure location. |
| 44 | +You will need to provide this token to the exporter when scraping metrics. |
| 45 | + |
| 46 | +## Configure Prometheus |
| 47 | + |
| 48 | +### Add a job for your organization |
| 49 | + |
| 50 | +In the Prometheus configuration file, add a new job for your organization. |
| 51 | +The job should include the following configuration; |
| 52 | +replace `ORG` with your organization name: |
| 53 | + |
| 54 | +```yaml |
| 55 | +scrape_configs: |
| 56 | + - job_name: <ORG> |
| 57 | + metrics_path: /v1/exporter/org/<ORG> |
| 58 | + scheme: https |
| 59 | + static_configs: |
| 60 | + - targets: |
| 61 | + - api.scout.docker.com |
| 62 | +``` |
| 63 | +
|
| 64 | +The address in the `targets` field is set to the domain name of the Docker Scout API, `api.scout.docker.com`. |
| 65 | +Make sure that there's no firewall rule in place preventing the server from communicating with this endpoint. |
| 66 | + |
| 67 | +### Scrape interval |
| 68 | + |
| 69 | +By default, Prometheus scrapes the metrics every 15 seconds. |
| 70 | +You can change the scrape interval by setting the `scrape_interval` field in the Prometheus configuration file at the global or job level. |
| 71 | +A scraping interval of 60 minutes or higher is recommended. |
| 72 | + |
| 73 | +Because of the own nature of vulnerability data, the metrics exposed through this API are unlikely to change at a high frequency. |
| 74 | +For this reason, the metrics endpoint has a 60-minute cache by default. |
| 75 | +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. |
| 76 | + |
| 77 | +### Add bearer token authentication |
| 78 | + |
| 79 | +To scrape metrics from the Docker Scout Exporter endpoint using Prometheus, you need to configure Prometheus to use the PAT as a bearer token. |
| 80 | +The exporter requires the PAT to be passed in the `Authorization` header of the request. |
| 81 | + |
| 82 | +Update the Prometheus configuration file to include the `authorization` configuration block. |
| 83 | +This block defines the PAT as a bearer token stored in a file: |
| 84 | + |
| 85 | +```yaml |
| 86 | +scrape_configs: |
| 87 | + - job_name: $ORG |
| 88 | + authorization: |
| 89 | + type: Bearer |
| 90 | + credentials_file: /etc/prometheus/token |
| 91 | +``` |
| 92 | + |
| 93 | +The content of the file should be the PAT in plain text: |
| 94 | + |
| 95 | +```console |
| 96 | +dckr_pat_... |
| 97 | +``` |
| 98 | + |
| 99 | +If you are running Prometheus in a Docker container or Kubernetes pod, mount the file into the container using a volume or secret. |
| 100 | + |
| 101 | +Finally, restart Prometheus to apply the changes. |
| 102 | + |
| 103 | +## Sample project |
| 104 | + |
| 105 | +If you don't have a Prometheus server set up, you can run a [sample project](https://github.com/dockersamples/scout-metrics-exporter) using Docker Compose. |
| 106 | +The sample includes a Prometheus server that scrapes metrics for a Docker organization enrolled in Docker Scout, |
| 107 | +alongside Grafana with a pre-configured dashboard to visualize the vulnerability and policy metrics. |
| 108 | + |
| 109 | +1. Clone the starter template for bootstrapping a set of Compose services |
| 110 | + for scraping and visualizing the Docker Scout metrics endpoint: |
| 111 | + |
| 112 | + ```console |
| 113 | + $ git clone [email protected]:dockersamples/scout-metrics-exporter.git |
| 114 | + ``` |
| 115 | + |
| 116 | +2. [Create a Docker access token](/security/for-developers/access-tokens/#create-an-access-token) |
| 117 | + and store it in a plain text file at `prometheus/token` under the template directory. |
| 118 | + |
| 119 | + ```plaintext {title=token} |
| 120 | + $ echo $DOCKER_PAT > ./prometheus/token |
| 121 | + ``` |
| 122 | + |
| 123 | +3. In the Prometheus configuration file at `prometheus/prometheus.yml`, |
| 124 | + replace `ORG` in the `metrics_path` property on line 6 with the namespace of your Docker organization. |
| 125 | + |
| 126 | + ```yaml {title="prometheus/prometheus.yml",hl_lines="6",linenos=1} |
| 127 | + global: |
| 128 | + scrape_interval: 60s |
| 129 | + scrape_timeout: 40s |
| 130 | + scrape_configs: |
| 131 | + - job_name: Docker Scout policy |
| 132 | + metrics_path: /v1/exporter/org/<ORG> |
| 133 | + scheme: https |
| 134 | + static_configs: |
| 135 | + - targets: |
| 136 | + - api.scout.docker.com |
| 137 | + authorization: |
| 138 | + type: Bearer |
| 139 | + credentials_file: /etc/prometheus/token |
| 140 | + ``` |
| 141 | + |
| 142 | +4. Start the compose services. |
| 143 | + |
| 144 | + ```console |
| 145 | + docker compose up -d |
| 146 | + ``` |
| 147 | + |
| 148 | + This command starts two services: the Prometheus server and Grafana. |
| 149 | + Prometheus scrapes metrics from the Docker Scout endpoint, |
| 150 | + and Grafana visualizes the metrics using a pre-configured dashboard. |
| 151 | + |
| 152 | +To stop the demo and clean up any resources created, run: |
| 153 | + |
| 154 | +```console |
| 155 | +docker compose down -v |
| 156 | +``` |
| 157 | + |
| 158 | +### Access to Prometheus |
| 159 | + |
| 160 | +After starting the services, you can access the Prometheus expression browser by visiting <http://localhost:9090>. |
| 161 | +The Prometheus server runs in a Docker container and is accessible on port 9090. |
| 162 | + |
| 163 | +After a few seconds, you should see the metrics endpoint as a target in the |
| 164 | +Prometheus UI at <http://localhost:9090/targets>. |
| 165 | + |
| 166 | + |
| 167 | + |
| 168 | +### Viewing the metrics in Grafana |
| 169 | + |
| 170 | +To view the Grafana dashboards, go to <http://localhost:3000/dashboards>, |
| 171 | +and sign in using the credentials defined in the Docker Compose file (username: `admin`, password: `grafana`). |
| 172 | + |
| 173 | + |
| 174 | + |
| 175 | +The dashboards are pre-configured to visualize the vulnerability and policy metrics scraped by Prometheus. |
| 176 | + |
| 177 | +### Revoke an access token |
| 178 | + |
| 179 | +If you suspect that your PAT has been compromised or is no longer needed, you can revoke it at any time. |
| 180 | +To revoke a PAT, follow the steps in the [Create and manage access tokens](/security/for-developers/access-tokens/#modify-existing-tokens). |
| 181 | + |
| 182 | +Revoking a PAT immediately invalidates the token, and prevents Prometheus from scraping metrics using that token. |
| 183 | +You will need to create a new PAT and update the Prometheus configuration to use the new token. |
0 commit comments