This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 7e04a8ef feat(project-agnosticism): add cve-allocation-config.md
capability-flag vocabulary (#562)
7e04a8ef is described below
commit 7e04a8ef3ce1b8a43ca5e4ceb7be5d4251f5925f
Author: Justin Mclean <[email protected]>
AuthorDate: Sat Jun 27 06:15:03 2026 +1000
feat(project-agnosticism): add cve-allocation-config.md capability-flag
vocabulary (#562)
Documents the three workflow-diverging capability flags for the
security-cve-allocate skill: cve_authority.tool (vulnogram /
mitre-form / cve-org-direct / ghsa / none), governance.cve_allocation_gate
(pmc-member / security-team-member / maintainer / none), and
cve_authority.reviewer_channel (mailing-list / github-pr / none).
Closes the third and final gap in project-agnosticism.md Known Gaps
("capability-flag vocabulary is defined only for release-management"):
capability-flags-committer-intake and capability-flags-security-intake
cover the other two gaps; this branch covers CVE allocation.
Generated-by: Claude (Opus 4.7)
---
projects/_template/cve-allocation-config.md | 197 ++++++++++++++++++++++++++++
1 file changed, 197 insertions(+)
diff --git a/projects/_template/cve-allocation-config.md
b/projects/_template/cve-allocation-config.md
new file mode 100644
index 00000000..282519f3
--- /dev/null
+++ b/projects/_template/cve-allocation-config.md
@@ -0,0 +1,197 @@
+<!-- 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 today in
+`airflow-s/airflow-s`. 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_temp [...]
+| `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 [...]
+| `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.
