git.stella-ops.org/docs/modules/scanner/design/schema-governance.md

Schema Governance for Scanner Outputs (SC9)

Status: Draft · Date: 2025-12-04 Scope: Define governance, approvals, RACI, and review cadence for schema bumps, downgrade adapters, and mapping table changes.

Objectives

• Establish clear ownership and approval workflows for schema changes.
• Define RACI matrix for schema-related decisions.
• Set review cadence and change control procedures.
• Ensure adapter tables are locked with documented changes.

RACI Matrix

Schema Changes

Activity	Product	Scanner TL	Sbomer TL	Policy TL	Ops	QA
CycloneDX version bump	A	R	C	C	I	C
CVSS version support	A	R	I	C	I	C
SLSA version bump	A	R	C	C	I	C
New evidence fields	A	R	C	C	I	C
CBOM property additions	A	R	C	C	I	C

Adapter Changes

Activity	Product	Scanner TL	Sbomer TL	Policy TL	Ops	QA
Downgrade adapter update	A	R	C	I	I	R
Mapping table changes	A	R	C	I	I	R
Hash update approval	A	R	I	I	I	R
Fixture updates	I	R	C	I	I	R

Release Artifacts

Activity	Product	Scanner TL	Sbomer TL	Policy TL	Ops	QA
Schema freeze	A	R	C	C	I	I
DSSE signing	I	C	I	I	R	I
Offline kit bundling	I	I	I	I	R	C
Release notes	R	C	C	C	C	I

Legend: R=Responsible, A=Accountable, C=Consulted, I=Informed

Schema Bump Workflow

1. Proposal Phase

graph LR
    A[RFC Draft] --> B[Technical Review]
    B --> C{Approved?}
    C -->|Yes| D[Implementation]
    C -->|No| A
    D --> E[Adapter Update]
    E --> F[Fixture Update]
    F --> G[Hash Freeze]
    G --> H[DSSE Sign]
    H --> I[Release]

2. Required Artifacts

Artifact	Owner	Location
RFC Document	Scanner TL	docs/rfcs/scanner/
Mapping CSV	Scanner TL	docs/modules/scanner/fixtures/adapters/
Golden Fixtures	QA	docs/modules/scanner/fixtures/cdx17-cbom/
Hash List	QA	docs/modules/scanner/fixtures/*/hashes.txt
DSSE Envelope	Ops	out/offline/scanner-standards-kit-v1/

3. Approval Gates

Gate	Approvers	Criteria
RFC Approval	Product + Scanner TL	Technical feasibility, backwards compat
Adapter Approval	Scanner TL + QA	Mapping completeness, determinism tests pass
Hash Freeze	Scanner TL + QA	All fixtures pass hash validation
DSSE Sign	Ops	All hashes recorded, offline kit complete
Release	Product	All gates passed, release notes approved

Review Cadence

Regular Reviews

Review	Frequency	Attendees	Scope
Schema Sync	Monthly	Scanner, Sbomer, Policy TLs	Upcoming changes, deprecations
Adapter Review	Per release	Scanner TL, QA	Mapping accuracy, test coverage
Hash Audit	Per release	QA, Ops	All fixture hashes valid

Ad-hoc Reviews

Triggered by:

• Upstream schema release (CycloneDX, SPDX, SLSA)
• Security advisory requiring field changes
• Customer request for new evidence types
• Determinism test failure

Change Control

Acceptable Changes

Change Type	Requires	Example
Add optional field	Scanner TL approval	New evidence property
Add required field	RFC + Product approval	New mandatory hash
Remove field	RFC + deprecation notice	Legacy property removal
Change ordering	Scanner TL + QA approval	Sort key update
Update hash	QA approval + documented reason	Fixture content change

Prohibited Changes

Change	Reason	Alternative
Silent hash update	Breaks determinism validation	Document change, get approval
Remove required field	Breaks consumers	Deprecate with N-1 support
Change field type	Breaks serialization	New field with migration
Reorder without docs	Breaks hash validation	Update ordering rules + hashes

Deprecation Policy

Deprecation Timeline

Phase	Duration	Actions
Announced	+0 days	Add deprecation notice to docs
Warning	+30 days	Emit warning in API responses
N-1 Support	+90 days	Old format still accepted
Removal	+180 days	Old format rejected

Deprecation Notice Format

{
  "deprecated": {
    "field": "ratings[method=CVSSv30]",
    "since": "v2.5.0",
    "removal": "v3.0.0",
    "replacement": "ratings[method=CVSSv31]",
    "migrationGuide": "docs/migrations/cvss-v30-removal.md"
  }
}

Adapter Locking

Lock Conditions

Adapters are locked when:

1. Hash recorded in hashes.txt
2. DSSE envelope signed
3. Offline kit bundled

Unlock Process

To modify a locked adapter:

1. Create new version (e.g., mapping-cvss4-to-cvss3-v2.csv)
2. Update hash file with new entry
3. Keep old version for N-1 compatibility
4. Get Scanner TL + QA approval
5. Sign new DSSE envelope

Audit Trail

Required Records

Record	Location	Retention
RFC decisions	docs/rfcs/scanner/	Permanent
Hash changes	Git history + CHANGELOG.md	Permanent
Approval records	PR comments	Permanent
DSSE envelopes	CAS + offline kit	Permanent

Git Commit Requirements

Schema-related commits must include:

feat(scanner): Add CVSS v4 support

- Add CVSSv4 rating method
- Update adapter mapping CSV
- Update golden fixtures
- New hashes recorded

Approved-By: @scanner-tl
Reviewed-By: @qa-lead
Hash-Update: mapping-cvss4-to-cvss3.csv BLAKE3=fa600b26...

Refs: RFC-2025-012, SCAN-GAP-186-SC9

Links

• Sprint: docs/implplan/SPRINT_0186_0001_0001_record_deterministic_execution.md (SC9)
• Roadmap: docs/modules/scanner/design/standards-convergence-roadmap.md (SC1)
• Adapters: docs/modules/scanner/fixtures/adapters/