Skip to content

Your first release

In this tutorial you upload the SBOM of one build, see which known vulnerabilities Affectra finds in it, and record your decision on one of them as a VEX statement. It takes about 15 minutes. Most of that is the first matching run, when Affectra loads vulnerability data it does not have yet.

You need:

  • an Affectra account with the member role or higher, and the address of your instance. The app address is the one you sign in at;
  • a terminal with curl 7.76 or later and jq;
  • an SBOM of one of your builds, in CycloneDX or SPDX. Use your own: findings are only interesting when they are about your software. If you have none yet, Supported SBOM formats lists what Affectra reads, and tools such as Syft write one from a directory or a container image. Name the file sbom.cdx.json, or change the name in the commands below.

The key lets curl act for your organization. In the app:

  1. Open API keys under Organization. If you do not see it, you are not an admin. Ask one to create the key.
  2. Under Create a key, enter a Name, for example First release.
  3. Set Access to Can propose changes. A Read only key cannot upload.
  4. Select Create key, then Copy. The key is shown once.
The API keys page with the form Create a key: Name, Access and Used by.

API keys explains the access levels and how to revoke a key.

Put the key and the addresses into the environment of your terminal. Replace the values with yours. The organization is the slug in the address of the app. The key below is made up:

Terminal window
export AFFECTRA_URL=https://affectra.example.com
export AFFECTRA_ORG=acme
export AFFECTRA_API_KEY=exk_example_not_a_real_key

Use the API address of your instance for AFFECTRA_URL. Using the API says which one that is. --fail-with-body in the commands makes curl stop with an error on any HTTP error status, and still print Affectra’s answer, which says why.

Run the commands in the order below, in the directory with sbom.cdx.json. Under each command is the HTTP status that Affectra answers with. To see the status in your terminal, add --include to the command.

1. Check the key

Read the products of your organization. A 200 means the address, the organization and the key are right. A new organization has an empty list.

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $AFFECTRA_API_KEY" \
  "$AFFECTRA_URL/v1/orgs/$AFFECTRA_ORG/products"

Status: 200

2. Upload the SBOM

Send the file as the body of one request. The product and the release do not exist yet, so Affectra creates them. The answer is 201 the first time. If you run the step again with the same file, it is 200 and nothing changes.

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 \
  "$AFFECTRA_URL/v1/orgs/$AFFECTRA_ORG/sbom-uploads?product=Quickstart%20Gateway&version=1.0.0" \
  > answer.json
release=$(jq --raw-output '.release.id' answer.json)

Status: 201 or 200

3. Check the release

List the SBOMs of the release. It holds the file you sent.

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $AFFECTRA_API_KEY" \
  "$AFFECTRA_URL/v1/orgs/$AFFECTRA_ORG/releases/$release/sboms"

Status: 200

4. Read the findings

List the findings of the release. Affectra matches the components in the background, so the list can be empty at first. Run the step again after a minute. On a new installation the first run can take longer, because Affectra first loads the vulnerability data.

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $AFFECTRA_API_KEY" \
  "$AFFECTRA_URL/v1/orgs/$AFFECTRA_ORG/releases/$release/vulnerabilities"

Status: 200

Steps 1 to 3 answer at once. The answer of the upload names the release that Affectra created for Quickstart Gateway version 1.0.0. Upload SBOMs from other CI explains every part of the request, including how to name a variant and what the warnings in the answer mean. To put the next build into the same product, upload with a new version.

  1. Open Releases. The product Quickstart Gateway is in the list.
  2. Select the release 1.0.0.
  3. The Vulnerabilities tab shows the findings. The line above the list says how current they are. If it says that components are still waiting to be matched, wait a minute and reload the page.
The Vulnerabilities tab of a release: one row for each CVE, with its severity, known-exploited and EPSS markers and a chip for each advisory behind it.

Findings are ordered with the known exploited ones first, then by CVSS score, then by EPSS. Each row is one CVE, however many advisories report it. The chips under the title are those advisories. Assess findings with VEX says what each marker on a finding means.

A statement is your decision about one finding on this release. Pick a finding you can judge, for example one in a component that your product includes but never runs.

  1. On the finding, select Assess. The panel Assess a vulnerability opens.
  2. Choose a Status. For a vulnerable component that your product cannot reach, choose Not affected.
  3. Choose a Justification from the list, for example vulnerable_code_not_in_execute_path (The vulnerable code is never run), or write an Impact statement that explains. Not affected needs one of the two.
  4. Select Record statement.
The panel Assess a vulnerability, with the status Not affected and a justification.

The statement is on the CVE, so the whole row is resolved now and drops out of the list of open findings. Select All above the list to see it again. Open the VEX tab of the release: the statement is there, with your name and the time.

The VEX tab of a release with one current statement.

A statement is never edited. To change your mind, record a new statement for the same vulnerability. The old one stays in the history. Assess findings with VEX covers the other statuses, advisories that cover several CVEs, and statements that an AI assistant proposes and you decide.

When you are done with the tutorial, revoke the key if you do not need it again. The product Quickstart Gateway stays: a release with a VEX statement cannot be deleted, because statements are kept as evidence.