tools/cve-tool/
Capability: contract:cve-authority
Kind: interface
Vendor: agnostic
Prerequisites
- Runtime: Python 3.11+ and
uv. Thecve-toolcommand (uvx --from ~/.claude/magpie/security-tools/cve-tool cve-tool <operation>) is stdlib-only; it readscve_authority.tooland runs that tool’s adapter. - CLIs / credentials / network: Provided entirely by the resolved adapter — the sibling
tools/cve-tool-<name>/directory named bycve_authority.toolinproject.md(the ASF default is Vulnogram attools/cve-tool-vulnogram/). See that adapter for its concrete prerequisites.
What this is
The framework’s CVE-tooling adapter contract, and the cve-tool command that implements it.
A project running the ASF’s Vulnogram, CVE.org’s direct submission portal, the MITRE form for non-CNAs, GHSA’s own CNA flow,
or no CVE allocation at all needs the security skills to handle a CVE record the same way.
This contract is the seam that makes that possible.
It defines the operations every CVE-tool backend implements, the lifecycle moments at which the skills run each one,
and the generic state verbs the skills use to talk about a CVE record without baking in any one tool’s vocabulary.
The skills and the security-management helpers never run a CVE tool’s own commands:
they run cve-tool <operation>, which reads cve_authority.tool and hands the call to that tool’s adapter.
Skills consume the contract; the adapter consumes the wire protocol of whichever CNA tool the adopter actually uses.
Adopters who run Vulnogram inherit the ASF defaults verbatim.
Today’s adapters
Only one CVE-tool adapter ships today:
| Adapter | Directory | Status | Notes |
|---|---|---|---|
| Vulnogram (ASF) | tools/cve-tool-vulnogram/ |
Shipping | The reference implementation. cve-tool runs it through src/cve_tool/adapters/vulnogram.py, which calls the oauth-api commands. |
| CVE.org direct submission | tools/cve-tool-cve-org-direct/ (planned) |
Placeholder | For adopters who are themselves a CNA and submit records straight to cve.org via the CVE Services API rather than through an intermediate CNA tool. |
| MITRE form | tools/cve-tool-mitre-form/ (planned) |
Placeholder | For adopters who are not a CNA and request CVE IDs via the MITRE CVE Request form. Allocation is asynchronous and operator-mediated; fetch_current_state will frequently return unknown until the form’s email reply arrives. |
| GHSA-as-CNA | tools/cve-tool-ghsa/ (planned) |
Placeholder | For adopters who already drive their advisory flow through GitHub Security Advisories (GHSA) and use GitHub as the CNA. allocate becomes a GHSA draft create; publish becomes a GHSA publish. |
| None | tools/cve-tool-none/ (planned) |
Placeholder | The disable-CVE-allocation backend. All methods are no-ops returning a synthetic not-applicable result. For adopters who triage security issues but do not allocate CVEs (e.g. an internal product with no public distribution). |
The four placeholder adapters do not exist on disk yet; they exist
in this table so the contract can describe the surface they will fit
into when an adopter actually needs one.
They land when an adopter implements them;
until then cve-tool refuses them with exit 21 (see Exit codes).
The cve-tool command
uvx --from ~/.claude/magpie/security-tools/cve-tool cve-tool [--tool NAME] [--project-root DIR] [--config-dir DIR] <operation> [args ...]
~/.claude/magpie/security-tools is the link the magpie-security-tools plugin’s SessionStart hook keeps on its own tools/.
cve-tool reads the CVE tool’s session under ~/.config/apache-magpie/, which the secure setup’s sandbox denies,
so that setup runs exactly this spelling outside the sandbox, with a confirmation on every call
(docs/setup/secure-agent-setup.md); type it as one command, nothing chained.
In a framework checkout without the plugin, run uv run --project <framework>/tools/cve-tool cve-tool … instead: it stays sandboxed, so the session-backed operations need the skills’ manual path.
The command resolves cve_authority.tool, first hit wins:
--tool, then <project-config>/project.md, then the project’s organization manifest
(organizations/<org>/organization.md, in-tree, then adopter-local), the chain AGENTS.md describes for every dotted config key.
--project-root (default: the current directory) is the adopter repository the configuration is read from.
cve-tool which prints, as JSON, the tool it resolved, where the value came from, and the operations its adapter implements.
Everything after the operation goes to the adapter unchanged,
so the flags, output and exit codes are the adapter’s own (for Vulnogram, see the oauth-api README).
That makes the order matter: cve-tool’s own options (--tool, --project-root, --config-dir) go before the operation,
and the operation’s own arguments go after it.
cve-tool --project-root /path/to/adopter fetch --cve-id CVE-2026-12345 --state-only # right
cve-tool fetch --project-root /path/to/adopter --cve-id CVE-2026-12345 --state-only # refused, exit 2
cve-tool refuses one of its own options after the operation with a usage error naming it,
before the adapter runs, rather than letting the adapter reject an argument it does not know.
Operations
| Operation | Contract method | Vulnogram adapter runs |
|---|---|---|
allocate |
allocate |
vulnogram-api-allocate |
fetch |
fetch_current_state |
vulnogram-api-record-fetch |
push |
push_update |
vulnogram-api-record-update |
publish |
publish |
vulnogram-api-record-publish |
retract |
retract |
not implemented: reject the record in the Vulnogram UI |
check |
session probe | vulnogram-api-check |
setup |
one-time session setup | vulnogram-api-setup |
An adapter translates its tool’s states at the edge, so callers see only the generic state verbs:
cve-tool fetch --state-only prints review-ready, not Vulnogram’s REVIEW,
and cve-tool publish --allow-state takes a generic state as well as a native one.
Exit codes
An adapter’s own exit codes pass through.
The interface adds three, clear of every adapter’s own 0–7:
| Exit | Meaning | What the skill does |
|---|---|---|
20 |
No cve_authority.tool is declared anywhere in the chain. |
Declare one in project.md, or pass --tool. |
21 |
The tool has no adapter (a planned one, or an unknown name). | Follow the skill’s manual path for the step. |
22 |
The adapter does not implement the operation. | Follow the hint in the message (for Vulnogram’s retract, the UI). |
A usage error in cve-tool’s own arguments (an unknown operation, or one of its options after the operation)
exits 2, as any argparse command does, and names the problem on stderr.
Adding an adapter
An adapter is one module under src/cve_tool/adapters/ and one entry in ADAPTERS there.
The module exposes OPERATIONS (the operation names it implements), run(operation, argv) -> int,
and optionally UNSUPPORTED, a hint per operation it cannot do.
Its commands must not define an option named --tool, --project-root or --config-dir:
cve-tool reserves those names (OWN_OPTIONS in cli.py) and refuses them after the operation.
The skills and helpers do not change: they already run cve-tool <operation>.
Interface
Every CVE-tool adapter exposes five methods. The names here are the generic verbs the skills use; an adapter is free to name its internal CLIs whatever fits its tool’s vocabulary, as long as the skill-facing surface uses these names.
allocate(scope, fields) to cve_id
Reserve a CVE ID and create the initial record.
- Lifecycle moment. Fires once per tracking issue, inside
security-cve-allocateafter the security team has agreed the report is valid and a CVE should be allocated. The pre-allocation consensus discussion happens on the tracker;allocateis the step that turns that consensus into a reserved ID. - Inputs.
scope— a string identifying the project scope under which the CVE belongs. Concretely for ASF: the scope label (affects: airflow/affects: providers/affects: chart) drives whichvendor/product/packageNametriad the adapter writes into the initial record. For other adopters this is whatever string their CVE tool needs to route the allocation to the right CNA pool.fields— a dict of the tracker’s body fields at the moment allocation fires:title,description,affected_versions,cwe,severity,credits,references. The adapter is free to ignore fields its tool cannot accept at allocation time and fill them in later viapush_update. The Vulnogram adapter accepts the full set at allocation; the MITRE-form adapter only sendstitle+affected_versions+ a short description in the initial form submission.
- Output. The allocated CVE ID as a string in canonical
CVE-YYYY-NNNN+form (CVE-2026-12345). If the adapter cannot allocate synchronously (the MITRE-form case), it returns a provisional placeholder string and the skill stores that on the tracker ascve allocation pending; the nextfetch_current_statecall upgrades it once the real ID arrives. - No-op case. The
noneadapter raisesNotApplicableand the skill skips allocation entirely. Thesecurity-cve-allocateskill detects this and posts a “this adopter does not allocate CVEs; closing without an ID” comment on the tracker instead.
fetch_current_state(cve_id) to {state, fields}
Read the current record state and the fields the tool stores.
- Lifecycle moment. Fires inside
security-issue-syncat Step 1e (the reviewer-comment sync) and Step 5b (the state-progression gate before the release-manager hand-off). Also fires fromsecurity-issue-invalidate’s Step 0 gate, to refuse closure when a record exists and is pastreview-ready. - Inputs. The CVE ID. Nothing else — the adapter is responsible for resolving the tool-specific URL or API call from the ID.
- Output. A two-field dict:
state— one of the generic state verbs defined below (allocated,review-ready,publish-ready,public,retracted,unknown). The adapter is responsible for mapping its tool’s native state vocabulary onto these verbs.fields— a dict of the fields the tool currently stores for the record. Shape matches theallocateinput dict; the skills diff this against the tracker body to detect drift.
- No-op case. The
noneadapter returns{state: "unknown", fields: {}}. Skills treatunknownas “do not gate progression on tool state”; they fall back to the tracker body’s view.
push_update(cve_id, fields, state_transition=None) to diff
Write field updates to the record, optionally with a state move.
- Lifecycle moment. Fires inside
security-issue-syncat Step 5c, whenever the tracker body has drifted from whatfetch_current_statereturned. Also fires fromsecurity-issue-deduplicatewhen the kept tracker absorbs credits or references from the merged-in tracker. - Inputs.
cve_id— as forfetch_current_state.fields— the new desired fields. The adapter is responsible for translating these into whatever wire format its tool accepts (JSON record for Vulnogram, web-form fields for the MITRE form, GraphQL mutation for GHSA).state_transition(optional) — one of the generic state verbs. When supplied, the adapter performs the state move as part of the same write; when omitted, the adapter only writes fields and leaves state untouched. The Vulnogram adapter today embeds the state inside the JSON body and so does both in one PUT; other adapters may need a separate API call after the field write. The contract does not constrain how — only that the call appear atomic from the skill’s point of view.
- Output. A diff dict —
{added: [...], removed: [...], changed: [...]}— that the skill can show the user as part of the sync confirmation. Empty diff means the record was already up to date; the skill suppresses the confirmation prompt in that case. - No-op case. The
noneadapter returns{added: [], removed: [], changed: []}and writes nothing. Theunknown-state return fromfetch_current_statealso causes the skill to skippush_update— the adapter has nowhere to push to.
publish(cve_id) to ok
Move the record to its terminal public state.
- Lifecycle moment. Fires inside
security-issue-syncat the publication step, after the public advisory archive URL has been captured on the tracker. The captured archive URL is the real-world signal that the advisory has actually shipped to the users-list; before that point the adapter would be publishing a record before the world has heard about the issue, which is the opposite of the desired ordering. - Inputs. The CVE ID.
- Output.
ok(a sentinel; the skill does not inspect the return body — failure raises). The skill follows up withfetch_current_stateto confirm the state landed atpublicand posts a confirmation comment on the tracker. - No-op case. The
noneadapter raisesNotApplicable. The skill treats this as “this adopter does not publish CVEs; the tracker close is the only terminal action” and proceeds to the archive-from-board step directly. Theghsaadapter implements this as a GraphQLpublishSecurityAdvisorymutation.
retract(cve_id, reason) to ok
Mark an allocated-but-not-public record as rejected.
- Lifecycle moment. Fires inside
security-issue-invalidatefor trackers that already carry a CVE ID. CVE retraction is governance-sensitive; the skill requires explicit confirmation from a release-vote-gating role (governance.cve_allocation_gatefromproject.md) before invokingretract. The retracted state is terminal — once a record has been retracted, no subsequentpush_updateorpublishis valid. - Inputs.
cve_id— as above.reason— a short string captured from the tracker discussion explaining the retraction. The adapter is responsible for writing this into the appropriate field of its tool’s record (Vulnogram’sCNA_private.justification, CVE.org’srejectedReason, etc.).
- Output.
oksentinel as forpublish. - No-op case. The
noneadapter raisesNotApplicable. The skill falls back to “close the tracker as invalid; there is no CVE record to retract.” For adapters whose tool does not support retraction ofpublicrecords (Vulnogram refuses this; CVE.org has a separate REJECT flow), the adapter must raise a distinguishableAlreadyPublicerror and the skill escalates to the configured governance contact.
Generic state verbs
The skills speak in generic verbs about a CVE record’s lifecycle. The adapter is responsible for mapping its tool’s native states onto these verbs. The verbs are:
| Verb | Meaning | Vulnogram-native state |
|---|---|---|
allocated |
Record exists, ID is reserved, content is being filled in. Not visible publicly. | DRAFT |
review-ready |
Record content is complete and ready for CNA review. Reviewer comments may arrive at this state. Not visible publicly. | REVIEW |
publish-ready |
Record content is final, reviewer comments addressed, staged for the advisory-send step. The advisory emails are dispatched from the CVE tool while in this state. Not visible publicly. | READY |
public |
Record pushed to cve.org and world-readable. Terminal in the success path. |
PUBLIC |
retracted |
Record marked rejected post-allocation. Terminal in the failure path. | REJECTED (in CNA_private.state) |
unknown |
The adapter cannot determine the state (network failure, asynchronous tool that hasn’t replied yet, none backend). Skills treat this as “fall back to the tracker body’s view.” |
n/a |
The map is adapter-internal. Skills never write DRAFT or
REVIEW — they write allocated and review-ready. An adapter
that needs a more granular internal model is free to introduce
sub-states inside its tool/ directory, as long as the
contract-facing methods normalise on the verbs above.
The DRAFT to REVIEW transition is sync-driven (the tracker body
fields determine readiness) in the Vulnogram adapter; the
REVIEW to READY transition is release-manager-driven because the
adapter cannot tell from the tracker body alone whether reviewer
comments are still pending. Other adapters may collapse these two
transitions into one (the GHSA adapter has no separate
review/publish-ready distinction) or split them further (a
hypothetical multi-stage CNA tool with REVIEW to ADDRESSING →
READY). The contract does not constrain how the adapter maps
its internal states onto the four generic verbs — only that the
verbs are what the skills see.
Skills that consume this contract
The CVE-tool contract is consumed by four skills today.
Each runs the operations as cve-tool <operation>, mostly through the commands the
security-management helpers print:
security-cve-allocate— callsallocateto reserve the CVE ID and create the initial record, then writes the ID back onto the tracker’s CVE tool link body field. The skill is PMC-gated (orgovernance.cve_allocation_gate-gated for non-ASF adopters); the adapter does not enforce that gate itself — the skill does.security-issue-sync— callsfetch_current_stateat Step 1e (to surface reviewer-comment signals) and at Step 5b (to gate the release-manager hand-off on the post-push state beingreview-ready). Callspush_updateat Step 5b on every run that regenerates the CVE JSON, so the record never drifts from the body. Callspublishat the publication step after the public advisory archive URL has been captured.security-issue-invalidate— usesfetch_current_stateat its Step 0 gate. A record inallocatedorreview-readystops the skill until it is retracted at the CVE tool (the retraction is a separate, governance-gated flow);publish-readyorpublicescalates togovernance.escalation_contact, since an invalid close there has public consequences.security-issue-deduplicate— callspush_updateon the kept tracker’s CVE record after merging in credits and references from the duplicate tracker. The duplicate tracker’s CVE record (if any) is the subject of a separateretractcall once the dedup decision has been confirmed.
These four skills are the only consumers in the current shape of
the framework. Future skills that need to touch a CVE record
(e.g. a hypothetical security-cve-rotate-credit action) will
extend the contract rather than reaching past it into a specific
adapter.
ASF default — Vulnogram
The ASF reference adapter lives at tools/cve-tool-vulnogram/.
It is the only adapter shipping today, and the only adapter the
skills are tested against. Key properties of the ASF default:
- URL prefix:
https://cveprocess.apache.org/cve5/<CVE-ID>. The record page,#sourcetab,#jsontab, and#emailtab are all rooted there. Seetools/cve-tool-vulnogram/record.mdfor the canonical URL table. - Email preview URL:
https://cveprocess.apache.org/cve5/<CVE-ID>#email. Renders the advisory exactly as Vulnogram will dispatch it to the users-list and announce-list — same subject, same body, same recipient list. The release-manager checklist calls this out as a load-bearing checkpoint before the advisory-send step. - Source tab URL:
https://cveprocess.apache.org/cve5/<CVE-ID>#source. The copy-paste fallback target for the JSON record. The default write path is the OAuth-authenticated API (cve-tool push, which runsvulnogram-api-record-update); copy-paste is the documented fallback when the OAuth session has expired or the operator has opted out. - State machine:
DRAFTtoREVIEWtoREADYtoPUBLIC, carried insideCNA_private.stateon the CVE 5.x record. The adapter maps these onto the generic verbs as shown in the state-verb table above. - Reviewer-comment channel: mailing-list (the ASF CNA
reviewers email the project’s
security_listrather than surfacing comments on the tracking issue directly). This is thecve_authority.reviewer_channel: mailing-listsetting inproject.md; an adapter could equally well declarereviewer_channel: github-pr(for a CNA tool that uses pull requests as its review surface) orreviewer_channel: none(for a CNA tool with no separate review step). - Publication propagation: poll (the skills check the public
advisory archive on every sync rather than waiting for a
webhook). This is the
cve_authority.publication_propagation: pollsetting inproject.md.
Configuration
A project inherits its CVE-tool choice from its organization’s cve_authority block
(the ASF’s names vulnogram, the independent baseline’s names mitre-form),
and declares the block in <project-config>/project.md only to differ from it.
The shape is:
cve_authority:
tool: vulnogram # vulnogram | cve-org-direct | mitre-form | ghsa | none
allocate_url: "https://cveprocess.apache.org/cve5/new"
record_url_template: "https://cveprocess.apache.org/cve5/{cve_id}"
source_tab_url_template: "https://cveprocess.apache.org/cve5/{cve_id}#source"
email_preview_url_template: "https://cveprocess.apache.org/cve5/{cve_id}#email"
states: [allocated, review-ready, publish-ready, public]
publication_propagation: poll # poll | webhook | manual
emits_allocation_email: true
reviewer_channel: mailing-list # mailing-list | github-pr | none
Field-by-field:
tool— names the adaptercve-toolruns. The ASF default isvulnogram(the adapter insrc/cve_tool/adapters/vulnogram.py, overtools/cve-tool-vulnogram/). Adopters using a different CVE-tool backend pick one of the other four enumerated values, each of which is expected to resolve to a siblingtools/cve-tool-<name>/directory and an adapter module (see Adding an adapter).allocate_url— the URL the human operator opens to begin the allocation flow (for tool-mediated allocation paths) or the API endpoint the adapter POSTs to (for fully automated paths). The Vulnogram default is the/cve5/newform; the MITRE-form default would behttps://cveform.mitre.org/.record_url_template— the per-record URL pattern. The{cve_id}placeholder is the only token the skills substitute. Skills use this for the “open the CVE record” links they post on the tracker.source_tab_url_template— the copy-paste fallback target. Optional for adapters that have no copy-paste fallback (e.g. GHSA — there is no JSON form to paste into). When the field is null, the skills suppress the copy-paste fallback proposal.email_preview_url_template— the advisory-email preview URL. Optional for adapters whose CVE tool does not dispatch the advisory itself; when null, the release-manager checklist omits the preview step. The ASF default points at the#emailtab.states— the ordered list of generic state verbs the adapter exposes. Adapters with fewer states (the GHSA adapter collapsesreview-readyandpublish-readyinto a single pre-publish state; thenoneadapter has onlyallocatedandunknown) declare a shorter list. Skills branch on the declared list when deciding which lifecycle steps apply.publication_propagation— how the skills learn that a record has reachedpublic.poll(the ASF default) means the skills check the public archive on every sync;webhookmeans an external hook updates the tracker directly;manualmeans a human flips the tracker label and the skills trust it.emits_allocation_email— whether the CVE tool sends an allocation-confirmation email atallocatetime. The ASF default istrue(Vulnogram emails the project’ssecurity_liston every allocation); the MITRE-form default is alsotrue(the form replies with the allocated ID); GHSA’s default isfalse(no email — the allocation result is the API response). Skills that wait on this email surface a “do not close this tracker until the allocation email lands” hint when the flag istrue.reviewer_channel— where reviewer comments arrive.mailing-list(ASF default) meanssecurity-issue-syncreads reviewer comments off the security mailing list;github-prmeans it reads them off a backing PR;nonemeans there is no separate review step.
The contract does not constrain how the adapter implements any of
these settings — only that the settings are present and that the
adapter respects them. Adapters are free to add their own
tool-specific sub-keys under cve_authority.<adapter-name>: (e.g.
cve_authority.vulnogram.asf_org_id, cve_authority.vulnogram.cna_private_owner)
for fields the contract does not surface.