Merge pull request #20093 from dvdksn/scout-health-scores

scout: health scores

content/scout/policy/_index.md

@@ -59,9 +59,7 @@ Docker Scout ships the following out-of-the-box policies:
 - [Outdated base images](#outdated-base-images)
 - [High-profile vulnerabilities](#high-profile-vulnerabilities)
 - [Supply chain attestations](#supply-chain-attestations)
-- [Quality gates passed](#quality-gates-passed)
 - [Default non-root user](#default-non-root-user)
-- [Unapproved base images](#unapproved-base-images)
 
 To give you a head start, Scout enables several policies by default for your
 Scout-enabled repositories. You can customize the default configurations to
@@ -69,6 +67,9 @@ reflect internal requirements and standards. You can also disable a policy
 altogether if it isn't relevant to you. For more information, see [Configure
 policies](./configure.md).
 
+There's also a set of [additional policies](#additional-policies) that can be
+optionally enabled for repositories.
+
 ### Fixable critical and high vulnerabilities
 
 The **Fixable critical and high vulnerabilities** policy requires that your
@@ -158,38 +159,6 @@ For more information about
 building with attestations, see
 [Attestations](../../build/attestations/_index.md).
 
-### Quality gates passed
-
-The Quality gates passed policy builds on the [SonarQube
-integration](../integrations/code-quality/sonarqube.md) to assess the quality
-of your source code. This policy works by ingesting the SonarQube code analysis
-results into Docker Scout.
-
-You define the criteria for this policy using SonarQube's [quality
-gates](https://docs.sonarsource.com/sonarqube/latest/user-guide/quality-gates/).
-SonarQube evaluates your source code against the quality gates you've defined
-in SonarQube. Docker Scout surfaces the SonarQube assessment as a Docker Scout
-policy.
-
-Docker Scout uses [provenance](../../build/attestations/slsa-provenance.md)
-attestations or the `org.opencontainers.image.revision` OCI annotation to link
-SonarQube analysis results with container images. In addition to enabling the
-SonarQube integration, you must also make sure that your images has either the
-attestation or the label.
-
-![Git commit SHA links image with SonarQube analysis](../images/scout-sq-commit-sha.webp)
-
-Once you push an image and policy evaluation completes, the results from the
-SonarQube quality gates display as a policy in the Docker Scout Dashboard, and
-in the CLI.
-
-> **Note**
->
-> Docker Scout can only access SonarQube analyses created after the integration
-> is enabled. Docker Scout doesn't have access to historic evaluations. Trigger
-> a SonarQube analysis and policy evaluation after enabling the integration to
-> view the results in Docker Scout.
-
 ### Default non-root user
 
 By default, containers run as the `root` superuser with full system
@@ -209,6 +178,7 @@ policy violations caused by images where the `root` user is implicit, and
 images where `root` is set on purpose.
 
 The following Dockerfile runs as `root` by default despite not being explicitly set:
+
 ```Dockerfile
 FROM alpine
 RUN echo "Hi"
@@ -266,6 +236,16 @@ ENTRYPOINT ["/app/production"]
 {{< /tab >}}
 {{< /tabs >}}
 
+## Additional policies
+
+In addition to the [out-of-the-box policies](#out-of-the-box-policies) enabled
+by default, Docker Scout supports the following optional policies. Before you
+can enable these policies, you need to either configure the policies, or
+configure the integration that the policy requires.
+
+- [Unapproved base images](#unapproved-base-images)
+- [Quality gates passed](#quality-gates-passed)
+
 ### Unapproved base images
 
 The **Unapproved base images** policy lets you restrict which base
@@ -317,6 +297,38 @@ This policy isn't enabled by default. To enable the policy:
 Your images need provenance attestations for this policy to successfully
 evaluate. For more information, see [No base image data](#no-base-image-data).
 
+### Quality gates passed
+
+The Quality gates passed policy builds on the [SonarQube
+integration](../integrations/code-quality/sonarqube.md) to assess the quality
+of your source code. This policy works by ingesting the SonarQube code analysis
+results into Docker Scout.
+
+You define the criteria for this policy using SonarQube's [quality
+gates](https://docs.sonarsource.com/sonarqube/latest/user-guide/quality-gates/).
+SonarQube evaluates your source code against the quality gates you've defined
+in SonarQube. Docker Scout surfaces the SonarQube assessment as a Docker Scout
+policy.
+
+Docker Scout uses [provenance](../../build/attestations/slsa-provenance.md)
+attestations or the `org.opencontainers.image.revision` OCI annotation to link
+SonarQube analysis results with container images. In addition to enabling the
+SonarQube integration, you must also make sure that your images have either the
+attestation or the label.
+
+![Git commit SHA links image with SonarQube analysis](../images/scout-sq-commit-sha.webp)
+
+Once you push an image and policy evaluation completes, the results from the
+SonarQube quality gates display as a policy in the Docker Scout Dashboard, and
+in the CLI.
+
+> **Note**
+>
+> Docker Scout can only access SonarQube analyses created after the integration
+> is enabled. Docker Scout doesn't have access to historic evaluations. Trigger
+> a SonarQube analysis and policy evaluation after enabling the integration to
+> view the results in Docker Scout.
+
 ## No base image data
 
 There are cases when it's not possible to determine information about the base

content/scout/scores.md

@@ -0,0 +1,117 @@
+---
+title: Docker Scout health scores
+description: |
+  Docker Scout health scores provide a supply chain assessment for Docker Hub
+  images, grading them from A to F based on various security policies.
+keywords: scout, health scores, evaluation, checks, grades, docker hub
+sitemap: false
+---
+
+> **Early Access**
+>
+> Health scores is an [Early Access](/release-lifecycle/#early-access-ea)
+> feature of Docker Scout. The feature is only available to organizations
+> participating in the early access program for this feature.
+{ .restricted }
+
+Docker Scout health scores provide a security assessment, and overall supply
+chain health, of images on Docker Hub, helping you determine whether an image
+meets established security best practices. The scores range from A to F, where
+A represents the highest level of security and F the lowest, offering an
+at-a-glance view of the security posture of your images.
+
+Only users who are members of the organization that owns the repository, and
+have at least “read” access to the repository, can view the health score. The
+score is not visible to users outside the organization or members without
+"read" access.
+
+## Scoring system
+
+Health scores are determined by evaluating images against a set of Docker Scout
+[policies](./policy/_index.md). These policies align with best practices for
+the software supply chain and are recommended by Docker as foundational
+standards for images.
+
+Each policy is assigned a points value. If the image is compliant with a
+policy, it is awarded the points value for that policy. The health score of an
+image is calculated based on the percentage of points achieved relative to the
+total possible points.
+
+### Scoring process
+
+1. Policy compliance is evaluated for the image.
+2. Points are awarded based on adherence to these policies.
+3. The points achieved percentage is calculated:
+
+   ```text
+   Percentage = (Points / Total) * 100
+   ```
+
+4. The final score is assigned based on the percentage of points achieved, as
+   shown in the following table:
+
+   | Points percentage (awarded out of total) | Score |
+   | ---------------------------------------- | ----- |
+   | More than 90%                            | A     |
+   | 71% to 90%                               | B     |
+   | 51% to 70%                               | C     |
+   | 31% to 50%                               | D     |
+   | 11% to 30%                               | E     |
+   | Less than 10%                            | F     |
+
+### Policy weights
+
+The policies that influence the score, and their respective weights, are as follows:
+
+| Policy                                                                                                    | Points |
+| --------------------------------------------------------------------------------------------------------- | ------ |
+| [Fixable Critical and High Vulnerabilities](./policy/_index.md#fixable-critical-and-high-vulnerabilities) | 20     |
+| [High-Profile Vulnerabilities](./policy/_index.md#high-profile-vulnerabilities)                           | 20     |
+| [Supply Chain Attestations](./policy/_index.md#supply-chain-attestations)                                 | 15     |
+| [Unapproved Base Images](./policy/_index.md#unapproved-base-images)                                       | 15     |
+| [Outdated Base Images](./policy/_index.md#outdated-base-images)                                           | 10     |
+| [Default Non-Root User](./policy/_index.md#default-non-root-user)                                         | 5      |
+| [Copyleft Licenses](./policy/_index.md#copyleft-licenses)                                                 | 5      |
+
+### Evaluation
+
+Health scores are calculated for new images pushed to Docker Hub after the
+feature is enabled. The health scores help you maintain high security standards
+and ensure your applications are built on secure and reliable images.
+
+### Repository scores
+
+In addition to individual image scores (per tag or digest), each repository
+receives a health score based on the latest pushed tag, providing an overall
+view of the repository's security status.
+
+### Example
+
+For an image with a total possible score of 90 points:
+
+- If the image only deviates from one policy (for example, the Copyleft
+  Licenses policy), it might score 85 out of 90, resulting in a score of A.
+- If the image has fixable CVEs and other issues, it might score 75 out of 90,
+  resulting in a score of B.
+
+## Improving your health score
+
+To improve the health score of an image, take steps to ensure that the image is
+compliant with the Docker Scout recommended [policies](./policy/_index.md).
+
+1. Go to the [Docker Scout Dashboard](https://scout.docker.com/).
+2. Sign in using your Docker ID.
+3. Go to [Repository settings](https://scout.docker.com/settings/repos) and
+   enable Docker Scout for your Docker Hub image repositories.
+4. Analyze the [policy compliance](./policy/_index.md) for your repositories,
+   and take actions to ensure your images are policy-compliant.
+
+Since policies are weighted differently, prioritize the policies with the
+highest scores for a greater impact on your image's overall score.
+
+## Known limitations
+
+Health score can currently only be evaluated for:
+
+- Images with a `linux/amd64` or `linux/arm64` architecture.
+- Images up to 4GB in compressed size.

data/redirects.yml

@@ -652,6 +652,8 @@
   - /go/scout-notifications/
 "/scout/integrations/team-collaboration/slack/":
   - "/go/scout-slack/"
+"/scout/scores/":
+  - /go/scout-scores/
 
 # Build links (internal)
 "/build/bake/reference/":