projects/_template/cve-allocation-config.md - magpie - Git at Google

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