GitHub - docker/scout-action: Docker Scout GitHub Action (original) (raw)

About

GitHub Action to run the Docker Scout CLI as part of your workflows.

You can pick one of the following commands to run:

• quickview: get a quick overview of an image, base image and available recommendations
• compare: compare an image to a second one (for instance to latest)
• cves: display vulnerabilities of an image
• recommendations: display available base image updates and remediation recommendations
• sbom: generate the SBOM of the image
• environment: record an image to an environment
• attestation-add: add attestation to an existing image

Inputs

Command

You can run one or multiple commands in the same GitHub Action run. Use a comma separated list to run several commands.

The commands will be run in the order of the value, and will share the same parameters.

For instance, if you built an image and want to display a quickview as well as to compare it against the latest indexed one, set the action as following:

command: quickview,compare image: ${{ steps.meta.outputs.tags }} to-latest: true

Authentication

Login to Docker Hub

To use scout features you need to be authenticated against Docker Hub.

You can use the parameters below to authenticate, or you can use the docker/login-action.

Login to a registry to pull private images (non Docker Hub)

Common Inputs

Image

(*) If image is not set (or empty) the most recently built image, if any, will be used instead.

Prefix

The image field can be prefixed to indicate the type of content to analyse. If no prefix is set, the image:// prefix is used.

Available prefixes:

• image://: optional prefix, the target is an image that first will be resolved locally then, if not found, will be resolved to the associated registry
• local://: only resolve the image from the local image store
• registry://: do not use the local image store, only use the registry
• oci-dir://: local directory to be read as an OCI directory
• archive://: image archive generated by docker save command, as a tar file
• fs://: local directory or file
• sbom:// SPDX file or in-toto attestation file with SPDX predicate or syft json SBOM file

Organization namespace

Namespace of the Docker Organization is required to match the query with the right data.

When using environments (for instance to compare an image to the one from a defined environment, or when comparing to the latest indexed) organization parameter is required.

Step Summary

By default the Markdown output of the command (if supported) will be displayed as a Job Summary. This can be disabled if needed.

Pull Request Comments

When triggered by a pull_request event, the output of the scout command can be written as a comment.

This behaviour is enabled by default.

By default one single comment per job step will be kept and updated at each run. If you prefer to keep previous comments but hide them, set the keep-previous-comments parameter to true.

pull-requests: write permission is required to allow the GitHub action to create the comment.

Output

The text version of the command output will be displayed in the logs. The markdown version (if exists) of the command output will be set as an output of the step, using the command name as identifier, and will be displayed as Pull Request comment or Step Summary.

compare Inputs

Compare to an image

See Prefix above about the available prefixes for the to argument.

Compare to an environment

(*) One and only one needs to be defined.

Common Inputs

cves Inputs

sbom Inputs

recommendations Inputs

environment Inputs

The image input must be an image in your local image store or in a registry. You can use prefixes to control whether to use a local or remote image. The following prefixes are supported:

• image:// (optional)
• local://
• registry://

See Environment example

attestation-add Inputs

Example usage

Build an image, push and compare

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 }}

Use latest as the tag to compare to if empty, assuming that it's already pushed

COMPARE_TAG: latest

jobs: build:

runs-on: ubuntu-latest
permissions:
  contents: read
  packages: write
  pull-requests: 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
    with:
      driver-opts: |
        image=moby/buildkit:v0.10.6

  # 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: <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>e</mi><mi>n</mi><mi>v</mi><mi mathvariant="normal">.</mi><mi>R</mi><mi>E</mi><mi>G</mi><mi>I</mi><mi>S</mi><mi>T</mi><mi>R</mi><mi>Y</mi></mrow><mi mathvariant="normal">/</mi></mrow><annotation encoding="application/x-tex">{{ env.REGISTRY }}/</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord"><span class="mord"><span class="mord mathnormal">e</span><span class="mord mathnormal">n</span><span class="mord mathnormal" style="margin-right:0.03588em;">v</span><span class="mord">.</span><span class="mord mathnormal">REG</span><span class="mord mathnormal" style="margin-right:0.07847em;">I</span><span class="mord mathnormal" style="margin-right:0.00773em;">STR</span><span class="mord mathnormal" style="margin-right:0.22222em;">Y</span></span></span><span class="mord">/</span></span></span></span>{{ 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@v1
    with:
      command: compare
      image: ${{ steps.meta.outputs.tags }}
      to: <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>e</mi><mi>n</mi><mi>v</mi><mi mathvariant="normal">.</mi><mi>R</mi><mi>E</mi><mi>G</mi><mi>I</mi><mi>S</mi><mi>T</mi><mi>R</mi><mi>Y</mi></mrow><mi mathvariant="normal">/</mi></mrow><annotation encoding="application/x-tex">{{ env.REGISTRY }}/</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord"><span class="mord"><span class="mord mathnormal">e</span><span class="mord mathnormal">n</span><span class="mord mathnormal" style="margin-right:0.03588em;">v</span><span class="mord">.</span><span class="mord mathnormal">REG</span><span class="mord mathnormal" style="margin-right:0.07847em;">I</span><span class="mord mathnormal" style="margin-right:0.00773em;">STR</span><span class="mord mathnormal" style="margin-right:0.22222em;">Y</span></span></span><span class="mord">/</span></span></span></span>{{ env.IMAGE_NAME }}:${{ env.COMPARE_TAG }}
      ignore-unchanged: true
      only-severities: critical,high
      write-comment: true
      github-token: ${{ secrets.GITHUB_TOKEN }} # to be able to write the comment

All-in-one

For the latest built image, display:

• the vulnerabilities (ignoring the base image, only displaying vulnerabilities with a fix available)

• the available recommendations

• compare it to the latest image indexed for the same repository (only displaying unchanged packages and vulnerabilities that already have a fix)

    - name: Docker Scout
      id: docker-scout
      uses: docker/scout-action@v1
      with:
        command: cves,recommendations,compare
        to-latest: true
        ignore-base: true
        ignore-unchanged: true
        only-fixed: true

Analyze vulnerabilities and upload report to GitHub code scanning

When GitHub code scanning is enabled, the sarif-file input can be used to upload the vulnerabilities to GitHub.

  - name: Analyze for critical and high CVEs
    id: docker-scout-cves
    if: ${{ github.event_name != 'pull_request_target' }}
    uses: docker/scout-action@v1
    with:
      command: cves
      image: ${{ steps.meta.outputs.tags }}
      sarif-file: sarif.output.json
      summary: true

  - name: Upload SARIF result
    id: upload-sarif
    if: ${{ github.event_name != 'pull_request_target' }}
    uses: github/codeql-action/upload-sarif@v2
    with:
      sarif_file: sarif.output.json

Record an image deployed to an environment

  - 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-environment
    uses: docker/scout-action@v1
    with:
      command: environment
      image: ${{ steps.meta.outputs.tags }}
      environment: prod
      organization: my-docker-org

License

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