diff --git a/spec/openapi.yaml b/spec/openapi.yaml index 0d66179..a251fb6 100644 --- a/spec/openapi.yaml +++ b/spec/openapi.yaml @@ -30,7 +30,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/tea_product" + $ref: "#/components/schemas/product" 400: $ref: "#/components/responses/400-invalid-request" 404: @@ -50,7 +50,7 @@ paths: responses: 200: description: Product retrieved successfully - $ref: "#/components/responses/paginated-tea-product" + $ref: "#/components/responses/paginated-product" 400: $ref: "#/components/responses/400-invalid-request" 404: @@ -69,7 +69,7 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/tea_leaf" + "$ref": "#/components/schemas/component" 400: $ref: "#/components/responses/400-invalid-request" 404: @@ -88,7 +88,7 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/tea_collection" + "$ref": "#/components/schemas/collection" 400: $ref: "#/components/responses/400-invalid-request" 404: @@ -98,258 +98,190 @@ paths: webhooks: {} components: schemas: - base_product_fields: + # + # 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$" + identifier: type: object + description: An identifier with a specified type properties: - product_name: + idType: + "$ref": "#/components/schemas/identifier-type" + idValue: type: string - description: Product name in free text. + 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: - $ref": "#/components/schemas/type_uuid" - description: UUID + "$ref": "#/components/schemas/uuid" + name: + type: string + description: Product name identifiers: type: array + description: List of identifiers for the product items: - type: object - properties: - type: - $ref: "#/components/schemas/type_product_identifier_type" - id: - type: string - required: - - type - - id - description: Array of identifiers for this product (tei, cpe, purl) - base_versioned_product: - allOf: - - "$ref": "#/components/schemas/base_product_fields" - - type: object - properties: - product_version: - type: string - release_date: - type: string - format: date-time - example: '2024-03-20T15:30:00Z' - base_artifact_object: - type: object - properties: - identifier: - "$ref": "#/components/schemas/type_uuid" - description: - type: string - mime_type: - type: string - artifact_url: - type: string - format: uri - artifact_size_in_bytes: - type: integer - format: int64 - artifact_checksum: - type: string - description: The checksum value - artifact_checksum_type: - type: string - description: The algorithm used to generate the checksum - enum: - - SHA512 - - SHA384 - - SHA256 - - SHA224 - - SHA1 - - MD5 - - BLAKE2b-512 - - BLAKE2s-256 - - BLAKE3 - default: SHA256 - tea_product: - allOf: - - "$ref": "#/components/schemas/base_product_fields" - - type: object - properties: - leaf_references: - type: array - items: - "$ref": "#/components/schemas/type_uuid" - description: Array of UUIDs referencing TEA Leaf entries - required: - - identifier - - product_name - tea_leaf: - allOf: - - "$ref": "#/components/schemas/base_versioned_product" - - type: object - properties: - identifier: - "$ref": "#/components/schemas/type_uuid" - pre_release: - type: boolean - end_of_life: - type: string - format: date-time - collection_references: - type: array - items: - "$ref": "#/components/schemas/type_uuid" - description: Array of UUIDs referencing TEA Collection entries - default: [] - required: - - identifier - - product_name - - product_version - - release_date - - pre_release - tea_collection: - type: object - properties: - identifier: - "$ref": "#/components/schemas/type_uuid" - product_name: - type: string - product_version: - type: string - release_date: - type: string - format: date-time - example: '2024-03-20T15:30:00Z' - author: - "$ref": "#/components/schemas/type_author" - reason: - "$ref": "#/components/schemas/type_collection_reason" - artifacts: + "$ref": "#/components/schemas/identifier" + components: type: array + description: List of TEA components for the product items: - "$ref": "#/components/schemas/tea_collection_artifact" - default: [] + "$ref": "#/components/schemas/uuid" required: - - identifier - - product_name - - product_version - - release_date - - author - - reason - tea_collection_artifact: + - uuid + - name + - identifiers + - components + + # + # TEA Component and related objects + # + component: type: object + description: A TEA component properties: - identifier: - "$ref": "#/components/schemas/type_uuid" + uuid: + "$ref": "#/components/schemas/uuid" name: type: string - type: - "$ref": "#/components/schemas/type_tea_collection_artifact_type" - author: - "$ref": "#/components/schemas/type_author" - objects: + description: Leaf name + identifiers: type: array + description: List of identifiers for the component items: - "$ref": "#/components/schemas/tea_collection_artifact_object" - minItems: 1 + "$ref": "#/components/schemas/identifier" + versions: + type: array + description: List of released versions for the component + items: + "$ref": "#/components/schemas/component-version" required: - - identifier + - uuid - name - - type - - author - - objects - tea_collection_artifact_object: + - identifiers + - versions + component-version: type: object + description: A specific version of a TEA leaf properties: - identifier: - "$ref": "#/components/schemas/type_uuid" - description: - type: string - mime_type: - type: string - artifact_url: + uuid: + "$ref": "#/components/schemas/uuid" + version: type: string - format: uri - artifact_size_in_bytes: + description: Version number of TEA leaf + identifiers: + type: array + description: List of identifiers for this component version + items: + "$ref": "#/components/schemas/identifier" + release_date: + "$ref": "#/components/schemas/date-time" + description: Release date + pre_release: + type: boolean + description: Marks if the version is a pre-release version + classifier: + type: object + description: Optional classifier to distinguish between artifacts + required: + - uuid + - version + - identifiers + - release_date + - pre_release + + # + # TEA Collection and related objects + # + collection: + type: object + description: A collection of security-related documents + properties: + uuid: + "$ref": "#/components/schemas/uuid" + description: Must match the UUID of the corresponding `component_version` object + version: type: integer - format: int64 - artifact_checksum: - type: string - description: The checksum value - artifact_checksum_type: + default: 1 + description: Collection version, incremented each time its content changes. + update_reason: + "$ref": "#/components/schemas/collection-update-reason" + collection-update-reason: + type: object + description: Reason for the last update to the TEA collection + properties: + type: + "$ref": "#/components/schemas/collection-update-reason-type" + comment: type: string - description: The algorithm used to generate the checksum - enum: - - SHA512 - - SHA384 - - SHA256 - - SHA224 - - SHA1 - - MD5 - - BLAKE2b-512 - - BLAKE2s-256 - - BLAKE3 - default: SHA256 - signature_url: + description: Free text description + collection-update-reason-type: + type: string + description: Type of TEA collection update + enum: + - product_released + - vulnerability_disclosed + - attestation_added + - document_fixed + + # + # TEA Artifact and related objects + # + artifact: + type: object + description: A security-related document + properties: + uuid: + "$ref": "#/components/schemas/uuid" + name: type: string - format: uri - required: - - identifier - - description - - mime_type - - artifact_url - - artifact_size_in_bytes - - artifact_checksum - - artifact_checksum_type - # Types - type_author: + description: Artifact name + author: + "$ref": "#/components/schemas/artifact-author" + type: + "$ref": "#/components/schemas/artifact-type" + formats: + type: array + items: + "$ref": "#/components/schemas/artifact-format" + artifact-author: type: object + description: The author of a document. properties: name: type: string + description: The name of the author email: type: string + description: The e-mail address of the author format: email organization: type: string - required: - - name - - email - - organization - type_collection_reason: + description: Organization + artifact-type: type: string - description: Event requiring this TEA Collection was published - enum: - - New Product Release - - BOM Updated - - Attestation Added - - Attestation Updated - type_pagination_details: - type: object - properties: - timestamp: - type: string - format: date-time - example: '2024-03-20T15:30:00Z' - page_start_index: - type: number - format: int64 - default: 0 - page_size: - type: number - format: int64 - default: 100 - total_results: - type: number - format: int64 - required: - - timestamp - - page_start_index - - page_size - - total_results - type_product_identifier_type: - type: string - description: Identifier types - enum: - - tei - - purl - - cpe - type_tea_collection_artifact_type: - type: string - title: Type description: Specifies the type of external reference. enum: - vcs @@ -488,9 +420,82 @@ components: Vulnerability Disclosure) other: Use this if no other types accurately describe the purpose of the external reference. - type_uuid: + artifact-format: + type: object + description: A security-related document in a specific format + properties: + uuid: + "$ref": "#/components/schemas/uuid" + mimeType: + type: string + description: The MIME type of the document + description: + type: string + description: A free text describing the artifact + url: + type: string + description: A download URL for the artifact + format: url + signature_url: + type: string + description: A 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/artifact-checksum" + artifact-checksum: + type: object + properties: + algType: + "$ref": "#/components/schemas/artifact-checksum-type" + algValue: + type: string + description: Checksum value + artifact-checksum-type: type: string - format: uuid + 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 + + # + # Types used in API responses + # + pagination-details: + type: object + properties: + timestamp: + type: string + format: date-time + example: '2024-03-20T15:30:00Z' + page_start_index: + type: number + format: int64 + default: 0 + page_size: + type: number + format: int64 + default: 100 + total_results: + type: number + format: int64 + required: + - timestamp + - page_start_index + - page_size + - total_results responses: 204-common-delete: description: Object deleted successfully @@ -508,19 +513,19 @@ components: description: Object requested by identifier not found content: application/json: {} - paginated-tea-product: + paginated-product: description: A paginated response containing TEA Products content: application/json: schema: allOf: - - $ref: "#/components/schemas/type_pagination_details" + - $ref: "#/components/schemas/pagination-details" - type: object properties: results: type: array items: - "$ref": "#/components/schemas/tea_product" + "$ref": "#/components/schemas/product" parameters: # Pagination page-offset: @@ -548,21 +553,21 @@ components: in: path required: true schema: - $ref: "#/components/schemas/type_uuid" + $ref: "#/components/schemas/uuid" leaf-identifier: name: leaf-identifier description: TEA Leaf Identifier in: path required: true schema: - $ref: "#/components/schemas/type_uuid" + $ref: "#/components/schemas/uuid" product-identifier-type: name: product-identifier-type description: The identifier type (enum) in: path required: true schema: - $ref: "#/components/schemas/type_product_identifier_type" + $ref: "#/components/schemas/identifier-type" product-identifier: name: product-identifier description: The actual identifier string @@ -590,8 +595,8 @@ security: - basicAuth: [] tags: - name: TEA Collection + - name: TEA Component - name: TEA Product - - name: TEA Leaf externalDocs: description: Transparency Exchange API specification url: https://github.com/CycloneDX/transparency-exchange-api