Docker Scout is a set of software supply chain features integrated into Docker's user interfaces and command line interface (CLI). These features offer comprehensive visibility into the structure and security of container images. This repository contains installable binaries of the docker scout CLI plugin.
The CLI documentation is available in this repository.
See the reference documentation to learn about Docker Scout including Docker Desktop and Docker Hub integrations.
The following environment variables are available to configure the Scout CLI:
| Name | Format | Description |
|---|---|---|
DOCKER_SCOUT_CACHE_FORMAT | String | Format of the local image cache; can be oci or tar |
DOCKER_SCOUT_CACHE_DIR | String | Directory where the local SBOM cache is stored |
DOCKER_SCOUT_NO_CACHE | Boolean | Disable the local SBOM cache |
DOCKER_SCOUT_OFFLINE | Boolean | Offline mode during SBOM indexing |
DOCKER_SCOUT_REGISTRY_TOKEN | String | Registry Access token to authenticate when pulling images |
DOCKER_SCOUT_REGISTRY_USER | String | Registry user name to authenticate when pulling images |
DOCKER_SCOUT_REGISTRY_PASSWORD | String | Registry password/PAT to authenticate when pulling images |
DOCKER_SCOUT_HUB_USER | String | Docker Hub user name to authenticate against the Docker Scout backend |
DOCKER_SCOUT_HUB_PASSWORD | String | Docker Hub password/PAT to authenticate against 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 policy output |
You can found further information about environment variables here.
docker scout CLI plugin is available by default on Docker Desktop starting with version 4.17.
To install it manually:
- Download the
docker-scoutbinary corresponding to your platform from the latest or other releases. - Uncompress it as
docker-scouton Linux and macOSdocker-scout.exeon Windows
- Copy the binary to the
scoutdirectory$HOME/.docker/scouton Linux and macOS%USERPROFILE%\.docker\scouton Windows
- Make it executable on Linux and macOS
chmod +x $HOME/.docker/scout/docker-scout
- Authorize the binary to be executable on macOS
xattr -d com.apple.quarantine $HOME/.docker/scout/docker-scout
- Add the
scoutdirectory to your.docker/config.jsonas a plugin directory$HOME/.docker/config.jsonon Linux and macOS%USERPROFILE%\.docker\config.jsonon Windows- Add the
cliPluginsExtraDirsproperty to theconfig.jsonfile
{ ... "cliPluginsExtraDirs": [ "<full path to the .docker/scout folder>" ], ... } To install, run the following command in your terminal:
curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s --A container image to run the Docker Scout CLI in containerized environments is available at docker/scout-cli.
Docker Scout CLI can be used in CI environments. See below for the various ways to integrate the CLI into your CI pipelines.
An early prototype of running the Docker Scout CLI as part of a GitHub Action workflow is available at docker/scout-action.
The following GitHub Action workflow can be used as a template to integrate Docker Scout:
name: Docker on: push: tags: [ "*" ] branches: - 'main' pull_request: branches: [ "**" ] env: # Use docker.io for Docker Hub if empty REGISTRY: docker.io IMAGE_NAME: ${{ github.repository }} SHA: ${{ github.event.pull_request.head.sha || github.event.after }} jobs: build: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - name: Checkout repository uses: actions/checkout@v3 with: ref: ${{ env.SHA }} - name: Setup Docker buildx uses: docker/setup-buildx-action@v2.5.0 # Login against a Docker registry except on PR # https://github.com/docker/login-action - name: Log into registry ${{ env.REGISTRY }} uses: docker/login-action@v2.1.0 with: registry: ${{ env.REGISTRY }} username: ${{ secrets.DOCKER_USER }} password: ${{ secrets.DOCKER_PAT }} # Extract metadata (tags, labels) for Docker # https://github.com/docker/metadata-action - name: Extract Docker metadata id: meta uses: docker/metadata-action@v4.4.0 with: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} labels: | org.opencontainers.image.revision=${{ env.SHA }} tags: | type=edge,branch=$repo.default_branch type=semver,pattern=v{{version}} type=sha,prefix=,suffix=,format=short # Build and push Docker image with Buildx (don't push on PR) # https://github.com/docker/build-push-action - name: Build and push Docker image id: build-and-push uses: docker/build-push-action@v4.0.0 with: context: . push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} cache-from: type=gha cache-to: type=gha,mode=max - name: Docker Scout id: docker-scout if: ${{ github.event_name == 'pull_request' }} uses: docker/scout-action@dd36f5b0295baffa006aa6623371f226cc03e506 with: command: cves image: ${{ steps.meta.outputs.tags }} only-severities: critical,high exit-code: trueUse the following pipeline definition as a template to get Docker Scout integrated in GitLab CI:
docker-build: image: docker:latest stage: build services: - docker:dind before_script: - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY # Install curl and the Docker Scout CLI - | apk add --update curl curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- apk del curl rm -rf /var/cache/apk/* # Login to Docker Hub required for Docker Scout CLI - echo "$DOCKER_HUB_PAT" | docker login --username "$DOCKER_HUB_USER" --password-stdin script: - | if [[ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]]; then tag="" echo "Running on default branch '$CI_DEFAULT_BRANCH': tag = 'latest'" else tag=":$CI_COMMIT_REF_SLUG" echo "Running on branch '$CI_COMMIT_BRANCH': tag = $tag" fi - docker build --pull -t "$CI_REGISTRY_IMAGE${tag}" . - | if [[ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]]; then # Get a CVE report for the built image and fail the pipeline when critical or high CVEs are detected docker scout cves "$CI_REGISTRY_IMAGE${tag}" --exit-code --only-severity critical,high else # Compare image from branch with latest image from the default branch and fail if new critical or high CVEs are detected docker scout compare "$CI_REGISTRY_IMAGE${tag}" --to "$CI_REGISTRY_IMAGE:latest" --exit-on vulnerability,policy --only-severity critical,high --ignore-unchanged fi - docker push "$CI_REGISTRY_IMAGE${tag}" rules: - if: $CI_COMMIT_BRANCH exists: - DockerfileUse the following pipeline definition as a template to get Docker Scout integrated in CircleCI project:
version: 2.1 jobs: build: docker: - image: cimg/base:stable environment: IMAGE_TAG: docker/scout-demo-service:latest steps: # Checkout the repository files - checkout # Set up a separate Docker environment to run `docker` commands in - setup_remote_docker: version: 20.10.24 # Install Docker Scout and login to Docker Hub - run: name: Install Docker Scout command: | env curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- -b /home/circleci/bin echo $DOCKER_HUB_PAT | docker login -u $DOCKER_HUB_USER --password-stdin # Build the Docker image - run: name: Build Docker image command: docker build -t $IMAGE_TAG . # Run Docker Scout - run: name: Scan image for CVEs command: | docker-scout cves $IMAGE_TAG --exit-code --only-severity critical,high workflows: build-docker-image: jobs: - buildUse the following pipeline definition as a template to get Docker Scout integrated in Azure DevOps Pipelines:
trigger: - main resources: - repo: self variables: tag: '$(Build.BuildId)' image: 'vonwig/nodejs-service' stages: - stage: Build displayName: Build image jobs: - job: Build displayName: Build pool: vmImage: ubuntu-latest steps: - task: Docker@2 displayName: Build an image inputs: command: build dockerfile: '$(Build.SourcesDirectory)/Dockerfile' repository: $(image) tags: | $(tag) - task: CmdLine@2 displayName: Find CVEs on image inputs: script: | # Install the Docker Scout CLI curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- # Login to Docker Hub required for Docker Scout CLI docker login -u $(DOCKER_HUB_USER) -p $(DOCKER_HUB_PAT) # Get a CVE report for the built image and fail the pipeline when critical or high CVEs are detected docker scout cves $(image):$(tag) --exit-code --only-severity critical,highThe following snippet can be added to a Jenkinsfile to install and analyze images:
stage('Analyze image') { steps { // Install Docker Scout sh 'curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- -b /usr/local/bin' // Log into Docker Hub sh 'echo $DOCKER_HUB_PAT | docker login -u $DOCKER_HUB_USER --password-stdin' // Analyze and fail on critical or high vulnerabilities sh 'docker-scout cves $IMAGE_TAG --exit-code --only-severity critical,high' } }This example assume two secrets to be available to authenticate against Docker Hub, called DOCKER_HUB_USER and DOCKER_HUB_PAT.
Use the following pipeline definition as a template to get Docker Scout integrated in Bitbucket Pipelines:
image: docker pipelines: default: - step: name: Build services: - docker caches: - docker script: - echo "$DOCKER_HUB_PAT" | docker login --username "$DOCKER_HUB_USER" --password-stdin $CI_REGISTRY # Install curl and the Docker Scout CLI - | export DOCKER_BUILDKIT=0 apk add --update curl curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- apk del curl rm -rf /var/cache/apk/* # Login to Docker Hub required for Docker Scout CLI - echo "$DOCKER_HUB_PAT" | docker login --username "$DOCKER_HUB_USER" --password-stdin - | export DEVELOPMENT_BRANCH="main" if [[ "$BITBUCKET_BRANCH" == "$DEVELOPMENT_BRANCH" ]]; then # Bitbucket uses master by default, adjust if your default branch is different tag=":latest" echo "Running on default branch '$DEVELOPMENT_BRANCH': tag = 'latest'" else tag=":$BITBUCKET_COMMIT" echo "Running on branch '$BITBUCKET_BRANCH': tag = $tag" fi - docker build --pull -t "$CI_REGISTRY_IMAGE${tag}" . - | if [[ "$BITBUCKET_BRANCH" == "$DEVELOPMENT_BRANCH" ]]; then # Get a CVE report for the built image and fail the pipeline when critical or high CVEs are detected docker scout cves "$CI_REGISTRY_IMAGE${tag}" --exit-code --only-severity critical,high else # Compare image from branch with latest image from the default branch and fail if new critical or high CVEs are detected docker scout compare "$CI_REGISTRY_IMAGE${tag}" --to "$CI_REGISTRY_IMAGE:latest" --exit-on vulnerability,policy --only-severity critical,high --ignore-unchanged fi - docker push "$CI_REGISTRY_IMAGE${tag}" definitions: services: docker: memory: 2048 # Optional: Increase if neededThis example assumes two secrets to be available to authenticate against Docker Hub, called DOCKER_HUB_USER and DOCKER_HUB_PAT, also is necessary more two secrets called CI_REGISTRY, CI_REGISTRY_IMAGE about registry info.
The Docker Scout CLI is licensed under the Terms and Conditions of the Docker Subscription Service Agreement.
![@docker-scout-ci[bot]](https://avatars.githubusercontent.com/u/5429470?s=64&v=4){kind=small}
