New Vulners Audit and CPE Search API

Following our recent update in 24Q4, we are excited to introduce a new set of features that are now available in Vulners API. In this update we focused on simplifying vulnerability assessment workflows by allowing less structured parameters.

This feature set builds on the foundation of our vulnerability intelligence database, which includes normalized machine-readable affected software configurations.

Many of the vulnerability databases — and specifically the National Vulnerability Database (NVD) — have the vulnerable products identified with Common Platform Enumerations (CPE). So, to use those for finding vulnerabilities that affect your assets, you need to know the CPE of the software products that run on them.

It gets tricky here, as there is no definitive way to form a CPE for a product that would surely match one used in a vulnerability database. You need to rely on someone to provide it for you, or engineer a fuzzy search in a noisy CPE dictionary.

Since at Vulners we’ve been dealing with this issue for ages, we’ve got numerous bits and pieces that form a solution for this problem already available. Firstly, it is a massive database that has all the CPE present in CVE-affected software configurations. Some of them are generated by third parties as NVD or CISA Vulnrichment, but also generated by Vulners on a basis of affected configurations provided for CVE by CVE Numbering Authorities (CNA).

Furthermore, we’ve developed a sophisticated database search engine that allows for super-fast and accurate searches in the database with precise and fuzzy parameters — exactly what is needed for the real-world vulnerability assessment.

We now expose this functionality as a set of new APIs. It includes the following capabilities:

• audit/software — search for vulnerabilities in a list of software components
• audit/host — search for vulnerabilities for a list of software components, filtering by applicable operating system, application, or hardware.
• search/cpe — search for the best matching CPE for product/vendor pairs.

This blog post provides an extensive description of the calls, some of the best practices, and caveats.

New API to Audit Software Products for Vulnerabilities

The new audit/software API makes it super easy to audit several software components for known vulnerabilities. You can specify the software components as (vendor)/product/versions triplets or as CPE.

The API is super fast, and the typical response time is 400 milliseconds for one software component. Eventually, the response could be slower for larger requests, but it is definitely under 1 second. Just compare it with the similar NVD API performance, and you will see the difference.

The documentation is available on the Vulners website, and the following sections provide some tips and tricks for using this API.

Specify Software for the Audit with Name and Version

For starters you can start just with the product name and the version. This is specifically what this API aims for - making it super easy to provide input parameters for vulnerability assessment without needing to guess exactly how vendor or NVD constructed the CPEs.

If you need more precision, you can use all attributes of well-formed CPE in the software structure to specify software components for audit.

Thanks to Vulners advanced software name matching algorithm, the configurations in this example are identical and produce the same results.

software = [
        {
        "product": "curl",
        "version": "7.85"          
        },
        {
        "part": "a",
        "vendor": "haxx",
        "product": "curl",
        "version": "7.85",
        "update": "*",
        "edition": "*",
        "language": "*",
        "platform": "*",
        "target_sw": "*",
        "target_hw": "*",
        "other": "*"
        }
    ]

The result of the API call will be a list of findings for each specified software component that includes:

• Provided software configuration
• Matched software configuration
• The list of vulnerabilities

{
    "input": {
        "product": "curl",
        "version": "7.85"
    },
    "matched_criteria": "cpe:2.3:a:haxx:curl:7.85:*:*:*:*:*:*:*",
    "vulnerabilities": [ ... ]
},
{
    "input": {
        "part": "a",
        "vendor": "haxx",
        "product": "curl",
        "version": "7.85",
        "update": "*",
        "edition": "*",
        "language": "*",
        "target_sw": "*",
        "target_hw": "*",
        "other": "*"
    },
    "matched_criteria": "cpe:2.3:a:haxx:curl:7.85:*:*:*:*:*:*:*",
    "vulnerabilities": [ ... ]
}

Specify Software for the Audit with CPE

