CVE allocation — capability-flag vocabulary

This file is the standalone vocabulary reference for the three workflow-diverging capability flags that the security-cve-allocate skill branches on. It is the CVE-allocation counterpart to the release-management-config.md Backends section, which documents the equivalent flags for the release-management family.

The flag values are declared in <project-config>/project.md under the cve_authority: and governance: YAML blocks (see § CVE authority and § Governance). This file explains the full allowed-value set for each flag, the workflow implications of each choice, and the non-ASF adoption paths.

Overview

The security-cve-allocate skill is the allocation-step gate in the security-issue lifecycle. It diverges at three decision points that differ by ecosystem:

Which CNA tool allocates the CVE record (cve_authority.tool).
Who is authorised to trigger allocation (governance.cve_allocation_gate).
Where the draft record is reviewed before publication (cve_authority.reviewer_channel).

All three are capability flags: an ASF TLP adopter leaves them at their defaults and the skill behaves identically to how it runs in the reference <org>/<repo> adopter. A non-ASF adopter overrides one or more flags to match their CNA program, and the skill emits backend-appropriate recipes without any skill-body edits.

Capability flags

Flag	ASF default	Location in `project.md`
`cve_authority.tool`	`vulnogram`	`### CVE authority` → `tool:`
`governance.cve_allocation_gate`	`pmc-member`	`### Governance` → `cve_allocation_gate:`
`cve_authority.reviewer_channel`	`mailing-list`	`### CVE authority` → `reviewer_channel:`

`cve_authority.tool`

Selects the CNA tool adapter the skill uses to allocate and manage CVE records.

Value	Description	When to use
`vulnogram`	ASF-hosted Vulnogram instance. The skill prints the allocation URL (`cve_authority.allocate_url`), the user pastes the stripped title, and Vulnogram auto-emails the assigner list on submission. The adapter lives under `tools/cve-tool-vulnogram/`.	ASF TLP default. Any project whose CNA is the ASF CNA (`f0158376-9dc2-43b6-827c-5f631a4d8d09`). Also valid for projects on any other Vulnogram tenant — override `allocate_url`, `record_url_template`, and `source_tab_url_template` in `project.md` to point at the tenant's URLs.
`mitre-form`	MITRE CNA web form (`https://cveform.mitre.org/`). The skill produces a paste-ready MITRE submission body the operator submits manually. No API; the form is the allocation surface.	Projects that are sub-CNAs of MITRE's root CNA and do not have their own Vulnogram instance. Typically research groups or small foundations not yet running their own CNA program.
`cve-org-direct`	CVE.org CVE Services REST API (`https://cveawg.mitre.org/api/`). The skill calls the API with the adopter's org ID and API key (stored in `.apache-magpie-overrides/user.md` → `cve_api_key`). The allocation and record-update steps are fully automated — no copy-paste.	Projects that have their own CNA org registered with MITRE and hold CVE Services API credentials. Non-ASF foundations with an active CNA programme.
`ghsa`	GitHub Security Advisory (GHSA) only. The skill opens or updates a GHSA on the upstream repo via `gh api` without allocating a separate CVE ID. The GHSA slug (`GHSA-xxxx-yyyy-zzzz`) is the canonical public identifier; MITRE may later assign a CVE ID from the GHSA, but that is outside the skill's scope.	Projects that opt out of CNA participation in favour of GHSA-only disclosure. Common for small GitHub-hosted projects where GitHub's CVE-review programme covers the disclosure channel.
`none`	No formal CVE allocation. The skill skips the allocation step and produces only a disclosure advisory (milestone notification, advisory text). Nothing is submitted to any CNA.	Projects that do not participate in any CNA programme and whose security policy does not require CVE IDs. Typically very early-stage projects or internal tooling.

ASF TLP constraint: ASF top-level projects are sub-CNAs under the ASF CNA. Switching cve_authority.tool away from vulnogram requires approval from the ASF Security team. Apache Incubator podlings may use none or ghsa during incubation and switch to vulnogram at graduation.

`governance.cve_allocation_gate`

Controls which operators are authorised to trigger the CVE allocation step (Step 3 of security-cve-allocate). The skill checks this gate against the running user's role_flags in .apache-magpie-overrides/user.md and against the roster source declared in governance.roster_url. Users who do not pass the gate receive a relay message to forward to an authorised member instead of a self-service allocation recipe.

