The CBOM Repository service acts as an object storage wrapper built on top of an S3-compatible backend. It provides a convenient REST API for uploading, retrieving, and searching Cryptographic Bills of Materials (CBOM) documents.
Use the provided Helm chart to deploy the service into your Kubernetes cluster. Please refer to the Helm chart README for detailed installation instructions and configuration options.
This project is currently under active development.
- You can explore the current REST API design at OpenAPI Spec.
- To run the service locally or see development notes, please continue to the development guide here.
A summary of the available endpoints and methods are below. For the complete specification please see OpenAPI Spec.
Please note that HTTP API Paths have an additional default prefix /api. You can change it by setting the environment variable APP_HTTP_PREFIX.
| Path | HTTP Method | Required Params | Optional Params | Description |
|---|---|---|---|---|
/v1/bom |
POST |
Contents of BOM in request body and Content-Type header set |
Uploads the supplied BOM to the repository | |
/v1/bom |
GET |
query parameter after |
Retrieves a list of BOM serial numbers and versions that were created later that after timestamp |
|
/v1/bom/{urn} |
GET |
query parameter version |
If optional query parameter version is not supplied, retrieves the latest version of the BOM from repository |
|
/v1/bom/{urn}/versions |
GET |
List all available versions of a BOM identified by its URN |
Let's see each endpoint in greater detail.
The upload operation requires a valid Content-Type header. At this time, only JSON format is supported, and CycloneDX 1.6 and 1.7 are supported.
This means the request must include the header:
Content-Type: application/vnd.cyclonedx+json
Specify the version via the media type, e.g.:
Content-Type: application/vnd.cyclonedx+json; version=1.7
When the version parameter is omitted, the server auto-detects the version from the document's own specVersion — so a client need not declare it.
When version is declared, the server validates against the declared version and rejects (400) a body whose specVersion disagrees. An unsupported version (declared or auto-detected) is also rejected with 400.
When processing uploaded BOMs, the system recognizes several use cases:
- BOM includes both a serial number and a version. The BOM is stored exactly as provided. Subsequent attempts to upload the same serial number and version will result in a 409 Conflict response.
- BOM includes a serial number but no version.
The storage layer is checked for existing BOMs with the same serial number:
- If matching entries are found, the uploaded BOM is assigned the next version number (latest version + 1).
- If none exist, the uploaded BOM is stored as Version 1.
- BOM includes neither a serial number nor a version.
A new URN is generated automatically. Two BOMs are stored:
- The original, potentially cryptographically signed, stored under the new URN with version original.
- A normalized version, where a serial number and version have been assigned, stored under the same URN with version 1.
Upon successful upload, the endpoint returns basic cryptographic statistics about the provided BOM.
This feature is still a work in progress, and both the format and the details reported may evolve over time.
The search operation requires a single query parameter: after, whose value must be a Unix timestamp.
The endpoint responds with a list of URNs along with all versions created after the specified timestamp.
This allows clients to efficiently discover updates without scanning the entire BOM collection.
The get operation retrieves the latest version of a BOM—i.e., the entry with the highest version number—based on the {urn} supplied in the URL path.
The value of {urn} must conform to RFC 4122, meaning it follows the format:
urn:<NID>:<NSS>
Where:
<NID>— Namespace Identifier, which must be exactly uuid for RFC 4122.<NSS>— Namespace-Specific String, which must be a valid UUID.
To retrieve a specific version instead of the latest, you may provide the optional query parameter:
?version=<number>
The following environment variables are used to configure the CBOM-Repository:
| Environment Variable | Required | Default Value | Explanation |
|---|---|---|---|
APP_LOG_LEVEL |
 |
INFO |
logger level, possible values: DEBUG, INFO, WARN, ERROR |
APP_HTTP_PORT |
|
8080 |
HTTP server port |
APP_HTTP_PREFIX |
|
/api |
HTTP server handlers route prefix, mainly used to mount the CBOM Repository handlers under a different starting path |
APP_HTTP_CORS_ALLOWED_ORIGINS |
 |
comma-separated list of browser origins (scheme://host[:port], no path or trailing slash) allowed to read responses cross-origin. Set it to the address of the ILM web console, not of this service — e.g. https://ilm.example.net for a console served there. Required because the console health-checks this service from the operator's browser against the cbomRepositoryUrl platform setting, and a browser only lets the page read the response if the page's own origin is listed. Empty disables CORS. * allows any origin and is intended for development only — this service has no authentication of its own, so every listed origin gets full read and upload access. |
|
APP_S3_ACCESS_KEY |
|
s3-compatible store access key | |
APP_S3_SECRET_KEY |
|
s3-compatible store secret key | |
APP_S3_REGION |
|
s3-compatible store Region | |
APP_S3_ENDPOINT |
|
s3-compatible store endpoint, leave empty for aws roles or default aws env. variables to take precedence | |
APP_S3_BUCKET |
|
Bucket name for the s3-compatible store. Deployment-critical: this value determines where BOMs are stored; changing it on an existing deployment points the service at a different bucket, so previously stored documents become inaccessible (they are not migrated). Keep it stable across upgrades. | |
APP_S3_USE_PATH_STYLE |
|
true |
Use s3 path style |