1# Cosign Vulnerability Scan Record Attestation Specification
2
3`Cosign` is heavily using [In-toto Attestations](https://github.com/in-toto/attestation) predicate models in its own
4codebase. But this is not the only option you have while working with predicates in cosign. `Cosign` already defines its
5own predicates: [Generic Predicate Specification](COSIGN_PREDICATE_SPEC.md). This `Vulnerability Scan`
6attestation is one of them.
7
8Let's talk a bit about the history of this specification. We first mentioned this idea
9in [in-toto attestation](https://github.com/in-toto/attestation/issues/58) repository. So many people interested in this
10issue, and shared ideas about which parts are necessary which parts are not to make that specification well-purposed.
11There is an also cross [issue](https://github.com/sigstore/cosign/issues/442) on cosign side that we discussed on it.
12
13And the final format for this is defined as follows:
14
15```json
16{
17 "_type": "https://in-toto.io/Statement/v0.1",
18 "subject": [
19 {
20 ...
21 }
22 ],
23 // Predicate:
24 "predicateType": "https://cosign.sigstore.dev/attestation/vuln/v1",
25 "predicate": {
26 "invocation": {
27 "parameters": [],
28 // [ "--format=json", "--skip-db-update" ]
29 "uri": "",
30 // https://github.com/developer-guy/alpine/actions/runs/1071875574
31 "event_id": "",
32 // 1071875574
33 "builder.id": ""
34 // GitHub Actions
35 },
36 "scanner": {
37 "uri": "",
38 // pkg:github/aquasecurity/trivy@244fd47e07d1004f0aed9
39 "version": "",
40 // 0.19.2
41 "db": {
42 "uri": "",
43 // pkg:github/aquasecurity/trivy-db/commit/4c76bb580b2736d67751410fa4ab66d2b6b9b27d
44 "version": ""
45 // "v1-2021080612"
46 },
47 "result": {}
48 },
49 "metadata": {
50 "scanStartedOn": "",
51 // 2021-08-06T17:45:50.52Z
52 "scanFinishedOn": ""
53 // 2021-08-06T17:50:50.52Z
54 }
55 }
56}
57```
58
59## Fields
60
61**scanner**
62
63> There are lots of container image scanners such as Trivy, Grype, Clair, etc.
64> This field describes which scanner is used while performing a container image scan,
65> as well as version information and which Vulnerability DB is used.
66
67**scanner.uri** string (ResourceURI), optional
68
69> > URI indicating the identity of the source of the scanner.
70
71**scanner.version** string (ResourceURI), optional
72
73> The version of the scanner.
74
75**scanner.db.uri** string (ResourceURI), optional
76
77> URI indicating the identity of the source of the Vulnerability DB.
78
79**scanner.db.version** string, optional
80
81> The version of the Vulnerability DB.
82
83**scanner.result** object
84
85> This is the most important part of this field because it'll store the scan result as a whole. So, people might want
86> to use this field to take decisions based on them by making use of Policy Engines tooling whether allow or deny these images.
87
88**metadata.scanStartedOn string (Timestamp), required**
89
90> The timestamp of when the scan started.
91
92**metadata.scanFinishedOn string (Timestamp), required**
93
94> The timestamp of when the scan completed.
95
96```shell
97$ trivy image -f json alpine:3.12
98```
99
100<details>
101
102<summary>Scan Result</summary>
103
104```json
105{
106 "SchemaVersion": 2,
107 "ArtifactName": "alpine:3.12",
108 "ArtifactType": "container_image",
109 "Metadata": {
110 "OS": {
111 "Family": "alpine",
112 "Name": "3.12.9"
113 },
114 "ImageID": "sha256:b0925e0819214cd29937af66dbaf0e6fe239997faea60922cc890f9984512507",
115 "DiffIDs": [
116 "sha256:eb4bde6b29a6746e0779f80a09ca6f0806de61475059f7d56d6e20f6cc2e15f7"
117 ],
118 "RepoTags": [
119 "alpine:3.12"
120 ],
121 "RepoDigests": [
122 "alpine@sha256:d9459083f962de6bd980ae6a05be2a4cf670df6a1d898157bceb420342bec280"
123 ],
124 "ImageConfig": {
125 "architecture": "amd64",
126 "container": "385e1cc96cc7482dfb6847e293bb24baecd3f48a49791b9b45e297204b160287",
127 "created": "2021-11-12T17:20:08.442217528Z",
128 "docker_version": "20.10.7",
129 "history": [
130 {
131 "created": "2021-11-12T17:20:08.190319702Z",
132 "created_by": "/bin/sh -c #(nop) ADD file:8f5bc5ce64ef781adadca88e4004e17affc72e6f20dbd08b9c478def12fe1dd3 in / "
133 },
134 {
135 "created": "2021-11-12T17:20:08.442217528Z",
136 "created_by": "/bin/sh -c #(nop) CMD [\"/bin/sh\"]",
137 "empty_layer": true
138 }
139 ],
140 "os": "linux",
141 "rootfs": {
142 "type": "layers",
143 "diff_ids": [
144 "sha256:eb4bde6b29a6746e0779f80a09ca6f0806de61475059f7d56d6e20f6cc2e15f7"
145 ]
146 },
147 "config": {
148 "Cmd": [
149 "/bin/sh"
150 ],
151 "Env": [
152 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
153 ],
154 "Image": "sha256:7d1c1e4b291dc9519b43a2b9c9330655927f6dfde90d36ef5fd16b2ae0f28bbc"
155 }
156 }
157 },
158 "Results": [
159 {
160 "Target": "alpine:3.12 (alpine 3.12.9)",
161 "Class": "os-pkgs",
162 "Type": "alpine",
163 "Vulnerabilities": [
164 {
165 "VulnerabilityID": "CVE-2021-28831",
166 "PkgName": "busybox",
167 "InstalledVersion": "1.31.1-r21",
168 "FixedVersion": "1.32.1-r4",
169 "Layer": {
170 "Digest": "sha256:8572bc8fb8a32061648dd183b2c0451c82be1bd053a4ea8fae991436b92faebb",
171 "DiffID": "sha256:eb4bde6b29a6746e0779f80a09ca6f0806de61475059f7d56d6e20f6cc2e15f7"
172 },
173 "SeveritySource": "nvd",
174 "PrimaryURL": "https://avd.aquasec.com/nvd/cve-2021-28831",
175 "Title": "busybox: invalid free or segmentation fault via malformed gzip data",
176 "Description": "decompress_gunzip.c in BusyBox through 1.32.1 mishandles the error bit on the huft_build result pointer, with a resultant invalid free or segmentation fault, via malformed gzip data.",
177 "Severity": "HIGH",
178 "CweIDs": [
179 "CWE-755"
180 ],
181 "CVSS": {
182 "nvd": {
183 "V2Vector": "AV:N/AC:L/Au:N/C:N/I:N/A:P",
184 "V3Vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
185 "V2Score": 5,
186 "V3Score": 7.5
187 },
188 "redhat": {
189 "V3Vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
190 "V3Score": 7.5
191 }
192 },
193 "References": [
194 "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-28831",
195 "https://git.busybox.net/busybox/commit/?id=f25d254dfd4243698c31a4f3153d4ac72aa9e9bd",
196 "https://lists.debian.org/debian-lts-announce/2021/04/msg00001.html",
197 "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/3UDQGJRECXFS5EZVDH2OI45FMO436AC4/",
198 "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/Z7ZIFKPRR32ZYA3WAA2NXFA3QHHOU6FJ/",
199 "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/ZASBW7QRRLY5V2R44MQ4QQM4CZIDHM2U/",
200 "https://security.gentoo.org/glsa/202105-09",
201 "https://ubuntu.com/security/notices/USN-5179-1"
202 ],
203 "PublishedDate": "2021-03-19T05:15:00Z",
204 "LastModifiedDate": "2021-05-26T10:15:00Z"
205 },
206 {
207 "VulnerabilityID": "CVE-2021-28831",
208 "PkgName": "ssl_client",
209 "InstalledVersion": "1.31.1-r21",
210 "FixedVersion": "1.32.1-r4",
211 "Layer": {
212 "Digest": "sha256:8572bc8fb8a32061648dd183b2c0451c82be1bd053a4ea8fae991436b92faebb",
213 "DiffID": "sha256:eb4bde6b29a6746e0779f80a09ca6f0806de61475059f7d56d6e20f6cc2e15f7"
214 },
215 "SeveritySource": "nvd",
216 "PrimaryURL": "https://avd.aquasec.com/nvd/cve-2021-28831",
217 "Title": "busybox: invalid free or segmentation fault via malformed gzip data",
218 "Description": "decompress_gunzip.c in BusyBox through 1.32.1 mishandles the error bit on the huft_build result pointer, with a resultant invalid free or segmentation fault, via malformed gzip data.",
219 "Severity": "HIGH",
220 "CweIDs": [
221 "CWE-755"
222 ],
223 "CVSS": {
224 "nvd": {
225 "V2Vector": "AV:N/AC:L/Au:N/C:N/I:N/A:P",
226 "V3Vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
227 "V2Score": 5,
228 "V3Score": 7.5
229 },
230 "redhat": {
231 "V3Vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
232 "V3Score": 7.5
233 }
234 },
235 "References": [
236 "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-28831",
237 "https://git.busybox.net/busybox/commit/?id=f25d254dfd4243698c31a4f3153d4ac72aa9e9bd",
238 "https://lists.debian.org/debian-lts-announce/2021/04/msg00001.html",
239 "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/3UDQGJRECXFS5EZVDH2OI45FMO436AC4/",
240 "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/Z7ZIFKPRR32ZYA3WAA2NXFA3QHHOU6FJ/",
241 "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/ZASBW7QRRLY5V2R44MQ4QQM4CZIDHM2U/",
242 "https://security.gentoo.org/glsa/202105-09",
243 "https://ubuntu.com/security/notices/USN-5179-1"
244 ],
245 "PublishedDate": "2021-03-19T05:15:00Z",
246 "LastModifiedDate": "2021-05-26T10:15:00Z"
247 }
248 ]
249 }
250 ]
251}
252```
253
254</details>
255
256Here is an example predicate containing a vulnerability scan result above:
257
258```json
259{
260 "predicate": {
261 "invocation": {
262 "parameters": [
263 "--format=json"
264 ],
265 "uri": "https://github.com/developer-guy/alpine/actions/runs/1071875574",
266 "event_id": "1071875574",
267 "builder.id": "github actions"
268 },
269 "scanner": {
270 "uri": "pkg:github/aquasecurity/trivy@244fd47e07d1004f0aed9",
271 "version": "0.19.2",
272 "db": {
273 "uri": "pkg:github/aquasecurity/trivy-db/commit/4c76bb580b2736d67751410fa4ab66d2b6b9b27d",
274 "version": "v1-2021080612"
275 },
276 "result": {
277 "SchemaVersion": 2,
278 "ArtifactName": "alpine:3.12",
279 "ArtifactType": "container_image",
280 "Metadata": {
281 "OS": {
282 "Family": "alpine",
283 "Name": "3.12.9"
284 },
285 "ImageID": "sha256:b0925e0819214cd29937af66dbaf0e6fe239997faea60922cc890f9984512507",
286 "DiffIDs": [
287 "sha256:eb4bde6b29a6746e0779f80a09ca6f0806de61475059f7d56d6e20f6cc2e15f7"
288 ],
289 "RepoTags": [
290 "alpine:3.12"
291 ],
292 "RepoDigests": [
293 "alpine@sha256:d9459083f962de6bd980ae6a05be2a4cf670df6a1d898157bceb420342bec280"
294 ],
295 "ImageConfig": {
296 "architecture": "amd64",
297 "container": "385e1cc96cc7482dfb6847e293bb24baecd3f48a49791b9b45e297204b160287",
298 "created": "2021-11-12T17:20:08.442217528Z",
299 "docker_version": "20.10.7",
300 "history": [
301 {
302 "created": "2021-11-12T17:20:08.190319702Z",
303 "created_by": "/bin/sh -c #(nop) ADD file:8f5bc5ce64ef781adadca88e4004e17affc72e6f20dbd08b9c478def12fe1dd3 in / "
304 },
305 {
306 "created": "2021-11-12T17:20:08.442217528Z",
307 "created_by": "/bin/sh -c #(nop) CMD [\"/bin/sh\"]",
308 "empty_layer": true
309 }
310 ],
311 "os": "linux",
312 "rootfs": {
313 "type": "layers",
314 "diff_ids": [
315 "sha256:eb4bde6b29a6746e0779f80a09ca6f0806de61475059f7d56d6e20f6cc2e15f7"
316 ]
317 },
318 "config": {
319 "Cmd": [
320 "/bin/sh"
321 ],
322 "Env": [
323 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
324 ],
325 "Image": "sha256:7d1c1e4b291dc9519b43a2b9c9330655927f6dfde90d36ef5fd16b2ae0f28bbc"
326 }
327 }
328 },
329 "Results": [
330 {
331 "Target": "alpine:3.12 (alpine 3.12.9)",
332 "Class": "os-pkgs",
333 "Type": "alpine",
334 "Vulnerabilities": [
335 {
336 "VulnerabilityID": "CVE-2021-28831",
337 "PkgName": "busybox",
338 "InstalledVersion": "1.31.1-r21",
339 "FixedVersion": "1.32.1-r4",
340 "Layer": {
341 "Digest": "sha256:8572bc8fb8a32061648dd183b2c0451c82be1bd053a4ea8fae991436b92faebb",
342 "DiffID": "sha256:eb4bde6b29a6746e0779f80a09ca6f0806de61475059f7d56d6e20f6cc2e15f7"
343 },
344 "SeveritySource": "nvd",
345 "PrimaryURL": "https://avd.aquasec.com/nvd/cve-2021-28831",
346 "Title": "busybox: invalid free or segmentation fault via malformed gzip data",
347 "Description": "decompress_gunzip.c in BusyBox through 1.32.1 mishandles the error bit on the huft_build result pointer, with a resultant invalid free or segmentation fault, via malformed gzip data.",
348 "Severity": "HIGH",
349 "CweIDs": [
350 "CWE-755"
351 ],
352 "CVSS": {
353 "nvd": {
354 "V2Vector": "AV:N/AC:L/Au:N/C:N/I:N/A:P",
355 "V3Vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
356 "V2Score": 5,
357 "V3Score": 7.5
358 },
359 "redhat": {
360 "V3Vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
361 "V3Score": 7.5
362 }
363 },
364 "References": [
365 "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-28831",
366 "https://git.busybox.net/busybox/commit/?id=f25d254dfd4243698c31a4f3153d4ac72aa9e9bd",
367 "https://lists.debian.org/debian-lts-announce/2021/04/msg00001.html",
368 "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/3UDQGJRECXFS5EZVDH2OI45FMO436AC4/",
369 "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/Z7ZIFKPRR32ZYA3WAA2NXFA3QHHOU6FJ/",
370 "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/ZASBW7QRRLY5V2R44MQ4QQM4CZIDHM2U/",
371 "https://security.gentoo.org/glsa/202105-09",
372 "https://ubuntu.com/security/notices/USN-5179-1"
373 ],
374 "PublishedDate": "2021-03-19T05:15:00Z",
375 "LastModifiedDate": "2021-05-26T10:15:00Z"
376 },
377 {
378 "VulnerabilityID": "CVE-2021-28831",
379 "PkgName": "ssl_client",
380 "InstalledVersion": "1.31.1-r21",
381 "FixedVersion": "1.32.1-r4",
382 "Layer": {
383 "Digest": "sha256:8572bc8fb8a32061648dd183b2c0451c82be1bd053a4ea8fae991436b92faebb",
384 "DiffID": "sha256:eb4bde6b29a6746e0779f80a09ca6f0806de61475059f7d56d6e20f6cc2e15f7"
385 },
386 "SeveritySource": "nvd",
387 "PrimaryURL": "https://avd.aquasec.com/nvd/cve-2021-28831",
388 "Title": "busybox: invalid free or segmentation fault via malformed gzip data",
389 "Description": "decompress_gunzip.c in BusyBox through 1.32.1 mishandles the error bit on the huft_build result pointer, with a resultant invalid free or segmentation fault, via malformed gzip data.",
390 "Severity": "HIGH",
391 "CweIDs": [
392 "CWE-755"
393 ],
394 "CVSS": {
395 "nvd": {
396 "V2Vector": "AV:N/AC:L/Au:N/C:N/I:N/A:P",
397 "V3Vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
398 "V2Score": 5,
399 "V3Score": 7.5
400 },
401 "redhat": {
402 "V3Vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
403 "V3Score": 7.5
404 }
405 },
406 "References": [
407 "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-28831",
408 "https://git.busybox.net/busybox/commit/?id=f25d254dfd4243698c31a4f3153d4ac72aa9e9bd",
409 "https://lists.debian.org/debian-lts-announce/2021/04/msg00001.html",
410 "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/3UDQGJRECXFS5EZVDH2OI45FMO436AC4/",
411 "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/Z7ZIFKPRR32ZYA3WAA2NXFA3QHHOU6FJ/",
412 "https://lists.fedoraproject.org/archives/list/package-announce@lists.fedoraproject.org/message/ZASBW7QRRLY5V2R44MQ4QQM4CZIDHM2U/",
413 "https://security.gentoo.org/glsa/202105-09",
414 "https://ubuntu.com/security/notices/USN-5179-1"
415 ],
416 "PublishedDate": "2021-03-19T05:15:00Z",
417 "LastModifiedDate": "2021-05-26T10:15:00Z"
418 }
419 ]
420 }
421 ]
422 }
423 },
424 "metadata": {
425 "scanStartedOn": "2021-08-06T17:45:50.52Z",
426 "scanFinishedOn": "2021-08-06T17:50:50.52Z"
427 }
428 }
429}
430```
431
View as plain text