Skip to content

Commit 41fb4e7

Browse files
craig-osterhoutcraig-osterhout
authored
dhi: add malware scan info (#24729)
<!--Delete sections as needed --> ## Description ### Summary - Add new Explore topic documenting how Docker scans DHI images for malware using ClamAV, including how to retrieve and verify the virus scan attestation - Update the base and customized build pipeline descriptions to include scanning (malware, secrets, vulnerabilities) as an explicit pipeline step - Add cross-references from the attestations page to the new malware scanning topic ### Details DHI images include a signed virus/malware scan attestation (`https://scout.docker.com/virus/v0.1`), but this wasn't documented anywhere beyond a one-line mention in the attestations table. This PR adds a dedicated Explore topic for it and integrates scanning into the build pipeline documentation. The attestation content was verified by pulling actual attestations from both a base image (`dhi.io/python:3.13`) and a customized image (`projectsteam/dhi-python-3:3.10-alpine3.22_curl`). Key findings that informed the docs: - The virus scan uses **ClamAV** (`clamav/clamav:stable`), scanning all OCI blobs including archives - The attestation payload is JSON with a base64-encoded ClamAV report - Both base and customized images get virus, secrets, and vulnerability scanning - Only base images get the functional **test** attestation — customized images do not ### Notable generated topics - https://deploy-preview-24729--docsdocker.netlify.app/dhi/explore/malware-scanning/ - https://deploy-preview-24729--docsdocker.netlify.app/dhi/explore/build-process/ ## Related issues or tickets Closes #24728 ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [ ] Editorial review --------- Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
1 parent a6744fa commit 41fb4e7

File tree

5 files changed

+121
-19
lines changed

5 files changed

+121
-19
lines changed

‎content/manuals/dhi/core-concepts/attestations.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ For more details, see [Verify image attestations](../how-to/verify.md#verify-ima
8282
| Scout SBOM | An SBOM generated and signed by Docker Scout, including additional Docker-specific metadata. |
8383
| Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys. |
8484
| Tests | A record of automated tests run against the image, such as functional checks or validation scripts. |
85-
| Virus scan | Results of antivirus scans performed on the image layers. |
85+
| Virus scan | Results of antivirus scans performed on the image layers. For details, see [Malware scanning](../explore/malware-scanning.md). |
8686
| CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data. |
8787
| SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the image was built, including build tool, parameters, and source. |
8888
| SLSA verification summary | A summary attestation indicating the image's compliance with SLSA requirements. |
@@ -130,7 +130,7 @@ For more details, see [Verify Helm chart attestations](../how-to/verify.md#verif
130130
| Scout SBOM | An SBOM generated and signed by Docker Scout, including the chart and container images it references, with additional Docker-specific metadata. |
131131
| Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys, in the chart package. |
132132
| Tests | A record of automated tests run against the chart to validate functionality and compatibility with referenced images. |
133-
| Virus scan | Results of antivirus scans performed on the chart package. |
133+
| Virus scan | Results of antivirus scans performed on the chart package. For details, see [Malware scanning](../explore/malware-scanning.md). |
134134
| CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data for the chart's referenced images. |
135135
| SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the chart was built, including build tool, source repository, referenced images, and build materials. |
136136
| SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, listing the chart and all container images and tools it references. |

‎content/manuals/dhi/explore/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@ params:
2525
description: See how Docker Hardened Images are automatically tested for standards compliance, functionality, and security.
2626
icon: science
2727
link: /dhi/explore/test/
28+
- title: Malware scanning
29+
description: Learn how Docker scans Docker Hardened Images for viruses and malware, and how to view and verify the scan attestation.
30+
icon: bug_report
31+
link: /dhi/explore/malware-scanning/
2832
- title: Responsibility overview
2933
description: Understand Docker's role and your responsibilities when using Docker Hardened Images as part of your secure software supply chain.
3034
icon: group

‎content/manuals/dhi/explore/build-process.md‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -118,8 +118,10 @@ Each Docker Hardened Image is built through an automated pipeline:
118118
projects, improving the code for the entire community. When fixes are accepted
119119
upstream, the DHI build pipeline applies the patch immediately to protect
120120
customers while the fix moves through the upstream release process.
121-
5. Testing: Images undergo comprehensive testing for compatibility and
122-
functionality.
121+
5. Testing and scanning: Images undergo comprehensive
122+
[testing](test.md) for compatibility and functionality, and are
123+
[scanned for malware](malware-scanning.md), secrets, and
124+
vulnerabilities.
123125
6. Signing and attestations: Docker signs each image and generates
124126
attestations (SBOMs, VEX documents, build provenance).
125127
7. Publishing: The signed image is published to the DHI registry and the
@@ -144,8 +146,8 @@ The following diagram shows the base image build flow:
144146
|
145147
v
146148
.-------------------. .-------------------. .-------------------. .-------------------.
147-
| Cascade rebuilds |<-----| Publish to |<-----| Sign & generate |<-----| Testing |
148-
| (if needed) | | DHI registry | | attestations | | |
149+
| Cascade rebuilds |<-----| Publish to |<-----| Sign & generate |<-----| Testing & |
150+
| (if needed) | | DHI registry | | attestations | | scanning |
149151
'-------------------' '-------------------' '-------------------' '-------------------'
150152
```
151153

@@ -160,9 +162,11 @@ When you customize a DHI image with DHI Select or DHI Enterprise, the build proc
160162
DHI image is updated, an automated rebuild starts.
161163
3. Fetch base image: The latest base DHI image is fetched.
162164
4. Apply customizations: Your OCI artifacts are applied to the base image.
163-
5. Signing and attestations: Docker signs the customized image and generates
165+
5. Scanning: The customized image is [scanned for
166+
malware](malware-scanning.md), secrets, and vulnerabilities.
167+
6. Signing and attestations: Docker signs the customized image and generates
164168
attestations (SBOMs, VEX documents, build provenance).
165-
6. Publishing: The signed customized image is published to Docker Hub and the
169+
7. Publishing: The signed customized image is published to Docker Hub and the
166170
attestations are published to the Docker Scout registry.
167171

168172
Docker handles the entire process automatically, so you don't need to manage
@@ -172,14 +176,14 @@ customized images and managing any CVEs introduced by your OCI artifacts.
172176
The following diagram shows the customized image build flow:
173177

174178
```goat {class="text-sm"}
175-
.-------------------. .-------------------. .-------------------.
176-
| Docker monitors |----->| Trigger rebuild |----->| Fetch base |
177-
| OCI artifacts | | | | DHI image |
178-
'-------------------' '-------------------' '-------------------'
179-
|
180-
v
181-
.-------------------. .-------------------. .-------------------.
182-
| Publish to |<-----| Sign & generate |<-----| Apply |
183-
| Docker Hub | | attestations | | customizations |
184-
'-------------------' '-------------------' '-------------------'
179+
.-------------------. .-------------------. .-------------------. .-------------------.
180+
| Docker monitors |----->| Trigger rebuild |----->| Fetch base |----->| Apply |
181+
| OCI artifacts | | | | DHI image | | customizations |
182+
'-------------------' '-------------------' '-------------------' '-------------------'
183+
|
184+
v
185+
.-------------------. .-------------------. .-------------------.
186+
| Publish to |<-----| Sign & generate |<-----| Scanning |
187+
| Docker Hub | | attestations | | |
188+
'-------------------' '-------------------' '-------------------'
185189
```

‎content/manuals/dhi/explore/feedback.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Give feedback
33
linkTitle: Feedback
44
description: How to interact with the DHI team
55
keywords: software supply chain security, feedback, bugs, discussion, questions
6-
weight: 50
6+
weight: 999
77
aliases:
88
- /dhi/about/feedback/
99
---

‎content/manuals/dhi/explore/malware-scanning.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: Malware scanning
3+
description: Learn how Docker scans Docker Hardened Images for viruses and malware using ClamAV, and how to view and verify the scan attestation.
4+
keywords: docker hardened images, malware scanning, virus scan, clamav, attestation, image security
5+
weight: 50
6+
---
7+
8+
The Docker Hardened Image (DHI) pipeline scans for viruses and malware as part
9+
of the build process. The scan results are embedded as a signed attestation,
10+
which you can independently retrieve and verify.
11+
12+
## How it works
13+
14+
Docker uses [ClamAV](https://www.clamav.net/), an open source antivirus engine,
15+
to scan every layer of each image. The scan runs automatically during the build
16+
process and checks all files in the image, including files inside archives, for
17+
known viruses and malware signatures.
18+
19+
The scan results are published as a signed attestation attached to the image.
20+
The attestation includes the full ClamAV scan report, including the number of
21+
files scanned, the virus signature database version, and whether any infected
22+
files were detected.
23+
24+
## View the malware scan attestation
25+
26+
You can retrieve the malware scan attestation using the Docker Scout CLI.
27+
28+
1. Use the `docker scout attest get` command with the virus scan predicate type:
29+
30+
```console
31+
$ docker scout attest get \
32+
--predicate-type https://scout.docker.com/virus/v0.1 \
33+
--predicate \
34+
dhi.io/<image>:<tag>
35+
```
36+
37+
> [!NOTE]
38+
>
39+
> If the image exists locally on your device, you must prefix the image name
40+
> with `registry://`. For example, use `registry://dhi.io/python` instead of
41+
> `dhi.io/python`.
42+
43+
For example:
44+
45+
```console
46+
$ docker scout attest get \
47+
--predicate-type https://scout.docker.com/virus/v0.1 \
48+
--predicate \
49+
dhi.io/python:3.13
50+
```
51+
52+
The output is a JSON object containing the scanner used and the base64-encoded
53+
scan report:
54+
55+
```json
56+
{
57+
"scanner": {
58+
"report": "<base64-encoded ClamAV report>",
59+
"uri": "clamav/clamav:stable"
60+
}
61+
}
62+
```
63+
64+
Decoding the report shows the full ClamAV output, ending with a scan summary:
65+
66+
```text
67+
----------- SCAN SUMMARY -----------
68+
Known viruses: 3627833
69+
Engine version: 1.5.2
70+
Scanned directories: 4
71+
Scanned files: 21
72+
Infected files: 0
73+
Data scanned: 44.90 MiB
74+
Data read: 23.88 MiB (ratio 1.88:1)
75+
Time: 11.473 sec (0 m 11 s)
76+
Start Date: 2026:04:12 02:36:19
77+
End Date: 2026:04:12 02:36:30
78+
```
79+
80+
2. Verify the attestation signature. To ensure the attestation is authentic and
81+
signed by Docker, run:
82+
83+
```console
84+
$ docker scout attest get \
85+
--predicate-type https://scout.docker.com/virus/v0.1 \
86+
--verify \
87+
dhi.io/<image>:<tag> --platform <platform>
88+
```
89+
90+
If the attestation is valid, Docker Scout confirms the signature and shows
91+
the matching `cosign verify` command.
92+
93+
To view other attestations, such as SBOMs or test results, see [Verify
94+
an image](../how-to/verify.md).

0 commit comments

Comments
 (0)