Value	Description	When to use
`pmc-member`	ASF PMC membership, verified via ASF OAuth into Vulnogram. The CVE tool's allocation button is disabled for non-PMC users; the relay message targets currently-authorised PMC members listed at `governance.roster_url`.	ASF TLP default. Any project whose CNA program restricts allocation to a governance committee.
`security-team-member`	Any member of the security team, as declared in `roster.source`. Broader than `pmc-member` — suitable when the full triage team holds allocation rights. The relay message targets the security team on `<security-list>`.	Non-ASF adopters whose CNA does not restrict allocation to a formal governance committee. Common for projects where the security team and the governance body largely overlap, or where the CNA simply requires “an authorised team member”.
`maintainer`	Any project committer (anyone with write access to `<upstream>`). No formal authority gate — the skill issues a self-service recipe to any operator with tracker access. The relay path is not used.	Small projects where the distinction between security-team member and committer is not maintained, or projects whose CNA programme has no allocation gate at all.
`none`	No gate. The skill does not check authority and produces a self-service recipe for every operator.	Projects using `cve_authority.tool: ghsa` (GitHub handles authority natively) or `tool: none` (no CNA submission). Inappropriate for any project that actually submits to a CNA.

`cve_authority.reviewer_channel`

Where the draft CVE record — after allocation but before publication — is reviewed by the security team. This is the “human-review gate” before the CNA publishes the record publicly.

Value	Description	When to use
`mailing-list`	Review discussion happens on `governance.private_governance_list` (for ASF: `private@<project>.apache.org`). The skill drafts an email to that list containing the CVE JSON link and the record's current state.	ASF TLP default. Any project with a private mailing list for governance discussions. Preserves a thread-based audit trail.
`github-pr`	Review happens as a draft PR on the tracker repo. The skill opens or updates a PR with the CVE JSON diff for team members to approve.	Adopters who prefer PR-based review workflows (approvals, inline comments) over mailing-list threads. Requires the tracker repo to be readable by all reviewers.
`none`	No formal review gate between allocation and publication. The skill proceeds directly to the “push record to CNA tool” step.	Projects using `cve_authority.tool: ghsa` (GitHub's advisory review is the gate) or `tool: none`. Also appropriate for `cve-org-direct` adopters whose CNA programme permits immediate publication without a separate review window.

Configuring the flags

The flag values live in <project-config>/project.md. To adopt:

Copy projects/_template/project.md → <project-config>/project.md if you have not already done so.
In the ### CVE authority YAML block, set cve_authority.tool to the value matching your CNA programme.
In the ### Governance YAML block, set governance.cve_allocation_gate to the value matching your authority model.
In the ### CVE authority YAML block, set cve_authority.reviewer_channel to the value matching your review workflow.
Update the remaining cve_authority.* URL fields (allocate_url, record_url_template, source_tab_url_template, email_preview_url_template) to point at your CNA tool's endpoints, or leave them blank / null if the chosen tool value does not use those fields (e.g. ghsa and none need no URL config).

ASF default (no changes needed for a fresh ASF TLP adopter):

cve_authority:
  tool: vulnogram
  reviewer_channel: mailing-list
  # ... URL fields already filled in with ASF Vulnogram endpoints

governance:
  cve_allocation_gate: pmc-member

Non-ASF example (GHSA-only, no formal gate):

cve_authority:
  tool: ghsa
  reviewer_channel: none
  allocate_url: null
  record_url_template: https://github.com/<upstream>/security/advisories/<GHSA-ID>
  source_tab_url_template: null
  email_preview_url_template: null

governance:
  cve_allocation_gate: maintainer

Non-ASF example (own CNA, CVE.org direct API, PR-based review):

cve_authority:
  tool: cve-org-direct
  reviewer_channel: github-pr
  allocate_url: https://cveawg.mitre.org/api/cve-id
  record_url_template: https://cveawg.mitre.org/api/cve/<CVE-ID>
  source_tab_url_template: null
  email_preview_url_template: null

governance:
  cve_allocation_gate: security-team-member

Non-ASF adopter quick-start

Pick the row matching your situation:

Situation	`cve_authority.tool`	`governance.cve_allocation_gate`	`cve_authority.reviewer_channel`
ASF TLP	`vulnogram`	`pmc-member`	`mailing-list`
ASF podling (pre-graduation)	`none` or `ghsa`	`maintainer`	`none`
Non-ASF, own CNA (Vulnogram tenant)	`vulnogram` (override URLs)	`security-team-member`	`mailing-list`
Non-ASF, own CNA (CVE.org API)	`cve-org-direct`	`security-team-member`	`github-pr` or `mailing-list`
Non-ASF, MITRE sub-CNA (no tool)	`mitre-form`	`security-team-member`	`mailing-list`
Non-ASF, GHSA only	`ghsa`	`maintainer`	`none`
No formal CVE programme	`none`	`none`	`none`

Cross-references

project.md — the cve_authority: and governance: YAML blocks where the flag values are declared and stored.
security-model.md — project security policy URL and the disclosure timeline the CVE workflow enforces.
tools/cve-tool-vulnogram/ — ASF default CNA tool adapter (Vulnogram).
tools/cve-org/ — CVE.org / CVE Services API helpers (for cve-org-direct).
security-cve-allocate skill — the skill that reads and branches on these flags at run time.
release-management-config.md — the parallel backend-flag vocabulary for the release-management family, which established the pattern this file follows.