diff --git a/api-flow/publisher.md b/api-flow/publisher.md index 172d133..c52cc0c 100644 --- a/api-flow/publisher.md +++ b/api-flow/publisher.md @@ -19,7 +19,7 @@ sequenceDiagram Vendor ->> tea_component: POST to /v1/component with the TEA PI and component version as the payload tea_component ->> Vendor: Component is created and a TEA Component ID is returned - Vendor ->> tea_collection: POST to /v1/collection with the TEA Component ID as the and the artifact as payload + Vendor ->> tea_collection: POST to /v1/collection with the TEA Component ID and the artefact as payload tea_collection ->> Vendor: Collection is created with the collection ID returned ``` @@ -39,13 +39,13 @@ sequenceDiagram Vendor ->> tea_component: POST to /v1/component with the TEA PI and component version as the payload tea_component ->> Vendor: Component is created and a TEA Component ID is returned - Note over Vendor,TEA Component: Add an artifact (e.g. SBOM) - Vendor ->> tea_collection: POST to /v1/collection with the TEA Component ID as the and the artifact as payload + Note over Vendor,TEA Component: Add an artefact (e.g. SBOM) + Vendor ->> tea_collection: POST to /v1/collection with the TEA Component ID and the artefact as payload tea_collection ->> Vendor: Collection is created with the collection ID returned ``` -## Adding a new artifact +## Adding a new artefact ```mermaid sequenceDiagram @@ -58,6 +58,6 @@ sequenceDiagram Vendor ->> tea_component: GET to /v1/component with the TEA PI to get the latest version tea_component ->> Vendor: Component will be returned - Vendor ->> tea_collection: POST to /v1/collection with the TEA Component ID as the and the artifact as payload + Vendor ->> tea_collection: POST to /v1/collection with the TEA Component ID and the artefact as payload tea_collection ->> Vendor: Collection is created with the collection ID returned ``` \ No newline at end of file diff --git a/archive/README.md b/archive/README.md new file mode 100644 index 0000000..30a13f1 --- /dev/null +++ b/archive/README.md @@ -0,0 +1 @@ +This directory contains archived versions of the API specification and related documentation. These files are preserved for historical reference and should not be used for current development. \ No newline at end of file diff --git a/api/bomexchangeapi.md b/archive/bomexchangeapi.md similarity index 100% rename from api/bomexchangeapi.md rename to archive/bomexchangeapi.md diff --git a/archive/legacy_consumer_spec/v0.2.0/openapi.yaml b/archive/legacy_consumer_spec/v0.2.0/openapi.yaml new file mode 100644 index 0000000..79c9a15 --- /dev/null +++ b/archive/legacy_consumer_spec/v0.2.0/openapi.yaml @@ -0,0 +1,1228 @@ +# $schema: https://spec.openapis.org/oas/3.1/schema-base/2025-02-13 +openapi: 3.1.1 +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base +info: + title: Transparency Exchange API + summary: The OWASP Transparency Exchange API specification for consumers and publishers + description: TBC + contact: + name: TEA Working Group + email: tbc@somewhere.tld + url: https://github.com/CycloneDX/transparency-exchange-api + license: + name: Apache 2.0 + url: https://github.com/CycloneDX/transparency-exchange-api/blob/main/LICENSE + version: 0.2.0-beta.2 +servers: + - url: http://localhost/tea/v1 + description: Local development +paths: + /product/{uuid}: + get: + description: Get a TEA Product by UUID + operationId: getTeaProductByUuid + parameters: + - name: uuid + in: path + required: true + description: UUID of the TEA product in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + responses: + '200': + description: Requested TEA Product found and returned + content: + application/json: + schema: + $ref: "#/components/schemas/product" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Product + /product/{uuid}/releases: + get: + description: Get releases of the product + operationId: getReleasesByProductId + parameters: + - name: uuid + in: path + required: true + description: UUID of TEA Product in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + - $ref: "#/components/parameters/page-offset" + - $ref: "#/components/parameters/page-size" + responses: + '200': + $ref: "#/components/responses/paginated-product-release" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Product Release + /productRelease/{uuid}: + get: + description: Get a TEA Product Release + operationId: getTeaProductReleaseByUuid + parameters: + - name: uuid + in: path + required: true + description: UUID of TEA Product Release in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + responses: + '200': + description: Requested TEA Product Release found and returned + content: + application/json: + schema: + "$ref": "#/components/schemas/productRelease" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Product Release + /productReleases: + get: + description: Returns a list of TEA product releases. Note that multiple product releases may match. + operationId: queryTeaProductReleases + parameters: + - $ref: "#/components/parameters/page-offset" + - $ref: "#/components/parameters/page-size" + - $ref: "#/components/parameters/id-type" + - $ref: "#/components/parameters/id-value" + responses: + '200': + $ref: "#/components/responses/paginated-product-release" + '400': + $ref: "#/components/responses/400-invalid-request" + tags: + - TEA Product Release + /products: + get: + description: Returns a list of TEA products. Note that multiple products may + match. + operationId: queryTeaProducts + parameters: + - $ref: "#/components/parameters/page-offset" + - $ref: "#/components/parameters/page-size" + - $ref: "#/components/parameters/id-type" + - $ref: "#/components/parameters/id-value" + responses: + '200': + $ref: "#/components/responses/paginated-product" + '400': + $ref: "#/components/responses/400-invalid-request" + tags: + - TEA Product + /component/{uuid}: + get: + description: Get a TEA Component + operationId: getTeaComponentById + parameters: + - name: uuid + in: path + required: true + description: UUID of TEA Component in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + responses: + '200': + description: Requested TEA Component found and returned + content: + application/json: + schema: + "$ref": "#/components/schemas/component" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Component + /component/{uuid}/releases: + get: + description: Get releases of the component + operationId: getReleasesByComponentId + parameters: + - name: uuid + in: path + required: true + description: UUID of TEA Component in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + responses: + '200': + description: Requested Releases of TEA Component found and returned + content: + application/json: + schema: + type: array + items: + "$ref": "#/components/schemas/release" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Component + /componentRelease/{uuid}: + get: + description: Get the TEA Component Release with its latest collection + operationId: getComponentReleaseById + parameters: + - name: uuid + in: path + required: true + description: UUID of TEA Component Release in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + responses: + '200': + description: Requested TEA Component Release and its latest Collection found and returned + content: + application/json: + schema: + "$ref": "#/components/schemas/component-release-with-collection" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Component Release + /componentRelease/{uuid}/collection/latest: + get: + description: Get the latest TEA Collection belonging to the TEA Component Release + operationId: getLatestCollection + parameters: + - name: uuid + in: path + required: true + description: UUID of TEA Component Release in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + responses: + '200': + description: Requested TEA Collection found and returned + content: + application/json: + schema: + "$ref": "#/components/schemas/collection" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Component Release + /productRelease/{uuid}/collection/latest: + get: + description: Get the latest TEA Collection belonging to the TEA Product Release + operationId: getLatestCollectionForProductRelease + parameters: + - name: uuid + in: path + required: true + description: UUID of TEA Product Release in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + responses: + '200': + description: Requested TEA Collection found and returned + content: + application/json: + schema: + "$ref": "#/components/schemas/collection" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Product Release + /componentRelease/{uuid}/collections: + get: + description: Get the TEA Collections belonging to the TEA Component Release + operationId: getCollectionsByReleaseId + parameters: + - name: uuid + in: path + required: true + description: UUID of TEA Component Release in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + responses: + '200': + description: Requested TEA Collection found and returned + content: + application/json: + schema: + type: array + items: + "$ref": "#/components/schemas/collection" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Component Release + /productRelease/{uuid}/collections: + get: + description: Get the TEA Collections belonging to the TEA Product Release + operationId: getCollectionsByProductReleaseId + parameters: + - name: uuid + in: path + required: true + description: UUID of TEA Product Release in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + responses: + '200': + description: Requested TEA Collection found and returned + content: + application/json: + schema: + type: array + items: + "$ref": "#/components/schemas/collection" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Product Release + /productRelease/{uuid}/collection/{collectionVersion}: + get: + description: Get a specific Collection (by version) for a TEA Product Release by its UUID + operationId: getCollectionForProductRelease + parameters: + - name: uuid + in: path + required: true + description: UUID of TEA Product Release in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + - name: collectionVersion + in: path + required: true + description: Version of TEA Collection + schema: + type: integer + responses: + '200': + description: Requested TEA Collection Version found and returned + content: + application/json: + schema: + "$ref": "#/components/schemas/collection" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Product Release + /componentRelease/{uuid}/collection/{collectionVersion}: + get: + description: Get a specific Collection (by version) for a TEA Component Release by its UUID + operationId: getCollection + parameters: + - name: uuid + in: path + required: true + description: UUID of TEA Collection in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + - name: collectionVersion + in: path + required: true + description: Version of TEA Collection + schema: + type: integer + responses: + '200': + description: Requested TEA Collection Version found and returned + content: + application/json: + schema: + "$ref": "#/components/schemas/collection" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Component Release + /artifact/{uuid}: + get: + description: Get metadata for specific TEA artifact + operationId: getArtifact + parameters: + - name: uuid + in: path + required: true + description: UUID of TEA Artifact in the TEA server + schema: + "$ref": "#/components/schemas/uuid" + responses: + '200': + description: Requested TEA Artifact metadata found and returned + content: + application/json: + schema: + "$ref": "#/components/schemas/artifact" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Artifact + /discovery: + get: + description: Discovery endpoint which resolves TEI into product release UUID. + operationId: discoveryByTei + parameters: + - name: tei + in: query + required: true + description: Transparency Exchange Identifier (TEI) for the product being discovered. Provide the TEI as a URL-encoded string per RFC 3986, RFC 3987. + schema: + type: string + example: urn%3Atei%3Auuid%3Aproducts.example.com%3Ad4d9f54a-abcf-11ee-ac79-1a52914d44b + responses: + '200': + $ref: "#/components/responses/discovery-response" + '400': + $ref: "#/components/responses/400-invalid-request" + '404': + $ref: "#/components/responses/404-object-by-id-not-found" + tags: + - TEA Discovery +components: + schemas: + # + # Definitions reused in multiple domain objects + # + date-time: + type: string + description: Timestamp + format: date-time + pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" + example: '2024-03-20T15:30:00Z' + identifier: + type: object + description: An identifier with a specified type + properties: + idType: + description: Type of identifier, e.g. `TEI`, `PURL`, `CPE` + "$ref": "#/components/schemas/identifier-type" + idValue: + description: Identifier value + type: string + identifier-type: + type: string + description: Enumeration of identifiers types + enum: + - CPE + - TEI + - PURL + uuid: + type: string + description: A UUID + format: uuid + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + + # + # TEA Product + # + product: + type: object + description: A TEA product + properties: + uuid: + description: A unique identifier for the TEA product + "$ref": "#/components/schemas/uuid" + name: + type: string + description: Product name + identifiers: + type: array + description: | + List of identifiers for the product, like TEI, CPE, PURL or other identifiers + items: + "$ref": "#/components/schemas/identifier" + required: + - uuid + - name + - identifiers + examples: + - uuid: 09e8c73b-ac45-4475-acac-33e6a7314e6d + name: Apache Log4j 2 + identifiers: + - idType: CPE + idValue: cpe:2.3:a:apache:log4j + - idType: PURL + idValue: pkg:maven/org.apache.logging.log4j/log4j-api + # + # TEA Product Release + # + productRelease: + type: object + description: A specific release of a TEA product + properties: + uuid: + description: A unique identifier for the TEA Product Release + "$ref": "#/components/schemas/uuid" + product: + description: UUID of the TEA Product this release belongs to + "$ref": "#/components/schemas/uuid" + productName: + description: Name of the TEA Product this release belongs to + type: string + example: Apache Log4j 2 + version: + description: Version number of the product release + type: string + example: 2.24.3 + createdDate: + description: Timestamp when this Product Release was created in TEA (for sorting purposes) + "$ref": "#/components/schemas/date-time" + releaseDate: + description: Timestamp of the product release + "$ref": "#/components/schemas/date-time" + preRelease: + type: boolean + description: | + A flag indicating pre-release (or beta) status. + May be disabled after the creation of the release object, but can't be enabled after creation of an object. + identifiers: + type: array + description: List of identifiers for the product release + items: + "$ref": "#/components/schemas/identifier" + components: + type: array + description: | + List of component references that compose this product release. A component reference can optionally include + the UUID of a specific component release to pin the exact version. + items: + "$ref": "#/components/schemas/component-ref" + required: + - uuid + - version + - createdDate + - components + examples: + - uuid: 123e4567-e89b-12d3-a456-426614174000 + version: "2.24.3" + createdDate: 2025-04-01T15:43:00Z + releaseDate: 2025-04-01T15:43:00Z + identifiers: + - idType: TEI + idValue: tei:vendor:product@2.24.3 + components: + - uuid: 3910e0fd-aff4-48d6-b75f-8bf6b84687f0 + - uuid: b844c9bd-55d6-478c-af59-954a932b6ad3 + release: da89e38e-95e7-44ca-aa7d-f3b6b34c7fab + + # + # TEA Component and related objects + # + component: + type: object + description: A TEA component + properties: + uuid: + description: A unique identifier for the TEA component + "$ref": "#/components/schemas/uuid" + name: + type: string + description: Component name + identifiers: + type: array + description: List of identifiers for the component + items: + "$ref": "#/components/schemas/identifier" + required: + - uuid + - name + - identifiers + examples: + - uuid: 3910e0fd-aff4-48d6-b75f-8bf6b84687f0 + name: Apache Log4j API + identifiers: + - idType: PURL + idValue: pkg:maven/org.apache.logging.log4j/log4j-api + - uuid: b844c9bd-55d6-478c-af59-954a932b6ad3 + name: Apache Log4j Core + identifiers: + - idType: CPE + idValue: cpe:2.3:a:apache:log4j + - idType: PURL + idValue: pkg:maven/org.apache.logging.log4j/log4j-core + +# + # Reference to a component, in some cases directly to a specific release + # + # The release reference (release UUID) is only used in cases where a product + # name includes a version and this version of the product always includes + # the same releases of the component. + component-ref: + type: object + description: A reference to a TEA component or specific component release + properties: + uuid: + description: A unique identifier for the TEA component + "$ref": "#/components/schemas/uuid" + release: + description: | + Optional UUID of a specific release included in the product in the case where the product + always include a specific release of a component. The product name should include a version + identifier in this case. + "$ref": "#/components/schemas/uuid" + required: + - uuid + + + + # + # TEA Component Release and related objects + # + release: + type: object + description: A TEA Component Release + properties: + uuid: + description: A unique identifier for the TEA Component Release + "$ref": "#/components/schemas/uuid" + component: + description: UUID of the TEA Component this release belongs to + "$ref": "#/components/schemas/uuid" + componentName: + description: Name of the TEA Component this release belongs to + type: string + example: tomcat + version: + description: Version number + type: string + example: 1.2.3 + createdDate: + description: Timestamp when this Release was created in TEA (for sorting purposes) + "$ref": "#/components/schemas/date-time" + releaseDate: + description: Timestamp of the release + "$ref": "#/components/schemas/date-time" + preRelease: + type: boolean + description: | + A flag indicating pre-release (or beta) status. + May be disabled after the creation of the release object, but can't be enabled after creation of an object. + identifiers: + type: array + description: List of identifiers for the component + items: + "$ref": "#/components/schemas/identifier" + distributions: + type: array + description: List of different formats of this component release + items: + "$ref": "#/components/schemas/release-distribution" + # add lifecycle here + required: + - uuid + - version + - createdDate + examples: + # Apache Tomcat 11.0.7 + - uuid: 605d0ecb-1057-40e4-9abf-c400b10f0345 + version: "11.0.7" + createdDate: 2025-05-07T18:08:00Z + releaseDate: 2025-05-12T18:08:00Z + identifiers: + - idType: PURL + idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.7 + distributions: + - distributionType: zip + description: Core binary distribution, zip archive + identifiers: + - idType: PURL + idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?type=zip + checksums: + - algType: SHA_256 + algValue: 9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1 + url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip + signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc + - distributionType: tar.gz + description: Core binary distribution, tar.gz archive + identifiers: + - idType: PURL + idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?type=tar.gz + checksums: + - algType: SHA_256 + algValue: 2fcece641c62ba1f28e1d7b257493151fc44f161fb391015ee6a95fa71632fb9 + url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.tar.gz + signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.tar.gz.asc + - distributionType: windows-x64.zip + description: Core binary distribution, Windows x64 zip archive + identifiers: + - idType: PURL + idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?classifier=windows-x64&type=zip + checksums: + - algType: SHA_256 + algValue: 62a5c358d87a8ef21d7ec1b3b63c9bbb577453dda9c00cbb522b16cee6c23fc4 + url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6-windows-x64.zip + signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc + - distributionType: windows-x64.exe + description: Core binary distribution, Windows Service Installer (MSI) + checksums: + - algType: SHA_512 + algValue: 1d3824e7643c8aba455ab0bd9e67b14a60f2aaa6aa7775116bce40eb0579e8ced162a4f828051d3b867e96ee2858ec5da0cc654e83a83ba30823cbea0df4ff96 + url: https://dlcdn.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe + signatureUrl: https://downloads.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe.asc + # A pre-release of Apache Tomcat + - uuid: 95f481df-f760-47f4-b2f2-f8b76d858450 + version: "11.0.0-M26" + createdDate: 2024-09-13T17:49:00Z + preRelease: true + identifiers: + - idType: PURL + idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.0-M26 + release-distribution: + type: object + properties: + distributionType: + type: string + description: Unique identifier for the distribution type. + description: + type: string + description: Free-text description of the distribution. + identifiers: + type: array + description: List of identifiers specific to this distribution. + items: + $ref: "#/components/schemas/identifier" + url: + type: string + description: Direct download URL for the distribution. + format: url + signatureUrl: + type: string + description: Direct download URL for the distribution's external signature. + format: url + checksums: + type: array + description: List of checksums for the distribution. + items: + "$ref": "#/components/schemas/checksum" + required: + - id + examples: + - distributionType: zip + description: Core binary distribution, zip archive + identifiers: + - idType: PURL + idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?type=zip + checksums: + - algType: SHA_256 + algValue: 9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1 + url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip + signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc + - distributionType: tar.gz + description: Core binary distribution, tar.gz archive + identifiers: + - idType: PURL + idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?type=tar.gz + checksums: + - algType: SHA_256 + algValue: 2fcece641c62ba1f28e1d7b257493151fc44f161fb391015ee6a95fa71632fb9 + url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.tar.gz + signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.tar.gz.asc + - distributionType: windows-x64.zip + description: Core binary distribution, Windows x64 zip archive + identifiers: + - idType: PURL + idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?classifier=windows-x64&type=zip + checksums: + - algType: SHA_256 + algValue: 62a5c358d87a8ef21d7ec1b3b63c9bbb577453dda9c00cbb522b16cee6c23fc4 + url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6-windows-x64.zip + signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc + - distributionType: windows-x64.exe + description: Core binary distribution, Windows Service Installer (MSI) + checksums: + - algType: SHA_512 + algValue: 1d3824e7643c8aba455ab0bd9e67b14a60f2aaa6aa7775116bce40eb0579e8ced162a4f828051d3b867e96ee2858ec5da0cc654e83a83ba30823cbea0df4ff96 + url: https://dlcdn.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe + signatureUrl: https://downloads.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe.asc + + component-release-with-collection: + type: object + description: A TEA Component Release combined with its latest collection + properties: + release: + description: The TEA Component Release information + $ref: "#/components/schemas/release" + latestCollection: + description: The latest TEA Collection for this component release + $ref: "#/components/schemas/collection" + required: + - release + - latestCollection + examples: + - release: + uuid: 605d0ecb-1057-40e4-9abf-c400b10f0345 + version: "11.0.7" + createdDate: 2025-05-07T18:08:00Z + releaseDate: 2025-05-12T18:08:00Z + identifiers: + - idType: PURL + idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.7 + latestCollection: + uuid: 605d0ecb-1057-40e4-9abf-c400b10f0345 + version: 2 + date: 2025-05-12T18:08:00Z + belongsTo: COMPONENT_RELEASE + updateReason: + type: INITIAL_RELEASE + comment: Initial collection for this release + artifacts: + - uuid: 1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce + name: Build SBOM + type: BOM + formats: + - mimeType: application/vnd.cyclonedx+xml + description: CycloneDX SBOM (XML) + url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7-cyclonedx.xml + checksums: + - algType: SHA-256 + algValue: 9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1 + - uuid: dfa35519-9734-4259-bba1-3e825cf4be06 + name: Vulnerability Disclosure Report + type: VULNERABILITIES + formats: + - mimeType: application/vnd.cyclonedx+xml + description: CycloneDX VDR (XML) + url: https://tomcat.apache.org/cyclonedx/vdr.xml + checksums: + - algType: SHA-256 + algValue: 75b81020b3917cb682b1a7605ade431e062f7a4c01a412f0b87543b6e995ad2a + + # + # TEA Collection and related objects + # + collection: + type: object + description: A collection of security-related documents + properties: + uuid: + description: | + UUID of the TEA Collection object. + This matches the UUID of the associated TEA Component Release or TEA Product Release object. + When updating a collection, only the `version` is changed. + "$ref": "#/components/schemas/uuid" + version: + type: integer + description: | + TEA Collection version, incremented each time its content changes. + Versions start with 1. + date: + description: The date when the TEA Collection version was created. + "$ref": "#/components/schemas/date-time" + belongsTo: + description: Indicates whether this collection belongs to a Component Release or a Product Release + "$ref": "#/components/schemas/collection-belongs-to-type" + updateReason: + description: Reason for the update/release of the TEA Collection object. + "$ref": "#/components/schemas/collection-update-reason" + artifacts: + type: array + description: List of TEA artifact objects. + items: + "$ref": "#/components/schemas/artifact" + examples: + # Documents in the latest release of Log4j Core + - uuid: 4c72fe22-9d83-4c2f-8eba-d6db484f32c8 + version: 3 + date: 2024-12-13T00:00:00Z + updateReason: + type: ARTIFACT_UPDATED + comment: VDR file updated + artifacts: + - uuid: 1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce + name: Build SBOM + type: BOM + formats: + - mimeType: application/vnd.cyclonedx+xml + description: CycloneDX SBOM (XML) + url: https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml + signatureUrl: https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml.asc + checksums: + - algType: MD5 + algValue: 2e1a525afc81b0a8ecff114b8b743de9 + - algType: SHA-1 + algValue: 5a7d4caef63c5c5ccdf07c39337323529eb5a770 + - uuid: dfa35519-9734-4259-bba1-3e825cf4be06 + name: Vulnerability Disclosure Report + type: VULNERABILITIES + formats: + - mimeType: application/vnd.cyclonedx+xml + description: CycloneDX VDR (XML) + url: https://logging.apache.org/cyclonedx/vdr.xml + checksums: + - algType: SHA-256 + algValue: 75b81020b3917cb682b1a7605ade431e062f7a4c01a412f0b87543b6e995ad2a + + collection-update-reason: + type: object + description: Reason for the update to the TEA collection + properties: + type: + description: Type of update reason. + "$ref": "#/components/schemas/collection-update-reason-type" + comment: + type: string + description: Free text description + collection-update-reason-type: + type: string + description: Type of TEA collection update + enum: + - INITIAL_RELEASE + - VEX_UPDATED + - ARTIFACT_UPDATED + - ARTIFACT_ADDED + - ARTIFACT_REMOVED + + collection-belongs-to-type: + type: string + description: Indicates whether a collection belongs to a component release or a product release + enum: + - COMPONENT_RELEASE + - PRODUCT_RELEASE + + # + # TEA Artifact and related objects + # + artifact: + type: object + description: A security-related document + properties: + uuid: + description: UUID of the TEA Artifact object. + "$ref": "#/components/schemas/uuid" + name: + type: string + description: Artifact name + type: + description: Type of artifact + "$ref": "#/components/schemas/artifact-type" + distributionTypes: + type: array + description: | + List of component distributions types that this artifact applies to. + If absent, the artifact applies to all distributions. + items: + type: string + description: | + The `id` of the component format that this artifact applies to. + formats: + type: array + description: | + List of objects with the same content, but in different formats. + The order of the list has no significance. + items: + "$ref": "#/components/schemas/artifact-format" + artifact-type: + type: string + description: Specifies the type of external reference. + enum: + - ATTESTATION + - BOM + - BUILD_META + - CERTIFICATION + - FORMULATION + - LICENSE + - RELEASE_NOTES + - SECURITY_TXT + - THREAT_MODEL + - VULNERABILITIES + - OTHER + artifact-format: + type: object + description: A security-related document in a specific format + properties: + mimeType: + type: string + description: The MIME type of the document + description: + type: string + description: A free text describing the artifact + url: + type: string + description: Direct download URL for the artifact + format: url + signatureUrl: + type: string + description: Direct download URL for an external signature of the artifact + format: url + checksums: + type: array + description: List of checksums for the artifact + items: + "$ref": "#/components/schemas/checksum" + checksum: + type: object + properties: + algType: + description: Checksum algorithm + "$ref": "#/components/schemas/checksum-type" + algValue: + type: string + description: Checksum value + checksum-type: + type: string + description: Checksum algorithm + enum: + - MD5 + - SHA-1 + - SHA-256 + - SHA-384 + - SHA-512 + - SHA3-256 + - SHA3-384 + - SHA3-512 + - BLAKE2b-256 + - BLAKE2b-384 + - BLAKE2b-512 + - BLAKE3 + unknown-error-type: + type: string + description: Classification of TEA error response + enum: + - OBJECT_UNKNOWN + - OBJECT_NOT_SHAREABLE + # + # Types used in API responses + # + error-response: + type: object + description: Error response + additionalProperties: false + properties: + error: + $ref: "#/components/schemas/unknown-error-type" + required: + - error + + tea-server-info: + type: object + description: TEA server information including URL, versions, and optional priority + additionalProperties: false + properties: + rootUrl: + description: Root URL of the TEA server for this TEI without trailing slash + type: string + format: uri + example: https://api.teaexample.com + versions: + description: Supported TEA API versions at this server without v prefix + type: array + minItems: 1 + items: + type: string + example: ["0.2.0-beta.2", "1.0.0"] + priority: + description: Optional priority for this server (0.0 to 1.0, where 1.0 is highest priority) + type: number + format: float + minimum: 0.0 + maximum: 1.0 + example: 0.8 + required: + - rootUrl + - versions + + discovery-info: + type: object + description: Discovery information for a TEI + additionalProperties: false + properties: + productReleaseUuid: + description: UUID of the resolved TEA Product Release + $ref: "#/components/schemas/uuid" + example: d4d9f54a-abcf-11ee-ac79-1a52914d44b + servers: + description: Array of TEA server information + type: array + minItems: 1 + items: + $ref: "#/components/schemas/tea-server-info" + required: + - productReleaseUuid + - servers + + pagination-details: + type: object + properties: + timestamp: + type: string + format: date-time + example: '2024-03-20T15:30:00Z' + pageStartIndex: + type: integer + format: int64 + default: 0 + pageSize: + type: integer + format: int64 + default: 100 + totalResults: + type: integer + format: int64 + required: + - timestamp + - pageStartIndex + - pageSize + - totalResults + + paginated-product-response: + type: object + description: A paginated response containing TEA Products + allOf: + - $ref: "#/components/schemas/pagination-details" + - type: object + properties: + results: + type: array + items: + $ref: "#/components/schemas/product" + + paginated-product-release-response: + type: object + description: A paginated response containing TEA Product Releases + allOf: + - $ref: "#/components/schemas/pagination-details" + - type: object + properties: + results: + type: array + items: + $ref: "#/components/schemas/productRelease" + responses: + 204-common-delete: + description: Object deleted successfully + content: + application/json: {} + 400-invalid-request: + description: Request was Invalid + content: + application/json: {} + 401-unauthorized: + description: Authentication required + content: + application/json: {} + 404-object-by-id-not-found: + description: Object requested by identifier not found + content: + application/json: + schema: + $ref: "#/components/schemas/error-response" + discovery-response: + description: Discovery information for the requested TEI + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/discovery-info" + paginated-product: + description: A paginated response containing TEA Products + content: + application/json: + schema: + $ref: "#/components/schemas/paginated-product-response" + paginated-product-release: + description: A paginated response containing TEA Product Releases + content: + application/json: + schema: + $ref: "#/components/schemas/paginated-product-release-response" + parameters: + # Pagination + page-offset: + name: pageOffset + description: Pagination offset + in: query + required: false + schema: + type: integer + format: int64 + default: 0 + page-size: + name: pageSize + description: Pagination offset + in: query + required: false + schema: + type: integer + format: int64 + default: 100 + # + # Query by identifier + # + # Since OpenAPI 3.0 it is possible to use RFC 6570-based serialization for JSON parameters of type array or object: + # https://swagger.io/docs/specification/v3_0/serialization/ + # + # Unfortunately many tools don't support it, for example, + # the `openapi-generator` for Java does not handle this correctly. + # https://github.com/OpenAPITools/openapi-generator/issues/4808 + # + # This can be uncommented, when RFC 6570-base serialization reaches a wider adoption: + # + # identifier-param: + # name: identifierParam + # description: If present, only the objects with the given identifier will be returned. + # in: query + # schema: + # $ref: "#/components/schemas/identifier" + # style: form + # explode: true + # + # In the meantime we explode the object manually: + id-type: + # To allow RFC 6570 in the future without breaking changes to the HTTP API, + # the name of this parameter should be identical to the equivalent property in /components/schemas/identifier + name: idType + description: Type of identifier specified in the `idValue` parameter + in: query + schema: + $ref: "#/components/schemas/identifier-type" + id-value: + # To allow RFC 6570 in the future without breaking changes to the HTTP API, + # the name of this parameter should be identical to the equivalent property in /components/schemas/identifier + name: idValue + description: If present, only the objects with the given identifier value will be returned. + in: query + schema: + type: string + + securitySchemes: + bearerAuth: + type: http + scheme: bearer + basicAuth: + type: http + scheme: basic +security: + - bearerAuth: [] + - basicAuth: [] +tags: + - name: TEA Product + - name: TEA Product Release + - name: TEA Component + - name: TEA Component Release + - name: TEA Artifact + - name: TEA Discovery +externalDocs: + description: Transparency Exchange API specification + url: https://github.com/CycloneDX/transparency-exchange-api diff --git a/doc/tea-requirements.md b/doc/tea-requirements.md index 2bf8e91..c60a1e6 100644 --- a/doc/tea-requirements.md +++ b/doc/tea-requirements.md @@ -21,10 +21,10 @@ At the base URL well known URLs (ref) needs to point to As an alternative, discovery using a company's ordinary web site should be supported. This can be handled using the file security.txt (IETF RFC 9116) -## Artifact Discovery based on TEA collections +## Artefact Discovery based on TEA collections -The API MUST provide a way to discover the artifacts that are available for retrieval or further query. -Discovery SHOULD group artifacts together that represent a **collection** +The API MUST provide a way to discover the artefacts that are available for retrieval or further query. +Discovery SHOULD group artefacts together that represent a **collection** that are directly applicable to a given product with a given version. Collections are OPTIONAL. @@ -44,11 +44,11 @@ modifying collections, or deleting existing collections. - Authn/Authz MUST be supported -## Artifact Retrieval +## Artefact Retrieval -The API MUST provide a method in which to retrieve an artifact based on the identity of the artifact. +The API MUST provide a method in which to retrieve an artefact based on the identity of the artefact. For example, using CycloneDX BOM-Link to retrieve either the -latest version or specific version of an artifact. +latest version or specific version of an artefact. ```text urn:cdx:serialNumber @@ -59,15 +59,15 @@ The API needs to provide support for update checks, i.e. to check if a document updated without downloading. (possibly etag or HEAD method or similar) Authn/Authz MUST be supported -## Artifact Publishing +## Artefact Publishing -The API MUST provide a way to publish an artifact, either standalone or to a collection. -The detection of duplicate artifacts with the same identity MUST be handled and prevented. +The API MUST provide a way to publish an artefact, either standalone or to a collection. +The detection of duplicate artefacts with the same identity MUST be handled and prevented. Authn/Authz MUST be supported -## Artifact Versioning +## Artefact Versioning -The system and API must support artifact versioning for formats that support +The system and API must support artefact versioning for formats that support versioning such as CycloneDX. For example: - The ability to retrieve the latest SBOM vs a previous (uncorrected) version of the same SBOM. @@ -77,7 +77,7 @@ versioning such as CycloneDX. For example: Authn/Authz MUST be supported -## insights: Search Artifact Inventory +## insights: Search Artefact Inventory The API MUST provide a way to search the inventory of a specific BOM or all available BOMs for a given component or service. The API SHOULD support multiple identity formats including @@ -92,6 +92,6 @@ The API MUST provide a way to search for the metadata component across all avail The API SHOULD support multiple identity formats including PURL, CPE, SWID, GAV, GTIN, and GMN. For example: -- Return the identity of all artifacts that describe `cpe:/a:acme:commerce_suite:1.0`. +- Return the identity of all artefacts that describe `cpe:/a:acme:commerce_suite:1.0`. Authn/Authz MUST be supported diff --git a/doc/tea-usecases.md b/doc/tea-usecases.md index 1d97748..bd3b702 100644 --- a/doc/tea-usecases.md +++ b/doc/tea-usecases.md @@ -7,7 +7,7 @@ a..." The use cases are divided in two categories: * Use cases for __customers__ (end-users, manufacturers) to find a repository with - Transparency Artefacts for a single unit purchased + Transparency artefacts for a single unit purchased * Use cases where there are different __products__ * This applies after discovery where we need to handle various things a customer may buy as a single unit @@ -21,7 +21,7 @@ As a consumer that has an SBOM for a product, I want to be able to retrieve VEX ### C2: Consumer: Automation based on product name/identifier -As a consumer, I want to download artifacts for a product based on known data. +As a consumer, I want to download artefacts for a product based on known data. A combination of manufacturer, product name, vendor product ID, EAN bar code or other unique identifier. After discovering the base repository URL I want to be able to find a specific product variant and version. @@ -29,9 +29,9 @@ product variant and version. If the consumer is a business, then the procurement process may include delivery of an SBOM with proper identifiers and possibly URLs or identifiers in another document, which may bootstrap the discovery process in a more exact way than in the case of buying a product in a retail market. Alice bought a gadget at the gadget store that contains a full Linux system. Where and how will she find the SBOM and VEX for the gadget? -### C3: Consumer: Artifact retrieval +### C3: Consumer: Artefact retrieval -As a consumer, I want to retrieve one or more supply chain artifacts for the products that I have access to, possibly through licensing or other means. As a consumer, I should be able to retrieve all source artifacts such as xBOMs, VDR/VEX, CDXA, and CLE. +As a consumer, I want to retrieve one or more supply chain artefacts for the products that I have access to, possibly through licensing or other means. As a consumer, I should be able to retrieve all source artefacts such as xBOMs, VDR/VEX, CDXA, and CLE. ### C4: Consumer: Summarized CLE @@ -41,7 +41,7 @@ A CLE captures all lifecycle events over time, however, there is a need to retri ### C5: Consumer: Insights As a consumer, I want the ability to simply ask the API questions rather than having to download, -process, and analyze raw supply chain artifacts on my own systems. Common questions should be +process, and analyze raw supply chain artefacts on my own systems. Common questions should be provided by the API by default along with the ability to query for more complex answers using the Common Expression Language (CEL). diff --git a/spec/openapi.yaml b/spec/openapi.yaml index 79c9a15..7d52394 100644 --- a/spec/openapi.yaml +++ b/spec/openapi.yaml @@ -12,7 +12,7 @@ info: license: name: Apache 2.0 url: https://github.com/CycloneDX/transparency-exchange-api/blob/main/LICENSE - version: 0.2.0-beta.2 + version: 0.3.0-beta.2 servers: - url: http://localhost/tea/v1 description: Local development @@ -356,7 +356,7 @@ paths: - TEA Component Release /artifact/{uuid}: get: - description: Get metadata for specific TEA artifact + description: Get metadata for specific TEA Artifact operationId: getArtifact parameters: - name: uuid @@ -837,7 +837,7 @@ components: "$ref": "#/components/schemas/collection-update-reason" artifacts: type: array - description: List of TEA artifact objects. + description: List of TEA Artifact objects. items: "$ref": "#/components/schemas/artifact" examples: @@ -912,19 +912,19 @@ components: "$ref": "#/components/schemas/uuid" name: type: string - description: Artifact name + description: Name of TEA Artifact type: - description: Type of artifact + description: Type of TEA Artifact "$ref": "#/components/schemas/artifact-type" distributionTypes: type: array description: | - List of component distributions types that this artifact applies to. - If absent, the artifact applies to all distributions. + List of component distributions types that this TEA Artifact applies to. + If absent, the TEA Artifact applies to all distributions. items: type: string description: | - The `id` of the component format that this artifact applies to. + The `id` of the component format that this TEA Artifact applies to. formats: type: array description: | @@ -956,18 +956,18 @@ components: description: The MIME type of the document description: type: string - description: A free text describing the artifact + description: A free text describing the TEA Artifact url: type: string - description: Direct download URL for the artifact + description: Direct download URL for the TEA Artifact format: url signatureUrl: type: string - description: Direct download URL for an external signature of the artifact + description: Direct download URL for an external signature of the TEA Artifact format: url checksums: type: array - description: List of checksums for the artifact + description: List of checksums for the TEA Artifact items: "$ref": "#/components/schemas/checksum" checksum: diff --git a/spec/publisher/openapi.json b/spec/publisher/openapi.json index 261986d..cdbbc65 100644 --- a/spec/publisher/openapi.json +++ b/spec/publisher/openapi.json @@ -615,7 +615,7 @@ "reason": "New Product Release", "artifacts": [ { - "name": "Example Artifact", + "name": "Example TEA Artifact", "type": "bom", "author": { "name": "John Doe", diff --git a/tea-collection/tea-collection.md b/tea-collection/tea-collection.md index f00d154..aac81af 100644 --- a/tea-collection/tea-collection.md +++ b/tea-collection/tea-collection.md @@ -112,7 +112,7 @@ For instance: created by the [Nullsoft Scriptable Install System](https://nsis.sourceforge.io/Main_Page). By defining separate `distributionType`s, -it becomes possible to precisely associate artifacts and vulnerability disclosures with the affected distributions, +it becomes possible to precisely associate artefacts and vulnerability disclosures with the affected distributions, ensuring accurate risk assessment and remediation.
@@ -271,22 +271,22 @@ There are two main scenarios for using the `preRelease` flag: ```
-## The TEA Collection object (TCO) +## TEA Collection object (TCO) For each product and version there is a Tea Collection object, which is a list -of available artifacts for this specific version. The TEA Index is a list of +of available artefacts for this specific version. The TEA Index is a list of TEA collections. The TEA collection is normally created by the TEA application server at -publication time of artifacts. The publisher may sign the collection +publication time of artefacts. The publisher may sign the collection object as a JSON file at time of publication. -If there are any updates of artifacts within a collection for the same +If there are any updates of artefacts within a collection for the same version of a product, then a new TEA Collection object is created and signed. This update will have the same UUID, but a new version number. A reason for the update will have to be provided. This shall be used to correct mistakes, spelling errors as well as to provide new information -on dynamic artifact types such as LCE or VEX. If the product +on dynamic artefact types such as LCE or VEX. If the product is modified, that is a new product version and that should generate a new collection object with a new UUID and updated metadata. @@ -321,62 +321,62 @@ to implement this: See [reasons for TEA Collection update](#the-reason-for-tco-update-enum) below. - __comment__: Free text description. - - - __artifacts__: List of TEA artifact objects. - See [below](#artifact-object). + - __artifacts__: List of TEA Artifact objects. + See [below](#tea-artifact-object). -## The TEA Artifact object +## TEA Artifact object A TEA Artifact object represents a security-related document or file linked to a component release, such as an SBOM, VEX, attestation, or license. -Artifacts are strictly **immutable**: if the underlying document changes, a new TEA Artifact object must be created. +TEA Artifacts are strictly **immutable**: if the underlying document changes, a new TEA Artifact object must be created. URLs referenced in this object must always resolve to the same resource to ensure that published checksums remain valid and verifiable. TEA Artifacts can be reused across multiple TEA Collections, -allowing the same document to be referenced by different component releases or even different components. +allowing the same document to be referenced by different component or product releases. This promotes consistency and reduces duplication. -Optionally, each artifact can specify the `distributionType` identifiers of the distributions it applies to. -If this field is absent, the artifact is considered applicable to all distributions of the release. +Optionally, each TEA Artifact can specify the `distributionType` identifiers of the distributions it applies to. +If this field is absent, the TEA Artifact is considered applicable to all distributions of the release. ### Structure A TEA Artifact object contains the following fields: -- __uuid__: The UUID of the TEA Artifact object. This uniquely identifies the artifact. -- __name__: A human-readable name for the artifact. -- __type__: The type of artifact. See [TEA Artifact types](#tea-artifact-types) for allowed values (e.g., `BOM`, `VULNERABILITIES`, `LICENSE`). +- __uuid__: The UUID of the TEA Artefact object. This uniquely identifies the TEA Artifact. +- __name__: A human-readable name for the artefact. +- __type__: The type of artefact. See [TEA Artifact types](#tea-artefact-types) for allowed values (e.g., `BOM`, `VULNERABILITIES`, `LICENSE`). - __componentDistributions__ (optional): - An array of `distributionType` identifiers indicating which distributions this artifact applies to. - If omitted, the artifact applies to all distributions. + An array of `distributionType` identifiers indicating which distributions this TEA Artifact applies to. + If omitted, the TEA Artifact applies to all distributions. - __formats__: - An array of objects, each representing the same artifact content in a different format. + An array of objects, each representing the same artefact content in a different format. The order of the list is not significant. Each format object includes: - __mimeType__: The MIME type of the document (e.g., `application/vnd.cyclonedx+xml`). - - __description__: A free-text description of the artifact format. - - __url__: A direct download URL for the artifact. This must point to an immutable resource. - - __signatureUrl__ (optional): A direct download URL for a detached digital signature of the artifact, if available. + - __description__: A free-text description of the artefact format. + - __url__: A direct download URL for the artefact. This must point to an immutable resource. + - __signatureUrl__ (optional): A direct download URL for a detached digital signature of the artefact, if available. - __checksums__: - An array of checksum objects for the artifact, each containing: + An array of checksum objects for the artefact, each containing: - __algType__: The checksum algorithm used (e.g., `SHA_256`, `SHA3_512`). - __algValue__: The checksum value as a string. ### Notes -- The `formats` array allows the same artifact to be provided in multiple encodings or serializations (e.g., JSON, XML). -- The `checksums` field provides integrity verification for each artifact format. -- The `signatureUrl` enables consumers to verify the authenticity of the artifact using detached signatures. -- Artifacts should be published to stable, versioned URLs to ensure immutability and traceability. +- The `formats` array allows the same artefact to be provided in multiple encodings or serializations (e.g., JSON, XML). +- The `checksums` field provides integrity verification for each artefact format. +- The `signatureUrl` enables consumers to verify the authenticity of the artefact using detached signatures. +- Artefacts should be published to stable, versioned URLs to ensure immutability and traceability. ## The reason for TCO update enum | ENUM | Description | |------------------|----------------------------------------| | INITIAL_RELEASE | Initial release of the collection | -| VEX_UPDATED | Updated the VEX artifact(s) | -| ARTIFACT_UPDATED | Updated the artifact(s) other than VEX | -| ARTIFACT_REMOVED | Removal of artifact | -| ARTIFACT_ADDED | Addition of an artifact | +| VEX_UPDATED | Updated the VEX artefact(s) | +| ARTIFACT_UPDATED | Updated the artefact(s) other than VEX | +| ARTIFACT_REMOVED | Removal of artefact | +| ARTIFACT_ADDED | Addition of an artefact | Updates of VEX (CSAF) files may be handled in a different way by a TEA client, producing different alerts than other changes of a collection. diff --git a/tea-component/tea-component.md b/tea-component/tea-component.md index 4f42a6f..510cd3b 100644 --- a/tea-component/tea-component.md +++ b/tea-component/tea-component.md @@ -2,7 +2,7 @@ The TEA Component represents a component lineage. A product release may be constructed with one or multiple TEA Components, each with their own set of -releases and related artifacts. +releases and related artefacts. Each TEA Component has a list of Component Releases (see `/component/{uuid}/releases`), which enumerates all known versions for that component. @@ -32,7 +32,7 @@ for a component. ### Examples -Some examples of Maven artifacts as TEA Components: +Some examples of Maven artefacts as TEA Components: ```json { diff --git a/tea-component/tea-release.md b/tea-component/tea-release.md index 82fe00f..35af4ac 100644 --- a/tea-component/tea-release.md +++ b/tea-component/tea-release.md @@ -2,7 +2,7 @@ ## Overview -A TEA Component Release represents a specific version of a TEA Component lineage. It is the concrete, versioned entity which has collections of security-related artifacts (SBOM, VDR/VEX, attestations, etc.). +A TEA Component Release represents a specific version of a TEA Component lineage. It is the concrete, versioned entity which has collections of security-related artefacts (SBOM, VDR/VEX, attestations, etc.). Key attributes: - uuid: Unique identifier of the component release @@ -13,7 +13,7 @@ Key attributes: - preRelease: Indicates pre-release/beta status - identifiers: Array of identifiers (idType: CPE/TEI/PURL; idValue: string) -Collections for a release contain artifacts relevant to that specific release. +Collections for a release contain artefacts relevant to that specific release. ## JSON examples diff --git a/tea-product/tea-product-release.md b/tea-product/tea-product-release.md index adb8240..ebe419d 100644 --- a/tea-product/tea-product-release.md +++ b/tea-product/tea-product-release.md @@ -2,7 +2,7 @@ ## Overview -A TEA Product Release represents a specific versioned release of a TEA Product. It is the primary resolvable entity via TEI and the entry point for discovery of included components and related collections of security artifacts. +A TEA Product Release represents a specific versioned release of a TEA Product. It is the primary resolvable entity via TEI and the entry point for discovery of included components and related collections of security artefacts. Key attributes: - uuid: Unique identifier of the product release @@ -16,7 +16,7 @@ Key attributes: - uuid: UUID of the TEA Component - release: Optional UUID of a specific component release to pin an exact version -Collections for a product release contain artifacts relevant to that product release. +Collections for a product release contain artefacts relevant to that product release. ## JSON examples diff --git a/tea-product/tea-product.md b/tea-product/tea-product.md index bc09aac..8bd7290 100644 --- a/tea-product/tea-product.md +++ b/tea-product/tea-product.md @@ -50,7 +50,7 @@ owned version. ### Example -An example of a product consisting of an OSS project and all its Maven artifacts: +An example of a product consisting of an OSS project and all its Maven artefacts: ```json {