Integrate Docker Scout with a container registry

docker scout watch is a long-running CLI process that indexes images from a container registry and pushes the results to Docker Scout. It works with any Docker/OCI-compliant registry, including Amazon ECR, Azure Container Registry, JFrog Artifactory, Harbor, and Sonatype Nexus.

How it works

You run docker scout watch on a host you control. The process can:

• Watch specific repositories or an entire registry
• Optionally ingest all existing images once, using --all-images
• Periodically refresh repository lists, using --refresh-registry
• Receive webhook callbacks from registries that support them, for near-real-time analysis instead of polling

After the integration, Docker Scout automatically pulls and analyzes images that you push to the registry. Metadata about your images are stored on the Docker Scout platform, but Docker Scout doesn't store the container images themselves. For more information about how Docker Scout handles image data, see Data handling.

Set up docker scout watch

1. Pick a host on which to run docker scout watch.

   The host must have network access to your registry and be able to access the Scout API (https://api.scout.docker.com) over the internet. If you're using webhook callbacks, the registry must also be able to reach the docker scout watch host on the configured port.

2. Ensure you are running the latest version of Scout.

   $ docker scout version
   

   If necessary, install the latest version of Scout.

3. Authenticate Docker to your registry.

   $ docker login <registry-hostname> --username <user> --password <password-or-access-token>
   

   For Amazon ECR, authenticate using the AWS CLI instead:

   $ aws ecr get-login-password --region <region> | \
     docker login --username AWS --password-stdin \
     <aws_account_id>.dkr.ecr.<region>.amazonaws.com
   

   The AWS identity used must have at least ecr:GetAuthorizationToken and ecr:BatchGetImage permissions on the target registry.

   For Azure Container Registry:

   $ docker login <registry-name>.azurecr.io \
     --username <username> \
     --password <password-or-access-token>
   

   Tip

   As a best practice, use a dedicated user or token with read-only access to the registry.

4. Set up your Scout credentials.

   1. Generate an organization access token. For more details, see Create an organization access token.

   2. Sign in to Docker using the organization access token.

      $ docker login --username <your_organization_name>
      

      When prompted for a password, paste the organization access token.

   3. Connect your local Docker environment to your organization's Docker Scout service.

      $ docker scout enroll <your_organization_name>
      

5. Index existing images. You only need to do this once.

   $ docker scout watch --registry <registry-hostname> --all-images
   

6. Confirm the images have been indexed by viewing them on the Scout Dashboard.

7. Continuously watch for new images.

   $ docker scout watch --registry <registry-hostname> --refresh-registry
   

   docker scout watch is a long-running process. Run it as a system service, for example using systemd or nohup, to ensure it continues running in the background. Use --interval (default 60 seconds) to control polling frequency, and --repository and --tag to narrow scope.

Reference: docker scout watch

Registry-specific options

Some registries need extra configuration beyond a hostname, passed through the --registry flag as a key=value string, for example a REST API endpoint for webhook callbacks, or a non-standard repository layout. Built-in adapters exist for type=artifactory, type=harbor, and type=nexus, and a type=oci adapter covers any OCI-compliant registry that implements the _catalog endpoint. For the full option reference for each type, see docker scout watch.

The following example walks through the type=artifactory adapter in detail. See the CLI reference for equivalent Harbor, Nexus, and generic OCI examples.

Example: JFrog Artifactory

These type=artifactory options override the generic registry handling for the --registry option:

Set up credentials for the Scout client to authenticate with Artifactory, and a secret for Artifactory to authenticate its webhook callbacks:

$ export DOCKER_SCOUT_ARTIFACTORY_API_USER=<user>
$ export DOCKER_SCOUT_ARTIFACTORY_API_PASSWORD=<password-or-access-token>
$ export DOCKER_SCOUT_ARTIFACTORY_WEBHOOK_SECRET=<random-64-128-character-secret>

Tip

As a best practice, create a dedicated user with read-only access and use an access token instead of a password. Generate the webhook secret as a high-entropy random string of 64-128 characters.

Index existing images with the Artifactory-specific registry string:

$ docker scout watch --registry \
  "type=artifactory,registry=example.jfrog.io,api=https://example.jfrog.io/artifactory,include=*/frontend*,exclude=*/dta/*,repository=docker-local,port=9000,subdomain-mode=true" \
  --all-images

Then configure Artifactory to call the webhook: in your Artifactory UI or via REST API, set up a webhook for image push/update events, pointing to your docker scout watch host and port, and include the DOCKER_SCOUT_ARTIFACTORY_WEBHOOK_SECRET for authentication. For more information, see the JFrog Artifactory Webhooks documentation or the JFrog Artifactory REST API Webhooks documentation.

Finally, run the same command with --refresh-registry instead of --all-images as your long-running watch process, so new images are picked up going forward:

$ docker scout watch --registry \
  "type=artifactory,registry=example.jfrog.io,api=https://example.jfrog.io/artifactory,include=*/frontend*,exclude=*/dta/*,repository=docker-local,port=9000,subdomain-mode=true" \
  --refresh-registry