<!-- 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)*

- [CVE allocation — capability-flag vocabulary](#cve-allocation--capability-flag-vocabulary)
  - [Overview](#overview)
  - [Capability flags](#capability-flags)
    - [`cve_authority.tool`](#cve_authoritytool)
    - [`governance.cve_allocation_gate`](#governancecve_allocation_gate)
    - [`cve_authority.reviewer_channel`](#cve_authorityreviewer_channel)
  - [Configuring the flags](#configuring-the-flags)
  - [Non-ASF adopter quick-start](#non-asf-adopter-quick-start)
  - [Cross-references](#cross-references)

<!-- 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 -->

# 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`](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](project.md#cve-authority) and
[§ Governance](project.md#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:

1. **Which CNA tool** allocates the CVE record (`cve_authority.tool`).
2. **Who is authorised** to trigger allocation (`governance.cve_allocation_gate`).
3. **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](https://cveprocess.apache.org/) 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:

1. Copy `projects/_template/project.md` → `<project-config>/project.md`
   if you have not already done so.
2. In the `### CVE authority` YAML block, set `cve_authority.tool` to
   the value matching your CNA programme.
3. In the `### Governance` YAML block, set `governance.cve_allocation_gate`
   to the value matching your authority model.
4. In the `### CVE authority` YAML block, set
   `cve_authority.reviewer_channel` to the value matching your review
   workflow.
5. 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):

```yaml
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):

```yaml
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):

```yaml
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`](project.md) — the `cve_authority:` and `governance:`
  YAML blocks where the flag values are declared and stored.
- [`security-model.md`](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`](release-management-config.md) — the
  parallel backend-flag vocabulary for the release-management family,
  which established the pattern this file follows.
