> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vulnerability

> Look up the published record of a software vulnerability by its CVE identifier.

Look up a software vulnerability by its CVE identifier in the US National Vulnerability Database. The record gives a description in English, when it was published and last modified, its analysis status, its severity (the newest CVSS version that has a primary score, with the score, the rating word and the vector), the weakness types, whether it is on the US list of known exploited vulnerabilities (with the date added, the date action is due and the required action), the first 10 references with their tags and a link to the record. The lists of affected product versions are not returned. A record is what the database publishes, not a measure of the risk to any one system. `total` is 1, or 0 when the database has no such identifier. Times are UTC. This product uses the NVD API but is not endorsed or certified by the NVD.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

<ParamField body="cve_id" type="string" required>
  The CVE identifier, for example CVE-2021-44228. Lower case is accepted. A CVE identifier is CVE-, a four-digit year, a dash and four or more digits.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  Always `record_vulnerability`
</ResponseField>

<ResponseField name="data.result" type="object">
  The answer, described under Result below
</ResponseField>

<ResponseField name="data.evidence" type="object">
  Where the answer came from and when
</ResponseField>

<ResponseField name="data.evidence.source" type="string">
  The public body the data comes from. Always `US National Institute of Standards and Technology`.
</ResponseField>

<ResponseField name="data.evidence.source_kind" type="string">
  `public` when the data comes from a public body, `commercial` otherwise
</ResponseField>

<ResponseField name="data.evidence.retrieved_at" type="string">
  When the lookup was made, as an ISO 8601 UTC time
</ResponseField>

<ResponseField name="data.evidence.as_of" type="string">
  When the source says the fact was last updated, or `null` when the source gives no date
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.total" type="number">
  1 when the database has the record, 0 when it has none.
</ResponseField>

<ResponseField name="data.result.vulnerabilities" type="object[]">
  The record, or an empty list when the database has none.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].id" type="string">
  The CVE identifier, in upper case.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].description" type="string">
  The description in English. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].published_at" type="string">
  When the record was published, ISO 8601 UTC. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].last_modified_at" type="string">
  When the record was last modified, ISO 8601 UTC. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].status" type="string">
  Where the record stands in analysis, for example Analyzed. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].severity" type="object">
  The primary score of the newest CVSS version that has one. `null` when none is published.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].severity.version" type="string">
  The CVSS version of the score: 4.0, 3.1, 3.0 or 2.0.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].severity.score" type="number">
  The base score, 0 to 10.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].severity.rating" type="string">
  The rating word the source gives the score, for example CRITICAL. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].severity.vector" type="string">
  The CVSS vector string. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].weaknesses" type="string[]">
  The weakness identifiers, for example CWE-502, each once.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].known_exploited" type="object">
  Set when the vulnerability is on the US list of known exploited vulnerabilities. `null` when it is not.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].known_exploited.added_on" type="string">
  When it was added to the US list of known exploited vulnerabilities, YYYY-MM-DD. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].known_exploited.action_due" type="string">
  The date federal agencies must act by, YYYY-MM-DD. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].known_exploited.required_action" type="string">
  The action the list requires. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].known_exploited.name" type="string">
  The name the list gives the vulnerability. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].references" type="object[]">
  The first 10 references.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].references[].url" type="string">
  The address of the reference.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].references[].tags" type="string[]">
  What kind of reference it is, for example Vendor Advisory.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].references_total" type="number">
  How many references the record has, including any beyond the first 10.
</ResponseField>

<ResponseField name="data.result.vulnerabilities[].url" type="string">
  The record on nvd.nist.gov.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/lookup/record-vulnerability \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "cve_id": "CVE-2021-44228"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/record-vulnerability", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "cve_id": "CVE-2021-44228"
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('lookup/record-vulnerability', {
    cve_id: 'CVE-2021-44228'
  });
  console.log(result.data.result);
  console.log(result.data.evidence);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "request_id": "uuid",
      "receipt_id": "rcpt_...",
      "status": "completed",
      "tool": "record_vulnerability",
      "result": {
        "total": 1,
        "vulnerabilities": [
          {
            "id": "CVE-2021-44228",
            "description": "Apache Log4j2 JNDI features do not protect against attacker controlled LDAP and other JNDI related endpoints.",
            "published_at": "2021-12-10T10:15:09.143Z",
            "last_modified_at": "2026-08-11T19:33:44.513Z",
            "status": "Analyzed",
            "severity": {
              "version": "3.1",
              "score": 10,
              "rating": "CRITICAL",
              "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H"
            },
            "weaknesses": [
              "CWE-20",
              "CWE-400",
              "CWE-502",
              "CWE-917"
            ],
            "known_exploited": {
              "added_on": "2021-12-10",
              "action_due": "2021-12-24",
              "required_action": "Apply updates, or remove affected assets from agency networks.",
              "name": "Apache Log4j2 Remote Code Execution Vulnerability"
            },
            "references": [
              {
                "url": "https://example.com/advisory",
                "tags": [
                  "Vendor Advisory"
                ]
              }
            ],
            "references_total": 103,
            "url": "https://nvd.nist.gov/vuln/detail/CVE-2021-44228"
          }
        ]
      },
      "evidence": {
        "source": "US National Institute of Standards and Technology",
        "source_kind": "public",
        "retrieved_at": "2026-10-13T12:00:00.000Z",
        "as_of": "2026-10-13T11:58:00.000Z"
      }
    }
  }
  ```
</ResponseExample>

<Info>Price: \$0.005 per lookup. See [Pricing](/pricing) for every tool.</Info>

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.