From b21e0573af6f2c156f383e95664f3962400edea9 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 12 Jun 2024 15:28:29 +0200 Subject: [PATCH 1/3] hugo: add support for absolute markdown links Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- layouts/_default/_markup/render-link.html | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/layouts/_default/_markup/render-link.html b/layouts/_default/_markup/render-link.html index c242f1e2a5..e228664356 100644 --- a/layouts/_default/_markup/render-link.html +++ b/layouts/_default/_markup/render-link.html @@ -11,7 +11,10 @@ {{- partialCached "icon" "open_in_new" "open_in_new" -}} {{- else if (strings.HasPrefix $url "/") -}} - {{/* absolute link, use url as-is */}} + {{ if (strings.HasSuffix (urls.Parse $url).Path ".md") }} + {{/* abs path to markdown file, use ref */}} + {{ $url = (ref .Page $url) }} + {{ end }} {{ .Text | safeHTML }} {{- else -}} {{/* check if the file links to index.md */}} From 4a7abd11be6eb8cc343b955d5b2613393e539ade Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 12 Jun 2024 16:06:03 +0200 Subject: [PATCH 2/3] scout: restructure manuals section Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/build/attestations/sbom.md | 2 +- content/desktop/use-desktop/images.md | 6 +-- content/docker-hub/vulnerability-scanning.md | 2 +- .../{ => deep-dive}/advisory-db-sources.md | 4 +- .../scout/{ => deep-dive}/data-handling.md | 6 ++- .../analysis.md} | 21 +++++----- content/scout/{ => explore}/dashboard.md | 23 +++++------ .../scout/{ => explore}/image-details-view.md | 8 ++-- .../scout/{ => explore}/metrics-exporter.md | 16 ++++---- .../artifact-types.md} | 10 +++-- .../{env-vars.md => how-tos/configure-cli.md} | 4 +- .../{sbom.md => how-tos/view-create-sboms.md} | 9 +++-- content/scout/integrations/ci/jenkins.md | 2 +- .../scout/integrations/environment/_index.md | 6 +-- content/scout/integrations/registry/ecr.md | 2 +- .../integrations/team-collaboration/slack.md | 2 +- content/scout/policy/_index.md | 2 +- content/scout/quickstart.md | 2 +- content/scout/release-notes/platform.md | 2 +- content/security/faqs/general.md | 2 +- data/redirects.yml | 10 ++--- data/toc.yaml | 38 ++++++++++--------- 22 files changed, 98 insertions(+), 81 deletions(-) rename content/scout/{ => deep-dive}/advisory-db-sources.md (97%) rename content/scout/{ => deep-dive}/data-handling.md (95%) rename content/scout/{image-analysis.md => explore/analysis.md} (93%) rename content/scout/{ => explore}/dashboard.md (89%) rename content/scout/{ => explore}/image-details-view.md (95%) rename content/scout/{ => explore}/metrics-exporter.md (95%) rename content/scout/{image-prefix.md => how-tos/artifact-types.md} (96%) rename content/scout/{env-vars.md => how-tos/configure-cli.md} (97%) rename content/scout/{sbom.md => how-tos/view-create-sboms.md} (91%) diff --git a/content/build/attestations/sbom.md b/content/build/attestations/sbom.md index 30bc4ca7d9..cf8889702c 100644 --- a/content/build/attestations/sbom.md +++ b/content/build/attestations/sbom.md @@ -226,7 +226,7 @@ $ docker buildx build --attest type=sbom,generator= . > **Tip** > > The Docker Scout SBOM generator is available. See -> [Docker Scout SBOMs](../../scout/sbom.md#attest). +> [Docker Scout SBOMs](/scout/how-tos/view-create-sboms.md). { .tip } ## SBOM attestation example diff --git a/content/desktop/use-desktop/images.md b/content/desktop/use-desktop/images.md index be4dc1a5f0..75767e72a4 100644 --- a/content/desktop/use-desktop/images.md +++ b/content/desktop/use-desktop/images.md @@ -52,8 +52,8 @@ To inspect an image, select the image row. Inspecting an image displays detailed - Vulnerabilities found - Packages inside the image -[Docker Scout](../../scout/index.md) powers this vulnerability information. -For more information about this view, see [Image details view](../../scout/image-details-view.md) +[Docker Scout](/scout/_index.md) powers this vulnerability information. +For more information about this view, see [Image details view](/scout/explore/image-details-view.md) ## Pull the latest image from Docker Hub @@ -102,4 +102,4 @@ Hovering over an image tag reveals two options: ## Additional resources -- [What is an image?](../../guides/docker-concepts/the-basics/what-is-an-image.md) \ No newline at end of file +- [What is an image?](../../guides/docker-concepts/the-basics/what-is-an-image.md) diff --git a/content/docker-hub/vulnerability-scanning.md b/content/docker-hub/vulnerability-scanning.md index 77d5f14166..6f35e50a29 100644 --- a/content/docker-hub/vulnerability-scanning.md +++ b/content/docker-hub/vulnerability-scanning.md @@ -123,7 +123,7 @@ To view the vulnerability report: ![Vulnerability scan details](images/vuln-scan-details.png) For more information on this view, see -[Image details view](../scout/image-details-view.md). +[Image details view](/scout/explore/image-details-view.md). ### Inspect vulnerabilities diff --git a/content/scout/advisory-db-sources.md b/content/scout/deep-dive/advisory-db-sources.md similarity index 97% rename from content/scout/advisory-db-sources.md rename to content/scout/deep-dive/advisory-db-sources.md index 0c57a28557..7a96fd0ccb 100644 --- a/content/scout/advisory-db-sources.md +++ b/content/scout/deep-dive/advisory-db-sources.md @@ -3,6 +3,8 @@ description: More details on the advisory database and CVE-to-package matching s behind Docker Scout analysis. keywords: scout, scanning, analysis, vulnerabilities, Hub, supply chain, security, packages, repositories, ecosystem title: Advisory database sources and matching service +aliases: + /scout/advisory-db-sources/ --- Reliable information sources are key for Docker Scout's ability to @@ -53,7 +55,7 @@ The database stores the Software Bill of Materials (SBOM) and other metadata abo When a security advisory has new information about a vulnerability, your SBOM is cross-referenced with the CVE information to detect how it affects you. -For more details on how image analysis works, see the [image analysis page](./image-analysis.md). +For more details on how image analysis works, see the [image analysis page](/scout/explore/analysis.md). ## Vulnerability matching diff --git a/content/scout/data-handling.md b/content/scout/deep-dive/data-handling.md similarity index 95% rename from content/scout/data-handling.md rename to content/scout/deep-dive/data-handling.md index 1c9a9b92c5..0d34c7528e 100644 --- a/content/scout/data-handling.md +++ b/content/scout/deep-dive/data-handling.md @@ -5,6 +5,8 @@ keywords: | materials, config, ports, labels, os, registry, timestamp, digest, layers, architecture, license, dependencies, base image title: Data collection and storage in Docker Scout +aliases: + /scout/data-handling/ --- Docker Scout's image analysis works by collecting metadata from the container @@ -68,7 +70,7 @@ and packages, and application-level packages such as maven, npm, and so on. ### Environment metadata If you integrate Docker Scout with your runtime environment via the -[Sysdig integration](./integrations/environment/sysdig.md), +[Sysdig integration](/scout/integrations/environment/sysdig.md), Docker Scout collects the following data points about your deployments: - Kubernetes namespace @@ -83,7 +85,7 @@ Docker Scout platform; it's only used to run the analysis. ### Provenance -For images with [provenance attestations](../build/attestations/slsa-provenance.md), +For images with [provenance attestations](/build/attestations/slsa-provenance.md), Docker Scout stores the following data in addition to the SBOM: - Materials diff --git a/content/scout/image-analysis.md b/content/scout/explore/analysis.md similarity index 93% rename from content/scout/image-analysis.md rename to content/scout/explore/analysis.md index 291c7e6a5b..c731671837 100644 --- a/content/scout/image-analysis.md +++ b/content/scout/explore/analysis.md @@ -6,6 +6,7 @@ description: keywords: scout, scanning, vulnerabilities, supply chain, security, analysis aliases: - /scout/advanced-image-analysis/ + - /scout/image-analysis/ --- When you activate image analysis for a repository, @@ -13,7 +14,7 @@ Docker Scout automatically analyzes new images that you push to that repository. Image analysis extracts the Software Bill of Material (SBOM) and other image metadata,and evaluates it against vulnerability data from -[security advisories](./advisory-db-sources.md). +[security advisories](/scout/deep-dive/advisory-db-sources.md). If you run image analysis as a one-off task using the CLI or Docker Desktop, Docker Scout won't store any data about your image. @@ -25,19 +26,19 @@ This dynamic evaluation means there's no need to re-analyze images when new CVE Docker Scout image analysis is available by default for Docker Hub repositories. You can also integrate third-party registries and other services. To learn more, -see [Integrating Docker Scout with other systems](./integrations/_index.md). +see [Integrating Docker Scout with other systems](/scout/integrations/_index.md). ## Activate Docker Scout on a repository The free tier of Docker Scout lets you use Docker Scout for up to 3 repositories per Docker organization. You can update your Docker Scout plan if you need additional repositories, see [Docker Scout -billing](../billing/scout-billing.md). +billing](/billing/scout-billing.md). Before you can activate image analysis on a repository in a third-party registry, the registry must be integrated with Docker Scout for your Docker organization. Docker Hub is integrated by default. For more information, see -See [Container registry integrations](./integrations/_index.md#container-registries) +See [Container registry integrations](/scout/integrations/_index.md#container-registries) > **Note** > @@ -74,13 +75,13 @@ analysis is activated. ``` Building with the `--provenance=true` and `--sbom=true` flags attaches - [build attestations](../build/attestations/_index.md) to the image. Docker + [build attestations](/build/attestations/_index.md) to the image. Docker Scout uses attestations to provide more fine-grained analysis results. > **Note** > > The default `docker` driver only supports build attestations if you use the - > [containerd image store](../desktop/containerd.md). + > [containerd image store](/desktop/containerd.md). 3. Go to the [Images page](https://scout.docker.com/reports/images) in the Docker Scout Dashboard. @@ -182,13 +183,13 @@ $ docker scout cves --format only-packages --only-vuln-packages \ For more information about these commands and how to use them, refer to the CLI reference documentation: -- [`docker scout quickview`](../reference/cli/docker/scout/quickview.md) -- [`docker scout cves`](../reference/cli/docker/scout/cves.md) +- [`docker scout quickview`](/reference/cli/docker/scout/quickview.md) +- [`docker scout cves`](/reference/cli/docker/scout/cves.md) ## Vulnerability severity assessment Docker Scout assigns a severity rating to vulnerabilities based on -vulnerability data from [advisory sources](./advisory-db-sources.md). +vulnerability data from [advisory sources](/scout/deep-dive/advisory-db-sources.md). Advisories are ranked and prioritized depending on the type of package that's affected by a vulnerability. For example, if a vulnerability affects an OS package, the severity level assigned by the distribution maintainer is @@ -230,7 +231,7 @@ Image analysis on the Docker Scout platform, and analysis triggered by backgroun indexing in Docker Desktop, has an image file size limit of 10 GB (uncompressed). To analyze images larger than that, you can either: -- Attach [SBOM attestations](../build/attestations/sbom.md) at build-time +- Attach [SBOM attestations](/build/attestations/sbom.md) at build-time - Use the [CLI](#cli) to analyze the image locally Images analyzed locally with the CLI and images with SBOM attestations diff --git a/content/scout/dashboard.md b/content/scout/explore/dashboard.md similarity index 89% rename from content/scout/dashboard.md rename to content/scout/explore/dashboard.md index 52adf7d0ab..e0dd1f31f5 100644 --- a/content/scout/dashboard.md +++ b/content/scout/explore/dashboard.md @@ -6,6 +6,7 @@ title: Dashboard aliases: - /scout/reports/ - /scout/web-app/ +- /scout/dashboard/ --- The [Docker Scout Dashboard](https://scout.docker.com/) helps you share the @@ -17,19 +18,19 @@ vulnerabilities and issues they need to focus on. ## Overview -![A screenshot of the Docker Scout Dashboard overview](./images/dashboard-overview.webp?border=true) +![A screenshot of the Docker Scout Dashboard overview](../images/dashboard-overview.webp?border=true) The **Overview** tab provides a summary for the repositories in the selected organization. At the top of this page, you can select which **Environment** to view. By default, the most recently pushed images are shown. To learn more about -environments, see [Environment monitoring](./integrations/environment/_index.md). +environments, see [Environment monitoring](/scout/integrations/environment/_index.md). The **Policy** boxes show your current compliance rating for each policy, and a trend indication for the selected environment. The trend describes the policy delta for the most recent images compared to the previous version. -For more information about policies, see [Policy Evaluation](./policy/_index.md). +For more information about policies, see [Policy Evaluation](/scout/policy/_index.md). The vulnerability chart shows the total number of vulnerabilities for images in the selected environment over time. You can configure the timescale for the @@ -52,14 +53,14 @@ The **Policies** view shows a breakdown of policy compliance for all of the images in the selected organization and environment. You can use the **Image** drop-down menu to view a policy breakdown for a specific environment. -For more information about policies, see [Policy Evaluation](./policy/_index.md). +For more information about policies, see [Policy Evaluation](/scout/policy/_index.md). ## Images The **Images** view shows all images in Scout-enabled repositories for the selected environment. You can filter the list by selecting a different environment, or by repository name using the text filter. -![Screenshot of the images view](./images/dashboard-images.webp) +![Screenshot of the images view](../images/dashboard-images.webp) For each repository, the list displays the following details: @@ -79,7 +80,7 @@ This view contains two tabs that detail the composition and policy compliance fo - **Policy status** shows the policy evaluation results for the selected image. Here you also have links for details about the policy violations. - For more information about policy, see [Policy Evaluation](./policy/_index.md). + For more information about policy, see [Policy Evaluation](/scout/policy/_index.md). - **Image layers** shows a breakdown of the image analysis results. You can get a complete view of the vulnerabilities your image contains @@ -90,7 +91,7 @@ This view contains two tabs that detail the composition and policy compliance fo The **Vulnerabilities** view shows a list of all vulnerabilities for images in the organization. This list includes details about CVE such as the severity and Common Vulnerability Scoring System (CVSS) score, as well as whether there's a fix version available. -The CVSS score displayed here is the highest score out of all available [sources](./advisory-db-sources.md). +The CVSS score displayed here is the highest score out of all available [sources](/scout/deep-dive/advisory-db-sources.md). Selecting the links on this page opens the vulnerability details page, This page is a publicly visible page, and shows detailed information about a CVE. @@ -105,7 +106,7 @@ affected by the CVE. The **Integrations** page lets you create and manage your Docker Scout integrations, such as environment integrations and registry integrations. For more information on how to get started with integrations, see -[Integrating Docker Scout with other systems](./integrations/_index.md). +[Integrating Docker Scout with other systems](/scout/integrations/_index.md). ## Settings @@ -123,7 +124,7 @@ included in your plan, compare it with other available plans, and change the plan if you're an organization owner. For more information about subscription plans, see -[Docker Scout subscriptions and features](../subscription/scout-details.md) +[Docker Scout subscriptions and features](/subscription/scout-details.md) ### Repository settings @@ -131,7 +132,7 @@ When you enable Docker Scout for a repository, Docker Scout analyzes new tags automatically when you push to that repository. To enable repositories in Amazon ECR, Azure ACR, or other third-party registries, you first need to integrate them. -See [Container registry integrations](./integrations/_index.md#container-registries) +See [Container registry integrations](/scout/integrations/_index.md#container-registries) ### Notification settings @@ -184,7 +185,7 @@ The available notification settings are: notifications using the browser API. From this page, you can also go to the settings for Team collaboration -integrations, such as the [Slack](./integrations/team-collaboration/slack.md) +integrations, such as the [Slack](/scout/integrations/team-collaboration/slack.md) integration. You can also configure your notification settings in Docker Desktop by going diff --git a/content/scout/image-details-view.md b/content/scout/explore/image-details-view.md similarity index 95% rename from content/scout/image-details-view.md rename to content/scout/explore/image-details-view.md index abf047141f..7a4c747ce4 100644 --- a/content/scout/image-details-view.md +++ b/content/scout/explore/image-details-view.md @@ -4,6 +4,8 @@ keywords: scout, supply chain, vulnerabilities, packages, cves, image, tag, scan analysis, analyze description: The Docker Scout image detail view analyzes images to show their heirachy, layers, packages, and vulnerabilities +aliases: + - /scout/image-details-view --- The image details view shows a breakdown of the Docker Scout analysis. You can @@ -12,11 +14,11 @@ access the image view from the Docker Scout Dashboard, the Docker Desktop show a breakdown of the image hierarchy (base images), image layers, packages, and vulnerabilities. -![The image details view in Docker Desktop](./images/dd-image-view.png) +![The image details view in Docker Desktop](../images/dd-image-view.png) Docker Desktop first analyzes images locally, where it generates a software bill of materials (SBOM). Docker Desktop, Docker Hub, and the Docker Scout Dashboard and CLI all use the [package URL (PURL) links](https://github.com/package-url/purl-spec) -in this SBOM to query for matching Common Vulnerabilities and Exposures (CVEs) in [Docker Scout's advisory database](./advisory-db-sources.md). +in this SBOM to query for matching Common Vulnerabilities and Exposures (CVEs) in [Docker Scout's advisory database](/scout/deep-dive/advisory-db-sources.md). ## Image hierarchy @@ -141,7 +143,7 @@ of `debian` to use. By providing more than one alternative to choose from, you can see for yourself how the options compare with each other, and decide which one to use. -![Base image recommendations](./images/change-base-image.png) +![Base image recommendations](../images/change-base-image.png) Select a tag recommendation to see further details of the recommendation. It shows the benefits and potential disadvantages of the tag, why it's a diff --git a/content/scout/metrics-exporter.md b/content/scout/explore/metrics-exporter.md similarity index 95% rename from content/scout/metrics-exporter.md rename to content/scout/explore/metrics-exporter.md index 42efe252bf..2eb85d18d5 100644 --- a/content/scout/metrics-exporter.md +++ b/content/scout/explore/metrics-exporter.md @@ -4,6 +4,8 @@ description: | Learn how to scrape data from Docker Scout using Prometheus to create your own vulnerability and policy dashboards wiht Grafana keywords: scout, exporter, prometheus, grafana, metrics, dashboard, api, compose +aliases: + - /scout/metrics-exporter/ --- Docker Scout exposes a metrics HTTP endpoint that lets you scrape vulnerability @@ -23,7 +25,7 @@ The metrics endpoint exposes the following metrics: > **Streams** > -> In Docker Scout, the streams concept is a superset of [environments](./integrations/environment/_index.md). +> In Docker Scout, the streams concept is a superset of [environments](/scout/integrations/environment/_index.md). > Streams include all runtime environments that you've defined, > as well as the special `latest-indexed` stream. > The `latest-indexed` stream contains the most recently pushed (and analyzed) tag for each repository. @@ -156,16 +158,16 @@ The Prometheus server runs in a Docker container and is accessible on port 9090. After a few seconds, you should see the metrics endpoint as a target in the Prometheus UI at . -![Docker Scout metrics exporter Prometheus target](./images/scout-metrics-prom-target.png "Docker Scout metrics exporter Prometheus target") +![Docker Scout metrics exporter Prometheus target](../images/scout-metrics-prom-target.png "Docker Scout metrics exporter Prometheus target") ### Viewing the metrics in Grafana To view the Grafana dashboards, go to , and sign in using the credentials defined in the Docker Compose file (username: `admin`, password: `grafana`). -![Vulnerability dashboard in Grafana](./images/scout-metrics-grafana-vulns.png "Vulnerability dashboard in Grafana") +![Vulnerability dashboard in Grafana](../images/scout-metrics-grafana-vulns.png "Vulnerability dashboard in Grafana") -![Policy dashboard in Grafana](images/scout-metrics-grafana-policy.png "Policy dashboard in Grafana") +![Policy dashboard in Grafana](../images/scout-metrics-grafana-policy.png "Policy dashboard in Grafana") The dashboards are pre-configured to visualize the vulnerability and policy metrics scraped by Prometheus. @@ -316,13 +318,13 @@ to see the metrics collected from this example. This configuration will collect all exposed metrics starting with `scout_` under the namespace `scout_metrics_exporter`. -![datadog_metrics_summary](images/datadog_metrics_summary.png) +![datadog_metrics_summary](../images/datadog_metrics_summary.png) The following screenshots show examples of a Datadog dashboard containing graphs about vulnerability and policy compliance for a specific [stream](#stream). -![datadog_dashboard_1](images/datadog_dashboard_1.png) -![datadog_dashboard_2](images/datadog_dashboard_2.png) +![datadog_dashboard_1](../images/datadog_dashboard_1.png) +![datadog_dashboard_2](../images/datadog_dashboard_2.png) > The reason why the lines in the graphs look flat is due to the own nature of > vulnerabilities (they don't change too often) and the short time interval diff --git a/content/scout/image-prefix.md b/content/scout/how-tos/artifact-types.md similarity index 96% rename from content/scout/image-prefix.md rename to content/scout/how-tos/artifact-types.md index 5262dddd9b..524219fc8c 100644 --- a/content/scout/image-prefix.md +++ b/content/scout/how-tos/artifact-types.md @@ -1,9 +1,11 @@ --- -title: Specify artifact type or location with prefixes +title: Use Scout with different artifact types description: | Some of the Docker Scout commands support image references prefixes for controlling the location of the images or files that you want to analyze. keywords: scout, vulnerabilities, analyze, analysis, cli, packages, sbom, cve, security, local, source, code, supply chain +aliases: + - /scout/image-prefix/ --- Some of the Docker Scout CLI commands support prefixes for specifying @@ -174,6 +176,6 @@ $ docker scout sbom --format spdx -o sbom.spdx.json archive://scout-cli.tar Read about the commands and supported flags in the CLI reference documentation: -- [`docker scout quickview`](../reference/cli/docker/scout/compare.md) -- [`docker scout cves`](../reference/cli/docker/scout/compare.md) -- [`docker scout compare`](../reference/cli/docker/scout/compare.md) +- [`docker scout quickview`](/reference/cli/docker/scout/quickview.md) +- [`docker scout cves`](/reference/cli/docker/scout/cves.md) +- [`docker scout compare`](/reference/cli/docker/scout/compare.md) diff --git a/content/scout/env-vars.md b/content/scout/how-tos/configure-cli.md similarity index 97% rename from content/scout/env-vars.md rename to content/scout/how-tos/configure-cli.md index d5dfd17f77..d65cc66084 100644 --- a/content/scout/env-vars.md +++ b/content/scout/how-tos/configure-cli.md @@ -1,8 +1,10 @@ --- -title: Environment variables used by Docker Scout +title: Configure Docker Scout with environment variables linkTitle: Docker Scout environment variables description: Configure how the behavior of Docker Scout CLI commands using these environment variables keywords: scout, supply chain, cli, environment, variables, env, vars, configure +aliases: + - /scout/env-vars/ --- The following environment variables are available to configure the Docker Scout diff --git a/content/scout/sbom.md b/content/scout/how-tos/view-create-sboms.md similarity index 91% rename from content/scout/sbom.md rename to content/scout/how-tos/view-create-sboms.md index e1dd04796f..1ac498abf0 100644 --- a/content/scout/sbom.md +++ b/content/scout/how-tos/view-create-sboms.md @@ -4,9 +4,10 @@ description: Use Docker Scout to extract the SBOM for your project. keywords: scout, supply chain, sbom, software bill of material, spdx, cli, attestations, file aliases: - /engine/sbom/ +- /scout/sbom/ --- -[Image analysis](./image-analysis.md) uses image SBOMs to understand what packages and versions an image contains. +[Image analysis](/scout/explore/analysis.md) uses image SBOMs to understand what packages and versions an image contains. Docker Scout uses SBOM attestations if available on the image (recommended). If no SBOM attestation is available, Docker Scout creates one by indexing the image contents. @@ -56,12 +57,12 @@ $ docker scout sbom --format list alpine ``` For more information about the `docker scout sbom` command, refer to the [CLI -reference](../reference/cli/docker/scout/sbom.md). +reference](/reference/cli/docker/scout/sbom.md). ## Attach as build attestation {#attest} You can generate the SBOM and attach it to the image at build-time as an -[attestation](../build/attestations/_index.md). BuildKit provides a default +[attestation](/build/attestations/_index.md). BuildKit provides a default SBOM generator which is different from what Docker Scout uses. You can configure BuildKit to use the Docker Scout SBOM generator using the `--attest` flag for the `docker build` command. @@ -75,7 +76,7 @@ $ docker build --tag / \ ``` To build images with SBOM attestations, you must either turn on -the [containerd image store](../desktop/containerd.md) feature, or use a +the [containerd image store](/desktop/containerd.md) feature, or use a `docker-container` builder together with the `--push` flag to push the image (with attestations) directly to a registry. diff --git a/content/scout/integrations/ci/jenkins.md b/content/scout/integrations/ci/jenkins.md index e9977c178a..52b227e482 100644 --- a/content/scout/integrations/ci/jenkins.md +++ b/content/scout/integrations/ci/jenkins.md @@ -44,6 +44,6 @@ high-severity vulnerabilities. > **Note** > > If you're seeing a `permission denied` error related to the image cache, try -> setting the [`DOCKER_SCOUT_CACHE_DIR`](../../env-vars.md) environment +> setting the [`DOCKER_SCOUT_CACHE_DIR`](/scout/how-tos/configure-cli.md) environment > variable to a writable directory. Or alternatively, disable local caching > entirely with `DOCKER_SCOUT_NO_CACHE=true`. diff --git a/content/scout/integrations/environment/_index.md b/content/scout/integrations/environment/_index.md index 3c52209a42..8dab024595 100644 --- a/content/scout/integrations/environment/_index.md +++ b/content/scout/integrations/environment/_index.md @@ -43,8 +43,8 @@ Docker Scout supports the following runtime integrations: > > Only organization owners can create new environments and set up integrations. > Additionally, Docker Scout only assigns an image to an environment if the -> image [has been analyzed](../../image-analysis.md), either manually or -> through a [registry integration](../_index.md#container-registries). +> image [has been analyzed](/scout/explore/analysis.md), either manually or +> through a [registry integration](/scout/integrations/_index.md#container-registries). ## List environments @@ -79,7 +79,7 @@ comparing the image built from the code in the PR to the corresponding image in staging or production. You can also compare with streams using the `--to-env` flag on the -[`docker scout compare`](../../../reference/cli/docker/scout/compare.md) +[`docker scout compare`](/reference/cli/docker/scout/compare.md) CLI command: ```console diff --git a/content/scout/integrations/registry/ecr.md b/content/scout/integrations/registry/ecr.md index 40650f51d6..99306ac838 100644 --- a/content/scout/integrations/registry/ecr.md +++ b/content/scout/integrations/registry/ecr.md @@ -26,7 +26,7 @@ After the integration, Docker Scout automatically pulls and analyzes images that you push to the ECR registry. Metadata about your images are stored on the Docker Scout platform, but Docker Scout doesn't store the container images themselves. For more information about how Docker Scout handles image data, see -[Data handling](../../data-handling.md). +[Data handling](/scout/deep-dive/data-handling.md). ### CloudFormation stack template diff --git a/content/scout/integrations/team-collaboration/slack.md b/content/scout/integrations/team-collaboration/slack.md index f2cf515d4e..3844718802 100644 --- a/content/scout/integrations/team-collaboration/slack.md +++ b/content/scout/integrations/team-collaboration/slack.md @@ -27,7 +27,7 @@ to the Slack channels associated with the webhook. > is not by a newly disclosed CVE, then no notification will be triggered. For more information about Docker Scout notifications, -see [Notification settings](../../dashboard.md#notification-settings) +see [Notification settings](/scout/explore/dashboard.md#notification-settings) ## Setup diff --git a/content/scout/policy/_index.md b/content/scout/policy/_index.md index e3b63c31b2..98580a81c5 100644 --- a/content/scout/policy/_index.md +++ b/content/scout/policy/_index.md @@ -25,7 +25,7 @@ with established best practices. ## 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 +[automatically analyzed](/scout/explore/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 diff --git a/content/scout/quickstart.md b/content/scout/quickstart.md index 3ab2a2c8b2..56a65c7879 100644 --- a/content/scout/quickstart.md +++ b/content/scout/quickstart.md @@ -274,7 +274,7 @@ to policy customization, and runtime environment monitoring in real-time. Check out the following sections: -- [Image analysis](./image-analysis.md) +- [Image analysis](/scout/explore/analysis.md) - [Data sources](/scout/advisory-db-sources) - [Docker Scout Dashboard](/scout/dashboard) - [Integrations](./integrations/_index.md) diff --git a/content/scout/release-notes/platform.md b/content/scout/release-notes/platform.md index 9b6cda698a..9bb2825af0 100644 --- a/content/scout/release-notes/platform.md +++ b/content/scout/release-notes/platform.md @@ -23,7 +23,7 @@ New features and enhancements released in the second quarter of 2024. New HTTP endpoint that lets you scrape data from Docker Scout with Prometheus, to create your own vulnerability and policy dashboards with Grafana. -For more information, see [Docker Scout metrics exporter](../metrics-exporter.md). +For more information, see [Docker Scout metrics exporter](/scout/explore/metrics-exporter.md). ## Q1 2024 diff --git a/content/security/faqs/general.md b/content/security/faqs/general.md index 76053412ab..58f088539b 100644 --- a/content/security/faqs/general.md +++ b/content/security/faqs/general.md @@ -71,7 +71,7 @@ If SCIM isn't enabled, you have to manually remove PAT users from the organizati ### What metadata is collected from container images that Scout analyzes? -For information about the metadata stored by Docker Scout, see [Data handling](../../scout/data-handling.md). +For information about the metadata stored by Docker Scout, see [Data handling](/scout/deep-dive/data-handling.md). ### How are extensions within the Marketplace vetted for security prior to placement? diff --git a/data/redirects.yml b/data/redirects.yml index a43a48ab02..79fc7a969a 100644 --- a/data/redirects.yml +++ b/data/redirects.yml @@ -609,10 +609,8 @@ - /go/docker-scout/ "/scout/quickstart/": - /go/scout-quickstart/ -"/scout/dashboard/": +"/scout/explore/dashboard/": - /go/scout-dashboard/ -"/scout/ci/": - - /go/scout-ci/ "/scout/policy/": - /go/scout-policy/ "/scout/policy/configure/": @@ -620,6 +618,8 @@ "/build/building/best-practices/#pin-base-image-versions": - /go/base-image-pinning/ # integrations +"/scout/integrations/ci/": + - /go/scout-ci/ "/scout/integrations/ci/gha/": - "/go/scout-gha/" "/scout/integrations/ci/gitlab/": @@ -646,9 +646,9 @@ - "/go/scout-github/" "/scout/guides/vex/": - "/go/vex-guide/" -"/scout/metrics-exporter/": +"/scout/explore/metrics-exporter/": - "/go/scout-metrics-exporter" -"/scout/dashboard/#notification-settings": +"/scout/explore/dashboard/#notification-settings": - /go/scout-notifications/ "/scout/integrations/team-collaboration/slack/": - "/go/scout-slack/" diff --git a/data/toc.yaml b/data/toc.yaml index c5a3dd9240..eb4ab4718c 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1415,28 +1415,30 @@ Manuals: title: Quickstart - path: /scout/install/ title: Install - - sectiontitle: Explore Docker Scout + - sectiontitle: Explore section: - - path: /scout/dashboard/ + - path: /scout/explore/analysis/ + title: Analysis + - path: /scout/explore/dashboard/ title: Dashboard - - path: /scout/image-details-view/ + - path: /scout/explore/image-details-view/ title: Image details view - - path: /scout/advisory-db-sources/ - title: Advisory database - - path: /scout/data-handling/ - title: Data handling - - sectiontitle: Use Docker Scout - section: - - path: /scout/image-analysis/ - title: Image analysis - - path: /scout/image-prefix/ - title: Specify artifact type or location - - path: /scout/sbom/ - title: SBOM - - path: /scout/env-vars/ - title: Environment variables - - path: /scout/metrics-exporter/ + - path: /scout/explore/metrics-exporter/ title: Metrics exporter + - sectiontitle: How-tos + section: + - path: /scout/how-tos/artifact-types/ + title: Specify artifact type or location + - path: /scout/how-tos/view-create-sboms/ + title: View and create SBOMs + - path: /scout/how-tos/configure-cli/ + title: Configure the CLI + - sectiontitle: Deep dive + section: + - path: /scout/deep-dive/advisory-db-sources/ + title: Advisory database + - path: /scout/deep-dive/data-handling/ + title: Data handling - sectiontitle: Policy Evaluation section: - path: /scout/policy/ From 64b844c9bf9028297f6517125c0b345504193567 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 12 Jun 2024 16:51:31 +0200 Subject: [PATCH 3/3] scout: add fundamental concepts pages Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/scout/concepts/s3c.md | 61 ++++++++++++++++++++++++++++++++++ content/scout/concepts/sbom.md | 50 ++++++++++++++++++++++++++++ data/toc.yaml | 6 ++++ 3 files changed, 117 insertions(+) create mode 100644 content/scout/concepts/s3c.md create mode 100644 content/scout/concepts/sbom.md diff --git a/content/scout/concepts/s3c.md b/content/scout/concepts/s3c.md new file mode 100644 index 0000000000..f9beb5ff6f --- /dev/null +++ b/content/scout/concepts/s3c.md @@ -0,0 +1,61 @@ +--- +title: Software supply chain security +description: Learn about software supply chain security (S3C), what it means, and why it is important. +keywords: docker scout, secure, software, supply, chain, security, sssc, sscs, s3c +--- + +The term "software supply chain" refers to the end-to-end process of developing +and delivering software, from the development to deployment and maintenance. +Software supply chain security, or "S3C" for short, is the practice for +protecting the components and processes of the supply chain. + +S3C is a fundamental change in how organizations approach software security. +Traditionally in the software industry, security and compliance has been mostly +an afterthought, left to the software delivery or release phase. With S3C, +security is integrated into the entire software development lifecycle, from the +inner loop of development and testing, to the outer loop of shipping and +monitoring. + +Following industry best practices for software supply chain conduct is +important because it helps organizations protect their software from security +threats, compliance risks, and other vulnerabilities. Implementing a software +supply chain security framework improves visibility, collaboration, and +traceability of a project across stakeholders. This helps organizations detect, +respond to, and remediate threats more effectively. + +## Securing the software supply chain + +Building a secure software supply chain involves several key steps, such as: + +- Identify the software components and dependencies you use to build and run + your applications. +- Automate security testing throughout the software development lifecycle. +- Monitor your software supply chain for security threats. +- Implement security policies that govern how software is built, and the + components it contains. + +Managing the software supply chain is a complex task, especially in the modern +day where software is built using multiple components from different sources. +Organizations need to have a clear understanding of the software components +they use, and the security risks associated with them. + +## Docker Scout + +Docker Scout is a platform designed to help organizations secure their software +supply chain. It provides tools and services for identifying and managing +software assets and policies, and automated remediation of security threats. + +Unlike traditional security tools that focus on scheduled, point-in-time scans +at specific stages in the software development lifecycle, Docker Scout uses a +modern event-driven model that spans the entire software supply chain. This +means that when a new vulnerability affecting your images is disclosed, your +updated risk assessment is available within seconds, and earlier in the +development process. + +Docker Scout works by analyzing the composition of your images to create a +[Software Bill of Materials (SBOM)](/scout/concepts/sbom.md). The SBOM is +cross-referenced against the security advisories to identify CVEs that affect +your images. Docker Scout integrates with [over 20 different security +advisories](/scout/deep-dive/advisory-db-sources.md), and updates its +vulnerability database in real-time. This ensures that your security posture is +represented using the latest available information. diff --git a/content/scout/concepts/sbom.md b/content/scout/concepts/sbom.md new file mode 100644 index 0000000000..6f7a33e9a3 --- /dev/null +++ b/content/scout/concepts/sbom.md @@ -0,0 +1,50 @@ +--- +title: Software Bill of Materials +description: Learn about Software Bill of Materials (SBOM) and how Docker Scout uses it. +keywords: scout, sbom, software bill of materials, analysis, composition +--- + +A Bill of Materials (BOM) is a list of materials, parts, and the quantities of +each needed to manufacture a product. For example, a BOM for a computer might +list the motherboard, CPU, RAM, power supply, storage devices, case, and other +components, along with the quantities of each that are needed to build the +computer. + +A Software Bill of Materials (SBOM) is a list of all the components that make +up a piece of software. This includes open source and third-party components, +as well as any custom code that has been written for the software. An SBOM is +similar to a BOM for a physical product, but for software. + +In the context of software supply chain security, SBOMs can help with +identifying and mitigating security and compliance risks in software. By +knowing exactly what components are used in a piece of software, you can +quickly identify and patch vulnerabilities in your components, or determine if +a component is licensed in a way that is incompatible with your project. + +## Contents of an SBOM + +An SBOM typically includes the following information: + +- The name of the software, such as the name of a library or framework, that + the SBOM describes. +- The version of the software. +- The license under which the software is distributed. +- A list of other components that the software depends on. + +## How Docker Scout uses SBOMs + +Docker Scout uses SBOMs to determine the components that are used in a Docker +image. When you analyze an image, Docker Scout will either use the SBOM that is +attached to the image (using [attestations](/build/attestations/_index.md)), or +it will generate an SBOM on the fly by analyzing the contents of the image. + +The SBOM is cross-referenced with the [advisory database](/scout/deep-dive/advisory-db-sources.md) +to determine if any of the components in the image have known vulnerabilities. + +## Additional resources + +To learn more about generating SBOMs and how SBOMs are used in Docker Scout, +see: + +- [Image analysis in Docker Scout](/scout/explore/analysis.md) +- [View and create SBOMs](/scout/how-tos/view-create-sboms.md) diff --git a/data/toc.yaml b/data/toc.yaml index eb4ab4718c..8a40656972 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1415,6 +1415,12 @@ Manuals: title: Quickstart - path: /scout/install/ title: Install + - sectiontitle: Concepts + section: + - path: /scout/concepts/s3c/ + title: Software supply chain security + - path: /scout/concepts/sbom/ + title: Software Bill of Materials - sectiontitle: Explore section: - path: /scout/explore/analysis/