diff --git a/content/scout/policy/_index.md b/content/scout/policy/_index.md index 40287558bd..e3b63c31b2 100644 --- a/content/scout/policy/_index.md +++ b/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 diff --git a/content/scout/scores.md b/content/scout/scores.md new file mode 100644 index 0000000000..d79f493094 --- /dev/null +++ b/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. diff --git a/data/redirects.yml b/data/redirects.yml index cbaeb8b40a..a43a48ab02 100644 --- a/data/redirects.yml +++ b/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/":