diff --git a/content/scout/policy/_index.md b/content/scout/policy/_index.md index 0afe00423b..bddba15c62 100644 --- a/content/scout/policy/_index.md +++ b/content/scout/policy/_index.md @@ -22,7 +22,7 @@ perform, relative to your rules and thresholds, over time. Learn how you can use Policy Evaluation to ensure that your artifacts align with established best practices. -## How it works +## How Policy Evaluation works When you activate Docker Scout for a repository, images that you push are [automatically analyzed](../image-analysis.md). The analysis gives you insights @@ -33,7 +33,7 @@ defined by policies. A policy defines one or more criteria that your artifacts should fulfill. For example, one of the default policies in Docker Scout is the **Critical -vulnerabilities** policy, which proclaims that your artifacts must not contain +vulnerabilities** policy, which requires that your artifacts must not contain any critical vulnerabilities. If an artifact contains one or more vulnerabilities with a critical severity, that artifact fails the evaluation. @@ -47,8 +47,8 @@ policy. Policies don't necessarily have to be related to application security and vulnerabilities. You can use policies to measure and track other aspects of -supply chain management as well, such as base image dependencies and -open-source licenses. +supply chain management as well, such as open-source license usage and base +image up-to-dateness. ## Default policies @@ -61,47 +61,62 @@ Docker Scout ships the following out-of-the-box policies: - [High-profile vulnerabilities](#high-profile-vulnerabilities) - [Supply chain attestations](#supply-chain-attestations) -These policies are turned on by default for Scout-enabled repositories. There's -currently no way to turn off or configure these policies. +Policies are enabled by default for Scout-enabled repositories. If you want to +customize the criteria of a policy, you can create custom policies based on the +default, out-of-the-box policies. You can also disable a policy altogether if +it isn't relevant to you. For more information, see [Configure +policies](./configure.md). ### Fixable critical and high vulnerabilities -This policy requires that your artifacts aren't exposed to known -vulnerabilities with a critical or high severity, and where there's a fix -version available. Essentially, this means that there's an easy fix that you -can deploy for images that fail this policy: upgrade the vulnerable package to -a version containing a fix for the vulnerability. +The **Fixable critical and high vulnerabilities** policy requires that your +artifacts aren't exposed to known vulnerabilities where there's a fix version +available. Essentially, this means that there's an easy fix that you can deploy +for images that fail this policy: upgrade the vulnerable package to a version +containing a fix for the vulnerability. -This policy only flags vulnerabilities that were published more than 30 -days ago, with the rationale that newly discovered vulnerabilities -shouldn't cause your evaluations to fail until you've had a chance to -address them. +This policy only flags critical and high severity vulnerabilities that were +published more than 30 days ago. The rationale for only flagging +vulnerabilities of a certain age is that newly discovered vulnerabilities +shouldn't cause your evaluations to fail until you've had a chance to address +them. This policy is unfulfilled if an artifact is affected by one or more critical- or high-severity vulnerability, where a fix version is available. +You can configure the severity level and age thresholds by creating a custom +policy. For more information, see [Configure policies](./configure.md). + ### Critical vulnerabilities -This policy requires that your artifacts contain no known critical -vulnerabilities. The policy is unfulfilled if your artifact contains one or -more critical vulnerabilities. +The **Critical vulnerabilities** policy requires that your artifacts contain no +known critical vulnerabilities. The policy is unfulfilled if your artifact +contains one or more critical vulnerabilities. This policy flags all critical vulnerabilities, whether or not there's a fix -version available. +version available, and regardless of how long it's been since the vulnerability +was first disclosed. + +You can configure the severity level by creating a custom policy, see +[Configure policies](./configure.md). ### Copyleft licenses -This policy requires that your artifacts don't contain packages distributed -under an AGPLv3 or GPLv3 license. These licenses are protective -[copyleft](https://en.wikipedia.org/wiki/Copyleft), and may be unsuitable for -use in your software because of the restrictions they enforce. +The **Copyleft licenses** policy requires that your artifacts don't contain +packages distributed under an AGPLv3 or GPLv3 license. These licenses are +protective [copyleft](https://en.wikipedia.org/wiki/Copyleft), and may be +unsuitable for use in your software because of the restrictions they enforce. This policy is unfulfilled if your artifacts contain one or more packages with a violating license. +You can configure the list of licenses by creating a custom policy, see +[Configure policies](./configure.md). + ### Outdated base images -This policy requires that the base images you use are up-to-date. +The **Outdated base images** policy requires that the base images you use are +up-to-date. It's unfulfilled when the tag you used to build your image points to a different digest than what you're using. If there's a mismatch in digests, that @@ -126,9 +141,10 @@ image version. ### High-profile vulnerabilities -This policy requires that your artifacts don't contain vulnerabilities from -Docker Scout’s curated list. This list is kept up-to-date with newly disclosed -vulnerabilities that are widely recognized to be risky. +The **High-profile vulnerabilities** policy requires that your artifacts don't +contain vulnerabilities from Docker Scout’s curated list. This list is kept +up-to-date with newly disclosed vulnerabilities that are widely recognized to +be risky. The list includes the following vulnerabilities: @@ -137,9 +153,12 @@ The list includes the following vulnerabilities: - [CVE-2023-38545 (cURL SOCKS5 heap buffer overflow)](https://scout.docker.com/v/CVE-2023-38545) - [CVE-2023-44487 (HTTP/2 Rapid Reset)](https://scout.docker.com/v/CVE-2023-44487) +You can configure the CVEs included in this list by creating a custom policy. +For more information, see [Configure policies](./configure.md). + ### Supply chain attestations -The Supply chain attestations policy requires that your artifacts have +The **Supply chain attestations** policy requires that your artifacts have [SBOM](../../build/attestations/sbom.md) and [provenance](../../build/attestations/slsa-provenance.md) attestations. diff --git a/content/scout/policy/configure.md b/content/scout/policy/configure.md new file mode 100644 index 0000000000..b98e4f10b8 --- /dev/null +++ b/content/scout/policy/configure.md @@ -0,0 +1,65 @@ +--- +title: Configure policies +description: Learn how to configure or disable the default policies in Docker Scout +keywords: scout, policy, configure, disable, enable, parametrize, thresholds +--- + +Some of the existing policies are configurable. This means that you can clone +an existing policy and create new, custom policies with your own configuration. +You can also disable a policy altogether, if a policy doesn't quite match your +needs. + +## Configure a policy + +To change the configuration of a policy, you must clone one of the existing +default policies, and then save your configuration as a new policy. You can +edit the display name and description of the new policy to help distinguish +it from the default policy it's based on. + +The available configuration parameters for a policy depends on the default +policy you used as a base for your custom policy. The following table lists the +default policies that you can configure, and the available configuration +parameters that you can use to create a custom policy. + +| Default policy | Configuration parameters | +| ----------------------------------------- | ------------------------ | +| All critical vulnerabilities | Severities | +| Copyleft licenses | License names | +| Fixable critical and high vulnerabilities | Severities, age | +| High-profile vulnerabilities | CVEs | + +To configure a policy: + +1. Go to the [Docker Scout Dashboard](https://scout.docker.com/). +2. Go to the **Policies** section. +3. Select the policy you want to configure. +4. Select the **View configuration** button to open the policy configuration. + + If the button is disabled, the selected policy doesn't have any + configuration parameters. + +5. Select the **Edit policy** button. This prompts you to create a clone of the + default policy. +6. Select **Copy and edit policy** to create a clone of the default policy. +7. Update the policy parameters. +8. Save the changes: + + - Select **Save and enable** to commit the changes and enable the policy for + your current organization. + - Select **Save changes** to save the policy configuration without enabling + it. + +## Disable a policy + +When you disable a policy, evaluation results for that policy are hidden, and +no longer appear in the Docker Scout Dashboard or in the CLI. Historic +evaluation results aren't deleted if you disable a policy, so if you change +your mind and re-enable a policy later, results from earlier evaluations will +still be available. + +To disable a policy: + +1. Go to the [Docker Scout Dashboard](https://scout.docker.com/). +2. Go to the **Policies** section. +3. Select the policy you want to disable. +4. Select **Disable policy**. diff --git a/data/redirects.yml b/data/redirects.yml index df25174931..42d3993a1a 100644 --- a/data/redirects.yml +++ b/data/redirects.yml @@ -584,6 +584,8 @@ - /go/scout-ci/ "/scout/policy/": - /go/scout-policy/ +"/scout/policy/configure/": + - /go/scout-configure-policy/ # integrations "/scout/integrations/ci/gha/": - "/go/scout-gha/" diff --git a/data/toc.yaml b/data/toc.yaml index 110f00ea45..aba9352d78 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1380,6 +1380,8 @@ Manuals: title: Overview - path: /scout/policy/view/ title: View policy status + - path: /scout/policy/configure/ + title: Configure policies - path: /scout/policy/ci/ title: Policy Evaluation in CI - sectiontitle: Integrations