Skip to content

Find affected units

Affectra can tell you which units run an affected package, and which release each of them runs. For that, a unit has to report its release, and the report has to match one of your releases.

The collector reads the release file /etc/affectra-release on the unit. (/etc/affectra-firmware, the old name, is read too.) The file holds either one line with the version:

v1.0

or KEY=value lines:

PRODUCT=gateway
VARIANT=eu
VERSION=2.1.0
  • VERSION is the version of the release the unit runs.
  • PRODUCT is the product key of the product in Affectra.
  • VARIANT is the name of the variant. Without it, the unit belongs to the default variant.

PRODUCT and VARIANT are optional and at most 100 characters each. Blank lines, unknown keys and spaces around keys and values are ignored, and a value may be in single or double quotes. A file with any = in it is read as KEY=value lines, so a bare version that contains = needs a VERSION= line.

Affectra links the unit to a release in this order:

  1. the release with that product key, variant and version;
  2. else a release alias: a version text that an admin linked to a release by hand;
  3. else, if the report has no PRODUCT, the one release that has that version.

Until a release matches, the unit is listed without a link. It is judged on its own SBOM matches only, and no VEX statement applies to it. A linked unit inherits the findings and the VEX statements of its release.

Under Units in the app, the Unlinked firmware section lists the versions that units report and that name none of your releases. An admin can link each version to a release there. The version then becomes an alias: these units, and any unit that reports the version later, are linked to the release.

If a unit shows unlinked, check its release file first. The product key must be the one of the product in Affectra.

  1. Open Fleet lookup.
  2. Under Package, enter the package, such as openssl. Under Fixed in version, enter the first version without the vulnerability, such as 1.1.1n-0+deb11u4.
  3. Select Check exposure.

Affectra lists the units that run the package below that version. The result shows how many units are affected and what share of your fleet that is, the releases they run, and a table of Affected units with each unit, its release and its delivery (online or bundle). A unit that did not report a release shows unknown.

A unit counts only if its collector reported package URLs. A unit with an old collector is not counted; its page under Units says so, and you update the collector on it.

Only packages of Debian, Ubuntu and Alpine are matched. Units on other distributions are reported but not matched yet. See the collector reference.

A release doesn’t change. Once you assess a finding as Affected, the release stays vulnerable, and your action statement tells customers to move to a release with the fix. What is left to do is in the field: the units that still run that release.

Units to upgrade on the overview counts the units linked to a release that has an open finding that is Affected or known exploited. A known exploited finding counts before you assess it. Other findings that still need your assessment don’t count here; they are under To assess. Units that stopped reporting count too: they are still in the field until you know otherwise.

The hint splits the number:

  • Can upgrade now: a newer release of the same variant has an SBOM and none of those findings open. They are fixed, not affected or not found there. Tell the customers running these units to upgrade.
  • Waiting for a fix: there is no such release yet. Ship one, then these units can upgrade.

Newer means a higher version number, such as 1.1 after 1.0 or 2.0.0 after 2.0.0-rc.1. Select the tile to open these units under Units. The Upgrade filter there shows all of them, those that can upgrade now, or those waiting for a fix.

Only units linked to a release count; see Tell Affectra which release a unit runs.

Under Units, the table shows each unit’s release, its last report, its delivery and its Findings: how many are open and how many a VEX statement resolved. Select a unit to see its installed packages, the collector version it runs and the release it is linked to.

The table lists 50 units at a time, by unit ID; Load more shows the next ones. The search finds units by part of their ID, of the release they report or of a package name, and the filters narrow the list to online or bundle units, to one release, or to the units to upgrade.

A unit that has not reported for 7 days is stale.

GET /v1/orgs/{org}/units (or GET /v1/units with an API key) lists the units a page at a time:

Terminal window
curl -s -H "Authorization: Bearer $AFFECTRA_API_KEY" \
"https://api.example.com/v1/orgs/your-org/units?delivery=bundle&limit=200"

The answer is { "items": [...], "next": "...", "more": true }. While more is true, ask again with after set to next. The units in the list carry package_count instead of their packages. q, delivery (online or bundle), release and upgrade (any, now or waiting) filter the list.

  • GET /v1/orgs/{org}/units/report?unit=<ID> returns one unit with its packages.
  • GET /v1/orgs/{org}/units/stats counts the units, the stale ones and those that report through bundles, and lists the releases they report. to_upgrade and can_upgrade are the units to upgrade and those of them that can upgrade now.