Add signal contracts for reachability, exploitability, trust, and unknown symbols
- 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.
This commit is contained in:
StellaOps Bot
197
docs/modules/scanner/design/schema-governance.md
Normal file
197
docs/modules/scanner/design/schema-governance.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# 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/`
|
||||
Reference in New Issue
Block a user