tools/cve-org/tool.md

<!-- SPDX-License-Identifier: Apache-2.0
     https://www.apache.org/licenses/LICENSE-2.0 -->

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Tool: cve.org](#tool-cveorg)
  - [What this tool provides](#what-this-tool-provides)
  - [URLs](#urls)
  - [Publication state check — `check-published`](#publication-state-check--check-published)
  - [Confidentiality](#confidentiality)
  - [When to replace this tool with another](#when-to-replace-this-tool-with-another)
  - [Per-project configuration](#per-project-configuration)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

<!-- SPDX-License-Identifier: Apache-2.0
     https://www.apache.org/licenses/LICENSE-2.0 -->

# Tool: cve.org

This directory documents the **cve.org** tool adapter — the public
CVE registry every CNA tool ultimately publishes records to. Unlike
[`tools/cve-tool-vulnogram/`](../cve-tool-vulnogram/) (the CNA-side tool where the
security team drafts and reviews the record), `cve.org` is
**read-only** from the skills' perspective: we query it to confirm
that a record has propagated from the CNA tool to the public
registry.

Use the [MITRE CVE Services API v2](https://cveawg.mitre.org/api-docs/)
for programmatic checks and the public `cve.org` UI for human-
readable lookup.

## What this tool provides

One capability: **publication state check**. Given a `CVE-ID`,
answer *"is this record live on cve.org yet?"*. Used by
`security-issue-sync` to drive the *"notify the reporter that the
CVE is published"* proposal (see the
[*"Check recently-closed trackers for CVE publication state"*
section](../../skills/security-issue-sync/SKILL.md)
in the sync skill).

## URLs

| Purpose | URL |
|---|---|
| Public HTML record | `https://www.cve.org/CVERecord?id=<CVE-ID>` |
| CVE Services JSON API v2 | `https://cveawg.mitre.org/api/cve/<CVE-ID>` |
| NVD record (alternative public registry — often a few days behind cve.org) | `https://nvd.nist.gov/vuln/detail/<CVE-ID>` |
| NVD JSON API | `https://services.nvd.nist.gov/rest/json/cves/2.0?cveId=<CVE-ID>` |

## Publication state check — `check-published`

The canonical state field on the CVE Services API is
`cveMetadata.state`, with three relevant values:

| `state` | Meaning |
|---|---|
| `RESERVED` | CVE ID has been allocated but no content has been published. The API returns a minimal record (metadata only). |
| `PUBLISHED` | Full CVE record is live on cve.org. The API returns the full CNA container (descriptions, affected, references, credits). |
| `REJECTED` | CVE was withdrawn after allocation. The API returns a record with `containers.cna.rejectedReasons`. |

Recipe:

```bash
# Read-only, no auth required. Returns JSON.
curl -sSf https://cveawg.mitre.org/api/cve/<CVE-ID> \
  | jq -r '.cveMetadata.state'
```

Interpretation:

- `RESERVED` → the record is still in the CNA's draft / review
  queue. The propagation from the CNA tool (for ASF projects,
  Vulnogram) to cve.org has not completed yet. Check again on the
  next sync run.
- `PUBLISHED` → the record is live on cve.org. This is the signal
  the sync skill waits for before proposing the final
  *CVE-published* email to the reporter.
- `REJECTED` → something went wrong post-publication. Surface to the
  security team; do not notify the reporter on the happy path.
- Non-zero exit from `curl` (404, 5xx, DNS failure) → treat as
  *"unknown — try again next sync"*. Do not propose notification
  on an absent response; cve.org sometimes returns transient 5xx
  during CNA-feed propagation.

Extract the `datePublished` alongside the state when you need to
print *"published on YYYY-MM-DD"* in the reporter email:

```bash
curl -sSf https://cveawg.mitre.org/api/cve/<CVE-ID> \
  | jq -r '{state: .cveMetadata.state, datePublished: .cveMetadata.datePublished}'
```

## Confidentiality

`cve.org` is the **public** CVE registry — everything it returns is
world-readable. No confidentiality concerns; the API has no auth and
no rate-limit the skills bump into at normal cadence (a handful of
closed trackers per sync sweep).

The *"Linking CVEs"* rule in [`../../AGENTS.md`](../../AGENTS.md)
applies: before the CVE record is live on cve.org, skills link only
to the project's CVE-tool URL (team-internal); once `cveMetadata.state`
returns `PUBLISHED`, the public `cve.org/CVERecord?id=<CVE-ID>` link
becomes the canonical one for reporter emails and any public
surface.

## When to replace this tool with another

Unlikely — cve.org is the single public CVE registry every CNA
feeds. If a project decides to track NVD publication separately
(NVD assigns a severity after cve.org publication, which can take
additional days), add NVD-specific recipes to this file rather than
creating a sibling adapter; NVD is a consumer of cve.org data, not
a parallel registry.

## Per-project configuration

None required. The URL templates above apply to every CVE ID
regardless of which CNA owns it. The skills substitute the concrete
`<CVE-ID>` per tracker at read time.