How matching works
Matching is how Affectra turns an SBOM into findings. For every component it asks: which known vulnerabilities affect this package at this version? This page explains the names it uses and what it guarantees. Why a finding is or isn’t shown has the exact rules.
Two ways to name a package
Section titled “Two ways to name a package”Package URL (purl). A purl names a package by its ecosystem, name and version, for example pkg:npm/lodash@4.17.21 or pkg:deb/debian/openssl@3.0.11-1~deb12u2. Most SBOM tools write one for each component. Affectra writes every purl in one canonical form, so the same package always looks the same.
CPE. A CPE is the way the NVD names products, as a vendor and a product, for example espressif:esp-idf. Many firmware components have no ecosystem and no purl, only a CPE, or nothing.
Affectra matches by purl first. It matches by CPE, and against vendor advisories, only for components that a purl in a supported ecosystem cannot describe.
| A component has | Affectra matches it against | A finding is marked |
|---|---|---|
| A purl with a version in a supported ecosystem | Advisories of that ecosystem (OSV) | no mark |
| No such purl, but a vendor advisory names the package by purl | That vendor advisory | no mark |
| No such purl, but the SBOM gives a CPE (private components only), or Affectra knows the package’s CPE name | NVD and vendor advisories, by CPE | CPE |
| No such purl, and you mapped it | NVD and vendor advisories, by your CPE | your mapping |
The supported ecosystems are Debian, Ubuntu, Alpine, npm, Go, crates.io, PyPI, Maven, RubyGems, NuGet and Packagist. Vulnerability sources lists the data behind them.
If a purl is in a supported ecosystem, Affectra never tries a CPE for that component, even when the advisories have nothing on it. The advisories of the ecosystem are the better answer.
A component with no version cannot be matched. Neither can an advisory that names no version: one that says “all versions” is affected leaves nothing to compare, so it never creates a finding by itself.
One finding for several advisories
Section titled “One finding for several advisories”The same CVE often appears in several advisories: the NVD’s record, an OSV advisory, a coordinator’s CSAF advisory and the vendor’s own. When several of them match the same component, the release shows one finding, from the most authoritative:
- the vendor’s own advisory;
- a coordinator’s advisory, such as BSI’s or CISA’s;
- OSV;
- the NVD.
The release has one row for the CVE, a finding group, and lists every advisory on it as a chip, with links. The best-ranked supplies the title when the NVD isn’t one of them. Advisories that name a component and say its version is not affected show as hollow chips, and the row says Sources disagree. An advisory with several CVEs is in the row of each. An advisory without a CVE is a row of its own, or shares one with the advisories without a CVE that it names as aliases, such as the Go and GitHub advisories for the same problem. Every count, such as the tab’s number, the totals on the overview and the notifications, is of rows, so a CVE counts once. A VEX statement on the CVE decides for the whole row. See Assess findings with VEX.
Package mappings
Section titled “Package mappings”Firmware often contains packages that no advisory database names by purl, such as a vendor SDK taken from GitHub. For these you can tell Affectra which CPE a package corresponds to. That is a package mapping. It applies to your organization only, so it changes your findings and nobody else’s. Package mappings shows how to add one.
An agent can propose a mapping. An admin decides.
Shared and private components
Section titled “Shared and private components”Affectra stores each public package once, however many organizations use it. Such a component is shared. A component is shared when it is a public package in a known ecosystem with a version, and its purl does not point at a private repository.
A component is private to your organization when it is vendor code, such as a generic package, or when its purl names a repository_url, vcs_url or download_url.
You can check what follows from this:
- Findings of a shared package depend only on public data. Your upload cannot change another organization’s results, and theirs cannot change yours. For a shared package, a CPE written in an SBOM is ignored, because it is one organization’s claim.
- Nobody learns which packages you use. Another organization sees only findings of components in its own releases.
- Your mappings are yours. They add findings to your releases only.
Your component lists never leave Affectra
Section titled “Your component lists never leave Affectra”Matching runs inside Affectra, against a copy of the public sources that Affectra keeps up to date. Affectra downloads whole public data sets, for example all npm advisories. It never asks a source about a particular package, so no source learns what is in your products. You can see the sources in Vulnerability sources, and every one is a public download.
When matching runs again
Section titled “When matching runs again”A finding is not a one-time result. Affectra matches again when:
- You upload an SBOM. Its new components are matched within seconds.
- Advisory data changes. When a new load of OSV, NVD or vendor advisory data arrives, every component is matched again. A new advisory can add a finding to a release you uploaded months ago, and a corrected advisory can remove one.
- You add or delete a mapping. The mapping takes effect on the next pass, and its findings go away when you delete it.
New KEV or EPSS data needs no new match. They show on existing findings as soon as they refresh.
Each release shows how current its results are. See Assess findings with VEX.