If your asset management system has CPE in it, you can also provide a list of the CPE strings to the API as a parameter. If you use CPE you MUST specify part, vendor, product, and version attributes of the well-formed CPE.

cpe = [
        "cpe:2.3:a:ivanti:connect_secure:22.7:r2.4:*:*:*:*:*:*",
        "cpe:2.3:o:sonicwall:sma_200_firmware:10.2.1.5-34sv"
      ]

The software structures can be used together with CPE in one list, and the software structure supports all attributes of the well-formed CPE. As well, for each software structure, you’d get a matched_criteria string that helps you to verify the correctness of the software matching.

[
    {
        "input": "cpe:2.3:a:ivanti:connect_secure:22.7:r2.4:*:*:*:*:*:*",
        "matched_criteria": "cpe:2.3:a:ivanti:connect_secure:22.7:r2.4:*:*:*:*:*:*",
        "vulnerabilities": [ ... ]
    },
    {
        "input": "cpe:2.3:o:sonicwall:sma_200_firmware:10.2.1.5-34sv",
        "matched_criteria": "cpe:2.3:o:sonicwall:sma_200_firmware:10.2.1.5-34sv:*:*:*:*:*:*:*",
        "vulnerabilities": [ ... ]
    }
]

Use the match Parameter

Parameter match manages how matching works for all but part, vendor, product, and version attributes of well-formed CPE attributes in affected configurations are matched to the audited software and can have two values. full or partial.

When the match parameter is partial, which is a default value, the algorithm will return the records with attributes that either exactly match or the records that have * value assigned to the attribute in the affected configuration.

When the match parameter is full the algorithm will return only the records with attributes that exactly match the value for the attribute in the affected configuration.

Consider the following example. These configurations are equivalent but use different match intent.

params_vulners_partial = {
    "software": [
        "cpe:2.3:a:adobe:acrobat_reader_dc:24.004.20272:*:*:*:*:windows:*:*"
    ],
    "match": "partial"
}
params_vulners_full = {
    "software": [
        {
        "vendor": "adobe",
        "product": "reader dc",
        "version": "24.004.20272",
        "target_sw": "windows" 
        }
    ],
    "match": "full"
}

In the results CVE-2024-49531 and CVE-2024-49535 have explicit “Running on/with” specification in the affected software configuration, while others lack it.

Understand the Response

For each software component specified in the audit/software call parameters, you’d get a dictionary with the following keys:

{
    "input": {
        "product": "curl",
        "version": "7.85"
	    },
    "matched_criteria": "cpe:2.3:a:haxx:curl:7.85:*:*:*:*:*:*:*",
    "vulnerabilities": [ ... ]
}

The input key includes software component specification as it was passed to the API, the matched_criteria key the CPE string that was used to match the Vulners database for affected configurations, and the vulnerabilities list.

The following example presents vulnerability data that is returned for each matched CVE.

{
    "id": "CVE-2024-9681",
    "reasons": [
        {
            "config": "nvd",
            "criterias": [
                [
                    {
                        "criteria": "cpe:2.3:a:haxx:curl:*:*:*:*:*:*:*:*",
                        "vulnerable": true,
                        "versionStartIncluding": "7.74.0",
                        "versionEndExcluding": "8.11.0"
                    }
                ]
            ]
        }
    ],
    "type": "cve",
    "title": "CVE-2024-9681",
    "published": "2024-11-06T08:15:03",
    "modified": "2024-12-13T14:15:22",
    "metrics": {
        "cvss": {
            "score": 6.5,
            "severity": "MEDIUM",
            "vector": "CVSS:3.1/AV:N/AC:H/PR:N/UI:N/S:U/C:N/I:H/A:L",
            "version": "3.1"
        },
        "epss": [
            {
                "cve": "CVE-2024-9681",
                "epss": 0.00054,
                "percentile": 0.2543,
                "date": "2025-02-18"
            }
        ]
    },
    "href": "https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2024-9681",
    "cvelist": [
        "CVE-2024-9681"
    ],
    "short_description": "Curl HSTS Expiry Time Overwrite Vulnerability",
    "ai_score": {
        "value": 6.7,
        "uncertainty": 1.5
    },
    "exploitation": {
        "wildExploited": false,
        "wildExploitedSources": []
    }
}

