Skip to content

Products, variants and releases

Affectra organizes what you ship in three levels:

  • A product is something you build and ship, such as a gateway or a controller.
  • A variant is a build of a product that gets its own releases: a hardware revision, a platform, an edition or a SKU.
  • A release is one version of a product, or of one of its variants. SBOMs, findings and VEX statements belong to a release.

A product with a single build does not need a variant. Its releases go into a variant that Affectra calls default, and the app does not show that level.

Pick one way to write each name and keep it. CI names a release with three values:

Value What it is Example
Product The product’s name. Gateway
Variant The name of a variant. Optional. rev-b, linux-arm64, pro
Version The release’s version. 1.4.0
  • A product name is unique in your organization. A variant name is unique in its product. A version is unique in its variant.
  • Names are matched exactly, including case. gateway and Gateway are two products.
  • Use the version your firmware reports, with the same prefix. If your units report v1.4.0, name the release v1.4.0, not 1.4.0. See Find affected units.
  • On a tag build, the tag name is a good version. In GitHub Actions it is github.ref_name.

Whatever does not exist yet is created when you upload. A new version needs no setup in Affectra. The upload tells CI what it created. The action prints a warning when it created a product or a variant, because a typo creates a new product, and a notice when it created a release. If that was a typo, delete the stray product or variant in the app and correct the name in the workflow.

You can also create them in the app. Under Releases, select Add product. In a product, select Add release, or Add variant if it has several builds.

Releases always come newest version first, so 1.10.0 comes before 1.9.2. If a version is not made of numbers, such as R12b, it comes after the numbered ones, the last added first.

  • Releases shows each product as a card with its newest 6 releases for each variant, with their open findings and whether they are signed. If there are more, Show all opens the product, and a line tells you how many of the older releases have open findings and how many of those are known exploited.
  • A product lists all its releases in a table: version, variant (for a product with several variants), release date, open findings, whether the SBOMs are signed, and whether there is an SBOM. Search by part of the version, pick a variant, or select Only with open findings. The table loads 25 releases at a time. Select Load more for the next ones.

The API has the same order in two places:

  • GET /v1/orgs/acme/catalog/overview returns every product with its variants. Each variant has its newest releases, 6 unless you set releases, and counts how many of its other releases have open or known-exploited findings.
  • GET /v1/orgs/acme/products/{product}/releases returns a product’s releases one page at a time. Filter by variant, by part of the version with q, or with open=true for releases with open findings. To get the next page, send the response’s next as after.

In both, a version made of numbers comes first, newest first. 2.0.0 comes before its pre-releases, such as 2.0.0-rc.1. Other versions follow, newest added first. Each release has its number of SBOMs and its open, known-exploited, affected and resolved findings, counted as on the overview. Open minus affected is what is still to assess. GET /v1/orgs/acme/variants/{variant}/releases lists one variant’s releases in the order they were added.

Use a variant when one product has builds that need their own SBOMs and findings. Typical cases:

  • board revisions, such as rev-a and rev-b;
  • platforms, such as linux-arm64 and linux-amd64;
  • editions, such as standard and pro;
  • SKUs that differ only in software.

Releases of different variants can have the same version. rev-a and rev-b can both have 1.4.0, and each has its own SBOMs and findings.

Leave the variant out in CI for a product with a single build. The release then goes into the default variant. If you add a named variant to such a product later, the existing releases stay in default. If you rename default, the next upload without a variant creates a new default.

An admin can set two more things on a product, under Product key and support:

  • Product key. A short name for the product: lowercase letters, digits and hyphens, up to 63 characters, such as edge-gateway. Your firmware reports it as PRODUCT=<key>, so that Affectra can link a unit to the product’s releases. It is not a licence key, and CI does not use it. CI uses the product’s name. A key is unique in your organization. Once units are linked to the product through it, it cannot be changed.
  • Support ends. The last day the product gets security updates, for the support period the Cyber Resilience Act asks for. Once the date has passed, the overview lists the product’s releases last under Most exposed releases, with an Out of support label. Their findings still count, in the release and in the totals on the overview. A product with no support end counts as supported.

A unit may report a version that matches no release, such as 2.3-hotfix on a unit that was patched by hand. An admin can link that text to a release under Units, in Unlinked firmware. The text becomes an alias. The units that report it, now and later, are linked to the release. An alias applies when product key, variant and version name no release. See Find affected units.

Roles and what each may do has the full table.

  • A member can add products, variants and releases, and upload SBOMs. An API key that can propose changes can upload.
  • An admin can also set the product key and the support end, add aliases, and delete products, variants and releases. Deleting a product deletes its variants, releases and SBOMs. Deleting a variant deletes its releases and SBOMs. The app asks you to confirm. A release with VEX statements cannot be deleted, and neither can its variant or product: statements are kept as evidence. See Evidence is only added to.