Skip to content

Commit f4ca0d8

Browse files
oejoej
authored
Merge pull request #137 from ppkarwasz/feat/clarify-collection
Clarify TEA Collection fields
2 parents 61b9cf9 + ef546d4 commit f4ca0d8

File tree

2 files changed

+155
-51
lines changed

2 files changed

+155
-51
lines changed

‎spec/openapi.yaml‎

Lines changed: 54 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -366,24 +366,66 @@ components:
366366
description: A collection of security-related documents
367367
properties:
368368
uuid:
369+
description: |
370+
UUID of the TEA Collection object.
371+
Note that this is equal to the UUID of the associated TEA Component Release object.
372+
When updating a collection, only the `version` is changed.
369373
"$ref": "#/components/schemas/uuid"
370-
description: Must match the UUID of the corresponding `release` object
371374
version:
372375
type: integer
373-
description: Collection version, incremented each time its content changes.
376+
description: |
377+
TEA Collection version, incremented each time its content changes.
378+
Versions start with 1.
374379
release_date:
380+
description: TEA Collection version release date.
375381
"$ref": "#/components/schemas/date-time"
376382
update_reason:
383+
description: Reason for the update/release of the TEA Collection object.
377384
"$ref": "#/components/schemas/collection-update-reason"
378385
artifacts:
379386
type: array
387+
description: List of TEA artifact objects.
380388
items:
381389
"$ref": "#/components/schemas/artifact"
390+
examples:
391+
# Documents in the latest release of Log4j Core
392+
- uuid: 4c72fe22-9d83-4c2f-8eba-d6db484f32c8
393+
version: 1
394+
release_date: 2024-12-13T00:00:00Z
395+
update_reason:
396+
type: ARTIFACT_UPDATED
397+
comment: VDR file updated
398+
artifacts:
399+
- uuid: 1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce
400+
name: Build SBOM
401+
type: bom
402+
formats:
403+
- mime_type: application/vnd.cyclonedx+xml
404+
description: CycloneDX SBOM (XML)
405+
url: https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml
406+
signature_url: https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml.asc
407+
checksums:
408+
- algType: MD5
409+
algValue: 2e1a525afc81b0a8ecff114b8b743de9
410+
- algType: SHA-1
411+
algValue: 5a7d4caef63c5c5ccdf07c39337323529eb5a770
412+
- uuid: dfa35519-9734-4259-bba1-3e825cf4be06
413+
name: Vulnerability Disclosure Report
414+
type: vulnerability-assertion
415+
formats:
416+
- mime_type: application/vnd.cyclonedx+xml
417+
description: CycloneDX VDR (XML)
418+
url: https://logging.apache.org/cyclonedx/vdr.xml
419+
checksums:
420+
- algType: SHA-256
421+
algValue: 75b81020b3917cb682b1a7605ade431e062f7a4c01a412f0b87543b6e995ad2a
422+
382423
collection-update-reason:
383424
type: object
384425
description: Reason for the update to the TEA collection
385426
properties:
386427
type:
428+
description: Type of update reason.
387429
"$ref": "#/components/schemas/collection-update-reason-type"
388430
comment:
389431
type: string
@@ -406,16 +448,22 @@ components:
406448
description: A security-related document
407449
properties:
408450
uuid:
451+
description: UUID of the TEA Artifact object.
409452
"$ref": "#/components/schemas/uuid"
410453
name:
411454
type: string
412455
description: Artifact name
413456
author:
457+
description: Author of the TEA Artifact object
414458
"$ref": "#/components/schemas/artifact-author"
415459
type:
460+
description: Type of artifact
416461
"$ref": "#/components/schemas/artifact-type"
417462
formats:
418463
type: array
464+
description: |
465+
List of objects with the same content, but in different formats.
466+
The order of the list has no significance.
419467
items:
420468
"$ref": "#/components/schemas/artifact-format"
421469
artifact-author:
@@ -483,19 +531,19 @@ components:
483531
type: object
484532
description: A security-related document in a specific format
485533
properties:
486-
mimeType:
534+
mime_type:
487535
type: string
488536
description: The MIME type of the document
489537
description:
490538
type: string
491539
description: A free text describing the artifact
492540
url:
493541
type: string
494-
description: A download URL for the artifact
542+
description: Direct download URL for the artifact
495543
format: url
496544
signature_url:
497545
type: string
498-
description: A download URL for an external signature of the artifact
546+
description: Direct download URL for an external signature of the artifact
499547
format: url
500548
checksums:
501549
type: array
@@ -506,6 +554,7 @@ components:
506554
type: object
507555
properties:
508556
algType:
557+
description: Checksum algorithm
509558
"$ref": "#/components/schemas/artifact-checksum-type"
510559
algValue:
511560
type: string

‎tea-collection/tea-collection.md‎

Lines changed: 101 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -50,56 +50,111 @@ to implement this:
5050

5151
### Collection object
5252

