Skip to content

feat(security): CVE-authority sub-tool extract (PR4/5)#388

Merged
potiuk merged 3 commits into
apache:mainfrom
potiuk:feat-security-genericization-pr4-cve-tool
May 30, 2026
Merged

feat(security): CVE-authority sub-tool extract (PR4/5)#388
potiuk merged 3 commits into
apache:mainfrom
potiuk:feat-security-genericization-pr4-cve-tool

Conversation

@potiuk

@potiuk potiuk commented May 30, 2026

Copy link
Copy Markdown
Member

Summary

Fourth of 5 PRs converting the security skill family from
Airflow/ASF-coupled to a generic framework with ASF as the
default-configured option. This is the biggest skill-side PR.

Two commits in this PR (kept separate for reviewability):

  1. chore — mechanical rename tools/vulnogram/
    tools/cve-tool-vulnogram/. 40 files updated via search-and-
    replace + docs row repositioned + stale venvs cleaned.
    No behaviour change.

  2. feat — substantive content lift. 4 skills + 2 docs
    rewritten to read the cve_authority config block + speak
    in tool-agnostic state verbs (allocatedreview-ready
    publish-readypublic).

Byte-equivalent for the airflow-s adopter. cve_authority.tool: vulnogram (the ASF default) resolves <cve-tool> to
cve-tool-vulnogram. Vulnogram-native DRAFT/REVIEW/READY/
PUBLIC states are preserved as named-example asides. Every
Vulnogram CLI (vulnogram-api-setup, vulnogram-api-check,
vulnogram-api-record-update, vulnogram-api-record-fetch) is
still named where the operator's command-line invocation actually
fires.

Per-target lifts

Target Lines Highlights
security-cve-allocate +222/-137 Frontmatter speaks of governance.cve_allocation_gate + configured <cve-tool> allocation URL. Body reads cve_authority.allocate_url / .record_url_template / .source_tab_url_template / .emits_allocation_email. PMC-only golden rule → governance.cve_allocation_gate + governance.roster_url. Rollup template uses <record-url>/<source-tab-url> tokens.
security-issue-sync Steps 5b/5c +139/-91 Largest single section. Step 5b reframes push as push_update(cve_id, fields, state_transition=None); replaces DRAFT/REVIEW/READY/PUBLIC with state verbs. publish() called via cve_authority.publication_propagation. Step 5c generalises variant-template table to tools/<cve-tool>/... paths.
security-issue-invalidate Step 0 +29/-1 Hard-stop CVE-state check lifts from DRAFT/REVIEW/REJECTED to generic state verbs. Retract flow → adapter's retract() method.
security-issue-deduplicate +54/-6 Dedup-when-both-have-CVE branch speaks state verbs. Merge-of-credits → <cve-tool>'s push_update().
docs/security/process.md Steps 12-14 +96/-53 Allocate / update / publish steps reference cve_authority.* + <cve-tool> methods + state verbs.
docs/security/roles.md +50/-27 Role descriptions lift Vulnogram-specific OAuth + state-machine references; PMC → governance-authorisation.

Aggregate: 6 files in the content commit, +590/-315 lines.
Plus the mechanical rename touching 40 files.

The contract

