save development progress
This commit is contained in:
StellaOps Bot
@@ -108,6 +108,200 @@ Scanner analyses container images layer-by-layer, producing deterministic SBOM f
|
||||
- Platform events rollout with scanner.report.ready@1 and scanner.scan.completed@1
|
||||
- Surface-cache environment resolution with startup validation
|
||||
|
||||
## Gating Explainability (Quiet-by-Design Triage)
|
||||
|
||||
The Scanner WebService exposes gating explainability through the triage APIs to support the "Quiet-by-Design" UX pattern where noise is gated at the source and proof is surfaced with one click.
|
||||
|
||||
### Gating Reasons
|
||||
|
||||
Findings can be hidden by default based on:
|
||||
|
||||
| Gating Reason | Description |
|
||||
|---------------|-------------|
|
||||
| `unreachable` | Not reachable from any application entrypoint |
|
||||
| `policy_dismissed` | Waived or tolerated by policy rules |
|
||||
| `backported` | Patched via distro backport |
|
||||
| `vex_not_affected` | VEX statement declares not affected with sufficient trust |
|
||||
| `superseded` | Superseded by newer advisory |
|
||||
| `user_muted` | Explicitly muted by user |
|
||||
|
||||
### Key DTOs
|
||||
|
||||
- `FindingTriageStatusDto` - Extended with `GatingReason`, `IsHiddenByDefault`, `SubgraphId`, `DeltasId`, `GatingExplanation`
|
||||
- `TriageVexStatusDto` - Includes `TrustScore`, `PolicyTrustThreshold`, `MeetsPolicyThreshold`, `TrustBreakdown`
|
||||
- `GatedBucketsSummaryDto` - Counts of hidden findings by gating reason for chip display
|
||||
- `BulkTriageQueryResponseDto` - Includes `GatedBuckets` and `ActionableCount`
|
||||
|
||||
### VEX Trust Scoring
|
||||
|
||||
VEX statements are evaluated against a policy-defined trust threshold (default 0.8). The trust score is computed from:
|
||||
- **Authority** (0-1): Issuer reputation and category
|
||||
- **Accuracy** (0-1): Historical correctness
|
||||
- **Timeliness** (0-1): Response speed
|
||||
- **Verification** (0-1): Signature validity
|
||||
|
||||
When `TrustScore >= PolicyTrustThreshold`, the VEX not_affected claim gates the finding.
|
||||
|
||||
### Unified Evidence Endpoint
|
||||
|
||||
`GET /v1/triage/findings/{findingId}/evidence` returns all evidence tabs in one call:
|
||||
- SBOM reference and component metadata
|
||||
- Reachability subgraph with call paths
|
||||
- VEX claims with trust scores
|
||||
- Attestation summaries
|
||||
- Delta comparison
|
||||
- Policy evaluation results
|
||||
- Manifest hashes for verification
|
||||
- Replay command for deterministic reproduction
|
||||
|
||||
### Evidence Bundle Export
|
||||
|
||||
`GET /v1/triage/findings/{findingId}/evidence/export` returns a downloadable archive containing:
|
||||
- `MANIFEST.json` - Bundle manifest with hashes
|
||||
- `finding-status.json` - Triage status
|
||||
- `proof-bundle.json` - Proof bundle
|
||||
- `replay-command.json` - Replay command info
|
||||
- `replay.sh` / `replay.ps1` - Replay scripts
|
||||
- `README.md` - Human-readable documentation
|
||||
|
||||
### Replay Command Generation
|
||||
|
||||
The `IReplayCommandService` generates copy-ready CLI commands:
|
||||
```bash
|
||||
stella scan replay --artifact sha256:abc... --manifest sha256:def... --feeds sha256:ghi... --policy sha256:jkl...
|
||||
```
|
||||
|
||||
For offline replay: `stella scan replay --offline --artifact ... --verify-inputs`
|
||||
|
||||
### UI Wireframes
|
||||
|
||||
#### Gated Buckets Summary
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Gated Findings Summary │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ ┌────────────────────────┐ │
|
||||
│ │ 12 actionable │ (96 hidden) │
|
||||
│ └────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ +42 │ │ +15 │ │ +8 │ │ +23 │ │
|
||||
│ │ unreachable │ │ policy │ │ backported │ │ VEX │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐ │
|
||||
│ │ +3 │ │ +5 │ │ [Show all] │ │
|
||||
│ │ superseded │ │ muted │ └─────────────────┘ │
|
||||
│ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### VEX Trust Display
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ VEX Status: not_affected │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Trust Score: ████████░░ 0.85 │
|
||||
│ Threshold: ──────── 0.80 ✓ Meets policy │
|
||||
│ │
|
||||
│ Issuer: vendor.example │
|
||||
│ Justification: vulnerable_code_not_in_execute_path │
|
||||
│ │
|
||||
│ ┌─ Trust Breakdown ─────────────────────────────────────────────────┐ │
|
||||
│ │ Authority: ██████████░ 0.90 │ │
|
||||
│ │ Accuracy: ████████░░░ 0.85 │ │
|
||||
│ │ Timeliness: ████████░░░ 0.80 │ │
|
||||
│ │ Verification: ████████░░░ 0.85 │ │
|
||||
│ └───────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### Replay Command Component
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Replay Command │
|
||||
│ Reproduce this verdict deterministically │
|
||||
├──────────┬─────────┬─────────────────────────────────────────────────────────┤
|
||||
│ [Full] │ Short │ Offline │
|
||||
├──────────┴─────────┴─────────────────────────────────────────────────────────┤
|
||||
│ ┌───────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ $ stella scan replay \ │ │
|
||||
│ │ --artifact sha256:a1b2c3d4e5f6... \ │ │
|
||||
│ │ --manifest sha256:def456... \ │ │
|
||||
│ │ --feeds sha256:feed789... \ │ │
|
||||
│ │ --policy sha256:policy321... │ │
|
||||
│ └───────────────────────────────────────────────────────────────────────┘ │
|
||||
│ ┌───────────────┐ │
|
||||
│ │ 📋 Copy │ │
|
||||
│ └───────────────┘ │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ 📦 Download Evidence Bundle 12.5 KB · ZIP │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Expected verdict hash: sha256:verdict123... │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### Gating Explainer Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Finding: CVE-2024-1234 │
|
||||
│ lodash@4.17.15 │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Status: Hidden by default [Why hidden?] ←─┐ │
|
||||
│ │ │
|
||||
│ ┌───────────────┴───────────────────────────┐ │
|
||||
│ │ Why is this finding hidden? │ │
|
||||
│ ├───────────────────────────────────────────┤ │
|
||||
│ │ │ │
|
||||
│ │ This finding is gated because: │ │
|
||||
│ │ │ │
|
||||
│ │ ✓ VEX not_affected (trust: 0.85) │ │
|
||||
│ │ Vendor issued not_affected statement │ │
|
||||
│ │ with justification: │ │
|
||||
│ │ "vulnerable_code_not_in_execute_path" │ │
|
||||
│ │ │ │
|
||||
│ │ Evidence: │ │
|
||||
│ │ • VEX document: vex-vendor-2025-001 │ │
|
||||
│ │ • Issued: 2025-12-15T10:00:00Z │ │
|
||||
│ │ • Signature: ✓ Valid (ES256) │ │
|
||||
│ │ │ │
|
||||
│ │ [View Evidence] [Close] │ │
|
||||
│ └───────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### Evidence Bundle Contents
|
||||
|
||||
```
|
||||
evidence-f-abc123/
|
||||
├── manifest.json ← Archive manifest with SHA-256 hashes
|
||||
├── README.md ← Human-readable documentation
|
||||
├── sbom.cdx.json ← CycloneDX SBOM slice
|
||||
├── reachability.json ← Reachability analysis
|
||||
├── vex/
|
||||
│ ├── vendor.json ← Vendor VEX statement
|
||||
│ ├── nvd.json ← NVD data
|
||||
│ └── cisa-kev.json ← CISA KEV flag
|
||||
├── attestations/
|
||||
│ ├── sbom.dsse.json ← SBOM DSSE envelope
|
||||
│ └── scan.dsse.json ← Scan DSSE envelope
|
||||
├── policy/
|
||||
│ └── evaluation.json ← Policy evaluation result
|
||||
├── delta.json ← Delta comparison
|
||||
├── replay-command.txt ← Copy-ready CLI command
|
||||
├── replay.sh ← Bash replay script
|
||||
└── replay.ps1 ← PowerShell replay script
|
||||
```
|
||||
|
||||
See Sprint 9200.0001.0001-0004 for implementation details.
|
||||
|
||||
## Epic alignment
|
||||
- **Epic 6 – Vulnerability Explorer:** provide policy-aware scan outputs, explain traces, and findings ledger hooks for triage workflows.
|
||||
- **Epic 10 – Export Center:** generate export-ready artefacts, manifests, and DSSE metadata for bundles.
|
||||
|
||||
Reference in New Issue
Block a user