Most of the fields are self-descriptive, but we wanted to draw your attention to a few of them.

The reasons key includes a list of affected configurations that match the requested software component and its version.

The metrics key includes the Base CVSS score, which is picked from CVSS scores provided by NVD and CNA — we first take the CVSS score with the highest available version, and then the highest Base Score. This key also includes all EPSS scores available in the Vulners database for the CVE in question.

The exploitation key shows if the CVE is included in any of the sources that list vulnerabilities with confirmed exploitation, namely CISA KEV and AttackerKB.

Similar to Vulners Lucene-based search API, audit/software call allows you to select fields which you want to receive with the fields parameter. By default, the following fields are returned.

[
        "title",
        "short_description",
        "type",
        "href",
        "published",
        "modified",
        "ai_score"
]

Note: Since in Vulners database we have affected configurations not only for CVE records but also for vendor security advisories and records from OSV and GHSA, be prepared to handle results with the type besides "cve". These results will have the same record structure, and if needed, you can query CVE details using the CVE ID in the… cvelist key.

New API to Audit Host for Known Vulnerabilities

Another new addition to the Vulners API is audit/host call.

It works similarly to the audit/software call with the same set of auxiliary parameters, but allows you to explicitly specify operating system, application, or hardware to use as the filter for the vulnerability assessment for the specified software components. Please check the documentation here.

Let’s consider an example like this.

{
    software = [
            "cpe:2.3:a:microsoft:.net_framework:3.5", 
            "cpe:2.3:a:microsoft:.net_framework:4.8.1"
    ],
    operating_system = "cpe:2.3:o:microsoft:windows_server_2022_23h2",
    match = "full"
}

Note in the response of the audit/host call, the reasons key includes two conditions. This example also outlines the content of the exploitation key.

{
    "id": "CVE-2024-29059",
    "reasons": [
        {
            "config": "nvd",
            "criterias": [
                [
                    {
                        "criteria": "cpe:2.3:a:microsoft:.net_framework:4.8.1:*:*:*:*:*:*:*",
                        "vulnerable": true
                    }
                ],
                [
                    {
                        "criteria": "cpe:2.3:o:microsoft:windows_server_2022_23h2:-:*:*:*:*:*:*:*",
                        "vulnerable": false
                    }
                ]
            ]
        }
    ],
    "type": "cve",
    "title": "CVE-2024-29059",
    "published": "2024-03-23T00:15:09",
    "modified": "2025-02-05T02:00:01",
    "metrics": {
        "cvss": {
            "score": 7.5,
            "severity": "HIGH",
            "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N",
            "version": "3.1"
        },
        "epss": [
            {
                "cve": "CVE-2024-29059",
                "epss": 0.69152,
                "percentile": 0.98234,
                "date": "2025-02-18"
            }
        ]
    },
    "href": "https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2024-29059",
    "cvelist": [
        "CVE-2024-29059"
    ],
    "short_description": ".NET Framework Information Disclosure Vulnerability",
    "ai_score": {
        "value": 7.3,
        "uncertainty": 0.1
    },
    "exploitation": {
        "wildExploited": true,
        "wildExploitedSources": [
            {
                "type": "attackerkb",
                "idList": [
                    "AKB:199DEA06-8971-4E4E-9A84-004B5DD70DD4"
                ]
            },
            {
                "type": "cisa_kev",
                "idList": [
                    "CISA-KEV-CVE-2024-29059"
                ]
            }
        ]
    }
}

New API to Find the Best-matching CPE

