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.
Tell Affectra which release a unit runs
Section titled “Tell Affectra which release a unit runs”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.0or KEY=value lines:
PRODUCT=gatewayVARIANT=euVERSION=2.1.0VERSIONis the version of the release the unit runs.PRODUCTis the product key of the product in Affectra.VARIANTis the name of the variant. Without it, the unit belongs to thedefaultvariant.
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:
- the release with that product key, variant and version;
- else a release alias: a version text that an admin linked to a release by hand;
- 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.
Link units that report an unknown version
Section titled “Link units that report an unknown version”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.
See which units a vulnerability affects
Section titled “See which units a vulnerability affects”- Open Fleet lookup.
- Under Package, enter the package, such as
openssl. Under Fixed in version, enter the first version without the vulnerability, such as1.1.1n-0+deb11u4. - 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.
See which units to upgrade
Section titled “See which units to upgrade”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.
See what a unit is affected by
Section titled “See what a unit is affected by”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.
Read units through the API
Section titled “Read units through the API”GET /v1/orgs/{org}/units (or GET /v1/units with an API key) lists the units a page at a time:
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/statscounts the units, the stale ones and those that report through bundles, and lists the releases they report.to_upgradeandcan_upgradeare the units to upgrade and those of them that can upgrade now.