tools/cve-tool/README.md (landed in
#381) is
now the canonical contract: every skill body references
push_update, fetch_current_state, publish, retract,
allocate. The Vulnogram adapter at
tools/cve-tool-vulnogram/ is one implementation; alternative
adapters (CVE.org direct, MITRE form, GHSA-only) plug in via
cve_authority.tool without skill-body changes.

What is not in this PR

PR5 picks up:

  • docs/security/threat-model.md
  • docs/security/forwarder-routing-policy.md
  • docs/security/how-to-fix-a-security-issue.md
  • docs/security/new-members-onboarding.md
  • Final scrub: any remaining literal @potiuk / @raboof /
    Apache Airflow / airflow | providers | chart in skill
    bodies and templates.

Test plan

  • uv run --project tools/skill-and-tool-validator skill-and-tool-validate
    clean (5 advisory soft warnings, none hard, all on files
    outside PR4 scope).
  • pytest clean for the validator (218 tests).
  • All pre-commit hooks pass.
  • Spot-read the rendered security-cve-allocate and
    security-issue-sync Step 5b/5c on GitHub to confirm the
    contract-layer prose reads correctly and the Vulnogram
    named-example asides land where they should.
  • Confirm the airflow-s adopter, with
    cve_authority.tool: vulnogram (the ASF default), still
    resolves to the same behaviour as today
    (byte-equivalence invariant).

potiuk added 3 commits May 30, 2026 20:23
Prep commit for PR4 (CVE-authority sub-tool extract).

Mechanical rename only:
- `git mv tools/vulnogram tools/cve-tool-vulnogram`
- 40 files updated via search-and-replace for the path string
- docs/labels-and-capabilities.md tool-table row repositioned to
  alphabetical order, description updated to name it as the
  default adapter implementing the tools/cve-tool/ contract

No behaviour change. Skills continue to reference the directory
at its new path. The substantive lift to read the cve_authority
config + tool-agnostic state verbs is the next commit on this
branch.

Generated-by: Claude Code (Opus 4.7)
Fourth of 5 PRs converting the security skill family from
Airflow/ASF-coupled to a generic framework with ASF as the
default-configured option.

This is the biggest skill-side PR. The previous commit on this
branch (ca47278) did the mechanical rename
tools/vulnogram/ -> tools/cve-tool-vulnogram/. This commit does
the substantive content lift: 4 skills + 2 docs rewritten to
read the cve_authority config block + speak in tool-agnostic
state verbs.

Byte-equivalent for the airflow-s adopter: cve_authority.tool:
vulnogram (the ASF default) resolves <cve-tool> to
cve-tool-vulnogram, the Vulnogram-native DRAFT/REVIEW/READY/PUBLIC
states are preserved as named-example asides, every Vulnogram CLI
(vulnogram-api-setup, vulnogram-api-check,
vulnogram-api-record-update, vulnogram-api-record-fetch) is still
named where the operator's command-line invocation fires.

Per-target lifts:

- security-cve-allocate (+222/-137) — frontmatter description
  speaks of governance.cve_allocation_gate + the configured
  <cve-tool> allocation URL; preamble declares <cve-tool>
  placeholder. Body: intro paragraph reads
  cve_authority.allocate_url; PMC-only golden rule becomes
  governance.cve_allocation_gate + governance.roster_url; Step 0
  preflight uses generic governance-authorisation; Step 2 / Step 3
  / Step 4 / Step 7 read cve_authority.* knobs and reference the
  contract in <cve-tool>/README.md. Rollup template uses
  <record-url>/<source-tab-url> tokens substituted from
  cve_authority.record_url_template /
  cve_authority.source_tab_url_template.

- security-issue-sync Steps 5b/5c (+139/-91) — the
  largest single section. Step 5b reframes the push as the
  contract's push_update(cve_id, fields, state_transition=None)
  method; replaces DRAFT/REVIEW/READY/PUBLIC with generic verbs
  (allocated / review-ready / publish-ready / public),
  Vulnogram-native tokens kept as named-example asides;
  publish() method called via cve_authority.publication_propagation;
  post-push state verification via fetch_current_state(cve_id).
  Step 5c generalises the variant-template table to
  tools/<cve-tool>/... paths and replaces OAuth-push branch
  labels with push_update succeeded / failed terminology.

- security-issue-invalidate Step 0 (+29/-1) — hard-stop check
  on CVE state lifts from Vulnogram DRAFT/REVIEW/REJECTED to
  generic state verbs (allocated / review-ready); the
  separate retract flow reference becomes the adapter's
  retract() method per <cve-tool>/README.md.

- security-issue-deduplicate (+54/-6) — dedup-when-both-have-CVE
  branch speaks in state verbs; merge-of-credits flow
  references <cve-tool>'s push_update() per the contract;
  regenerate-CVE-JSON step mentions adapter storage.

- docs/security/process.md Steps 12-14 (+96/-53) — allocate
  / update / publish steps reference cve_authority.* knobs +
  <cve-tool> methods + state verbs; Vulnogram URLs kept as
  named-example asides.

- docs/security/roles.md (+50/-27) — role descriptions lift
  Vulnogram-specific OAuth + state-machine references to
  cve_authority knobs + generic state verbs; PMC ->
  governance-authorisation under governance.cve_allocation_gate.

Aggregate: 6 files, +590/-315 lines. Validator clean (5 advisory
soft warnings, none hard, all on files outside PR4 scope).
218 tests green.

The generic surface (push_update, fetch_current_state, publish,
retract, allocate) is the contract layer in tools/cve-tool/README.md
(landed in PR1 apache#381). The Vulnogram adapter is now an
implementation of that contract, named where the operator's
command-line tool actually fires; the skill body speaks contract.

Out of scope (PR5):

- docs/security/threat-model.md, forwarder-routing-policy.md,
  how-to-fix-a-security-issue.md, new-members-onboarding.md
- Final scrub: any remaining literal @potiuk / @raboof /
  Apache Airflow / airflow | providers | chart in skill bodies
  and templates

Generated-by: Claude Code (Opus 4.7)
The earlier rename sed (ca47278) matched "tools/vulnogram" verbatim,
but three files had link targets in the relative form "../vulnogram/"
(visible text already said "tools/cve-tool-vulnogram/" — only the URL
target was stale):

- tools/cve-org/tool.md         -> 1 link
- tools/cve-tool/README.md      -> 2 links (incl. an #record-urls anchor)
- tools/forwarder-relay/README.md -> 3 links to bot-credits-policy.md

Update each "../vulnogram/..." -> "../cve-tool-vulnogram/..." and
sweep the rest of the tree for stragglers (none found).

Generated-by: Claude Code (Opus 4.7)
@potiuk potiuk merged commit 6c16c56 into apache:main May 30, 2026
17 checks passed
potiuk added a commit that referenced this pull request May 30, 2026
Fifth and final PR of the security genericization series.

Lifts the remaining 4 docs in docs/security/ to read config knobs
from projects/_template/project.md and the contract docs from
PR1-PR4 (cve_authority.*, governance.*, security_inbox.*,
forwarders.*, archive_system.*, scope_detection.*). Plus a final
scrub of 4 skills for leftover ASF/Vulnogram literals.

Byte-equivalent for the airflow-s adopter: every ASF/Airflow/
Vulnogram-specific value either resolves through a config knob
whose ASF default matches today's behaviour, OR stays as one
named-example aside in generic prose.

Per-target lifts:

- docs/security/threat-model.md (+107/-77) — Purpose/Scope/
  Assumptions reframed from "ASF"/"PMC" to governance-knob
  terms. STRIDE matrix rows A.6/A.7/C.1-C.4/E.1-E.2 lifted:
  Vulnogram -> <cve-tool>; security@apache.org -> <security-list>;
  DRAFT/REVIEW/READY/PUBLIC -> cve_authority.states sequence
  (allocated -> review-ready -> publish-ready -> public).
  Mitigations M.10/M.16/M.18/M.19/M.27 + residual risks
  #3/#8/#10/#11 + re-audit cadence ownership generalised.

- docs/security/forwarder-routing-policy.md (+42/-27) — references
  the optional security-issue-import-via-forwarder sub-skill from
  PR3 (#387) and the tools/forwarder-relay/README.md contract.
  Replaces "ASF-security relay" / "security@apache.org" with
  forwarders.enabled / <security-list> / foundation_security_address.
  ASF-Airflow shown as a named-example aside per concept.

- docs/security/how-to-fix-a-security-issue.md (+20/-8) —
  "governance-authorised member of the adopting project (per
  governance.cve_allocation_gate)" replaces "PMC member of
  apache/airflow"; <cve-tool> + cve_authority.* replaces Vulnogram-
  specific URLs and state names; archive_system.advisory_publication_signal_url
  replaces the lists.apache.org users-list URL.

- docs/security/new-members-onboarding.md (+26/-13) — onboarding-
  style register preserved. "PMC members and committers" reframed
  as "governance body that satisfies governance.cve_allocation_gate";
  per-user-config "PMC status" steps reference the governance knob;
  Vulnogram steps reference <cve-tool> via cve_authority.record_url_template.

- Final scrub of 4 skills (+17/-15 net): security-issue-import,
  security-issue-import-via-forwarder, security-issue-invalidate,
  security-issue-fix — leftover literal references caught and
  lifted to roster.bare_name_handles / governance.escalation_contact /
  forwarders.<adapter>.contact_handle.

Aggregate: 8 files, +240/-156 lines.

That closes the series. Five PRs (#381, #386, #387, #388, this)
transitioned the security skill family from Airflow/ASF-coupled to a
generic framework with ASF as the default-configured option. The
airflow-s adopter, with the ASF defaults baked into project.md, sees
byte-equivalent behaviour throughout. Non-ASF adopters override
specific dimensions (CVE authority, mail provider, archive system,
governance gate, scope axis) by changing only their <project-config>/
files.

Generated-by: Claude Code (Opus 4.7)
potiuk added a commit to potiuk/magpie that referenced this pull request Jun 1, 2026
…ity-suite refactor patterns

Adds `optimize-skill` (capability:setup) — the refactoring sibling of
`write-skill`. It takes an existing framework skill (or sweeps a set)
and applies the five restructuring patterns proven on the security
suite, as behavior-preserving proposals gated by the validator
(green-before / green-after):

- split — slim an oversized SKILL.md into linked siblings (the apache#410
  pattern; addresses the PRINCIPLES.md P14 cap)
- config-lift — move concrete values into <project-config> (apache#386/apache#387/apache#388)
- out-of-context — read/PATCH one field without loading the body
  (apache#412 github-body-field, apache#424 github-rollup)
- fetch-upfront — batch per-item round-trips (apache#347)
- preflight-classifier — skip obvious no-ops before LLM passes (apache#414/apache#416)

SKILL.md is 297 lines; the pass catalogue (smell / exemplar PR /
mechanics / behavior-preservation guarantee / validation) lives in
the patterns.md sibling. Reads only framework-internal files, so no
injection-guard / Privacy-LLM callouts.

Ships a step-diagnose eval (5 auto-comparable cases incl. an
injection-resistance case) so the skill is not released without an
eval (P8). Wires the skill into the capability->skill map and the
eval index.

Generated-by: Claude Code (Opus 4.8)
potiuk added a commit to potiuk/magpie that referenced this pull request Jun 1, 2026
…ity-suite refactor patterns

Adds `optimize-skill` (capability:setup) — the refactoring sibling of
`write-skill`. It takes an existing framework skill (or sweeps a set)
and applies the five restructuring patterns proven on the security
suite, as behavior-preserving proposals gated by the validator
(green-before / green-after):

- split — slim an oversized SKILL.md into linked siblings (the apache#410
  pattern; addresses the PRINCIPLES.md P14 cap)
- config-lift — move concrete values into <project-config> (apache#386/apache#387/apache#388)
- out-of-context — read/PATCH one field without loading the body
  (apache#412 github-body-field, apache#424 github-rollup)
- fetch-upfront — batch per-item round-trips (apache#347)
- preflight-classifier — skip obvious no-ops before LLM passes (apache#414/apache#416)

SKILL.md is 297 lines; the pass catalogue (smell / exemplar PR /
mechanics / behavior-preservation guarantee / validation) lives in
the patterns.md sibling. Reads only framework-internal files, so no
injection-guard / Privacy-LLM callouts.

Ships a step-diagnose eval (5 auto-comparable cases incl. an
injection-resistance case) so the skill is not released without an
eval (P8). Wires the skill into the capability->skill map and the
eval index.

Generated-by: Claude Code (Opus 4.8)
potiuk added a commit that referenced this pull request Jun 1, 2026
…ity-suite refactor patterns (#427)

Adds `optimize-skill` (capability:setup) — the refactoring sibling of
`write-skill`. It takes an existing framework skill (or sweeps a set)
and applies the five restructuring patterns proven on the security
suite, as behavior-preserving proposals gated by the validator
(green-before / green-after):

- split — slim an oversized SKILL.md into linked siblings (the #410
  pattern; addresses the PRINCIPLES.md P14 cap)
- config-lift — move concrete values into <project-config> (#386/#387/#388)
- out-of-context — read/PATCH one field without loading the body
  (#412 github-body-field, #424 github-rollup)
- fetch-upfront — batch per-item round-trips (#347)
- preflight-classifier — skip obvious no-ops before LLM passes (#414/#416)

SKILL.md is 297 lines; the pass catalogue (smell / exemplar PR /
mechanics / behavior-preservation guarantee / validation) lives in
the patterns.md sibling. Reads only framework-internal files, so no
injection-guard / Privacy-LLM callouts.

Ships a step-diagnose eval (5 auto-comparable cases incl. an
injection-resistance case) so the skill is not released without an
eval (P8). Wires the skill into the capability->skill map and the
eval index.

Generated-by: Claude Code (Opus 4.8)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant