Agent Support

Vulnpatch exposes CVE dossiers designed for agent runtimes. A dossier is a single JSON document that combines canonical CVE fields, source provenance, data-quality gaps, ingest status, and action hints.

CVE Dossier

GET /api/v1/cve/:id/dossier

Example:

curl https://api.vulnpatch.dev/api/v1/cve/CVE-2024-3094/dossier

The response includes:

• canonical: normalized CVE fields for agent reasoning (id, severity, cvssScore, affectedPackages, epss, kev, availability).
• sources: raw source payloads from MITRE, NVD, OSV, GitHub Advisories, Nixpkgs, EPSS, and KEV when available.
• provenance: source names, source URLs, integrity hashes, and fetch timestamps.
• quality: missing fields, conflicts, grade (A–F), and completeness score.
• agentHints: recommended actions, known fixed versions, and booleans such as needsIngest, needsTriage, and safeForAutomation.
• ingest: freshness metadata including lastIngestedAt, sourcesChecked, and the canonical dossier URL.
• links: the human CVE page, API lookup, and dossier URL.
• lookup: the full raw multi-source envelope from /api/v1/cve/:id, embedded for agents that want to drill down without a second request.

Availability

canonical.availability signals the publication state of the CVE using a stable enum. Agents should branch on this rather than parsing free-text.

Value	Meaning
published	At least one authority has usable data.
partial	Some sources have data, but the canonical MITRE record is missing.
reserved	The CVE id is reserved with MITRE but details have not been published.
rejected	The CVE has been rejected by the numbering authority — do not use for remediation.
withdrawn	The CVE record was withdrawn.
awaiting_ingest	The id appears in the MITRE delta feed but enrichment has not landed yet. Treat like reserved; request ?fresh=true.

A response header X-Dossier-Availability carries the same value for quick inspection.

Not found

If no authority has allocated the id, the dossier endpoint returns 404 with a structured body:

{
  "success": false,
  "error": "not_found",
  "code": "CVE_UNKNOWN",
  "hint": "No authority has allocated CVE-9999-99999. Verify the ID follows the CVE-YYYY-NNNNN+ format and check for typos."
}

Branch on code — it is stable. The same contract is enforced on the raw lookup endpoint.

Agents should fetch the dossier before making remediation or triage decisions. The human-readable view of the same record is available at:

https://cve.vulnpatch.dev/CVE-2024-3094

Requesting a fresh dossier

If agentHints.needsIngest is true, or the fetched data looks stale, append ?fresh=true to bypass cache and have the server reconcile the dossier from upstream sources before responding:

GET /api/v1/cve/:id/dossier?fresh=true

curl "https://api.vulnpatch.dev/api/v1/cve/CVE-2024-3094/dossier?fresh=true"

?fresh=true is rate-limited and may be disabled for unauthenticated callers under load; treat the cached dossier as the normal path and ?fresh=true as the refresh hint.

Runtime Guidance

Recommended agent flow:

1. Fetch GET /api/v1/cve/:id/dossier.
2. Read agentHints. If needsIngest is true, retry with ?fresh=true.
3. Use agentHints.knownFixedVersions, quality.conflicts, and provenance before recommending remediation.
4. Link users back to links.html so humans can inspect the same evidence.

Do not mutate canonical CVE data directly from model output. The agent requests a refresh; deterministic server code performs the source fetches, normalization, hashing, and storage.

Agent Tools

Agent runtimes that integrate with Vulnpatch expose two dossier-aware tools backed by the public dossier endpoint:

• lookup_cve_dossier({ cve_id, fresh? }) — returns the dossier JSON. Use fresh: true to request a refresh.
• queue_cve_ingest({ cve_id }) — signals that the dossier is stale or incomplete and requests reconciliation. Rate-limited per CVE.

Both tools validate cve_id against CVE-YYYY-NNNNN+ and return JSON identical in shape to the dossier endpoint.