Extended Schema Documentation

Here you can find extended documentation about search_vulns' result schema and API format.

Match Reason

When a module matches a vulnerability to the user's query, it has to provide a MatchReason. In addition, every vulnerability is assigned the best MatchReason out of all modules reporting a match. Essentially, it is an ordered Enum value:

class MatchReason(str, Enum):
    PRODUCT_MATCH = "product_match"
    VERSION_IN_RANGE = "version_in_range"
    GENERAL_PRODUCT_OK = "general_product_ok"
    DESCRIPTION_MATCH = "description_match"
    GENERAL_PRODUCT_UNCERTAIN = "general_product_uncertain"
    SINGLE_HIGHER_VERSION = "single_higher_version"
    VULN_ID = "vuln_id"
    N_A = "n_a"

    @property
    def _priority(self) -> int:
        return _MATCH_REASON_PRIORITY[self]

    def __lt__(self, other):
        if isinstance(other, MatchReason):
            return self._priority < other._priority
        return NotImplemented


_MATCH_REASON_PRIORITY: dict[MatchReason, int] = {
    MatchReason.PRODUCT_MATCH: 8,
    MatchReason.VERSION_IN_RANGE: 7,
    MatchReason.GENERAL_PRODUCT_OK: 6,
    MatchReason.DESCRIPTION_MATCH: 5,
    MatchReason.GENERAL_PRODUCT_UNCERTAIN: 4,
    MatchReason.SINGLE_HIGHER_VERSION: 3,
    MatchReason.VULN_ID: 2,
    MatchReason.N_A: 1,
}

This MatchReason allows modules to provide information on why a vulnerability was matched to a query. This enables users to distinguish between different types of matches and confidence levels. For example, the NVD module returns MatchReason.PRODUCT_MATCH if the CPE provided by the user is fully included in the NVD's list of affected CPEs, like with cpe:2.3:a:facebook:react:19.1.0:*:*:*:*:*:*:* in https://nvd.nist.gov/vuln/detail/cve-2025-55182. On the other hand, if the NVD lists a general CPE of the user's query with a versionStart and versionEnd, MatchReason.VERSION_IN_RANGE is returned. This is the case with query cpe:2.3:a:facebook:react:16.1.1:*:*:*:*:*:*:* and https://nvd.nist.gov/vuln/detail/cve-2018-6341, for example.