scout: configurable policies m1

Signed-off-by: David Karlsson <[email protected]>

content/scout/policy/_index.md

@@ -11,7 +11,7 @@ description: |
 >
 > Policy Evaluation is an [Early Access](/release-lifecycle/#early-access-ea)
 > feature of Docker Scout.
-> { .restricted }
+{ .restricted }
 
 In software supply chain management, maintaining the security and reliability
 of artifacts is a top priority. Policy Evaluation in Docker Scout introduces a
@@ -61,26 +61,32 @@ 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 enabled 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
 
 The **Fixable critical and high vulnerabilities** 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.
+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, see [Configure policies](./configure.md).
+
 ### Critical vulnerabilities
 
 The **Critical vulnerabilities** policy requires that your artifacts contain no
@@ -91,6 +97,9 @@ This policy flags all critical vulnerabilities, whether or not there's a fix
 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
 
 The **Copyleft licenses** policy requires that your artifacts don't contain
@@ -101,6 +110,9 @@ 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
 
 The **Outdated base images** policy requires that the base images you use are
@@ -141,6 +153,9 @@ 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,
+see [Configure policies](./configure.md).
+
 ### Supply chain attestations
 
 The **Supply chain attestations** policy requires that your artifacts have

content/scout/policy/configure.md

@@ -0,0 +1,62 @@
+---
+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 use as a base, and the parameters that you can
+use to create a customized version of a 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 configure button to view the policy configuration: <span
+   class="material-symbols-rounded">tune</span>
+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 appears 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/toc.yaml

@@ -1356,6 +1356,8 @@ Manuals:
         title: Overview
       - path: /scout/policy/view/
         title: View policy status
+      - path: /scout/policy/configure/
+        title: Configure policies
     - sectiontitle: Integrations
       section:
       - title: Overview