stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Add property-based tests for SBOM/VEX document ordering and Unicode normalization determinism

Browse Source 
- Implement `SbomVexOrderingDeterminismProperties` for testing component list and vulnerability metadata hash consistency.
- Create `UnicodeNormalizationDeterminismProperties` to validate NFC normalization and Unicode string handling.
- Add project file for `StellaOps.Testing.Determinism.Properties` with necessary dependencies.
- Introduce CI/CD template validation tests including YAML syntax checks and documentation content verification.
- Create validation script for CI/CD templates ensuring all required files and structures are present.
This commit is contained in:
StellaOps Bot
2025-12-26 15:17:15 +02:00
parent 7792749bb4
commit 907783f625
354 changed files with 79727 additions and 1346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/modules/web/README.md
View File

@@ -20,6 +20,8 @@ Web provides the Angular 17 single-page application (SPA) frontend for StellaOps
- VEX statement review and approval workflows
- Task pack execution monitoring
- Admin console for configuration and user management
- **Unified Triage Experience** - Smart-Diff Compare View, Triage Canvas, Risk Dashboard
- **Risk Budget Visualization** - Burn-up charts, heatmaps, exception ledger
## Configuration
@@ -59,10 +61,22 @@ npx playwright test
## Related Documentation
- Architecture: `./architecture.md` (if exists)
### Triage Experience
- [Unified Triage Specification](./unified-triage-specification.md) - Consolidated triage requirements
- [Smart-Diff UI Architecture](./smart-diff-ui-architecture.md) - Compare view design
- [Triage Component Catalog](./triage-component-catalog.md) - Angular component documentation
- [Competitive Triage Patterns](./competitive-triage-patterns.md) - Industry comparison
### Module Dependencies
- UI Module: `../ui/` (shared UI components)
- Gateway: `../gateway/`
- Authority: `../authority/`
- Gateway: `../gateway/` (API access)
- Authority: `../authority/` (authentication)
- VulnExplorer: `../vulnexplorer/` (vulnerability data)
### Implementation Sprints
- [Smart-Diff Compare](../../implplan/SPRINT_20251226_012_FE_smart_diff_compare.md)
- [Triage Canvas](../../implplan/SPRINT_20251226_013_FE_triage_canvas.md)
- [Risk Dashboard](../../implplan/SPRINT_20251226_004_FE_risk_dashboard.md)
## Current Status

154
docs/modules/web/competitive-triage-patterns.md Normal file
View File

