diff --git a/content/scout/images/policy-detailed-results.webp b/content/scout/images/policy-detailed-results.webp new file mode 100644 index 0000000000..c74365a73a Binary files /dev/null and b/content/scout/images/policy-detailed-results.webp differ diff --git a/content/scout/images/policy-image-list.webp b/content/scout/images/policy-image-list.webp new file mode 100644 index 0000000000..fd9d512d21 Binary files /dev/null and b/content/scout/images/policy-image-list.webp differ diff --git a/content/scout/images/policy-overview.webp b/content/scout/images/policy-overview.webp new file mode 100644 index 0000000000..5ea82e2e05 Binary files /dev/null and b/content/scout/images/policy-overview.webp differ diff --git a/content/scout/policy.md b/content/scout/policy.md new file mode 100644 index 0000000000..700f840f64 --- /dev/null +++ b/content/scout/policy.md @@ -0,0 +1,165 @@ +--- +title: Get started with Policy Evaluation in Docker Scout +keywords: scout, supply chain, vulnerabilities, packages, cves, policy +description: | + Policies in Docker Scout let you define supply chain rules and thresholds + for your artifacts, and track how your artifacts perform against those + requirements over time +--- + +> **Beta** +> +> Policy Evaluation is a [Beta](/release-lifecycle/#beta) feature of Docker +> Scout. This feature is available to organizations participating in the +> limited preview program for policies. +> +> If you're interested in trying out this feature, reach out using the form on +> the [Docker Scout product page](https://docker.com/products/docker-scout) +{ .restricted } + +In software supply chain management, maintaining the security and reliability +of artifacts is a top priority. Policy Evaluation in Docker Scout introduces a +layer of control, on top of existing analysis capabilities. It lets you define +supply chain rules for your artifacts, and helps you track how your artifacts +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 + +When you activate Docker Scout for a repository, images that you push are +[automatically analyzed](../advanced-image-analysis.md). The analysis gives you +insights about the composition of your images, including what packages they +contain, and what vulnerabilities they're exposed to. Policy Evaluation builds +on top of the image analysis feature, interpreting the analysis results against +the rules 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 +any critical vulnerabilities. If an artifact contains one or more +vulnerabilities with a critical severity, that artifact fails the evaluation. + +In Docker Scout, policies are designed to help you ratchet forward your +security and supply chain stature. Where other tools focus on providing a pass +or fail status, Docker Scout policies visualizes how small, incremental changes +affect policy status, even when your artifacts don't meet the policy +requirements (yet). By tracking how the fail gap changes over time, you more +easily see whether your artifact is improving or deteriorating relative to +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. + +## Default policies + +Docker Scout ships the following three out-of-the-box policies: + +- [Critical and high vulnerabilities with fixes](#critical-and-high-vulnerabilities-with-fixes) +- [Critical vulnerabilities](#critical-vulnerabilities) +- [Packages with GPL3+ licenses](#packages-with-gpl3-licenses) + +These policies are turned on by default for Scout-enabled repositories. There's +currently no way to turn off or configure these policies. + +### Critical and high vulnerabilities with fixes + +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. + +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 is unfulfilled if an artifact is affected by one or more critical- +or high-severity vulnerability, where a fix version is available. + +### 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. + +This policy flags all critical vulnerabilities, whether or not there's a fix +version available. + +### Packages with GPL3+ licenses + +This policy requires that your artifacts don't contain packages distributed +under a GPL3+ [copyleft](https://en.wikipedia.org/wiki/Copyleft) license. + +This policy is unfulfilled if your artifacts contain one or more packages with +a violating license. + +## View policy status + +The **Overview** tab of the [Docker Scout Dashboard](https://scout.docker.com/) +displays a summary of recent changes in policy for your repositories. +This summary shows images that have seen the most change in their policy +evaluation between the most recent image and the previous image. + +![Policy overview](./images/policy-overview.webp) + +### Policy status per repository + +The **Images** tab shows the current policy status, and recent policy trend, +for all images in the selected environment. The **Policy status** column in the +list shows: + +- Number of fulfilled policies versus the total number of policies +- Recent policy trends + +![Policy status in the image list](./images/policy-image-list.webp) + +The policy trend, denoted by the directional arrows, indicates whether an image +is better, worse, or unchanged in terms of policy, compared to the previous +image in the same environment. + +- The green arrow pointing upwards shows the number of policies that got better + in the latest pushed image. +- The red arrow pointing downwards shows the number of policies that got worse + in the latest pushed image. +- The bidirectional gray arrow shows the number of policies that were unchanged + in the latest version of this image. + +If you select a repository, you can open the **Policy** tab for a detailed +description of the policy delta for the most recently analyzed image and its +predecessor. + +### Detailed evaluation results + +To view the full results of an evaluation of an image, select the image in +the Docker Scout Dashboard and open the **Policy** tab. This shows a +breakdown for all policy violations for the current image. + +![Detailed Policy Evaluation results](./images/policy-detailed-results.webp) + +## Remediate policy violations + +To remediate issues in your artifacts that cause policy violations, you can use +the tag view in the Docker Scout Dashboard. + +1. Go to the **Images** view in the Docker Scout Dashboard. +2. In the list of repositories, select the image that you want to improve. +3. Select an image. +4. Open the **Policy** tab. + +The **Policy** tab shows you all of the policy violations for the current +image. Expand the policy menus to learn which packages in the image are +causing the evaluation to fail. + +For vulnerability-related policies, if a package has an available fix version +that removes the vulnerability, that fix version is displayed in the policy +list. To remediate the issue, upgrade the package version to the fix version. + +For licensing-related policies, the list shows all packages whose license +doesn't meet the policy criteria. To fix the issue, look for an alternative +package distributed under a more appropriate license, or cut the dependency by +reimplementing the functionality in your own code. diff --git a/data/toc.yaml b/data/toc.yaml index 6585a3831f..7de8a00890 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1909,6 +1909,8 @@ Manuals: title: Advisory Database - path: /scout/data-handling/ title: Data handling + - path: /scout/policy/ + title: Policy - sectiontitle: Integrations section: - title: Overview