Add using Docker Scout with CI docs

Signed-off-by: Chris Chinchilla <chris.ward@docker.com>
This commit is contained in:
Chris Chinchilla 2023-06-22 15:30:26 +02:00
parent 2f83755dba
commit c02d261225
No known key found for this signature in database
GPG Key ID: 78FA9FB7CEAE483F
4 changed files with 144 additions and 5 deletions

View File

@ -1901,6 +1901,8 @@ manuals:
title: Artifactory integration
- path: /scout/advisory-db-sources/
title: Advisory Database
- path: /scout/ci
title: Continuous integration
- sectiontitle: Administration and security
section:

142
scout/ci.md Normal file
View File

@ -0,0 +1,142 @@
---
description: How to setup Docker Scout in continuous integration pipelines
keywords: scanning, vulnerabilities, Hub, supply chain, security, ci, continuous integration, github actions, gitlab
title: Using Docker Scout in continuous integration
---
{% include scout-early-access.md %}
Using the Docker Scout CLI plugin, you can analyze Docker images in
continuous integration pipelines as you build them.
## GitHub Actions
You can use [the Docker Scout GitHub action](https://github.com/docker/scout-action) to run Docker Scout CLI commands
as part of a workflow.
The following example works in a repository containing a Docker image's definition and contents. Triggered by a pull request, the action builds the
image and uses Docker Scout to compare the new version to the current published
version.
<!-- Create action? -->
First, set up the rest of the workflow. There's a lot that's not specific to Docker
Scout but needed to create the images to compare.
Add the following to a GitHub action YAML file:
```yaml
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
```
This sets up the workflow to run on pull requests and pushes to the `main`
branch, and sets up environment variables available to all workflow steps. It
then defines a job called `build` that runs on the latest Ubuntu image and sets
the permissions available to the job.
Add the following to the YAML file:
```yaml
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
```
This creates workflow steps to checkout the repository, set up Docker buildx,
log into the Docker registry, and extract metadata from Git reference and GitHub
events to use in later steps.
Add the following to the YAML file:
```yaml
# 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
```
This uses the extracted metadata from the previous step to build and push the
Docker image to Docker Hub. GitHub Actions skips this step on pull requests and
only runs when a pull request is merged.
Add the following to the YAML file:
```yaml
- name: Docker Scout
id: docker-scout
if: $\{\{ github.event_name == 'pull_request' \}\}
uses: docker/scout-action@dd36f5b0295baffa006aa6623371f226cc03e506
with:
command: compare
image: $\{\{ steps.meta.outputs.tags \}\}
to: $\{\{ env.REGISTRY \}\}/$\{\{ env.IMAGE_NAME \}\}:edge
ignore-unchanged: true
only-severities: critical,high
token: $\{\{ secrets.DOCKER_PAT \}\}
```
This final step uses the Docker Scout CLI to run [the `compare` command](../engine/reference/commandline/scout_compare.md), comparing the new
image to the published one. It only shows critical or high-severity vulnerabilities and
ignores vulnerabilities that haven't changed since the last analysis.
The GitHub Action outputs the comparison results as a table and a summary
in the action output.
![A screenshot showing the results of Docker Scout output in a GitHub Action](./images/gha-output.png)

View File

@ -1,5 +0,0 @@
# Using Docker Scout in continuous integration
By using the Docker Scout CLI plugin, you can analyze Docker images in continuous integration pipelines.
## GitHub Actions

BIN
scout/images/gha-output.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 167 KiB