Merge pull request docker#18961 from dvdksn/scout-remediation-github

scout: github integration, base image remediation

content/develop/develop-images/guidelines.md

@@ -117,3 +117,66 @@ frequently changed where possible.
 
 For more information about the Docker build cache and how to optimize your
 builds, see [cache management](../../build/cache/_index.md).
+
+## Pin base image versions
+
+Image tags are mutable, meaning a publisher can update a tag to point to a new
+image. This is a useful because it lets publishers update tags to point to
+newer versions of an image. And as an image consumer, it means you
+automatically get the new version when you re-build your image.
+
+For example, if you specify `FROM alpine:3.19` in your Dockerfile, `3.19`
+resolves to the latest patch version for `3.19`.
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM alpine:3.19
+```
+
+At one point in time, the `3.19` tag might point to version 3.19.1 of the
+image. If you rebuild the image 3 months later, the same tag might point to a
+different version, such as 3.19.4. This publishing workflow is best practice,
+and most publishers use this tagging strategy, but it isn't enforced.
+
+The downside with this is that you're not guaranteed to get the same for every
+build. This could result in breaking changes, and it means you also don't have
+an audit trail of the exact image versions that you're using.
+
+To fully secure your supply chain integrity, you can pin the image version to a
+specific digest. By pinning your images to a digest, you're guaranteed to
+always use the same image version, even if a publisher replaces the tag with a
+new image. For example, the following Dockerfile pins the Alpine image to the
+same tag as earlier, `3.19`, but this time with a digest reference as well.
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM alpine:3.19@sha256:13b7e62e8df80264dbb747995705a986aa530415763a6c58f84a3ca8af9a5bcd
+```
+
+With this Dockerfile, even if the publisher updates the `3.19` tag, your builds
+would still use the pinned image version:
+`13b7e62e8df80264dbb747995705a986aa530415763a6c58f84a3ca8af9a5bcd`.
+
+While this helps you avoid unexpected changes, it's also more tedious to have
+to look up and include the image digest for base image versions manually each
+time you want to update it. And you're opting out of automated security fixes,
+which is likely something you want to get.
+
+Docker Scout has a built-in [**Outdated base images**
+policy](../../scout/policy/_index.md#outdated-base-images) that checks for
+whether the base image version you're using is in fact the latest version. This
+policy also checks if pinned digests in your Dockerfile correspond to the
+correct version. If a publisher updates an image that you've pinned, the policy
+evaluation returns a non-compliant status, indicating that you should update
+your image.
+
+Docker Scout also supports an automated remediation workflow for keeping your
+base images up-to-date. When a new image digest is available, Docker Scout can
+automatically raise a pull request on your repository to update your
+Dockerfiles to use the latest version. This is better than using a tag that
+changes the version automatically, because you're in control and you have an
+audit trail of when and how the change occurred.
+
+For more information about automatically updating your base images with Docker
+Scout, see
+[Remediation](../../scout/policy/remediation.md#automatic-base-image-updates)

content/scout/integrations/_index.md

@@ -72,3 +72,13 @@ you've enabled the integration.
 The following code quality integrations are available:
 
 - [SonarQube](sonarqube.md)
+
+### Source code management
+
+Integrate Docker Scout with your version control system to get guided
+remediation advice on how to address issues detected by Docker Scout image
+analysis, directly in your repositories.
+
+The following source code management integrations are available:
+
+- [GitHub](source-code-management/github.md) {{< badge color=violet text=Beta >}}

content/scout/integrations/source-code-management/github.md

@@ -0,0 +1,62 @@
+---
+title: Integrate Docker Scout with GitHub
+description: Integrate Docker Scout using the GitHub app to get remediation advice directly in your repositories
+keywords: scout, github, integration, image analysis, supply chain, remediation, source code
+---
+
+> **Beta feature**
+>
+> The GitHub integration is currently in [Beta](../../../release-lifecycle.md#Beta).
+{ .experimental }
+
+The GitHub app integration for Docker Scout grants Docker Scout access to your
+source code repository on GitHub. This improved visibility into how your image
+gets created means Docker Scout can give you automated and contextual
+remediation advice.
+
+## How it works
+
+When you enable the GitHub integration, Docker Scout can make a direct link
+between the image analysis results and the source.
+
+When analyzing your image, Docker Scout checks for [provenance
+attestations](../../../build/attestations/slsa-provenance.md) to detect the
+location of the source code repository for the image. If the source location is
+found, and you've enabled the GitHub app, Docker Scout parses the Dockerfile
+used to create the image.
+
+Parsing the Dockerfile reveals the base image tag used to build the image. By
+knowing the base image tags used, Docker Scout can detect whether the tag is
+outdated, meaning it's been changed to a different image digest. For example,
+say you're using `alpine:3.18` as your base image, and at a later point in
+time, the image maintainers release a patch version for version `3.18`,
+containing security fixes. The `alpine:3.18` tag you've been using becomes
+out-of-date; the `alpine:3.18` you're using is no longer the latest.
+
+When this happens, Docker Scout detects the discrepancy and surfaces it through
+the [Outdated base images](../../policy/_index.md#outdated-base-images) policy.
+When the GitHub integration's enabled, you'll also get automated suggestions on
+how to update your base image. For more information about how Docker Scout can
+help you automatically improve your supply chain conduct and security posture,
+see [Remediation](../../policy/remediation.md).
+
+## Setup
+
+To integrate Docker Scout with your GitHub organization:
+
+1. Go to [Integrations](https://scout.docker.com/settings/integrations/) on the
+   Docker Scout Dashboard.
+2. Find the **GitHub** integration under the **Source code management**
+   section, and select **Integrate**.
+3. On the integration page that opens, select the
+   **Integrate GitHub app** button to open GitHub.
+4. Select the organization that you want to integrate.
+5. Select whether you want to integrate all repositories in the GitHub
+   organization or a manual selection of repositories.
+6. Select **Install & Authorize** to add the Docker Scout app to the
+   organization.
+
+   This redirects you back to the Docker Scout Dashboard, which lists your
+   active GitHub integrations.
+
+The GitHub integration is now active.

content/scout/policy/remediation.md

@@ -0,0 +1,148 @@
+---
+title: Remediation with Docker Scout
+description: Learn how Docker Scout can help you improve your software quality automatically, using remediation
+keywords: scout, supply chain, security, remediation, automation
+---
+
+> **Beta feature**
+>
+> Remediation with Docker Scout is currently in [Beta](../../release-lifecycle.md#Beta).
+{ .experimental }
+
+Docker Scout helps you remediate supply chain or security issues by providing
+recommendations based on policy evaluation results. Recommendations are
+suggested actions you can take that improve policy compliance, or that add
+metadata to images which enables Docker Scout to provide better evaluation
+results and recommendations.
+
+Docker Scout provides remediation advice for the following policies:
+
+- [Outdated base images](#outdated-base-image-remediation)
+- [Supply chain attestations](#supply-chain-attestations-remediation)
+
+For images that violate policy, the recommendations focus on addressing
+compliance issues and fixing violations. For images where Docker Scout is
+unable to determine compliance, recommendations show you how to meet the
+prerequisites that ensure Docker Scout can successfully evaluate the policy.
+
+## View recommendations
+
+Recommendations appear on the policy details pages of the Docker Scout
+Dashboard. To get to this page:
+
+1. Open the [Docker Scout Dashboard](https://scout.docker.com/)
+2. Go to the **Policies** page.
+3. Select a policy in the list.
+
+The policy details page groups evaluation results into two different tabs
+depending on the policy status:
+
+- Violations
+- Compliance unknown
+
+The **Violations** tab lists images that don't comply with the selected policy.
+The **Compliance unknown** tab lists images that Docker Scout is unable to
+determine the compliance status for. When compliance is unknown, Docker Scout
+needs more information about the image.
+
+To view recommended actions for an image, hover over one of the images in the
+list to reveal a **View fixes** button.
+
+![Remediation for policy violations](../images/remediation.png)
+
+Select the **View fixes** button to opens the remediation side panel containing
+recommended actions for your image.
+
+If there are more than one recommendations available, the primary
+recommendation displays as the **Recommended fix**. Additional recommendations
+are listed as **Quick fixes**. Quick fixes are usually actions that provide a
+temporary solution.
+
+The side panel may also contain one or more help sections related to the
+available recommendations.
+
+## Outdated base image remediation
+
+The **Outdated base images** policy checks whether the base image you use is
+up-to-date. The recommended actions displayed in the remediation side panel
+depend on how much information Docker Scout has about your image. The more
+information that's available, the better the recommendations.
+
+The following scenarios outline the different recommendations depending on the
+information available about the image.
+
+### No provenance attestations
+
+For Docker Scout to be able to evaluate this policy, you must add [provenance
+attestations](../../build/attestations/slsa-provenance.md) to your image. If
+your image doesn't have provenance attestations, compliance is undeterminable.
+
+<!--
+  TODO(dvdksn): no support for the following, yet
+
+  When provenance attestations are unavailable, Docker Scout provides generic,
+  best-effort recommendations in the remediation side panel. These
+  recommendations estimate your base using information from image analysis
+  results. The base image version is unknown, but you can manually select the
+  version you use in the remediation side panel. This lets Docker Scout evaluate
+  whether the base image detected in the image analysis is up-to-date with the
+  version you selected.
+
+  https://github.com/docker/docs/pull/18961#discussion_r1447186845
+-->
+
+### Provenance attestations available
+
+With provenance attestations added, Docker Scout can correctly detect the base
+image version that you're using. The version found in the attestations is
+cross-referenced against the current version of the corresponding tag to
+determine if it's up-to-date.
+
+If there's a policy violation, the recommended actions show how to update your
+base image version to the latest version, while also pinning the base image
+version to a specific digest. For more information, see [Pin base image
+versions](../../develop/develop-images/guidelines.md#pin-base-image-versions).
+
+### GitHub integration enabled
+
+If you're hosting the source code for your image on GitHub, you can enable the
+[GitHub integration](../integrations/source-code-management/github.md). This
+integration enables Docker Scout to provide even more useful remediation
+advice, and lets you initiate remediation for violations directly from the
+Docker Scout Dashboard.
+
+With the GitHub integration enabled, you can use the remediation side panel to
+raise a pull request on the GitHub repository of the image. The pull request
+automatically updates the base image version in your Dockerfile to the
+up-to-date version.
+
+This automated remediation pins your base image to a specific digest, while
+helping you stay up-to-date as new versions become available. Pinning the base
+image to a digest is important for reproducibility, and helps avoid unwanted
+changes from making their way into your supply chain.
+
+For more information about base image pinning, see [Pin base image
+versions](../../develop/develop-images/guidelines.md#pin-base-image-versions).
+
+<!--
+  TODO(dvdksn): no support for the following, yet
+
+  Enabling the GitHub integration also allows Docker Scout to visualize the
+  remediation workflow in the Docker Scout Dashboard. Each step, from the pull
+  request being raised to the image being deployed to an environment, is
+  displayed in the remediation sidebar when inspecting the image.
+
+  https://github.com/docker/docs/pull/18961#discussion_r1447189475
+-->
+
+## Supply chain attestations remediation
+
+The **Supply chain attestations** policy requires full provenance and SBOM
+attestations on images. If your image is missing an attestation, or if an
+attestation doesn't contain enough information, the policy is violated.
+
+The recommendations available in the remediation side panel helps guide you to
+what action you need to take to address the issues. For example, if your image
+has a provenance attestation, but the attestation doesn't contain enough
+information, you're recommended to re-build your image with
+[`mode=max`](../../build/attestations/slsa-provenance.md#max) provenance.

data/redirects.yml

@@ -586,6 +586,8 @@
   - /go/scout-policy/
 "/scout/policy/configure/":
   - /go/scout-configure-policy/
+"/develop/develop-images/guidelines/#pin-base-image-versions":
+  - /go/base-image-pinning/
 # integrations
 "/scout/integrations/ci/gha/":
   - "/go/scout-gha/"
@@ -609,6 +611,8 @@
   - "/go/scout-acr/"
 "/scout/integrations/code-quality/sonarqube/":
   - "/go/scout-sq/"
+"/scout/integrations/source-code-management/github/":
+  - "/go/scout-github/"
 
 # Build links
 "/desktop/use-desktop/builds/":
@@ -631,6 +635,10 @@
   - /build/customize/bake/file-definition/
 "/build/ci/github-actions/attestations/":
   - /go/build-attestations-gha/
+"/build/attestations/":
+  - /go/attestations/
+"/build/attestations/slsa-provenance/":
+  - /go/provenance/
 
 # CLI backlinks
 "/config/filter/":

data/toc.yaml

@@ -1378,6 +1378,8 @@ Manuals:
         title: Configure policies
       - path: /scout/policy/ci/
         title: Policy Evaluation in CI
+      - path: /scout/policy/remediation/
+        title: Remediation
     - sectiontitle: Integrations
       section:
       - title: Overview
@@ -1414,6 +1416,10 @@ Manuals:
         section:
         - title: SonarQube
           path: /scout/integrations/code-quality/sonarqube/
+      - sectiontitle: Source code management
+        section:
+        - title: GitHub
+          path: /scout/integrations/source-code-management/github/
     - path: /scout/release-notes/
       title: Release notes