Upload SBOMs from other CI
Any CI system can upload an SBOM to Affectra. One HTTP request per file is enough. Use this page for GitLab CI, Jenkins, Azure Pipelines, a build script or your own machine. For GitHub Actions, the action does the same and needs no secret when you trust the repository.
Before you start, you need:
- an SBOM file from your build. See Supported SBOM formats;
- the address of your Affectra instance and the slug of your organization, which you see in the address of the app;
- an API key. In the app, open API keys, select Create a key, give it a name, and set Access to Can propose changes. A Read only key cannot upload. Copy the key. It is shown once.
Keep the key in the environment
Section titled “Keep the key in the environment”Store the key in your CI system’s secret store, and give it to the job as an environment variable named AFFECTRA_API_KEY. Do not write the key into a script or a command line. A key on a command line shows up in the process list and in shell history, and a key in a repository is a leaked key.
The examples show a made-up key so that you can see the form. It is not a real key:
export AFFECTRA_API_KEY=exk_example_not_a_real_keyUse one key per pipeline, so you can revoke one without touching the others. If a key leaks, revoke it under API keys. It stops working at once.
Upload an SBOM
Section titled “Upload an SBOM”Send the file as the body of one request. Name the release with the product, optionally the variant, and the version. Whatever does not exist yet is created.
curl --fail-with-body --silent --show-error \ --request POST \ --header "Authorization: Bearer $AFFECTRA_API_KEY" \ --header "Content-Type: application/octet-stream" \ --data-binary @sbom.cdx.json \ "https://affectra.example.com/v1/orgs/acme/sbom-uploads?product=Gateway&variant=rev-b&version=1.4.0" \ > upload.json--fail-with-bodymakes curl exit with an error on an HTTP error status, and still prints Affectra’s answer, which says why. It needs curl 7.76 or later. On an older curl, use--fail. Without either, a failed upload looks like a success to your CI.- The
acmein the path is your organization. The key must belong to it. - Encode the names for a URL: a space is
%20. Leave outvariantfor a product with one build. The release then goes into the product’sdefaultvariant. - Add
released_at=2026-11-05T12:00:00Z, an RFC 3339 time, to set the release date. It is used only when the release is created. - Names are matched exactly, including case.
gatewayandGatewayare two products.
The answer is JSON. A 201 means Affectra stored a new SBOM. A 200 means the release already had this exact file, and nothing changed, so repeating an upload is safe. The body holds:
sbom: the stored SBOM, with its format, number of components andsignature_status;product,variantandrelease: the names you sent, with their IDs;new: which of the three this upload created. Ifnew.productistrueand you did not mean to add a product, you probably mistyped the name;warnings: problems that did not stop the upload, such as an invalid package URL.
To keep the release ID for the next steps:
release=$(jq --raw-output '.release.id' upload.json)Check the result
Section titled “Check the result”Read the release back with the same key:
curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $AFFECTRA_API_KEY" \ "https://affectra.example.com/v1/orgs/acme/releases/$release/sboms"It lists the release’s SBOMs. Vulnerabilities appear once Affectra has matched the components, usually within a minute:
curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $AFFECTRA_API_KEY" \ "https://affectra.example.com/v1/orgs/acme/releases/$release/vulnerabilities"The answer is a page: items holds up to 50 advisories, most urgent first, and more says whether others follow. Ask for the next page with after set to the answer’s next, and limit (up to 200) sets the page size. That list has one item per advisory, so a CVE that several sources publish appears more than once. Each item’s groups names the finding groups it belongs to, and the number of distinct groups is the number of problems the release has. To read them one by one, one item per CVE, ask for the groups:
curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $AFFECTRA_API_KEY" \ "https://affectra.example.com/v1/orgs/acme/releases/$release/finding-groups"A group lists its advisories as members, the components they matched, and a conflict when one advisory says a component is affected and another with the same CVE says its version is not. Both lists leave out what a VEX statement resolved, unless you add ?include=resolved, and both come a page at a time. To read every finding group of a release:
url="https://affectra.example.com/v1/orgs/acme/releases/$release/finding-groups?limit=200"after=""while :; do page=$(curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $AFFECTRA_API_KEY" \ "$url${after:+&after=$after}") echo "$page" | jq --compact-output '.items[]' [ "$(echo "$page" | jq '.more')" = true ] || break after=$(echo "$page" | jq --raw-output '.next')doneYou can also open the release in the app, under Releases. Its SBOMs tab lists the file, and its Vulnerabilities tab lists the findings. Assess findings with VEX says what to do with them.
Create the release first
Section titled “Create the release first”You do not have to. If you prefer to create the product and release yourself, do it in the app under Releases with Add product and Add release, and upload to the release by name as above. The API for this takes product and release IDs: POST /v1/orgs/acme/products, POST /v1/orgs/acme/products/{product}/releases for a product with one build, and POST /v1/orgs/acme/releases/{release}/sboms to upload to a release by its ID. Using the API covers credentials, errors and rate limits. The routes are in the API reference.
Upload several files
Section titled “Upload several files”Each file is its own request, to the same release names:
for f in build/sbom/*.cdx.json; do curl --fail-with-body --silent --show-error \ --request POST \ --header "Authorization: Bearer $AFFECTRA_API_KEY" \ --header "Content-Type: application/octet-stream" \ --data-binary @"$f" \ "https://affectra.example.com/v1/orgs/acme/sbom-uploads?product=Gateway&version=1.4.0"doneUpload a signed SBOM
Section titled “Upload a signed SBOM”Send the SBOM and its signature bundle together as a form. See Sign SBOMs.
When it fails
Section titled “When it fails”Affectra answers errors as JSON with a code and a detail. Read the detail, and match on the code in scripts.
| Status | Meaning |
|---|---|
| 400 | The file is not a supported SBOM, product or version is missing, released_at is not an RFC 3339 time, or a signature does not verify. |
| 401 | The key is wrong or revoked. |
| 403 | The key can only read, or your organization requires signed uploads and this one has no signature from a trusted publisher. |
| 404 | The organization in the path is not the key’s organization. |
| 413 | The file is larger than 16 MiB, or has more than 30,000 components or 150,000 dependencies. See SBOM formats. |
| 429 | Too many uploads in a short time, or the service is busy with other uploads. Wait for the number of seconds in the Retry-After header, then try again. |
A 5xx answer or a connection error is safe to retry, because repeating an upload changes nothing.