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

Tests fixes, audit progress, UI completions

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-30 09:03:22 +02:00
parent 7a5210e2aa
commit 82e55c206a
318 changed files with 7232 additions and 1256 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_019_TEST_integration_e2e.md Normal file
View File

@@ -0,0 +1,39 @@
# Sprint 20251229_019_TEST_integration_e2e <20> Integration E2E Validation
## Topic & Scope
- Build end-to-end tests covering registry, SCM, and CI integrations.
- Validate offline-friendly integration flows and deterministic outputs.
- Provide a regression harness for integration onboarding paths.
- **Working directory:** src/__Tests. Evidence: E2E test suite and integration fixtures.
## Dependencies & Concurrency
- Depends on Integration Catalog, registry sources, and SCM/CI connectors sprints.
- Can run in parallel once APIs are stable.
## Documentation Prerequisites
- src/__Tests/AGENTS.md
- docs/modules/platform/architecture-overview.md
- docs/benchmarks/ (for fixtures/runbooks)
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | INT-E2E-001 | DONE | Fixture plan | QA - E2E | Build registry webhook fixtures and replay bundles. |
| 2 | INT-E2E-002 | DONE | SCM webhooks | QA - E2E | Add GitHub/GitLab/Gitea webhook ingestion tests. |
| 3 | INT-E2E-003 | DONE | CI templates | QA - E2E | Validate generated CI templates and SBOM uploads. |
| 4 | INT-E2E-004 | DONE | Offline mode | QA - E2E | Add air-gap integration flow tests and cache priming. |
| 5 | INT-E2E-005 | DONE | Determinism | QA - E2E | Validate deterministic ordering/hashes in integration outputs. |
| 6 | INT-E2E-006 | DONE | Docs update | QA - Docs | Document E2E integration harness and runbooks. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-29 | Sprint created; awaiting staffing. | Planning |
| 2025-12-30 | All tasks completed. Registry/SCM webhook fixtures, CI template tests, offline mode tests, determinism tests, and documentation delivered. Test infrastructure includes IntegrationTestFixture, WebhookTestHelper, TestCiTemplates. | Implementer |
## Decisions & Risks
- Risk: integration E2E requires live credentials; mitigate with mock providers and recorded fixtures.
- Risk: offline tests are slow; mitigate with minimal fixture sets and caching.
## Next Checkpoints
- TBD: integration E2E test plan review.

48
docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_043_PLATFORM_platform_service_foundation.md Normal file
View File

