Skip to content

Commit

Permalink
scout: support OATs
Browse files Browse the repository at this point in the history
Signed-off-by: David Karlsson <[email protected]>
  • Loading branch information
dvdksn committed Dec 5, 2024
1 parent 27094d5 commit 4109f42
Show file tree
Hide file tree
Showing 5 changed files with 21 additions and 21 deletions.
31 changes: 16 additions & 15 deletions content/manuals/scout/explore/metrics-exporter.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,12 +37,13 @@ The metrics endpoint exposes the following metrics:
## 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.
Then, create an Organization Access Token (OAT) - a secret token that allows the exporter to authenticate the organization with the Docker Scout API.

Check warning on line 40 in content/manuals/scout/explore/metrics-exporter.md

View workflow job for this annotation

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Docker.RecommendedWords] Consider using 'lets' instead of 'allows' Raw Output: {"message": "[Docker.RecommendedWords] Consider using 'lets' instead of 'allows'", "location": {"path": "content/manuals/scout/explore/metrics-exporter.md", "range": {"start": {"line": 40, "column": 71}}}, "severity": "INFO"}

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](/security/for-developers/access-tokens/#create-an-access-token).
The access token does not require any specific permissions, but it must be an organization access token created for the Docker organization in question,

Check warning on line 42 in content/manuals/scout/explore/metrics-exporter.md

View workflow job for this annotation

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [Docker.SentenceLength] Write short, concise sentences. (<=40 words) Raw Output: {"message": "[Docker.SentenceLength] Write short, concise sentences. (\u003c=40 words)", "location": {"path": "content/manuals/scout/explore/metrics-exporter.md", "range": {"start": {"line": 42, "column": 1}}}, "severity": "WARNING"}
or a personal access token created by a user who is an owner of the Docker organization.
For instructions on how to create an access token, follow the steps in [Create an access token](/security/for-developers/access-tokens/#create-an-access-token).

Once you have created the PAT, store it in a secure location.
Once you have created the access token, store it in a secure location.
You will need to provide this token to the exporter when scraping metrics.

## Prometheus
Expand Down Expand Up @@ -70,11 +71,11 @@ Make sure that there's no firewall rule in place preventing the server from comm

### 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.
To scrape metrics from the Docker Scout Exporter endpoint using Prometheus, you need to configure Prometheus to use the Docker access token as a bearer token.
The exporter requires the access token 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:
This block defines the access token as a bearer token stored in a file:

```yaml
scrape_configs:
Expand All @@ -84,10 +85,10 @@ scrape_configs:
credentials_file: /etc/prometheus/token
```

The content of the file should be the PAT in plain text:
The content of the file should be the access token in plain text:

```console
dckr_pat_...
dckr_oat_...
```

If you are running Prometheus in a Docker container or Kubernetes pod, mount the file into the container using a volume or secret.
Expand All @@ -112,7 +113,7 @@ alongside Grafana with a pre-configured dashboard to visualize the vulnerability
and store it in a plain text file at `/prometheus/prometheus/token` under the template directory.

```plaintext {title=token}
$ echo $DOCKER_PAT > ./prometheus/token
$ echo $DOCKER_TOKEN > ./prometheus/token
```

3. In the Prometheus configuration file at `/prometheus/prometheus/prometheus.yml`,
Expand Down Expand Up @@ -245,7 +246,7 @@ and a Datadog site.
and store it in a plain text file at `/datadog/token` under the template directory.

```plaintext {title=token}
$ echo $DOCKER_PAT > ./token
$ echo $DOCKER_TOKEN > ./token
```

3. In the `/datadog/compose.yaml` file, update the `DD_API_KEY` and `DD_SITE` environment variables
Expand Down Expand Up @@ -346,8 +347,8 @@ To change the scrape interval:

## 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](/security/for-developers/access-tokens/#modify-existing-tokens).
If you suspect that your access token has been compromised or is no longer needed, you can revoke it at any time.
To revoke an access token, follow the steps in the [Create and manage access tokens](/security/for-developers/access-tokens/#modify-existing-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.
Revoking an access token immediately invalidates the token, and prevents Prometheus from scraping metrics using that token.
You will need to create a new access token and update the Prometheus configuration to use the new token.
4 changes: 2 additions & 2 deletions content/manuals/scout/how-tos/configure-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ CLI commands, and the corresponding `docker/scout-cli` container image:
| DOCKER_SCOUT_OFFLINE | Boolean | Use [offline mode](#offline-mode) when indexing SBOM |
| DOCKER_SCOUT_REGISTRY_TOKEN | String | Token for authenticating to a registry when pulling images |
| DOCKER_SCOUT_REGISTRY_USER | String | Username for authenticating to a registry when pulling images |
| DOCKER_SCOUT_REGISTRY_PASSWORD | String | Password or personal access token for authenticating to a registry when pulling images |
| DOCKER_SCOUT_REGISTRY_PASSWORD | String | Password or access token for authenticating to a registry when pulling images |
| DOCKER_SCOUT_HUB_USER | String | Docker Hub username for authenticating to the Docker Scout backend |
| DOCKER_SCOUT_HUB_PASSWORD | String | Docker Hub password or personal access token for authenticating to the Docker Scout backend |
| DOCKER_SCOUT_HUB_PASSWORD | String | Docker Hub password or access token for authenticating to the Docker Scout backend |
| DOCKER_SCOUT_NEW_VERSION_WARN | Boolean | Warn about new versions of the Docker Scout CLI |
| DOCKER_SCOUT_EXPERIMENTAL_WARN | Boolean | Warn about experimental features |
| DOCKER_SCOUT_EXPERIMENTAL_POLICY_OUTPUT | Boolean | Disable experimental output for policy evaluation |
Expand Down
4 changes: 2 additions & 2 deletions content/manuals/scout/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,8 +115,8 @@ Use the `docker/scout-cli` to run `docker scout` commands without installing the

```console
$ docker run -it \
-e DOCKER_SCOUT_HUB_USER=<your Docker Hub user name> \
-e DOCKER_SCOUT_HUB_PASSWORD=<your Docker Hub PAT> \
-e DOCKER_SCOUT_HUB_USER=<your-docker-username> \
-e DOCKER_SCOUT_HUB_PASSWORD=<your-docker-token> \
docker/scout-cli <command>
```

Expand Down
2 changes: 1 addition & 1 deletion content/manuals/scout/integrations/environment/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ refer to the [CLI reference](/reference/cli/docker/scout/environment.md).
Before you start, set the following environment variables in your CI system:

- `DOCKER_SCOUT_HUB_USER`: your Docker Hub username
- `DOCKER_SCOUT_HUB_PASSWORD`: your Docker Hub personal access token
- `DOCKER_SCOUT_HUB_PASSWORD`: your Docker Hub access token

Make sure the variables are accessible to your project.

Expand Down
1 change: 0 additions & 1 deletion content/manuals/security/for-admins/access-tokens.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@ The organization access tokens feature is currently in [Beta](../../release-life
> Organization access tokens aren't currently compatible with the following services:
>
> - Docker Build Cloud
> - Docker Scout
> - Docker REST APIs
>
> If you use these services, you must use personal access tokens instead.
Expand Down

0 comments on commit 4109f42

Please sign in to comment.