Smart Audit (preview)¶

Unlisted preview

This endpoint is in preview and intentionally not linked from the navigation. It is reachable only via this direct link and may change before general availability.

Smart Audit turns a list of raw, free-form software strings into vulnerabilities. Unlike audit/software — which expects already structured input (vendor/product/version or a CPE) — Smart Audit accepts messy strings such as "Adobe Reader 5.3" or "nginx 1.14 on windows" and resolves them to CPEs itself via the Vulners matcher Construct service (the matcher extracts the version and applicability from the string), then runs the same audit engine as audit/software to return matched vulnerabilities.

POST /api/v4/audit/smart

Auth: X-Api-Key header required. Billed per submitted string.

Parameters¶

Name	In	Type	Required	Description
`software`	body	array[string]	yes	Raw software description strings. 1–500 items, each 1–512 characters. Empty strings are rejected.
`catalog`	body	enum	no	CPE catalog to match against. `official` (default) — only NVD CVE Dictionary CPEs. `extended` — NVD + Vulners custom CPEs.

catalog: official vs extended

official — matches only CPEs published in the NVD CVE Dictionary. Strict, lowest false-positive rate.
extended — adds Vulners custom-built CPEs on top of the official set. Higher coverage (OS packages, JS/Python libs, niche vendors), but may introduce false positives.

Response schema¶

The response is an object with a single result key holding one entry per submitted string (order preserved):

Field	Type	Description
`input`	string	Echo of the submitted raw string.
`cpe`	string	CPE 2.3 the string resolved to (version included). Empty string if the matcher found no CPE.
`purls`	array[string]	Package URLs (pURL) the matcher associated with the string. Informational; not used for matching in this version.
`confidence`	number	Matcher construct confidence, `0.0–1.0`.
`vulnerabilities`	array[object]	Matched vulnerabilities (same shape as `audit/software`). Empty if no matches or unresolved.

Each item in vulnerabilities carries id and reasons, plus a default set of advisory fields (title, short_description, type, href, published, modified, ai_score). The reasons[] structure is identical to audit/software.

Resilience: transparent fallback

If the matcher service is unavailable, Smart Audit transparently falls back to fuzzy CPE naming (FFN) so a result is still returned — version-agnostic and lower precision. The response shape is unchanged; the incident is recorded server-side (logs + Sentry), not surfaced in the response.

Usage¶

curl Response

Query:

POST /api/v4/audit/smart

curl -X POST https://vulners.com/api/v4/audit/smart \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "software": [
      "Adobe Reader 5.3",
      "nginx 1.14 on windows",
      "OpenSSL 1.0.1"
    ],
    "catalog": "official"
  }'

{
  "result": [
    {
      "input": "Adobe Reader 5.3",
      "cpe": "cpe:2.3:a:adobe:acrobat_reader:5.3:*:*:*:*:*:*:*",
      "purls": [],
      "confidence": 0.81,
      "vulnerabilities": [
        {
          "id": "CVE-2020-0001",
          "reasons": [
            {
              "config": "nvd",
              "criterias": [
                [
                  {
                    "criteria": "cpe:2.3:a:adobe:acrobat_reader:5.3:*:*:*:*:*:*:*",
                    "vulnerable": true
                  }
                ]
              ]
            }
          ],
          "title": "...",
          "short_description": "...",
          "type": "cve",
          "href": "https://vulners.com/cve/CVE-2020-0001",
          "published": "2020-01-01T00:00:00",
          "modified": "2020-01-02T00:00:00",
          "ai_score": { "value": 7.5, "uncertainty": 0.5 }
        }
      ]
    },
    {
      "input": "nginx 1.14 on windows",
      "cpe": "cpe:2.3:a:f5:nginx:1.14:*:*:*:*:windows:*:*",
      "purls": [],
      "confidence": 0.77,
      "vulnerabilities": []
    }
  ]
}

Errors¶

Status	Meaning
`401`	Missing or invalid `X-Api-Key`.
`422`	Validation error — empty list, more than 500 items, or an empty/over-long string.
`402`	Insufficient wallet balance for the request (restricted licenses).