Smart Audit (beta)¶

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". The Vulners matcher automatically determines the correct CPE / PURL for each string, which is then fed into the same audit engine as audit/software to return the matched vulnerabilities.

Matching currently runs against the full CPE catalog — the NVD CVE Dictionary plus Vulners custom-built CPEs (extra coverage for OS packages, language libraries and niche vendors) — with PURL-based matching on the way (resolved PURLs are already returned in the response). Catalog behaviour may still evolve while the endpoint is in beta.

POST /api/v4/audit/smart

Parameters¶

Batching & rate limits¶

• Hard limits: 1–500 strings per request, each 1–512 characters.
• Recommended batch size: ≤128 strings per request. Larger batches are accepted up to the hard limit, but smaller batches keep latency stable and make retries cheaper.
• HTTP 429 (Too Many Requests): retry with exponential backoff and honor the Retry-After response header when present — wait at least that many seconds before retrying.

Response schema¶

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

Each item in vulnerabilities carries id and reasons, plus a default set of advisory fields (title, short_description, type, href, published, modified, ai_score). Ask for fields to get metrics, exploitation and cvelistMetrics as well — the same enrichment audit/software returns, in the same shape. The reasons[] structure is identical to audit/software.

One item comes back per submitted string, in request order, including strings that resolved to nothing — so the response is always the same length as the request. Join on input anyway: it costs nothing and survives the ordering ever changing.

Usage¶

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"
    ]
  }'

# Billed per submitted string — keep batches small.
# The SDK validates the 1-500 items / 1-512 characters limits client-side.
results = v.audit.smart([
    "Adobe Reader 5.3",
    "nginx 1.14 on windows",
    "OpenSSL 1.0.1",
])
for entry in results:
    print(entry["input"], "->", entry["cpe"], len(entry["vulnerabilities"]), "vulnerabilities")

{
  "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¶