Skip to content

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.

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:

Terminal window
export AFFECTRA_API_KEY=exk_example_not_a_real_key

Use 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.

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.

Terminal window
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-body makes 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 acme in the path is your organization. The key must belong to it.
  • Encode the names for a URL: a space is %20. Leave out variant for a product with one build. The release then goes into the product’s default variant.
  • 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. gateway and Gateway are 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 and signature_status;
  • product, variant and release: the names you sent, with their IDs;
  • new: which of the three this upload created. If new.product is true and 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:

Terminal window
release=$(jq --raw-output '.release.id' upload.json)

Read the release back with the same key:

Terminal window
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:

Terminal window
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:

Terminal window
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:

Terminal window
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')
done

You 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.

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.

Each file is its own request, to the same release names:

Terminal window
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"
done

Send the SBOM and its signature bundle together as a form. See Sign SBOMs.

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.