@@ -0,0 +1,154 @@
# Competitive Triage UI Patterns - Design Document
> **Sprint:** SPRINT_20251226_010_FE_visual_diff_enhancements
> **Task:** VD-ENH-09
> **Status:** Complete
> **Author:** Implementation Team
> **Date:** 2025-12-26
---
## Overview
This document captures competitive insights from leading vulnerability management tools and recommends patterns for adoption in StellaOps' visual diff and triage UI.
## Competitive Analysis
### Snyk — Reachability + Continuous Context
**What they do:**
- Reachability analysis builds call graphs to determine if vulnerable code is actually reachable
- Risk scores factor in reachability, not just CVSS severity
- Static program analysis combined with AI and expert curation
- Continuous monitoring tracks issues over time as projects are rescanned
**Adoption recommendation:** ✅ **Already implemented**
- `GraphDiffComponent` visualizes reachability graphs with call paths
- Hover highlighting shows connected paths from entry points to sinks
- Plain language explanations help users understand "why" a finding matters
### Anchore — Vulnerability Annotations & VEX Export
**What they do:**
- Vulnerability annotation workflows via UI or API
- Labels: "not applicable", "mitigated", "under investigation"
- Export as OpenVEX and CycloneDX VEX formats
- Curated reasoning reduces redundant triage downstream
**Adoption recommendation:** ✅ **Already implemented**
- `TriageWorkspaceComponent` provides VEX decisioning with trust levels
- `DeltaVerdict` backend exports signed VEX statements
- Attestable exception objects with expiries and audit trails
### Prisma Cloud — Runtime Defense
**What they do:**
- Runtime profiling and behavioral baselines for containers
- Process, file, and network rule enforcement
- Learning models detect anomalies
- Runtime context during operational incidents
**Adoption recommendation:** ⚠️ **Partial - Signals module**
- `Signals` module provides runtime observation correlation
- Hot symbol index tracks runtime function execution
- Integration with FuncProof links runtime observations to static analysis
---
## Recommended UI Patterns
### 1. Unified Triage Canvas
**Pattern:** Single view combining static analysis with runtime evidence
```
┌─────────────────────────────────────────────────────────────────┐
│ TRIAGE CANVAS │
├──────────────────┬────────────────────┬─────────────────────────┤
│ Graph View │ Evidence Panel │ Decision Panel │
│ │ │ │
│ ┌─────┐ │ • SBOM Component │ ○ Not Affected │
│ │main │────► │ • VEX Statement │ ○ Under Investigation │
│ └─────┘ │ │ • Reachability │ ○ Affected │
│ ▼ │ • Runtime Obs. │ ○ Fixed │
│ ┌─────┐ │ • Policy Match │ │
│ │vuln │ │ │ [Record Decision] │
│ └─────┘ │ │ │
└──────────────────┴────────────────────┴─────────────────────────┘
```
**Implementation:** Already complete via `TriageWorkspaceComponent` + `GraphDiffComponent`
### 2. Exploitability Scoring Visualization
**Pattern:** Visual risk score breakdown showing contributing factors
| Component | Weight | Score | Visualization |
|-----------|--------|-------|---------------|
| Reachability | 25% | 95 | ████████░░ |
| VEX Coverage | 20% | 90 | █████████░ |
| SBOM Completeness | 20% | 85 | ████████░░ |
| Runtime Evidence | 20% | 88 | ████████░░ |
| Policy Freshness | 15% | 92 | █████████░ |
**Implementation:** `ProofTreeComponent` displays trust score breakdown with donut chart
### 3. Attack Path Diagrams
**Pattern:** Entry point → vulnerable function path highlighting
- Color-coded paths (green=safe, red=vulnerable, amber=uncertain)
- Hop count indicators
- Confidence levels per path segment
- Interactive path exploration with zoom-to-fit
**Implementation:** `GraphDiffComponent` with `findPath()` and path highlighting
### 4. Evidence Provenance Indicators
**Pattern:** Visual indicators showing evidence source and trust level
| Indicator | Meaning |
|-----------|---------|
| 🔒 Signed | DSSE-signed evidence |
| ✓ Verified | Signature verified |
| ⚡ Runtime | Observed at runtime |
| 📋 Policy | Policy-derived |
| 👤 Manual | Human decision |
**Implementation:** `ProofTreeComponent` with evidence chunk icons
---
## Adoption Status
| Pattern | Status | Component |
|---------|--------|-----------|
| Reachability graphs | ✅ Complete | `GraphDiffComponent` |
| VEX decisioning | ✅ Complete | `TriageWorkspaceComponent` |
| Attack path visualization | ✅ Complete | `GraphDiffComponent` + path highlighting |
| Evidence provenance | ✅ Complete | `ProofTreeComponent` |
| Plain language explanations | ✅ Complete | `PlainLanguageService` |
| Runtime observation correlation | ✅ Complete | `Signals` module integration |
| Offline replay packs | ✅ Complete | Evidence bundle export |
| Trust score breakdown | ✅ Complete | `ProofTreeComponent` donut chart |
---
## Differentiation Strategy
StellaOps differentiates from competitors by unifying these patterns into a single, evidence-rich, policy-driven triage experience:
1. **Evidence-first:** Every decision is backed by cryptographic evidence
2. **Policy-driven:** VEX as core policy objects, not just export format
3. **Attestable:** Exceptions are attestable contracts with audit trails
4. **Offline-capable:** Same UI/interactions work in air-gapped environments
5. **Deterministic:** Reproducible verdicts across runs and environments
---
## References
- [Snyk Reachability Analysis](https://docs.snyk.io/manage-risk/prioritize-issues-for-fixing/reachability-analysis)
- [Anchore Vulnerability Annotations](https://docs.anchore.com/current/docs/vulnerability_management/vuln_annotations/)
- [Prisma Cloud Runtime Defense](https://docs.prismacloud.io/en/compute-edition/30/admin-guide/runtime-defense/runtime-defense-containers)

16
docs/modules/web/smart-diff-ui-architecture.md
View File

@@ -1,9 +1,9 @@
# Smart-Diff UI Architecture
**Version:** 1.0
**Status:** Draft
**Last Updated:** 2025-12-22
**Sprint Reference:** SPRINT_4200_0002_0003
**Version:** 1.1
**Status:** Active
**Last Updated:** 2025-12-26
**Sprint Reference:** SPRINT_20251226_012_FE_smart_diff_compare
## Overview
@@ -352,7 +352,9 @@ For large deltas (> 100 items), the items pane uses virtual scrolling:
## Related Documentation
- [Sprint: Delta Compare View UI](../../implplan/SPRINT_4200_0002_0003_delta_compare_view.md)
- [Sprint: Delta Compare Backend API](../../implplan/SPRINT_4200_0002_0006_delta_compare_api.md)
- [Unified Triage Specification](./unified-triage-specification.md) - Consolidated triage experience requirements
- [Triage Component Catalog](./triage-component-catalog.md) - Angular component documentation
- [Sprint: Smart-Diff Compare View](../../implplan/SPRINT_20251226_012_FE_smart_diff_compare.md) - Current implementation sprint
- [Sprint: Triage Canvas](../../implplan/SPRINT_20251226_013_FE_triage_canvas.md) - Unified triage canvas sprint
- [Sprint: Risk Dashboard](../../implplan/SPRINT_20251226_004_FE_risk_dashboard.md) - Risk budget visualization sprint
- [Smart-Diff CLI Reference](../../cli/smart-diff-cli.md)
- [Advisory: Smart Diff - Reproducibility as a Feature](../../product-advisories/archived/22-Dec-2025/21-Dec-2025%20-%20Smart%20Diff%20-%20Reproducibility%20as%20a%20Feature.md)

445
docs/modules/web/triage-component-catalog.md Normal file
View File

@@ -0,0 +1,445 @@
# Triage Component Catalog
**Version:** 1.0
**Status:** Active
**Last Updated:** 2025-12-26
**Sprint:** SPRINT_20251226_014_DOCS_triage_consolidation
## Overview
This document catalogs all Angular components used in the unified triage experience, including the Smart-Diff Compare View, Triage Canvas, and Risk Dashboard. Each component is documented with its responsibilities, inputs/outputs, and relationships.
## Component Hierarchy
```
src/Web/StellaOps.Web/src/app/
├── features/
│ ├── triage/
│ │ ├── triage-canvas/
│ │ │ ├── triage-canvas.component.ts [Container]
│ │ │ ├── triage-list.component.ts
│ │ │ ├── triage-detail.component.ts
│ │ │ ├── ai-recommendation-panel.component.ts
│ │ │ ├── vex-decision-modal.component.ts
│ │ │ └── vex-history.component.ts
│ │ └── compare/
│ │ ├── compare-view.component.ts [Container]
│ │ ├── baseline-selector.component.ts
│ │ ├── trust-indicators.component.ts
│ │ ├── delta-summary-strip.component.ts
│ │ ├── three-pane-layout.component.ts
│ │ ├── categories-pane.component.ts
│ │ ├── items-pane.component.ts
│ │ ├── proof-pane.component.ts
│ │ └── export-actions.component.ts
│ ├── risk-budget/
│ │ ├── risk-dashboard.component.ts [Container]
│ │ ├── burn-up-chart.component.ts
│ │ ├── unknowns-heatmap.component.ts
│ │ ├── delta-table.component.ts
│ │ ├── exception-ledger.component.ts
│ │ └── kpi-tiles.component.ts
│ └── vulnerabilities/
│ └── vulnerability-detail.component.ts
└── shared/
└── components/
├── confidence-badge.component.ts
├── determinism-badge.component.ts
├── severity-indicator.component.ts
└── evidence-chain.component.ts
```
## Container Components
### TriageCanvasComponent
**Location:** `features/triage/triage-canvas/triage-canvas.component.ts`
**Sprint:** SPRINT_20251226_013_FE
**Status:** TODO
**Purpose:** Main container for the unified triage experience. Orchestrates list, detail, and decision panels.
**Inputs:**
| Name | Type | Description |
|------|------|-------------|
| initialVulnId | string? | Pre-select vulnerability by ID |
| environment | string? | Filter by environment |
**Outputs:**
| Name | Type | Description |
|------|------|-------------|
| triageComplete | EventEmitter<VexDecision> | Emitted when triage decision saved |
| queueExhausted | EventEmitter<void> | Emitted when all items triaged |
**Child Components:**
- TriageListComponent
- TriageDetailComponent
- AiRecommendationPanel
- VexDecisionModalComponent
- VexHistoryComponent
---
### CompareViewComponent
**Location:** `features/triage/compare/compare-view.component.ts`
**Sprint:** SPRINT_20251226_012_FE
**Status:** TODO
**Purpose:** Three-pane Smart-Diff comparison view with baseline selection and proof display.
**Inputs:**
| Name | Type | Description |
|------|------|-------------|
| currentDigest | string | Digest of current scan |
| baselineDigest | string? | Digest of baseline (auto-selected if not provided) |
**Outputs:**
| Name | Type | Description |
|------|------|-------------|
| baselineChanged | EventEmitter<string> | New baseline selected |
| exportRequested | EventEmitter<ExportFormat> | Export action triggered |
**Child Components:**
- BaselineSelectorComponent
- TrustIndicatorsComponent
- DeltaSummaryStripComponent
- ThreePaneLayoutComponent
- ExportActionsComponent
---
### RiskDashboardComponent
**Location:** `features/risk-budget/risk-dashboard.component.ts`
**Sprint:** SPRINT_20251226_004_FE
**Status:** TODO
**Purpose:** Risk budget visualization with burn-up charts, heatmaps, and exception ledger.
**Inputs:**
| Name | Type | Description |
|------|------|-------------|
| serviceId | string | Service to display budget for |
| window | BudgetWindow | Budget window (monthly, weekly) |
**Outputs:**
| Name | Type | Description |
|------|------|-------------|
| exceptionCreated | EventEmitter<Exception> | New exception added |
| thresholdAlert | EventEmitter<ThresholdAlert> | Budget threshold crossed |
**Child Components:**
- BurnUpChartComponent
- UnknownsHeatmapComponent
- DeltaTableComponent
- ExceptionLedgerComponent
- KpiTilesComponent
---
## Presentation Components
### TriageListComponent
**Location:** `features/triage/triage-canvas/triage-list.component.ts`
**Sprint:** SPRINT_20251226_013_FE
**Status:** TODO
**Purpose:** Paginated, filterable list of vulnerabilities for triage.
**Inputs:**
| Name | Type | Description |
|------|------|-------------|
| vulnerabilities | Vulnerability[] | List of vulnerabilities |
| selectedId | string? | Currently selected vulnerability |
| filters | TriageFilters | Active filters |
**Outputs:**
| Name | Type | Description |
|------|------|-------------|
| selectionChange | EventEmitter<Vulnerability> | Vulnerability selected |
| bulkAction | EventEmitter<BulkActionRequest> | Bulk triage requested |
**Features:**
- Virtual scrolling (cdk-virtual-scroll) for large lists
- Filter chips: severity, KEV, exploitability, fix-available
- Quick actions: "Mark Not Affected", "Request Analysis"
---
### VexDecisionModalComponent
**Location:** `features/triage/triage-canvas/vex-decision-modal.component.ts`
**Sprint:** SPRINT_20251226_013_FE
**Status:** TODO
**Purpose:** Modal for creating/editing VEX decisions with full form controls.
**Inputs:**
| Name | Type | Description |
|------|------|-------------|
| vulnerability | Vulnerability | Target vulnerability |
| existingDecision | VexDecision? | Decision to edit |
| suggestedJustification | string? | AI-suggested justification |
**Outputs:**
| Name | Type | Description |
|------|------|-------------|
| save | EventEmitter<VexDecision> | Decision saved |
| cancel | EventEmitter<void> | Modal cancelled |
**Form Fields:**
- Status: NotAffected, AffectedMitigated, AffectedUnmitigated, Fixed
- Justification type (matches VexJustificationType enum)
- Evidence references (PR, Ticket, Doc, Commit links)
- Scope: environments and projects
- Validity window: NotBefore/NotAfter dates
- "Sign as Attestation" checkbox
---
### ThreePaneLayoutComponent
**Location:** `features/triage/compare/three-pane-layout.component.ts`
**Sprint:** SPRINT_20251226_012_FE
**Status:** TODO
**Purpose:** Responsive three-column layout for Categories, Items, and Proof panes.
**Inputs:**
| Name | Type | Description |
|------|------|-------------|
| delta | Delta | Computed delta with items |
| selectedCategory | Category? | Currently selected category |
| selectedItem | DeltaItem? | Currently selected item |
**Outputs:**
| Name | Type | Description |
|------|------|-------------|
| categorySelected | EventEmitter<Category> | Category clicked |
| itemSelected | EventEmitter<DeltaItem> | Item clicked |
**Layout Behavior:**
- Desktop: 3 columns (20% / 40% / 40%)
- Tablet: 2 columns (collapsed categories)
- Mobile: Single pane with navigation
---
### BurnUpChartComponent
**Location:** `features/risk-budget/burn-up-chart.component.ts`
**Sprint:** SPRINT_20251226_004_FE
**Status:** TODO
**Purpose:** Risk budget burn-up chart showing budget line vs actual risk over time.
**Inputs:**
| Name | Type | Description |
|------|------|-------------|
| budgetData | BudgetTimeSeries | Historical budget data |
| releaseDate | Date | Target release date |
| showMarkers | boolean | Show milestone markers |
**Outputs:**
| Name | Type | Description |
|------|------|-------------|
| pointClicked | EventEmitter<DataPoint> | Chart point clicked |
**Chart Features:**
- X-axis: Calendar dates
- Y-axis: Risk points
- Lines: Budget (flat), Actual (cumulative)
- Shaded regions: Headroom (green), Overrun (red)
- Markers: Feature freeze, pen-test, dependency bumps
---
## Shared Components
### ConfidenceBadgeComponent
**Location:** `shared/components/confidence-badge.component.ts`
**Status:** COMPLETE
**Purpose:** Displays confidence level with color-coded visual indicator.
**Inputs:**
| Name | Type | Description |
|------|------|-------------|
| confidence | number | 0-1 confidence value |
| showValue | boolean | Display numeric value |
---
### DeterminismBadgeComponent
**Location:** `shared/components/determinism-badge.component.ts`
**Status:** COMPLETE
**Purpose:** Shows determinism status with hash verification.
**Inputs:**
| Name | Type | Description |
|------|------|-------------|
| hash | string | Determinism hash |
| verified | boolean | Hash verification status |
| copyable | boolean | Show copy button |
---
## Service Layer
### TriageService
**Location:** `core/services/triage.service.ts`
**Sprint:** SPRINT_20251226_013_FE
**Methods:**
```typescript
getVulnerabilities(filters: TriageFilters): Observable<Page<Vulnerability>>
getVulnerability(id: string): Observable<Vulnerability>
getReachability(id: string): Observable<CallGraphSlice>
```
### VexDecisionService
**Location:** `core/services/vex-decision.service.ts`
**Sprint:** SPRINT_20251226_013_FE
**Methods:**
```typescript
create(decision: CreateVexDecision): Observable<VexDecision>
update(id: string, decision: UpdateVexDecision): Observable<VexDecision>
getHistory(vulnId: string): Observable<VexDecision[]>
```
### CompareService
**Location:** `core/services/compare.service.ts`
**Sprint:** SPRINT_20251226_012_FE
**Methods:**
```typescript
getBaselineRecommendations(digest: string): Observable<BaselineRecommendation[]>
computeDelta(current: string, baseline: string): Observable<Delta>
getTrustIndicators(deltaId: string): Observable<TrustIndicators>
```
### RiskBudgetService
**Location:** `core/services/risk-budget.service.ts`
**Sprint:** SPRINT_20251226_004_FE
**Methods:**
```typescript
getBudgetStatus(serviceId: string): Observable<BudgetStatus>
getBurnUpData(serviceId: string, window: BudgetWindow): Observable<BudgetTimeSeries>
createException(exception: CreateException): Observable<Exception>
```
---
## Interaction Diagrams
### Triage Flow
```
User Action Component Service
│ │ │
│ Select vulnerability │ │
├────────────────────────────►│ TriageListComponent │
│ ├─────────────────────────────►│
│ │ │ getVulnerability()
│ │◄─────────────────────────────┤
│ │ │
│ │ TriageDetailComponent │
│ ├─────────────────────────────►│
│ │ │ getReachability()
│ │◄─────────────────────────────┤
│ │ │
│ Click "Mark Not Affected" │ │
├────────────────────────────►│ VexDecisionModalComponent │
│ │ │
│ Submit form │ │
├────────────────────────────►│ │
│ ├─────────────────────────────►│
│ │ │ VexDecisionService.create()
│ │◄─────────────────────────────┤
│ │ │
│ │ Update list, advance queue │
│◄────────────────────────────┤ │
```
### Compare Flow
```
User Action Component Service
│ │ │
│ Navigate to /compare/:id │ │
├────────────────────────────►│ CompareViewComponent │
│ ├─────────────────────────────►│
│ │ │ getBaselineRecommendations()
│ │◄─────────────────────────────┤
│ │ │
│ │ Auto-select baseline │
│ ├─────────────────────────────►│
│ │ │ computeDelta()
│ │◄─────────────────────────────┤
│ │ │
│ │ ThreePaneLayoutComponent │
│ │ ├ CategoriesPaneComponent │
│ │ ├ ItemsPaneComponent │
│ │ └ ProofPaneComponent │
│ │ │
│ Select category │ │
├────────────────────────────►│ │
│ │ Filter items by category │
│ │ │
│ Select item │ │
├────────────────────────────►│ │
│ │ Display proof in right pane │
│◄────────────────────────────┤ │
```
---
## Accessibility Requirements
All triage components must meet WCAG 2.1 AA compliance:
| Requirement | Implementation |
|-------------|----------------|
| Keyboard navigation | Tab/Arrow/Enter/Escape, documented shortcuts |
| Focus management | Visible focus indicators, logical tab order |
| Screen reader | ARIA labels, live regions for updates |
| Color contrast | 4.5:1 minimum for text, 3:1 for UI elements |
| Error messages | Associated with inputs, announced immediately |
---
## Testing Requirements
### Unit Tests
- Component behavior (selection, filtering, expansion)
- Signal/computed derivations
- Form validation
### Integration Tests
- Service API calls
- Route navigation
- State persistence
### E2E Tests (Playwright)
- Full triage workflow
- Comparison workflow
- Keyboard navigation
---
## References
- [Unified Triage Specification](./unified-triage-specification.md)
- [Smart-Diff UI Architecture](./smart-diff-ui-architecture.md)
- [Angular Component Guidelines](https://angular.dev/guide/components)