• Docker Scout
• Usage
• CLI Plugin Installation
• Run as container
• CI integration
• License

Docker Scout

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.

Usage

The CLI documentation is available in this repository.

See the reference documentation to learn about Docker Scout including Docker Desktop and Docker Hub integrations.

Environment Variables

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.

CLI Plugin Installation

Docker Desktop

docker scout CLI plugin is available by default on Docker Desktop starting with version 4.17.

Manual Installation

To install it manually:

• Download the docker-scout binary corresponding to your platform from the latest or other releases.
• Uncompress it as
  • docker-scout on Linux and macOS
  • docker-scout.exe on Windows
• Copy the binary to the scout directory
  • $HOME/.docker/scout on Linux and macOS
  • %USERPROFILE%\.docker\scout on 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 scout directory to your .docker/config.json as a plugin directory
  • $HOME/.docker/config.json on Linux and macOS
  • %USERPROFILE%\.docker\config.json on Windows
  • Add the cliPluginsExtraDirs property to the config.json file

{
...
"cliPluginsExtraDirs": [
"<full path to the .docker/scout folder>"
],
...
}

Script Installation (macOS and Linux)

To install, run the following command in your terminal:

curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s --

Run as container

A container image to run the Docker Scout CLI in containerized environments is available at docker/scout-cli.

CI Integration

Docker Scout CLI can be used in CI environments. See below for the various ways to integrate the CLI into your CI pipelines.

GitHub Action

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: Dockeron:
push:
tags: [ "*" ]branches:
- 'main'pull_request:
branches: [ "**" ]env:
# Use docker.io for Docker Hub if emptyREGISTRY: docker.ioIMAGE_NAME: ${{ github.repository }}SHA: ${{ github.event.pull_request.head.sha || github.event.after }}jobs:
build:
runs-on: ubuntu-latestpermissions:
contents: readpackages: writesteps:
- name: Checkout repositoryuses: actions/checkout@v3with:
ref: ${{ env.SHA }}
- name: Setup Docker buildxuses: 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.0with:
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 metadataid: metauses: docker/metadata-action@v4.4.0with:
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 imageid: build-and-pushuses: docker/build-push-action@v4.0.0with:
context: .push: truetags: ${{ steps.meta.outputs.tags }}labels: ${{ steps.meta.outputs.labels }}cache-from: type=ghacache-to: type=gha,mode=max
- name: Docker Scoutid: docker-scoutif: ${{ github.event_name == 'pull_request' }}uses: docker/scout-action@dd36f5b0295baffa006aa6623371f226cc03e506with:
command: cvesimage: ${{ steps.meta.outputs.tags }}only-severities: critical,highexit-code: true

GitLab

Use the following pipeline definition as a template to get Docker Scout integrated in GitLab CI:

docker-build:
image: docker:lateststage: buildservices:
- docker:dindbefore_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-stdinscript:
- | 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_BRANCHexists:
- Dockerfile

CircleCI

Use the following pipeline definition as a template to get Docker Scout integrated in CircleCI project:

version: 2.1jobs:
build:
docker:
- image: cimg/base:stableenvironment:
IMAGE_TAG: docker/scout-demo-service:lateststeps:
# 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 Scoutcommand: | 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 imagecommand: docker build -t $IMAGE_TAG .# Run Docker Scout 
- run:
name: Scan image for CVEscommand: | docker-scout cves $IMAGE_TAG --exit-code --only-severity critical,highworkflows:
build-docker-image:
jobs:
- build

Microsoft Azure DevOps Pipelines

Use the following pipeline definition as a template to get Docker Scout integrated in Azure DevOps Pipelines:

trigger:
- mainresources:
- repo: selfvariables:
tag: '$(Build.BuildId)'image: 'vonwig/nodejs-service'stages:
- stage: BuilddisplayName: Build imagejobs:
- job: BuilddisplayName: Buildpool:
vmImage: ubuntu-lateststeps:
- task: Docker@2displayName: Build an imageinputs:
command: builddockerfile: '$(Build.SourcesDirectory)/Dockerfile'repository: $(image)tags: | $(tag) - task: CmdLine@2displayName: Find CVEs on imageinputs:
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,high

Jenkins

The 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.

Bitbucket

Use the following pipeline definition as a template to get Docker Scout integrated in Bitbucket Pipelines:

image: dockerpipelines:
default:
- step:
name: Buildservices:
- dockercaches:
- dockerscript:
- 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 needed

This 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.

License

The Docker Scout CLI is licensed under the Terms and Conditions of the Docker Subscription Service Agreement.