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 | Description |
|---|---|
DOCKER_SCOUT_CACHE_FORMAT |
Format of the local image cache; can be oci or tar |
DOCKER_SCOUT_CACHE_DIR |
Directory where the local SBOM cache is stored |
DOCKER_SCOUT_NO_CACHE |
Disable the local SBOM cache |
DOCKER_SCOUT_REGISTRY_TOKEN |
Registry Access token to authenticate when pulling images |
DOCKER_SCOUT_REGISTRY_USER |
Registry user name to authenticate when pulling images |
DOCKER_SCOUT_REGISTRY_PASSWORD |
Registry password/PAT to authenticate when pulling images |
DOCKER_SCOUT_HUB_USER |
Docker Hub user name to authenticate against the Docker Scout backend |
DOCKER_SCOUT_HUB_PASSWORD |
Docker Hub password/PAT to authenticate against the Docker Scout backend |
DOCKER_SCOUT_OFFLINE |
Offline mode during SBOM indexing |
DOCKER_SCOUT_NEW_VERSION_WARN |
Warn about new versions of the Docker Scout CLI |
DOCKER_SCOUT_EXPERIMENTAL_WARN |
Warn about experimental features |
DOCKER_SCOUT_EXPERIMENTAL_POLICY_OUTPUT |
Disable experimental policy output |
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/[email protected]
# Login against a Docker registry except on PR
# https://github.com/docker/login-action
- name: Log into registry ${{ env.REGISTRY }}
uses: docker/[email protected]
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/[email protected]
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/[email protected]
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-code --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-code --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}
