Merge pull request #18697 from dvdksn/scout-configurable-policy

scout: configurable policies m1

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.
 

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**.

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/"

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