diff --git a/api-flow/consumer.md b/api-flow/consumer.md index 1bd7137..3451ecb 100644 --- a/api-flow/consumer.md +++ b/api-flow/consumer.md @@ -23,8 +23,18 @@ Component Release) to find the list of artefacts for the particular Product Rele ## API flow based on TEI discovery ```mermaid - --- +config: + sequence: + diagramMarginX: 60 + diagramMarginY: 40 + actorFontSize: 20 + actorFontWeight: bold + noteFontSize: 18 + theme: neo dark + layout: elk + look: neo + title: TEA consumer flow --- sequenceDiagram @@ -60,7 +70,6 @@ sequenceDiagram user ->> tea_component_release: Obtain latest collections tea_component_release -->> user: List of TEA Artifacts end - ``` ## API flow based on direct access to API @@ -70,6 +79,16 @@ In this case, the client wants to search for a specific product release using th ```mermaid --- +config: + sequence: + diagramMarginX: 60 + diagramMarginY: 40 + actorFontSize: 20 + actorFontWeight: bold + noteFontSize: 18 + theme: neo dark + layout: elk + look: neo title: TEA client flow with search --- @@ -109,6 +128,16 @@ for a release. ```mermaid --- +config: + sequence: + diagramMarginX: 60 + diagramMarginY: 40 + actorFontSize: 20 + actorFontWeight: bold + noteFontSize: 18 + theme: neo dark + layout: elk + look: neo title: TEA client flow with direct query for release --- @@ -137,6 +166,16 @@ another query is done to get reason for update and new collection list of artefa ```mermaid --- +config: + sequence: + diagramMarginX: 60 + diagramMarginY: 40 + actorFontSize: 20 + actorFontWeight: bold + noteFontSize: 18 + theme: neo + layout: elk + look: neo title: TEA client collection query --- diff --git a/doc/authorization.md b/doc/authorization.md new file mode 100644 index 0000000..a8a317f --- /dev/null +++ b/doc/authorization.md @@ -0,0 +1,98 @@ +# Authorization + +The Transparency Exchange API (TEA) uses a scope-based authorization model. Permissions are granted through scopes assigned to authenticated identities. Scopes follow a hierarchical structure with read operations generally requiring fewer permissions than write operations. + +## Scope Model + +Scopes are granted to identities during authentication. Bearer tokens include scopes in the `scope` claim as a space-separated list. mTLS certificates are mapped to scopes through server configuration. + +### Scope Hierarchy + +``` +SCOPE_ADMIN_FULL (admin) +├── SCOPE_PUBLISHER_* (publisher) +│ ├── SCOPE_PUBLISHER_PRODUCTS_WRITE +│ ├── SCOPE_PUBLISHER_COMPONENTS_WRITE +│ ├── SCOPE_PUBLISHER_RELEASES_WRITE +│ ├── SCOPE_PUBLISHER_ARTIFACTS_WRITE +│ └── SCOPE_PUBLISHER_COLLECTIONS_WRITE +└── SCOPE_CONSUMER_* (consumer) + ├── SCOPE_CONSUMER_PRODUCTS_READ + ├── SCOPE_CONSUMER_COMPONENTS_READ + ├── SCOPE_CONSUMER_COLLECTIONS_READ + ├── SCOPE_CONSUMER_ARTIFACTS_READ + ├── SCOPE_CONSUMER_ARTIFACTS_DOWNLOAD + └── SCOPE_CONSUMER_INSIGHTS_QUERY +``` + +## Consumer Scopes + +### Read Operations + +- `SCOPE_CONSUMER_PRODUCTS_READ`: List and retrieve product metadata +- `SCOPE_CONSUMER_COMPONENTS_READ`: List and retrieve component metadata +- `SCOPE_CONSUMER_COLLECTIONS_READ`: Access collection metadata and versions +- `SCOPE_CONSUMER_ARTIFACTS_READ`: Retrieve artifact metadata +- `SCOPE_CONSUMER_ARTIFACTS_DOWNLOAD`: Download artifact content +- `SCOPE_CONSUMER_INSIGHTS_QUERY`: Execute CEL-based queries and searches + +## Publisher Scopes + +### Write Operations + +- `SCOPE_PUBLISHER_PRODUCTS_WRITE`: Create, update, delete products +- `SCOPE_PUBLISHER_COMPONENTS_WRITE`: Create, update, delete components +- `SCOPE_PUBLISHER_RELEASES_WRITE`: Create, update product/component releases +- `SCOPE_PUBLISHER_ARTIFACTS_WRITE`: Upload and delete artifacts +- `SCOPE_PUBLISHER_COLLECTIONS_WRITE`: Create and update collections + +## Admin Scopes + +### Administrative Operations + +- `SCOPE_ADMIN_FULL`: Full administrative access including user management, system configuration, and audit functions + +## Authorization Logic + +### API Endpoint Requirements + +| Endpoint | Required Scopes | +| ----------------------------- | ----------------------------------- | +| `GET /.well-known/tea` | None (public) | +| `GET /v1/discovery` | None (public) | +| `GET /v1/products*` | `SCOPE_CONSUMER_PRODUCTS_READ` | +| `GET /v1/components*` | `SCOPE_CONSUMER_COMPONENTS_READ` | +| `GET /v1/collections*` | `SCOPE_CONSUMER_COLLECTIONS_READ` | +| `GET /v1/artifacts*` | `SCOPE_CONSUMER_ARTIFACTS_READ` | +| `GET /v1/artifacts/*/content` | `SCOPE_CONSUMER_ARTIFACTS_DOWNLOAD` | +| `POST /v1/insights/*` | `SCOPE_CONSUMER_INSIGHTS_QUERY` | +| `POST /v1/publisher/*` | Publisher scopes as above | + +### Scope Validation + +Servers MUST validate that the authenticated identity possesses all required scopes for the requested operation. Missing scopes result in `403 Forbidden` responses. + +### Scope Granularity + +Scopes are intentionally coarse-grained to simplify implementation. Fine-grained access control (e.g., per-object permissions) is not supported in the base specification but may be implemented as extensions. + +## Authorization Flow + +```mermaid +flowchart TD + A[Request] --> B[Authenticate] + B --> C{Valid Identity?} + C -->|No| D[401 Unauthorized] + C -->|Yes| E[Extract Scopes] + E --> F{Required Scopes?} + F -->|No| G[403 Forbidden] + F -->|Yes| H[Process Request] + H --> I[Response] +``` + +## Security Considerations + +- Implement least privilege: grant only necessary scopes +- Regularly rotate credentials and review scope assignments +- Audit authorization decisions for compliance +- Consider scope expiration for temporary access diff --git a/doc/tea-requirements.md b/doc/tea-requirements.md index c60a1e6..2f8b070 100644 --- a/doc/tea-requirements.md +++ b/doc/tea-requirements.md @@ -1,6 +1,7 @@ # TEA Requirements ## Repository discovery + Based on an identifier a repository URL needs to be found. The identifier can be: - PURL @@ -34,6 +35,9 @@ Collections are OPTIONAL. - VDR - Vulnerability Disclosure Report - VEX - Vulnerability Exploitability eXchange - CDXA - Attestation +- ML-BOM - Machine Learning Bill of Material (profile of SBOM) +- DATA-BOM - Data Bill of Material (profile of SBOM) +- AI-BOM - Artificial Intelligence Bill of Material (profile of SBOM) Authn/Authz MUST be supported @@ -61,7 +65,7 @@ Authn/Authz MUST be supported ## Artefact Publishing -The API MUST provide a way to publish an artefact, either standalone or to a collection. +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 @@ -85,11 +89,11 @@ PURL, CPE, SWID, GAV, GTIN, and GMN. For example: -- Return the identity of all BOMs that have a vulnerable version of Apache Log4J: +- Return the identity of all BOMs that have a vulnerable version of Apache Log4J: `pkg:maven/org.apache.logging.log4j/log4j-core@2.10.0` -The API MUST provide a way to search for the metadata component across all available BOMs. -The API SHOULD support multiple identity formats including PURL, CPE, SWID, GAV, GTIN, and GMN. +The API MUST provide a way to search for the metadata component across all available BOMs. +The API SHOULD support multiple identity formats including PURL, CPE, SWID, GAV, GTIN, and GMN. For example: - Return the identity of all artefacts that describe `cpe:/a:acme:commerce_suite:1.0`. diff --git a/doc/tea-usecases.md b/doc/tea-usecases.md index bd3b702..916a6a9 100644 --- a/doc/tea-usecases.md +++ b/doc/tea-usecases.md @@ -6,10 +6,10 @@ a..." The use cases are divided in two categories: -* Use cases for __customers__ (end-users, manufacturers) to find a repository with +* Use cases for __customers__ (end-users, manufacturers) to find a repository with 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 + * This applies after discovery where we need to handle various things a customer may buy as a single unit ## Customer focused use cases @@ -18,18 +18,17 @@ The use cases are divided in two categories: As a consumer that has an SBOM for a product, I want to be able to retrieve VEX and VDR files automatically both for current and old versions of the software. In the SBOM the product is identified by a PURL or other means (CPE, …) - ### C2: Consumer: Automation based on product name/identifier 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 +After discovering the base repository URL I want to be able to find a specific 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: Artefact retrieval +### C3: Consumer: Artefact retrieval 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. @@ -42,8 +41,8 @@ A CLE captures all lifecycle events over time, however, there is a need to retri As a consumer, I want the ability to simply ask the API questions rather than having to download, 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). +provided by the API by default along with the ability to query for more complex answers using +the Common Expression Language (CEL). _NOTE_: Project Hyades (Dependency-Track v5) already implements CEL with the CycloneDX object model and has proven that this approach works for complex queries. @@ -82,7 +81,6 @@ They need to make an assessment before starting tests and possible production us The can either use the Debian package, the Alpine Linux Package or build a binary themselves from source code. How can they find the transparency exchange data sets? - ### O1: Open Source project The hatturl open source project publish a library and a server side software on Github. This is diff --git a/doc/versioning.md b/doc/versioning.md new file mode 100644 index 0000000..f91330c --- /dev/null +++ b/doc/versioning.md @@ -0,0 +1,146 @@ +# Versioning + +The Transparency Exchange API (TEA) uses semantic versioning for API evolution. This document describes the versioning strategy, compatibility guarantees, and migration guidelines. + +## Semantic Versioning + +TEA follows [Semantic Versioning 2.0.0](https://semver.org/) for API versions: + +``` +MAJOR.MINOR.PATCH +``` + +### Version Components + +- **MAJOR**: Breaking changes that require client updates +- **MINOR**: Backward-compatible additions (new endpoints, optional fields) +- **PATCH**: Backward-compatible bug fixes + +### Pre-release Versions + +Pre-release versions use the format: + +``` +MAJOR.MINOR.PATCH-PRERELEASE +``` + +Examples: + +- `1.0.0-alpha.1` +- `1.0.0-beta.2` +- `1.0.0-rc.1` + +## API Versioning Strategy + +### URL Versioning + +API versions are included in the URL path: + +``` +/v{MAJOR}/... +``` + +Current version: `v1` + +### Content Negotiation + +For content that may evolve independently of the API version, use content negotiation with the `Accept` header: + +``` +Accept: application/vnd.cyclonedx+json; version=1.5 +``` + +## Compatibility Guarantees + +### Backward Compatibility + +- **PATCH** versions: Fully backward compatible +- **MINOR** versions: Backward compatible additions only +- **MAJOR** versions: May include breaking changes + +### Forward Compatibility + +Clients SHOULD ignore unknown fields in responses. Servers MUST NOT require unknown fields in requests. + +### Deprecation Policy + +1. Features are marked as deprecated in MINOR releases +2. Deprecated features are removed in the next MAJOR release +3. Deprecation notices include: + - Deprecation version + - Removal version + - Migration guidance + +## Version Discovery + +### Well-Known Endpoint + +Clients discover available API versions through `/.well-known/tea`: + +```json +{ + "schemaVersion": 1, + "endpoints": [ + { + "url": "https://api.example.com/tea/v1", + "versions": ["1.0.0", "1.1.0"], + "priority": 1 + } + ] +} +``` + +### Version Headers + +Servers MAY include version information in responses: + +``` +X-API-Version: 1.0.0 +``` + +## Migration Guidelines + +### Minor Version Upgrades + +1. Review release notes for new features +2. Update client code to handle new optional fields +3. Test with new version in staging environment +4. Gradually roll out updated clients + +### Major Version Upgrades + +1. Review breaking changes documentation +2. Update client code for required changes +3. Implement feature flags if needed +4. Test extensively in staging +5. Plan rollback strategy +6. Execute blue-green deployment + +### Testing Strategy + +- Maintain test suites for multiple API versions during transition periods +- Use contract testing to validate compatibility +- Implement canary deployments for gradual rollout + +## Implementation Considerations + +### Server-Side + +- Support multiple concurrent API versions +- Use version-aware routing +- Implement graceful degradation for older clients +- Provide version-specific documentation + +### Client-Side + +- Implement version negotiation logic +- Handle version-specific response formats +- Provide upgrade prompts for deprecated versions +- Support fallback to older versions when possible + +## Version Support Policy + +- Current MAJOR version receives active development and support +- Previous MAJOR version receives security updates only +- Versions older than N-1 MAJOR releases are deprecated +- Deprecation notices provided 6 months before end of support