Skip to content

Package mappings

Some components have no package URL that any advisory database knows. A vendor SDK taken from GitHub is a typical case. Affectra cannot find its vulnerabilities by itself. A package mapping tells it which CPE name the package has in the NVD. Then Affectra matches the package against the NVD data, and the findings appear in your releases.

A mapping applies to your organization only. It changes your findings and nobody else’s.

You need a mapping when all of this is true:

  • the component has no package URL in a supported ecosystem such as npm, PyPI or Debian;
  • the SBOM does not give a CPE for it;
  • Affectra’s own list of known packages does not cover it;
  • the component has a version.

If a package URL is in an ecosystem that Affectra reads from OSV, such as npm, PyPI or Debian, you never need a mapping, and Affectra refuses one. It uses the advisories of that ecosystem instead. How matching works explains the order, and Why a finding is or isn’t shown the rules for mappings.

The line above the findings of a release says how many components were checkable. A component that cannot be checked often needs a mapping.

Everyone can read the mappings. Only an admin or an owner can add or delete one.

  1. Look up the vendor and product in NVD’s CPE dictionary. For the Zephyr RTOS, for example, the vendor is zephyrproject and the product is zephyr.
  2. Open Package mappings under Organization in the app.
  3. Under Add a mapping, enter the Package URL without a version, such as pkg:github/zephyrproject-rtos/zephyr. Each SBOM supplies the version.
  4. Enter the NVD vendor and the NVD product, for example zephyrproject and zephyr.
  5. Select Add mapping.

Affectra checks the form:

  • The package URL has no version, qualifiers or subpath.
  • Vendor and product use lower case letters, digits and ., _, -, ~, as in the NVD.
  • The mapping is not one that is already built in. The list Built in shows the mappings that Affectra maintains for every organization, so you can see what is covered. To get a public package added there, ask Affectra.

The mapping applies to components with exactly this package. pkg:github/acme/lib does not apply to pkg:github/acme/lib-extra.

The list shows how many NVD records name the vendor and product, for example 12 NVD records. If it says NVD has no records for this name, check the spelling in NVD’s CPE dictionary. There may be no vulnerabilities, or the name may be wrong. A mapping with a wrong name matches nothing.

After you add a mapping, Affectra matches again on its next pass. Then open a release that has the package. Findings that came through your mapping carry the tag your mapping, and Details shows in its timeline that the finding came through it. See Assess findings with VEX.

NVD matches are broader than advisories of an ecosystem. Affectra reads the NVD’s list of affected products without conditions, so a finding can show although your build is not affected. Record that with a VEX statement.

Select Delete next to the mapping and confirm Delete the mapping of …? Findings it produced disappear. Its findings go away on the next pass. A VEX statement you recorded for such a finding stays in the history.

Many vendors publish their advisories as CSAF documents (see Vendor advisories), but name a device or firmware only by model number, SKU or product name, such as 1138965 or RUGGEDCOM APE1808, not by a package URL or CPE. Affectra can’t tell by itself that one of your packages is that product. A vendor product mapping says so. Then the vendor’s advisories match the package, in your organization’s findings only.

The section Vendor products on the same page lists your organization’s vendor product mappings. To add one, as an admin or owner:

  1. Under Add a vendor product mapping, choose the Advisory source, such as Siemens ProductCERT. Only sources whose advisories are loaded are listed.
  2. Enter part of the model number, SKU or product name under Find a product and select Search. The results list each model number, SKU and product name the source’s advisories use, and how many advisories name it.
  3. Select Use next to the right one. It fills in Matched by (model number, SKU or product name) and Value. You can also type them yourself.
  4. Under Your package, enter the package URL without a version, such as pkg:generic/acme/plc-firmware. Each SBOM supplies the version.
  5. Select Add product mapping.

Affectra stores the value trimmed, in lower case and with single spaces, and compares the advisories’ values the same way. The list shows how many advisories name the value. If it says No loaded advisory names this value, check the spelling, or the source may not be loaded.

A component without a package URL can’t be mapped, neither to a vendor product nor to an NVD name. Packages in ecosystems that Affectra reads from OSV are refused, as for NVD mappings.

The version comes from the package URL in each SBOM. A product the advisory calls known affected matches when:

  • the advisory gives that exact version, or a vers: range that contains it; or
  • the advisory says every version is affected (vers:all/*). Without a mapping that is never a finding; with one, you have said the package is that product, so it is.

If the advisory also says a version at or below yours is fixed, there is no finding. A range the advisory gives only in words, such as “FW <1.7.4”, never matches.

Findings that came through a vendor product mapping carry the tag your mapping, and the timeline under Details names the mapping. Deleting the mapping removes its findings at once. Agents can’t propose vendor product mappings yet.

An AI agent with an API key that can propose changes can propose an NVD mapping. The proposal appears under Proposals. Only an admin accepts or rejects it, because only an admin creates mappings. See Assess findings with VEX.