How matching works

There are two matchers. One connects PURLs to OSV affected entries. The other connects CPE identities to NVD configurations. Both compare the advisory data with versions published on conda-forge.

The matchers do not try to decide whether a vulnerability is exploitable in your environment. They answer a smaller question: is a known conda-forge version inside the range reported by the advisory source?

The version universe

For each package, Basilisk takes the version strings from conda-forge repodata and combines versions from all subdirs into one list.

For now, matching stops at the version. It does not distinguish platforms, builds, or build numbers. This means a patched conda-forge rebuild can still match an upstream advisory for the same version.

Basilisk also assumes that a conda-forge version maps to the same upstream version. The affected-version set keeps the original repodata string.

OSV and PURLs

The osv-purl matcher considers primary and alternative PURLs from purl-associator.

First, the identity and OSV entry need to belong to the same ecosystem. An npm advisory cannot match a PyPI identity just because both packages have the same name.

Names are normalized before the join:

• PyPI names use PEP 503 normalization: lowercase, with runs of -, _, and . treated as the same separator.
• Other ecosystem names are lowercased.
• GitHub repository URLs are lowercased, normalized to HTTPS, and stripped of a trailing .git.

After the identity joins an affected entry, the matcher checks its ranges and explicit version list.

Version comparators

Version rules differ between ecosystems, so Basilisk picks the comparator from the PURL type:

The result records which comparator was used. If that comparator cannot parse a bound, Basilisk does not quietly treat it as open-ended.

OSV range events

OSV stores ranges as events. Basilisk sorts them with the selected comparator and checks each known conda-forge version.

• introduced opens an affected interval.
• fixed closes it and is not itself affected. The interval is [introduced, fixed).
• last_affected closes the interval after that version, so last_affected itself is included.
• introduced: "0" means there is no lower bound.
• Explicit versions are matched against the version strings in the conda-forge universe.

Worked example: an OSV fixed event

This example uses a PyPI identity, so the matcher selects PEP 440.

{
  "identity": "pkg:pypi/pillow",
  "versions": ["9.1.0", "10.1.0", "10.2.0"],
  "latest": "10.2.0"
}

{
  "package": { "ecosystem": "PyPI", "name": "Pillow" },
  "ranges": [{
    "type": "ECOSYSTEM",
    "events": [
      { "introduced": "0" },
      { "fixed": "10.2.0" }
    ]
  }]
}

{
  "matcher": "osv-purl",
  "comparator": "pep440",
  "applicability": "evaluated",
  "affected_versions": ["9.1.0", "10.1.0"],
  "active_on_latest": false
}

An advisory can contain several ranges or affected entries. Basilisk combines the versions found through all entries for the same package, advisory, and identity.

Git commit ranges cannot usually be compared to release versions. If an entry only has a GIT range and no explicit versions, the identity match is kept as unevaluated rather than dropped.

NVD and CPEs

The nvd-cpe matcher joins package CPEs to NVD criteria using the lowercase (vendor, product) pair. It only considers application CPEs (part = a) marked vulnerable: true.

For each matching criterion:

• Inclusive and exclusive bounds are checked against the conda-forge versions.
• A concrete version inside the CPE is treated as an exact version under the comparator.
• A wildcard version without bounds cannot be narrowed to specific versions.

The last case becomes version_unbounded and includes every known version of the package.

Worked example: an NVD upper bound

{
  "criteria": "cpe:2.3:a:zlib:zlib:*:*:*:*:*:*:*:*",
  "versionEndIncluding": "1.2.12",
  "vulnerable": true
}

If the CPE used * for the version and had no bounds, the result would be version_unbounded with all three versions.

Deciding applicability

Each match gets one of three applicability values:

If a range is valid and none of the known versions fall inside it, no match is written.

Applicability and identity confidence are separate. A range can be fully evaluated even when the package identity is still automatic or unverified.

What the API returns

The OSV-compatible query endpoints return evaluated matches by default. Add ?confidence=low to include unevaluated and version_unbounded matches.

Each result can include:

• the affected conda-forge versions,
• whether the latest known version is in that set,
• the comparator,
• the matched PURL or CPE,
• identity status,
• matcher name and version.

active_on_latest uses exact membership in the affected-version set. It does not compare or normalize the latest version a second time.