Skip to content

Latest commit

 

History

History
311 lines (245 loc) · 9.9 KB

README.md

File metadata and controls

311 lines (245 loc) · 9.9 KB

Note: Docker Scout is a new product and is free while in early access. Read more about Docker Scout.

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.

CLI Plugin Installation

Docker Desktop

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

Script Installation

To install, run the following command in your terminal:

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

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 it in your local CLI plugin directory
    • $HOME/.docker/cli-plugins on Linux and macOS
    • %USERPROFILE%\.docker\cli-plugins on Windows
  • Make it executable on Linux and macOS
    • chmod +x $HOME/.docker/cli-plugins/docker-scout
  • Authorize the binary to be executable on macOS
    • xattr -d com.apple.quarantine $HOME/.docker/cli-plugins/docker-scout

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: 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: true

Gitlab

Use 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
    - docker login -u "$DOCKER_HUB_USER" -p "$DOCKER_HUB_PAT"
  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:
        - Dockerfile

CircleCI

Use 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:
      - build

Microsoft Azure DevOps Pipelines

Use 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,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-serverity critical,high'
            }
        }

This example assume two secrets to be available to authenticate against Docker Hub, called DOCKER_HUB_USER and DOCKER_HUB_PAT.

License

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