Skip to content

feat(security): docs lift + final scrub (PR5/5)#399

Merged
potiuk merged 1 commit into
apache:mainfrom
potiuk:feat-security-genericization-pr5-docs-scrub
May 30, 2026
Merged

feat(security): docs lift + final scrub (PR5/5)#399
potiuk merged 1 commit into
apache:mainfrom
potiuk:feat-security-genericization-pr5-docs-scrub

Conversation

@potiuk

@potiuk potiuk commented May 30, 2026

Copy link
Copy Markdown
Member

Summary

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 that
survived earlier passes.

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

Target Lines Highlights
docs/security/threat-model.md +107/-77 Purpose/Scope/Assumptions reframed; STRIDE 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/PUBLICcve_authority.states sequence); 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 (PR3 #387) and the tools/forwarder-relay/README.md contract. forwarders.enabled / forwarders.<adapter>.contact_handle / foundation_security_address replace the inlined ASF-Security relay shape.
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.
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.
security-issue-import, -via-forwarder, -invalidate, -fix (scrub) +17/-15 Leftover literal references caught and lifted to roster.bare_name_handles / governance.escalation_contact / forwarders.<adapter>.contact_handle.

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

The series, end-to-end

PR Scope Status
#381 Schema + adapter contracts merged
#386 Config-driven lifts of 6 skills merged
#387 Forwarder-relay + mail-archive sub-tools merged
#388 CVE-authority sub-tool extract merged
(this) Docs lift + final scrub this PR

After this PR merges, the security skill family is generic by
default
:

  • For ASF projects (like airflow-s, the reference adopter):
    the ASF defaults in projects/_template/project.md resolve every
    knob to today's behaviour. Vulnogram URLs, PMC-only allocation,
    security@apache.org inbox, PonyMail archive, ASF-Security
    forwarder, airflow | providers | chart scope cascade — all
    unchanged at runtime.

  • For non-ASF adopters: override specific dimensions in
    <project-config>/project.md to plug in alternative
    CVE authorities (CVE.org direct submission, MITRE form, GHSA-only),
    mail providers (IMAP, Outlook, Discourse), archive systems
    (Hyperkitty, Discourse, Google Groups, GitHub Discussions),
    governance gates, scope axes, and roster sources. Adapter
    contracts in tools/cve-tool/README.md,
    tools/mail-archive/README.md, and
    tools/forwarder-relay/README.md describe the interface.

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 PR5 scope).
  • pytest clean for the validator (218 tests).
  • All pre-commit hooks pass.
  • Spot-read each rewritten doc on GitHub to confirm the
    airflow-s named-example asides land where they should and the
    generic prose reads cleanly.
  • Confirm the airflow-s adopter, with the ASF defaults
    unchanged, still gets the same security-flow behaviour as
    before (byte-equivalence invariant — the closing test for the
    series).

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
  apache#3/apache#8/apache#10/apache#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 (apache#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 (apache#381, apache#386, apache#387, apache#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 potiuk merged commit 1b66d15 into apache:main May 30, 2026
16 checks passed
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