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.
Name your releases
Section titled “Name your releases”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.
gatewayandGatewayare two products. - Use the version your firmware reports, with the same prefix. If your units report
v1.4.0, name the releasev1.4.0, not1.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.
Find a release
Section titled “Find a release”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/overviewreturns every product with its variants. Each variant has its newest releases, 6 unless you setreleases, and counts how many of its other releases have open or known-exploited findings.GET /v1/orgs/acme/products/{product}/releasesreturns a product’s releases one page at a time. Filter byvariant, by part of the version withq, or withopen=truefor releases with open findings. To get the next page, send the response’snextasafter.
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.
Variants
Section titled “Variants”Use a variant when one product has builds that need their own SBOMs and findings. Typical cases:
- board revisions, such as
rev-aandrev-b; - platforms, such as
linux-arm64andlinux-amd64; - editions, such as
standardandpro; - 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.
Product key and support end
Section titled “Product key and support end”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 asPRODUCT=<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.
Release aliases
Section titled “Release aliases”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.
Who can do what
Section titled “Who can do what”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.
- Upload SBOMs to a release: from GitHub Actions or from other CI.