Merge pull request #18180 from dvdksn/scout-policy-base-image

scout: restructure policy

content/scout/policy/_index.md

@@ -29,7 +29,7 @@ with established best practices.
 ## How it works
 
 When you activate Docker Scout for a repository, images that you push are
-[automatically analyzed](./image-analysis.md). The analysis gives you insights
+[automatically analyzed](../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
@@ -97,69 +97,3 @@ 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.

content/scout/policy/view.md

@@ -0,0 +1,113 @@
+---
+title: View Docker Scout policy status
+description: |
+  The Docker Scout Dashboard and the `docker scout policy` command lets you
+  view policy status of images.
+keywords: scout, policy, status, vulnerabilities, supply chain, cves, licenses
+---
+
+> **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 }
+
+You can track policy status for your artifacts from the [Docker Scout
+Dashboard](#dashboard), or using the [CLI](#cli).
+
+## Dashboard
+
+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 results and remediation
+
+To view the full evaluation results for an image, navigate to the image tag 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)
+
+This view also provides recommendations on how to improve improve policy status
+for violated policies.
+
+![Policy details in the tag view](../images/policy-tag-view.webp)
+
+For vulnerability-related policies, the policy details view displays the fix
+version that removes the vulnerability, when a fix version is available. To fix
+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.
+
+## CLI
+
+To view policy status for an image from the CLI, use the `docker scout policy`
+command.
+
+```console
+$ docker scout policy \
+  --org dockerscoutpolicy \
+  --platform linux/amd64 \
+  dockerscoutpolicy/email-api-service:0.0.2
+
+Image reference: dockerscoutpolicy/email-api-service:0.0.2
+Digest: sha256:17b1fde0329c71af302b6391fc73a08f56cb8c33e7eea7a33b61a24cedbf2b69
+Platform: linux/amd64
+
+## Overview
+
+Policy status:  FAILED  (1/3 policies violated)
+
+                      Policy                     │      Results       
+─────────────────────────────────────────────────┼────────────────────
+  ✓ Critical and high vulnerabilities with fixes │ 0 vulnerabilities  
+  ✗ Critical vulnerabilities                     │    1C              
+  ✓ Packages with GPL3+ licenses                 │ 0 packages         
+
+
+## "Critical vulnerabilities" policy evaluation results
+
+  Vulnerability  │  Severity  │                     Current package version                     │ Fix version  
+─────────────────┼────────────┼─────────────────────────────────────────────────────────────────┼──────────────
+  CVE-2022-48174 │  CRITICAL  │ pkg:apk/alpine/busybox@1.36.1-r0?os_name=alpine&os_version=3.18 │ 1.36.1-r1
+```
+
+For more information about the command, refer to the [CLI
+reference](../../engine/reference/commandline/scout_policy.md).

data/toc.yaml

@@ -1970,10 +1970,14 @@ Manuals:
       title: Advisory database
     - path: /scout/data-handling/
       title: Data handling
-    - path: /scout/policy/
-      title: Policy
     - path: /scout/sbom/
       title: SBOM
+    - sectiontitle: Policy
+      section:
+      - path: /scout/policy/
+        title: Overview
+      - path: /scout/policy/view/
+        title: View policy status
     - sectiontitle: Integrations
       section:
       - title: Overview