diff --git a/spec/openapi.yaml b/spec/openapi.yaml index 31083f6..393b1ca 100644 --- a/spec/openapi.yaml +++ b/spec/openapi.yaml @@ -1,3 +1,5 @@ +--- +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base openapi: 3.1.1 info: title: Transparency Exchange API @@ -17,13 +19,13 @@ servers: paths: /product/{uuid}: get: - description: Returns the corresponding leafs for a given product UUID. + description: Returns the corresponding TEA components for a given TEA product UUID. operationId: getTeaProductByUuid parameters: - name: uuid in: path required: true - description: UUID of product in the TEA server + description: UUID of the TEA product in the TEA server schema: type: string format: uuid @@ -33,11 +35,11 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/tea_product" + $ref: "#/components/schemas/product" '400': - $ref: "#/components/responses/400_invalid_request" + $ref: "#/components/responses/400-invalid-request" '404': - $ref: "#/components/responses/404_object_by_id_not_found" + $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Product /products: @@ -46,21 +48,21 @@ paths: match. operationId: getTeaProductByIdentifier parameters: - - $ref: "#/components/parameters/page_offset" - - $ref: "#/components/parameters/page_size" + - $ref: "#/components/parameters/page-offset" + - $ref: "#/components/parameters/page-size" - $ref: "#/components/parameters/tei_urn" responses: '200': - $ref: "#/components/responses/paginated_tea_product" + $ref: "#/components/responses/paginated-product" '400': - $ref: "#/components/responses/400_invalid_request" + $ref: "#/components/responses/400-invalid-request" '404': - $ref: "#/components/responses/404_object_by_id_not_found" + $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Product - /tea-component/{uuid}: + /component/{uuid}: get: - description: Get the TEA Leaf that describes the Version of a Product + description: Get a TEA Component operationId: getTeaComponentById parameters: - name: uuid @@ -76,16 +78,16 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/tea_component_detailed_view" + "$ref": "#/components/schemas/component" '400': - $ref: "#/components/responses/400_invalid_request" + $ref: "#/components/responses/400-invalid-request" '404': - $ref: "#/components/responses/404_object_by_id_not_found" + $ref: "#/components/responses/404-object-by-id-not-found" tags: - - TEA Leaf - /component/{uuid}/collections: + - TEA Component + /component/{uuid}/versions: get: - description: Get the TEA Leaf that describes the Version of a Product + description: Get all TEA Component versions that match the given criteria operationId: getCollectionsByComponentId parameters: - name: uuid @@ -102,17 +104,17 @@ paths: application/json: schema: type: array - items: - "$ref": "#/components/schemas/tea_collections_list_view" + items: + "$ref": "#/components/schemas/component-version" '400': - $ref: "#/components/responses/400_invalid_request" + $ref: "#/components/responses/400-invalid-request" '404': - $ref: "#/components/responses/404_object_by_id_not_found" + $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Leaf /collection/{uuid}: get: - description: Get a TEA Component Version and Collection by its Identifier + description: Get a TEA Collection by its identifier operationId: getTeaCollectionById parameters: - name: uuid @@ -128,275 +130,198 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/tea_collection" + "$ref": "#/components/schemas/collection" '400': - $ref: "#/components/responses/400_invalid_request" + $ref: "#/components/responses/400-invalid-request" '404': - $ref: "#/components/responses/404_object_by_id_not_found" + $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Collection 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/uuid" + name: type: string - format: uuid + description: Product name identifiers: type: array + description: List of identifiers for the product + items: + "$ref": "#/components/schemas/identifier" + components: + type: array + description: List of TEA components 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: + "$ref": "#/components/schemas/uuid" + required: + - uuid + - name + - identifiers + - components + + # + # TEA Component and related objects + # + component: type: object + description: A TEA component 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: + uuid: + "$ref": "#/components/schemas/uuid" + name: 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_collections_list_view: - 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 - required: - - identifier - - product_name - - product_version - - release_date - - pre_release - tea_component_detailed_view: - allOf: - - "$ref": "#/components/schemas/base_product_fields" - - type: object - properties: - end_of_life: - type: string - format: date-time - required: - - identifier - - product_name - - product_version - - release_date - - pre_release - tea_collection: + description: Component name + identifiers: + type: array + description: List of identifiers for the component + items: + "$ref": "#/components/schemas/identifier" + required: + - uuid + - name + - identifiers + - versions + component-version: type: object + description: A specific version of a TEA component properties: - identifier: - "$ref": "#/components/schemas/type_uuid" - product_name: - type: string - product_version: + collection_uuid: + "$ref": "#/components/schemas/uuid" + 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: + description: Version number of TEA component + identifiers: type: array + description: List of identifiers for this component version items: - "$ref": "#/components/schemas/tea_collection_artifact" - default: [] + "$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: - - identifier - - product_name - - product_version + - uuid + - version + - identifiers - release_date - - author - - reason - tea_collection_artifact: + - pre_release + + # + # TEA Collection and related objects + # + collection: type: object + description: A collection of security-related documents properties: - identifier: - "$ref": "#/components/schemas/type_uuid" - name: - type: string - type: - "$ref": "#/components/schemas/type_tea_collection_artifact_type" - author: - "$ref": "#/components/schemas/type_author" - objects: + uuid: + "$ref": "#/components/schemas/uuid" + description: Must match the UUID of the corresponding `component_version` object + version: + type: integer + default: 1 + description: Collection version, incremented each time its content changes. + update_reason: + "$ref": "#/components/schemas/collection-update-reason" + artifacts: type: array items: - "$ref": "#/components/schemas/tea_collection_artifact_object" - minItems: 1 - required: - - identifier - - name - - type - - author - - objects - tea_collection_artifact_object: + "$ref": "#/components/schemas/artifact" + collection-update-reason: type: object + description: Reason for the last update to the TEA collection 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: + "$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: - 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: + description: Organization + artifact-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 @@ -442,108 +367,181 @@ components: - digital-signature - rfc-9116 - other - # meta:enum: - # vcs: Version Control System - # issue-tracker: Issue or defect tracking system, or an Application Lifecycle - # Management (ALM) system - # website: Website - # advisories: Security advisories - # bom: Bill of Materials (SBOM, OBOM, HBOM, SaaSBOM, etc) - # mailing-list: Mailing list or discussion group - # social: Social media account - # chat: Real-time chat platform - # documentation: Documentation, guides, or how-to instructions - # support: Community or commercial support - # source-distribution: - # description: The location where the source code distributable can be obtained. - # This is often an archive format such as zip or tgz. The source-distribution - # type complements use of the version control (vcs) type. - # distribution: Direct or repository download location - # distribution-intake: The location where a component was published to. This - # is often the same as "distribution" but may also include specialized publishing - # processes that act as an intermediary. - # license: The reference to the license file. If a license URL has been defined - # in the license node, it should also be defined as an external reference - # for completeness. - # build-meta: Build-system specific meta file (i.e. pom.xml, package.json, .nuspec, - # etc) - # build-system: Reference to an automated build system - # release-notes: Reference to release notes - # security-contact: Specifies a way to contact the maintainer, supplier, or - # provider in the event of a security incident. Common URIs include links - # to a disclosure procedure, a mailto (RFC-2368) that specifies an email address, - # a tel (RFC-3966) that specifies a phone number, or dns (RFC-4501) that specifies - # the records containing DNS Security TXT. - # model-card: A model card describes the intended uses of a machine learning - # model, potential limitations, biases, ethical considerations, training parameters, - # datasets used to train the model, performance metrics, and other relevant - # data useful for ML transparency. - # log: A record of events that occurred in a computer system or application, - # such as problems, errors, or information on current operations. - # configuration: Parameters or settings that may be used by other components - # or services. - # evidence: Information used to substantiate a claim. - # formulation: Describes how a component or service was manufactured or deployed. - # attestation: Human or machine-readable statements containing facts, evidence, - # or testimony. - # threat-model: An enumeration of identified weaknesses, threats, and countermeasures, - # dataflow diagram (DFD), attack tree, and other supporting documentation - # in human-readable or machine-readable format. - # adversary-model: The defined assumptions, goals, and capabilities of an adversary. - # risk-assessment: Identifies and analyzes the potential of future events that - # may negatively impact individuals, assets, and/or the environment. Risk - # assessments may also include judgments on the tolerability of each risk. - # vulnerability-assertion: A Vulnerability Disclosure Report (VDR) which asserts - # the known and previously unknown vulnerabilities that affect a component, - # service, or product including the analysis and findings describing the impact - # (or lack of impact) that the reported vulnerability has on a component, - # service, or product. - # exploitability-statement: A Vulnerability Exploitability eXchange (VEX) which - # asserts the known vulnerabilities that do not affect a product, product - # family, or organization, and optionally the ones that do. The VEX should - # include the analysis and findings describing the impact (or lack of impact) - # that the reported vulnerability has on the product, product family, or organization. - # pentest-report: Results from an authorized simulated cyberattack on a component - # or service, otherwise known as a penetration test. - # static-analysis-report: SARIF or proprietary machine or human-readable report - # for which static analysis has identified code quality, security, and other - # potential issues with the source code. - # dynamic-analysis-report: Dynamic analysis report that has identified issues - # such as vulnerabilities and misconfigurations. - # runtime-analysis-report: Report generated by analyzing the call stack of a - # running application. - # component-analysis-report: Report generated by Software Composition Analysis - # (SCA), container analysis, or other forms of component analysis. - # maturity-report: Report containing a formal assessment of an organization, - # business unit, or team against a maturity model. - # certification-report: Industry, regulatory, or other certification from an - # accredited (if applicable) certification body. - # codified-infrastructure: Code or configuration that defines and provisions - # virtualized infrastructure, commonly referred to as Infrastructure as Code - # (IaC). - # quality-metrics: Report or system in which quality metrics can be obtained. - # poam: Plans of Action and Milestones (POAM) complement an "attestation" external - # reference. POAM is defined by NIST as a "document that identifies tasks - # needing to be accomplished. It details resources required to accomplish - # the elements of the plan, any milestones in meeting the tasks and scheduled - # completion dates for the milestones". - # electronic-signature: An e-signature is commonly a scanned representation - # of a written signature or a stylized script of the person's name. - # digital-signature: A signature that leverages cryptography, typically public/private - # key pairs, which provides strong authenticity verification. - # rfc-9116: Document that complies with RFC-9116 (A File Format to Aid in Security - # Vulnerability Disclosure) - # other: Use this if no other types accurately describe the purpose of the external - # reference. - type_uuid: + meta:enum: + vcs: Version Control System + issue-tracker: Issue or defect tracking system, or an Application Lifecycle + Management (ALM) system + website: Website + advisories: Security advisories + bom: Bill of Materials (SBOM, OBOM, HBOM, SaaSBOM, etc) + mailing-list: Mailing list or discussion group + social: Social media account + chat: Real-time chat platform + documentation: Documentation, guides, or how-to instructions + support: Community or commercial support + source-distribution: + description: The location where the source code distributable can be obtained. + This is often an archive format such as zip or tgz. The source-distribution + type complements use of the version control (vcs) type. + distribution: Direct or repository download location + distribution-intake: The location where a component was published to. This + is often the same as "distribution" but may also include specialized publishing + processes that act as an intermediary. + license: The reference to the license file. If a license URL has been defined + in the license node, it should also be defined as an external reference + for completeness. + build-meta: Build-system specific meta file (i.e. pom.xml, package.json, .nuspec, + etc) + build-system: Reference to an automated build system + release-notes: Reference to release notes + security-contact: Specifies a way to contact the maintainer, supplier, or + provider in the event of a security incident. Common URIs include links + to a disclosure procedure, a mailto (RFC-2368) that specifies an email address, + a tel (RFC-3966) that specifies a phone number, or dns (RFC-4501) that specifies + the records containing DNS Security TXT. + model-card: A model card describes the intended uses of a machine learning + model, potential limitations, biases, ethical considerations, training parameters, + datasets used to train the model, performance metrics, and other relevant + data useful for ML transparency. + log: A record of events that occurred in a computer system or application, + such as problems, errors, or information on current operations. + configuration: Parameters or settings that may be used by other components + or services. + evidence: Information used to substantiate a claim. + formulation: Describes how a component or service was manufactured or deployed. + attestation: Human or machine-readable statements containing facts, evidence, + or testimony. + threat-model: An enumeration of identified weaknesses, threats, and countermeasures, + dataflow diagram (DFD), attack tree, and other supporting documentation + in human-readable or machine-readable format. + adversary-model: The defined assumptions, goals, and capabilities of an adversary. + risk-assessment: Identifies and analyzes the potential of future events that + may negatively impact individuals, assets, and/or the environment. Risk + assessments may also include judgments on the tolerability of each risk. + vulnerability-assertion: A Vulnerability Disclosure Report (VDR) which asserts + the known and previously unknown vulnerabilities that affect a component, + service, or product including the analysis and findings describing the impact + (or lack of impact) that the reported vulnerability has on a component, + service, or product. + exploitability-statement: A Vulnerability Exploitability eXchange (VEX) which + asserts the known vulnerabilities that do not affect a product, product + family, or organization, and optionally the ones that do. The VEX should + include the analysis and findings describing the impact (or lack of impact) + that the reported vulnerability has on the product, product family, or organization. + pentest-report: Results from an authorized simulated cyberattack on a component + or service, otherwise known as a penetration test. + static-analysis-report: SARIF or proprietary machine or human-readable report + for which static analysis has identified code quality, security, and other + potential issues with the source code. + dynamic-analysis-report: Dynamic analysis report that has identified issues + such as vulnerabilities and misconfigurations. + runtime-analysis-report: Report generated by analyzing the call stack of a + running application. + component-analysis-report: Report generated by Software Composition Analysis + (SCA), container analysis, or other forms of component analysis. + maturity-report: Report containing a formal assessment of an organization, + business unit, or team against a maturity model. + certification-report: Industry, regulatory, or other certification from an + accredited (if applicable) certification body. + codified-infrastructure: Code or configuration that defines and provisions + virtualized infrastructure, commonly referred to as Infrastructure as Code + (IaC). + quality-metrics: Report or system in which quality metrics can be obtained. + poam: Plans of Action and Milestones (POAM) complement an "attestation" external + reference. POAM is defined by NIST as a "document that identifies tasks + needing to be accomplished. It details resources required to accomplish + the elements of the plan, any milestones in meeting the tasks and scheduled + completion dates for the milestones". + electronic-signature: An e-signature is commonly a scanned representation + of a written signature or a stylized script of the person's name. + digital-signature: A signature that leverages cryptography, typically public/private + key pairs, which provides strong authenticity verification. + rfc-9116: Document that complies with RFC-9116 (A File Format to Aid in Security + Vulnerability Disclosure) + other: Use this if no other types accurately describe the purpose of the external + reference. + 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 content: application/json: {} - 400_invalid_request: + 400-invalid-request: description: Request was Invalid content: application/json: {} @@ -551,27 +549,27 @@ components: description: Authentication required content: application/json: {} - 404_object_by_id_not_found: + 404-object-by-id-not-found: 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: - name: page_offset + page-offset: + name: page-offset description: Pagination offset in: query required: false @@ -579,8 +577,8 @@ components: type: number format: int64 default: 0 - page_size: - name: page_size + page-size: + name: page-size description: Pagination offset in: query required: false @@ -609,8 +607,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 \ No newline at end of file + url: https://github.com/CycloneDX/transparency-exchange-api