@@ -0,0 +1,48 @@
# Sprint 20251229_043_PLATFORM · Platform Service Foundation
## Topic & Scope
- Establish the Platform Service as the aggregation layer for health, quotas, onboarding, preferences, and global search.
- Define API contracts and storage for user/tenant-level platform state with deterministic, offline-friendly behavior.
- **Working directory:** `src/Platform`. Evidence: service skeleton, API contracts, tests, and updated platform docs.
## Dependencies & Concurrency
- Depends on Authority, Gateway, Orchestrator, and Notifier contracts for aggregation inputs.
- Unblocks UI sprints for platform health, quotas, onboarding, and personalization.
- CC-decade sprints remain independent; service work is isolated to `src/Platform`.
## Documentation Prerequisites
- `docs/modules/platform/platform-service.md`
- `docs/modules/platform/architecture.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/gateway/architecture.md`
- `docs/modules/authority/architecture.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | PLAT-SVC-001 | DONE | Project scaffold | Platform · BE | Create `StellaOps.Platform.WebService` skeleton with DI, auth, and health endpoints. |
| 2 | PLAT-SVC-002 | DONE | Health inputs | Platform · BE | Implement `/api/v1/platform/health/*` aggregation with caching and deterministic ordering. |
| 3 | PLAT-SVC-003 | DONE | Quota inputs | Platform · BE | Implement `/api/v1/platform/quotas/*` aggregation (Authority, Gateway, Orchestrator). |
| 4 | PLAT-SVC-004 | DONE | Storage schema | Platform · BE | Add onboarding state storage and endpoints under `/api/v1/platform/onboarding/*`. |
| 5 | PLAT-SVC-005 | DONE | Storage schema | Platform · BE | Add dashboard preference storage and endpoints under `/api/v1/platform/preferences/*`. |
| 6 | PLAT-SVC-006 | DONE | Search inputs | Platform · BE | Provide `/api/v1/search` aggregation with stable scoring and pagination. |
| 7 | PLAT-SVC-007 | DONE | Gateway config | Platform · BE | Register Platform Service routes in Gateway/Router and define auth scopes. |
| 8 | PLAT-SVC-008 | DONE | Observability | Platform · BE | Emit aggregation latency/error metrics and structured logs. |
| 9 | PLAT-SVC-009 | DONE | Tests | Platform · QA | Add unit/integration tests for aggregation ordering and offline cache behavior. |
| 10 | PLAT-SVC-010 | DONE | Docs update | Platform · Docs | Update module docs and runbooks with Platform Service contracts and ownership. |
| 11 | PLAT-SVC-011 | DONE | Platform docs | Platform - Docs | Create `docs/modules/platform/implementation_plan.md` and `docs/modules/platform/TASKS.md` for Platform Service tracking. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-29 | Sprint created; awaiting staffing. | Planning |
| 2025-12-29 | Added platform implementation plan and task board docs for Platform Service tracking. | Docs |
| 2025-12-30 | Delivered Platform Service endpoints, tests, and docs; added platform schema spec. | Implementer |
## Decisions & Risks
- Risk: Aggregation latency and fan-out failures may slow UI. Mitigation: caching, partial responses, and explicit "data as of" metadata.
- Risk: Conflicting source-of-truth between Platform Service and module APIs. Mitigation: treat Platform Service as read-only aggregation; no mutation of module data.
- Decision: Default storage driver remains in-memory; Postgres schema defined for future driver swap.
## Next Checkpoints
- 2025-12-30 Platform Service scope review (Architecture Guild).

294
docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_044_FE_vex_ai_explanations.md Normal file
View File

@@ -0,0 +1,294 @@
# Sprint 20251229_044_FE - VEX-AI Explanations
## Topic & Scope
- Deliver VEX Hub exploration UI with search, statistics, and statement detail views.
- Integrate Advisory AI explain/remediate workflows with consent gating.
- Provide evidence-linked VEX decisioning with consensus visualization.
- Enable VEX statement creation with AI-assisted justification drafting.
- **Working directory:** src/Web/StellaOps.Web. Evidence: `/admin/vex-hub` route with exploration, AI integration, and decision workflows.
## Dependencies & Concurrency
- Depends on VEX Hub and VexLens endpoints for statement retrieval and consensus.
- Requires Advisory AI endpoints for explanation and remediation generation.
- Links to existing triage UI for VEX decisioning integration.
- **Backend Dependencies (Gateway-aligned)**:
- Optional gateway alias: `/api/v1/vexhub/*` -> `/api/v1/vex/*`
- GET `/api/v1/vex/search` - Search VEX statements with filters
- GET `/api/v1/vex/statement/{id}` - Get statement details
- GET `/api/v1/vex/stats` - VEX Hub statistics (statements by status, source)
- GET `/api/v1/vex/index` - VEX Hub index manifest (tool integration)
- POST `/api/v1/vexlens/consensus` - Compute consensus for CVE/product pair
- POST `/api/v1/vexlens/consensus:batch` - Batch consensus for multiple CVE/product pairs
- GET `/api/v1/vexlens/conflicts` - Query conflicts by CVE/product
- GET `/api/v1/vexlens/projections` - Consensus projections list
- Optional gateway alias: `/api/v1/vexlens/consensus/{cveId}` -> `/api/v1/vexlens/consensus` (if UI expects GET by CVE)
- Optional gateway alias: `/api/v1/vexlens/conflicts/{cveId}` -> `/api/v1/vexlens/conflicts` (if UI expects per-CVE GET)
- Optional gateway alias: `/api/v1/advisory-ai/*` -> `/v1/advisory-ai/*`
- POST `/v1/advisory-ai/explain` - Generate vulnerability explanation
- POST `/v1/advisory-ai/remediate` - Generate remediation guidance
- POST `/v1/advisory-ai/justify` - Draft VEX justification
- GET `/v1/advisory-ai/consent` - Check AI feature consent status
- POST `/v1/advisory-ai/consent` - Grant/revoke AI feature consent
## Architectural Compliance
- **Determinism**: VEX consensus uses stable voting algorithm; explanations tagged with model version.
- **Offline-first**: VEX statements cached locally; AI features require online connection.
- **AOC**: VEX statements preserve upstream source; conflicts visible, not merged.
- **Security**: AI consent gated; no VEX data sent to AI without explicit approval.
- **Audit**: AI explanation requests logged; VEX decisions include evidence trail.
## Documentation Prerequisites
- docs/modules/vex-hub/architecture.md
- docs/modules/vex-lens/architecture.md
- docs/modules/advisory-ai/architecture.md
- docs/modules/platform/architecture-overview.md
## Delivery Tracker
| # | Task ID | Status | Phase | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | VEX-AI-001 | DONE | P0 | Routes | FE - Web | Add `/admin/vex-hub` route with navigation entry under Admin menu. |
| 2 | VEX-AI-002 | DONE | P0 | API client | FE - Web | Create `VexHubService` and `AdvisoryAiService` in `core/services/`. |
| 3 | VEX-AI-003 | DONE | P0 | Search UI | FE - Web | Build `VexStatementSearchComponent`: CVE, product, status, source filters. |
| 4 | VEX-AI-004 | DONE | P0 | Statistics | FE - Web | Build `VexHubStatsComponent`: statements by status, source breakdown, trends. |
| 5 | VEX-AI-005 | DONE | P0 | Statement detail | FE - Web | Build `VexStatementDetailPanel`: full statement, evidence links, consensus status. |
| 6 | VEX-AI-006 | DONE | P0 | Consensus view | FE - Web | Build `VexConsensusComponent`: multi-issuer voting visualization, conflict display. |
| 7 | VEX-AI-007 | DONE | P1 | AI consent | FE - Web | Implement consent gate UI for AI features with scope explanation. |
| 8 | VEX-AI-008 | DONE | P1 | Explain workflow | FE - Web | Integrate AI explain in finding detail: summary, impact, affected versions. |
| 9 | VEX-AI-009 | DONE | P1 | Remediate workflow | FE - Web | Integrate AI remediate in triage: upgrade paths, mitigation steps. |
| 10 | VEX-AI-010 | DONE | P1 | Justify draft | FE - Web | AI-assisted VEX justification drafting with edit-before-submit. |
| 11 | VEX-AI-011 | DONE | P2 | VEX create | FE - Web | VEX statement creation workflow with evidence attachment. |
| 12 | VEX-AI-012 | DONE | P2 | Conflict resolution | FE - Web | Conflict resolution UI: compare claims, select authoritative source. |
| 13 | VEX-AI-013 | DONE | P2 | Docs update | FE - Docs | Update VEX Hub usage guide and AI integration documentation. |
| 14 | VEX-AI-014 | DONE | P0 | Gateway routes | Gateway - BE | Add gateway aliases for `/api/v1/vexhub/*` -> `/api/v1/vex/*` and `/api/v1/advisory-ai/*` -> `/v1/advisory-ai/*`. Gateway uses dynamic routing via service registration. |
| 15 | VEX-AI-015 | DONE | P0 | VexLens service | VexLens - BE | Exposed VexLens consensus/conflict/projection endpoints at `/api/v1/vexlens/*` via VexLens.WebService. |
| 16 | VEX-AI-016 | DONE | P0 | Advisory AI parity | AdvisoryAI - BE | Added consent endpoints (GET/POST/DELETE `/v1/advisory-ai/consent`), justify endpoint (`POST /v1/advisory-ai/justify`), remediate alias, and rate-limits endpoint in AdvisoryAI WebService. |
| 17 | VEX-AI-017 | DONE | P0 | UI base URLs | FE - Web | Update VEX Hub and Advisory AI base URLs in `app.config.ts`, `vex-hub.client.ts`, and `advisory-ai.client.ts` to match `/api/v1/vex` and `/v1/advisory-ai`. |
| 18 | VEX-AI-018 | DONE | P0 | VexLens alias | Gateway - BE | Add gateway aliases for GET `/api/v1/vexlens/consensus/{cveId}` and `/api/v1/vexlens/conflicts/{cveId}`, or update UI to use POST `/api/v1/vexlens/consensus` and query `/api/v1/vexlens/conflicts`. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-29 | Sprint created as split from SPRINT_018; focused on VEX and AI features. | Planning |
| 2025-12-29 | Aligned backend dependency paths and added gateway/advisory/vexlens backend tasks. | Planning |
| 2025-12-29 | Added UI base URL alignment task for VEX Hub and Advisory AI clients. | Planning |
| 2025-12-29 | Aligned VEX Hub and Advisory AI base URLs in UI config and API clients (VEX-AI-017). | Implementer |
| 2025-12-30 | Completed VEX-AI-015: Created VexLens.WebService with consensus, conflicts, stats, and statement endpoints. | Backend |
| 2025-12-30 | Completed VEX-AI-016: Added consent (GET/POST/DELETE), justify, remediate, and rate-limits endpoints to AdvisoryAI.WebService. | Backend |
| 2025-12-30 | Completed VEX-AI-014: Gateway uses dynamic routing via service registration; no explicit aliases needed. | Backend |
| 2025-12-30 | Aligned VexLens dependency paths to `/api/v1/vexlens/*`, added alias task for UI compatibility, and refreshed UI base URL notes. | Implementer |
## Decisions & Risks
- Risk: AI hallucination in explanations; mitigate with "AI-generated" badges and human review.
- Risk: Consent fatigue; mitigate with session-level consent and clear scope explanation.
- Risk: VexLens and Advisory AI endpoint gaps block UI; mitigate with gateway aliases and backend parity tasks.
- Risk: VexLens UI uses legacy per-CVE GET routes; mitigate with gateway aliases or UI client updates (VEX-AI-018).
- Risk: UI base URLs still point at legacy routes; mitigate with VEX-AI-017 and gateway aliases.
- Decision: AI justification is draft-only; human must review and approve before submission.
- Decision: Consensus visualization shows all votes, not just winning decision.
## Next Checkpoints
- TBD: VEX-AI UX review with security engineering team.
## Appendix: VEX-AI Integration Requirements
### VEX Statement Status Values
| Status | Description | Color | Triage Implication |
|--------|-------------|-------|-------------------|
| **affected** | Product is affected by vulnerability | Red | Requires action |
| **not_affected** | Product is not affected | Green | No action needed |
| **fixed** | Vulnerability has been fixed | Blue | Verify fix applied |
| **under_investigation** | Assessing impact | Yellow | Monitor for update |
### VEX Consensus Model
```
Consensus Algorithm:
1. Collect VEX statements from all trusted issuers
2. Group by product + CVE pair
3. Apply trust weights (issuer reputation, recency)
4. Calculate weighted vote for each status
5. Majority status becomes consensus
6. Surface conflicts if votes are split
Trust Weights:
- Vendor VEX (product owner): 1.0
- CERT/coordination center: 0.8
- Security researcher: 0.6
- Community/OSS maintainer: 0.5
- AI-generated: 0.3 (requires human confirmation)
```
### Dashboard Wireframe
```
VEX Hub Explorer
+-----------------------------------------------------------------+
| Statistics: |
| [Total: 15,234] [Affected: 3,211] [Not Affected: 8,923] |
| [Fixed: 2,847] [Investigating: 253] |
+-----------------------------------------------------------------+
| Search Statements: |
| [CVE: __________] [Product: __________] [Status: All v] |
| [Source: All v] [Date Range: 30d v] [Search] |
+-----------------------------------------------------------------+
| Results: |
| +----------+----------------+----------+--------+---------+-----+|
| | CVE | Product | Status | Source | Date | Act ||
| +----------+----------------+----------+--------+---------+-----+|
| | CVE-2024 | acme/web:1.2 | affected | vendor | Jan 15 | [V] ||
| | CVE-2024 | beta/api:3.0 | fixed | oss | Jan 14 | [V] ||
| | CVE-2024 | gamma/lib:2.1 | not_aff | cert | Jan 13 | [V] ||
| +----------+----------------+----------+--------+---------+-----+|
+-----------------------------------------------------------------+
VEX Statement Detail (slide-out):
+-----------------------------------------------------------------+
| CVE-2024-12345: SQL Injection in acme/web |
| Status: affected |
| Product: docker.io/acme/web:1.2.3 |
+-----------------------------------------------------------------+
| Statement Details: |
| Source: vendor (Acme Corp) |
| Published: 2025-01-15T10:00:00Z |
| Document ID: ACME-VEX-2025-001 |
+-----------------------------------------------------------------+
| Justification: |
| "Product uses affected library in request handler. Impact: |
| remote code execution via crafted SQL query. Affected versions: |
| 1.0.0 through 1.2.3. Fix available in 1.2.4." |
+-----------------------------------------------------------------+
| Evidence Links: |
| - Advisory: NVD CVE-2024-12345 [View] |
| - SBOM: acme/web:1.2.3 [View] |
| - Reachability: 87% confidence [View Analysis] |
+-----------------------------------------------------------------+
| Consensus Status: |
| [█████████░] 3/4 issuers agree: affected |
| - vendor (Acme): affected (1.0 weight) |
| - cert (CISA): affected (0.8 weight) |
| - oss (maintainer): affected (0.5 weight) |
| - researcher: not_affected (0.6 weight) [CONFLICT] |
+-----------------------------------------------------------------+
| [AI Explain] [AI Remediate] [Create Override] [Export] |
+-----------------------------------------------------------------+
AI Consent Gate:
+-----------------------------------------------------------------+
| Enable AI-Assisted Features |
+-----------------------------------------------------------------+
| Advisory AI can help you: |
| - Explain vulnerabilities in plain language |
| - Generate remediation guidance |
| - Draft VEX justifications for review |
+-----------------------------------------------------------------+
| Data Sharing Notice: |
| When using AI features, the following data may be sent to |
| the AI service: |
| - CVE details (public information) |
| - Affected product identifiers |
| - SBOM component information (package names, versions) |
| |
| NO proprietary code or secrets are ever shared. |
+-----------------------------------------------------------------+
| [x] I understand and consent to AI-assisted analysis |
| [ ] Remember my choice for this session |
+-----------------------------------------------------------------+
| [Cancel] [Enable AI Features] |
+-----------------------------------------------------------------+
AI Explain Panel (integrated in finding detail):
+-----------------------------------------------------------------+
| AI Vulnerability Explanation |
| [AI-Generated - Review for accuracy] |
+-----------------------------------------------------------------+
| Summary: |
| CVE-2024-12345 is a SQL injection vulnerability in the |
| database query builder library. Attackers can craft malicious |
| input that bypasses input validation... |
+-----------------------------------------------------------------+
| Impact Assessment: |
| - Severity: HIGH (CVSS 8.1) |
| - Attack Vector: Network (remote exploitation possible) |
| - Privileges Required: None |
| - Impact: Confidentiality, Integrity |
+-----------------------------------------------------------------+
| Affected Versions: |
| - Vulnerable: < 2.5.0 |
| - Fixed: >= 2.5.0 |
| - Your version: 2.4.3 (VULNERABLE) |
+-----------------------------------------------------------------+
| [Refresh Explanation] [Report Inaccuracy] [Copy] |
+-----------------------------------------------------------------+
AI Remediation Panel:
+-----------------------------------------------------------------+
| AI Remediation Guidance |
| [AI-Generated - Review for accuracy] |
+-----------------------------------------------------------------+
| Recommended Actions: |
| 1. Upgrade `query-builder` from 2.4.3 to 2.5.1 |
| Command: npm install query-builder@2.5.1 |
| |
| 2. Apply input validation patch (if upgrade not possible) |
| Add parameterized query enforcement |
| |
| 3. Enable WAF rule for SQL injection patterns |
+-----------------------------------------------------------------+
| Compatibility Notes: |
| - 2.5.x has breaking changes in connection pooling |
| - Review migration guide: [link] |
+-----------------------------------------------------------------+
| [Apply Upgrade] [View Upgrade Impact] [Dismiss] |
+-----------------------------------------------------------------+
AI Justification Drafting:
+-----------------------------------------------------------------+
| Draft VEX Justification |
| [AI-Generated Draft - Edit before submitting] |
+-----------------------------------------------------------------+
| Status: [not_affected v] |
| Justification Type: [vulnerable_code_not_present v] |
+-----------------------------------------------------------------+
| Draft Justification: |
| [The affected function `buildQuery()` is present in the ]|
| [dependency but our application uses parameterized queries ]|
| [exclusively via the ORM layer, which prevents exploitation. ]|
| [Code analysis confirms no direct usage of raw query builder. ]|
+-----------------------------------------------------------------+
| Evidence Attachments: |
| [x] Reachability analysis (87% confidence) |
| [x] Code search results (0 matches for vulnerable pattern) |
| [ ] Manual review notes: ______________________ |
+-----------------------------------------------------------------+
| [Regenerate Draft] [Submit for Review] [Save as Draft] |
+-----------------------------------------------------------------+
```
### AI Feature Gating
| Feature | Consent Required | Data Sent | Rate Limit |
|---------|------------------|-----------|------------|
| Explain | Session consent | CVE ID, SBOM components | 10/min |
| Remediate | Session consent | CVE ID, dependency graph | 5/min |
| Justify Draft | Per-action consent | VEX context, product info | 3/min |
| Bulk Analysis | Admin consent | Multiple CVEs, full SBOM | 1/hour |
### Performance Requirements
- **Search results**: < 1s for 100 statements
- **Consensus calculation**: < 500ms per CVE
- **AI explanation**: < 5s (async with loading indicator)
- **AI remediation**: < 10s (async with progress)
### Integration with Triage UI
- "AI Explain" button on finding detail page
- "AI Remediate" button on triage workflow
- VEX consensus badge on finding cards
- Link to VEX Hub from finding detail
---
## Success Criteria
- VEX Hub explorer accessible at `/admin/vex-hub`.
- Statement search with filters and pagination works correctly.
- Consensus visualization shows multi-issuer voting and conflicts.
- AI consent gate functional with session-level consent option.
- AI explain, remediate, and justify features integrated with review.
- Evidence links connect VEX statements to SBOMs and advisories.
- E2E tests cover search, AI consent, and VEX creation workflows.

306
docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_045_FE_notification_delivery_audit.md Normal file
View File

@@ -0,0 +1,306 @@
# Sprint 20251229_045_FE - Notification Delivery Audit
## Topic & Scope
- Deliver notification rule, channel, and template management UI.
- Provide delivery status tracking with retry and failure diagnostics.
- Enable rule simulation (test before activation) to prevent alert fatigue.
- Implement operator override management and quiet hours configuration.
- **Working directory:** src/Web/StellaOps.Web. Evidence: `/admin/notifications` route with rule management, delivery audit, and simulation tools.
## Dependencies & Concurrency
- Depends on Notifier endpoints for rules, channels, templates, and delivery tracking.
- Requires simulation endpoints for rule testing before activation.
- Links to SPRINT_028 (Audit Log) for notification event logging.
- **Backend Dependencies (Notify v1)**:
- Decision: `/api/v1/notify` is the canonical UI base; `/api/v2/notify` remains compatibility only.
- Optional gateway alias: `/api/v1/notifier/*` -> `/api/v1/notify/*`
- Optional gateway alias: `/api/v2/notify/*` -> `/api/v1/notify/*` (if any v2 clients remain)
- GET `/api/v1/notify/rules` - List notification rules
- POST `/api/v1/notify/rules` - Create notification rule
- PUT `/api/v1/notify/rules/{ruleId}` - Update rule
- DELETE `/api/v1/notify/rules/{ruleId}` - Delete rule
- GET `/api/v1/notify/channels` - List notification channels (email, Slack, webhook)
- POST `/api/v1/notify/channels` - Create channel
- GET `/api/v1/notify/templates` - List message templates
- POST `/api/v1/notify/templates` - Create template
- GET `/api/v1/notify/deliveries` - Delivery history with status
- POST `/api/v1/notify/deliveries/{id}/retry` - Retry failed delivery
- POST `/api/v1/notify/simulation/test` - Test rule against sample event
- POST `/api/v1/notify/simulation/preview` - Preview notification output
- GET `/api/v1/notify/quiethours` - Get quiet hours configuration
- POST `/api/v1/notify/quiethours` - Configure quiet hours
- GET `/api/v1/notify/overrides` - Get operator overrides
- POST `/api/v1/notify/overrides` - Create operator override
- GET `/api/v1/notify/escalation` - Get escalation policies
- POST `/api/v1/notify/escalation` - Configure escalation
- GET `/api/v1/notify/throttle` - Get throttle configuration
- POST `/api/v1/notify/throttle` - Configure rate limits
## Architectural Compliance
- **Determinism**: Delivery timestamps UTC ISO-8601; rule matching uses stable evaluation order.
- **Offline-first**: Rule configuration cached locally; delivery requires online connection.
- **AOC**: Delivery history is append-only; failed attempts preserved for audit.
- **Security**: Notification admin scoped to `notify.admin`; templates cannot contain secrets.
- **Audit**: All rule changes and delivery attempts logged with actor and timestamp.
## Documentation Prerequisites
- docs/modules/notifier/architecture.md
- docs/modules/notify/architecture.md
- docs/modules/platform/architecture-overview.md
## Delivery Tracker
| # | Task ID | Status | Phase | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | NOTIFY-001 | DONE | P0 | Routes | FE - Web | Add `/admin/notifications` route with navigation entry under Admin menu. |
| 2 | NOTIFY-002 | DONE | P0 | API client | FE - Web | Create `NotifierService` in `core/services/`: unified notification API client. |
| 3 | NOTIFY-003 | DONE | P0 | Rule list | FE - Web | Build `NotificationRuleListComponent`: rules with status, channels, actions. |
| 4 | NOTIFY-004 | DONE | P0 | Rule editor | FE - Web | Build `NotificationRuleEditorComponent`: conditions, channels, template selection. |
| 5 | NOTIFY-005 | DONE | P0 | Channel management | FE - Web | Build `ChannelManagementComponent`: email, Slack, Teams, webhook configuration. |
| 6 | NOTIFY-006 | DONE | P0 | Delivery history | FE - Web | Build `DeliveryHistoryComponent`: delivery status, retry, failure details. |
| 7 | NOTIFY-007 | DONE | P1 | Rule simulation | FE - Web | Build `RuleSimulatorComponent`: test rule against sample events before activation. |
| 8 | NOTIFY-008 | DONE | P1 | Notification preview | FE - Web | Implement notification preview: see rendered message before sending. |
| 9 | NOTIFY-009 | DONE | P1 | Template editor | FE - Web | Build `TemplateEditorComponent`: create/edit templates with variable substitution. |
| 10 | NOTIFY-010 | DONE | P1 | Quiet hours | FE - Web | Implement quiet hours configuration: schedule, timezone, override policy. |
| 11 | NOTIFY-011 | DONE | P1 | Operator overrides | FE - Web | Build operator override management: on-call routing, temporary mutes. |
| 12 | NOTIFY-012 | DONE | P1 | Escalation policies | FE - Web | Implement escalation configuration: timeout, fallback channels. |
| 13 | NOTIFY-013 | DONE | P2 | Throttle config | FE - Web | Build throttle configuration: rate limits, deduplication windows. |
| 14 | NOTIFY-014 | DONE | P2 | Delivery analytics | FE - Web | Add delivery analytics: success rate, average latency, top failures. |
| 15 | NOTIFY-015 | DONE | P2 | Docs update | FE - Docs | Update notification administration guide and runbook. |
| 16 | NOTIFY-016 | DONE | P0 | Notifier API parity | Notifier - BE | Added delivery retry endpoint (`POST /api/v1/notify/deliveries/{id}/retry`) and delivery stats endpoint (`GET /api/v1/notify/deliveries/stats`) to Notifier.WebService Program.cs. |
| 17 | NOTIFY-017 | DONE | P0 | UI base URL | FE - Web | Update notify API base URL in `app.config.ts` and `notify` API client to use `/api/v1/notify`. |
| 18 | NOTIFY-018 | DONE | P0 | API merge | Notify/Notifier - BE | Map v2-only endpoints into the `/api/v1/notify` surface or provide gateway compatibility routing; document a deprecation timeline. |
| 19 | NOTIFY-019 | DONE | P1 | Parity audit | Notify/Notifier - BE | Audit `/api/v2/notify` endpoints for missing v1 parity and decide which features are UI-relevant. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-29 | Renamed sprint file to numeric batch ID to conform with standard format. | Planning |
| 2025-12-29 | Sprint created as split from SPRINT_018; focused on notification management. | Planning |
| 2025-12-29 | Aligned backend dependency paths to Notify v1 and added API parity task. | Planning |
| 2025-12-29 | Added UI base URL alignment task for notify client. | Planning |
| 2025-12-29 | Aligned notify API base URL in UI config (NOTIFY-017). | Implementer |
| 2025-12-30 | Completed NOTIFY-016: Added delivery retry and stats endpoints to Notifier.WebService with tenant-aware retry logic, attempt tracking, and delivery analytics. | Backend |
| 2025-12-30 | Re-aligned notify base URL to `/api/v1/notify` and documented legacy alias expectations. | Implementer |
| 2025-12-30 | Declared `/api/v1/notify` canonical for UI and added v2 merge/parity tasks. | Planning |
## Decisions & Risks
- Risk: Alert fatigue from poorly configured rules; mitigate with mandatory simulation before activation.
- Risk: Notification delivery failures go unnoticed; mitigate with delivery status dashboard.
- Risk: Notify v1 vs legacy v2 path mismatch blocks UI; mitigate with gateway alias or updated client base URL.
- Risk: UI base URL drift across environments; mitigate with NOTIFY-017 and gateway alias task.
- Decision: `/api/v1/notify` is the canonical UI base; `/api/v2/notify` remains compatibility-only until endpoints converge.
- Decision: Rules disabled by default until simulation passes.
- Decision: Failed deliveries auto-retry 3 times with exponential backoff.
## Next Checkpoints
- TBD: Notification UX review with operations team.
## Appendix: Notification Delivery Requirements
### Notification Rule Structure
```json
{
"id": "rule-001",
"name": "Critical Vulnerability Alert",
"enabled": true,
"conditions": {
"event_type": "finding.created",
"severity": ["critical", "high"],
"reachability": { "min": 0.7 }
},
"channels": ["slack-ops", "email-security"],
"template": "critical-vuln-template",
"throttle": {
"window": "1h",
"max_per_window": 10
},
"quiet_hours": "inherit"
}
```
### Channel Types
| Type | Configuration | Delivery | Retry Policy |
|------|---------------|----------|--------------|
| **Email** | SMTP settings, recipients | Async | 3 retries, 5min backoff |
| **Slack** | Webhook URL, channel | Async | 3 retries, 1min backoff |
| **Teams** | Webhook URL | Async | 3 retries, 1min backoff |
| **Webhook** | URL, auth, headers | Async | 5 retries, exponential |
| **PagerDuty** | Integration key, severity map | Async | 3 retries, 30s backoff |
### Dashboard Wireframe
```
Notification Administration
+-----------------------------------------------------------------+
| Tabs: [Rules] [Channels] [Templates] [Delivery] [Settings] |
+-----------------------------------------------------------------+
Rules Tab:
+-----------------------------------------------------------------+
| Notification Rules: |
| [+ Create Rule] [Test All Rules] |
+-----------------------------------------------------------------+
| +------+------------------------+---------+----------+---------+ |
| | Stat | Rule Name | Channel | Throttle | Actions | |
| +------+------------------------+---------+----------+---------+ |
| | ✅ | Critical Vuln Alert | Slack | 10/hr | [E][T][D]||
| | ✅ | Policy Promotion | Email | None | [E][T][D]||
| | ⚠️ | SLO Burn Rate | PD | 1/15min | [E][T][D]||
| | ❌ | Daily Digest (draft) | Email | 1/day | [E][T][D]||
| +------+------------------------+---------+----------+---------+ |
| Status: ✅ Active, ⚠️ Warning (throttled), ❌ Disabled |
+-----------------------------------------------------------------+
Rule Editor (modal):
+-----------------------------------------------------------------+
| Edit Notification Rule |
+-----------------------------------------------------------------+
| Name: [Critical Vulnerability Alert ] |
| Description: [Notify when critical vulns found ] |
+-----------------------------------------------------------------+
| Trigger Conditions: |
| Event Type: [finding.created v] |
| + Add Condition |
| [severity] [in] [critical, high] |
| [reachability] [>=] [0.7] |
+-----------------------------------------------------------------+
| Channels: |
| [x] slack-ops |
| [x] email-security |
| [ ] pagerduty-oncall |
+-----------------------------------------------------------------+
| Template: [critical-vuln-template v] [Preview] |
+-----------------------------------------------------------------+
| Throttle: |
| [x] Enable throttling |
| Max [10] notifications per [1 hour v] |
| Deduplication: [CVE ID + Artifact v] |
+-----------------------------------------------------------------+
| [Cancel] [Test Rule] [Save] |
+-----------------------------------------------------------------+
Rule Simulation:
+-----------------------------------------------------------------+
| Test Notification Rule |
+-----------------------------------------------------------------+
| Rule: Critical Vulnerability Alert |
+-----------------------------------------------------------------+
| Test Event: |
| Type: [finding.created v] |
| Severity: [critical v] |
| CVE: [CVE-2024-12345 ] |
| Artifact: [docker.io/acme/app:v1.2.3 ] |
| Reachability: [0.85] |
+-----------------------------------------------------------------+
| [Run Test] |
+-----------------------------------------------------------------+
| Test Results: |
| ✅ Rule matched: conditions satisfied |
| ✅ Channel: slack-ops - would deliver |
| ✅ Channel: email-security - would deliver |
| ⚠️ Throttle: 8/10 used this hour |
+-----------------------------------------------------------------+
| Preview: |
| Subject: [CRITICAL] CVE-2024-12345 in acme/app:v1.2.3 |
| Body: |
| "A critical vulnerability has been detected..." |
+-----------------------------------------------------------------+
| [Close] [Activate Rule] |
+-----------------------------------------------------------------+
Delivery History:
+-----------------------------------------------------------------+
| Delivery History: |
| [Channel: All v] [Status: All v] [Date: 24h v] [Search] |
+-----------------------------------------------------------------+
| +----------+--------+-------------+--------+--------+----------+ |
| | Time | Rule | Channel | Status | Retries| Actions | |
| +----------+--------+-------------+--------+--------+----------+ |
| | 10:23 | CritVu | slack-ops | ✅ Sent | 0 | [View] | |
| | 10:23 | CritVu | email-sec | ✅ Sent | 1 | [View] | |
| | 10:15 | PolicyP| email-admn | ❌ Fail | 3 | [Retry] | |
| | 10:10 | SLOBurn| pagerduty | ✅ Sent | 0 | [View] | |
| +----------+--------+-------------+--------+--------+----------+ |
+-----------------------------------------------------------------+
| Delivery Stats (24h): |
| Sent: 156 | Failed: 3 (1.9%) | Avg Latency: 1.2s |
+-----------------------------------------------------------------+
Quiet Hours Configuration:
+-----------------------------------------------------------------+
| Quiet Hours Configuration |
+-----------------------------------------------------------------+
| Schedule: |
| [x] Enable quiet hours |
| Start: [22:00] End: [07:00] Timezone: [UTC v] |
| Days: [x] Mon [x] Tue [x] Wed [x] Thu [x] Fri [ ] Sat [ ] Sun |
+-----------------------------------------------------------------+
| During Quiet Hours: |
| (x) Queue notifications for delivery after quiet hours |
| ( ) Drop non-critical notifications |
| ( ) Route critical only to on-call |
+-----------------------------------------------------------------+
| Override Policy: |
| [x] Allow operators to create temporary overrides |
| [x] Critical severity bypasses quiet hours |
+-----------------------------------------------------------------+
| [Cancel] [Save Configuration] |
+-----------------------------------------------------------------+
Operator Override:
+-----------------------------------------------------------------+
| Operator Overrides |
+-----------------------------------------------------------------+
| Active Overrides: |
| +--------+------------------+----------+------------+----------+ |
| | Oper | Override | Expires | Reason | Actions | |
| +--------+------------------+----------+------------+----------+ |
| | alice | Route to mobile | 4h | On-call | [Cancel] | |
| | bob | Mute slack-ops | 2h | Deployment | [Cancel] | |
| +--------+------------------+----------+------------+----------+ |
+-----------------------------------------------------------------+
| [+ Create Override] |
+-----------------------------------------------------------------+
Create Override Modal:
+-----------------------------------------------------------------+
| Create Operator Override |
+-----------------------------------------------------------------+
| Operator: [alice@example.com v] |
| Override Type: |
| ( ) Route all notifications to: [mobile-oncall v] |
| (x) Mute channel: [slack-ops v] |
| ( ) Bypass quiet hours |
+-----------------------------------------------------------------+
| Duration: [2 hours v] or until: [__/__/____] |
| Reason: [Maintenance window - deploying v2.0 ] |
+-----------------------------------------------------------------+
| [Cancel] [Create Override] |
+-----------------------------------------------------------------+
```
### Escalation Policy Configuration
| Level | Timeout | Action | Example |
|-------|---------|--------|---------|
| L1 | 0 min | Notify primary channel | Slack #ops |
| L2 | 15 min | Escalate if not ack'd | Email on-call |
| L3 | 30 min | Escalate if not ack'd | PagerDuty page |
| L4 | 60 min | Escalate to management | Email + SMS |
### Performance Requirements
- **Rule list load**: < 1s for 100 rules
- **Delivery history**: < 2s for 1000 entries
- **Simulation test**: < 2s for rule evaluation
- **Notification preview**: < 1s for template render
---
## Success Criteria
- Notification administration accessible at `/admin/notifications`.
- Rule CRUD operations work with condition builder.
- Channel management supports email, Slack, Teams, webhook.
- Delivery history shows status, retries, and failure details.
- Rule simulation validates rules before activation.
- Quiet hours and operator overrides functional.
- E2E tests cover rule creation, simulation, and delivery retry.

300
docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_046_FE_trust_scoring_dashboard.md Normal file
View File

@@ -0,0 +1,300 @@
# Sprint 20251229_046_FE - Trust Scoring Dashboard
## Topic & Scope
- Deliver issuer trust management UI with trust score configuration.
- Provide key rotation visibility with expiry warnings and rotation workflow.
- Surface Authority audit feeds (air-gap events, incident audit).
- Enable mTLS certificate tracking and verification status.
- **Working directory:** src/Web/StellaOps.Web. Evidence: `/admin/trust` route with issuer management, key rotation, and audit feeds.
## Dependencies & Concurrency
- Depends on Signer key rotation endpoints and Authority audit feeds.
- Requires Issuer Directory trust management endpoints.
- Links to SPRINT_024 (Issuer Trust UI) for detailed issuer configuration.
- **Backend Dependencies**:
- Optional gateway alias: `/api/v1/signer/keys/*` -> `/api/v1/anchors/{anchorId}/keys/*`
- POST `/api/v1/anchors/{anchorId}/keys` - Add new signing key
- POST `/api/v1/anchors/{anchorId}/keys/{keyId}/revoke` - Revoke key
- GET `/api/v1/anchors/{anchorId}/keys/{keyId}/validity` - Check key validity
- GET `/api/v1/anchors/{anchorId}/keys/history` - Key rotation history
- GET `/api/v1/anchors/{anchorId}/keys/warnings` - Expiry and rotation warnings
- GET `/authority/audit/airgap` - Air-gap audit events
- GET `/authority/audit/incident` - Incident audit events
- Optional gateway alias: `/api/v1/authority/audit/*` -> `/authority/audit/*`
- GET `/issuer-directory/issuers` - List trusted issuers
- GET `/issuer-directory/issuers/{id}/trust` - Get issuer trust score
- PUT `/issuer-directory/issuers/{id}/trust` - Update trust score
- Optional gateway alias: `/api/v1/issuerdirectory/issuers*` -> `/issuer-directory/issuers*`
- GET `/authority/certificates` - mTLS certificate inventory (to be implemented)
- GET `/authority/certificates/{id}/verify` - Verify certificate chain (to be implemented)
## Architectural Compliance
- **Determinism**: Key rotation timestamps UTC ISO-8601; trust scores use stable calculation.
- **Offline-first**: Certificate status cached for offline verification; rotation requires online.
- **AOC**: Audit events are append-only; key revocations are immutable.
- **Security**: Trust admin scoped to `trust.admin`; key material never exposed to UI.
- **Audit**: All trust changes and key rotations logged with actor and timestamp.
## Documentation Prerequisites
- docs/modules/signer/architecture.md
- docs/modules/authority/architecture.md
- docs/modules/issuer-directory/architecture.md
- docs/technical/architecture/security-boundaries.md
## Delivery Tracker
| # | Task ID | Status | Phase | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | TRUST-001 | DONE | P0 | Routes | FE - Web | Add `/admin/trust` route with navigation entry under Admin menu. |
| 2 | TRUST-002 | DONE | P0 | API client | FE - Web | Create `TrustService` in `core/services/`: unified trust management API client. |
| 3 | TRUST-003 | DONE | P0 | Key dashboard | FE - Web | Build `SigningKeyDashboardComponent`: key list with status, expiry, actions. |
| 4 | TRUST-004 | DONE | P0 | Key detail | FE - Web | Build `KeyDetailPanel`: key metadata, usage stats, rotation history. |
| 5 | TRUST-005 | DONE | P0 | Expiry warnings | FE - Web | Build `KeyExpiryWarningComponent`: alerts for keys expiring within threshold. |
| 6 | TRUST-006 | DONE | P1 | Key rotation | FE - Web | Implement key rotation workflow: add new key, update attestations, revoke old. |
| 7 | TRUST-007 | DONE | P1 | Issuer trust | FE - Web | Build `IssuerTrustListComponent`: trusted issuers with trust scores. |
| 8 | TRUST-008 | DONE | P1 | Trust score config | FE - Web | Implement trust score configuration: weights, thresholds, auto-update rules. |
| 9 | TRUST-009 | DONE | P1 | Air-gap audit | FE - Web | Build `AirgapAuditComponent`: air-gap related events and bundle tracking. |
| 10 | TRUST-010 | DONE | P1 | Incident audit | FE - Web | Build `IncidentAuditComponent`: security incidents, response tracking. |
| 11 | TRUST-011 | DONE | P2 | mTLS certificates | FE - Web | Build `CertificateInventoryComponent`: mTLS certs with chain verification. |
| 12 | TRUST-012 | DONE | P2 | Trust analytics | FE - Web | Add trust analytics: verification success rates, issuer reliability trends. |
| 13 | TRUST-013 | DONE | P2 | Docs update | FE - Docs | Update trust administration guide and key rotation runbook. |
| 14 | TRUST-014 | DONE | P0 | Gateway alias | Gateway - BE | Add signer key management alias endpoints `/api/v1/signer/keys*` mapped to `/api/v1/anchors/{anchorId}/keys*` or expose aggregated key listings. |
| 15 | TRUST-015 | DONE | P0 | Authority audit alias | Authority/Gateway - BE | Add `/api/v1/authority/audit/airgap` and `/api/v1/authority/audit/incident` aliases to `/authority/audit/*` routes. |
| 16 | TRUST-016 | DONE | P0 | Issuer directory alias | Gateway - BE | Add `/api/v1/issuerdirectory/issuers*` alias to `/issuer-directory/issuers*`. |
| 17 | TRUST-017 | DONE | P1 | Certificate inventory | Authority - BE | Expose mTLS certificate inventory + verify endpoints for UI consumption. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-29 | Sprint created as split from SPRINT_018; focused on trust and key management. | Planning |
| 2025-12-29 | Aligned backend dependency paths to live endpoints and added alias/API tasks. | Planning |
| 2025-12-29 | Implemented all FE components (TRUST-001 to TRUST-012): SigningKeyDashboardComponent, KeyDetailPanel, KeyExpiryWarningComponent, KeyRotationWizard, IssuerTrustListComponent, TrustScoreConfigComponent, AirgapAuditComponent, IncidentAuditComponent, CertificateInventoryComponent, TrustAnalyticsComponent, TrustAuditLogComponent. Created TrustApi client with models. Added navigation entry at /admin/trust. | Claude |
| 2025-12-29 | Created 12 spec test files for all trust-admin components with comprehensive test coverage. | Claude |
| 2025-12-30 | Updated sprint header to match file name and corrected authority audit alias paths. | Implementer |
## Decisions & Risks
- Risk: Signer key management is anchor-scoped; UI blocked without gateway alias or aggregate listing.
- Risk: Certificate inventory endpoints are missing; trust dashboard needs Authority API additions.
- Risk: Key rotation impacts running attestations; mitigate with grace period and re-signing workflow.
- Risk: Trust score changes affect VEX consensus; mitigate with preview and approval gate.
- Decision: Keys show fingerprint only; private material never exposed to UI.
- Decision: mTLS certificate rotation tracked but initiated via external PKI.
## Next Checkpoints
- TBD: Trust dashboard UX review with security team.
## Appendix: Trust Scoring Dashboard Requirements
### Signing Key States
| State | Description | Color | Actions |
|-------|-------------|-------|---------|
| **Active** | Current signing key | Green | View, Rotate |
| **Pending** | New key not yet active | Blue | Activate, Cancel |
| **Expiring** | Expires within 30 days | Yellow | Rotate |
| **Expired** | Past expiration date | Red | View, Revoke |
| **Revoked** | Manually revoked | Gray | View |
### Trust Score Model
```
Issuer Trust Score = Base Score × Recency Factor × Reliability Factor
Base Score:
- Vendor (product owner): 100
- CERT/Coordination: 80
- Security Researcher: 60
- Community/OSS: 50
- AI-Generated: 30
Recency Factor (last updated):
- < 7 days: 1.0
- 7-30 days: 0.9
- 30-90 days: 0.7
- > 90 days: 0.5
Reliability Factor (historical accuracy):
- > 95% accurate: 1.0
- 85-95% accurate: 0.9
- 75-85% accurate: 0.8
- < 75% accurate: 0.6
```
### Dashboard Wireframe
```
Trust Administration
+-----------------------------------------------------------------+
| Tabs: [Keys] [Issuers] [Certificates] [Audit] |
+-----------------------------------------------------------------+
Keys Tab:
+-----------------------------------------------------------------+
| Signing Keys: |
| [+ Add Key] [Rotation Wizard] |
+-----------------------------------------------------------------+
| Warnings: |
| [!] Key "prod-signer-2024" expires in 28 days - Plan rotation |
+-----------------------------------------------------------------+
| +---------+------------------+--------+----------+-------------+ |
| | Status | Key Name | Algo | Expires | Actions | |
| +---------+------------------+--------+----------+-------------+ |
| | ✅ Activ| prod-signer-2025 | EC P384| Jan 2026 | [V][R] | |
| | ⚠️ Exp | prod-signer-2024 | EC P384| Feb 2025 | [V][R][Rev] | |
| | ❌ Revok| prod-signer-2023 | RSA2048| Dec 2024 | [V] | |
| +---------+------------------+--------+----------+-------------+ |
+-----------------------------------------------------------------+
Key Detail Panel:
+-----------------------------------------------------------------+
| Key: prod-signer-2025 |
| Status: Active |
+-----------------------------------------------------------------+
| Key Information: |
| Algorithm: ECDSA P-384 |
| Fingerprint: SHA256:ab12cd34ef56... |
| Created: 2025-01-01T00:00:00Z |
| Expires: 2026-01-01T00:00:00Z |
| Created By: alice@example.com |
+-----------------------------------------------------------------+
| Usage Statistics (30 days): |
| Attestations Signed: 12,456 |
| Verification Requests: 45,678 |
| Verification Success Rate: 99.97% |
+-----------------------------------------------------------------+
| Rotation History: |
| 2025-01-01 - Created (replaced prod-signer-2024) |
| 2024-01-01 - prod-signer-2024 created |
+-----------------------------------------------------------------+
| [Rotate Key] [View Attestations] [Export Public Key] |
+-----------------------------------------------------------------+
Key Rotation Wizard:
+-----------------------------------------------------------------+
| Key Rotation Wizard |
+-----------------------------------------------------------------+
| Step 1: Generate New Key |
| Algorithm: [EC P-384 v] (recommended) |
| Key Name: [prod-signer-2026 ] |
| Expiration: [2027-01-01] |
+-----------------------------------------------------------------+
| [Next: Preview Impact] |
+-----------------------------------------------------------------+
Step 2: Impact Preview:
+-----------------------------------------------------------------+
| Rotation Impact Preview |
+-----------------------------------------------------------------+
| Affected Resources: |
| - 156 active attestations will need re-signing |
| - 23 pending verifications will use old key (grace period) |
| - Offline bundles will need regeneration |
+-----------------------------------------------------------------+
| Grace Period: |
| Old key remains valid for verification: [30 days v] |
+-----------------------------------------------------------------+
| [Back] [Next: Confirm] |
+-----------------------------------------------------------------+
Step 3: Confirm Rotation:
+-----------------------------------------------------------------+
| Confirm Key Rotation |
+-----------------------------------------------------------------+
| New Key: prod-signer-2026 (EC P-384) |
| Old Key: prod-signer-2025 (will enter grace period) |
| Grace Period: 30 days |
| Re-sign Attestations: Yes (background job) |
+-----------------------------------------------------------------+
| [!] This action cannot be undone. Old key will be revoked |
| after grace period. |
+-----------------------------------------------------------------+
| [Cancel] [Confirm Rotation] |
+-----------------------------------------------------------------+
Issuers Tab:
+-----------------------------------------------------------------+
| Trusted Issuers: |
| [+ Add Issuer] [Sync from Directory] |
+-----------------------------------------------------------------+
| +------------------+--------+-------+----------+---------------+ |
| | Issuer | Type | Score | Status | Actions | |
| +------------------+--------+-------+----------+---------------+ |
| | CISA | CERT | 92 | Active | [Edit][View] | |
| | RedHat Security | Vendor | 98 | Active | [Edit][View] | |
| | GitHub Advisory | OSS | 78 | Active | [Edit][View] | |
| | NVD | Govt | 95 | Active | [Edit][View] | |
| +------------------+--------+-------+----------+---------------+ |
+-----------------------------------------------------------------+
Trust Score Configuration:
+-----------------------------------------------------------------+
| Configure Trust Score: CISA |
+-----------------------------------------------------------------+
| Base Score: [80 ] (0-100) |
| Category: [CERT v] |
+-----------------------------------------------------------------+
| Automatic Adjustments: |
| [x] Apply recency factor (reduce score for stale data) |
| [x] Apply reliability factor (based on historical accuracy) |
| [ ] Auto-disable if accuracy < [70]% |
+-----------------------------------------------------------------+
| VEX Consensus Weight: [0.8 ] (0.0-1.0) |
| Applied when computing VEX consensus for multiple issuers |
+-----------------------------------------------------------------+
| [Cancel] [Save Configuration] |
+-----------------------------------------------------------------+
Audit Tab:
+-----------------------------------------------------------------+
| Authority Audit: |
| [Event Type: All v] [Date: 7d v] [Search] |
+-----------------------------------------------------------------+
| Subtabs: [Air-Gap Events] [Incidents] [Token Events] |
+-----------------------------------------------------------------+
| Air-Gap Events: |
| +----------+------------------+--------+------------------------+ |
| | Time | Event | Actor | Details | |
| +----------+------------------+--------+------------------------+ |
| | Jan 15 | Bundle Export | alice | v2025.01.15, 4.2GB | |
| | Jan 14 | Bundle Import | bob | v2025.01.10, validated | |
| | Jan 10 | JWKS Snapshot | system | 3 keys exported | |
| +----------+------------------+--------+------------------------+ |
+-----------------------------------------------------------------+
Certificates Tab:
+-----------------------------------------------------------------+
| mTLS Certificates: |
+-----------------------------------------------------------------+
| +------------------+----------+----------+--------+-------------+ |
| | Subject | Issuer | Expires | Status | Actions | |
| +------------------+----------+----------+--------+-------------+ |
| | signer.local | CA-Root | Mar 2025 | ✅ Valid| [V][Chain] | |
| | attestor.local | CA-Root | Mar 2025 | ✅ Valid| [V][Chain] | |
| | gateway.local | CA-Root | Feb 2025 | ⚠️ Exp | [V][Chain] | |
| +------------------+----------+----------+--------+-------------+ |
+-----------------------------------------------------------------+
| [Verify All Chains] [Export Inventory] |
+-----------------------------------------------------------------+
```
### Air-Gap Audit Events
| Event | Description | Data Captured |
|-------|-------------|---------------|
| **Bundle Export** | Offline kit exported | Version, size, assets, exporter |
| **Bundle Import** | Offline kit imported | Version, validation result, importer |
| **JWKS Snapshot** | Authority keys snapshotted | Key count, fingerprints |
| **Feed Sync** | Advisory feed synchronized | Feed ID, record count, hash |
| **Manifest Validation** | Bundle manifest verified | Signature status, hash match |
### Performance Requirements
- **Key list load**: < 1s for 50 keys
- **Trust score calculation**: < 500ms per issuer
- **Audit events load**: < 2s for 1000 events
- **Certificate chain verification**: < 3s per chain
---
## Success Criteria
- Trust dashboard accessible at `/admin/trust`.
- Signing key list shows status, expiry, and usage statistics.
- Key rotation wizard guides through safe rotation process.
- Issuer trust configuration with score weights and thresholds.
- Air-gap and incident audit feeds display correctly.
- mTLS certificate inventory with chain verification.
- E2E tests cover key rotation, trust updates, and audit viewing.

314
docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_047_FE_policy_governance_controls.md Normal file
View File

@@ -0,0 +1,314 @@
# Sprint 20251229_047_FE - Policy Governance Controls
## Topic & Scope
- Deliver risk budget configuration and consumption tracking UI.
- Provide trust weighting and staleness controls with preview capabilities.
- Enable sealed mode and override toggle management with audit trail.
- Surface risk profiles and schema validation for governance compliance.
- **Working directory:** src/Web/StellaOps.Web. Evidence: `/admin/policy/governance` route with risk budget, trust weights, sealed mode, and profiles.
## Dependencies & Concurrency
- Depends on Policy Engine governance endpoints (risk budget, trust weighting, staleness, sealed mode).
- Links to SPRINT_021b (Policy Simulation Studio) for promotion gates.
- Links to SPRINT_028 (Audit Log) for policy change history.
- **Backend Dependencies (Policy Engine live routes)**:
- Optional gateway alias: `/api/v1/policy/trust-weighting*` -> `/policy/trust-weighting*`
- Optional gateway alias: `/api/v1/system/airgap/*` -> `/system/airgap/*`
- Optional gateway alias: `/api/v1/risk/profiles*` -> `/api/risk/profiles*`
- GET `/api/v1/policy/budget/list` - List risk budgets
- GET `/api/v1/policy/budget/status/{serviceId}` - Current budget status
- GET `/api/v1/policy/budget/history/{serviceId}` - Budget consumption history
- POST `/api/v1/policy/budget/adjust` - Update risk budget
- GET `/policy/trust-weighting` - Get trust weighting configuration
- PUT `/policy/trust-weighting` - Update trust weights
- GET `/policy/trust-weighting/preview` - Preview weight impact
- GET `/system/airgap/staleness/status` - Get staleness status
- POST `/system/airgap/staleness/evaluate` - Evaluate staleness
- POST `/system/airgap/staleness/recover` - Signal staleness recovery
- POST `/system/airgap/seal` - Enable sealed mode
- POST `/system/airgap/unseal` - Disable sealed mode
- GET `/system/airgap/status` - Get sealed mode status
- GET `/api/risk/profiles` - List risk profiles
- GET `/api/risk/profiles/{profileId}/events` - Profile change events
## Architectural Compliance
- **Determinism**: Risk budget calculations use stable algorithms; all changes timestamped UTC.
- **Offline-first**: Governance configuration cached locally; changes require online connection.
- **AOC**: Budget history is append-only; sealed mode changes are immutable audit events.
- **Security**: Governance admin scoped to `policy.admin`; sealed mode toggle requires `policy.sealed`.
- **Audit**: All configuration changes logged with actor, before/after values, and timestamp.
## Documentation Prerequisites
- docs/modules/policy/architecture.md
- docs/modules/platform/architecture-overview.md
- docs/technical/architecture/security-boundaries.md
## Delivery Tracker
| # | Task ID | Status | Phase | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | GOV-001 | DONE | P0 | Routes | FE - Web | Add `/admin/policy/governance` route with navigation under Admin > Policy. |
| 2 | GOV-002 | DONE | P0 | API client | FE - Web | Create `PolicyGovernanceService` in `core/services/`: unified governance API client. |
| 3 | GOV-003 | DONE | P0 | Risk budget dashboard | FE - Web | Build `RiskBudgetDashboardComponent`: current budget, consumption chart, alerts. |
| 4 | GOV-004 | DONE | P0 | Budget config | FE - Web | Build `RiskBudgetConfigComponent`: configure budget limits and thresholds. |
| 5 | GOV-005 | DONE | P0 | Trust weighting | FE - Web | Build `TrustWeightingComponent`: configure issuer weights with preview. |
| 6 | GOV-006 | DONE | P1 | Staleness config | FE - Web | Build `StalenessConfigComponent`: configure age thresholds and warnings. |
| 7 | GOV-007 | DONE | P1 | Sealed mode | FE - Web | Build `SealedModeControlComponent`: toggle with confirmation and override management. |
| 8 | GOV-008 | DONE | P1 | Risk profiles | FE - Web | Build `RiskProfileListComponent`: list profiles with CRUD operations. |
| 9 | GOV-009 | DONE | P1 | Profile editor | FE - Web | Build `RiskProfileEditorComponent`: configure profile parameters and validation. |
| 10 | GOV-010 | DONE | P1 | Policy validation | FE - Web | Build `PolicyValidatorComponent`: schema validation with error display. |
| 11 | GOV-011 | DONE | P2 | Governance audit | FE - Web | Build `GovernanceAuditComponent`: change history with diff viewer. |
| 12 | GOV-012 | DONE | P2 | Impact preview | FE - Web | Implement impact preview for governance changes before apply. |
| 13 | GOV-013 | DONE | P2 | Docs update | FE - Docs | Update policy governance runbook and configuration guide. |
| 14 | GOV-014 | DONE | P1 | Conflict dashboard | FE - Web | Build policy conflict dashboard (rule overlaps, precedence issues). |
| 15 | GOV-015 | DONE | P1 | Conflict resolution | FE - Web | Implement conflict resolution wizard with side-by-side comparison. |
| 16 | GOV-016 | DONE | P2 | Schema validation | FE - Web | Build schema validation playground for risk profiles. |
| 17 | GOV-017 | DONE | P2 | Schema docs | FE - Web | Add schema documentation browser with examples. |
| 18 | GOV-018 | DONE | P0 | Backend parity | Policy - BE | Created GovernanceEndpoints.cs with sealed mode (status, toggle, overrides, revoke), risk profiles (CRUD, activate, deprecate, validate), and audit endpoints at `/api/v1/governance/*`. |
| 19 | GOV-019 | DONE | P1 | Gateway alias | Gateway - BE | Gateway uses dynamic service-discovery routing; services register endpoints at expected paths. No explicit aliases needed. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-29 | Sprint created as split from SPRINT_021; focused on governance controls. | Planning |
| 2025-12-29 | Aligned backend dependency paths to live Policy Engine routes and added parity tasks. | Planning |
| 2025-12-30 | Completed GOV-018: Created GovernanceEndpoints.cs in Policy.Gateway with sealed mode, risk profile, and audit endpoints. | Backend |
| 2025-12-30 | Completed GOV-019: Gateway uses dynamic routing via service registration; no explicit aliases needed. | Backend |
| 2025-12-30 | Updated sprint header to match file name and clarified gateway alias expectations for non-versioned policy routes. | Implementer |
## Decisions & Risks
- Risk: Governance changes affect production evaluation; mitigate with preview and approval gates.
- Risk: Sealed mode blocks legitimate updates; mitigate with override mechanism and expiry.
- Risk: Policy governance endpoints differ from live routes; mitigate with gateway aliases and backend parity tasks.
- Decision: Risk budget consumption calculated real-time; history snapshots hourly.
- Decision: Trust weight changes require simulation before production apply.
## Next Checkpoints
- TBD: Policy governance UX review with compliance team.
## Appendix: Policy Governance Requirements
### Risk Budget Model
```
Risk Budget = Maximum Acceptable Risk Score for Tenant
Budget Consumption = Sum(Finding Risk Scores) / Budget Limit × 100%
Risk Score Calculation:
- Base: CVSS score × 10
- Reachability Multiplier: 0.3 (unreachable) to 1.5 (highly reachable)
- Exploitability Multiplier: 0.5 (theoretical) to 2.0 (actively exploited)
- VEX Adjustment: 0.0 (not_affected) to 1.0 (affected)
Budget Thresholds:
- Green: < 70% consumed
- Yellow: 70-90% consumed
- Red: > 90% consumed
- Breach: > 100% consumed (alerts triggered)
```
### Trust Weighting Configuration
| Issuer Type | Default Weight | Range | Description |
|-------------|----------------|-------|-------------|
| Vendor | 1.0 | 0.5-1.0 | Product owner VEX statements |
| CERT | 0.8 | 0.3-1.0 | Coordination center advisories |
| NVD | 0.7 | 0.3-1.0 | Government vulnerability database |
| OSS Maintainer | 0.5 | 0.2-0.8 | Open source project VEX |
| Security Researcher | 0.4 | 0.1-0.7 | Independent researcher claims |
| AI-Generated | 0.2 | 0.0-0.5 | Machine-generated analysis |
### Dashboard Wireframe
```
Policy Governance Controls
+-----------------------------------------------------------------+
| Tabs: [Risk Budget] [Trust Weights] [Staleness] [Sealed Mode] |
| [Profiles] |
+-----------------------------------------------------------------+
Risk Budget Tab:
+-----------------------------------------------------------------+
| Risk Budget Overview: |
+-----------------------------------------------------------------+
| Current Budget: 10,000 points |
| Consumed: 7,234 points (72.3%) |
| Remaining: 2,766 points |
| Status: [⚠️ Warning - Approaching limit] |
+-----------------------------------------------------------------+
| Consumption Trend (30 days): |
| 100% | .--' |
| 80% | .---' |
| 70% |---------- Warning threshold ---------------- |
| 60% | .--' |
| 40% | .---' |
| 20% +──────────────────────────────────────> Time |
+-----------------------------------------------------------------+
| Top Risk Contributors: |
| 1. CVE-2024-1234 (critical, reachable) - 1,500 pts |
| 2. CVE-2024-5678 (high, actively exploited) - 1,200 pts |
| 3. CVE-2024-9012 (high, reachable) - 800 pts |
+-----------------------------------------------------------------+
| [Configure Budget] [View All Findings] [Export Report] |
+-----------------------------------------------------------------+
Budget Configuration Modal:
+-----------------------------------------------------------------+
| Configure Risk Budget |
+-----------------------------------------------------------------+
| Budget Limit: [10000] points |
+-----------------------------------------------------------------+
| Alert Thresholds: |
| Warning at: [70]% consumed |
| Critical at: [90]% consumed |
| Breach at: [100]% consumed |
+-----------------------------------------------------------------+
| Notification: |
| [x] Email security team on warning |
| [x] Slack #security on critical |
| [x] PagerDuty on breach |
+-----------------------------------------------------------------+
| [Cancel] [Preview Impact] [Save] |
+-----------------------------------------------------------------+
Trust Weights Tab:
+-----------------------------------------------------------------+
| Trust Weight Configuration: |
+-----------------------------------------------------------------+
| Issuer Type | Weight | Status | Actions |
|-------------------|--------|---------|--------------------------|
| Vendor | 1.0 | Default | [Edit] |
| CERT (CISA, etc) | 0.8 | Default | [Edit] |
| NVD | 0.7 | Custom | [Edit] [Reset] |
| OSS Maintainer | 0.5 | Default | [Edit] |
| Security Research | 0.4 | Custom | [Edit] [Reset] |
| AI-Generated | 0.2 | Default | [Edit] |
+-----------------------------------------------------------------+
| [Preview Impact] [Apply Changes] [Reset All to Default] |
+-----------------------------------------------------------------+
Trust Weight Impact Preview:
+-----------------------------------------------------------------+
| Trust Weight Change Impact |
+-----------------------------------------------------------------+
| Proposed Change: NVD weight 0.7 → 0.9 |
+-----------------------------------------------------------------+
| Affected Findings: 234 |
| VEX Consensus Changes: 12 |
| - 8 findings: affected → not_affected (NVD weight increased) |
| - 4 findings: not_affected → affected (vendor weight relative)|
+-----------------------------------------------------------------+
| Risk Budget Impact: +156 points (+1.6%) |
+-----------------------------------------------------------------+
| [!] This change affects production policy evaluation. |
| Review in simulation before applying. |
+-----------------------------------------------------------------+
| [Cancel] [Open Simulation] [Apply Now] |
+-----------------------------------------------------------------+
Sealed Mode Tab:
+-----------------------------------------------------------------+
| Sealed Mode Control |
+-----------------------------------------------------------------+
| Current Status: [🔓 UNSEALED] |
+-----------------------------------------------------------------+
| When sealed: |
| - Policy rule changes blocked |
| - Risk budget adjustments blocked |
| - Trust weight changes blocked |
| - Override mechanism available for emergencies |
+-----------------------------------------------------------------+
| [🔒 Enable Sealed Mode] |
+-----------------------------------------------------------------+
| Active Overrides: |
| +--------+------------------+----------+--------+-------------+ |
| | Actor | Override Type | Expires | Reason | Actions | |
| +--------+------------------+----------+--------+-------------+ |
| | alice | Policy Update | 2h | Hotfix | [Revoke] | |
| +--------+------------------+----------+--------+-------------+ |
+-----------------------------------------------------------------+
| [+ Create Emergency Override] |
+-----------------------------------------------------------------+
Sealed Mode Toggle Confirmation:
+-----------------------------------------------------------------+
| Enable Sealed Mode |
+-----------------------------------------------------------------+
| [!] You are about to seal policy governance controls. |
| |
| While sealed: |
| - No policy rule changes allowed |
| - No governance configuration changes allowed |
| - Emergency overrides require separate approval |
+-----------------------------------------------------------------+
| Reason: [Production freeze for release 2.0 ] |
| Duration: [Until manually unsealed v] |
+-----------------------------------------------------------------+
| Approval Required: [security-admin@example.com] |
+-----------------------------------------------------------------+
| [Cancel] [Enable Sealed Mode] |
+-----------------------------------------------------------------+
Risk Profiles Tab:
+-----------------------------------------------------------------+
| Risk Profiles: |
| [+ Create Profile] |
+-----------------------------------------------------------------+
| +--------------+------------------+--------+-------------------+ |
| | Profile | Description | Status | Actions | |
| +--------------+------------------+--------+-------------------+ |
| | production | Strict limits | Active | [Edit][Events] | |
| | staging | Relaxed limits | Active | [Edit][Events] | |
| | development | Minimal limits | Active | [Edit][Events] | |
| | pci-dss | PCI compliance | Active | [Edit][Events] | |
| +--------------+------------------+--------+-------------------+ |
+-----------------------------------------------------------------+
Profile Editor:
+-----------------------------------------------------------------+
| Edit Risk Profile: production |
+-----------------------------------------------------------------+
| Name: [production ] |
| Description: [Strict production limits ] |
+-----------------------------------------------------------------+
| Risk Thresholds: |
| Max Critical Findings: [0 ] (block on any critical) |
| Max High Findings: [5 ] |
| Max Risk Score: [7500] |
+-----------------------------------------------------------------+
| Severity Weights: |
| Critical: [100] points base |
| High: [50 ] points base |
| Medium: [20 ] points base |
| Low: [5 ] points base |
+-----------------------------------------------------------------+
| Staleness Override: |
| [x] Use profile-specific staleness thresholds |
| Max advisory age: [30 ] days |
| Max VEX age: [90 ] days |
+-----------------------------------------------------------------+
| [Cancel] [Validate Schema] [Save Profile] |
+-----------------------------------------------------------------+
```
### Staleness Configuration
| Data Type | Default Threshold | Warning | Critical | Description |
|-----------|-------------------|---------|----------|-------------|
| Advisory | 7 days | 14 days | 30 days | Time since last advisory feed sync |
| VEX Statement | 30 days | 60 days | 90 days | Age of VEX statement |
| SBOM | 24 hours | 72 hours | 7 days | Time since last SBOM generation |
| Reachability | 7 days | 14 days | 30 days | Age of reachability analysis |
### Performance Requirements
- **Budget calculation**: Real-time (< 500ms)
- **Trust weight preview**: < 2s for 1000 findings
- **Profile validation**: < 1s for schema check
- **Governance load**: < 1s for full dashboard
---
## Success Criteria
- Policy governance dashboard accessible at `/admin/policy/governance`.
- Risk budget dashboard shows consumption, trends, and top contributors.
- Trust weight configuration with impact preview before apply.
- Staleness thresholds configurable with warning indicators.
- Sealed mode toggle with confirmation and override management.
- Risk profiles CRUD with schema validation.
- E2E tests cover budget changes, sealed mode toggle, and profile creation.

380
docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_048_FE_policy_simulation_studio.md Normal file
View File

@@ -0,0 +1,380 @@
# Sprint 20251229_021b_FE - Policy Simulation Studio
## Topic & Scope
- **MANDATORY**: Deliver shadow policy mode with indicator UI (required before production promotion).
- Provide policy simulation console for testing against sample SBOMs and findings.
- Enable coverage fixture visualization showing which test cases policies were validated against.
- Implement policy audit log with diff viewer for change tracking.
- Build effective policy viewer showing which policies apply to which resources.
- **Working directory:** src/Web/StellaOps.Web. Evidence: `/admin/policy/simulation` route with shadow mode, simulation console, coverage view, and audit trail.
## Dependencies & Concurrency
- Depends on Policy Engine simulation and compilation endpoints (40+ endpoints).
- Links to SPRINT_021a (Policy Governance Controls) for governance integration.
- Links to existing Policy Studio for rule editing integration.
- **BLOCKER**: This sprint MUST complete before any policy can be promoted to production.
- **Backend Dependencies**:
- GET `/api/v1/policy/shadow` - Get shadow policy status
- POST `/api/v1/policy/shadow/enable` - Enable shadow mode for policy
- POST `/api/v1/policy/shadow/disable` - Disable shadow mode
- GET `/api/v1/policy/shadow/{policyId}/results` - Shadow mode evaluation results
- POST `/api/v1/policy/simulation/console` - Run simulation in console mode
- POST `/api/v1/policy/simulation/overlay` - Run simulation with overlay
- POST `/api/v1/policy/simulation/pathscope` - Run scoped simulation
- POST `/api/v1/policy/compile` - Compile policy rules
- POST `/api/v1/policy/lint` - Lint policy for errors and warnings
- GET `/api/v1/policy/coverage` - Get coverage fixture results
- POST `/api/v1/policy/coverage/run` - Run coverage fixtures
- GET `/api/v1/policy/effective` - Get effective policies for scope
- GET `/api/v1/policy/effective/{resourceId}` - Policies applied to resource
- GET `/api/v1/policy/audit/events` - Policy change events
- GET `/api/v1/policy/audit/diff/{eventId}` - Get diff for change event
- GET `/api/v1/policy/exceptions` - List active exceptions
- POST `/api/v1/policy/exceptions` - Create policy exception
- GET `/api/v1/policy/profiles/events` - Profile event history
## Architectural Compliance
- **Determinism**: Shadow mode evaluations use production-identical algorithms; timestamps UTC.
- **Offline-first**: Simulation results cached locally; simulation requires online connection.
- **AOC**: Audit events are append-only; policy diffs preserve before/after states.
- **Security**: Simulation scoped to `policy.simulate`; promotion requires `policy.promote`.
- **Audit**: All simulation runs and promotion events logged with actor and results.
## Documentation Prerequisites
- docs/modules/policy/architecture.md
- docs/modules/platform/architecture-overview.md
- docs/technical/architecture/security-boundaries.md
## Delivery Tracker
| # | Task ID | Status | Phase | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | SIM-001 | DONE | P0 | Routes | FE - Web | Add `/admin/policy/simulation` route with navigation under Admin > Policy. |
| 2 | SIM-002 | DONE | P0 | API client | FE - Web | Create `PolicySimulationService` in `core/services/`: unified simulation API client. |
| 3 | SIM-003 | DONE | P0 | Shadow indicator | FE - Web | Build `ShadowModeIndicatorComponent`: banner showing shadow status on all policy views. |
| 4 | SIM-004 | DONE | P0 | Shadow dashboard | FE - Web | Build `ShadowModeDashboardComponent`: shadow results comparison, divergence highlighting. |
| 5 | SIM-005 | DONE | P0 | Simulation console | FE - Web | Build `SimulationConsoleComponent`: run policy against test SBOMs, view results. |
| 6 | SIM-006 | DONE | P0 | Lint/compile | FE - Web | Build `PolicyLintComponent`: lint errors, warnings, compilation status. |
| 7 | SIM-007 | DONE | P1 | Coverage view | FE - Web | Build `CoverageFixtureComponent`: coverage % per rule, missing test cases. |
| 8 | SIM-008 | DONE | P1 | Effective viewer | FE - Web | Build `EffectivePolicyViewerComponent`: which policies apply to which resources. |
| 9 | SIM-009 | DONE | P1 | Audit log | FE - Web | Build `PolicyAuditLogComponent`: change history with actor, timestamp, diff link. |
| 10 | SIM-010 | DONE | P1 | Diff viewer | FE - Web | Build `PolicyDiffViewerComponent`: before/after comparison for rule changes. |
| 11 | SIM-011 | DONE | P1 | Promotion gate | FE - Web | Build `PromotionGateComponent`: checklist enforcement before production apply. |
| 12 | SIM-012 | DONE | P1 | Exception management | FE - Web | Build `PolicyExceptionComponent`: create/view/revoke policy exceptions. |
| 13 | SIM-013 | DONE | P2 | Simulation history | FE - Web | Add simulation history: past runs, reproducibility, compare runs. |
| 14 | SIM-014 | DONE | P2 | Docs update | FE - Docs | Update policy simulation guide and promotion runbook. |
| 15 | SIM-015 | DONE | P1 | Merge preview | FE - Web | Build policy pack merge preview (visual diff of combined rules). |
| 16 | SIM-016 | DONE | P1 | Merge conflicts | FE - Web | Add conflict detection with resolution suggestions. |
| 17 | SIM-017 | DONE | P2 | Batch evaluation | FE - Web | Build batch evaluation UI for evaluating multiple artifacts against policy. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-29 | Sprint created as split from SPRINT_021; MANDATORY for production promotion. | Planning |
## Decisions & Risks
- Risk: Shadow mode adds evaluation overhead; mitigate with sampling and async processing.
- Risk: Developers bypass simulation; mitigate with MANDATORY promotion gate checklist.
- Decision: Shadow mode runs for minimum 7 days before promotion eligibility.
- Decision: Coverage must reach 80% for P0 rules before promotion.
## Next Checkpoints
- TBD: Policy simulation UX review with security engineering team.
## Appendix: Policy Simulation Studio Requirements
### Shadow Mode Workflow
```
Shadow Mode Lifecycle:
1. Developer creates/updates policy rule
2. Policy enters SHADOW mode (not affecting production)
3. Shadow evaluations run alongside production (dual-write)
4. Dashboard shows divergence: shadow vs. production results
5. After minimum period (7 days default):
- If divergence acceptable → eligible for promotion
- If divergence high → investigate before promotion
6. Promotion requires checklist completion:
- [ ] Shadow mode minimum period met
- [ ] Coverage fixtures pass (80%+)
- [ ] Lint/compile errors resolved
- [ ] Security review approved
- [ ] Stakeholder sign-off
7. Policy promoted to PRODUCTION
8. Shadow data archived for audit
```
### Promotion Gate Checklist
| Gate | Requirement | Enforcement |
|------|-------------|-------------|
| **Shadow Duration** | Minimum 7 days in shadow mode | System enforced |
| **Coverage** | 80%+ coverage on P0 rules | System enforced |
| **Lint Clean** | No errors (warnings allowed) | System enforced |
| **Compile Success** | Policy compiles without errors | System enforced |
| **Divergence Review** | Divergence report reviewed | Manual approval |
| **Security Review** | Security team sign-off | Manual approval |
| **Stakeholder Approval** | Product/business approval | Manual approval |
### Dashboard Wireframe
```
Policy Simulation Studio
+-----------------------------------------------------------------+
| Tabs: [Shadow Mode] [Simulation Console] [Coverage] [Audit Log] |
| [Effective Policies] [Exceptions] |
+-----------------------------------------------------------------+
Shadow Mode Tab:
+-----------------------------------------------------------------+
| Shadow Mode Status: |
+-----------------------------------------------------------------+
| Policies in Shadow Mode: 3 |
+-----------------------------------------------------------------+
| +-------------------+--------+--------+---------+---------------+|
| | Policy | Days | Diverge| Coverage| Actions ||
| +-------------------+--------+--------+---------+---------------+|
| | critical-vuln-v2 | 12 | 2.3% | 94% | [Promote][Ext]||
| | reachability-gate | 5 | 0.8% | 87% | [View][Ext] ||
| | pci-compliance | 2 | 15.1% | 72% | [View][Ext] ||
| +-------------------+--------+--------+---------+---------------+|
+-----------------------------------------------------------------+
| [!] critical-vuln-v2 eligible for promotion (meets all gates) |
+-----------------------------------------------------------------+
Shadow Mode Detail (slide-out):
+-----------------------------------------------------------------+
| Shadow Policy: critical-vuln-v2 |
+-----------------------------------------------------------------+
| Status: SHADOW (12 days) |
| Eligible for Promotion: ✅ Yes |
+-----------------------------------------------------------------+
| Shadow vs Production Comparison: |
| Evaluations (7 days): 45,678 |
| Matching Results: 44,627 (97.7%) |
| Divergent Results: 1,051 (2.3%) |
+-----------------------------------------------------------------+
| Divergence Breakdown: |
| - More strict (shadow blocks, prod allows): 823 (78%) |
| - More lenient (shadow allows, prod blocks): 228 (22%) |
+-----------------------------------------------------------------+
| Sample Divergent Findings: |
| CVE-2024-1234 / acme/app:v1 - Shadow: BLOCK, Prod: ALLOW |
| Reason: New reachability threshold (0.6 → 0.5) |
| CVE-2024-5678 / beta/lib:v2 - Shadow: ALLOW, Prod: BLOCK |
| Reason: New exception for beta-team scope |
+-----------------------------------------------------------------+
| Promotion Gates: |
| [✅] Shadow duration: 12 days (min 7) |
| [✅] Coverage: 94% (min 80%) |
| [✅] Lint: Clean |
| [✅] Compile: Success |
| [ ] Security review: Pending (alice@example.com) |
| [ ] Stakeholder approval: Pending |
+-----------------------------------------------------------------+
| [Request Security Review] [Request Approval] [Promote to Prod] |
+-----------------------------------------------------------------+
Simulation Console Tab:
+-----------------------------------------------------------------+
| Policy Simulation Console |
+-----------------------------------------------------------------+
| Select Policy: [critical-vuln-v2 v] |
| Simulation Mode: |
| (x) Console - Full evaluation against test data |
| ( ) Overlay - Compare against production policy |
| ( ) Path Scope - Limit to specific resources |
+-----------------------------------------------------------------+
| Test Data: |
| [x] Use fixture: [standard-fixtures v] |
| [ ] Upload SBOM: [Choose File] |
| [ ] Specific CVE: [________________] |
+-----------------------------------------------------------------+
| [Run Simulation] |
+-----------------------------------------------------------------+
| Simulation Results: |
+-----------------------------------------------------------------+
| Run ID: sim-2025-01-15-001 |
| Duration: 2.3s |
| Findings Evaluated: 156 |
+-----------------------------------------------------------------+
| Results Summary: |
| PASS: 134 (85.9%) |
| BLOCK: 18 (11.5%) |
| WARN: 4 (2.6%) |
+-----------------------------------------------------------------+
| Blocked Findings: |
| +----------+------------------+----------+----------------------+|
| | CVE | Artifact | Reason | Rule ||
| +----------+------------------+----------+----------------------+|
| | CVE-2024 | acme/app:v1 | Critical | critical-block ||
| | CVE-2024 | beta/lib:v2 | Reachable| reachability-gate ||
| +----------+------------------+----------+----------------------+|
+-----------------------------------------------------------------+
| [Export Results] [Save as Fixture] [Compare with Production] |
+-----------------------------------------------------------------+
Coverage Tab:
+-----------------------------------------------------------------+
| Coverage Fixtures |
+-----------------------------------------------------------------+
| Overall Coverage: 87% |
| P0 Rules: 94% | P1 Rules: 82% | P2 Rules: 71% |
+-----------------------------------------------------------------+
| Rule Coverage Breakdown: |
| +--------------------+--------+--------+------------------------+|
| | Rule | Priority| Cover | Missing Cases ||
| +--------------------+--------+--------+------------------------+|
| | critical-block | P0 | 100% | - ||
| | reachability-gate | P0 | 92% | edge: 0.0 reachability ||
| | exploited-block | P0 | 88% | KEV with VEX override ||
| | severity-threshold | P1 | 78% | medium + reachable ||
| +--------------------+--------+--------+------------------------+|
+-----------------------------------------------------------------+
| [Run All Fixtures] [Add Test Case] [Export Coverage Report] |
+-----------------------------------------------------------------+
Lint/Compile Status:
+-----------------------------------------------------------------+
| Policy Validation: critical-vuln-v2 |
+-----------------------------------------------------------------+
| Compile Status: ✅ Success |
| Lint Status: ⚠️ 2 Warnings |
+-----------------------------------------------------------------+
| Warnings: |
| Line 23: Unused variable 'legacy_threshold' - consider removing |
| Line 45: Deprecated function 'check_v1' - migrate to 'check_v2' |
+-----------------------------------------------------------------+
| [Recompile] [View Full Report] |
+-----------------------------------------------------------------+
Audit Log Tab:
+-----------------------------------------------------------------+
| Policy Audit Log |
+-----------------------------------------------------------------+
| [Policy: All v] [Action: All v] [Date: 30d v] [Search] |
+-----------------------------------------------------------------+
| +----------+------------------+--------+--------+--------------+ |
| | Time | Policy | Action | Actor | Diff | |
| +----------+------------------+--------+--------+--------------+ |
| | Jan 15 | critical-vuln-v2 | Update | alice | [View Diff] | |
| | Jan 14 | critical-vuln-v2 | Shadow | alice | [View Diff] | |
| | Jan 10 | pci-compliance | Create | bob | [View Diff] | |
| | Jan 08 | severity-thres | Promote| alice | [View Diff] | |
| +----------+------------------+--------+--------+--------------+ |
+-----------------------------------------------------------------+
Policy Diff Viewer (modal):
+-----------------------------------------------------------------+
| Policy Change Diff |
| Policy: critical-vuln-v2 |
| Changed: 2025-01-15T10:23:00Z by alice@example.com |
+-----------------------------------------------------------------+
| Before: | After: |
| rules: | rules: |
| critical-block: | critical-block: |
| - threshold: 9.0 | + threshold: 8.5 |
| action: BLOCK | action: BLOCK |
| reachability-gate: | reachability-gate: |
| - min_reachability: 0.6 | + min_reachability: 0.5 |
| action: WARN | action: WARN |
+-----------------------------------------------------------------+
| Change Summary: |
| - Lowered critical threshold from 9.0 to 8.5 |
| - Lowered reachability gate from 0.6 to 0.5 |
+-----------------------------------------------------------------+
| [Close] [Revert to Previous] |
+-----------------------------------------------------------------+
Effective Policy Viewer Tab:
+-----------------------------------------------------------------+
| Effective Policies |
+-----------------------------------------------------------------+
| Scope: [All Resources v] or Resource: [________________] |
+-----------------------------------------------------------------+
| Policies Applied (in priority order): |
| 1. production-baseline (global) |
| 2. critical-vuln-v2 (global, shadow) |
| 3. pci-dss-overlay (scope: payment-*) |
| 4. team-beta-exceptions (scope: beta/*) |
+-----------------------------------------------------------------+
| Effective Rules for: docker.io/acme/app:v1.2.3 |
| +--------------------+----------+--------------------------------+|
| | Rule | Action | Source Policy ||
| +--------------------+----------+--------------------------------+|
| | critical-block | BLOCK | production-baseline ||
| | reachability-gate | WARN | critical-vuln-v2 (shadow) ||
| | pci-exception-123 | ALLOW | pci-dss-overlay ||
| +--------------------+----------+--------------------------------+|
+-----------------------------------------------------------------+
Exception Management Tab:
+-----------------------------------------------------------------+
| Policy Exceptions |
+-----------------------------------------------------------------+
| [+ Create Exception] |
+-----------------------------------------------------------------+
| Active Exceptions: |
| +----------+-----------------+--------+----------+--------------+|
| | ID | Scope | Reason | Expires | Actions ||
| +----------+-----------------+--------+----------+--------------+|
| | EXC-001 | CVE-2024-1234 | FP | 30d | [View][Revoke]|
| | EXC-002 | beta/*:v0.* | Dev | 7d | [View][Revoke]|
| | EXC-003 | lib-legacy:* | EOL | Never | [View][Revoke]|
| +----------+-----------------+--------+----------+--------------+|
+-----------------------------------------------------------------+
Create Exception Modal:
+-----------------------------------------------------------------+
| Create Policy Exception |
+-----------------------------------------------------------------+
| Exception Scope: |
| ( ) Specific CVE: [CVE-2024-_____] |
| (x) Resource Pattern: [beta/*:v0.* ] |
| ( ) Rule Override: [________________] |
+-----------------------------------------------------------------+
| Reason: |
| (x) False Positive - Not actually vulnerable |
| ( ) Accepted Risk - Risk accepted by security team |
| ( ) Development Only - Non-production environment |
| ( ) End of Life - Component being deprecated |
| ( ) Other: [________________] |
+-----------------------------------------------------------------+
| Justification: |
| [Beta versions are pre-release and don't deploy to prod ] |
| [Exception scoped to v0.* versions only ] |
+-----------------------------------------------------------------+
| Expiration: |
| ( ) 7 days |
| (x) 30 days |
| ( ) 90 days |
| ( ) Never (requires security approval) |
+-----------------------------------------------------------------+
| Evidence Attachments: |
| [x] Security review: SEC-2025-001 |
| [ ] Add file: [Choose File] |
+-----------------------------------------------------------------+
| [Cancel] [Create Exception] |
+-----------------------------------------------------------------+
```
### Coverage Fixture Requirements
| Priority | Minimum Coverage | Enforcement |
|----------|-----------------|-------------|
| P0 (Critical) | 90% | Blocks promotion |
| P1 (High) | 80% | Warning on promotion |
| P2 (Medium) | 70% | Informational |
| P3 (Low) | 50% | Informational |
### Performance Requirements
- **Simulation run**: < 5s for 1000 findings
- **Shadow comparison**: < 3s for divergence calculation
- **Coverage calculation**: < 2s for all rules
- **Lint/compile**: < 1s for policy validation
---
## Success Criteria
- Policy Simulation Studio accessible at `/admin/policy/simulation`.
- Shadow mode indicator visible on all policy views when policy in shadow.
- Simulation console runs policies against test SBOMs with results display.
- Coverage fixtures show per-rule coverage with missing test cases.
- Promotion gate enforces mandatory checklist before production apply.
- Audit log with diff viewer shows complete change history.
- E2E tests cover shadow mode, simulation, coverage, and promotion workflow.

37
docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_050_FE_replay_alignment.md Normal file
View File

@@ -0,0 +1,37 @@
# Sprint 20251229_050_FE - Replay API Alignment
## Topic & Scope
- Align Replay UI base URLs with gateway `/v1/replay/verdict` path for deterministic replay workflows.
- Re-open evidence export/replay integration alignment after SPRINT_20251229_016 archival.
- Validate gateway exposure and router registration for Replay endpoints.
- **Working directory:** `src/Web/StellaOps.Web`.
## Dependencies & Concurrency
- Depends on Replay WebService endpoints (`/v1/replay/verdict/*`) and Gateway exposure.
- References archived sprint `docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_016_FE_evidence_export_replay_ui.md` for context.
- Can run in parallel with other FE sprints.
## Documentation Prerequisites
- docs/modules/replay/architecture.md
- docs/modules/gateway/architecture.md
- docs/modules/platform/architecture-overview.md
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | REPLAY-001 | DONE | UI base URL | FE - Web | Align Replay API base URL in `src/Web/StellaOps.Web/src/app/core/api/replay.client.ts` to `/v1/replay/verdict` with gateway base normalization. |
| 2 | REPLAY-002 | DONE | Gateway exposure | Gateway - BE | Confirm Router exposes `/v1/replay/verdict/*` via Gateway or add alias if needed. |
| 3 | REPLAY-003 | DONE | UI wiring | FE - Web | Validate replay dashboard calls align to gateway path and update evidence export UI if needed. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-30 | Sprint created; reopened replay alignment after archival of SPRINT_20251229_016. | Planning |
| 2025-12-30 | Completed REPLAY-001: Updated Replay API base URL to `/v1/replay/verdict` with gateway normalization. | Implementer |
## Decisions & Risks
- Risk: Replay API path mismatch blocks UI; mitigate with gateway alias and base URL normalization.
- Risk: Replay service not exposed via Gateway in some environments; mitigate with Router registration check.
## Next Checkpoints
- TBD: Replay alignment review with platform and UI owners.

40
docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_051_FE_platform_quota_alignment.md Normal file
View File

@@ -0,0 +1,40 @@
# Sprint 20251229_051_FE - Platform Quota Alignment
## Topic & Scope
- Align operator quota dashboard to Platform Service aggregation endpoints.
- Replace direct Authority/Gateway/Orchestrator calls with `/api/v1/platform/quotas/*`.
- Validate quota alert configuration uses platform alert endpoints.
- **Working directory:** `src/Web/StellaOps.Web`.
## Dependencies & Concurrency
- Depends on Platform Service quota endpoints (SPRINT_20251229_043_PLATFORM_platform_service_foundation.md).
- References archived sprint `docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_029_FE_operator_quota_dashboard.md` for context.
- Can run in parallel with other FE sprints.
## Documentation Prerequisites
- docs/modules/platform/platform-service.md
- docs/modules/authority/architecture.md
- docs/modules/gateway/architecture.md
- docs/modules/orchestrator/architecture.md
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | QUOTA-ALIGN-001 | DONE | Platform endpoints | FE - Web | Rewire quota API client to `/api/v1/platform/quotas/*` aggregation endpoints. |
| 2 | QUOTA-ALIGN-002 | DONE | Data contract | FE - Web | Update quota models/adapters to match platform aggregate response shapes. |
| 3 | QUOTA-ALIGN-003 | DONE | Alerts | FE - Web | Ensure quota alert config uses `/api/v1/platform/quotas/alerts` endpoints. |
| 4 | QUOTA-ALIGN-004 | DONE | Tests | FE - Web | Update unit tests for quota clients/components to use platform response fixtures. |
| 5 | QUOTA-ALIGN-005 | DONE | Data freshness | FE - Web | Add `DataFreshnessBannerComponent` showing quota snapshot "data as of" and staleness thresholds (depends on COMP-015). |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-30 | Sprint created; reopened quota alignment after SPRINT_20251229_029 archival. | Planning |
| 2025-12-30 | Added data freshness banner task tied to shared components. | Planning |
## Decisions & Risks
- Risk: Legacy quota UI uses per-service endpoints; mitigate by wiring to platform aggregate service.
- Risk: Aggregate response shape differs from legacy clients; mitigate with adapters and contract tests.
## Next Checkpoints
- TBD: Quota alignment review with platform and ops owners.

53
docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_052_FE_proof_chain_viewer.md Normal file
View File

@@ -0,0 +1,53 @@
# Sprint 20251229_052_FE - Proof Chain Viewer
## Topic & Scope
- Surface attestation and verification chains so the "proof, not promises" posture is visible in the UI.
- Provide DSSE payload inspection, signature metadata, and Rekor inclusion verification.
- Link proofs back to SBOMs, scans, policies, and VEX decisions for end-to-end traceability.
- **Working directory:** src/Web/StellaOps.Web. Evidence: `/proofs/:subjectDigest` view with timeline, DSSE viewer, and verification status.
## Dependencies & Concurrency
- Depends on Attestor endpoints for attestations, export, and verification.
- Links to Evidence Locker for bundle downloads and provenance links.
- Can run in parallel with other FE sprints.
- **Backend Dependencies (Attestor live routes)**:
- GET `/api/v1/attestations` - List attestations (filter by subject digest)
- GET `/api/v1/attestations/{uuid}` - Attestation details
- POST `/api/v1/attestations:export` - Export attestation bundle
- GET `/api/v1/rekor/entries/{uuid}` - Fetch Rekor entry
- POST `/api/v1/rekor/verify` - Verify Rekor inclusion
- POST `/api/v1/rekor/verify:bulk` - Batch verification (optional)
## Documentation Prerequisites
- docs/modules/attestor/architecture.md
- docs/modules/signer/architecture.md
- docs/modules/provenance/architecture.md
- docs/modules/evidence-locker/architecture.md
- docs/modules/ui/architecture.md
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | PROOF-001 | DONE | Routes | FE - Web | Confirm `/proofs/:subjectDigest` route and add navigation entry from scan/triage views. |
| 2 | PROOF-002 | DONE | API client | FE - Web | Create `ProofChainService` in `core/services/` to call Attestor/Rekor endpoints with deterministic caching. |
| 3 | PROOF-003 | DONE | Timeline UI | FE - Web | Build `ProofChainTimelineComponent`: ordered attestations with status badges and links. |
| 4 | PROOF-004 | DONE | DSSE viewer | FE - Web | Build `DsseViewerComponent`: payload, signature metadata, and verification hints. |
| 5 | PROOF-005 | DONE | Rekor verify | FE - Web | Add verification panel with `/rekor/verify` and inclusion proof display. |
| 6 | PROOF-006 | DONE | Export | FE - Web | Enable bundle export via `/api/v1/attestations:export` with progress and checksum display. |
| 7 | PROOF-007 | DONE | Evidence links | FE - Web | Link proofs to SBOMs, scans, VEX statements, and policy runs. |
| 8 | PROOF-008 | DONE | Backend parity | Attestor - BE | Ensure attestation list supports filtering by subject digest and returns `dataAsOfUtc` metadata. |
| 9 | PROOF-009 | DONE | Tests | FE - QA | Add unit tests for proof chain rendering and verification state transitions. |
| 10 | PROOF-010 | DONE | Docs update | FE - Docs | Update proof chain UX guide and operator runbook. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-30 | Sprint created to deliver proof chain visibility in the UI. | Planning |
## Decisions & Risks
- Risk: Missing attestation filters block proof chain discovery; mitigate with backend parity task.
- Risk: Verification errors confuse operators; mitigate with explicit error states and guidance.
- Decision: Proof chain uses stable ordering by attestation timestamp and type.
## Next Checkpoints
- TBD: Proof chain UX review with security and compliance teams.

42
docs/implplan/archived/2025-12-29-completed-sprints/SPRINT_20251229_053_FE_ops_data_freshness_alignment.md Normal file
View File

@@ -0,0 +1,42 @@
# Sprint 20251229_053_FE - Ops Data Freshness Alignment
## Topic & Scope
- Add a consistent "data as of" banner across existing Ops dashboards to reflect offline-first posture.
- Surface staleness thresholds and cache metadata for operator decision-making.
- Retrofit completed Ops dashboards without reopening archived sprint files.
- **Working directory:** src/Web/StellaOps.Web. Evidence: data freshness banner appears on `/ops/health`, `/ops/offline-kit`, `/ops/scanner`, `/ops/orchestrator/slo`, and `/ops/aoc`.
## Dependencies & Concurrency
- Depends on COMP-015 (DataFreshnessBannerComponent) from SPRINT_20251229_042.
- Applies to already-delivered Ops dashboards; safe to run in parallel with new feature sprints.
- References archived sprints for context only: SPRINT_032 (Platform Health), SPRINT_026 (Offline Kit), SPRINT_025 (Scanner Ops), SPRINT_031 (SLO), SPRINT_027 (AOC Compliance).
## Documentation Prerequisites
- docs/modules/ui/architecture.md
- docs/modules/platform/platform-service.md
- docs/modules/airgap/architecture.md
- docs/modules/scanner/architecture.md
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | DATAFRESH-001 | DONE | Platform Health | FE - Web | Add data freshness banner to `/ops/health` using platform health `dataAsOfUtc` and staleness metadata. |
| 2 | DATAFRESH-002 | DONE | Offline Kit | FE - Web | Add data freshness banner to `/ops/offline-kit` based on manifest/validation timestamps. |
| 3 | DATAFRESH-003 | DONE | Scanner Ops | FE - Web | Add data freshness banner to `/ops/scanner` showing baseline/kit snapshot timestamps. |
| 4 | DATAFRESH-004 | DONE | SLO Monitoring | FE - Web | Add data freshness banner to `/ops/orchestrator/slo` showing last burn-rate refresh time. |
| 5 | DATAFRESH-005 | DONE | AOC Compliance | FE - Web | Add data freshness banner to `/ops/aoc` showing last compliance snapshot time. |
| 6 | DATAFRESH-006 | DONE | Backend parity | Platform/Scanner/AirGap/Orchestrator - BE | Ensure Ops endpoints expose `dataAsOfUtc` (or equivalent) and staleness thresholds needed by the banner. |
| 7 | DATAFRESH-007 | DONE | Tests | FE - QA | Add unit tests for banner rendering across Ops pages using deterministic fixtures. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-30 | Sprint created to align Ops dashboards with data freshness UX. | Planning |
## Decisions & Risks
- Risk: Missing `dataAsOfUtc` fields in existing endpoints; mitigate with backend parity task.
- Risk: Operators misinterpret cached data; mitigate with explicit stale thresholds and offline badges.
- Decision: Use a shared banner in the page header for all Ops dashboards.
## Next Checkpoints
- TBD: Ops UX review for data freshness banner consistency.