Gaps fill up, fixes, ui restructuring
This commit is contained in:
master
94
docs/modules/attestor/predicate-schema-registry.md
Normal file
94
docs/modules/attestor/predicate-schema-registry.md
Normal file
@@ -0,0 +1,94 @@
|
||||
# Predicate Schema Registry
|
||||
|
||||
## Status
|
||||
- Status: DRAFT (2026-02-19)
|
||||
- Owner: Attestor Guild
|
||||
- Sprint: SPRINT_20260219_010
|
||||
|
||||
## Purpose
|
||||
Replace hardcoded predicate type URIs scattered across the codebase with a discoverable, versioned, PostgreSQL-backed registry. External tooling (cosign, policy-as-code engines, audit exporters) can query the registry to discover and validate predicate schemas.
|
||||
|
||||
## Design
|
||||
|
||||
### Storage
|
||||
- Schema: `proofchain` (alongside existing proof chain tables)
|
||||
- Table: `proofchain.predicate_type_registry`
|
||||
|
||||
### Data Model
|
||||
Each registry entry:
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `registry_id` | UUID | Primary key |
|
||||
| `predicate_type_uri` | TEXT UNIQUE | The canonical predicate type URI |
|
||||
| `display_name` | TEXT | Human-readable name |
|
||||
| `version` | TEXT | Semver string (e.g., "1.0.0") |
|
||||
| `category` | TEXT | Category: stella-core, stella-proof, ecosystem, intoto |
|
||||
| `json_schema` | JSONB | JSON Schema document for payload validation (nullable) |
|
||||
| `description` | TEXT | Purpose description |
|
||||
| `is_active` | BOOLEAN | Whether this type accepts new submissions |
|
||||
| `validation_mode` | TEXT | log-only / warn / reject (default: log-only) |
|
||||
| `created_at` | TIMESTAMPTZ | Created timestamp |
|
||||
| `updated_at` | TIMESTAMPTZ | Last update timestamp |
|
||||
|
||||
### Immutability Rule
|
||||
Once a `(predicate_type_uri, version)` pair is published, its `json_schema` MUST NOT change. New versions get new semver.
|
||||
|
||||
### API Endpoints
|
||||
- `GET /api/v1/attestor/predicates` — List all registered predicate types (paged, filterable by category and is_active)
|
||||
- `GET /api/v1/attestor/predicates/{uri}` — Get schema and metadata for a specific predicate type URI (URI is URL-encoded)
|
||||
- `POST /api/v1/attestor/predicates` — Register a new predicate type (admin-only, OpTok-gated with `attestor:admin` scope)
|
||||
|
||||
### Submission Validation
|
||||
When a DSSE envelope is submitted via `POST /api/v1/rekor/entries`:
|
||||
1. Look up `predicate_type` in registry
|
||||
2. If found and `validation_mode = "log-only"`: validate payload against `json_schema`, log result (pass/mismatch), proceed
|
||||
3. If found and `validation_mode = "warn"`: validate, emit warning metric, proceed
|
||||
4. If found and `validation_mode = "reject"`: validate, reject on mismatch (400 Bad Request)
|
||||
5. If not found: log unknown predicate type, proceed (don't block unregistered types during rollout)
|
||||
|
||||
### Seeded Predicate Types (from codebase analysis)
|
||||
|
||||
**stella-core (Attestor native):**
|
||||
1. `https://stella-ops.org/predicates/sbom-linkage/v1`
|
||||
2. `https://stella-ops.org/predicates/vex-verdict/v1`
|
||||
3. `https://stella-ops.org/predicates/evidence/v1`
|
||||
4. `https://stella-ops.org/predicates/reasoning/v1`
|
||||
5. `https://stella-ops.org/predicates/proof-spine/v1`
|
||||
6. `https://stella-ops.org/predicates/reachability-drift/v1`
|
||||
7. `https://stella-ops.org/predicates/reachability-subgraph/v1`
|
||||
8. `https://stella-ops.org/predicates/delta-verdict/v1`
|
||||
9. `https://stella-ops.org/predicates/policy-decision/v1`
|
||||
10. `https://stella-ops.org/predicates/unknowns-budget/v1`
|
||||
11. `https://stella-ops.org/predicates/ai-code-guard/v1`
|
||||
12. `https://stella-ops.org/predicates/fix-chain/v1`
|
||||
13. `https://stella-ops.org/attestation/graph-root/v1`
|
||||
|
||||
**stella-proof (ProofChain predicates):**
|
||||
14. `https://stella.ops/predicates/path-witness/v1`
|
||||
15. `https://stella.ops/predicates/runtime-witness/v1`
|
||||
16. `https://stella.ops/predicates/policy-decision@v2`
|
||||
17. `https://stellaops.dev/predicates/binary-micro-witness@v1`
|
||||
18. `https://stellaops.dev/predicates/binary-fingerprint-evidence@v1`
|
||||
19. `https://stellaops.io/attestation/budget-check/v1`
|
||||
20. `https://stellaops.dev/attestation/vex/v1`
|
||||
21. `https://stellaops.dev/attestations/vex-override/v1`
|
||||
22. `https://stellaops.dev/predicates/trust-verdict@v1`
|
||||
23. `https://stellaops.io/attestation/v1/signed-exception`
|
||||
24. `https://stellaops.dev/attestation/verification-report/v1`
|
||||
|
||||
**stella-delta (Delta predicates):**
|
||||
25. `stella.ops/changetrace@v1`
|
||||
26. `stella.ops/vex-delta@v1`
|
||||
27. `stella.ops/sbom-delta@v1`
|
||||
28. `stella.ops/verdict-delta@v1`
|
||||
29. `stellaops.binarydiff.v1`
|
||||
|
||||
**ecosystem (Standard predicates):**
|
||||
30. `https://spdx.dev/Document`
|
||||
31. `https://cyclonedx.org/bom`
|
||||
32. `https://slsa.dev/provenance`
|
||||
|
||||
**intoto (In-Toto standard):**
|
||||
33. `https://in-toto.io/Statement/v1`
|
||||
34. `https://in-toto.io/Link/v1`
|
||||
35. `https://in-toto.io/Layout/v1`
|
||||
@@ -23,6 +23,7 @@ The OCI Distribution Spec v1.1 introduced the native referrers API (), which ena
|
||||
| **Harbor 1.x** | No | Yes | N/A | Fallback only |
|
||||
| **Quay.io** | Partial | Yes | Limited | Support varies by version and configuration |
|
||||
| **JFrog Artifactory** | Partial | Yes | Limited | Requires OCI layout repository type |
|
||||
| **GitLab Container Registry** | No | Yes | N/A | Stores OCI artifacts with `subject` field but does not expose referrers endpoint; use tag-based fallback or GitLab-specific APIs |
|
||||
| **Zot** | Yes | Yes | Yes | Full OCI 1.1 support |
|
||||
| **Distribution (registry:2)** | No | Yes | N/A | Reference implementation without referrers API |
|
||||
|
||||
@@ -60,7 +61,9 @@ The OCI Distribution Spec v1.1 introduced the native referrers API (), which ena
|
||||
- **Fallback**: Yes, as backup
|
||||
- **Authentication**: Google Cloud service account or gcloud auth
|
||||
- **Rate Limits**: Generous; project quotas apply
|
||||
- **Known Issues**: None significant
|
||||
- **Known Issues**:
|
||||
- Google Artifact Registry also exposes an **attachments model** (`gcloud artifacts attachments list`) as an alternative metadata UX alongside the standard OCI referrers endpoint. StellaOps uses the standard OCI API; the Google-specific attachments API is not required.
|
||||
- Some non-Docker format features may be in public preview; Docker/OCI artifact discovery is stable.
|
||||
|
||||
### Amazon Elastic Container Registry (ECR)
|
||||
|
||||
@@ -89,16 +92,18 @@ The OCI Distribution Spec v1.1 introduced the native referrers API (), which ena
|
||||
- **Known Issues**:
|
||||
- Harbor 1.x does not support referrers API
|
||||
- Project-level permissions required
|
||||
- Harbor UI may display cosign signatures or SBOM referrers as **"UNKNOWN"** artifact type in versions around v2.15+; this is a Harbor UI classification issue and does not affect API-level discovery or StellaOps functionality
|
||||
|
||||
### Quay.io / Red Hat Quay
|
||||
|
||||
- **API Support**: Partial (version-dependent)
|
||||
- **API Support**: Partial (version-dependent); Red Hat has announced full OCI Referrers API support on Quay.io
|
||||
- **Fallback**: Yes
|
||||
- **Authentication**: Robot account or OAuth token
|
||||
- **Rate Limits**: Account tier dependent
|
||||
- **Known Issues**:
|
||||
- Support varies significantly by version
|
||||
- Some deployments may have referrers API disabled
|
||||
- Self-hosted Quay deployments may require **admin toggles or deployment flags** to enable the referrers API; if referrer discovery is inconsistent, verify the feature is enabled in the Quay configuration
|
||||
|
||||
### JFrog Artifactory
|
||||
|
||||
@@ -110,6 +115,17 @@ The OCI Distribution Spec v1.1 introduced the native referrers API (), which ena
|
||||
- Repository must be configured as Docker with OCI layout
|
||||
- Referrers API requires Artifactory 7.x+
|
||||
|
||||
### GitLab Container Registry
|
||||
|
||||
- **API Support**: No native referrers API
|
||||
- **Fallback**: Yes, required for all referrer discovery
|
||||
- **Authentication**: GitLab deploy token, personal access token, or CI job token with `read_registry` scope
|
||||
- **Rate Limits**: Instance-dependent
|
||||
- **Known Issues**:
|
||||
- Stores OCI artifacts with `subject` field but does not expose a referrers endpoint
|
||||
- Referrer discovery must use tag-schema fallback or GitLab-specific APIs
|
||||
- Discovery behavior mirrors GHCR: push referrers with tag-schema pattern and enumerate via tag listing
|
||||
|
||||
## Discovery Methods
|
||||
|
||||
### Native Referrers API (OCI 1.1)
|
||||
|
||||
@@ -26,15 +26,22 @@ This document captures the gap analysis between the competitive moat advisory an
|
||||
|
||||
| Feature | Moat | Current % | Key Gaps | Sprint Coverage |
|
||||
|---------|------|-----------|----------|-----------------|
|
||||
| Signed, replayable risk verdicts | 5 | 70% | OCI push, one-command replay | 4300_0001_* |
|
||||
| VEX decisioning engine | 4 | 85% | Evidence hooks | Minimal |
|
||||
| Reachability with proof | 4 | 75% | Standalone artifact | 4400_0001_0002 |
|
||||
| Smart-Diff semantic delta | 4 | 80% | Signed delta verdict | 4400_0001_0001 |
|
||||
| Unknowns as first-class state | 4 | 75% | Policy budgets, attestations | 4300_0002_* |
|
||||
| Air-gapped epistemic mode | 4 | 70% | Sealed snapshot workflow | 4300_0003_0001 |
|
||||
| SBOM ledger + lineage | 3 | 60% | Historical tracking, BYOS | 4600_0001_* |
|
||||
| Policy engine with proofs | 3 | 85% | Compilation to artifact | Minimal |
|
||||
| VEX distribution network | 3-4 | 30% | Hub layer entirely | 4500_0001_* |
|
||||
| Signed, replayable risk verdicts | 5 | 85% | OCI push polish | 4300_0001_* |
|
||||
| VEX decisioning engine | 4 | 90% | Evidence hooks polish | Minimal |
|
||||
| Reachability with proof | 4 | 85% | Standalone artifact polish | 4400_0001_0002 |
|
||||
| Smart-Diff semantic delta | 4 | 85% | Signed delta verdict | 4400_0001_0001 |
|
||||
| Unknowns as first-class state | 4 | 80% | Policy budgets, attestations | 4300_0002_* |
|
||||
| Air-gapped epistemic mode | 4 | 80% | Sealed snapshot workflow | 4300_0003_0001 |
|
||||
| SBOM ledger + lineage | 3 | 70% | Historical tracking, BYOS | 4600_0001_* |
|
||||
| Policy engine with proofs | 3 | 90% | Compilation to artifact | Minimal |
|
||||
| VEX distribution network | 3-4 | 50% | Hub layer refinement | 4500_0001_* |
|
||||
| Symbolized call-stack proofs | 4 | 95% | Rust/Ruby/PHP language support | Sprint 0401+, 20260220_001-002 (marketplace) |
|
||||
| Deterministic signed scoring | 5 | 85% | SLO formalization | Existing |
|
||||
| Rekor size-aware pointer strategy | 4 | 90% | Documentation polish | Existing |
|
||||
| Signed execution evidence | 3-4 | 40% | Trace-to-DSSE pipeline, policy gate | 20260219_013 |
|
||||
| Runtime beacon attestations | 3 | 20% | Beacon fact type, attestation pipeline | 20260219_014 |
|
||||
| Privacy-preserving federated telemetry | 5 | 0% | Full stack: privacy primitives, sync, API, UI | 20260220_005-009 |
|
||||
| Remediation marketplace (signed-PR fixes) | 4 | 0% | Full stack: registry, webhook, verification, UI | 20260220_010-015 |
|
||||
|
||||
---
|
||||
|
||||
@@ -209,6 +216,106 @@ This document captures the gap analysis between the competitive moat advisory an
|
||||
|
||||
---
|
||||
|
||||
### 10. Signed Execution Evidence (Moat 3-4)
|
||||
|
||||
> *Added 2026-02-19 from advisory review (rescoped from external "sandbox traces" proposal).*
|
||||
|
||||
**What exists:**
|
||||
- `RuntimeTracesEndpoints` — runtime trace ingestion in Findings module
|
||||
- `RuntimeSignalIngester` — containment/blast-radius signal ingestion in Unknowns
|
||||
- `SignalSnapshotBuilder` — signal snapshot composition for replay/audit
|
||||
- Signals `POST /signals/runtime-facts` — runtime fact ingestion (eBPF/ETW)
|
||||
- `InMemoryRuntimeInstrumentationServices` — address canonicalization, hot-symbol aggregation
|
||||
|
||||
**Gaps:**
|
||||
| Gap | Sprint |
|
||||
|-----|--------|
|
||||
| `executionEvidence@v1` predicate type | 20260219_013 (SEE-01) |
|
||||
| Trace-to-DSSE pipeline (canonicalize → aggregate → sign) | 20260219_013 (SEE-02) |
|
||||
| Policy gate: require execution evidence before promotion | 20260219_013 (SEE-03) |
|
||||
| Execution evidence in audit packs | 20260219_013 (SEE-04) |
|
||||
|
||||
**Moat Thesis**: "We don't just claim it ran — we provide signed, replayable proof of execution with deterministic trace summarization."
|
||||
|
||||
**Moat Strategy**: Elevates from Level 3 (runtime instrumentation exists elsewhere) to Level 4 when combined with existing proof chain (signed execution evidence + verdict + reachability = attestable decision lifecycle).
|
||||
|
||||
---
|
||||
|
||||
### 11. Runtime Beacon Attestations (Moat 3)
|
||||
|
||||
> *Added 2026-02-19 from advisory review (rescoped from external "canary beacons" proposal).*
|
||||
|
||||
**What exists:**
|
||||
- Signals runtime-facts ingestion pipeline
|
||||
- Zastava module (planned runtime protection/admission controller)
|
||||
- Doctor module runtime host capabilities (eBPF, ETW, dyld agents)
|
||||
|
||||
**Gaps:**
|
||||
| Gap | Sprint |
|
||||
|-----|--------|
|
||||
| `beacon` fact type in Signals | 20260219_014 (BEA-01) |
|
||||
| `beaconAttestation@v1` predicate type | 20260219_014 (BEA-01) |
|
||||
| Beacon ingestion + batched attestation pipeline | 20260219_014 (BEA-02) |
|
||||
| Beacon verification rate as policy input | 20260219_014 (BEA-03) |
|
||||
| Beacon attestations in audit packs | 20260219_014 (BEA-04) |
|
||||
|
||||
**Moat Thesis**: "Low-volume signed proof that this artifact actually ran in this environment — verifiable offline, no image modification required."
|
||||
|
||||
**Moat Strategy**: Level 3 standalone; combined with execution evidence and proof chain, contributes to the "attestable decision lifecycle" story for compliance-oriented customers.
|
||||
|
||||
---
|
||||
|
||||
### 12. Privacy-Preserving Federated Runtime Telemetry (New L5 — Structural)
|
||||
|
||||
> *Added 2026-02-19 from moat-gap advisory.*
|
||||
|
||||
**What exists:**
|
||||
- Signals runtime-facts ingestion pipeline (eBPF/ETW/dyld)
|
||||
- FederationHub / CrossRegionSync for bundle transport
|
||||
- DsseEnvelope signing infrastructure
|
||||
- AirGap egress policy enforcement
|
||||
|
||||
**Implementation (Sprints 20260220_005-009):**
|
||||
| Component | Sprint |
|
||||
|-----------|--------|
|
||||
| Privacy primitives (k-anonymity, DP, epsilon budget) | 20260220_005 (FPT-01 → FPT-07) |
|
||||
| Federation sync + intelligence merger | 20260220_006 (FTS-01 → FTS-06) |
|
||||
| API endpoints + CLI + Doctor plugin | 20260220_007 (FAC-01 → FAC-05) |
|
||||
| UI (5 pages under Platform Ops) | 20260220_008 (FUI-01 → FUI-07) |
|
||||
| Documentation + contracts | 20260220_009 (FDC-01 → FDC-05) |
|
||||
|
||||
**Moat Thesis**: "We share exploit intelligence across sites without sharing raw code — privacy-preserving, consent-proven, offline-compatible."
|
||||
|
||||
**Moat Strategy**: No competitor has DP + k-anonymity over federated runtime signals with DSSE consent. Network-effect moat: each new participant enriches the shared corpus. Combined with existing proof chain, creates attestable federated intelligence lifecycle.
|
||||
|
||||
---
|
||||
|
||||
### 13. Developer-Facing Signed-PR Remediation Marketplace (New L4 — Strong)
|
||||
|
||||
> *Added 2026-02-19 from moat-gap advisory.*
|
||||
|
||||
**What exists:**
|
||||
- FixChainAttestationService (DSSE-signed fix chain proofs)
|
||||
- SCM webhook pipeline in Signals
|
||||
- ReachGraph for reachability delta computation
|
||||
- Integration Hub plugin framework
|
||||
|
||||
**Implementation (Sprints 20260220_010-015):**
|
||||
| Component | Sprint |
|
||||
|-----------|--------|
|
||||
| Registry + persistence + domain models | 20260220_010 (REM-01 → REM-07) |
|
||||
| Signals webhook handler | 20260220_011 (REM-08 → REM-12) |
|
||||
| Verification pipeline (scan → delta → attest) | 20260220_012 (REM-13 → REM-17) |
|
||||
| Matching + marketplace sources + policy | 20260220_013 (REM-18 → REM-22) |
|
||||
| UI (3 pages + contextual badge) | 20260220_014 (REM-23 → REM-27) |
|
||||
| Offline bundles + CLI + docs | 20260220_015 (REM-28 → REM-32) |
|
||||
|
||||
**Moat Thesis**: "Every remediation PR is verified against reachability proof deltas and cryptographically attested — not just a patch, but proof the fix actually reduces exploitable surface."
|
||||
|
||||
**Moat Strategy**: No competitor has PR-level fix attestations verified against reachability proof deltas. Six-module integration depth (Attestor + ReachGraph + Signals + Scanner + Policy + EvidenceLocker) creates deep switching cost.
|
||||
|
||||
---
|
||||
|
||||
## Sprint Roadmap
|
||||
|
||||
### Phase 1: Moat 5 Anchor (P0)
|
||||
@@ -246,15 +353,46 @@ This document captures the gap analysis between the competitive moat advisory an
|
||||
└── SBOM becomes historical
|
||||
```
|
||||
|
||||
### Phase 5: Runtime Evidence (P2-P3)
|
||||
```
|
||||
20260219_013 (SEE-01 → SEE-04)
|
||||
│
|
||||
└── Execution becomes attestable
|
||||
|
||||
20260219_014 (BEA-01 → BEA-04)
|
||||
│
|
||||
└── Presence becomes provable
|
||||
```
|
||||
|
||||
### Phase 6: Moat Expansion — Three New Capabilities (P1)
|
||||
```
|
||||
20260220_001 → 20260220_002 → 20260220_003
|
||||
│
|
||||
└── Symbol Marketplace (L4 @ 95%)
|
||||
|
||||
20260220_005 → 20260220_006 → 20260220_007 → 20260220_008
|
||||
│
|
||||
└── Federated Telemetry (New L5)
|
||||
|
||||
20260220_010 → 20260220_011 → 20260220_012 → 20260220_013 → 20260220_014
|
||||
│
|
||||
└── Remediation Marketplace (New L4)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Competitive Positioning Summary
|
||||
|
||||
### Where StellaOps Is Strong
|
||||
1. **VEX decisioning** — Multi-mode consensus engine is ahead of competitors
|
||||
1. **VEX decisioning** — Multi-mode consensus engine is ahead of all competitors (including Docker Scout, JFrog)
|
||||
2. **Smart-Diff** — R1-R4 rules with priority scoring is unique
|
||||
3. **Policy engine** — OPA/Rego with proof output is mature
|
||||
4. **Attestor** — in-toto/DSSE infrastructure is complete
|
||||
5. **Symbolized call-stack proofs** — No competitor (Docker Scout, Trivy, JFrog) delivers function-level symbol evidence with demangled names and build-ID binding
|
||||
6. **Deterministic signed scoring** — JFrog centralizes evidence but can't replay; Stella produces seeded, verifiable scoring envelopes
|
||||
7. **Rekor size-aware strategy** — Hash pointer in Rekor + full payload in Evidence Locker solves real ~100KB upload constraints
|
||||
8. **Federated telemetry** — Privacy-preserving cross-site exploit intelligence with DP + k-anonymity + DSSE consent proofs
|
||||
9. **Remediation marketplace** — Signed-PR fix attestations verified against reachability proof deltas with contributor trust scoring
|
||||
|
||||
### Where StellaOps Must Improve
|
||||
1. **Verdict portability** — OCI push makes verdicts first-class artifacts
|
||||
@@ -266,6 +404,8 @@ This document captures the gap analysis between the competitive moat advisory an
|
||||
- **Snyk**: Don't compete on developer UX; compete on proof-carrying reachability
|
||||
- **Prisma**: Don't compete on CNAPP breadth; compete on decision integrity
|
||||
- **Anchore**: Don't compete on SBOM storage; compete on semantic diff + VEX reasoning
|
||||
- **Docker Scout**: Don't compete on registry-native DHI integration; compete on call-stack symbolization, replay, and lattice VEX
|
||||
- **JFrog**: Don't compete on artifact management breadth; compete on deterministic scoring, replayable verdicts, and function-level proofs
|
||||
|
||||
---
|
||||
|
||||
|
||||
104
docs/modules/policy/gates/beacon-rate-gate.md
Normal file
104
docs/modules/policy/gates/beacon-rate-gate.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# Beacon Verification Rate Gate
|
||||
|
||||
**Gate ID:** `beacon-rate`
|
||||
|
||||
Enforces minimum beacon verification rate for runtime canary coverage. When enabled, blocks or warns for releases where beacon coverage is insufficient in a required environment.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Checks if the target environment requires beacon coverage (configurable per environment)
|
||||
2. Reads beacon telemetry data from the policy context
|
||||
3. If no beacon data exists, applies the configured missing-beacon action (warn or block)
|
||||
4. If beacon count is below the minimum, defers rate enforcement (insufficient sample size)
|
||||
5. Compares verification rate against threshold, returns pass, warn, or block
|
||||
|
||||
## Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"PolicyGates": {
|
||||
"BeaconRate": {
|
||||
"Enabled": false,
|
||||
"BelowThresholdAction": "Warn",
|
||||
"MissingBeaconAction": "Warn",
|
||||
"MinVerificationRate": 0.8,
|
||||
"RequiredEnvironments": ["production"],
|
||||
"MinBeaconCount": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `Enabled` | bool | `false` | Whether the gate is active (opt-in) |
|
||||
| `BelowThresholdAction` | enum | `Warn` | Action when rate is below threshold: `Warn` or `Block` |
|
||||
| `MissingBeaconAction` | enum | `Warn` | Action when no beacon data exists: `Warn` or `Block` |
|
||||
| `MinVerificationRate` | double | `0.8` | Minimum acceptable verification rate (0.0–1.0) |
|
||||
| `RequiredEnvironments` | string[] | `["production"]` | Environments requiring beacon coverage |
|
||||
| `MinBeaconCount` | int | `10` | Minimum beacons before rate enforcement applies |
|
||||
|
||||
## Context Metadata Keys
|
||||
|
||||
The gate reads the following keys from `PolicyGateContext.Metadata`:
|
||||
|
||||
| Key | Type | Description |
|
||||
|-----|------|-------------|
|
||||
| `beacon_verification_rate` | double string | Verification rate (0.0–1.0) |
|
||||
| `beacon_verified_count` | int string | Number of verified beacon events |
|
||||
|
||||
## Beacon Verification States
|
||||
|
||||
| State | Description | Default Behavior |
|
||||
|-------|-------------|------------------|
|
||||
| No data | No beacon telemetry available | Depends on `MissingBeaconAction` |
|
||||
| Insufficient count | Fewer beacons than `MinBeaconCount` | Rate enforcement deferred (pass with warning) |
|
||||
| Below threshold | Rate < `MinVerificationRate` | Depends on `BelowThresholdAction` |
|
||||
| Above threshold | Rate >= `MinVerificationRate` | Pass |
|
||||
|
||||
## Example Gate Results
|
||||
|
||||
**Pass:**
|
||||
```
|
||||
Beacon verification rate (95.0%) meets threshold (80.0%)
|
||||
```
|
||||
|
||||
**Pass (environment not required):**
|
||||
```
|
||||
Beacon rate not required for environment 'dev'
|
||||
```
|
||||
|
||||
**Pass (insufficient sample):**
|
||||
```
|
||||
Beacon count (3) below minimum (10); rate enforcement deferred
|
||||
```
|
||||
|
||||
**Warn (below threshold):**
|
||||
```
|
||||
Beacon verification rate (60.0%) is below threshold (warn mode)
|
||||
```
|
||||
|
||||
**Fail (no data, block mode):**
|
||||
```
|
||||
No beacon telemetry data available for this artifact
|
||||
```
|
||||
|
||||
**Fail (below threshold, block mode):**
|
||||
```
|
||||
Beacon verification rate (60.0%) is below threshold (80.0%)
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
This gate consumes beacon verification rate data derived from `stella.ops/beaconAttestation@v1` predicates. The rate is computed by the Signals beacon pipeline as `verified_beacons / expected_beacons` over a configurable lookback window.
|
||||
|
||||
## Related Documents
|
||||
|
||||
- `docs/contracts/beacon-attestation-v1.md` — Predicate contract
|
||||
- `docs/modules/policy/gates/execution-evidence-gate.md` — Companion execution evidence gate
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-02-19.*
|
||||
96
docs/modules/policy/gates/execution-evidence-gate.md
Normal file
96
docs/modules/policy/gates/execution-evidence-gate.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Execution Evidence Gate
|
||||
|
||||
**Gate ID:** `execution-evidence`
|
||||
|
||||
Enforces that an artifact has signed execution evidence from a specific environment before promotion. Ensures artifacts are observed running (with sufficient trace quality) before advancing through the release pipeline.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Checks if the target environment requires execution evidence (configurable per environment)
|
||||
2. Reads execution evidence metadata from the policy context
|
||||
3. If no evidence exists, applies the configured action (warn or block)
|
||||
4. If evidence exists, validates trace quality (minimum hot symbols and unique call paths)
|
||||
5. Returns pass, warn, or block result
|
||||
|
||||
## Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"PolicyGates": {
|
||||
"ExecutionEvidence": {
|
||||
"Enabled": false,
|
||||
"MissingEvidenceAction": "Warn",
|
||||
"RequiredEnvironments": ["production"],
|
||||
"MinHotSymbolCount": 3,
|
||||
"MinUniqueCallPaths": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `Enabled` | bool | `false` | Whether the gate is active (opt-in) |
|
||||
| `MissingEvidenceAction` | enum | `Warn` | Action when evidence is missing: `Warn` or `Block` |
|
||||
| `RequiredEnvironments` | string[] | `["production"]` | Environments that require execution evidence |
|
||||
| `MinHotSymbolCount` | int | `3` | Minimum hot symbols for sufficient trace quality |
|
||||
| `MinUniqueCallPaths` | int | `1` | Minimum unique call paths for sufficient trace quality |
|
||||
|
||||
## Context Metadata Keys
|
||||
|
||||
The gate reads the following keys from `PolicyGateContext.Metadata`:
|
||||
|
||||
| Key | Type | Description |
|
||||
|-----|------|-------------|
|
||||
| `has_execution_evidence` | `"true"/"false"` | Whether execution evidence exists |
|
||||
| `execution_evidence_hot_symbol_count` | int string | Number of hot symbols in the evidence |
|
||||
| `execution_evidence_unique_call_paths` | int string | Number of unique call paths |
|
||||
|
||||
## Example Gate Results
|
||||
|
||||
**Pass (evidence meets quality):**
|
||||
```
|
||||
Execution evidence meets quality thresholds (hot symbols: 42, call paths: 17)
|
||||
```
|
||||
|
||||
**Pass (environment not required):**
|
||||
```
|
||||
Execution evidence not required for environment 'staging'
|
||||
```
|
||||
|
||||
**Warn (no evidence, warn mode):**
|
||||
```
|
||||
No execution evidence found for this artifact (warn mode)
|
||||
```
|
||||
|
||||
**Fail (no evidence, block mode):**
|
||||
```
|
||||
No execution evidence found for this artifact in required environment
|
||||
```
|
||||
|
||||
**Fail (insufficient quality):**
|
||||
```
|
||||
Execution evidence trace quality is insufficient: hot symbols 1 < 3 or call paths 0 < 1
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
This gate consumes `stella.ops/executionEvidence@v1` predicates generated by the Signals execution evidence pipeline. Evidence is populated in the policy context during release evaluation.
|
||||
|
||||
Typical flow:
|
||||
1. Artifact runs in staging environment
|
||||
2. Signals captures runtime trace via eBPF/ETW
|
||||
3. `ExecutionEvidenceBuilder` generates signed predicate
|
||||
4. Release promotion to production triggers policy evaluation
|
||||
5. This gate verifies execution evidence exists from staging
|
||||
|
||||
## Related Documents
|
||||
|
||||
- `docs/contracts/execution-evidence-v1.md` — Predicate contract
|
||||
- `docs/modules/policy/gates/beacon-rate-gate.md` — Companion beacon rate gate
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-02-19.*
|
||||
137
docs/modules/remediation/architecture.md
Normal file
137
docs/modules/remediation/architecture.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# Remediation Module Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
The Remediation module provides a developer-facing signed-PR remediation marketplace for the Stella Ops platform. It enables developers to discover, apply, and verify community-contributed or vendor-supplied fix templates for known vulnerabilities (CVEs).
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Fix Templates
|
||||
Structured remediation patches tied to specific CVE + PURL combinations. Templates include unified diff content, version range applicability, and trust scores from contributor history.
|
||||
|
||||
### PR Submissions
|
||||
Tracks the lifecycle of a remediation pull request from submission through scanning, merging, and post-merge verification. Each submission produces attestation evidence including reachability deltas and fix-chain DSSE envelopes.
|
||||
|
||||
### Contributors
|
||||
Community members or vendors who submit fix templates. Each contributor has a trust score computed from their verification history (verified fixes, rejections).
|
||||
|
||||
### Marketplace Sources
|
||||
Curated collections of fix templates from community, partner, or vendor origins. Sources are rated independently and can be enabled/disabled per tenant.
|
||||
|
||||
## Domain Model
|
||||
|
||||
```
|
||||
FixTemplate (remediation.fix_templates)
|
||||
├── CveId (text, indexed)
|
||||
├── Purl (text, indexed — pkg:type/name)
|
||||
├── VersionRange (semver range)
|
||||
├── PatchContent (unified diff)
|
||||
├── Status (pending/verified/rejected)
|
||||
├── TrustScore (0.0–1.0)
|
||||
├── DsseDigest (nullable — signed envelope hash)
|
||||
└── ContributorId / SourceId (foreign keys)
|
||||
|
||||
PrSubmission (remediation.pr_submissions)
|
||||
├── FixTemplateId (nullable FK)
|
||||
├── PrUrl, RepositoryUrl, SourceBranch, TargetBranch
|
||||
├── CveId (text, indexed)
|
||||
├── Status (opened/scanning/merged/verified/failed/inconclusive)
|
||||
├── PreScanDigest, PostScanDigest
|
||||
├── ReachabilityDeltaDigest, FixChainDsseDigest
|
||||
├── Verdict (fixed/partial/not_fixed/inconclusive)
|
||||
└── ContributorId
|
||||
|
||||
Contributor (remediation.contributors)
|
||||
├── Username (unique)
|
||||
├── VerifiedFixes, TotalSubmissions, RejectedSubmissions
|
||||
└── TrustScore (computed)
|
||||
|
||||
MarketplaceSource (remediation.marketplace_sources)
|
||||
├── Key (unique)
|
||||
├── SourceType (community/partner/vendor)
|
||||
├── Enabled, TrustScore
|
||||
└── LastSyncAt
|
||||
```
|
||||
|
||||
## Trust Scoring
|
||||
|
||||
Contributor trust score formula:
|
||||
```
|
||||
score = clamp((verified * 1.0 - rejected * 0.5) / max(total, 1), 0, 1)
|
||||
```
|
||||
|
||||
Trust tiers:
|
||||
- **trusted** (> 0.8): Verified track record
|
||||
- **established** (> 0.5): Growing history
|
||||
- **new** (> 0.2): Recently joined
|
||||
- **untrusted** (<= 0.2): Insufficient or negative history
|
||||
|
||||
## API Surface
|
||||
|
||||
All endpoints under `/api/v1/remediation/`.
|
||||
|
||||
### Templates
|
||||
- `GET /templates` — List fix templates (filter by CVE, PURL)
|
||||
- `GET /templates/{id}` — Get template detail
|
||||
- `POST /templates` — Create template (requires `remediation.submit`)
|
||||
|
||||
### Submissions
|
||||
- `GET /submissions` — List PR submissions
|
||||
- `GET /submissions/{id}` — Get submission with attestation chain
|
||||
- `POST /submissions` — Submit PR for verification
|
||||
- `GET /submissions/{id}/status` — Pipeline status
|
||||
|
||||
### Matching
|
||||
- `GET /match?cve=...&purl=...&version=...` — Find applicable fix templates
|
||||
|
||||
### Contributors
|
||||
- `GET /contributors` — List contributors
|
||||
- `GET /contributors/{username}` — Profile with trust score
|
||||
|
||||
### Sources
|
||||
- `GET /sources` — List marketplace sources
|
||||
- `GET /sources/{key}` — Source detail
|
||||
- `POST /sources` — Create/update source (requires `remediation.manage`)
|
||||
|
||||
## Authorization Policies
|
||||
|
||||
| Policy | Description |
|
||||
|--------|-------------|
|
||||
| `remediation.read` | Read templates, submissions, contributors, sources |
|
||||
| `remediation.submit` | Create templates and submit PRs |
|
||||
| `remediation.manage` | Manage marketplace sources, verify/reject templates |
|
||||
|
||||
## Verification Pipeline
|
||||
|
||||
1. PR submitted (status: `opened`)
|
||||
2. Pre-merge scan captures baseline SBOM digest
|
||||
3. PR merged (status: `merged`)
|
||||
4. Post-merge scan captures updated SBOM digest
|
||||
5. Reachability delta computed between pre/post digests
|
||||
6. Fix-chain DSSE envelope signed
|
||||
7. Verdict determined: `fixed`, `partial`, `not_fixed`, or `inconclusive`
|
||||
|
||||
## Webhook Integration
|
||||
|
||||
The `RemediationPrWebhookHandler` in the Signals module detects remediation PRs by:
|
||||
- Title convention: `fix(CVE-XXXX-NNNNN): description`
|
||||
- Label: `stella-ops/remediation`
|
||||
|
||||
## Module Location
|
||||
|
||||
```
|
||||
src/Remediation/
|
||||
├── StellaOps.Remediation.Core/ — Domain models, interfaces, services
|
||||
├── StellaOps.Remediation.WebService/ — API endpoints, Program.cs
|
||||
├── StellaOps.Remediation.Persistence/ — SQL migrations, repositories
|
||||
└── __Tests/StellaOps.Remediation.Tests/ — Unit tests
|
||||
```
|
||||
|
||||
## Related Sprints
|
||||
|
||||
- SPRINT_20260220_010: Registry and persistence
|
||||
- SPRINT_20260220_011: Signals webhook handler
|
||||
- SPRINT_20260220_012: Verification pipeline
|
||||
- SPRINT_20260220_013: Matching, sources, policy
|
||||
- SPRINT_20260220_014: UI components
|
||||
- SPRINT_20260220_015: Documentation
|
||||
129
docs/modules/symbols/marketplace-architecture.md
Normal file
129
docs/modules/symbols/marketplace-architecture.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# Symbol Marketplace Architecture
|
||||
|
||||
**Module**: `src/Symbols/StellaOps.Symbols.Marketplace/`
|
||||
**Server**: `src/Symbols/StellaOps.Symbols.Server/`
|
||||
**Sprint**: SPRINT_20260220_001, SPRINT_20260220_002
|
||||
**Status**: Implemented
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The Symbol Marketplace extends the existing Symbols module with a registry of symbol/debug pack sources, a browsable catalog, and a four-dimension trust scoring model. It provides the infrastructure needed to discover, evaluate, and install debug symbol packs from vendor, distro, community, and partner providers.
|
||||
|
||||
This directly strengthens the "Symbolized call-stack proofs" moat by ensuring Stella Ops can source verified debug symbols for any artifact in the reachability graph, enabling DSSE-signed call-stack resolution across platforms.
|
||||
|
||||
## Domain Primitives
|
||||
|
||||
### SymbolPackSource
|
||||
Registry entry for a symbol provider. Each source has:
|
||||
- **Key/Name**: Human-readable identifier (e.g., `microsoft-symbols`, `ubuntu-debuginfod`).
|
||||
- **SourceType**: `vendor` | `distro` | `community` | `partner`.
|
||||
- **Priority**: Integer ordering for resolution precedence.
|
||||
- **FreshnessSLA**: Target sync interval in seconds (default: 6 hours).
|
||||
- **WarningRatio**: Threshold (0-1) for warning state transition.
|
||||
|
||||
### SymbolPackCatalogEntry
|
||||
Represents an installable symbol/debug pack:
|
||||
- **PackId**: PURL-formatted package identifier.
|
||||
- **Platform**: Target platform (e.g., `linux/amd64`, `any`).
|
||||
- **Components**: Array of debug components included.
|
||||
- **DsseDigest**: DSSE signature digest for integrity verification.
|
||||
- **Installed**: Whether the pack is active for the tenant.
|
||||
|
||||
### SymbolSourceFreshnessRecord
|
||||
Materialized freshness projection following the advisory source pattern:
|
||||
- Tracks sync cadence, error rates, and SLA compliance.
|
||||
- Freshness state machine: `healthy` -> `warning` -> `stale` -> `unavailable`.
|
||||
- Includes signature coverage metrics (signed/unsigned/failure counts).
|
||||
|
||||
### SymbolSourceTrustScore
|
||||
Four-dimension trust scoring:
|
||||
| Dimension | Weight | Description |
|
||||
|-----------|--------|-------------|
|
||||
| Freshness | 0.30 | How up-to-date the source is relative to SLA |
|
||||
| Signature | 0.30 | DSSE signature coverage (signed packs / total packs) |
|
||||
| Coverage | 0.20 | Artifact coverage derived from sync success rate |
|
||||
| SLA Compliance | 0.20 | Whether source stays within freshness window |
|
||||
|
||||
Overall score = weighted average, clamped to [0, 1].
|
||||
|
||||
## Database Schema
|
||||
|
||||
### symbol_pack_sources
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| id | uuid PK | Source identifier |
|
||||
| key | text UNIQUE | Machine-readable key |
|
||||
| name | text | Display name |
|
||||
| source_type | text | vendor/distro/community/partner |
|
||||
| url | text NULL | Source endpoint URL |
|
||||
| priority | int | Resolution priority |
|
||||
| enabled | boolean | Active flag |
|
||||
| freshness_sla_seconds | int | Target sync interval |
|
||||
| warning_ratio | decimal | Warning threshold |
|
||||
| created_at | timestamptz | Creation timestamp |
|
||||
| updated_at | timestamptz NULL | Last update |
|
||||
|
||||
### symbol_pack_catalog
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| id | uuid PK | Entry identifier |
|
||||
| source_id | uuid FK | References symbol_pack_sources |
|
||||
| pack_id | text | PURL identifier |
|
||||
| platform | text | Target platform |
|
||||
| components | text[] | Component list |
|
||||
| dsse_digest | text | Signature digest |
|
||||
| version | text | Pack version |
|
||||
| size_bytes | bigint | Pack size |
|
||||
| published_at | timestamptz | Publish date |
|
||||
|
||||
## API Surface
|
||||
|
||||
### Symbol Sources (`/api/v1/symbols/sources`)
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/` | List sources with freshness projections |
|
||||
| GET | `/summary` | Summary cards (healthy/stale/unavailable counts + avg trust) |
|
||||
| GET | `/{id}` | Source detail with trust score |
|
||||
| GET | `/{id}/freshness` | Freshness detail |
|
||||
| POST | `/` | Create source |
|
||||
| PUT | `/{id}` | Update source |
|
||||
| DELETE | `/{id}` | Disable source |
|
||||
|
||||
### Marketplace Catalog (`/api/v1/symbols/marketplace`)
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/` | List catalog entries |
|
||||
| GET | `/search` | Search by PURL/platform |
|
||||
| GET | `/{entryId}` | Catalog entry detail |
|
||||
| POST | `/{entryId}/install` | Install pack for tenant |
|
||||
| POST | `/{entryId}/uninstall` | Uninstall pack |
|
||||
| GET | `/installed` | List installed packs |
|
||||
| POST | `/sync` | Trigger sync from sources |
|
||||
|
||||
All responses include `dataAsOf` timestamp for staleness detection.
|
||||
|
||||
## Integration Points
|
||||
|
||||
### IntegrationType.SymbolSource (= 7)
|
||||
New integration type added to `StellaOps.Integrations.Core`:
|
||||
- `MicrosoftSymbols = 700`
|
||||
- `UbuntuDebuginfod = 701`
|
||||
- `FedoraDebuginfod = 702`
|
||||
- `DebianDebuginfod = 703`
|
||||
- `PartnerSymbols = 704`
|
||||
|
||||
### UI Integration
|
||||
- **Symbol Sources list**: `/security-risk/symbol-sources` — freshness summary + source table.
|
||||
- **Symbol Source detail**: `/security-risk/symbol-sources/:sourceId` — trust breakdown, sync timeline.
|
||||
- **Symbol Marketplace**: `/security-risk/symbol-marketplace` — catalog browse/search with install/uninstall.
|
||||
- Sidebar entries under "Security and Risk" section.
|
||||
|
||||
### Existing Module Touchpoints
|
||||
- **Scanner**: Symbol resolution uses marketplace-installed packs for call-stack symbolication.
|
||||
- **ReachGraph**: Coverage dimension reflects artifact matching from reachability analysis.
|
||||
- **Attestor**: DSSE signatures on packs are verified through the existing proof chain infrastructure.
|
||||
- **Policy**: Trust scores feed into policy gate decisions for symbol-dependent verdicts.
|
||||
118
docs/modules/telemetry/federation-architecture.md
Normal file
118
docs/modules/telemetry/federation-architecture.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# Federated Telemetry Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
The Federated Telemetry subsystem enables privacy-preserving sharing of runtime exploit intelligence across Stella Ops instances in a federation mesh. It uses differential privacy (Laplacian noise) and k-anonymity to ensure that individual tenant data cannot be reconstructed from shared aggregates.
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
Tenant Runtime -> TelemetryFact Buffer -> TelemetryAggregator
|
||||
-> k-Anonymity Filter -> Laplacian Noise -> AggregationResult
|
||||
-> ConsentManager Check -> BundleBuilder -> DSSE-Signed Bundle
|
||||
-> EgressPolicy Check -> Federation Mesh Sync
|
||||
-> ExploitIntelligenceMerger <- Incoming Bundles from Peers
|
||||
```
|
||||
|
||||
## Privacy Model
|
||||
|
||||
### Differential Privacy (Epsilon Budget)
|
||||
|
||||
Each aggregation cycle consumes a portion of the total epsilon budget. The budget resets on a configurable period (default: 24 hours).
|
||||
|
||||
- **Epsilon per bucket**: `total_budget / number_of_buckets`
|
||||
- **Laplacian noise**: `-(sensitivity / epsilon) * sign(u) * ln(1 - 2|u|)` where u ~ Uniform(-0.5, 0.5)
|
||||
- **Budget exhaustion**: When remaining epsilon reaches zero, all further aggregation is suppressed until the next reset period.
|
||||
|
||||
### K-Anonymity
|
||||
|
||||
Buckets (grouped by CVE ID) with fewer than `k` distinct artifact digests are suppressed entirely. The default threshold is k=5, configurable via `FederatedTelemetryOptions.KAnonymityThreshold`.
|
||||
|
||||
## Consent Lifecycle
|
||||
|
||||
1. **Not Granted** (default) -- no federation data leaves the instance.
|
||||
2. **Granted** -- admin explicitly grants consent with optional TTL. A DSSE-signed consent proof is created.
|
||||
3. **Expired** -- consent with a TTL automatically reverts to Not Granted after expiry.
|
||||
4. **Revoked** -- admin explicitly revokes consent.
|
||||
|
||||
Consent state is checked at the start of each sync cycle. No bundles are built or transmitted without active consent.
|
||||
|
||||
## Sync Service
|
||||
|
||||
`FederatedTelemetrySyncService` is a `BackgroundService` that runs on a configurable interval (default: 15 minutes).
|
||||
|
||||
Each cycle:
|
||||
1. Check sealed mode -- skip if active.
|
||||
2. Check privacy budget -- skip if exhausted.
|
||||
3. Check consent -- skip if not granted.
|
||||
4. Drain fact buffer.
|
||||
5. Aggregate facts with k-anonymity and Laplacian noise.
|
||||
6. Build DSSE-signed bundle.
|
||||
7. Check egress policy.
|
||||
8. Transmit to federation mesh.
|
||||
|
||||
## Intelligence Merging
|
||||
|
||||
Incoming bundles from federation peers are processed by `ExploitIntelligenceMerger`:
|
||||
- Entries are normalized (CVE ID uppercase, timestamps UTC, site IDs lowercase).
|
||||
- Deduplication by `(CveId, SourceSiteId)` composite key.
|
||||
- Conflict resolution: latest `ObservedAt` wins.
|
||||
|
||||
## Bundle Format
|
||||
|
||||
A `FederatedBundle` contains:
|
||||
- Unique ID (GUID)
|
||||
- Source site identifier
|
||||
- Aggregation result (buckets with noisy counts, suppression flags)
|
||||
- Consent DSSE digest (proof that consent was active)
|
||||
- Bundle DSSE digest (integrity verification)
|
||||
- DSSE envelope (signed payload)
|
||||
- Creation timestamp
|
||||
|
||||
## Sealed Mode
|
||||
|
||||
When `FederatedTelemetryOptions.SealedModeEnabled` is true:
|
||||
- Sync service skips all cycles.
|
||||
- No outbound traffic is generated.
|
||||
- Local aggregation still functions for internal analytics.
|
||||
- Intelligence merging is paused.
|
||||
|
||||
## Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"FederatedTelemetry": {
|
||||
"KAnonymityThreshold": 5,
|
||||
"EpsilonBudget": 1.0,
|
||||
"BudgetResetPeriod": "24:00:00",
|
||||
"AggregationInterval": "00:15:00",
|
||||
"SealedModeEnabled": false,
|
||||
"ConsentPredicateType": "stella.ops/federatedConsent@v1",
|
||||
"BundlePredicateType": "stella.ops/federatedTelemetry@v1",
|
||||
"SiteId": "site-001"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API Surface
|
||||
|
||||
See `src/Platform/StellaOps.Platform.WebService/Endpoints/FederationTelemetryEndpoints.cs` for the full REST API.
|
||||
|
||||
| Method | Path | Auth Policy | Description |
|
||||
|--------|------|-------------|-------------|
|
||||
| GET | /api/v1/telemetry/federation/consent | FederationRead | Get consent state |
|
||||
| POST | /api/v1/telemetry/federation/consent/grant | FederationManage | Grant consent |
|
||||
| POST | /api/v1/telemetry/federation/consent/revoke | FederationManage | Revoke consent |
|
||||
| GET | /api/v1/telemetry/federation/status | FederationRead | Federation status |
|
||||
| GET | /api/v1/telemetry/federation/bundles | FederationRead | List bundles |
|
||||
| GET | /api/v1/telemetry/federation/bundles/{id} | FederationRead | Bundle detail |
|
||||
| GET | /api/v1/telemetry/federation/intelligence | FederationRead | Exploit corpus |
|
||||
| GET | /api/v1/telemetry/federation/privacy-budget | FederationRead | Budget snapshot |
|
||||
| POST | /api/v1/telemetry/federation/trigger | FederationManage | Trigger aggregation |
|
||||
|
||||
## Source Files
|
||||
|
||||
- Project: `src/Telemetry/StellaOps.Telemetry.Federation/`
|
||||
- Tests: `src/Telemetry/StellaOps.Telemetry.Federation.Tests/`
|
||||
- API: `src/Platform/StellaOps.Platform.WebService/Endpoints/FederationTelemetryEndpoints.cs`
|
||||
- UI: `src/Web/StellaOps.Web/src/app/features/platform-ops/federation-telemetry/`
|
||||
@@ -1,45 +1,132 @@
|
||||
# S00 Advisory Sources Specification
|
||||
# S00 Advisory Sources Specification
|
||||
|
||||
Status: Draft (created for sprint planning pointer integrity)
|
||||
Date: 2026-02-18
|
||||
Status: Frozen (implemented backend contracts reconciled)
|
||||
Date: 2026-02-19
|
||||
Working directory: `docs/modules/ui/v2-rewire`
|
||||
Sprint: `20260218_005`, task `R0-02`
|
||||
|
||||
## Purpose
|
||||
Define `Security and Risk -> Advisory Sources` as the decision-impact view of advisory-source health.
|
||||
|
||||
## Ownership split
|
||||
- `Integrations` owns source connector configuration, credentials, and connectivity checks.
|
||||
- `Platform Ops` owns mirror/freshness operation workflows.
|
||||
- `Security and Risk` owns advisory decision impact (gate relevance, risk confidence impact).
|
||||
Define `Security and Risk -> Advisory Sources` as the decision-impact view of advisory-source health.
|
||||
This is the security gating interpretation surface; operations on connectors/mirrors belong to other domains.
|
||||
|
||||
## Implementation reconciliation (2026-02-19)
|
||||
|
||||
- Freshness routes are implemented in Concelier:
|
||||
- `GET /api/v1/advisory-sources`
|
||||
- `GET /api/v1/advisory-sources/summary`
|
||||
- `GET /api/v1/advisory-sources/{id}/freshness`
|
||||
- Policy impact/conflict routes are implemented in Policy Gateway:
|
||||
- `GET /api/v1/advisory-sources/{id}/impact`
|
||||
- `GET /api/v1/advisory-sources/{id}/conflicts`
|
||||
- Persistence backing is implemented via:
|
||||
- `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Migrations/004_add_advisory_source_freshness_projection.sql`
|
||||
- `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Migrations/005_add_advisory_source_signature_projection.sql`
|
||||
- `src/Policy/__Libraries/StellaOps.Policy.Persistence/Migrations/005_advisory_source_projection.sql`
|
||||
- Frontend Security & Risk consumption is implemented via:
|
||||
- `src/Web/StellaOps.Web/src/app/features/security-risk/advisory-sources.api.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/features/security-risk/advisory-sources.component.ts`
|
||||
- Endpoint-driven table/summary/detail state rendering (hard fail, degraded, conflict, and empty behaviors).
|
||||
- Detail-panel advisory statistics now bind to backend contract fields (`totalAdvisories`, `signedAdvisories`, `unsignedAdvisories`, `signatureFailureCount`) instead of placeholders.
|
||||
|
||||
## Ownership split (field-level)
|
||||
|
||||
| Field / Action | Owner domain | Rationale |
|
||||
| --- | --- | --- |
|
||||
| Source name, family, description | Integrations | Connector catalog owner |
|
||||
| Credential / connectivity status | Integrations | Connector health owner |
|
||||
| Test connection action | Integrations | Links to Integrations connector detail |
|
||||
| Mirror and freshness operation actions | Platform Ops | Mirror workflow owner |
|
||||
| Last successful ingest, freshness age, freshness SLA | Platform Ops (source), Security & Risk (display) | Platform Ops publishes freshness facts; this screen reads and interprets for gating impact |
|
||||
| Signature / trust status | Administration (Trust & Signing, source), Security & Risk (display) | Administration manages trust keys; this screen shows effect on advisory verification |
|
||||
| Impacted decisions count | Security & Risk | Gate evaluation owner |
|
||||
| Impact severity | Security & Risk | Risk scoring owner |
|
||||
| Conflict detection / conflict diagnostics | Security & Risk | Conflict resolution belongs to security decision model |
|
||||
| Unsigned advisory ratio | Security & Risk | Advisory interpretation owner |
|
||||
|
||||
## Screen structure
|
||||
- Header: scope filters (region, env, source family, freshness severity).
|
||||
- Summary cards: healthy sources, stale sources, unavailable sources, conflicting-source warnings.
|
||||
- Source table columns:
|
||||
- Source name
|
||||
- Last successful ingest
|
||||
- Freshness SLA
|
||||
- Current freshness age
|
||||
- Signature/trust status
|
||||
- Impacted decisions count
|
||||
- Impact severity
|
||||
- Actions: open connector config, open mirror ops, open impacted findings/gates
|
||||
- Detail panel:
|
||||
- Source status timeline
|
||||
- Conflict diagnostics
|
||||
- Signed/unsigned advisory ratio
|
||||
- Impacted release/approval/environment references
|
||||
|
||||
### Header
|
||||
- Page title: `Advisory Sources`
|
||||
- Scope filters: region, environment, source family (feed type), freshness severity.
|
||||
- Quick stats bar: total sources, healthy count, stale count, unavailable count.
|
||||
|
||||
### Summary cards (4 cards)
|
||||
- Healthy sources — count with trend.
|
||||
- Stale sources — count with worst freshness age and SLA breach delta.
|
||||
- Unavailable sources — count; includes sources with connectivity failure or mirror lag > threshold.
|
||||
- Conflicting-source warnings — count of active advisory conflicts with unresolved triage status.
|
||||
|
||||
### Source table
|
||||
Required columns:
|
||||
|
||||
| Column | Source | Notes |
|
||||
| --- | --- | --- |
|
||||
| Source name | Integrations | Link to Integrations connector detail with preserved source id |
|
||||
| Source family | Integrations | Feed type (NVD, OSV, GHSA, vendor, custom) |
|
||||
| Last successful ingest | Platform Ops | Timestamp |
|
||||
| Freshness age | Platform Ops | Age since last successful ingest |
|
||||
| Freshness SLA | Platform Ops | Configured SLA threshold |
|
||||
| Freshness status | Platform Ops | Healthy / Warning / Stale / Unavailable badge |
|
||||
| Signature / trust status | Administration | Signed / Unsigned / Untrusted |
|
||||
| Impacted decisions count | Security & Risk | Count of release/approval decisions gated by this source |
|
||||
| Impact severity | Security & Risk | Highest severity of active advisory in this source affecting decisions |
|
||||
|
||||
### Table actions per row
|
||||
- Open connector config → navigates to Integrations connector detail (preserved source id).
|
||||
- Open mirror ops → navigates to Platform Ops feeds/freshness page (preserved source id).
|
||||
- View impacted findings/gates → navigates to Security & Risk findings filtered by source.
|
||||
|
||||
### Detail panel (slide-in)
|
||||
Opened from row click. Sections:
|
||||
- Source status timeline — ingest events, gaps, and failure events.
|
||||
- Conflict diagnostics — conflicting statement list with source pair, advisory id, conflict type (severity mismatch, remediation mismatch, existence conflict).
|
||||
- Advisory statistics — total advisories, signed count, unsigned count, signature failure count.
|
||||
- Impacted release/approval/environment references — linked list of active decisions impacted by this source.
|
||||
|
||||
## State behavior
|
||||
- Healthy: all freshness and signature checks pass.
|
||||
- Stale: freshness age exceeds SLA; show gating confidence warning.
|
||||
- Unavailable: source unreachable; mark impacted decisions as degraded confidence.
|
||||
- Conflict: source statements disagree; show conflict badge and triage action.
|
||||
|
||||
## Required links
|
||||
- To `Integrations` connector detail with preserved source id.
|
||||
- To `Platform Ops` feeds/mirror page with preserved source id.
|
||||
- To `Security and Risk` findings filtered by source impact.
|
||||
### Per-source states
|
||||
|
||||
## Contract notes
|
||||
- This screen likely requires an aggregate endpoint composed from integrations + ops + security data.
|
||||
- Initial classification expected: `MISSING_NEW` pending contract definition.
|
||||
| State | Trigger | UI treatment |
|
||||
| --- | --- | --- |
|
||||
| Healthy | Freshness within SLA, signature valid or source is unsigned-accepted | Green badge; no action surfaced |
|
||||
| Warning | Freshness age approaching SLA (configurable threshold, default 80%) | Yellow badge; show time-to-breach |
|
||||
| Stale | Freshness age exceeds SLA | Red badge; show gating confidence degraded warning; show Open mirror ops action |
|
||||
| Unavailable | No ingest activity in critical window or mirror failure | Critical badge; show Open connector config action; impacted decisions show degraded confidence |
|
||||
| Conflicting | Active unresolved advisory conflict involving this source | Conflict badge; show conflict count; triage link |
|
||||
|
||||
### Page-level states
|
||||
|
||||
| State | Trigger | UI treatment |
|
||||
| --- | --- | --- |
|
||||
| All healthy | All sources healthy or warning | No banner; summary cards show normal |
|
||||
| Degraded sources present | One or more stale or unavailable | Warning banner with count and quick action links |
|
||||
| Conflict active | One or more unresolved conflicts | Security banner with conflict count; link to filtered view |
|
||||
| Stale data | Advisory source API returns cached or stale data (> configured page-stale threshold) | Stale-data banner with last-refreshed timestamp; disable gating-critical actions |
|
||||
| Hard fail | Advisory source API unavailable | Error banner; page content unavailable; link to Platform Ops data-integrity page |
|
||||
| Empty | No advisory sources configured | Empty state with link to Integrations to configure first source |
|
||||
|
||||
## Forbidden behaviors
|
||||
|
||||
- This page must not expose connector credential editing (Integrations owns this).
|
||||
- This page must not expose freshness operation controls such as trigger sync, clear cache (Platform Ops owns this).
|
||||
- This page must not host trust key or issuer management (Administration owns this).
|
||||
- Conflict diagnostics is a read-only view; resolution actions are surfaced as links to owning triage surfaces.
|
||||
|
||||
## API dependency list
|
||||
|
||||
| API | Proposed endpoint | Owner module | Status class | Auth scope | Notes |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Advisory source list with freshness | `GET /api/v1/advisory-sources` | `Concelier` | `EXISTS_COMPAT` | `advisory:read` | Implemented; requires tenant via `X-Stella-Tenant` or `tenant_id` claim |
|
||||
| Advisory source freshness detail | `GET /api/v1/advisory-sources/{id}/freshness` | `Concelier` | `EXISTS_COMPAT` | `advisory:read` | Implemented; supports source UUID/key lookup and includes advisory stats fields for detail diagnostics |
|
||||
| Advisory source gating impact | `GET /api/v1/advisory-sources/{id}/impact` | `Policy` | `EXISTS_COMPAT` | `findings:read` | Implemented; supports `region`, `environment`, and `sourceFamily` filters |
|
||||
| Advisory source conflict report | `GET /api/v1/advisory-sources/{id}/conflicts` | `Policy` | `EXISTS_COMPAT` | `findings:read` | Implemented; supports `status` plus deterministic `limit`/`offset` pagination |
|
||||
| Advisory source summary aggregate | `GET /api/v1/advisory-sources/summary` | `Concelier` | `EXISTS_COMPAT` | `advisory:read` | Implemented card aggregate (healthy/warning/stale/unavailable/disabled/conflicts placeholder) |
|
||||
| Security source freshness (existing) | `GET /api/v1/security/sources/freshness` (check Concelier) | `Concelier` | `EXISTS_ADAPT` | existing | May need freshness-SLA delta and impact-count additions |
|
||||
|
||||
## Non-allowed implementations
|
||||
|
||||
- A single combined API that merges connector config and freshness without a clear split contract.
|
||||
- Advisory Sources rendered as a sub-tab of Integrations or Platform Ops (Security & Risk is owner).
|
||||
- Freshness operation controls embedded in this page (must be deep-link to Platform Ops only).
|
||||
|
||||
@@ -1,27 +1,50 @@
|
||||
# S00 Endpoint Contract Ledger v1 (Starter)
|
||||
# S00 Endpoint Contract Ledger v1
|
||||
|
||||
Status: Starter sheet
|
||||
Instructions: replace placeholder values with discovered implementation reality.
|
||||
Status: Frozen baseline (reconciled with backend implementation)
|
||||
Date: 2026-02-19
|
||||
Working directory: `docs/modules/ui/v2-rewire`
|
||||
Template source: `S00_contract_ledger_template.md`
|
||||
Sprint: `20260218_005`, task `R0-06`
|
||||
|
||||
## Reconciliation note (2026-02-19)
|
||||
|
||||
- Frontend shell structure was reverified in `SPRINT_20260219_002` to `SPRINT_20260219_007`.
|
||||
- Backend dependency rows `S00-T05-RC-01` and `S00-T05-SEC-02` are shipped and reclassified to `EXISTS_COMPAT`; frontend endpoint consumption for both rows is now implemented in UI surfaces.
|
||||
- Backend contract-enrichment adapters were implemented in `SPRINT_20260219_016` for `S00-T05-DASH-01`, `S00-T05-RC-02`, `S00-T05-RUN-01`, `S00-T05-APR-01`, `S00-T05-ENV-01`, `S00-T05-SEC-01`, `S00-T05-EVID-01`, `S00-T05-INT-01`, and `S00-T05-OPS-01`; these rows are now reclassified to `EXISTS_COMPAT`.
|
||||
- Backend administration adapters now cover Pack-21 A0-A7 (`/api/v1/administration/{summary,identity-access,tenant-branding,notifications,usage-limits,policy-governance,trust-signing,system}`), so `S00-T05-ADM-01` is reclassified to `EXISTS_COMPAT`.
|
||||
- Trust owner mutation routes for keys/issuers/certificates/transparency log are implemented under `/api/v1/administration/trust-signing/*` with `platform.trust.write` / `platform.trust.admin`, backed by Platform DB migration `046_TrustSigningAdministration.sql`.
|
||||
- Readiness reconciliation is recorded in `S16_release_readiness_package.md`.
|
||||
|
||||
## Status class definitions
|
||||
|
||||
| Status class | Meaning |
|
||||
| --- | --- |
|
||||
| `EXISTS_COMPAT` | Endpoint exists and is compatible with v2 screen needs without schema change. |
|
||||
| `EXISTS_ADAPT` | Endpoint exists but requires schema additions, filter/sort extensions, or composition changes for v2. |
|
||||
| `MISSING_NEW` | No endpoint exists; must be designed and implemented before the consuming sprint can complete. |
|
||||
|
||||
## Ledger
|
||||
|
||||
| Domain | Screen/Page | Canonical source refs | Current route/page | Current endpoint candidate(s) | Status | Owner module | Auth scope impact | Schema delta summary | Decision/risk notes | Action ticket |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| Dashboard | Dashboard v3 mission board | `source-of-truth.md 3.2`, `authority-matrix.md A: Dashboard`, `pack-16.md` | `/` (control-plane/dashboard variants) | `TBD` | `EXISTS_ADAPT` | `Web` | `TBD` | aggregate model for CritR, SBOM freshness, B/I/R, data integrity likely needs composition changes | route naming and model aggregation not finalized | `S00-T05-DASH-01` |
|
||||
| Release Control | Bundle catalog/detail/builder | `source-of-truth.md 3.1`, `authority-matrix.md A: bundles`, `pack-12.md` | `/releases/*` and related bundle placeholders | `TBD` | `MISSING_NEW` | `ReleaseOrchestrator` | `TBD` | bundle-version lifecycle and materialization contracts likely incomplete | high risk for schema spread across modules | `S00-T05-RC-01` |
|
||||
| Release Control | Promotions list/create/detail | `source-of-truth.md 3.1`, `authority-matrix.md A: releases`, `pack-13.md` | `/releases/*` | `TBD` | `EXISTS_ADAPT` | `ReleaseOrchestrator` | `TBD` | bundle-version anchoring required in promotion contracts | depends on bundle contract finalization | `S00-T05-RC-02` |
|
||||
| Approvals | Approvals v2 tabs and decision packet | `source-of-truth.md 3.3`, `authority-matrix.md A: approvals`, `pack-17.md` | `/approvals/*` | `TBD` | `EXISTS_ADAPT` | `Policy` | `TBD` | richer gate trace and ops/data context payloads expected | cross-service joins may be needed | `S00-T05-APR-01` |
|
||||
| Release Runs | Run timeline and rollback | `source-of-truth.md 3.1`, `authority-matrix.md A: run timeline`, `pack-14.md` | `/deployments/*` and run views | `TBD` | `EXISTS_ADAPT` | `ReleaseOrchestrator` | `TBD` | checkpoint-level evidence/log linkage may be partial | rollback guard semantics must be explicit | `S00-T05-RUN-01` |
|
||||
| Environment | Environment detail standard tabs | `source-of-truth.md 3.1 and 3.6`, `authority-matrix.md A: env detail`, `pack-18.md` | `/environments/*` | `TBD` | `EXISTS_ADAPT` | `ReleaseOrchestrator` | `TBD` | env summary requires deploy+security+ops evidence merge | risk of expensive fan-out queries | `S00-T05-ENV-01` |
|
||||
| Security and Risk | Risk overview/findings/vuln/vex/exceptions | `source-of-truth.md 3.4`, `authority-matrix.md A: security`, `pack-19.md` | `/security/*` | `TBD` | `EXISTS_ADAPT` | `Scanner` | `TBD` | decision-first grouping and filters may require endpoint normalization | mapping from existing pages may be non-trivial | `S00-T05-SEC-01` |
|
||||
| Security and Risk | Advisory Sources | `source-of-truth.md 3.4 and 5`, `authority-matrix.md B: legacy security data split`, `pack-21.md` | `TBD` | `TBD` | `MISSING_NEW` | `Integrations` | `TBD` | final screen spec pending S00-T01, likely needs new aggregate endpoint | ownership boundary unresolved until S00 freeze | `S00-T05-SEC-02` |
|
||||
| Evidence and Audit | Evidence home/packs/bundles/export/proof/replay/audit | `source-of-truth.md 3.5`, `authority-matrix.md A: evidence`, `pack-20.md` | `/evidence/*` | `TBD` | `EXISTS_ADAPT` | `EvidenceLocker` | `TBD` | requires consolidated navigation model and consistent search keys | trust links must follow administration ownership override | `S00-T05-EVID-01` |
|
||||
| Administration | A0-A7 admin surfaces (IAM, policy, trust, system) | `source-of-truth.md 2.2 and 3.8`, `authority-matrix.md A: administration`, `pack-21.md` | `/settings/*` migration targets `TBD` | `TBD` | `EXISTS_ADAPT` | `Authority` | `TBD` | ownership shift from settings to administration needs route/permissions cleanup | high migration surface area | `S00-T05-ADM-01` |
|
||||
| Integrations | Integrations taxonomy and detail + feeds tie-in | `source-of-truth.md 3.7`, `authority-matrix.md A: integrations`, `pack-21.md`, `pack-10.md` | `/settings/integrations/*` and related | `TBD` | `EXISTS_ADAPT` | `Integrations` | `TBD` | advisory connectivity and impact mapping may require model split | coordinate with Advisory Sources spec | `S00-T05-INT-01` |
|
||||
| Platform Ops | Data Integrity and Feeds/AirGap ops | `source-of-truth.md 3.6`, `authority-matrix.md A: ops`, `pack-15.md`, `pack-10.md` | `/operations/*` | `TBD` | `EXISTS_ADAPT` | `Orchestrator` | `TBD` | data-integrity aggregate likely spans scheduler/orchestrator/integrations | ensure no duplicated source-of-truth cards | `S00-T05-OPS-01` |
|
||||
| Dashboard | Dashboard v3 mission board | `source-of-truth.md 3.2`, `authority-matrix.md A: Dashboard`, `pack-16.md` | `/` (control-plane/dashboard variants) | `GET /api/v1/dashboard/summary`; existing promotion, approval, and scan summary endpoints | `EXISTS_COMPAT` | `Web` (composition) + `ReleaseOrchestrator`, `Policy`, `Scanner` | No new scopes; requires existing viewer scopes | Implemented in Platform pack adapters with deterministic data-confidence, CritR env breakdown, B/I/R coverage, and top-driver fields consumed by dashboard v3 cards | Route finalized to `/api/v1/dashboard/summary`; validated by `PackAdapterEndpointsTests` | `S00-T05-DASH-01` |
|
||||
| Release Control | Bundle catalog/detail/builder | `source-of-truth.md 3.1`, `authority-matrix.md A: bundles`, `pack-12.md` | `/release-control/bundles/*` | `GET /api/v1/release-control/bundles`; `GET /api/v1/release-control/bundles/{bundleId}`; `GET /api/v1/release-control/bundles/{bundleId}/versions`; `GET /api/v1/release-control/bundles/{bundleId}/versions/{versionId}`; `POST /api/v1/release-control/bundles`; `POST /api/v1/release-control/bundles/{bundleId}/versions`; `POST /api/v1/release-control/bundles/{bundleId}/versions/{versionId}/materialize` | `EXISTS_COMPAT` | `Platform` (`StellaOps.Platform.WebService`) | `orch:read` (read routes), `orch:operate` (create/publish/materialize) | Implemented with Postgres-backed lifecycle tables (`release.control_bundles*`) plus deterministic list ordering and idempotent materialization key handling | Collision with Evidence bundle export routes resolved by dedicated `/api/v1/release-control/*` namespace; frontend bundle surfaces are now API-bound (see sprint `20260219_003` RC3-06) | `S00-T05-RC-01` |
|
||||
| Release Control | Promotions list/create/detail | `source-of-truth.md 3.1`, `authority-matrix.md A: releases`, `pack-13.md` | `/release-control/promotions/*` | `GET /api/release-orchestrator/approvals` (list); `GET /api/release-orchestrator/approvals/{id}` (detail); `GET /api/release-orchestrator/releases/{releaseId}/available-environments` (target preflight); `GET /api/release-orchestrator/releases/{releaseId}/promotion-preview` (gate preflight); `POST /api/release-orchestrator/releases/{releaseId}/promote` (create); `POST /api/release-orchestrator/approvals/{id}/approve`; `POST /api/release-orchestrator/approvals/{id}/reject` | `EXISTS_COMPAT` | `ReleaseOrchestrator` | Existing `orch:read` / `orch:operate` | Legacy promotion/approval payloads are enriched with manifest digest, risk snapshot, hybrid reachability coverage, ops confidence, and decision digest via `ApprovalEndpoints.WithDerivedSignals` | Contract fields verified by `ReleaseControlV2EndpointsTests`; Pack 13 digest-first promotion cards no longer depend on frontend-only gap placeholders | `S00-T05-RC-02` |
|
||||
| Release Control | Run timeline, checkpoints, rollback | `source-of-truth.md 3.1`, `authority-matrix.md A: run timeline`, `pack-14.md` | `/deployments/*` and run views | `GET /api/v1/runs/{id}` (run detail); `GET /api/v1/runs/{id}/steps` (step list); `GET /api/v1/runs/{id}/steps/{stepId}` (step detail + logs); `POST /api/v1/runs/{id}/rollback` (trigger rollback) | `EXISTS_COMPAT` | `ReleaseOrchestrator` | Existing `orch:read` / `orch:operate` | Implemented v2 run contracts include ordered checkpoints plus explicit evidence-thread and log-artifact links; rollback returns deterministic accepted payload with guard state | `/api/v1/runs/*` and `/v1/runs/*` compatibility routes are live and test-backed; policy-coupled rollback guard hardening remains future work | `S00-T05-RUN-01` |
|
||||
| Approvals | Approvals v2 tabs and decision packet | `source-of-truth.md 3.3`, `authority-matrix.md A: approvals`, `pack-17.md` | `/approvals/*` | `GET /api/v1/approvals` (queue); `GET /api/v1/approvals/{id}` (detail); `GET /api/v1/approvals/{id}/gates` (gate trace); `GET /api/v1/approvals/{id}/evidence` (evidence packet); `GET /api/v1/approvals/{id}/security-snapshot` (security tab data); `GET /api/v1/approvals/{id}/ops-health` (ops/data tab); `POST /api/v1/approvals/{id}/decision` (approve/reject/defer/escalate) | `EXISTS_COMPAT` | `Policy` + `ReleaseOrchestrator` | Existing policy reviewer / approver scopes | v2 approvals adapter routes now return deterministic decision-packet shapes containing digest, gate trace, security snapshot (risk + B/I/R), and ops/data confidence payloads | Deterministic ordering and contract fields are verified in `ReleaseControlV2EndpointsTests` (queue determinism, gate ordering, decision mutation, not-found behavior) | `S00-T05-APR-01` |
|
||||
| Environment | Environment detail standard tabs | `source-of-truth.md 3.1 and 3.6`, `authority-matrix.md A: env detail`, `pack-18.md` | `/environments/*` | `GET /api/v1/environments/{id}` (detail); `GET /api/v1/environments/{id}/deployments` (deployment history); `GET /api/v1/environments/{id}/security-snapshot` (security state); `GET /api/v1/environments/{id}/evidence` (evidence summary); `GET /api/v1/environments/{id}/ops-health` (data confidence) | `EXISTS_COMPAT` | `ReleaseOrchestrator` | Existing `orch:read` | Pack-18 environment tab contracts are implemented with standardized header fields (manifest digest, risk snapshot, B/I/R coverage, ops confidence) and deterministic deployment ordering | Environment adapters are live under `/api/v1/environments/*` and validated in `ReleaseControlV2EndpointsTests` | `S00-T05-ENV-01` |
|
||||
| Security and Risk | Risk overview, findings, vulns, vex, exceptions, reachability | `source-of-truth.md 3.4`, `authority-matrix.md A: security`, `pack-19.md` | `/security/*` | `GET /api/v1/security/findings` (decision-first grouped); `GET /api/v1/security/vulnerabilities`; `GET /api/v1/security/vex`; `GET /api/v1/security/reachability`; existing risk/scanner endpoints | `EXISTS_COMPAT` | `Scanner` | Existing security viewer scopes | Security adapter routes now normalize findings/vulnerability/VEX/reachability payloads with deterministic filters and B/I/R confidence fields expected by Pack 19 decision-centric screens | Scanner routes are validated in `SecurityAdapterEndpointsTests`; exception lifecycle remains served by Policy endpoints (`/api/policy/exceptions`) and linked from security flows | `S00-T05-SEC-01` |
|
||||
| Security and Risk | Advisory Sources | `source-of-truth.md 3.4 and 5`, `authority-matrix.md B: legacy security data split`, `pack-21.md`, `S00_advisory_sources_spec.md` | `/security-risk/advisory-sources` | `GET /api/v1/advisory-sources`; `GET /api/v1/advisory-sources/summary`; `GET /api/v1/advisory-sources/{id}/freshness` (Concelier); `GET /api/v1/advisory-sources/{id}/impact`; `GET /api/v1/advisory-sources/{id}/conflicts` (Policy) | `EXISTS_COMPAT` | `Concelier` (freshness) + `Policy` (impact/conflicts) | `advisory:read` (Concelier freshness routes), `findings:read` (Policy impact/conflicts routes); tenant header required | Implemented with Concelier freshness + signature-stat projections (`vuln.source_freshness_sla`, `vuln.advisory_source_signature_projection`) and Policy impact/conflict projections (`policy.advisory_source_impacts`, `policy.advisory_source_conflicts`) | Ownership split implemented at endpoint boundary; UI composes read-only facts from Concelier + Policy without write side-effects, including backend advisory stats in detail diagnostics (see sprint `20260219_004` SR4-07) | `S00-T05-SEC-02` |
|
||||
| Evidence and Audit | Evidence home, packs, bundles, export, proof, replay, audit | `source-of-truth.md 3.5`, `authority-matrix.md A: evidence`, `pack-20.md` | `/evidence/*` | `GET /api/v1/evidence` (home); `GET /api/v1/evidence/packs` (pack list); `GET /api/v1/evidence/packs/{id}` (pack detail); `GET /api/v1/evidence/proofs/{subjectDigest}` (proof chain); `GET /api/v1/evidence/thread/{id}` (evidence thread); `GET /api/v1/evidence/audit` (unified audit log); `GET /api/v1/evidence/receipts/cvss/{id}` | `EXISTS_COMPAT` | `EvidenceLocker` + `Attestor` | Existing evidence viewer scopes | Evidence adapter family is implemented for home/packs/proofs/audit/receipts plus thread lookup with deterministic ordering and explicit not-found contracts | Routes are validated by `EvidenceAuditEndpointsTests`; trust management remains an Administration owner workflow while evidence APIs stay read-only consumer surfaces | `S00-T05-EVID-01` |
|
||||
| Administration | A0 overview + A1 Identity and Access + A2 Tenant and Branding + A3 Notifications + A4 Usage and Limits + A5 Policy Governance + A6 Trust and Signing + A7 System | `source-of-truth.md 2.2 and 3.8`, `authority-matrix.md A: administration`, `pack-21.md` | `/settings/*` migration targets and new `/administration/*` routes | `GET /api/v1/administration/summary`; `GET /api/v1/administration/identity-access`; `GET /api/v1/administration/tenant-branding`; `GET /api/v1/administration/notifications`; `GET /api/v1/administration/usage-limits`; `GET /api/v1/administration/policy-governance`; `GET /api/v1/administration/trust-signing`; `GET /api/v1/administration/system`; `GET /api/v1/administration/trust-signing/{keys,issuers,certificates,transparency-log}`; `POST /api/v1/administration/trust-signing/keys`; `POST /api/v1/administration/trust-signing/keys/{keyId}/rotate`; `POST /api/v1/administration/trust-signing/keys/{keyId}/revoke`; `POST /api/v1/administration/trust-signing/issuers`; `POST /api/v1/administration/trust-signing/certificates`; `POST /api/v1/administration/trust-signing/certificates/{certificateId}/revoke`; `PUT /api/v1/administration/trust-signing/transparency-log` | `EXISTS_COMPAT` | `Platform` (composition) + `Authority` + `Policy` | `platform.setup.read` for A0/A1/A2/A3/A4/A5/A7 adapters; A6 read routes use `platform.trust.read` (`trust:read`), owner mutations use `platform.trust.write` (`trust:write`) and `platform.trust.admin` (`trust:admin`) | Pack adapters now return deterministic A1-A7 payloads plus `legacyAliases` route-migration metadata for `/settings/*`, `/policy/*`, and `/admin/*`; trust-owner mutation routes persist deterministic state via Platform stores | Adapter surface decouples frontend from legacy prefixes while preserving explicit trust-owner boundaries and admin-grade mutation authorization for keys/issuers/certificates/transparency configuration | `S00-T05-ADM-01` |
|
||||
| Integrations | Integrations taxonomy, hub overview, connector detail, feeds tie-in | `source-of-truth.md 3.7`, `authority-matrix.md A: integrations`, `pack-21.md`, `pack-10.md` | `/settings/integrations/*` and `/integrations/*` (partially) | `GET /api/v1/integrations` (hub list); `GET /api/v1/integrations/{id}` (connector detail); `GET /api/v1/integrations/{id}/health` (health check); `GET /api/v1/integrations/{id}/impact` (impact map); `POST /api/v1/integrations/{id}/test` (test connection) | `EXISTS_COMPAT` | `Integrations` | Existing integration admin scopes | Impact map contract is implemented at `/api/v1/integrations/{id}/impact` with deterministic workflow ordering; list/detail/health/test routes remain compatible for pack-21 integration detail tabs | Endpoint behavior is validated in `IntegrationImpactEndpointsTests`; advisory source ownership split remains handled by `S00-T05-SEC-02` | `S00-T05-INT-01` |
|
||||
| Platform Ops | Data Integrity overview + nightly report + feeds freshness + scan pipeline health + reachability ingest + DLQ + data quality SLOs | `source-of-truth.md 3.6`, `authority-matrix.md A: ops`, `pack-15.md`, `pack-10.md`, `pack-21.md` | `/operations/*` (current) | `GET /api/v1/platform/data-integrity/summary` (overview cards); `GET /api/v1/platform/data-integrity/report` (nightly report); `GET /api/v1/platform/feeds/freshness` (feeds health); `GET /api/v1/platform/scan-pipeline/health`; `GET /api/v1/platform/reachability/ingest-health`; existing DLQ and SLO endpoints | `EXISTS_COMPAT` | `Orchestrator` + `Concelier` + `Scanner` | Existing ops viewer scopes | Platform pack adapters now expose the data-integrity aggregate routes required by Packs 15/21 with deterministic card/report ordering and feed/pipeline/reachability drilldown links | Endpoints and tenant-header validation are covered in `PackAdapterEndpointsTests`; ownership split with Integrations remains explicit per `S00_advisory_sources_spec.md` | `S00-T05-OPS-01` |
|
||||
|
||||
## Completion checklist
|
||||
## Sign-off requirement
|
||||
|
||||
- [ ] Replace all `TBD` values with concrete route and endpoint references.
|
||||
- [ ] Verify one status class per row.
|
||||
- [ ] Add rows for additional active-authority screens discovered during route audit.
|
||||
- [ ] Link each `Action ticket` to a concrete sprint task.
|
||||
Before readiness closure, frontend and backend leads must confirm:
|
||||
- All previously `MISSING_NEW` rows are either shipped or formally deferred with owner/date.
|
||||
- Any `EXISTS_ADAPT` rows (none at this revision) have backend team acknowledgment of planned schema delta.
|
||||
- No active-authority screen remains unclassified.
|
||||
|
||||
Sign-off is captured in `S00_handoff_packet.md`.
|
||||
|
||||
@@ -1,19 +1,64 @@
|
||||
# S00 Handoff Packet
|
||||
# S00 Handoff Packet
|
||||
|
||||
Status: Placeholder (created for sprint planning pointer integrity)
|
||||
Date: 2026-02-18
|
||||
Status: Published (reconciled to reopened 20260219 sprint wave)
|
||||
Date: 2026-02-19
|
||||
Working directory: `docs/modules/ui/v2-rewire`
|
||||
Sprint: `20260218_005`, task `R0-07`
|
||||
|
||||
## Upstream artifacts
|
||||
- `S00_advisory_sources_spec.md`
|
||||
- `S00_nav_rendering_policy.md`
|
||||
- `S00_trust_ownership_transition.md`
|
||||
- `S00_route_deprecation_map.md`
|
||||
- `S00_endpoint_contract_ledger_v1.md`
|
||||
## Purpose
|
||||
|
||||
## Downstream target sprints
|
||||
- `SPRINT_20260218_006_FE_ui_v2_rewire_navigation_shell_route_migration.md`
|
||||
- `SPRINT_20260218_007_FE_ui_v2_rewire_administration_foundation.md`
|
||||
- `SPRINT_20260218_008_FE_ui_v2_rewire_integrations_platform_ops_data_integrity.md`
|
||||
This packet is the authoritative handoff from sprint `20260218_005` (Spec Freeze) to implementation sprints.
|
||||
All frozen decisions are referenced here.
|
||||
|
||||
## Current status
|
||||
- This packet is a planning placeholder and will be expanded when sprint `20260218_005` reaches DONE.
|
||||
Implementation execution for this handoff was the reopened sprint set:
|
||||
|
||||
- `SPRINT_20260219_002` through `SPRINT_20260219_007`
|
||||
- `SPRINT_20260219_008` (backend endpoint + migration dependency closure)
|
||||
- `SPRINT_20260219_015` (Pack-13 promotions contract binding follow-on)
|
||||
|
||||
All completed sprint files from this set are now archived under `docs-archived/implplan/`.
|
||||
|
||||
## Frozen decisions
|
||||
|
||||
| Decision | Document | Key ruling |
|
||||
| --- | --- | --- |
|
||||
| Canonical IA taxonomy and root domain ordering | `source-of-truth.md` sections 2.1 and 2.2 | Seven roots: Dashboard, Release Control, Security and Risk, Evidence and Audit, Integrations, Platform Ops, Administration. Order is fixed. |
|
||||
| Ownership boundaries (Policy, Trust, System, Security Data split) | `source-of-truth.md` section 2.2, `authority-matrix.md` section B | Policy Governance -> Administration. Trust and Signing -> Administration. System -> Administration. Legacy Security Data -> split: connectivity in Integrations/Platform Ops, gating impact in Security and Risk. |
|
||||
| Superseded alternatives (forbidden placements) | `authority-matrix.md` section B; `S00_nav_rendering_policy.md` do-not list | Trust in Evidence, Policy in Release Control, System as top-level root are forbidden. |
|
||||
| Release Control capability rendering policy | `S00_nav_rendering_policy.md` | Releases and Approvals may be direct nav shortcuts under Release Control group; Bundles, Deployments, and Environments stay grouped under Release Control ownership. |
|
||||
| Advisory Sources screen ownership and spec | `S00_advisory_sources_spec.md` | Security and Risk owns decision-impact view. Integrations owns connector config. Platform Ops owns freshness ops. |
|
||||
| Trust and Signing ownership transition and consumer model | `S00_trust_ownership_transition.md` | Administration is sole owner. Evidence and Audit and Security and Risk are consumers with read-only links only. |
|
||||
| Route deprecation map and activation sequence | `S00_route_deprecation_map.md` | Complete v1 -> v2 mapping with per-sprint activation sequence. |
|
||||
| Endpoint contract ledger v1 | `S00_endpoint_contract_ledger_v1.md` | 12 screen domains classified; previously missing rows `S00-T05-RC-01` and `S00-T05-SEC-02` are now reconciled to shipped backend contracts (`EXISTS_COMPAT`). |
|
||||
|
||||
## Downstream target sprints (executed and archived)
|
||||
|
||||
| Sprint | Dependency on S00 decisions | Unblocked after |
|
||||
| --- | --- | --- |
|
||||
| `SPRINT_20260219_002_FE_ui_v2_shell_navigation_and_route_truth` | Nav rendering policy, route deprecation map | `SPRINT_20260219_001` DONE |
|
||||
| `SPRINT_20260219_003_FE_ui_v2_shell_release_control_structure` | Release Control ownership policy, Pack 12/13/14 structure, contract ledger RC rows | `SPRINT_20260219_002` |
|
||||
| `SPRINT_20260219_004_FE_ui_v2_shell_security_and_advisory_sources` | Advisory Sources spec, ownership split, contract ledger SEC rows | `SPRINT_20260219_002` |
|
||||
| `SPRINT_20260219_005_FE_ui_v2_shell_evidence_audit_structure` | Trust transition doc, evidence ownership policy, contract ledger EVID row | `SPRINT_20260219_002` |
|
||||
| `SPRINT_20260219_006_FE_ui_v2_shell_integrations_platform_ops_alignment` | Integrations/Platform Ops taxonomy, security-data split policy | `SPRINT_20260219_002` |
|
||||
| `SPRINT_20260219_007_FE_ui_v2_shell_qa_and_readiness_reverification` | Strict closure gate, ledger reconciliation, readiness publication | `SPRINT_20260219_003` to `SPRINT_20260219_006` |
|
||||
|
||||
## Unresolved risks (carry into implementation)
|
||||
|
||||
| Risk | Severity | Mitigation | Owner sprint |
|
||||
| --- | --- | --- | --- |
|
||||
| Bundle API (`S00-T05-RC-01`) contract drift after implementation | Medium | Keep ledger pinned to implemented `/api/v1/release-control/bundles*` routes and reject path regressions that collide with evidence bundle export namespace. | `SPRINT_20260219_008` + downstream QA |
|
||||
| Advisory Sources cross-service composition drift (`S00-T05-SEC-02`) | Medium | Keep Concelier freshness and Policy impact/conflicts ownership split explicit; verify tenant/scope behavior in readiness reruns. | `SPRINT_20260219_008` + downstream QA |
|
||||
| Trust scope model (`trust:read`, `trust:write`, `trust:admin`) requires Authority alignment | Closed (2026-02-19) | Authority canonical scopes and Platform trust policies are wired; A6 now includes owner mutation routes (`/api/v1/administration/trust-signing/{keys,issuers,certificates,transparency-log}`) with DB backing via migration `046_TrustSigningAdministration.sql`. | `SPRINT_20260219_016` |
|
||||
| Approvals multi-tab fan-out latency (`S00-T05-APR-01`) | Medium | Preserve lazy loading and stale-data behavior in shell and add backend performance verification in follow-on integration work. | `SPRINT_20260219_003` |
|
||||
| Data Integrity aggregate endpoint (`S00-T05-OPS-01`) spans modules | Medium | Keep ownership split explicit in shell and assign backend composition owner before full readiness GO. | `SPRINT_20260219_006` / `SPRINT_20260219_007` |
|
||||
| Legacy alias removal can miss long-tail deep links | Low | Keep redirect map under strict tests and remove aliases only after measured traffic evidence. | `SPRINT_20260219_002` / `SPRINT_20260219_007` |
|
||||
|
||||
## Contract ledger sign-off status
|
||||
|
||||
- Frontend shell sign-off is complete through `SPRINT_20260219_006`.
|
||||
- Backend dependency sign-off for previously unresolved rows (`S00-T05-RC-01`, `S00-T05-SEC-02`) is now complete via `SPRINT_20260219_008` evidence and ledger reconciliation.
|
||||
- Promotions row `S00-T05-RC-02` and Administration row `S00-T05-ADM-01` are fully reconciled to `EXISTS_COMPAT` via `SPRINT_20260219_016` backend contract enrichment evidence.
|
||||
|
||||
## Non-shipped exploratory work
|
||||
|
||||
None.
|
||||
|
||||
@@ -1,25 +1,116 @@
|
||||
# S00 Nav Rendering Policy
|
||||
# S00 Nav Rendering Policy
|
||||
|
||||
Status: Draft (created for sprint planning pointer integrity)
|
||||
Status: Frozen
|
||||
Date: 2026-02-18
|
||||
Working directory: `docs/modules/ui/v2-rewire`
|
||||
Sprint: `20260218_005`, task `R0-03`
|
||||
|
||||
## Policy statement
|
||||
Release Control-owned capabilities may be rendered as direct shortcuts if and only if ownership remains labeled as Release Control in breadcrumbs and headers.
|
||||
|
||||
## Allowed model
|
||||
- Root domains remain canonical.
|
||||
- Shortcuts allowed for `Releases` and `Approvals` when they route to Release Control-owned routes.
|
||||
- `Bundles`, `Deployments`, and `Regions and Environments` remain under Release Control navigation hierarchy.
|
||||
Release Control-owned capabilities may be rendered as direct shortcuts in the sidebar if and only if:
|
||||
1. Ownership is labeled as **Release Control** in breadcrumbs and page headers.
|
||||
2. The canonical routes for those capabilities live under `/release-control/*`.
|
||||
3. The sidebar shortcut links to the canonical route, not an alias.
|
||||
|
||||
This policy prevents mixed rendering where the same screen appears to be owned by two domains.
|
||||
|
||||
## Allowed rendering model
|
||||
|
||||
### Desktop (expanded sidebar)
|
||||
|
||||
```
|
||||
Dashboard
|
||||
Release Control
|
||||
├── Releases [shortcut direct nav allowed]
|
||||
├── Approvals [shortcut direct nav allowed]
|
||||
├── Bundles [nested only — no direct shortcut]
|
||||
├── Deployments [nested only — no direct shortcut]
|
||||
└── Regions & Environments [nested only — no direct shortcut]
|
||||
Security & Risk
|
||||
Evidence & Audit
|
||||
Integrations
|
||||
Platform Ops
|
||||
Administration
|
||||
```
|
||||
|
||||
`Releases` and `Approvals` may appear as direct children under `Release Control` in the sidebar
|
||||
(rather than requiring expand → click).
|
||||
`Bundles`, `Deployments`, and `Regions & Environments` remain nested and require expand.
|
||||
|
||||
### Desktop (collapsed sidebar — icons only)
|
||||
|
||||
- Show icon for Release Control root only.
|
||||
- Tooltip on hover shows "Release Control".
|
||||
- Click navigates to Release Control overview or last active child.
|
||||
- No separate Releases / Approvals icons in collapsed mode.
|
||||
|
||||
### Mobile (navigation drawer)
|
||||
|
||||
- All root domains appear as top-level items in the drawer.
|
||||
- Release Control expands in-place to show child nav items.
|
||||
- `Releases` and `Approvals` may appear as drawer children with Release Control as visible parent.
|
||||
- No Release Control capabilities may appear as top-level drawer items separate from the Release Control group.
|
||||
|
||||
## Breadcrumb rules
|
||||
- Any shortcut route must render breadcrumb prefix `Release Control`.
|
||||
- Header titles use canonical naming; optional compatibility labels may be temporary.
|
||||
|
||||
## Non-allowed model
|
||||
- Dual ownership labels for same screen.
|
||||
- Divergent mobile vs desktop ownership paths.
|
||||
- Legacy settings-first entry as primary owner path.
|
||||
Canonical format: `Root Domain > Capability > [Sub-page]`
|
||||
|
||||
## Route guidance
|
||||
- Use alias redirects for historical direct paths.
|
||||
- Canonical targets must live under final IA route families.
|
||||
| Scenario | Breadcrumb | Notes |
|
||||
| --- | --- | --- |
|
||||
| Releases list | `Release Control > Releases` | No shortcut bypasses ownership label |
|
||||
| Release detail | `Release Control > Releases > RCB-1234` | ID or name appended |
|
||||
| Approvals queue | `Release Control > Approvals` | |
|
||||
| Approval detail | `Release Control > Approvals > APR-5678` | |
|
||||
| Bundle catalog | `Release Control > Bundles` | |
|
||||
| Bundle detail | `Release Control > Bundles > my-bundle` | |
|
||||
| Bundle version detail | `Release Control > Bundles > my-bundle > v1.3.0` | |
|
||||
| Deployments | `Release Control > Deployments` | |
|
||||
| Environments list | `Release Control > Regions & Environments` | |
|
||||
| Environment detail | `Release Control > Regions & Environments > staging-eu` | |
|
||||
|
||||
### Concrete counter-examples (forbidden)
|
||||
|
||||
| Forbidden breadcrumb | Reason |
|
||||
| --- | --- |
|
||||
| `Approvals > APR-5678` | Missing Release Control ownership prefix |
|
||||
| `Releases` (no parent) | Same — no domain context |
|
||||
| `Settings > Policy Governance` | Policy Governance owner is Administration, not Settings |
|
||||
| `Evidence & Audit > Trust & Signing` | Trust & Signing owner is Administration; Evidence may only show a consumer link |
|
||||
|
||||
## Legacy label transition behavior
|
||||
|
||||
Where users know a surface by an old label, show a compact transition label during the migration window defined in `S00_route_deprecation_map.md`.
|
||||
|
||||
Rules:
|
||||
- Transition labels appear only in page headers and sidebar items, not in breadcrumbs.
|
||||
- Format: canonical label is primary; old label appears parenthetically — e.g., `Policy Governance (formerly Policy Studio)`.
|
||||
- Transition labels are removed at sprint 016 cutover unless traffic evidence requires extension.
|
||||
- Canonical labels are always primary; old labels never replace canonical ones.
|
||||
|
||||
Planned transition labels:
|
||||
|
||||
| Canonical label | Transition label (migration window only) | Remove at |
|
||||
| --- | --- | --- |
|
||||
| `Security & Risk` | `Security & Risk (formerly Security)` | Sprint 016 |
|
||||
| `Platform Ops` | `Platform Ops (formerly Operations)` | Sprint 016 |
|
||||
| `Evidence & Audit` | `Evidence & Audit (formerly Evidence)` | Sprint 016 |
|
||||
| `Policy Governance` | `Policy Governance (formerly Policy Studio / Policy)` | Sprint 016 |
|
||||
|
||||
## Explicit do-not list
|
||||
|
||||
The following rendering patterns are forbidden in any sprint implementation:
|
||||
|
||||
1. **Do not** place Release Control capability screens (`Releases`, `Approvals`, `Bundles`, `Deployments`, `Environments`) as root-level sidebar items independent from the `Release Control` group.
|
||||
2. **Do not** display a breadcrumb that omits the canonical root domain prefix.
|
||||
3. **Do not** show different ownership labels on desktop vs. mobile for the same screen.
|
||||
4. **Do not** use legacy root-level nav paths (e.g., `/approvals`, `/releases`) as the canonical nav target — they must redirect to `/release-control/*` canonical targets.
|
||||
5. **Do not** label `Trust & Signing` as owned by Evidence & Audit or Security in any nav or header.
|
||||
6. **Do not** label `Policy Governance` as owned by Release Control in any nav or header.
|
||||
7. **Do not** introduce a new root domain that is not in the canonical 7: Dashboard, Release Control, Security & Risk, Evidence & Audit, Integrations, Platform Ops, Administration.
|
||||
|
||||
## Route alias requirements for migration
|
||||
|
||||
During the alias window, current root-level paths (`/releases`, `/approvals`) must:
|
||||
- Resolve to the canonical `/release-control/releases` and `/release-control/approvals` routes.
|
||||
- Render the canonical breadcrumb (e.g., `Release Control > Releases`) — not an alias-derived breadcrumb.
|
||||
- Not appear as primary nav items in the sidebar; the sidebar must link to canonical paths only.
|
||||
|
||||
@@ -1,26 +1,183 @@
|
||||
# S00 Route Deprecation Map
|
||||
# S00 Route Deprecation Map
|
||||
|
||||
Status: Draft baseline (created for sprint planning pointer integrity)
|
||||
Status: Frozen baseline
|
||||
Date: 2026-02-18
|
||||
Working directory: `docs/modules/ui/v2-rewire`
|
||||
Canonical source: `source-of-truth.md`, `authority-matrix.md`
|
||||
|
||||
## Purpose
|
||||
Baseline mapping for legacy route families to canonical IA targets.
|
||||
|
||||
## Route action values
|
||||
- `keep`
|
||||
- `redirect`
|
||||
- `alias`
|
||||
- `remove-later`
|
||||
Complete route baseline mapping current v1 canonical paths to v2 target IA families.
|
||||
Every major route family must have exactly one migration action.
|
||||
This map governs all implementation in sprints 006 through 016.
|
||||
|
||||
## Baseline mapping examples
|
||||
| Legacy family | Canonical target family | Action |
|
||||
## Route action definitions
|
||||
|
||||
| Action | Meaning |
|
||||
| --- | --- |
|
||||
| `keep` | Path and semantics are unchanged; no migration work required. |
|
||||
| `redirect` | Current path redirects to v2 canonical target; old path is no longer authoritative. |
|
||||
| `alias` | Current path remains active and resolves to the same content as canonical; both paths are valid during the migration window. Planned for removal after cutover. |
|
||||
| `remove-later` | Path is superseded; leave as redirect stub until traffic confirms safety, then remove in sprint 016. |
|
||||
|
||||
## Section 1 — Root domain family migrations
|
||||
|
||||
These are the highest-priority mappings because they affect top-level navigation and all deep links.
|
||||
|
||||
| Current v1 path family | v2 canonical target family | Action | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `/` (control-plane landing) | `/dashboard` | `redirect` | Current Control Plane becomes Dashboard v3 landing. Sprint 012 implements target. |
|
||||
| `/security/*` | `/security-risk/*` | `redirect` + temporary `alias` | High-traffic. Alias `/security/*` during sprint 014 window; remove in sprint 016. |
|
||||
| `/operations/*` | `/platform-ops/*` | `redirect` + temporary `alias` | Ops team bookmarks. Alias during sprint 008 window; remove in sprint 016. |
|
||||
| `/evidence/*` | `/evidence-audit/*` | `redirect` + temporary `alias` | Alias during sprint 015 window; remove in sprint 016. |
|
||||
| `/policy/*` | `/administration/policy-governance/*` | `redirect` | Ownership change. High risk; enforce breadcrumb and ownership labels per nav policy. |
|
||||
| `/settings/*` (admin subset) | `/administration/*` | `redirect` | Split: admin sub-paths go to `/administration/*`; integration sub-paths go to `/integrations/*`. |
|
||||
| `/settings/integrations/*` | `/integrations/*` | `redirect` | Integrations becomes a canonical root domain. |
|
||||
| `/integrations/*` (current shallow root) | `/integrations/*` (v2 canonical root) | `keep` | Route family stays. Sprint 008 expands content and taxonomy. |
|
||||
| `/approvals/*` | `/release-control/approvals/*` | `redirect` + temporary `alias` | Alias `/approvals/*` for operator convenience during cutover; remove in sprint 016. |
|
||||
| `/releases/*` | `/release-control/releases/*` | `redirect` + temporary `alias` | High-traffic operator route. Alias during sprints 010-016 window. |
|
||||
| `/environments/*` | `/release-control/environments/*` | `redirect` | Medium risk. |
|
||||
| `/deployments/*` | `/release-control/deployments/*` | `redirect` | Medium risk. |
|
||||
| `/analytics/*` | `/security-risk/analytics/*` | `redirect` | Analytics is consumed under Security & Risk. |
|
||||
|
||||
## Section 2 — Settings sub-family migrations
|
||||
|
||||
All settings sub-paths have a final canonical owner under Administration or Integrations.
|
||||
|
||||
| Current v1 path | v2 target | Action | Sprint |
|
||||
| --- | --- | --- | --- |
|
||||
| `/settings/admin/users` | `/administration/identity-access/users` | `redirect` | 007 |
|
||||
| `/settings/admin/roles` | `/administration/identity-access/roles` | `redirect` | 007 |
|
||||
| `/settings/admin/tenants` | `/administration/identity-access/tenants` | `redirect` | 007 |
|
||||
| `/settings/admin/clients` | `/administration/identity-access/clients` | `redirect` | 007 |
|
||||
| `/settings/admin/tokens` | `/administration/identity-access/tokens` | `redirect` | 007 |
|
||||
| `/settings/admin/branding` | `/administration/tenant-branding` | `redirect` | 007 |
|
||||
| `/settings/admin/:page` | `/administration/:page` | `redirect` (catch-all) | 007 |
|
||||
| `/settings/trust/*` | `/administration/trust-signing/*` | `redirect` | 007 |
|
||||
| `/settings/notifications/*` | `/administration/notifications/*` | `redirect` | 007 |
|
||||
| `/settings/security-data/trivy` | `/integrations/feeds/trivy` | `redirect` | 008 |
|
||||
| `/settings/sbom-sources/*` | `/integrations/sbom-sources/*` | `redirect` | 008 |
|
||||
| `/settings/workflows/*` | `/administration/system/workflows` | `redirect` | 007 |
|
||||
| `/settings/profile` | `/administration/profile` | `alias` | 007 (keep; `/administration/profile` is canonical) |
|
||||
| `/settings/configuration-pane` | `/administration/system/configuration` | `redirect` | 007 |
|
||||
|
||||
## Section 3 — Evidence & Audit sub-family migrations
|
||||
|
||||
| Current v1 path | v2 target | Action | Sprint |
|
||||
| --- | --- | --- | --- |
|
||||
| `/evidence` | `/evidence-audit` | `redirect` + alias | 015 |
|
||||
| `/evidence/audit` | `/evidence-audit/audit` | `redirect` | 015 |
|
||||
| `/evidence/packs/*` | `/evidence-audit/packs/*` | `redirect` | 015 |
|
||||
| `/evidence/proofs/*` | `/evidence-audit/proofs/*` | `alias` | 015 (permanent convenience alias for external linking) |
|
||||
| `/evidence/change-trace/*` | `/evidence-audit/change-trace/*` | `redirect` | 015 |
|
||||
| `/evidence/receipts/cvss/*` | `/evidence-audit/receipts/cvss/*` | `redirect` | 015 |
|
||||
| `/evidence-thread/*` | `/evidence-audit/thread/*` | `redirect` | 015 |
|
||||
| `/timeline/*` | `/evidence-audit/timeline/*` | `redirect` | 015 |
|
||||
|
||||
## Section 4 — Platform Ops sub-family migrations
|
||||
|
||||
| Current v1 path | v2 target | Action | Sprint |
|
||||
| --- | --- | --- | --- |
|
||||
| `/operations/feeds/*` | `/platform-ops/data-integrity/feeds/*` | `redirect` | 008 |
|
||||
| `/operations/orchestrator/*` | `/platform-ops/orchestrator/*` | `redirect` | 008 |
|
||||
| `/operations/health` | `/platform-ops/health` | `redirect` | 008 |
|
||||
| `/operations/quotas/*` | `/platform-ops/quotas/*` | `redirect` | 008 |
|
||||
| `/operations/slo` | `/platform-ops/data-integrity/slo` | `redirect` | 008 |
|
||||
| `/operations/dead-letter` | `/platform-ops/orchestrator/dead-letter` | `redirect` | 008 |
|
||||
| `/operations/aoc` | `/platform-ops/aoc` | `redirect` | 008 |
|
||||
| `/operations/doctor` | `/platform-ops/doctor` | `redirect` | 008 |
|
||||
| `/operations/offline-kit/*` | `/platform-ops/offline-kit/*` | `redirect` | 008 |
|
||||
| `/operations/agents/*` | `/platform-ops/agents/*` | `redirect` | 008 |
|
||||
| `/operations/scanner/*` | `/platform-ops/scanner/*` | `redirect` | 008 |
|
||||
| `/operations/packs/*` | `/platform-ops/pack-registry/*` | `redirect` | 008 |
|
||||
| `/operations/signals/*` | `/platform-ops/signals/*` | `redirect` | 008 |
|
||||
| `/operations/ai-runs/*` | `/platform-ops/ai-runs/*` | `redirect` | 008 |
|
||||
| `/operations/notifications` | `/administration/notifications` | `redirect` | 007 (ownership change) |
|
||||
| `/operations/status` | `/administration/system/status` | `redirect` | 007 (ownership change) |
|
||||
|
||||
## Section 5 — Release Control sub-family migrations
|
||||
|
||||
| Current v1 path | v2 target | Action | Sprint |
|
||||
| --- | --- | --- | --- |
|
||||
| `/releases` | `/release-control/releases` | `redirect` + alias | 010 |
|
||||
| `/releases/:id` | `/release-control/releases/:id` | `redirect` | 010 |
|
||||
| `/approvals` | `/release-control/approvals` | `redirect` + alias | 011 |
|
||||
| `/approvals/:id` | `/release-control/approvals/:id` | `redirect` | 011 |
|
||||
| `/environments` | `/release-control/environments` | `redirect` | 013 |
|
||||
| `/environments/:id` | `/release-control/environments/:id` | `redirect` | 013 |
|
||||
| `/deployments/*` | `/release-control/deployments/*` | `redirect` | 010 |
|
||||
| (new) `/release-control/bundles/*` | `/release-control/bundles/*` | `new (implemented)` | 20260219_003 |
|
||||
|
||||
## Section 6 — Security & Risk sub-family migrations
|
||||
|
||||
| Current v1 path | v2 target | Action | Sprint |
|
||||
| --- | --- | --- | --- |
|
||||
| `/security` | `/security-risk` | `redirect` + alias | 014 |
|
||||
| `/security/findings/*` | `/security-risk/findings/*` | `redirect` | 014 |
|
||||
| `/security/vulnerabilities/*` | `/security-risk/vulnerabilities/*` | `redirect` | 014 |
|
||||
| `/security/sbom/graph` | `/security-risk/sbom/graph` | `redirect` | 014 |
|
||||
| `/security/lineage/*` | `/security-risk/lineage/*` | `redirect` | 014 |
|
||||
| `/security/reachability` | `/security-risk/reachability` | `redirect` | 014 |
|
||||
| `/security/risk` | `/security-risk/risk` | `redirect` | 014 |
|
||||
| `/security/artifacts/*` | `/security-risk/artifacts/*` | `redirect` | 014 |
|
||||
| `/security/vex/*` | `/security-risk/vex/*` | `redirect` | 014 |
|
||||
| `/security/unknowns` | `/security-risk/unknowns` | `redirect` | 014 |
|
||||
| `/security/patch-map` | `/security-risk/patch-map` | `redirect` | 014 |
|
||||
| `/security/scans/*` | `/security-risk/scans/*` | `redirect` | 014 |
|
||||
| (new) `/security-risk/advisory-sources` | `/security-risk/advisory-sources` | `new (implemented)` | 20260219_004 |
|
||||
|
||||
## Section 7 — Administration sub-family migrations
|
||||
|
||||
| Current v1 path | v2 target | Action | Sprint |
|
||||
| --- | --- | --- | --- |
|
||||
| `/policy/governance` | `/administration/policy-governance` | `redirect` | 007 |
|
||||
| `/policy/exceptions/*` | `/administration/policy-governance/exceptions/*` | `redirect` | 007 |
|
||||
| `/policy/packs/*` | `/administration/policy-governance/packs/*` | `redirect` | 007 |
|
||||
| `/admin/trust/*` | `/administration/trust-signing/*` | `redirect` | 007 |
|
||||
| `/admin/audit` | `/evidence-audit/audit` | `redirect` | 015 |
|
||||
| `/admin/notifications` | `/administration/notifications` | `redirect` | 007 |
|
||||
| `/admin/policy/governance` | `/administration/policy-governance` | `redirect` | 007 |
|
||||
| `/admin/policy/simulation` | `/administration/policy-governance/simulation` | `redirect` | 007 |
|
||||
| `/admin/registries` | `/integrations/registries` | `redirect` | 008 |
|
||||
| `/admin/issuers` | `/administration/trust-signing/issuers` | `redirect` | 007 |
|
||||
| `/admin/vex-hub/*` | `/security-risk/vex/*` | `redirect` | 014 |
|
||||
|
||||
## Section 8 — Remove-later candidates
|
||||
|
||||
Paths that are stale and should be removed after traffic confirmation:
|
||||
|
||||
| Path | Current state | Proposed timeline |
|
||||
| --- | --- | --- |
|
||||
| `/settings/*` admin-owned surfaces | `/administration/*` | `redirect` |
|
||||
| `/settings/security-data` | split to `/integrations/*` and `/security/*` contexts | `redirect` |
|
||||
| `/integrations/*` legacy settings paths | `/integrations/*` canonical root | `alias` |
|
||||
| historical trust routes | `/administration/trust*` | `redirect` |
|
||||
| historical ops aliases | `/operations/*` canonical root | `alias` |
|
||||
| `/home` | Already redirects to `/` | Sprint 016: confirm and remove from app.routes |
|
||||
| `/orchestrator/*` | Already redirects to `/operations/*` → sprint 008 will update to `/platform-ops/*` | Sprint 016 |
|
||||
| `/release-orchestrator/*` | Already redirects to root routes | Sprint 016 |
|
||||
| `/ops/*` | Already redirects to `/operations/*` → sprint 008 will update | Sprint 016 |
|
||||
| `/console/*` | Already redirects to `/settings/*` → sprint 007 will update to `/administration/*` | Sprint 016 |
|
||||
| `/triage/*` | Already redirects to `/security/*` → sprint 014 will update | Sprint 016 |
|
||||
| `/qa/*` (internal workbenches) | Internal tooling; keep as `alias` long-term | No sprint 016 removal |
|
||||
|
||||
## Notes
|
||||
- Full detailed map is completed in sprint `20260218_005` task `R0-05`.
|
||||
- Query and fragment preservation is required for redirect families.
|
||||
## Section 9 — High-risk deep-link mitigation
|
||||
|
||||
| Risk | Mitigation |
|
||||
| --- | --- |
|
||||
| `/approvals/:id` bookmarks (operators) | Alias `/approvals/:id` until sprint 016 cutover confirmation. |
|
||||
| `/releases/:id` links from CI/CD notifications | Alias `/releases/:id` until sprint 016. Log alias traffic before removal. |
|
||||
| `/settings/trust/*` from admin-written runbooks | Update internal runbooks in sprint 007 alongside redirect implementation. |
|
||||
| `/policy/*` ownership migration confuses policy authors | Apply transition labels in sprint 007 alongside redirect; breadcrumb shows `Administration > Policy Governance`. |
|
||||
| `/operations/*` ops-team dashboards with hardcoded links | Announce alias window in release notes. Alias during sprint 008-016 window. |
|
||||
|
||||
## Section 10 — Activation sequence
|
||||
|
||||
| Sprint | Routes activated / aliases established |
|
||||
| --- | --- |
|
||||
| 006 | Root nav + canonical domain route trees; alias existing roots to new domains |
|
||||
| 007 | Administration domain routes; redirect `/settings/admin/*`, `/policy/*`, `/admin/*` paths |
|
||||
| 008 | Integrations and Platform Ops routes; redirect `/operations/*`, `/settings/integrations/*` paths |
|
||||
| 009 | Bundle routes under `/release-control/bundles/*` (new) |
|
||||
| 010 | Release and promotion routes; redirect `/releases/*`, `/deployments/*` |
|
||||
| 011 | Approvals routes; alias `/approvals/*` to `/release-control/approvals/*` |
|
||||
| 012 | Dashboard v3; redirect `/` and update home behavior |
|
||||
| 013 | Environment detail routes; redirect `/environments/*` |
|
||||
| 014 | Security & Risk routes; alias `/security/*` |
|
||||
| 015 | Evidence & Audit routes; alias `/evidence/*` |
|
||||
| 016 | Remove all `alias` and `remove-later` temporary paths; publish cutover confirmation |
|
||||
|
||||
@@ -1,23 +1,96 @@
|
||||
# S00 Trust Ownership Transition
|
||||
# S00 Trust Ownership Transition
|
||||
|
||||
Status: Draft (created for sprint planning pointer integrity)
|
||||
Status: Frozen
|
||||
Date: 2026-02-18
|
||||
Working directory: `docs/modules/ui/v2-rewire`
|
||||
Sprint: `20260218_005`, task `R0-04`
|
||||
|
||||
## Ownership decision
|
||||
`Administration` is the owner domain for Trust and Signing.
|
||||
|
||||
`Administration` is the sole owner domain for Trust and Signing.
|
||||
This is a final decision (Pack 21 overrides Packs 9, 11, and 20 on ownership).
|
||||
|
||||
No other domain may host trust management screens. Trust management includes:
|
||||
- Key lifecycle (rotate, revoke, generate).
|
||||
- Issuer/CA registration and trust configuration.
|
||||
- Certificate lifecycle and renewal.
|
||||
- Transparency log configuration.
|
||||
- Trust scoring policy.
|
||||
|
||||
## Consumer model
|
||||
- `Evidence and Audit` consumes trust state through deep links and contextual trust indicators.
|
||||
- `Security and Risk` consumes issuer/signature confidence as decision context.
|
||||
|
||||
## Route policy
|
||||
- Legacy trust routes redirect or alias to Administration trust pages.
|
||||
- Evidence and Security pages must not host owner-duplicate trust management screens.
|
||||
Two domains consume trust state without owning it:
|
||||
|
||||
## UX policy
|
||||
- Trust actions (rotate, issuer management, cert lifecycle) remain in Administration.
|
||||
- Consumer pages provide contextual links with preserved entity ids.
|
||||
### Evidence & Audit (consumer)
|
||||
- Displays trust indicators on proof chain, attestation, and evidence node views.
|
||||
- Links to Administration > Trust & Signing > [entity] for management actions.
|
||||
- Read-only trust status display only; no management surface.
|
||||
- Preserved entity id must be included in all deep links to Administration trust pages.
|
||||
|
||||
## Risk controls
|
||||
- Prevent duplicate owner surfaces.
|
||||
- Ensure breadcrumbs and page headers always indicate Administration ownership.
|
||||
### Security & Risk (consumer)
|
||||
- Displays issuer/signature confidence as a decision context field in security findings, advisory sources, and approval tabs.
|
||||
- Links to Administration > Trust & Signing > Issuers > [issuerId] when an issuer is referenced in a finding or advisory.
|
||||
- Read-only trust confidence display only; no management surface.
|
||||
|
||||
## Cross-link contract
|
||||
|
||||
All trust management deep links from consumer domains must:
|
||||
1. Navigate to the Administration trust screen that is the canonical owner of the referenced entity.
|
||||
2. Preserve the entity identifier as a route parameter or query parameter.
|
||||
3. Return-navigation must allow the user to return to the originating domain context.
|
||||
|
||||
| Consumer page | Link target | Preserved context |
|
||||
| --- | --- | --- |
|
||||
| Evidence proof chain node (issuer) | `/administration/trust-signing/issuers/:issuerId` | `issuerId` |
|
||||
| Evidence attestation detail (signing key) | `/administration/trust-signing/keys/:keyId` | `keyId` |
|
||||
| Security finding advisory (issuer trust) | `/administration/trust-signing/issuers/:issuerId` | `issuerId` |
|
||||
| Approval detail — trust confidence indicator | `/administration/trust-signing` (overview) | none required |
|
||||
| Security advisory source — signature status | `/administration/trust-signing/issuers` (filtered) | `sourceId` as query param |
|
||||
|
||||
## Alias and deprecation behavior by route family
|
||||
|
||||
| Legacy path | v2 canonical target | Action | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `/admin/trust` | `/administration/trust-signing` | `redirect` | Sprint 007 |
|
||||
| `/admin/trust/keys` | `/administration/trust-signing/keys` | `redirect` | Sprint 007 |
|
||||
| `/admin/trust/issuers` | `/administration/trust-signing/issuers` | `redirect` | Sprint 007 |
|
||||
| `/admin/trust/certs` | `/administration/trust-signing/certificates` | `redirect` | Sprint 007 |
|
||||
| `/admin/trust/:page` | `/administration/trust-signing/:page` | `redirect` (catch-all) | Sprint 007 |
|
||||
| `/admin/issuers` | `/administration/trust-signing/issuers` | `redirect` | Sprint 007 |
|
||||
| `/settings/trust` | `/administration/trust-signing` | `redirect` | Sprint 007 |
|
||||
| `/settings/trust/:page` | `/administration/trust-signing/:page` | `redirect` (catch-all) | Sprint 007 |
|
||||
| `/evidence/trust` | `/administration/trust-signing` | `redirect` | Sprint 015 (if exists) |
|
||||
|
||||
Alias window: trust route aliases are removed at sprint 016 cutover.
|
||||
Legacy `/admin/trust/*` and `/settings/trust/*` paths must not remain as primary navigation targets after sprint 007.
|
||||
|
||||
## Auth scope implications
|
||||
|
||||
| Action | Required scope | Notes |
|
||||
| --- | --- | --- |
|
||||
| View trust overview and key list | `trust:read` | Read-only access; auditors and security reviewers |
|
||||
| View issuer list and trust scoring | `trust:read` | Read access |
|
||||
| Create or update key, rotate key | `trust:write` | Restricted to trust admins |
|
||||
| Revoke key or certificate | `trust:admin` | Highest privilege; requires explicit MFA re-auth recommendation |
|
||||
| Register issuer | `trust:write` | |
|
||||
| Configure transparency log | `trust:admin` | |
|
||||
| View trust state in consumer domains (Evidence, Security) | No additional scope; inherited from existing page access | Consumer pages do not require trust scope to display trust indicators |
|
||||
|
||||
Trust scope constants are now implemented in Authority (`StellaOpsScopes.TrustRead`, `StellaOpsScopes.TrustWrite`, `StellaOpsScopes.TrustAdmin`) and mapped in Platform policy wiring.
|
||||
`/api/v1/administration/trust-signing` now enforces `platform.trust.read` (`trust:read`) and contract row `S00-T05-ADM-01` remains `EXISTS_COMPAT`.
|
||||
|
||||
Trust-owner backend mutation routes are now implemented under Platform Administration A6:
|
||||
- `POST /api/v1/administration/trust-signing/keys` (`platform.trust.write`)
|
||||
- `POST /api/v1/administration/trust-signing/keys/{keyId}/rotate` (`platform.trust.write`)
|
||||
- `POST /api/v1/administration/trust-signing/keys/{keyId}/revoke` (`platform.trust.admin`)
|
||||
- `POST /api/v1/administration/trust-signing/issuers` (`platform.trust.write`)
|
||||
- `POST /api/v1/administration/trust-signing/certificates` (`platform.trust.write`)
|
||||
- `POST /api/v1/administration/trust-signing/certificates/{certificateId}/revoke` (`platform.trust.admin`)
|
||||
- `PUT /api/v1/administration/trust-signing/transparency-log` (`platform.trust.admin`)
|
||||
|
||||
## Non-allowed regressions
|
||||
|
||||
- Evidence & Audit may not host a `Trust Management` section or own a trust key/issuer editing surface.
|
||||
- Security & Risk may not host issuer or key management; only trust confidence indicators are allowed.
|
||||
- Legacy route paths (`/admin/trust/*`, `/settings/trust/*`) may not be kept as primary authoritative routes after sprint 007; they must redirect.
|
||||
- Breadcrumbs on all trust pages must show `Administration > Trust & Signing > ...`, never `Evidence > Trust` or `Security > Trust`.
|
||||
|
||||
189
docs/modules/ui/v2-rewire/S16_release_readiness_package.md
Normal file
189
docs/modules/ui/v2-rewire/S16_release_readiness_package.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# UI V2 Rewire - Release Readiness Package
|
||||
|
||||
**Sprint:** `SPRINT_20260219_007_FE_ui_v2_shell_qa_and_readiness_reverification`
|
||||
**Date:** 2026-02-19
|
||||
**Owner:** Project Manager, QA lead
|
||||
**Status:** PASS (frontend shell structure + backend contract dependency closure + UI endpoint binding)
|
||||
|
||||
---
|
||||
|
||||
## 1. Scope Reverification Summary
|
||||
|
||||
Frontend shell restructuring is implemented for the canonical seven domains and verified against reopened sprint requirements:
|
||||
|
||||
- Dashboard
|
||||
- Release Control
|
||||
- Security and Risk
|
||||
- Evidence and Audit
|
||||
- Integrations
|
||||
- Platform Ops
|
||||
- Administration
|
||||
|
||||
Implemented shell evidence (non-exhaustive):
|
||||
|
||||
- `src/Web/StellaOps.Web/src/app/app.routes.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/layout/app-sidebar/app-sidebar.component.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/routes/release-control.routes.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/routes/security-risk.routes.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/routes/evidence-audit.routes.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/routes/platform-ops.routes.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/routes/administration.routes.ts`
|
||||
|
||||
API binding evidence for previously blocked contract rows:
|
||||
|
||||
- `src/Web/StellaOps.Web/src/app/features/bundles/bundle-organizer.api.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/features/bundles/bundle-catalog.component.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/features/bundles/bundle-detail.component.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/features/bundles/bundle-builder.component.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/features/bundles/bundle-version-detail.component.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/features/security-risk/advisory-sources.api.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/features/security-risk/advisory-sources.component.ts`
|
||||
|
||||
---
|
||||
|
||||
## 2. QA Evidence (Strict Suites)
|
||||
|
||||
### 2.1 Unit and Structural Route Coverage
|
||||
|
||||
Command:
|
||||
|
||||
```bash
|
||||
npm run test -- --watch=false --include src/tests/navigation/nav-route-integrity.spec.ts --include src/tests/navigation/nav-model.spec.ts --include src/tests/navigation/legacy-redirects.spec.ts --include src/tests/release-control/release-control-routes.spec.ts --include src/tests/release-control/release-control-setup.component.spec.ts --include src/tests/release-control/release-control-structure.component.spec.ts --include src/tests/security-risk/security-risk-routes.spec.ts --include src/tests/security-risk/advisory-sources.component.spec.ts --include src/tests/evidence-audit/evidence-audit-routes.spec.ts --include src/tests/evidence-audit/evidence-audit-overview.component.spec.ts --include src/tests/platform-ops/platform-ops-routes.spec.ts --include src/tests/administration/administration-routes.spec.ts
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
- 12 files passed
|
||||
- 167 tests passed
|
||||
- 0 failed
|
||||
|
||||
### 2.2 E2E Shell Reverification
|
||||
|
||||
Command:
|
||||
|
||||
```bash
|
||||
npx playwright test tests/e2e/nav-shell.spec.ts tests/e2e/critical-path.spec.ts tests/e2e/ia-v2-a11y-regression.spec.ts --workers=1
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
- 33 tests passed
|
||||
- 0 failed
|
||||
|
||||
Suites covered:
|
||||
|
||||
- canonical nav shell and redirect behavior
|
||||
- cross-domain critical flows
|
||||
- IA v2 accessibility/regression checks
|
||||
|
||||
---
|
||||
|
||||
## 3. Contract Ledger Reconciliation (QA7-04 + BE8-06)
|
||||
|
||||
Source ledger: `docs/modules/ui/v2-rewire/S00_endpoint_contract_ledger_v1.md`
|
||||
|
||||
Previously blocked backend dependency rows are now implemented and reconciled:
|
||||
|
||||
1. `S00-T05-RC-01` (Bundle catalog/detail/builder endpoint family)
|
||||
- Reclassified from `MISSING_NEW` -> `EXISTS_COMPAT`.
|
||||
- Implemented route family:
|
||||
- `GET /api/v1/release-control/bundles`
|
||||
- `GET /api/v1/release-control/bundles/{bundleId}`
|
||||
- `GET /api/v1/release-control/bundles/{bundleId}/versions`
|
||||
- `GET /api/v1/release-control/bundles/{bundleId}/versions/{versionId}`
|
||||
- `POST /api/v1/release-control/bundles`
|
||||
- `POST /api/v1/release-control/bundles/{bundleId}/versions`
|
||||
- `POST /api/v1/release-control/bundles/{bundleId}/versions/{versionId}/materialize`
|
||||
- Persistence implemented by migration:
|
||||
- `src/Platform/__Libraries/StellaOps.Platform.Database/Migrations/Release/045_ReleaseControlBundleLifecycle.sql`
|
||||
|
||||
2. `S00-T05-SEC-02` (Advisory Sources aggregate endpoint family)
|
||||
- Reclassified from `MISSING_NEW` -> `EXISTS_COMPAT`.
|
||||
- Implemented Concelier freshness routes:
|
||||
- `GET /api/v1/advisory-sources`
|
||||
- `GET /api/v1/advisory-sources/summary`
|
||||
- `GET /api/v1/advisory-sources/{id}/freshness`
|
||||
- Implemented Policy impact/conflict routes:
|
||||
- `GET /api/v1/advisory-sources/{id}/impact`
|
||||
- `GET /api/v1/advisory-sources/{id}/conflicts`
|
||||
- Persistence implemented by migrations:
|
||||
- `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Migrations/004_add_advisory_source_freshness_projection.sql`
|
||||
- `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Migrations/005_add_advisory_source_signature_projection.sql`
|
||||
- `src/Policy/__Libraries/StellaOps.Policy.Persistence/Migrations/005_advisory_source_projection.sql`
|
||||
- Advisory detail diagnostics now include backend contract fields for total/signed/unsigned/signature-failure counts.
|
||||
|
||||
Reconciled truth:
|
||||
|
||||
- Frontend shell conformance: PASS.
|
||||
- Backend dependency closure for UI shell contracts (`S00-T05-RC-01`, `S00-T05-SEC-02`): PASS.
|
||||
- Frontend endpoint-consumption closure for `S00-T05-RC-01` and `S00-T05-SEC-02`: PASS.
|
||||
|
||||
---
|
||||
|
||||
## 4. Decision
|
||||
|
||||
### Readiness outcome
|
||||
|
||||
- Frontend shell gate (sprints 002-006 scope): **PASS**.
|
||||
- Backend dependency gate for full pack closure (`S00-T05-RC-01`, `S00-T05-SEC-02`): **PASS**.
|
||||
|
||||
### Verification evidence (backend dependency closure)
|
||||
|
||||
- `dotnet test src/Platform/__Tests/StellaOps.Platform.WebService.Tests/StellaOps.Platform.WebService.Tests.csproj -v minimal` -> Passed 115/115 (MTP full project run)
|
||||
- `dotnet test src/Policy/__Tests/StellaOps.Policy.Gateway.Tests/StellaOps.Policy.Gateway.Tests.csproj -v minimal` -> Passed 131/131 (MTP full project run)
|
||||
- `src/Platform/__Tests/StellaOps.Platform.WebService.Tests/bin/Debug/net10.0/StellaOps.Platform.WebService.Tests.exe -class "StellaOps.Platform.WebService.Tests.ReleaseControlEndpointsTests"` -> Passed 3/3
|
||||
- `src/Policy/__Tests/StellaOps.Policy.Gateway.Tests/bin/Debug/net10.0/StellaOps.Policy.Gateway.Tests.exe -class "StellaOps.Policy.Gateway.Tests.AdvisorySourceEndpointsTests"` -> Passed 5/5
|
||||
- `src/Concelier/__Tests/StellaOps.Concelier.WebService.Tests/bin/Debug/net10.0/StellaOps.Concelier.WebService.Tests.exe -class "StellaOps.Concelier.WebService.Tests.AdvisorySourceEndpointsTests"` -> Passed 5/5
|
||||
- Note: `dotnet test --filter` remains non-deterministic in this repo under Microsoft Testing Platform (`MTP0001`), so targeted class evidence uses xUnit in-proc runner executables.
|
||||
- `npm run test -- --watch=false --include src/tests/release-control/release-control-structure.component.spec.ts --include src/tests/security-risk/advisory-sources.component.spec.ts` -> Passed 11/11
|
||||
- `npm run build` -> Passed (with existing bundle-size/commonjs warnings unrelated to these endpoint bindings)
|
||||
|
||||
---
|
||||
|
||||
## 5. Sprint Archival Decision
|
||||
|
||||
Backend dependency blockers tracked by this package are cleared.
|
||||
|
||||
Archival for reopened UI sprints can proceed once sprint owners confirm remaining non-endpoint risks (if any) are closed and statuses are updated in their sprint trackers.
|
||||
|
||||
- backend contract blockers are implemented (completed here),
|
||||
- ledger reconciliation remains current with implementation state,
|
||||
- sprint trackers carry explicit QA/closure evidence.
|
||||
|
||||
---
|
||||
|
||||
## 6. Addendum - Promotions Contract Binding (Sprint 015)
|
||||
|
||||
Follow-on sprint `SPRINT_20260219_015_FE_ui_v2_shell_release_control_promotions_pack13_contract_binding` completed pack-13 promotions contract binding work that remained after structural closure.
|
||||
|
||||
Implemented frontend evidence:
|
||||
|
||||
- `src/Web/StellaOps.Web/src/app/features/promotions/promotions-list.component.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/features/promotions/promotion-detail.component.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/features/promotions/create-promotion.component.ts`
|
||||
- `src/Web/StellaOps.Web/src/tests/release-control/release-control-structure.component.spec.ts`
|
||||
|
||||
Validation evidence:
|
||||
|
||||
- `npm run test -- --watch=false --include src/tests/release-control/release-control-structure.component.spec.ts --include src/tests/release-control/release-control-routes.spec.ts` -> Passed 33/33.
|
||||
- `npm run build` -> Passed (existing bundle-size/commonjs warnings unchanged).
|
||||
|
||||
Ledger impact:
|
||||
|
||||
- `S00-T05-RC-02` and `S00-T05-ADM-01` are now `EXISTS_COMPAT` after backend contract enrichment in sprint `20260219_016` (release-control derived-signal contracts + administration A0-A7 adapter routes).
|
||||
- Trust-owner mutation routes (`/api/v1/administration/trust-signing/{keys,issuers,certificates,transparency-log}`) are now shipped with `platform.trust.write` / `platform.trust.admin` mapping and DB backing via `046_TrustSigningAdministration.sql`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Post-Readiness Verification and Archival Update
|
||||
|
||||
Additional verification was executed after reading all `docs/modules/ui/v2-rewire/pack-01.md` through `pack-21.md` to account for higher-pack overrides.
|
||||
|
||||
Updated Playwright evidence:
|
||||
|
||||
- `npx playwright test tests/e2e/nav-shell.spec.ts tests/e2e/critical-path.spec.ts tests/e2e/ia-v2-a11y-regression.spec.ts --workers=1` -> Passed 33/33.
|
||||
- Deterministic advisory-source API fixtures were added to `tests/e2e/critical-path.spec.ts` so ownership-split assertions are validated against stable data.
|
||||
|
||||
Archival update:
|
||||
|
||||
- Completed sprint files were moved from `docs/implplan/` to `docs-archived/implplan/`.
|
||||
Reference in New Issue
Block a user