8768c27f30
- Introduced `ReachabilityState`, `RuntimeHit`, `ExploitabilitySignal`, `ReachabilitySignal`, `SignalEnvelope`, `SignalType`, `TrustSignal`, and `UnknownSymbolSignal` records to define various signal types and their properties. - Implemented JSON serialization attributes for proper data interchange. - Created project files for the new signal contracts library and corresponding test projects. - Added deterministic test fixtures for micro-interaction testing. - Included cryptographic keys for secure operations with cosign.
198 lines
6.0 KiB
Markdown
198 lines
6.0 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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/`
|