53-
The TEA Collection object has the following parts
54-
55-
* Preamble
56-
* UUID of the TEA collection release object (TCO). Note that this
57-
is the same UUID as the release object for this version. When updating
58-
a collection, the version is changed.
59-
* Product Release date (timestamp)
60-
* Collection version release date (timestamp)
61-
* _Version_ of this collection object. Starting with 1.
62-
* Reason for update/release of TCO
63-
* ENUM reason
64-
See below
65-
* clear text description of change
66-
* "New product release"
67-
* "Corrected dependency in SBOM that was faulty"
68-
* "Added missing In-Toto build attestation"
69-
* List of artifact objects (see below)
70-
* Optional Signature of the collection object
71-
72-
The artifact object has the following parts
73-
74-
* Artifact UUID
75-
* Artifact name
76-
* Author of the artifact object
77-
* Name
78-
* Email
79-
* Organisation
80-
* List of objects with the same content, but in different formats.
53+
The TEA Collection object has the following parts:
54+
55+
- Preamble
56+
- __uuid__: UUID of the TEA Collection object.
57+
Note that this is equal to the UUID of the associated TEA Component Release object.
58+
When updating a collection, only the `version` is changed.
59+
- __version__: TEA Collection version, incremented each time its content changes.
60+
Versions start with 1.
61+
- __release_date__: TEA Collection version release date.
62+
- __update_reason__: Reason for the update/release of the TEA Collection object.
63+
- __type__: Type of update reason.
64+
See [reasons for TEA Collection update](#the-reason-for-tco-update-enum) below.
65+
- __comment__: Free text description.
66+
- __artifacts__: List of TEA artifact objects.
67+
See [below](#artifact-object).
68+
69+
### Artifact object
70+
71+
The TEA Artifact object has the following parts:
72+
73+
- __uuid__: UUID of the TEA Artifact object.
74+
- __name__: Artifact name.
75+
- __author__: Author of the TEA Artifact object:
76+
- __name__: The name of the author.
77+
- __email__: The e-mail address of the author.
78+
- __organization__: Organization
79+
- __type__: Type of artifact.
80+
See [TEA Artifact types](../tea-artifact/tea-artifact.md) for a list.
81+
- __formats__: List of objects with the same content, but in different formats.
8182
The order of the list has no significance.
82-
* UUID for subdoc
83-
* Optional BOM identifier
84-
* SPDX or CycloneDX reference to BOM
85-
* MIME media type
86-
* Artifact category (enum)
87-
* <https://cyclonedx.org/docs/1.6/json/#externalReferences_items_type>
88-
* Description in clear text
89-
* Direct URL for downloads of artefact
90-
* Direct URL for download of external signature
91-
* Size in bytes
92-
* SHA384 checksum
83+
- __mime_type__: The MIME type of the document
84+
- __description__: A free text describing the artifact
85+
- __url__: Direct download URL for the artifact
86+
- __signature_url__: Direct download URL for an external signature of the artifact
87+
- __checksums__: List of checksums for the artifact
88+
- __algType__: Checksum algorithm
89+
See [CycloneDX checksum algorithms](https://cyclonedx.org/docs/1.6/json/#components_items_hashes_items_alg) for a list of supported values.
90+
- __algValue__: Checksum value
9391

9492
### The reason for TCO update enum
9593

96-
| ENUM | Explanation |
97-
|-------------|--------------------------------|
98-
| INITIAL_RELEASE | Initial release of the collection |
99-
| VEX_UPDATED | Updated the VEX artifact(s) |
100-
| ARTIFACT_UPDATED | Updated the artifact(s) other than VEX |
101-
| ARTIFACT_REMOVED | Removal of artifact |
102-
| ARTIFACT_ADDED | Addition of an artifact |
94+
| ENUM | Explanation |
95+
|------------------|----------------------------------------|
96+
| INITIAL_RELEASE | Initial release of the collection |
97+
| VEX_UPDATED | Updated the VEX artifact(s) |
98+
| ARTIFACT_UPDATED | Updated the artifact(s) other than VEX |
99+
| ARTIFACT_REMOVED | Removal of artifact |
100+
| ARTIFACT_ADDED | Addition of an artifact |
103101

104102
Updates of VEX (CSAF) files may be handled in a different way by a TEA client,
105103
producing different alerts than other changes of a collection.
104+
105+
### Examples
106+
107+
```json
108+
{
109+
"uuid": "4c72fe22-9d83-4c2f-8eba-d6db484f32c8",
110+
"version": 1,
111+
"release_date": "2024-12-13T00:00:00Z",
112+
"update_reason": {
113+
"type": "ARTIFACT_UPDATED",
114+
"comment": "VDR file updated"
115+
},
116+
"artifacts": [
117+
{
118+
"uuid": "1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce",
119+
"name": "Build SBOM",
120+
"type": "bom",
121+
"formats": [
122+
{
123+
"mime_type": "application/vnd.cyclonedx+xml",
124+
"description": "CycloneDX SBOM (XML)",
125+
"url": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml",
126+
"signature_url": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml.asc",
127+
"checksums": [
128+
{
129+
"algType": "MD5",
130+
"algValue": "2e1a525afc81b0a8ecff114b8b743de9"
131+
},
132+
{
133+
"algType": "SHA-1",
134+
"algValue": "5a7d4caef63c5c5ccdf07c39337323529eb5a770"
135+
}
136+
]
137+
}
138+
]
139+
},
140+
{
141+
"uuid": "dfa35519-9734-4259-bba1-3e825cf4be06",
142+
"name": "Vulnerability Disclosure Report",
143+
"type": "vulnerability-assertion",
144+
"formats": [
145+
{
146+
"mime_type": "application/vnd.cyclonedx+xml",
147+
"description": "CycloneDX VDR (XML)",
148+
"url": "https://logging.apache.org/cyclonedx/vdr.xml",
149+
"checksums": [
150+
{
151+
"algType": "SHA-256",
152+
"algValue": "75b81020b3917cb682b1a7605ade431e062f7a4c01a412f0b87543b6e995ad2a"
153+
}
154+
]
155+
}
156+
]
157+
}
158+
]
159+
}
160+
```

0 commit comments

Comments
 (0)