diff --git a/content/manuals/dhi/core-concepts/vex.md b/content/manuals/dhi/core-concepts/vex.md index df7189486d43..264779962baf 100644 --- a/content/manuals/dhi/core-concepts/vex.md +++ b/content/manuals/dhi/core-concepts/vex.md @@ -1,39 +1,41 @@ --- title: Vulnerability Exploitability eXchange (VEX) linktitle: VEX -description: Learn how VEX helps you prioritize real risks by identifying which vulnerabilities in Docker Hardened Images are actually exploitable. +description: Learn how VEX helps you prioritize real risks through producer assertions about which vulnerabilities in Docker Hardened Images are exploitable in the product as shipped. keywords: vex container security, vulnerability exploitability, filter false positives, docker scout vex, cve prioritization --- ## What is VEX? -Vulnerability Exploitability eXchange (VEX) is a standardized framework -developed by the U.S. Cybersecurity and Infrastructure Security Agency (CISA) to -document the exploitability of vulnerabilities within software components. -Unlike traditional CVE (Common Vulnerabilities and Exposures) databases, VEX -provides contextual assessments, indicating whether a vulnerability is -exploitable in a given environment. This approach helps organizations prioritize -remediation efforts by distinguishing between vulnerabilities that are -exploitable and those that are not relevant to their specific use cases. +Vulnerability Exploitability eXchange (VEX) is a specification for documenting +the exploitability status of vulnerabilities within software components. VEX is +primarily defined through industry standards such as CSAF (OASIS) and CycloneDX +VEX, with the U.S. Cybersecurity and Infrastructure Security Agency (CISA) +encouraging its adoption. VEX complements CVE (Common Vulnerabilities and +Exposures) identifiers by adding producer-asserted status information, +indicating whether a vulnerability is exploitable in the product as shipped. +This helps organizations prioritize remediation efforts by identifying +vulnerabilities that do not affect their specific product configurations. ## Why is VEX important? VEX enhances traditional vulnerability management by: -- Reducing false positives: By providing context-specific assessments, VEX helps - in filtering out vulnerabilities that do not pose a threat in a particular - environment. +- Suppressing non-applicable vulnerabilities: By providing product-level + exploitability assertions from the supplier, VEX helps filter out + vulnerabilities that do not affect the product as shipped. - Prioritizing remediation: Organizations can focus resources on addressing - vulnerabilities that are exploitable in their specific context, improving - efficiency in vulnerability management. + vulnerabilities that the producer has confirmed are exploitable in the + product, improving efficiency in vulnerability management. -- Enhancing compliance: VEX reports provide detailed information that can assist - in meeting regulatory requirements and internal security standards. +- Supporting vulnerability documentation: VEX statements can support audit + discussions and help document why certain vulnerabilities do not require + remediation. -This approach is particularly beneficial in complex environments where numerous -components and configurations exist, and traditional CVE-based assessments may -lead to unnecessary remediation efforts. +This approach is particularly beneficial when working with complex software +components where not all reported CVEs apply to the specific product +configuration. ## How Docker Hardened Images integrate VEX @@ -42,54 +44,29 @@ VEX reports, providing context-specific assessments of known vulnerabilities. This integration allows you to: -- Assess exploitability: Determine whether known vulnerabilities in the image's -components are exploitable in their specific environment. +- Consume producer assertions: Review Docker's assertions about whether known + vulnerabilities in the image's components are exploitable in the product as + shipped. -- Prioritize actions: Focus remediation efforts on vulnerabilities that pose - actual risks, optimizing resource allocation. +- Prioritize actions: Focus remediation efforts on vulnerabilities that Docker + has confirmed are exploitable in the image, optimizing resource allocation. -- Streamline audits: Utilize the detailed information provided by VEX reports to - simplify compliance audits and reporting. +- Support audit documentation: Use VEX statements to document why certain + reported vulnerabilities do not require immediate action. -By combining the security features of DHI with the contextual insights of VEX, -organizations can achieve a more effective and efficient approach to -vulnerability management. +By combining the security features of DHI with VEX's product-level +exploitability assertions, organizations can achieve a more effective and +efficient approach to vulnerability management. -## Use VEX to filter known non-exploitable CVEs - -When using Docker Scout or Trivy, VEX statements are automatically applied as -shown in the examples in [Common Vulnerabilities and Exposures (CVEs)](./cves.md). - -For Grype, you need to export the VEX attestation to a file first before -scanning, as shown in the [Grype scanning example](./cves.md#scan-a-dhi-using-grype). - -> [!NOTE] +> [!TIP] > -> By default, VEX attestations are fetched from `registry.scout.docker.com`. Ensure that you can access this registry if -> your network has outbound restrictions. You can also mirror the attestations to an alternate registry. For more -> details, see [Mirror a Docker Hardened Image -> repository](../how-to/mirror.md#mirror-from-docker-hub-to-another-registry). - -To manually retrieve the VEX attestation for tools that support it: - -```console -$ docker scout vex get dhi.io/: --output vex.json -``` - -> [!NOTE] -> -> The `docker scout vex get` command requires [Docker Scout -> CLI](https://github.com/docker/scout-cli/) version 1.18.3 or later. -> -> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use -> `registry://dhi.io/python:3.13` instead of `dhi.io/python:3.13`. - -For example: +> To understand which scanners support VEX and why it matters for your security +> workflow, see [Scanner integrations](/manuals/dhi/explore/scanner-integrations.md). -```console -$ docker scout vex get dhi.io/python:3.13 --output vex.json -``` +## Use VEX to suppress non-applicable CVEs -This creates a `vex.json` file containing the VEX statements for the specified -image. You can then use this file with tools that support VEX to filter out -known non-exploitable CVEs. \ No newline at end of file +Docker Hardened Images include VEX attestations that can be consumed by +vulnerability scanners to suppress non-applicable CVEs. For detailed +instructions on scanning with VEX support across different tools including +Docker Scout, Trivy, and Grype, see [Scan Docker Hardened +Images](/manuals/dhi/how-to/scan.md). \ No newline at end of file diff --git a/content/manuals/dhi/explore/_index.md b/content/manuals/dhi/explore/_index.md index 1f81916cb6df..7055a2d101b9 100644 --- a/content/manuals/dhi/explore/_index.md +++ b/content/manuals/dhi/explore/_index.md @@ -13,6 +13,14 @@ params: description: Learn how Docker builds, tests, and maintains Docker Hardened Images through an automated, security-focused pipeline. icon: build link: /dhi/explore/build-process/ + - title: Image types + description: Learn about the different image types, distributions, and variants offered in the Docker Hardened Images catalog. + icon: view_module + link: /dhi/explore/available/ + - title: Scanner integrations + description: Discover which vulnerability scanners integrate with Docker Hardened Images and support open standards like OpenVEX. + icon: security + link: /dhi/explore/scanner-integrations/ - title: Image testing description: See how Docker Hardened Images are automatically tested for standards compliance, functionality, and security. icon: science @@ -21,10 +29,6 @@ params: description: Understand Docker's role and your responsibilities when using Docker Hardened Images as part of your secure software supply chain. icon: group link: /dhi/explore/responsibility/ - - title: Image types - description: Learn about the different image types, distributions, and variants offered in the Docker Hardened Images catalog. - icon: view_module - link: /dhi/explore/available/ - title: Give feedback icon: question_exchange description: Docker welcomes all contributions and feedback. diff --git a/content/manuals/dhi/explore/scanner-integrations.md b/content/manuals/dhi/explore/scanner-integrations.md new file mode 100644 index 000000000000..c2704d6768b6 --- /dev/null +++ b/content/manuals/dhi/explore/scanner-integrations.md @@ -0,0 +1,169 @@ +--- +title: Scanner integrations +description: Learn which vulnerability scanners work with Docker Hardened Images and how to choose the right scanner for accurate vulnerability assessment. +keywords: scanner integration, vulnerability scanning, docker scout, trivy, grype, container security scanners +weight: 40 +--- + +Docker Hardened Images work with various vulnerability scanners. However, to get +accurate results that reflect the actual security posture of these images, your +scanner needs to understand the VEX (Vulnerability Exploitability eXchange) +attestations included with each image. + +## Scanners with VEX support + +The following are a few scanners that can read and apply the VEX attestations +included with Docker Hardened Images, providing accurate vulnerability +assessments: + +- [Docker Scout](/scout/): Automatically applies VEX statements with + zero configuration. Integrated directly into Docker Desktop and the Docker CLI. +- [Trivy](https://trivy.dev/): Supports VEX through VEX Hub for automatic + updates or local VEX files for air-gapped environments. +- [Grype](https://github.com/anchore/grype): Supports VEX via the `--vex` + flag for local VEX file processing. +- [Wiz](https://www.wiz.io/): TBD + +For step-by-step instructions, see [Scan Docker Hardened Images](/manuals/dhi/how-to/scan.md). + +## Choosing a scanner for Docker Hardened Images + +When selecting a scanner for use with Docker Hardened Images, whether it +supports open standards like OpenVEX is the key differentiator. + +Docker Hardened Images include signed VEX attestations that follow the +[OpenVEX standard](https://openvex.dev/). OpenVEX is an open standard that meets +the minimum requirements for VEX defined by CISA (Cybersecurity and +Infrastructure Security Agency), the U.S. government agency responsible for +cybersecurity guidance. These attestations document which vulnerabilities don't +apply to the image and why, helping you focus on real risks. To understand what +VEX is and how it works, see the [VEX core concept](/manuals/dhi/core-concepts/vex.md). + +Because OpenVEX is an open standard with government backing, it has strong +industry momentum and any tool can implement it without vendor-specific +integrations. This matters when you bring in third-party auditors with their own +scanning tools, or when you want to use multiple security tools in your +pipeline. With VEX, these tools can all read and verify the same vulnerability +data directly from your images. + +Without open standards like VEX, vendors make exploitability decisions using +proprietary methods, making it difficult to verify claims or compare results +across tools. This fragments your security toolchain and creates inconsistent +vulnerability assessments across different scanning tools. + +### Benefits of scanners with VEX support + +Scanners that support open standards like OpenVEX and can read VEX attestations +from Docker Hardened Images provide: + +- Accurate vulnerability counts: Automatically filter out vulnerabilities + that don't apply to your specific image, often reducing false positives + dramatically. +- Transparency and auditability: Verify exactly why vulnerabilities are or + aren't flagged; security teams and compliance officers can review the reasoning + rather than trusting a vendor's black box. +- Scanner flexibility: Switch between any VEX-enabled scanner (Docker Scout, + Trivy, Grype, etc.) without losing vulnerability context or rebuilding + exclusion lists. +- Consistent results: All VEX-enabled scanners interpret the same data the + same way, eliminating discrepancies between tools. +- Faster workflows: Focus on real risks rather than researching why reported + CVEs don't actually affect your deployment. + +### Scanners without VEX support + +Scanners that can't read VEX attestations will report vulnerabilities that don't +apply to Docker Hardened Images. This creates operational challenges: + +- Manual filtering required: You'll need to maintain scanner-specific ignore + lists to replicate what VEX statements already document. +- Higher false positive rates: Expect to see more reported vulnerabilities + that don't represent real risks. +- Increased investigation time: Security teams spend time researching why + CVEs don't apply instead of addressing actual vulnerabilities. +- CI/CD friction: Build pipelines may fail on vulnerabilities that aren't + exploitable in your images. + +### VEX-based vulnerability handling vs. proprietary approaches + +Docker Hardened Images use VEX attestations based on the OpenVEX open standard to document vulnerability exploitability. OpenVEX is an open standard that is recognized by government agencies such as CISA. This open standards approach differs from how some other image vendors handle vulnerabilities using proprietary methods. + +#### Docker Hardened Images with VEX + +The image includes signed attestations that explain which vulnerabilities don't +apply and why. Any VEX-enabled scanner can read these attestations, giving you: + +- Tool flexibility: Use any scanner that supports OpenVEX (Docker Scout, + Trivy, Grype, Wiz, etc.) +- Complete transparency: Review the exact reasoning for each vulnerability + assessment +- Full auditability: Security teams and compliance officers can independently + verify all vulnerability assessments and reasoning +- Historical visibility: VEX statements remain with the image, so you can + always check vulnerability status, even for older versions + +#### Proprietary vulnerability handling + +Some image vendors use proprietary advisory feeds or internal databases instead +of VEX. While this may result in fewer reported vulnerabilities, it creates +significant limitations: + +- Tool dependency: You must use the vendor's preferred scanning tools to see + their vulnerability filtering, while standard scanners will still report all + CVEs; scanners must implement proprietary feeds rather than using open + standards that work with all images +- No transparency: Proprietary feeds act as "black boxes" - vulnerabilities + simply disappear from vendor tools with no explanation +- Limited verifiability: Security teams have no way to independently verify + why vulnerabilities are excluded or whether the reasoning is sound +- Maintenance challenges: If you scan older image versions with standard + tools, you can't determine which vulnerabilities actually applied at that + time, making long-term security tracking difficult +- Ecosystem incompatibility: Your existing security tools (SCA, policy + engines, compliance scanners) can't access or verify the vendor's proprietary + vulnerability data + +The fundamental difference: VEX-based approaches explain vulnerability +assessments using open standards that any tool can verify and audit. Proprietary +approaches hide vulnerabilities in vendor-specific systems where the reasoning +can't be independently validated. + +For Docker Hardened Images, use VEX-enabled scanners to get accurate results +that work across your entire security toolchain. + +## What to expect from different scanners + +When scanning Docker Hardened Images with different tools, you'll see +significant differences in reported vulnerability counts. + +### What VEX-enabled scanners filter automatically + +When you scan Docker Hardened Images with VEX-enabled scanners, they +automatically exclude vulnerabilities that don't apply: + +- Hardware-specific vulnerabilities: Issues that only affect specific + hardware architectures (for example, Power10 processors) that are irrelevant to + containerized workloads. +- Unreachable code paths: CVEs in code that exists in the package but isn't + executed in the image's runtime configuration. +- Build-time only issues: Vulnerabilities in build tools or dependencies + that don't exist in the final runtime image. +- Temporary identifiers: Placeholder vulnerability IDs (like Debian's + `TEMP-xxxxxxx`) that aren't intended for external tracking. + +### Using scanners without VEX support + +If your scanner doesn't support VEX, you'll need to manually exclude +vulnerabilities through scanner-specific mechanisms like ignore lists or policy +exceptions. This requires: + +- Reviewing VEX statements from Docker Hardened Images +- Translating VEX justifications into your scanner's format +- Maintaining these exclusions as new vulnerabilities are discovered +- Repeating this process if you switch scanners or add additional scanning tools + +## What's next + +Learn how to [scan Docker Hardened Images](/manuals/dhi/how-to/scan.md) with +VEX-compliant scanners. + diff --git a/content/manuals/dhi/how-to/scan.md b/content/manuals/dhi/how-to/scan.md index 7a0055de32bb..74f5b37cc124 100644 --- a/content/manuals/dhi/how-to/scan.md +++ b/content/manuals/dhi/how-to/scan.md @@ -1,7 +1,7 @@ --- title: Scan Docker Hardened Images linktitle: Scan an image -description: Learn how to scan Docker Hardened Images for known vulnerabilities using Docker Scout, Grype, or Trivy. +description: Learn how to scan Docker Hardened Images for known vulnerabilities using Docker Scout, Grype, Trivy, or Wiz. keywords: scan container image, docker scout cves, grype scanner, trivy container scanner, vex attestation weight: 46 --- @@ -10,27 +10,20 @@ Docker Hardened Images (DHIs) are designed to be secure by default, but like any container image, it's important to scan them regularly as part of your vulnerability management process. -You can scan DHIs using the same tools you already use for standard images, such -as Docker Scout, Grype, and Trivy. DHIs follow the same formats and standards -for compatibility across your security tooling. Before you scan an image, the image must -be mirrored into your organization on Docker Hub. +## Scan with OpenVEX-compliant scanners -> [!NOTE] -> -> When you have a Docker Hardened Images Enterprise subscription, [Docker -> Scout](/manuals/scout/_index.md) is automatically enabled at no additional -> cost for all mirrored Docker Hardened Image repositories on Docker Hub. You -> can view scan results directly in the Docker Hub UI under your organization's -> repository. +To get accurate vulnerability assessments, use scanners that support +[VEX](/manuals/dhi/core-concepts/vex.md) attestations. The following scanners can +read and apply the VEX statements included with Docker Hardened Images: -> [!IMPORTANT] -> -> You must authenticate to the Docker Hardened Images registry (`dhi.io`) to -> pull images. Use your Docker ID credentials (the same username and password -> you use for Docker Hub) when signing in. If you don't have a Docker account, -> [create one](../../accounts/create-account.md) for free. -> -> Run `docker login dhi.io` to authenticate. +- [Docker Scout](#docker-scout): Automatically applies VEX statements with zero configuration +- [Trivy](#trivy): Supports VEX through VEX Hub or local VEX files +- [Grype](#grype): Supports VEX via the `--vex` flag +- [Wiz](#wiz): Supports VEX attestations for accurate vulnerability filtering + +For guidance on choosing the right scanner and understanding the differences +between VEX-enabled and non-VEX scanners, see [Scanner +integrations](/manuals/dhi/explore/scanner-integrations.md). ## Docker Scout @@ -43,6 +36,7 @@ To scan a Docker Hardened Image using Docker Scout, run the following command: ```console +$ docker login dhi.io $ docker scout cves dhi.io/: --platform ``` @@ -126,26 +120,6 @@ insecure images. For more details on using Docker Scout in CI, see [Integrating Docker Scout with other systems](/manuals/scout/integrations/_index.md). -### Comparing Docker Scout results with other scanners - -Some vulnerabilities reported by other scanners may not appear in Docker Scout results. This can happen for several -reasons: - -- Hardware-specific vulnerabilities: Certain vulnerabilities may only affect specific hardware architectures (for - example, Power10 processors) that are not relevant to Docker images, so they are not reported by Docker Scout. -- VEX statement filtering: Docker Scout automatically applies VEX statements to document and suppress vulnerabilities - that do not apply to the image. If your scanner does not consume VEX statements, you may see more vulnerabilities - reported than what appears in Docker Scout results. -- Temporary vulnerability identifiers: Temporary vulnerability identifiers (like `TEMP-xxxxxxx` from Debian) are not - surfaced by Docker Scout, as they are not intended for external reference. - -While Docker Scout handles this filtering automatically, you can manually configure similar filtering with other -scanners using [Grype ignore rules](https://github.com/anchore/grype#specifying-matches-to-ignore) in its configuration -file (`~/.grype.yaml`) or [Trivy policy exceptions](https://trivy.dev/v0.19.2/misconfiguration/policy/exceptions/) using -REGO rules to filter out specific vulnerabilities by CVE ID, package name, fix state, or other criteria. You can also -use VEX statements with other scanners as described in [Use VEX to filter known non-exploitable -CVEs](#use-vex-to-filter-known-non-exploitable-cves). - ## Grype [Grype](https://github.com/anchore/grype) is an open-source scanner that checks @@ -154,27 +128,21 @@ advisories. ### Scan a DHI using Grype -After installing Grype, you can scan a Docker Hardened Image by pulling -the image and running the scan command: +To scan a Docker Hardened Image using Grype with VEX filtering, first export +the VEX attestation and then scan with the `--vex` flag: ```console +$ docker login dhi.io $ docker pull dhi.io/: -$ grype dhi.io/: +$ docker scout vex get dhi.io/: --output vex.json +$ grype dhi.io/: --vex vex.json ``` -Example output: +The `--vex` flag applies VEX statements during the scan, filtering out known +non-exploitable CVEs for accurate results. -```plaintext -NAME INSTALLED FIXED-IN TYPE VULNERABILITY SEVERITY EPSS% RISK -libperl5.36 5.36.0-7+deb12u2 (won't fix) deb CVE-2023-31484 High 79.45 1.1 -perl 5.36.0-7+deb12u2 (won't fix) deb CVE-2023-31484 High 79.45 1.1 -perl-base 5.36.0-7+deb12u2 (won't fix) deb CVE-2023-31484 High 79.45 1.1 -... -``` - -You should include the `--vex` flag to apply VEX statements during the scan, -which filter out known non-exploitable CVEs. For more information, see the [VEX -section](#use-vex-to-filter-known-non-exploitable-cves). +For more information on exporting VEX attestations, see [Export VEX +attestations](#export-vex-attestations). ## Trivy @@ -188,6 +156,7 @@ After installing Trivy, you can scan a Docker Hardened Image by pulling the image and running the scan command: ```console +$ docker login dhi.io $ docker pull dhi.io/: $ trivy image --scanners vuln dhi.io/: ``` @@ -223,6 +192,7 @@ $ trivy vex repo download After setting up VEX Hub, you can scan a Docker Hardened Image with VEX filtering: ```console +$ docker login dhi.io $ docker pull dhi.io/: $ trivy image --scanners vuln --vex repo dhi.io/: ``` @@ -271,14 +241,24 @@ Then scan the image with the local VEX file: $ trivy image --scanners vuln --vex vex.json dhi.io/: ``` -## Use VEX to filter known non-exploitable CVEs +## Wiz + +[Wiz](https://www.wiz.io/) is a cloud security platform that includes container +image scanning capabilities with support for VEX attestations. Wiz automatically +consumes VEX statements from Docker Hardened Images to provide accurate +vulnerability assessments. + +### Scan a DHI using Wiz + +Wiz automatically integrates with container registries and scans images as part +of its cloud security posture management. -Docker Hardened Images include signed VEX (Vulnerability Exploitability -eXchange) attestations that identify vulnerabilities not relevant to the image’s -runtime behavior. +TBD -When using Docker Scout, these VEX statements are automatically applied and no -manual configuration needed. +## Export VEX attestations + +For scanners that need local VEX files (like Grype or Trivy with local files), +you can export the VEX attestations from Docker Hardened Images. > [!NOTE] > @@ -286,7 +266,7 @@ manual configuration needed. > if your network has outbound restrictions. You can also mirror the attestations to an alternate registry. For more > details, see [Mirror to a third-party registry](mirror.md#mirror-to-a-third-party-registry). -To manually create a JSON file of VEX attestations for tools that support it: +Export VEX attestations to a JSON file: ```console $ docker scout vex get dhi.io/: --output vex.json @@ -300,19 +280,3 @@ $ docker scout vex get dhi.io/: --output vex.json > If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use > `registry://docs/dhi-python:3.13` instead of `docs/dhi-python:3.13`. -For example: - -```console -$ docker scout vex get dhi.io/python:3.13 --output vex.json -``` - -This creates a `vex.json` file containing the VEX statements for the specified -image. You can then use this file with tools that support VEX to filter out -known non-exploitable CVEs. - -For example, with Grype you can use the `--vex` flag to apply the VEX -statements during the scan: - -```console -$ grype dhi.io/python:3.13 --vex vex.json -```