dhi: add scanner integration

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 @@
 
 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/<image>:<tag> --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.
+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).

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.

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.
+