When using CPE-based vulnerability search, most of all, you want to have the vendor:product part of CPE figured out correctly. If you don’t, you are going to have to deal with the False Negatives problem. Vulnerabilities that affect your products just wouldn’t appear in the search results. However, once you have a correct vendor:product identification, you start dealing with True and False Positives, which in a sense is a simpler task — it becomes relatively straightforward to filter results by version, target operating system, and hardware.

Under the hood, this API performs sophisticated search of a vendor:product pairs, which are essentially a core part of a CPE.

Please refer to the documentation for the formal parameters' description. The next blog post section provides some best practices and caveats for using this API.

Get most of CPE Search API

Foremost, you need to understand that this API isn’t intended to create a new CPE. Instead, it helps you find CPE that are already present in the Vulners database. We use quite a few smart heuristics to offer you the best match and as well a few options that our algorithm still finds relevant.

For example, if you search for “curl”, the best match will be haxx:curl combination, which we believe is the most relevant CPE for finding Curl vulnerabilities. The following is the full result of the search.

{
  "result": {
    "best_match": "cpe:2.3:a:haxx:curl:*:*:*:*:*:*:*:*",
    "cpe": [
      "cpe:2.3:a:haxx:libcurl:*:*:*:*:*:*:*:*",
      "cpe:2.3:a:curl_project:curl:*:*:*:*:*:*:*:*",
      "cpe:2.3:a:daniel_stenberg:curl:*:*:*:*:*:*:*:*",
      "cpe:2.3:a:php_curl_class_project:php_curl_class:*:*:*:*:*:*:*:*"
    ]
  }
}

If you try to search NVD CPE dictionary using the same query, you are going to sift through more than 300 results, many of which have no relevance at all.

You can refine the search by specifying the vendor. Here are search results for “Microsoft Office" — the best match is the most generic product CPE, but you also see other Microsoft products that have “Office” in their names.

{
  "result": {
    "best_match": "cpe:2.3:a:microsoft:office:*:*:*:*:*:*:*:*",
    "cpe": [
      "cpe:2.3:a:microsoft:office_long_term_servicing_channel:*:*:*:*:*:*:*:*",
      "cpe:2.3:a:microsoft:office_compatibility_pack:*:*:*:*:*:*:*:*",
      "cpe:2.3:a:microsoft:office_online_server:*:*:*:*:*:*:*:*",
      "cpe:2.3:a:microsoft:office_web_apps:*:*:*:*:*:*:*:*",
      "cpe:2.3:a:microsoft:office_365_proplus:*:*:*:*:*:*:*:*",
      "cpe:2.3:a:microsoft:office_web_apps_server:*:*:*:*:*:*:*:*",
      "cpe:2.3:a:microsoft:office_word:*:*:*:*:*:*:*:*",
      "cpe:2.3:a:microsoft:office_sharepoint_server:*:*:*:*:*:*:*:*",
      "cpe:2.3:a:microsoft:office_excel:*:*:*:*:*:*:*:*"
    ]
  }
}

Generally, you would rather not include a version in these searches unless it is an integral part of the product name. For example, here are the results of a “Windows 11" related CPE search.

{
  "result": {
    "best_match": "cpe:2.3:o:microsoft:windows_11:*:*:*:*:*:*:*:*",
    "cpe": [
      "cpe:2.3:o:microsoft:windows_11_21h2:*:*:*:*:*:*:*:*",
      "cpe:2.3:o:microsoft:windows_11_22h2:*:*:*:*:*:*:*:*",
      "cpe:2.3:o:microsoft:windows_11_23h2:*:*:*:*:*:*:*:*",
      "cpe:2.3:o:microsoft:windows_11_24h2:*:*:*:*:*:*:*:*"
    ]
  }
}

Try it out!

These new Vulners API is already in production and available for both commercial and free community plans. Please don’t hesitate to start a free trial with Vulners to explore these new API calls in full - the trial comes with no strings attached and doesn’t require anything but an email to create the account.

We eagerly await your feedback! Please don’t hesitate to reach out if you have questions or find any inconsistencies.