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

old sprints work, new sprints for exposing functionality via cli, improve code_of_conduct and other agents instructions

Browse Source
This commit is contained in:
master
2026-01-15 18:37:59 +02:00
parent c631bacee2
commit 88a85cdd92
208 changed files with 32271 additions and 2287 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/GOVERNANCE.md
View File

@@ -60,7 +60,6 @@ Approval is recorded via Git forge review or a signed commit trailer
|-----------|------------|
| Technical deadlock | **Maintainer Summit** (recorded & published) |
| Security bug | Follow [Security Policy](SECURITY_POLICY.md) |
| Code of Conduct violation | See `code-of-conduct/CODE_OF_CONDUCT.md` escalation ladder |
---

100
docs/README.md
View File

@@ -1,21 +1,50 @@
# Stella Ops Suite Documentation
**Stella Ops Suite** is a centralized, auditable release control plane for non-Kubernetes container estates. It orchestrates environment promotions, gates releases using reachability-aware security and policy, and produces verifiable evidence for every decision.
**Stella Ops Suite** is a centralized, auditable release control plane for **non‑Kubernetes** container estates. It orchestrates environment promotions, gates releases using reachability-aware security and policy, and produces verifiable evidence for every decision.
The platform combines:
- **Release orchestration** — UI-driven promotion (Dev → Stage → Prod), approvals, policy gates, rollbacks
- **Security decisioning as a gate** — Scan on build, evaluate on release, re-evaluate on CVE updates
- **OCI-digest-first releases** — Immutable digest-based release identity with "what is deployed where" tracking
- **Toolchain-agnostic integrations** — Plug into any SCM, CI, registry, and secrets system
- **Auditability + standards** — Evidence packets, SBOM/VEX/attestation support, deterministic replay
- **Release orchestration** — UI-driven promotion (Dev -> Stage -> Prod), approvals, policy gates, rollbacks, and step-graph execution (sequential/parallel) with per-step logs
- **Security decisioning as a gate** — scan on build, evaluate on release, re-evaluate on vulnerability intel updates
- **OCI-digest-first releases** — immutable digest-based release identity with authoritative "what is deployed where" tracking
- **Toolchain-agnostic integrations** — plug into any SCM, CI, registry, secrets system, and host access method via plugins
- **Auditability + standards** — evidence packets, SBOM/VEX/attestation support, deterministic replay and explainable decisions
---
## Verified vs Unverified Releases
Stella supports two operational modes:
- **Verified releases (recommended):** promotions require Stella evidence for each new digest (SBOM + reachability + policy decision record + approvals where configured). Intended for certifiable security and audit-grade releases.
- **Unverified releases (CD-only):** orchestration is allowed with evidence gates bypassed. Still tracked and logged, but not intended for security certification.
This documentation emphasizes the **verified release** path as the primary product value.
---
## Licensing model (documentation-level summary)
Stella Ops Suite uses **no feature gating** across plans. Licensing limits apply only to:
- **Environments**
- **New digests deep-scanned per month** (evidence-grade analysis of previously unseen OCI digests)
**Deployment targets are not licensed** (unlimited targets; fair use may apply only under abusive automation patterns).
(See your offer/pricing document if present in the repo; commonly stored under `docs/product/`.)
---
## Two Levels of Documentation
- **High-level (canonical):** the curated guides in `docs/*.md`.
- **Detailed (reference):** deep dives under `docs/**` (module dossiers, architecture notes, API contracts/samples, runbooks, schemas). The entry point is `docs/technical/README.md`.
- **High-level (canonical):** curated guides in `docs/*.md`.
- **Detailed (reference):** deep dives under `docs/**` (module dossiers, architecture notes, API contracts/samples, runbooks, schemas). Entry point: `docs/technical/README.md`.
This documentation set is internal and does not keep compatibility stubs for old paths. Content is consolidated to reduce duplication and outdated pages.
---
## Start Here
### Product Understanding
@@ -27,14 +56,18 @@ This documentation set is internal and does not keep compatibility stubs for old
| Feature matrix | [FEATURE_MATRIX.md](FEATURE_MATRIX.md) |
| Product vision | [product/VISION.md](product/VISION.md) |
| Roadmap (priorities + definition of "done") | [ROADMAP.md](ROADMAP.md) |
| Verified release model (concepts + evidence) | [VERIFIED_RELEASES.md](VERIFIED_RELEASES.md) |
### Getting Started
| Goal | Open this |
| --- | --- |
| First run (minimal install) | [quickstart.md](quickstart.md) |
| Run a first scan (CLI) | [quickstart.md](quickstart.md) |
| Run a first verified promotion (Dev -> Stage -> Prod) | [RELEASE_PROCESS.md](releases/RELEASE_PROCESS.md) |
| Ingest advisories (Concelier + CLI) | [CONCELIER_CLI_QUICKSTART.md](CONCELIER_CLI_QUICKSTART.md) |
| Console (Web UI) operator guide | [UI_GUIDE.md](UI_GUIDE.md) |
| Doctor / self-service diagnostics | [DOCTOR_GUIDE.md](doctor/README.md) |
| Offline / air-gap operations | [OFFLINE_KIT.md](OFFLINE_KIT.md) |
### Architecture
@@ -48,16 +81,21 @@ This documentation set is internal and does not keep compatibility stubs for old
| Architecture: data flows | [technical/architecture/data-flows.md](technical/architecture/data-flows.md) |
| Architecture: schema mapping | [technical/architecture/schema-mapping.md](technical/architecture/schema-mapping.md) |
| Release Orchestrator architecture | [modules/release-orchestrator/architecture.md](modules/release-orchestrator/architecture.md) |
| Evidence and attestations | [modules/evidence/README.md](modules/evidence/README.md) |
### Development & Operations
| Goal | Open this |
| --- | --- |
| Engineering rules (determinism, security, docs discipline) | [code-of-conduct/CODE_OF_CONDUCT.md](code-of-conduct/CODE_OF_CONDUCT.md) |
| Testing standards and evidence expectations | [code-of-conduct/TESTING_PRACTICES.md](code-of-conduct/TESTING_PRACTICES.md) |
| Develop plugins/connectors | [PLUGIN_SDK_GUIDE.md](PLUGIN_SDK_GUIDE.md) |
| Security deployment hardening | [SECURITY_HARDENING_GUIDE.md](SECURITY_HARDENING_GUIDE.md) |
| VEX consensus and issuer trust | [VEX_CONSENSUS_GUIDE.md](VEX_CONSENSUS_GUIDE.md) |
| Vulnerability Explorer guide | [VULNERABILITY_EXPLORER_GUIDE.md](VULNERABILITY_EXPLORER_GUIDE.md) |
---
## Detailed Indexes
- **Technical index (everything):** [docs/technical/README.md](/docs/technical/)
@@ -71,45 +109,13 @@ This documentation set is internal and does not keep compatibility stubs for old
- **Benchmarks and fixtures:** [docs/benchmarks/](/docs/benchmarks/), [docs/assets/](/docs/assets/)
- **Product advisories:** [docs/product/advisories/](/docs/product/advisories/)
## Platform Themes
Stella Ops Suite organizes capabilities into themes:
### Existing Themes (Operational)
| Theme | Purpose | Key Modules |
|-------|---------|-------------|
| **INGEST** | Advisory ingestion | Concelier, Advisory-AI |
| **VEXOPS** | VEX document handling | Excititor, VEX Lens, VEX Hub |
| **REASON** | Policy and decisioning | Policy Engine, OPA Runtime |
| **SCANENG** | Scanning and SBOM | Scanner, SBOM Service, Reachability |
| **EVIDENCE** | Evidence and attestation | Evidence Locker, Attestor, Export Center |
| **RUNTIME** | Runtime signals | Signals, Graph, Zastava |
| **JOBCTRL** | Job orchestration | Scheduler, Orchestrator, TaskRunner |
| **OBSERVE** | Observability | Notifier, Telemetry |
| **REPLAY** | Deterministic replay | Replay Engine |
| **DEVEXP** | Developer experience | CLI, Web UI, SDK |
### Planned Themes (Release Orchestration)
| Theme | Purpose | Key Modules |
|-------|---------|-------------|
| **INTHUB** | Integration hub | Integration Manager, Connection Profiles, Connector Runtime |
| **ENVMGR** | Environment management | Environment Manager, Target Registry, Agent Manager |
| **RELMAN** | Release management | Component Registry, Version Manager, Release Manager |
| **WORKFL** | Workflow engine | Workflow Designer, Workflow Engine, Step Executor |
| **PROMOT** | Promotion and approval | Promotion Manager, Approval Gateway, Decision Engine |
| **DEPLOY** | Deployment execution | Deploy Orchestrator, Target Executor, Artifact Generator |
| **AGENTS** | Deployment agents | Agent Core, Docker/Compose/ECS/Nomad agents |
| **PROGDL** | Progressive delivery | A/B Manager, Traffic Router, Canary Controller |
| **RELEVI** | Release evidence | Evidence Collector, Sticker Writer, Audit Exporter |
| **PLUGIN** | Plugin infrastructure | Plugin Registry, Plugin Loader, Plugin SDK |
---
## Design Principles
- **Offline-first**: All core operations work in air-gapped environments
- **Deterministic replay**: Same inputs yield same outputs (stable ordering, canonical hashing)
- **Evidence-linked decisions**: Every decision links to concrete evidence artifacts
- **Digest-first release identity**: Releases are immutable OCI digests, not mutable tags
- **Pluggable everything**: Integrations are plugins; core orchestration is stable
- **No feature gating**: All plans include all features; limits are environments + new digests/day
- **Offline-first**: core operations work in air-gapped environments
- **Deterministic replay**: same inputs yield same outputs (stable ordering, canonical hashing)
- **Evidence-linked decisions**: every verified release decision links to concrete evidence artifacts
- **Digest-first release identity**: releases are immutable OCI digests, not mutable tags
- **Pluggable everything**: integrations are plugins; core orchestration is stable
- **No feature gating**: all plans include all features; licensing limits are environments + new digests deep-scanned per month; deployment targets are not licensed

72
docs/UI_GUIDE.md
View File

@@ -62,12 +62,84 @@ See `docs/VEX_CONSENSUS_GUIDE.md` for the underlying concepts.
See `docs/OFFLINE_KIT.md` for packaging and offline verification workflows.
### Export Evidence Cards (v1.1)
Evidence Cards are single-file exports containing SBOM excerpt, DSSE envelope, and optional Rekor receipt for offline verification.
**To export an Evidence Card:**
1. Open an evidence pack from **Findings** or **Runs** workspace.
2. Click the **Export** dropdown in the pack viewer header.
3. Select **Evidence Card** for full export or **Evidence Card (Compact)** for a smaller file without full SBOM.
4. The browser downloads a `.evidence-card.json` file.
**Evidence Card contents:**
- `cardId`: Unique card identifier
- `version`: Schema version (e.g., "1.0.0")
- `packId`: Source evidence pack ID
- `subject`: Finding/CVE/component metadata
- `envelope`: DSSE signature envelope (when signed)
- `sbomExcerpt`: Relevant SBOM component data (full export only)
- `rekorReceipt`: Sigstore Rekor transparency log receipt (when available)
- `contentDigest`: SHA-256 digest for verification
**Content types:**
- Full: `application/vnd.stellaops.evidence-card+json`
- Compact: `application/vnd.stellaops.evidence-card-compact+json`
See `docs/api/evidence-decision-api.openapi.yaml` for the complete schema.
## Offline / Air-Gap Expectations
- The Console must operate against Offline Kit snapshots (no external lookups required).
- The UI should surface snapshot identity and staleness budgets (feeds, VEX, policy versions).
- Upload/import workflows for Offline Kit bundles should be auditable (who imported what, when).
## Setup Wizard
The Setup Wizard provides a guided interface for initial platform configuration and reconfiguration. It communicates with the Platform backend via `/api/v1/setup/*` endpoints.
### Wizard Features
- **Session-based workflow:** Sessions track progress across steps, enabling resume after interruption.
- **Step validation:** Each step includes Doctor checks that validate configuration before proceeding.
- **Dry-run mode:** Preview configuration changes before applying them.
- **Error handling:** Problem+JSON errors are mapped to user-friendly messages with suggested fixes.
- **Data freshness:** Stale data banners show when cached information may be outdated.
- **Retry support:** Failed operations can be retried with backoff and attempt tracking.
### Wizard Steps
The wizard guides operators through these configuration areas:
| Step | Category | Required | Description |
|------|----------|----------|-------------|
| Database | Infrastructure | Yes | PostgreSQL connection and migrations |
| Cache | Infrastructure | Yes | Valkey/Redis connection |
| Vault | Security | No | HashiCorp Vault, Azure Key Vault, or AWS Secrets Manager |
| Settings Store | Configuration | No | Consul, etcd, or PostgreSQL-backed configuration |
| Registry | Integration | No | Container registry connections |
| Telemetry | Observability | No | OTLP endpoint configuration |
### Using the Wizard
1. Access the Setup Wizard from **Admin > Configuration Wizard** or during first-run.
2. Complete required steps (Database, Cache) before optional integrations.
3. Use **Test Connection** to validate credentials before applying.
4. Review validation checks (Doctor diagnostics) for each step.
5. Use dry-run mode to preview changes before committing.
6. After completion, restart services to apply the configuration.
### Reconfiguration
To modify existing configuration:
- Use `stella setup --reconfigure` (CLI) or **Admin > Configuration Wizard** (UI).
- Individual steps can be reconfigured without re-running the entire wizard.
See `docs/setup/setup-wizard-ux.md` for detailed UX specifications and CLI parity.
## Security and Access
- Authentication is typically OIDC/OAuth2 via Authority; scopes/roles govern write actions.

93
docs/VEX_CONSENSUS_GUIDE.md
View File

@@ -81,6 +81,99 @@ The Console uses these concepts to keep VEX explainable:
See `docs/UI_GUIDE.md` for the operator workflow perspective.
## Anchor-Aware Mode (v1.1)
> **Sprint:** SPRINT_20260112_004_BE_policy_determinization_attested_rules
Anchor-aware mode enforces cryptographic attestation requirements on VEX proofs used for allow decisions.
### VexProofGate Options
| Option | Type | Default | Strict Mode |
|--------|------|---------|-------------|
| `AnchorAwareMode` | bool | `false` | `true` |
| `RequireVexAnchoring` | bool | `false` | `true` |
| `RequireRekorVerification` | bool | `false` | `true` |
| `RequireSignedStatements` | bool | `false` | `true` |
| `RequireProofForFixed` | bool | `false` | `true` |
| `MaxAllowedConflicts` | int | `5` | `0` |
| `MaxProofAgeHours` | int | `168` | `72` |
### Strict Anchor-Aware Preset
For production environments requiring maximum security:
```csharp
var options = VexProofGateOptions.StrictAnchorAware;
// Enables: RequireVexAnchoring, RequireRekorVerification,
// RequireSignedStatements, RequireProofForFixed
// Sets: MinimumConfidenceTier=high, MaxAllowedConflicts=0, MaxProofAgeHours=72
```
### Metadata Keys
When passing VEX proof context through policy evaluation:
| Key | Type | Description |
|-----|------|-------------|
| `vex_proof_anchored` | bool | Whether proof has DSSE anchoring |
| `vex_proof_envelope_digest` | string | DSSE envelope sha256 digest |
| `vex_proof_rekor_verified` | bool | Whether Rekor transparency verified |
| `vex_proof_rekor_log_index` | long | Rekor log index if verified |
### Failure Reasons
| Reason | Description |
|--------|-------------|
| `vex_not_anchored` | VEX proof requires DSSE anchoring but is not anchored |
| `rekor_verification_missing` | VEX proof requires Rekor verification but not verified |
## VEX Change Events
> Sprint: SPRINT_20260112_006_EXCITITOR_vex_change_events
Excititor emits deterministic events when VEX statements change, enabling policy reanalysis.
### Event Types
| Event | Description | Policy Trigger |
|-------|-------------|----------------|
| `vex.statement.added` | New statement ingested | Immediate reanalysis |
| `vex.statement.superseded` | Statement replaced | Immediate reanalysis |
| `vex.statement.conflict` | Status disagreement detected | Queue for review |
| `vex.status.changed` | Effective status changed | Immediate reanalysis |
### Conflict Detection
Conflicts are detected when multiple providers report different statuses for the same vulnerability-product pair:
| Conflict Type | Description |
|---------------|-------------|
| `status_mismatch` | Different status values (e.g., affected vs not_affected) |
| `trust_tie` | Equal trust scores with different recommendations |
| `supersession_conflict` | Disagreement on which statement supersedes |
### Event Ordering
Events follow deterministic ordering:
1. Ordered by timestamp (ascending)
2. Conflict events after related statement events
3. Same-timestamp events sorted by provider ID
### Integration with Policy
Subscribe to VEX events for automatic reanalysis:
```yaml
subscriptions:
- event: vex.statement.*
action: reanalyze
filter:
trustScore: { $gte: 0.7 }
```
See [Excititor Architecture](docs/modules/excititor/architecture.md#33-vex-change-events) for full event schemas.
## Offline / Air-Gap Operation
- VEX observations/linksets are included in Offline Kit snapshots with content hashes and timestamps.

272
docs/api/evidence-decision-api.openapi.yaml
View File

@@ -4,7 +4,8 @@ info:
description: |
REST API for evidence retrieval and decision recording.
Sprint: SPRINT_3602_0001_0001
version: 1.0.0
Updated: SPRINT_20260112_005_BE_evidence_card_api (EVPCARD-BE-002)
version: 1.1.0
license:
name: AGPL-3.0-or-later
url: https://www.gnu.org/licenses/agpl-3.0.html
@@ -196,6 +197,81 @@ paths:
'404':
$ref: '#/components/responses/NotFound'
# Sprint: SPRINT_20260112_005_BE_evidence_card_api (EVPCARD-BE-002)
/evidence-packs/{packId}/export:
get:
operationId: exportEvidencePack
summary: Export evidence pack in various formats
description: |
Exports an evidence pack in the specified format. Supports JSON, signed JSON,
Markdown, HTML, PDF, and evidence-card formats.
**Evidence Card formats** (v1.1):
- `evidence-card`: Full evidence card with SBOM excerpt, DSSE envelope, and Rekor receipt
- `card-compact`: Compact evidence card without full SBOM
tags:
- EvidencePacks
parameters:
- name: packId
in: path
required: true
schema:
type: string
description: Evidence pack identifier
- name: format
in: query
required: false
schema:
type: string
enum: [json, signedjson, markdown, md, html, pdf, evidence-card, evidencecard, card, card-compact, evidencecardcompact]
default: json
description: |
Export format. Format aliases:
- `evidence-card`, `evidencecard`, `card` → Evidence Card
- `card-compact`, `evidencecardcompact` → Compact Evidence Card
responses:
'200':
description: Exported evidence pack
headers:
X-Evidence-Pack-Id:
schema:
type: string
description: Evidence pack identifier
X-Content-Digest:
schema:
type: string
description: SHA-256 content digest of the pack
X-Evidence-Card-Version:
schema:
type: string
description: Evidence card schema version (only for evidence-card formats)
X-Rekor-Log-Index:
schema:
type: integer
format: int64
description: Rekor transparency log index (only for evidence-card formats with Rekor receipt)
content:
application/json:
schema:
$ref: '#/components/schemas/EvidencePackExport'
application/vnd.stellaops.evidence-card+json:
schema:
$ref: '#/components/schemas/EvidenceCard'
text/markdown:
schema:
type: string
text/html:
schema:
type: string
application/pdf:
schema:
type: string
format: binary
'404':
$ref: '#/components/responses/NotFound'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
bearerAuth:
@@ -432,3 +508,197 @@ components:
type: string
instance:
type: string
# Sprint: SPRINT_20260112_005_BE_evidence_card_api (EVPCARD-BE-002)
EvidencePackExport:
type: object
required:
- pack_id
- format
- content_type
- file_name
properties:
pack_id:
type: string
description: Evidence pack identifier
format:
type: string
enum: [json, signedjson, markdown, html, pdf, evidence-card, evidence-card-compact]
description: Export format used
content_type:
type: string
description: MIME content type
file_name:
type: string
description: Suggested filename for download
content_digest:
type: string
description: SHA-256 digest of the content
EvidenceCard:
type: object
description: |
Single-file evidence card packaging SBOM excerpt, DSSE envelope, and Rekor receipt.
Designed for offline verification and audit trail.
required:
- card_id
- version
- pack_id
- created_at
- subject
- envelope
properties:
card_id:
type: string
description: Unique evidence card identifier
version:
type: string
description: Evidence card schema version (e.g., "1.0.0")
pack_id:
type: string
description: Source evidence pack identifier
created_at:
type: string
format: date-time
description: Card creation timestamp (ISO 8601 UTC)
subject:
$ref: '#/components/schemas/EvidenceCardSubject'
envelope:
$ref: '#/components/schemas/DsseEnvelope'
sbom_excerpt:
$ref: '#/components/schemas/SbomExcerpt'
rekor_receipt:
$ref: '#/components/schemas/RekorReceipt'
content_digest:
type: string
description: SHA-256 digest of canonical card content
EvidenceCardSubject:
type: object
required:
- type
properties:
type:
type: string
enum: [finding, cve, component, image, policy, custom]
finding_id:
type: string
cve_id:
type: string
component:
type: string
description: Component PURL
image_digest:
type: string
DsseEnvelope:
type: object
description: Dead Simple Signing Envelope (DSSE) per https://github.com/secure-systems-lab/dsse
required:
- payload_type
- payload
- signatures
properties:
payload_type:
type: string
description: Media type of the payload
payload:
type: string
format: byte
description: Base64-encoded payload
signatures:
type: array
items:
$ref: '#/components/schemas/DsseSignature'
DsseSignature:
type: object
required:
- sig
properties:
keyid:
type: string
description: Key identifier
sig:
type: string
format: byte
description: Base64-encoded signature
SbomExcerpt:
type: object
description: Relevant excerpt from the SBOM for the evidence subject
properties:
format:
type: string
enum: [spdx-2.2, spdx-2.3, cyclonedx-1.5, cyclonedx-1.6]
component_name:
type: string
component_version:
type: string
component_purl:
type: string
licenses:
type: array
items:
type: string
vulnerabilities:
type: array
items:
type: string
RekorReceipt:
type: object
description: Sigstore Rekor transparency log receipt for offline verification
required:
- log_index
- log_id
- integrated_time
properties:
log_index:
type: integer
format: int64
description: Rekor log index
log_id:
type: string
description: Rekor log ID (base64-encoded SHA-256 of public key)
integrated_time:
type: integer
format: int64
description: Unix timestamp when entry was integrated
inclusion_proof:
$ref: '#/components/schemas/InclusionProof'
inclusion_promise:
$ref: '#/components/schemas/SignedEntryTimestamp'
InclusionProof:
type: object
description: Merkle tree inclusion proof for log entry
properties:
log_index:
type: integer
format: int64
root_hash:
type: string
format: byte
tree_size:
type: integer
format: int64
hashes:
type: array
items:
type: string
format: byte
SignedEntryTimestamp:
type: object
description: Signed Entry Timestamp (SET) from Rekor
properties:
log_id:
type: string
format: byte
integrated_time:
type: integer
format: int64
signature:
type: string
format: byte

105
docs/api/findings-scoring.md
View File

@@ -112,6 +112,111 @@ Content-Type: application/json
}
```
### Attested-Reduction Mode (v1.1)
When attested-reduction scoring is enabled on the policy, the response includes additional fields for cryptographic attestation metadata and reduction profile information.
**Extended Response (200 OK) with Reduction Mode:**
```json
{
"findingId": "CVE-2024-1234@pkg:deb/debian/curl@7.64.0-4",
"score": 0,
"bucket": "Watchlist",
"inputs": { "rch": 0.00, "rts": 0.00, "bkp": 1.00, "xpl": 0.30, "src": 0.90, "mit": 1.00 },
"weights": { "rch": 0.30, "rts": 0.25, "bkp": 0.15, "xpl": 0.15, "src": 0.10, "mit": 0.10 },
"flags": ["anchored-vex", "vendor-na", "attested-reduction"],
"explanations": [
"Anchored VEX statement: not_affected - score reduced to 0"
],
"caps": { "speculativeCap": false, "notAffectedCap": false, "runtimeFloor": false },
"policyDigest": "sha256:reduction123...",
"calculatedAt": "2026-01-15T14:30:00Z",
"cachedUntil": "2026-01-15T15:30:00Z",
"fromCache": false,
"reductionProfile": {
"enabled": true,
"mode": "aggressive",
"profileId": "attested-verified",
"maxReductionPercent": 100,
"requireVexAnchoring": true,
"requireRekorVerification": true
},
"hardFail": false,
"shortCircuitReason": "anchored_vex_not_affected",
"anchor": {
"anchored": true,
"envelopeDigest": "sha256:abc123def456...",
"predicateType": "https://stellaops.io/attestation/vex/v1",
"rekorLogIndex": 12345678,
"rekorEntryId": "24296fb24b8ad77a7e...",
"scope": "finding",
"verified": true,
"attestedAt": "2026-01-14T10:00:00Z"
}
}
```
### Attested-Reduction Fields
| Field | Type | Description |
|-------|------|-------------|
| `reductionProfile` | object | Reduction profile configuration (when enabled) |
| `reductionProfile.enabled` | boolean | Whether attested-reduction is active |
| `reductionProfile.mode` | string | `"aggressive"` or `"conservative"` |
| `reductionProfile.profileId` | string | Profile identifier for audit trail |
| `reductionProfile.maxReductionPercent` | integer | Maximum score reduction allowed (0-100) |
| `reductionProfile.requireVexAnchoring` | boolean | Whether VEX must be anchored to qualify |
| `reductionProfile.requireRekorVerification` | boolean | Whether Rekor verification is required |
| `hardFail` | boolean | `true` if anchored evidence confirms active exploitation |
| `shortCircuitReason` | string | Reason for short-circuit (if score was short-circuited) |
| `anchor` | object | Primary evidence anchor metadata (if available) |
### Short-Circuit Reasons
| Reason | Score Effect | Condition |
|--------|--------------|-----------|
| `anchored_vex_not_affected` | Score = 0 | Verified VEX not_affected/fixed attestation |
| `anchored_affected_runtime_confirmed` | Score = 100 (hard fail) | Anchored VEX affected + anchored runtime confirms vulnerability |
### Evidence Anchor Fields
| Field | Type | Description |
|-------|------|-------------|
| `anchor.anchored` | boolean | Whether evidence has cryptographic attestation |
| `anchor.envelopeDigest` | string | DSSE envelope digest (sha256 hex) |
| `anchor.predicateType` | string | Attestation predicate type URL |
| `anchor.rekorLogIndex` | integer | Sigstore Rekor transparency log index |
| `anchor.rekorEntryId` | string | Rekor entry UUID |
| `anchor.scope` | string | Attestation scope (finding, package, image) |
| `anchor.verified` | boolean | Whether attestation signature was verified |
| `anchor.attestedAt` | string | ISO-8601 attestation timestamp |
### Hard-Fail Response Example
When anchored evidence confirms active exploitation:
```json
{
"findingId": "CVE-2024-9999@pkg:npm/critical@1.0.0",
"score": 100,
"bucket": "ActNow",
"flags": ["anchored-vex", "anchored-runtime", "hard-fail", "attested-reduction"],
"explanations": [
"Anchored VEX affected + runtime confirmed vulnerable path - hard fail"
],
"hardFail": true,
"shortCircuitReason": "anchored_affected_runtime_confirmed",
"reductionProfile": {
"enabled": true,
"mode": "aggressive",
"profileId": "attested-verified",
"maxReductionPercent": 100,
"requireVexAnchoring": true,
"requireRekorVerification": true
}
}
```
### Score Buckets
| Bucket | Score Range | Action |

26
docs/api/triage-export-api-reference.md
View File

@@ -282,6 +282,32 @@ else
fi
```
## Evidence Card Format (v1.1)
For single-file evidence exports with offline verification support, use the Evidence Pack API's evidence-card format:
```
GET /v1/evidence-packs/{packId}/export?format=evidence-card
```
### Formats
| Format | Content-Type | Description |
|--------|--------------|-------------|
| `evidence-card` | `application/vnd.stellaops.evidence-card+json` | Full evidence card with SBOM excerpt, DSSE envelope, and Rekor receipt |
| `card-compact` | `application/vnd.stellaops.evidence-card-compact+json` | Compact card without full SBOM |
### Response Headers
| Header | Description |
|--------|-------------|
| `X-Evidence-Pack-Id` | Pack identifier |
| `X-Content-Digest` | SHA-256 content digest |
| `X-Evidence-Card-Version` | Schema version (e.g., "1.0.0") |
| `X-Rekor-Log-Index` | Rekor transparency log index (when available) |
See [Evidence Decision API](./evidence-decision-api.openapi.yaml) for complete schema.
## See Also
- [Evidence Bundle Format Specification](../modules/cli/guides/commands/evidence-bundle-format.md)

260
docs/architecture/integrations.md Normal file
View File

@@ -0,0 +1,260 @@
# Integrations Architecture
## Overview
The Integrations module provides a unified catalog for external service connections including SCM providers (GitHub, GitLab, Bitbucket), container registries (Harbor, ECR, GCR, ACR), CI systems, and runtime hosts. It implements a plugin-based architecture for extensibility while maintaining consistent security and observability patterns.
## Architecture Diagram
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Integrations Module │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ WebService Host │ │ Plugin Loader │ │
│ │ (ASP.NET Core) │────│ (DI Registration) │ │
│ └──────────┬───────────┘ └──────────┬───────────┘ │
│ │ │ │
│ ┌──────────▼───────────────────────────▼───────────┐ │
│ │ Integration Catalog │ │
│ │ - Registration CRUD │ │
│ │ - Health Polling │ │
│ │ - Test Connection │ │
│ └──────────┬───────────────────────────────────────┘ │
│ │ │
│ ┌──────────▼───────────────────────────────────────┐ │
│ │ Plugin Contracts │ │
│ │ - IIntegrationConnectorPlugin │ │
│ │ - IScmAnnotationClient │ │
│ │ - IRegistryConnector │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────▼───────────────────────────────────────┐ │
│ │ Provider Plugins │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ GitHub │ │ GitLab │ │ Harbor │ │ ECR │ │ │
│ │ │ App │ │ │ │ │ │ │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ GCR │ │ ACR │ │InMemory │ │ │
│ │ │ │ │ │ │ (test) │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
## Core Components
### Integration Catalog
The central registry for all external service connections:
- **Registration**: Store connection configuration with encrypted credentials
- **Health Monitoring**: Periodic health checks with status tracking
- **Test Connection**: On-demand connectivity verification
- **Lifecycle Events**: Emit events for Scheduler/Signals integration
### Plugin System
Extensible plugin architecture for provider support:
```csharp
public interface IIntegrationConnectorPlugin : IAvailabilityPlugin
{
IntegrationType Type { get; }
IntegrationProvider Provider { get; }
Task<TestConnectionResult> TestConnectionAsync(IntegrationConfig config, CancellationToken ct);
Task<HealthCheckResult> CheckHealthAsync(IntegrationConfig config, CancellationToken ct);
}
```
### SCM Annotation Client
Interface for PR/MR comments and status checks:
```csharp
public interface IScmAnnotationClient
{
Task<ScmOperationResult<ScmCommentResponse>> PostCommentAsync(
ScmCommentRequest request, CancellationToken ct);
Task<ScmOperationResult<ScmStatusResponse>> PostStatusAsync(
ScmStatusRequest request, CancellationToken ct);
Task<ScmOperationResult<ScmCheckRunResponse>> CreateCheckRunAsync(
ScmCheckRunRequest request, CancellationToken ct);
}
```
## SCM Annotation Architecture
### Comment and Status Flow
```
┌────────────┐ ┌─────────────┐ ┌────────────────┐ ┌──────────┐
│ Scanner │────▶│ Integrations│────▶│ SCM Annotation │────▶│ GitHub/ │
│ Service │ │ Service │ │ Client │ │ GitLab │
└────────────┘ └─────────────┘ └────────────────┘ └──────────┘
│ │
│ ┌─────────────────┐ │
└────────▶│ Annotation │◀───────────┘
│ Payload Builder │
└─────────────────┘
```
### Supported Operations
| Operation | GitHub | GitLab |
|-----------|--------|--------|
| PR/MR Comment | Issue comment / Review comment | MR Note / Discussion |
| Commit Status | Commit status API | Commit status API |
| Check Run | Checks API with annotations | Pipeline status (emulated) |
| Inline Annotation | Check run annotation | MR discussion on line |
### Payload Models
#### Comment Request
```csharp
public record ScmCommentRequest
{
public required string Owner { get; init; }
public required string Repository { get; init; }
public required int PullRequestNumber { get; init; }
public required string Body { get; init; }
public string? CommentId { get; init; } // For updates
public bool UpdateExisting { get; init; } = true;
}
```
#### Status Request
```csharp
public record ScmStatusRequest
{
public required string Owner { get; init; }
public required string Repository { get; init; }
public required string CommitSha { get; init; }
public required ScmStatusState State { get; init; }
public required string Context { get; init; }
public string? Description { get; init; }
public string? TargetUrl { get; init; }
}
public enum ScmStatusState
{
Pending,
Success,
Failure,
Error
}
```
#### Check Run Request
```csharp
public record ScmCheckRunRequest
{
public required string Owner { get; init; }
public required string Repository { get; init; }
public required string HeadSha { get; init; }
public required string Name { get; init; }
public string? Status { get; init; } // queued, in_progress, completed
public string? Conclusion { get; init; } // success, failure, neutral, etc.
public string? Summary { get; init; }
public string? Text { get; init; }
public IReadOnlyList<ScmCheckRunAnnotation>? Annotations { get; init; }
}
public record ScmCheckRunAnnotation
{
public required string Path { get; init; }
public required int StartLine { get; init; }
public required int EndLine { get; init; }
public required string AnnotationLevel { get; init; } // notice, warning, failure
public required string Message { get; init; }
public string? Title { get; init; }
}
```
## Provider Implementations
### GitHub App Plugin
- Uses GitHub App authentication (installation tokens)
- Supports: PR comments, commit status, check runs with annotations
- Handles rate limiting with exponential backoff
- Maps StellaOps severity to GitHub annotation levels
### GitLab Plugin
- Uses Personal Access Token or CI Job Token
- Supports: MR notes, discussions, commit status
- Emulates check runs via pipeline status + MR discussions
- Handles project path encoding for API calls
## Security
### Credential Management
- All credentials stored as AuthRef URIs
- Resolved at runtime through Authority
- No plaintext secrets in configuration
- Audit trail for credential access
### Token Scopes
| Provider | Required Scopes |
|----------|----------------|
| GitHub App | `checks:write`, `pull_requests:write`, `statuses:write` |
| GitLab | `api`, `read_repository`, `write_repository` |
## Error Handling
### Offline-Safe Operations
All SCM operations return `ScmOperationResult<T>`:
```csharp
public record ScmOperationResult<T>
{
public bool Success { get; init; }
public T? Result { get; init; }
public string? ErrorMessage { get; init; }
public bool IsTransient { get; init; } // Retry-able
public bool SkippedOffline { get; init; }
}
```
### Retry Policy
- Transient errors (rate limit, network): Retry with exponential backoff
- Permanent errors (auth, not found): Fail immediately
- Offline mode: Skip with warning, log payload for manual posting
## Observability
### Metrics
| Metric | Type | Labels |
|--------|------|--------|
| `integrations_health_check_total` | Counter | `provider`, `status` |
| `integrations_test_connection_duration_seconds` | Histogram | `provider` |
| `scm_annotation_total` | Counter | `provider`, `operation`, `status` |
| `scm_annotation_duration_seconds` | Histogram | `provider`, `operation` |
### Structured Logging
All operations log with:
- `integrationId`: Registration ID
- `provider`: GitHub, GitLab, etc.
- `operation`: comment, status, check_run
- `prNumber` / `commitSha`: Target reference
## Related Documentation
- [CI/CD Gate Flow](../../flows/10-cicd-gate-flow.md)
- [Authority Architecture](../authority/architecture.md)
- [Scanner Architecture](../scanner/architecture.md)

693
docs/code-of-conduct/CODE_OF_CONDUCT.md
View File

@@ -1,88 +1,679 @@
# Stella Ops Code of Conduct
*Contributor Covenant v2.1 + project‑specific escalation paths*
> We pledge to make participation in the Stella Ops community a
> harassment‑free experience for everyone, regardless of age, body size,
> disability, ethnicity, sex characteristics, gender identity and expression,
> level of experience, education, socio‑economic status, nationality,
> personal appearance, race, religion, or sexual identity and orientation.
# StellaOps Engineering Code of Conduct
*Technical excellence + safe for change = best-in-class product*
---
## 0 · Our standard
## 0 · Mission and Values
This project adopts the
[**Contributor Covenant v2.1**](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)
with the additions and clarifications listed below.
If anything here conflicts with the upstream covenant, *our additions win*.
**StellaOps** is a sovereign, self-hostable release control plane delivering reproducible, auditable, and secure software releases for non-Kubernetes container estates. We are committed to building a **best-in-class product that is safe for change** — where every contribution improves quality, maintainability, and security without regression.
### Our Engineering Pledge
We pledge to uphold:
1. **Technical Excellence** — Code that is deterministic, testable, and production-ready from day one.
2. **Safety for Change** — Comprehensive testing, minimal surprise, and zero tolerance for silent failures.
3. **Security by Design** — Input validation, least privilege, cryptographic correctness, and defense in depth.
4. **Maintainability First** — Clear contracts, minimal coupling, immutable outputs, and self-documenting code.
5. **Transparency and Auditability** — Every decision, every release, every change is traceable and reproducible.
This document codifies the **technical standards** all contributors must follow. Behavioral expectations are covered in [COMMUNITY_CONDUCT.md](./COMMUNITY_CONDUCT.md).
---
## 1 · Scope
## 1 · Core Principles
| Applies to | Examples |
|------------|----------|
| **All official spaces** | Repos under `git.stella-ops.org/stella-ops.org/*`, Matrix rooms (`#stellaops:*`), issue trackers, pull‑request reviews, community calls, and any event officially sponsored by Stella Ops |
| **Unofficial spaces that impact the project** | Public social‑media posts that target or harass community members, coordinated harassment campaigns, doxxing, etc. |
### 1.1 Quality
Quality is not negotiable. Every line of code must be:
- **Correct** — Does what it claims, handles errors gracefully, fails fast when assumptions break
- **Tested** — Unit tests for logic, integration tests for contracts, E2E tests for workflows
- **Deterministic** — Same inputs always produce same outputs; no hidden state, no timing dependencies
- **Observable** — Logs structured events, emits metrics, traces execution paths
- **Documented** — Self-explanatory code; architecture decisions recorded; APIs have examples
**Why it matters**: Quality debt compounds. A shortcut today becomes a week-long incident tomorrow. We build for the long term.
---
## 2 · Reporting a violation ☎️
### 1.2 Maintainability
| Channel | When to use |
|---------|-------------|
| `conduct@stella-ops.org` (PGP key [`keys/#pgp`](https://stella-ops.org/keys/#pgp)) | **Primary, confidential** – anything from micro‑aggressions to serious harassment |
| Matrix `/msg @coc-bot:libera.chat` | Quick, in‑chat nudge for minor issues |
| Public issue with label `coc` | Transparency preferred and **you feel safe** doing so |
Code is read 10x more than it's written. Optimize for the next engineer:
We aim to acknowledge **within 48 hours** (business days, UTC).
- **Clear intent** — Names reveal purpose; functions do one thing; classes have single responsibilities
- **Low coupling** — Modules depend on interfaces, not implementations; changes propagate predictably
- **High cohesion** — Related logic lives together; unrelated logic stays separate
- **Minimal surprise** — Standard patterns over clever tricks; explicit over implicit
- **Refactorable** — Tests enable confident changes; abstractions hide complexity without obscuring behavior
**Why it matters**: Unmaintainable code slows velocity to zero. We build systems that evolve, not calcify.
---
## 3 · Incident handlers 🛡️
### 1.3 Security
| Name | Role | Alt‑contact |
|------|------|-------------|
| Alice Doe (`@alice`) | Core Maintainer • Security WG | `+1‑555‑0123` |
| Bob Ng (`@bob`) | UI Maintainer • Community lead | `+1‑555‑0456` |
Security is a design constraint, not a feature:
If **any** handler is the subject of a complaint, skip them and contact another
handler directly or email `conduct@stella-ops.org` only.
- **Defense in depth** — Multiple layers: input validation, authorization, cryptographic verification, audit trails
- **Least privilege** — Services run with minimal permissions; users see only what they need
- **Fail secure** — Errors deny access; missing config stops startup; invalid crypto rejects requests
- **Cryptographic correctness** — Use vetted libraries; never roll your own crypto; verify all signatures
- **Supply chain integrity** — Pin dependencies; scan for vulnerabilities; generate SBOMs; issue VEX statements
- **Auditability** — Every action logged; every release signed; every decision traceable
**Why it matters**: Security failures destroy trust. We protect our users' infrastructure and their reputation.
---
## 4 · Enforcement ladder ⚖️
## 2 · Scope and Authority
1. **Private coaches / mediation** – first attempt to resolve misunderstandings.
2. **Warning** – written, includes corrective actions & cooling‑off period.
3. **Temporary exclusion** – mute (chat), read‑only (repo) for *N* days.
4. **Permanent ban** – removal from all official spaces + revocation of roles.
This Code of Conduct applies to:
All decisions are documented **privately** (for confidentiality) but a summary
is published quarterly in the “Community Health” report.
- All code contributions (C#, TypeScript, Angular, SQL, Dockerfiles, Helm charts, CI/CD pipelines)
- All documentation (architecture, API references, runbooks, sprint files)
- All testing artifacts (unit, integration, E2E, performance, security tests)
- All infrastructure-as-code (Terraform, Ansible, Compose, Kubernetes manifests)
**Authority**: This document supersedes informal guidance. When in conflict with external standards, StellaOps rules win. Module-specific `AGENTS.md` files may impose stricter requirements but cannot relax the rules defined here.
---
## 5 · Appeals 🔄
## 3 · Mandatory Reading
A sanctioned individual may appeal **once** by emailing
`appeals@stella-ops.org` within **14 days** of the decision.
Appeals are reviewed by **three maintainers not involved in the original case**
and resolved within 30 days.
Before contributing to any module, you **must** read and understand:
1. **This document** — The engineering code of conduct (you're reading it now)
2. [docs/README.md](../README.md) — Project overview and navigation
3. [docs/07_HIGH_LEVEL_ARCHITECTURE.md](../07_HIGH_LEVEL_ARCHITECTURE.md) — System architecture
4. [docs/modules/platform/architecture-overview.md](../modules/platform/architecture-overview.md) — Platform design
5. [TESTING_PRACTICES.md](./TESTING_PRACTICES.md) — Testing requirements and evidence standards
6. The relevant module's architecture dossier (`docs/modules/<module>/architecture.md`)
7. The module's `AGENTS.md` if present (e.g., `src/Scanner/AGENTS.md`)
**Enforcement**: Pull requests that violate documented architecture or module-specific constraints will be rejected with a reference to the violated document.
---
## 6 · No‑retaliation policy 🛑
## 4 · Code Quality Standards
Retaliation against reporters **will not be tolerated** and results in
immediate progression to **Step 4** of the enforcement ladder.
### 3.1 Compiler Discipline
**Rule**: All projects must enable `TreatWarningsAsErrors`.
```xml
<!-- In .csproj or Directory.Build.props -->
<PropertyGroup>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
```
**Rationale**: Warnings mask regressions and code quality drift. Zero-warning builds are mandatory.
---
## 7 · Attribution & licence 📜
### 3.2 Determinism: Time, IDs, and Randomness
* Text adapted from Contributor Covenant v2.1 –
Copyright © 2014‑2024 Contributor Covenant Contributors
Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
**Rule**: Never use `DateTime.UtcNow`, `DateTimeOffset.UtcNow`, `Guid.NewGuid()`, or `Random.Shared` directly in production code.
**Required**: Inject `TimeProvider` and `IGuidGenerator` abstractions.
```csharp
// ❌ BAD - nondeterministic, untestable
public class BadService
{
public Record CreateRecord() => new Record
{
Id = Guid.NewGuid(),
CreatedAt = DateTimeOffset.UtcNow
};
}
// ✅ GOOD - injectable, testable, deterministic
public class GoodService(TimeProvider timeProvider, IGuidGenerator guidGenerator)
{
public Record CreateRecord() => new Record
{
Id = guidGenerator.NewGuid(),
CreatedAt = timeProvider.GetUtcNow()
};
}
```
**Rationale**: Deterministic outputs enable reproducible builds, reliable tests, and cryptographic verification. Nondeterministic code breaks evidence chains.
---
### 3.3 Culture-Invariant Parsing and Formatting
**Rule**: Always use `CultureInfo.InvariantCulture` for parsing and formatting dates, numbers, percentages, and any string that will be persisted, hashed, or compared.
```csharp
// ❌ BAD - culture-sensitive, locale-dependent
var value = double.Parse(input);
var formatted = percentage.ToString("P2");
// ✅ GOOD - culture-invariant, deterministic
var value = double.Parse(input, CultureInfo.InvariantCulture);
var formatted = percentage.ToString("P2", CultureInfo.InvariantCulture);
```
**Rationale**: Current culture causes nondeterministic behavior across environments. All outputs must be reproducible regardless of locale.
---
### 3.4 ASCII-Only Output
**Rule**: Use ASCII-only characters in comments, output strings, and log messages. No mojibake (`ƒ?`), Unicode glyphs (`✓`, `→`, `バ`), or box-drawing characters.
```csharp
// ❌ BAD - non-ASCII glyphs
Console.WriteLine("✓ Success → proceeding");
// ✅ GOOD - ASCII only
Console.WriteLine("[OK] Success - proceeding");
```
**Exceptions**: When Unicode is **required** (e.g., internationalized user messages), use explicit escapes (`\uXXXX`) and document the rationale.
**Rationale**: Non-ASCII characters break in constrained environments (containers, SSH, logs). ASCII ensures universal readability.
---
### 3.5 Immutable Collection Returns
**Rule**: Public APIs must return `IReadOnlyList<T>`, `ImmutableArray<T>`, or defensive copies. Never expose mutable backing stores.
```csharp
// ❌ BAD - exposes mutable backing store
public class BadRegistry
{
private readonly List<string> _scopes = new();
public List<string> Scopes => _scopes; // Callers can mutate!
}
// ✅ GOOD - immutable return
public class GoodRegistry
{
private readonly List<string> _scopes = new();
public IReadOnlyList<string> Scopes => _scopes.AsReadOnly();
}
```
**Rationale**: Mutable returns create hidden coupling and race conditions. Immutability is a safety contract.
---
### 3.6 No Silent Stubs
**Rule**: Placeholder code must throw `NotImplementedException` or return an explicit error status. Never return success from unimplemented paths.
```csharp
// ❌ BAD - silent stub masks missing implementation
public async Task<Result> ProcessAsync()
{
// TODO: implement later
return Result.Success(); // Ships broken feature!
}
// ✅ GOOD - explicit failure
public async Task<Result> ProcessAsync()
{
throw new NotImplementedException("ProcessAsync not yet implemented. See SPRINT_20251218_001_BE_ReleasePromotion.md");
}
```
**Rationale**: Silent stubs ship broken features. Explicit failures prevent production incidents.
---
### 3.7 CancellationToken Propagation
**Rule**: Always propagate `CancellationToken` through async call chains. Never use `CancellationToken.None` in production code.
```csharp
// ❌ BAD - ignores cancellation
public async Task ProcessAsync(CancellationToken ct)
{
await _repository.SaveAsync(data, CancellationToken.None); // Wrong!
await Task.Delay(1000); // Missing ct
}
// ✅ GOOD - propagates cancellation
public async Task ProcessAsync(CancellationToken ct)
{
await _repository.SaveAsync(data, ct);
await Task.Delay(1000, ct);
}
```
**Rationale**: Proper cancellation prevents resource leaks and enables graceful shutdown.
---
### 3.8 HttpClient via IHttpClientFactory
**Rule**: Never instantiate `HttpClient` directly. Use `IHttpClientFactory` with configured timeouts and retry policies.
```csharp
// ❌ BAD - direct instantiation
public class BadService
{
public async Task FetchAsync()
{
using var client = new HttpClient(); // Socket exhaustion risk
await client.GetAsync(url);
}
}
// ✅ GOOD - factory with resilience
public class GoodService(IHttpClientFactory httpClientFactory)
{
public async Task FetchAsync()
{
var client = httpClientFactory.CreateClient("MyApi");
await client.GetAsync(url);
}
}
// Registration with timeout/retry
services.AddHttpClient("MyApi")
.ConfigureHttpClient(c => c.Timeout = TimeSpan.FromSeconds(30))
.AddStandardResilienceHandler();
```
**Rationale**: Direct `HttpClient` creation causes socket exhaustion. Factories enable connection pooling and resilience patterns.
---
### 3.9 Bounded Caches with Eviction
**Rule**: Do not use `ConcurrentDictionary` or `Dictionary` for caching without eviction policies.
```csharp
// ❌ BAD - unbounded growth
private readonly ConcurrentDictionary<string, CacheEntry> _cache = new();
public void Add(string key, CacheEntry entry)
{
_cache[key] = entry; // Never evicts, memory grows forever
}
// ✅ GOOD - bounded with eviction
private readonly MemoryCache _cache = new(new MemoryCacheOptions
{
SizeLimit = 10_000
});
public void Add(string key, CacheEntry entry)
{
_cache.Set(key, entry, new MemoryCacheEntryOptions
{
Size = 1,
SlidingExpiration = TimeSpan.FromMinutes(30)
});
}
```
**Rationale**: Unbounded caches cause memory exhaustion in long-running services. Bounded caches with TTL/LRU eviction are mandatory.
---
### 3.10 Options Validation at Startup
**Rule**: Use `ValidateDataAnnotations()` and `ValidateOnStart()` for all options classes. Implement `IValidateOptions<T>` for complex validation.
```csharp
// ❌ BAD - no validation until runtime failure
services.Configure<MyOptions>(config.GetSection("My"));
// ✅ GOOD - validated at startup
services.AddOptions<MyOptions>()
.Bind(config.GetSection("My"))
.ValidateDataAnnotations()
.ValidateOnStart();
```
**Rationale**: All required config must be validated at startup, not at first use. Fail fast prevents runtime surprises.
---
## 5 · Cryptographic and Security Standards
### 4.1 DSSE PAE Consistency
**Rule**: Use one spec-compliant DSSE PAE helper (`StellaOps.Attestation.DsseHelper`) across the codebase. Never reimplement PAE encoding.
```csharp
// ❌ BAD - custom PAE implementation
var pae = $"DSSEv1 {payloadType.Length} {payloadType} {payload.Length} ";
// ✅ GOOD - use shared helper
var pae = DsseHelper.ComputePreAuthenticationEncoding(payloadType, payload);
```
**Rationale**: DSSE v1 requires ASCII decimal lengths and space separators. Reimplementations introduce cryptographic vulnerabilities.
---
### 4.2 RFC 8785 JSON Canonicalization
**Rule**: Use a shared RFC 8785-compliant JSON canonicalizer for digest/signature inputs. Do not use `UnsafeRelaxedJsonEscaping` or `CamelCase` naming for canonical outputs.
```csharp
// ❌ BAD - non-canonical JSON
var json = JsonSerializer.Serialize(obj, new JsonSerializerOptions
{
Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
PropertyNamingPolicy = JsonNamingPolicy.CamelCase
});
// ✅ GOOD - use shared canonicalizer
var canonicalJson = CanonicalJsonSerializer.Serialize(obj);
var digest = ComputeDigest(canonicalJson);
```
**Rationale**: RFC 8785 ensures deterministic JSON serialization. Non-canonical JSON breaks signature verification.
---
### 4.3 DateTimeOffset for PostgreSQL timestamptz
**Rule**: PostgreSQL `timestamptz` columns must be read via `reader.GetFieldValue<DateTimeOffset>()`, not `reader.GetDateTime()`.
```csharp
// ❌ BAD - loses offset information
var createdAt = reader.GetDateTime(reader.GetOrdinal("created_at"));
// ✅ GOOD - preserves offset
var createdAt = reader.GetFieldValue<DateTimeOffset>(reader.GetOrdinal("created_at"));
```
**Rationale**: `GetDateTime()` loses offset information and causes UTC/local confusion. All timestamps must be stored and retrieved as UTC `DateTimeOffset`.
---
### 4.4 Explicit CLI Options for Paths
**Rule**: Do not derive repository root from `AppContext.BaseDirectory` with parent directory walks. Use explicit CLI options (`--repo-root`) or environment variables.
```csharp
// ❌ BAD - fragile parent walks
var repoRoot = Path.GetFullPath(Path.Combine(
AppContext.BaseDirectory, "..", "..", "..", ".."));
// ✅ GOOD - explicit option with fallback
[Option("--repo-root", Description = "Repository root path")]
public string? RepoRoot { get; set; }
public string GetRepoRoot() =>
RepoRoot ?? Environment.GetEnvironmentVariable("STELLAOPS_REPO_ROOT")
?? throw new InvalidOperationException("Repository root not specified. Use --repo-root or set STELLAOPS_REPO_ROOT.");
```
**Rationale**: Parent walks break in containerized and CI environments. Explicit paths are mandatory.
---
## 6 · Testing Requirements
**All code contributions must include tests.** See [TESTING_PRACTICES.md](./TESTING_PRACTICES.md) for comprehensive guidance.
### 5.1 Test Project Requirements
**Rule**: All production libraries/services must have a corresponding `*.Tests` project covering:
- (a) Happy paths
- (b) Error/edge cases
- (c) Determinism
- (d) Serialization round-trips
```
src/
Scanner/
__Libraries/
StellaOps.Scanner.Core/
__Tests/
StellaOps.Scanner.Core.Tests/ <-- Required
```
---
### 5.2 Test Categorization
**Rule**: Tag tests correctly:
- `[Trait("Category", "Unit")]` for pure unit tests
- `[Trait("Category", "Integration")]` for tests requiring databases, containers, or network
```csharp
// ❌ BAD - integration test marked as unit
public class UserRepositoryTests // Uses Testcontainers/Postgres
{
[Fact] // Missing category
public async Task Save_PersistsUser() { ... }
}
// ✅ GOOD - correctly categorized
[Trait("Category", "Integration")]
public class UserRepositoryTests
{
[Fact]
public async Task Save_PersistsUser() { ... }
}
[Trait("Category", "Unit")]
public class UserValidatorTests
{
[Fact]
public void Validate_EmptyEmail_ReturnsFalse() { ... }
}
```
**Rationale**: Unit tests must run fast and offline. Integration tests require infrastructure. Mixing categories breaks CI pipelines.
---
### 5.3 Test Production Code, Not Reimplementations
**Rule**: Test helpers must call production code, not reimplement algorithms.
```csharp
// ❌ BAD - test reimplements production logic
[Fact]
public void Merkle_ComputesCorrectRoot()
{
var root = TestMerkleHelper.ComputeRoot(leaves); // Drift risk!
Assert.Equal(expected, root);
}
// ✅ GOOD - test exercises production code
[Fact]
public void Merkle_ComputesCorrectRoot()
{
var root = MerkleTreeBuilder.ComputeRoot(leaves);
Assert.Equal(expected, root);
}
```
**Rationale**: Reimplementations in tests cause test/production drift. Only mock I/O and network boundaries.
---
### 5.4 Offline and Deterministic Tests
**Rule**: All tests must run without network access. Use:
- UTC timestamps
- Fixed seeds
- `CultureInfo.InvariantCulture`
- Injected `TimeProvider` and `IGuidGenerator`
**Rationale**: Network-dependent tests are flaky and break in air-gapped environments. Deterministic tests are reproducible.
---
## 7 · Architecture and Design Principles
### 6.1 SOLID Principles
All service and library code must follow:
1. **Single Responsibility Principle (SRP)** — One class, one reason to change
2. **Open/Closed Principle (OCP)** — Open for extension, closed for modification
3. **Liskov Substitution Principle (LSP)** — Subtypes must be substitutable for base types
4. **Interface Segregation Principle (ISP)** — Clients should not depend on interfaces they don't use
5. **Dependency Inversion Principle (DIP)** — Depend on abstractions, not concretions
---
### 6.2 Directory Ownership
**Rule**: Work only inside the module's directory defined by the sprint's "Working directory". Cross-module edits require explicit approval and documentation.
**Example**:
- Sprint scope: `src/Scanner/`
- Allowed: Edits to `StellaOps.Scanner.*` projects
- Forbidden: Edits to `src/Concelier/` without explicit approval
**Rationale**: Directory boundaries enforce module isolation and prevent unintended coupling.
---
### 6.3 No Backup Files in Source
**Rule**: Add backup patterns to `.gitignore` and remove stray artifacts during code review.
```gitignore
*.Backup.tmp
*.bak
*.orig
*~
```
**Rationale**: Backup files pollute the repository and create confusion.
---
## 8 · Documentation Standards
### 7.1 Required Documentation
Every change must update:
1. **Module architecture docs** (`docs/modules/<module>/architecture.md`)
2. **API references** (`docs/api/`)
3. **Sprint files** (`docs/implplan/SPRINT_*.md`)
4. **Risk/airgap docs** if applicable (`docs/risk/`, `docs/airgap/`)
---
### 7.2 Sprint File Discipline
**Rule**: Always update task status in `docs/implplan/SPRINT_*.md`:
- `TODO` → `DOING` → `DONE` / `BLOCKED`
Sprint files are the single source of truth for project state.
---
## 9 · Security and Hardening
### 8.1 Input Validation
**Rule**: All external inputs (HTTP requests, CLI arguments, file uploads, database queries) must be validated and sanitized.
**Required**:
- Use `[Required]`, `[Range]`, `[RegularExpression]` attributes on DTOs
- Implement `IValidateOptions<T>` for complex validation
- Reject unexpected inputs with explicit error messages
---
### 8.2 Least Privilege
**Rule**: Services must run with minimal permissions:
- Database users: read-only where possible
- File system: restrict to required directories
- Network: allowlist remote hosts
---
### 8.3 Dependency Security
**Enforcement**: PRs introducing new dependencies must include:
- SBOM entry
- VEX statement if vulnerabilities exist
- Justification for the dependency
---
## 10 · Technology Stack Compliance
### 9.1 Mandatory Technologies
- **Runtime**: .NET 10 (`net10.0`) with latest C# preview features
- **Frontend**: Angular v17
- **Database**: PostgreSQL ≥16
- **Testing**: xUnit, Testcontainers, Moq
- **NuGet**: Standard feeds configured in `nuget.config`. Always strive to use latest stable verison of dependencies. Never specify versions on nugets on the csproj files. Use src/Directory.Packages.props to specify versions.
---
### 9.2 Naming Conventions
- Module projects: `StellaOps.<ModuleName>`
- Libraries: `StellaOps.<LibraryName>`
- Tests: `StellaOps.<ModuleName>.Tests`
---
## 11 · Enforcement and Compliance
### 10.1 Pull Request Requirements
All PRs must:
1. Pass all unit and integration tests
2. Pass determinism checks
3. Include test coverage for new code
4. Update relevant documentation
5. Follow sprint file discipline
6. Pass security scans (no high/critical CVEs)
---
### 10.2 Rejection Criteria
PRs will be **rejected** if they:
- Violate any rule in this document
- Introduce compiler warnings
- Fail tests
- Lack required documentation
- Contain silent stubs or nondeterministic code
---
### 10.3 Continuous Improvement
This document is a **living standard**. Contributors are encouraged to:
- Propose improvements via PRs
- Document new patterns in module-specific `AGENTS.md` files
- Share lessons learned in sprint retrospectives
---
## 12 · Attribution and License
This Code of Conduct incorporates engineering standards from:
- **AGENTS.md** — Autonomous engineering workflows
- **CLAUDE.md** — Claude Code integration guidance
- **TESTING_PRACTICES.md** — Testing and evidence standards
Copyright © 2025 StellaOps Contributors
Licensed under [AGPL-3.0-or-later](../../LICENSE)
---
**Last updated**: 2026-01-15
**Next review**: 2026-04-15

88
docs/code-of-conduct/COMMUNITY_CONDUCT.md Normal file
View File

@@ -0,0 +1,88 @@
# Stella Ops Code of Conduct
*Contributor Covenant v2.1 + project‑specific escalation paths*
> We pledge to make participation in the Stella Ops community a
> harassment‑free experience for everyone, regardless of age, body size,
> disability, ethnicity, sex characteristics, gender identity and expression,
> level of experience, education, socio‑economic status, nationality,
> personal appearance, race, religion, or sexual identity and orientation.
---
## 0 · Our standard
This project adopts the
[**Contributor Covenant v2.1**](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)
with the additions and clarifications listed below.
If anything here conflicts with the upstream covenant, *our additions win*.
---
## 1 · Scope
| Applies to | Examples |
|------------|----------|
| **All official spaces** | Repos under `git.stella-ops.org/stella-ops.org/*`, Matrix rooms (`#stellaops:*`), issue trackers, pull‑request reviews, community calls, and any event officially sponsored by Stella Ops |
| **Unofficial spaces that impact the project** | Public social‑media posts that target or harass community members, coordinated harassment campaigns, doxxing, etc. |
---
## 2 · Reporting a violation ☎️
| Channel | When to use |
|---------|-------------|
| `conduct@stella-ops.org` (PGP key [`keys/#pgp`](https://stella-ops.org/keys/#pgp)) | **Primary, confidential** – anything from micro‑aggressions to serious harassment |
| Matrix `/msg @coc-bot:libera.chat` | Quick, in‑chat nudge for minor issues |
| Public issue with label `coc` | Transparency preferred and **you feel safe** doing so |
We aim to acknowledge **within 48 hours** (business days, UTC).
---
## 3 · Incident handlers 🛡️
| Name | Role | Alt‑contact |
|------|------|-------------|
| Alice Doe (`@alice`) | Core Maintainer • Security WG | `+1‑555‑0123` |
| Bob Ng (`@bob`) | UI Maintainer • Community lead | `+1‑555‑0456` |
If **any** handler is the subject of a complaint, skip them and contact another
handler directly or email `conduct@stella-ops.org` only.
---
## 4 · Enforcement ladder ⚖️
1. **Private coaches / mediation** – first attempt to resolve misunderstandings.
2. **Warning** – written, includes corrective actions & cooling‑off period.
3. **Temporary exclusion** – mute (chat), read‑only (repo) for *N* days.
4. **Permanent ban** – removal from all official spaces + revocation of roles.
All decisions are documented **privately** (for confidentiality) but a summary
is published quarterly in the “Community Health” report.
---
## 5 · Appeals 🔄
A sanctioned individual may appeal **once** by emailing
`appeals@stella-ops.org` within **14 days** of the decision.
Appeals are reviewed by **three maintainers not involved in the original case**
and resolved within 30 days.
---
## 6 · No‑retaliation policy 🛑
Retaliation against reporters **will not be tolerated** and results in
immediate progression to **Step 4** of the enforcement ladder.
---
## 7 · Attribution & licence 📜
* Text adapted from Contributor Covenant v2.1 –
Copyright © 2014‑2024 Contributor Covenant Contributors
Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
---

320
docs/compliance/COMPLIANCE_READINESS_TRACKER.md Normal file
View File

@@ -0,0 +1,320 @@
# Compliance Readiness Tracker
**Version**: 1.0.0
**Created**: 2026-01-15
**Last Updated**: 2026-01-15
**Status**: Active
This document tracks implementation progress for the 7-Item Compliance Readiness Checklist for regulated customer deployments.
## Executive Summary
| Item | Description | Coverage | Status | Target |
|------|-------------|----------|--------|--------|
| 1 | Attestation caching (offline) | 75% | In Progress | Demo Ready |
| 2 | Offline RBAC & break-glass | 60% | In Progress | Demo Ready |
| 3 | Signed SBOM archives | 55% | In Progress | Demo Ready |
| 4 | HSM / key escrow | 50% | In Progress | RFP Ready |
| 5 | Local Rekor mirrors | 60% | In Progress | RFP Ready |
| 6 | Offline policy engine | 80% | In Progress | RFP Ready |
| 7 | Upgrade & evidence migration | 45% | In Progress | Audit Ready |
## Sprint Allocation
### Phase 1: Demo Blockers (016)
Target: Features needed for 10-minute compliance demo.
| Sprint | Module | Description | Status |
|--------|--------|-------------|--------|
| [016_CLI_attest_verify_offline](../implplan/SPRINT_20260112_016_CLI_attest_verify_offline.md) | CLI | Offline attestation verification CLI | TODO |
| [016_CLI_sbom_verify_offline](../implplan/SPRINT_20260112_016_CLI_sbom_verify_offline.md) | CLI | Offline SBOM verification CLI | TODO |
| [016_SCANNER_signed_sbom_archive_spec](../implplan/SPRINT_20260112_016_SCANNER_signed_sbom_archive_spec.md) | Scanner | Signed SBOM archive format | TODO |
| [016_DOCS_blue_green_deployment](../implplan/SPRINT_20260112_016_DOCS_blue_green_deployment.md) | Docs | Blue/green deployment guide | TODO |
### Phase 2: RFP Compliance (017)
Target: Features needed to pass RFP security questionnaires.
| Sprint | Module | Description | Status |
|--------|--------|-------------|--------|
| [017_CRYPTO_pkcs11_hsm_implementation](../implplan/SPRINT_20260112_017_CRYPTO_pkcs11_hsm_implementation.md) | Crypto | PKCS#11 HSM implementation | TODO |
| [017_ATTESTOR_periodic_rekor_sync](../implplan/SPRINT_20260112_017_ATTESTOR_periodic_rekor_sync.md) | Attestor | Periodic Rekor checkpoint sync | TODO |
| [017_ATTESTOR_checkpoint_divergence_detection](../implplan/SPRINT_20260112_017_ATTESTOR_checkpoint_divergence_detection.md) | Attestor | Checkpoint divergence detection | TODO |
| [017_POLICY_cvss_threshold_gate](../implplan/SPRINT_20260112_017_POLICY_cvss_threshold_gate.md) | Policy | CVSS threshold policy gate | TODO |
| [017_POLICY_sbom_presence_gate](../implplan/SPRINT_20260112_017_POLICY_sbom_presence_gate.md) | Policy | SBOM presence policy gate | TODO |
| [017_POLICY_signature_required_gate](../implplan/SPRINT_20260112_017_POLICY_signature_required_gate.md) | Policy | Signature required policy gate | TODO |
### Phase 3: Audit Readiness (018)
Target: Features needed to pass security audits.
| Sprint | Module | Description | Status |
|--------|--------|-------------|--------|
| [018_SIGNER_dual_control_ceremonies](../implplan/SPRINT_20260112_018_SIGNER_dual_control_ceremonies.md) | Signer | Dual-control signing ceremonies | TODO |
| [018_CRYPTO_key_escrow_shamir](../implplan/SPRINT_20260112_018_CRYPTO_key_escrow_shamir.md) | Crypto | Key escrow with Shamir | TODO |
| [018_AUTH_local_rbac_fallback](../implplan/SPRINT_20260112_018_AUTH_local_rbac_fallback.md) | Authority | Local RBAC policy fallback | TODO |
| [018_EVIDENCE_reindex_tooling](../implplan/SPRINT_20260112_018_EVIDENCE_reindex_tooling.md) | Evidence | Evidence re-index tooling | TODO |
| [018_DOCS_upgrade_runbook_evidence_continuity](../implplan/SPRINT_20260112_018_DOCS_upgrade_runbook_evidence_continuity.md) | Docs | Upgrade runbook with evidence | TODO |
## Detailed Item Status
### Item 1: Attestation Caching (Offline)
**Why it matters**: Regulated shops can't reach public Sigstore/Rekor during audits.
| Requirement | Implementation | Status | Sprint |
|-------------|---------------|--------|--------|
| DSSE caching | `TrustVerdictCache`, `CachedAttestorVerificationService` | DONE | Existing |
| Transparency proofs | `RekorOfflineReceiptVerifier` | DONE | Existing |
| Exportable bundles | `EvidencePortableBundleService` | DONE | Existing |
| Hash manifest | `EvidenceBundleManifest` | DONE | Existing |
| Offline CLI verify | `stella attest verify --offline` | TODO | 016_CLI |
| Bundle test fixtures | Golden test fixtures | TODO | 016_CLI |
| VERIFY.md generation | Bundled verification script | TODO | 016_SCANNER |
**Proof Artifacts**:
- [ ] Demo verifying image on laptop with Wi-Fi off
- [ ] SHA-256 match + signature chain report
### Item 2: Offline RBAC & Break-Glass
**Why it matters**: No cloud IdP during outages/air-gap. Auditors want least-privilege and emergency access trails.
| Requirement | Implementation | Status | Sprint |
|-------------|---------------|--------|--------|
| Incident mode tokens | `obs:incident` scope | DONE | Existing |
| 5-minute freshness | `auth_time` claim validation | DONE | Existing |
| Reason codes | `incident_reason` claim | DONE | Existing |
| Audit logging | `/authority/audit/incident` endpoint | DONE | Existing |
| Local file policy | `FileBasedPolicyStore` | TODO | 018_AUTH |
| Break-glass account | Bootstrap bypass account | TODO | 018_AUTH |
| Auto-revocation | Session timeout enforcement | TODO | 018_AUTH |
**Proof Artifacts**:
- [ ] RBAC matrix (roles -> verbs -> resources)
- [ ] Audit log showing break-glass entry/exit
### Item 3: Signed SBOM Archives (Immutable)
**Why it matters**: SBOMs must be tamper-evident and tied to exact build inputs.
| Requirement | Implementation | Status | Sprint |
|-------------|---------------|--------|--------|
| CycloneDX/SPDX | `SbomExportService` | DONE | Existing |
| DSSE signing | `SignerPipeline` | DONE | Existing |
| Archive format | Signed SBOM archive spec | TODO | 016_SCANNER |
| Tool versions | `metadata.json` in archive | TODO | 016_SCANNER |
| Source hashes | Scanner image digest capture | TODO | 016_SCANNER |
| One-click verify | `stella sbom verify` CLI | TODO | 016_CLI |
| RFC 3161 TSA | TSA integration | DEFERRED | Future |
**Proof Artifacts**:
- [ ] One-click "Verify SBOM" checking signature, timestamps, content hashes
### Item 4: HSM / Key Escrow Patterns
**Why it matters**: Key custody is a governance hotspot.
| Requirement | Implementation | Status | Sprint |
|-------------|---------------|--------|--------|
| PKCS#11 support | `HsmPlugin` architecture | PARTIAL | Existing |
| AWS/GCP KMS | `AwsKmsClient`, `GcpKmsClient` | DONE | Existing |
| Key rotation | `KeyRotationService` | DONE | Existing |
| PKCS#11 impl | `Pkcs11HsmClient` with Interop | TODO | 017_CRYPTO |
| Dual-control | M-of-N ceremonies | TODO | 018_SIGNER |
| Key escrow | Shamir secret sharing | TODO | 018_CRYPTO |
| HSM runbook | Setup and config guide | TODO | 017_CRYPTO |
**Proof Artifacts**:
- [ ] Config targeting HSM slot
- [ ] Simulated key rotation with attestation continuity
### Item 5: Local Rekor (Transparency) Mirrors
**Why it matters**: Auditors want inclusion proofs even when offline.
| Requirement | Implementation | Status | Sprint |
|-------------|---------------|--------|--------|
| Tile verification | `IRekorTileClient`, `HttpRekorTileClient` | DONE | Existing |
| Checkpoint verify | `CheckpointSignatureVerifier` | DONE | Existing |
| Offline receipts | `RekorOfflineReceiptVerifier` | DONE | Existing |
| Periodic sync | `RekorSyncBackgroundService` | TODO | 017_ATTESTOR |
| Checkpoint store | `PostgresRekorCheckpointStore` | TODO | 017_ATTESTOR |
| Divergence detect | Root mismatch alarms | TODO | 017_ATTESTOR |
**Proof Artifacts**:
- [ ] Verify inclusion proof against local checkpoint without internet
- [ ] Mismatch alarm if roots diverge
### Item 6: Offline Policy Engine (OPA/Conftest-class)
**Why it matters**: Gates must hold when the network doesn't.
| Requirement | Implementation | Status | Sprint |
|-------------|---------------|--------|--------|
| Policy bundles | `PolicyBundle` with versioning | DONE | Existing |
| Sealed mode | `SealedModeService` | DONE | Existing |
| VEX gates | `VexProofGate`, `VexTrustGate` | DONE | Existing |
| Unknowns gate | `UnknownsBudgetGate` | DONE | Existing |
| Evidence gates | `EvidenceFreshnessGate`, etc. | DONE | Existing |
| CVSS gate | `CvssThresholdGate` | TODO | 017_POLICY |
| SBOM gate | `SbomPresenceGate` | TODO | 017_POLICY |
| Signature gate | `SignatureRequiredGate` | TODO | 017_POLICY |
**Proof Artifacts**:
- [ ] Local policy pack on sample image showing fail
- [ ] Compliant pass after adding VEX exception with justification
### Item 7: Upgrade & Evidence-Migration Paths
**Why it matters**: "Can we upgrade without invalidating proofs?" is a top blocker.
| Requirement | Implementation | Status | Sprint |
|-------------|---------------|--------|--------|
| DB migrations | Forward-only strategy | DONE | Existing |
| Evidence bundles | Merkle roots in manifests | DONE | Existing |
| Backup/restore | Per-module procedures | DONE | Existing |
| Blue/green docs | Deployment guide | TODO | 016_DOCS |
| Upgrade runbook | Step-by-step procedures | TODO | 018_DOCS |
| Re-index tools | `stella evidence reindex` | TODO | 018_EVIDENCE |
| Root cross-ref | Old/new root mapping | TODO | 018_EVIDENCE |
**Proof Artifacts**:
- [ ] Staged upgrade in test namespace
- [ ] Before/after verification reports
- [ ] Unchanged artifact digests
## Documentation Deliverables
| Document | Path | Status |
|----------|------|--------|
| Blue/Green Deployment | [docs/operations/blue-green-deployment.md](../operations/blue-green-deployment.md) | DONE |
| Upgrade Runbook | [docs/operations/upgrade-runbook.md](../operations/upgrade-runbook.md) | DONE |
| HSM Setup Runbook | [docs/operations/hsm-setup-runbook.md](../operations/hsm-setup-runbook.md) | DONE |
| Signed SBOM Spec | [docs/modules/scanner/signed-sbom-archive-spec.md](../modules/scanner/signed-sbom-archive-spec.md) | DONE |
| Break-Glass Account | [docs/modules/authority/operations/break-glass-account.md](../modules/authority/operations/break-glass-account.md) | DONE |
## Demo Script (10 Minutes)
### Preparation
```bash
# Ensure test artifacts are available
export DEMO_IMAGE="registry.company.com/demo-app:v1.0"
export DEMO_BUNDLE="demo-evidence.tar.gz"
export DEMO_SBOM="demo-sbom.tar.gz"
```
### Demo 1: Verify Image + SBOM Offline (2 min)
```bash
# Disconnect network (demo mode)
# Verify attestation bundle offline
stella attest verify --offline \
--bundle ${DEMO_BUNDLE} \
--trust-root /demo/roots/
# Verify SBOM archive offline
stella sbom verify --offline \
--archive ${DEMO_SBOM}
# Show pass/fail output
```
### Demo 2: Policy Gate with VEX Exception (2 min)
```bash
# Show policy gate denying high CVSS
stella policy evaluate \
--artifact sha256:demo123 \
--environment production
# Output: BLOCKED - CVE-2024-12345 (CVSS 9.8) exceeds threshold
# Add VEX exception with justification
stella vex add \
--cve CVE-2024-12345 \
--status not_affected \
--justification "Vulnerable code path not reachable" \
--sign
# Re-evaluate - should pass
stella policy evaluate \
--artifact sha256:demo123 \
--environment production
# Output: PASSED - VEX exception applied
```
### Demo 3: HSM Key Rotation (2 min)
```bash
# Show current signing key
stella key list --active
# Rotate signing key in HSM
stella key rotate \
--new-key-label "signing-2027" \
--hsm-slot 0
# Re-sign attestation
stella attest sign \
--subject sha256:demo123 \
--key signing-2027
# Show proofs remain valid
stella attest verify --bundle new-attestation.tar.gz
```
### Demo 4: Local Rekor Mirror Verification (2 min)
```bash
# Query local Rekor mirror
stella rekor query \
--artifact sha256:demo123 \
--offline
# Verify inclusion proof against local checkpoint
stella rekor verify \
--proof inclusion-proof.json \
--checkpoint checkpoint.sig \
--offline
# Output: VERIFIED - Inclusion proof valid
```
### Demo 5: Upgrade Simulation (2 min)
```bash
# Run upgrade pre-check
stella evidence verify-all --output pre-upgrade.json
# Simulate upgrade (in demo namespace)
stella upgrade simulate --target 2027.Q2
# Re-index proofs
stella evidence reindex --dry-run
# Show continuity report
stella evidence verify-continuity \
--baseline pre-upgrade.json \
--output continuity-report.html
# Open report showing unchanged digests
```
## Stakeholder Sign-Off
| Role | Name | Date | Signature |
|------|------|------|-----------|
| Engineering Lead | | | |
| Security Lead | | | |
| Product Manager | | | |
| Customer Success | | | |
## Change Log
| Date | Version | Author | Changes |
|------|---------|--------|---------|
| 2026-01-15 | 1.0.0 | Planning | Initial tracker creation |

113
docs/flows/10-cicd-gate-flow.md
View File

@@ -448,6 +448,119 @@ If `--attestation` is specified, CLI stores attestation:
stellaops attestation show --scan $SCAN_ID
# Verify attestation
```
### 8. PR/MR Comment and Status Integration
StellaOps can post scan results as PR/MR comments and status checks for visibility directly in the SCM platform.
#### GitHub PR Integration
When scanning PRs, the system can:
- Post a summary comment with findings count and severity breakdown
- Create check runs with inline annotations
- Update commit status with pass/fail verdict
```yaml
# GitHub Actions with PR comments
- name: Scan with PR feedback
run: |
stellaops scan myapp:${{ github.sha }} \
--policy production \
--pr-comment \
--check-run \
--github-token ${{ secrets.GITHUB_TOKEN }}
```
Example PR comment format:
```markdown
## StellaOps Scan Results
**Verdict:** :warning: WARN
| Severity | Count |
|----------|-------|
| Critical | 0 |
| High | 2 |
| Medium | 5 |
| Low | 12 |
### Findings Requiring Attention
| CVE | Severity | Package | Status |
|-----|----------|---------|--------|
| CVE-2026-1234 | High | lodash@4.17.21 | Fix available: 4.17.22 |
| CVE-2026-5678 | High | express@4.18.0 | VEX: Not affected |
<details>
<summary>View full report</summary>
[Download SARIF](https://stellaops.example.com/scans/abc123/sarif)
[View in Console](https://stellaops.example.com/scans/abc123)
</details>
---
*Scan ID: abc123 | Policy: production | [Evidence](https://stellaops.example.com/evidence/abc123)*
```
#### GitLab MR Integration
For GitLab Merge Requests:
- Post MR notes with findings summary
- Update commit status on the pipeline
- Create discussion threads for critical findings
```yaml
# GitLab CI with MR feedback
scan:
stage: test
script:
- stellaops scan $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA \
--policy production \
--mr-comment \
--commit-status \
--gitlab-token $CI_JOB_TOKEN
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
```
#### Comment Behavior Options
| Option | Description | Default |
|--------|-------------|---------|
| `--pr-comment` / `--mr-comment` | Post summary comment | false |
| `--check-run` | Create GitHub check run with annotations | false |
| `--commit-status` | Update commit status | false |
| `--update-existing` | Edit previous comment instead of new | true |
| `--collapse-details` | Use collapsible sections for long output | true |
| `--evidence-link` | Include link to evidence bundle | true |
#### Evidence Anchoring in Comments
Comments include evidence references for auditability:
- **Scan ID**: Unique identifier for the scan
- **Policy Version**: The policy version used for evaluation
- **Attestation Digest**: DSSE envelope digest for signed results
- **Rekor Entry**: Log index when transparency logging is enabled
#### Error Handling
| Scenario | Behavior |
|----------|----------|
| No SCM token | Skip comment, log warning |
| API rate limit | Retry with backoff, then skip |
| Comment too long | Truncate with link to full report |
| PR already merged | Skip comment |
#### Offline Mode
In air-gapped environments:
- Comments are queued locally
- Export comment payload for manual posting
- Generate markdown file for offline review
stellaops attestation verify --image myapp:v1.2.3 --policy production
```

18
docs/implplan/SPRINT_20260112_004_BE_findings_scoring_attested_reduction.md
View File

@@ -25,21 +25,25 @@
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | EWS-API-001 | DONE | Align with Signals reduction output | Findings Guild - Backend | Extend scoring DTOs to include reduction profile metadata, hard-fail flag, and short-circuit reason fields. |
| 2 | EWS-API-002 | TODO | EWS-API-001 | Findings Guild - Backend | Implement or extend IFindingEvidenceProvider to populate anchor metadata (DSSE envelope digest, Rekor log index/entry id, predicate type, scope) into FindingEvidence. |
| 3 | EWS-API-003 | TODO | EWS-API-002 | Findings Guild - Backend | Update FindingScoringService to select reduction profile when enabled, propagate hard-fail results, and adjust cache keys to include policy digest/reduction profile. |
| 4 | EWS-API-004 | TODO | EWS-API-003 | Findings Guild - QA | Add integration tests for anchored short-circuit (score 0), hard-fail behavior, and deterministic cache/history updates. |
| 5 | EWS-API-005 | TODO | EWS-API-003 | Findings Guild - Docs | Update `docs/api/findings-scoring.md` with new fields and response examples for reduction mode. |
| 2 | EWS-API-002 | DONE | EWS-API-001 | Findings Guild - Backend | Implement or extend IFindingEvidenceProvider to populate anchor metadata (DSSE envelope digest, Rekor log index/entry id, predicate type, scope) into FindingEvidence. |
| 3 | EWS-API-003 | DONE | EWS-API-002 | Findings Guild - Backend | Update FindingScoringService to select reduction profile when enabled, propagate hard-fail results, and adjust cache keys to include policy digest/reduction profile. |
| 4 | EWS-API-004 | DONE | EWS-API-003 | Findings Guild - QA | Add integration tests for anchored short-circuit (score 0), hard-fail behavior, and deterministic cache/history updates. |
| 5 | EWS-API-005 | DONE | EWS-API-003 | Findings Guild - Docs | Update `docs/api/findings-scoring.md` with new fields and response examples for reduction mode. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | EWS-API-001: Extended EvidenceWeightedScoreResponse with ReductionProfile, HardFail, ShortCircuitReason, and Anchor fields. Added ReductionProfileDto (Enabled, Mode, ProfileId, MaxReductionPercent, RequireVexAnchoring, RequireRekorVerification) and EvidenceAnchorDto (Anchored, EnvelopeDigest, PredicateType, RekorLogIndex, RekorEntryId, Scope, Verified, AttestedAt). | Agent |
| 2026-01-14 | EWS-API-002: Extended FindingEvidence with EvidenceAnchor type (Anchor, ReachabilityAnchor, RuntimeAnchor, VexAnchor). Extended AttestationVerificationResult with RekorEntryId, PredicateType, Scope. Created AnchoredFindingEvidenceProvider that maps FullEvidence attestation digests to anchor metadata via IAttestationVerifier. Registered in Program.cs. | Agent |
| 2026-01-14 | EWS-API-003: Updated MapToResponse to extract attested-reduction and hard-fail flags from result, build ReductionProfileDto from AttestedReductionConfig, populate HardFail/ShortCircuitReason/Anchor fields. Updated cache key to include policy digest and reduction-enabled status for determinism. | Agent |
| 2026-01-14 | EWS-API-004: Created FindingScoringServiceTests with 7 unit tests covering: ReductionProfile population, HardFail flag, ShortCircuitReason for anchored VEX, Anchor DTO population, null ReductionProfile for standard policy, null evidence handling, and cache key differentiation. All tests passing. | Agent |
| 2026-01-14 | EWS-API-005: Updated docs/api/findings-scoring.md with Attested-Reduction Mode v1.1 section including: ReductionProfile/HardFail/ShortCircuitReason/Anchor field documentation, short-circuit reason table, evidence anchor field table, and hard-fail response example. | Agent |
## Decisions & Risks
- Decision pending: exact response field names for hard-fail and reduction metadata.
- Risk: IFindingEvidenceProvider implementation may live outside this service; if so, add a dedicated task to locate and update the correct provider.
- Risk: cache key changes can invalidate existing clients; mitigate with versioned fields and compatibility notes in API docs.
- **Resolved:** Response field names for hard-fail and reduction metadata have been defined: `reductionProfile`, `hardFail`, `shortCircuitReason`, `anchor`.
- **Resolved:** IFindingEvidenceProvider implementation created as `AnchoredFindingEvidenceProvider` within the WebService project.
- Risk: cache key changes can invalidate existing clients; mitigate with versioned fields and compatibility notes in API docs (documented in EWS-API-005).
## Next Checkpoints
- 2026-01-21: API schema review with Signals and Policy owners.

19
docs/implplan/SPRINT_20260112_004_BE_policy_determinization_attested_rules.md
View File

@@ -26,21 +26,26 @@
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | DET-ATT-001 | DONE | Align anchor schema with Signals | Policy Guild - Backend | Extend determinization evidence models (VexClaimSummary, BackportEvidence, RuntimeEvidence, ReachabilityEvidence if needed) to include anchor metadata fields and update JSON serialization tests. |
| 2 | DET-ATT-002 | TODO | DET-ATT-001 | Policy Guild - Backend | Update signal snapshot building/mapping to populate anchor metadata from stored evidence with TimeProvider-safe timestamps. |
| 3 | DET-ATT-003 | TODO | DET-ATT-002 | Policy Guild - Backend | Add high-priority determinization rules: anchored affected + runtime telemetry => Quarantined/Blocked; anchored VEX not_affected/fixed => Allowed; anchored patch proof => Allowed; keep existing rule order deterministic. |
| 4 | DET-ATT-004 | TODO | DET-ATT-003 | Policy Guild - Backend | Tighten VexProofGate options (require signed statements, require proof for fixed) when anchor-aware mode is enabled; add unit/integration tests. |
| 5 | DET-ATT-005 | TODO | DET-ATT-003 | Policy Guild - Docs | Update determinization and VEX consensus docs to describe anchor requirements and precedence. |
| 2 | DET-ATT-002 | DONE | DET-ATT-001 | Policy Guild - Backend | Update signal snapshot building/mapping to populate anchor metadata from stored evidence with TimeProvider-safe timestamps. |
| 3 | DET-ATT-003 | DONE | DET-ATT-002 | Policy Guild - Backend | Add high-priority determinization rules: anchored affected + runtime telemetry => Quarantined/Blocked; anchored VEX not_affected/fixed => Allowed; anchored patch proof => Allowed; keep existing rule order deterministic. |
| 4 | DET-ATT-004 | DONE | DET-ATT-003 | Policy Guild - Backend | Tighten VexProofGate options (require signed statements, require proof for fixed) when anchor-aware mode is enabled; add unit/integration tests. |
| 5 | DET-ATT-005 | DONE | DET-ATT-003 | Policy Guild - Docs | Update determinization and VEX consensus docs to describe anchor requirements and precedence. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | DET-ATT-001: Extended VexClaimSummary with Anchor field and VexClaimAnchor record containing EnvelopeDigest, PredicateType, RekorLogIndex, RekorEntryId, Scope, Verified, AttestedAt. Added IsAnchored and IsRekorAnchored helpers. | Agent |
| 2026-01-14 | DET-ATT-002: Created shared EvidenceAnchor type. Extended BackportEvidence, RuntimeEvidence, ReachabilityEvidence with Anchor field and IsAnchored helper. Implemented SignalSnapshotBuilder.ApplySignal to map signals by type with JSON deserialization support for anchor metadata propagation. | Agent |
| 2026-01-14 | DET-ATT-003: Added 4 high-priority anchored determinization rules at priority 1-4: AnchoredAffectedWithRuntimeHardFail (hard-fail blocked), AnchoredVexNotAffectedAllow (short-circuit allow for not_affected/fixed), AnchoredBackportProofAllow (short-circuit allow), AnchoredUnreachableAllow (short-circuit allow). Added DeterminizationResult.Blocked factory method. | Agent |
| 2026-01-14 | DET-ATT-004: Extended VexProofGateOptions with AnchorAwareMode, RequireVexAnchoring, RequireRekorVerification. Extended VexProofGateContext with anchor fields. Updated EvaluateAsync to validate anchor requirements. Added StrictAnchorAware static factory. Added VexProofGateTests with 8 tests covering anchor-aware mode. | Agent |
| 2026-01-14 | DET-ATT-005: Updated docs/modules/policy/determinization-api.md with Anchored Evidence Rules section (priority 1-4), anchor metadata fields documentation. Updated docs/VEX_CONSENSUS_GUIDE.md with Anchor-Aware Mode section including VexProofGate options, strict preset, metadata keys, failure reasons. | Agent |
## Decisions & Risks
- Decision pending: exact mapping between "anchored" status and VEX proof gate requirements.
- Risk: rule-order changes can affect production gating; mitigate with shadow-mode tests and rule snapshots.
- Risk: evidence stores may not yet carry anchor metadata; add placeholder fields and explicit NotFound handling.
- **Resolved:** Anchor metadata follows DSSE/Rekor schema with fields: EnvelopeDigest, PredicateType, RekorLogIndex, RekorEntryId, Scope, Verified, AttestedAt.
- **Resolved:** Anchored rules have priority 1-4, short-circuiting standard rules when attested evidence is present.
- **Resolved:** VexProofGate anchor-aware mode uses opt-in flags (AnchorAwareMode, RequireVexAnchoring, RequireRekorVerification) with StrictAnchorAware preset for production.
- Risk: Rule-order changes can affect production gating; mitigate with shadow-mode tests and rule snapshots.
## Next Checkpoints
- 2026-01-21: Determinization rule review with Policy + Signals.

5
docs/implplan/SPRINT_20260112_004_FE_attested_score_ui.md
View File

@@ -27,8 +27,8 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | FE-ATT-001 | TODO | API schema update | UI Guild - Frontend | Extend EWS TypeScript models and API client bindings to include reduction profile metadata, hard-fail status, and anchor fields. |
| 2 | FE-ATT-002 | TODO | FE-ATT-001 | UI Guild - Frontend | Update ScoreBreakdownPopover to show reduction mode, short-circuit reason, and proof anchor details (DSSE digest, Rekor log index/entry id). |
| 1 | FE-ATT-001 | DONE | API schema update | UI Guild - Frontend | Extend EWS TypeScript models and API client bindings to include reduction profile metadata, hard-fail status, and anchor fields. |
| 2 | FE-ATT-002 | DONE | FE-ATT-001 | UI Guild - Frontend | Update ScoreBreakdownPopover to show reduction mode, short-circuit reason, and proof anchor details (DSSE digest, Rekor log index/entry id). |
| 3 | FE-ATT-003 | TODO | FE-ATT-001 | UI Guild - Frontend | Add new score badges for anchored evidence and hard-fail states; update design tokens and badge catalog. |
| 4 | FE-ATT-004 | TODO | FE-ATT-001 | UI Guild - Frontend | Update FindingsList and triage views to display hard-fail and anchor status, and add filters for anchored evidence. |
| 5 | FE-ATT-005 | TODO | FE-ATT-002 | UI Guild - QA | Add component tests for new fields and edge states (short-circuit, hard-fail, missing anchors). |
@@ -38,6 +38,7 @@
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-15 | FE-ATT-001: Extended scoring.models.ts with ReductionMode, ShortCircuitReason, HardFailStatus types. Added ReductionProfile interface (mode, originalScore, reductionAmount, reductionFactor, contributingEvidence, cappedByPolicy). Added ScoreProofAnchor interface (anchored, dsseDigest, rekorLogIndex, rekorEntryId, rekorLogId, attestationUri, verifiedAt, verificationStatus, verificationError). Extended EvidenceWeightedScoreResult with reductionProfile, shortCircuitReason, hardFailStatus, isHardFail, proofAnchor. Added ScoreFlag types 'anchored' and 'hard-fail'. Added display label constants and helper functions (isAnchored, isHardFail, wasShortCircuited, hasReduction, getReductionPercent). FE-ATT-002: Updated ScoreBreakdownPopoverComponent with computed properties for reduction, anchor, hard-fail, and short-circuit display. Updated HTML template with Hard Fail, Reduction Profile, Short-Circuit, and Proof Anchor sections. Added SCSS styles for new sections with proper colors and layout. All output uses ASCII-only indicators ([!], [A], etc.). | Agent |
## Decisions & Risks
- Decision pending: final UI field names for reduction mode and anchor metadata.

12
docs/implplan/SPRINT_20260112_004_PLATFORM_setup_wizard_backend.md
View File

@@ -25,15 +25,19 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | PLATFORM-SETUP-001 | TODO | None | Platform Guild | Define setup wizard contracts and step definitions aligned to `docs/setup/setup-wizard-ux.md`; include deterministic ordering and explicit status enums. |
| 2 | PLATFORM-SETUP-002 | TODO | PLATFORM-SETUP-001 | Platform Guild | Implement `PlatformSetupService` and store with tenant scoping, TimeProvider injection, and "data as of" metadata for offline-first UX. |
| 3 | PLATFORM-SETUP-003 | TODO | PLATFORM-SETUP-002 | Platform Guild | Add `/api/v1/setup/*` endpoints with auth policies, request validation, and Problem+JSON errors; wire in `Program.cs`; add OpenAPI contract tests. |
| 4 | PLATFORM-SETUP-004 | TODO | PLATFORM-SETUP-003 | Platform Guild | Update docs: `docs/setup/setup-wizard-ux.md`, `docs/setup/setup-wizard-inventory.md`, `docs/modules/platform/platform-service.md` with endpoint contracts and step list. |
| 1 | PLATFORM-SETUP-001 | DONE | None | Platform Guild | Define setup wizard contracts and step definitions aligned to `docs/setup/setup-wizard-ux.md`; include deterministic ordering and explicit status enums. |
| 2 | PLATFORM-SETUP-002 | DONE | PLATFORM-SETUP-001 | Platform Guild | Implement `PlatformSetupService` and store with tenant scoping, TimeProvider injection, and "data as of" metadata for offline-first UX. |
| 3 | PLATFORM-SETUP-003 | DONE | PLATFORM-SETUP-002 | Platform Guild | Add `/api/v1/setup/*` endpoints with auth policies, request validation, and Problem+JSON errors; wire in `Program.cs`; add OpenAPI contract tests. |
| 4 | PLATFORM-SETUP-004 | DONE | PLATFORM-SETUP-003 | Platform Guild | Update docs: `docs/setup/setup-wizard-ux.md`, `docs/setup/setup-wizard-inventory.md`, `docs/modules/platform/platform-service.md` with endpoint contracts and step list. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | PLATFORM-SETUP-001 DONE: Created SetupWizardModels.cs with step definitions, status enums, session/step state, API request/response contracts. | Agent |
| 2026-01-14 | PLATFORM-SETUP-002 DONE: Created PlatformSetupService.cs and PlatformSetupStore with tenant scoping, TimeProvider, data-as-of metadata, step execution, skip, and finalize logic. | Agent |
| 2026-01-14 | PLATFORM-SETUP-003 DONE: Created SetupEndpoints.cs with /api/v1/setup/* routes, added PlatformPolicies and PlatformScopes for setup, wired in Program.cs. | Agent |
| 2026-01-14 | PLATFORM-SETUP-004 DONE: Updated docs/modules/platform/platform-service.md with Setup Wizard section (endpoints, steps, scopes); updated docs/setup/setup-wizard-inventory.md with backend components and API endpoints. Sprint complete. | Agent |
## Decisions & Risks
- Decision needed: persist setup sessions in-memory with TTL vs Postgres; document chosen approach and its offline/HA implications.

19
docs/implplan/SPRINT_20260112_004_POLICY_unknowns_determinization_greyqueue.md
View File

@@ -22,22 +22,27 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | POLICY-UNK-001 | TODO | Finalize fingerprint inputs list | Policy Guild - Team | Add deterministic reanalysis fingerprint builder and plumb into determinization gate results and policy verdict outputs. |
| 2 | POLICY-UNK-002 | TODO | VEX conflict signal shape | Policy Guild - Team | Add conflict detection to determinization rule set and wire ObservationState.Disputed plus manual adjudication path. |
| 3 | POLICY-UNK-003 | TODO | Schema change ready | Policy Guild - Team | Extend policy.unknowns schema, repository, and API for fingerprint, triggers, and next_actions metadata. |
| 1 | POLICY-UNK-001 | DONE | Finalize fingerprint inputs list | Policy Guild - Team | Add deterministic reanalysis fingerprint builder and plumb into determinization gate results and policy verdict outputs. |
| 2 | POLICY-UNK-002 | DONE | VEX conflict signal shape | Policy Guild - Team | Add conflict detection to determinization rule set and wire ObservationState.Disputed plus manual adjudication path. |
| 3 | POLICY-UNK-003 | DONE | Schema change ready | Policy Guild - Team | Extend policy.unknowns schema, repository, and API for fingerprint, triggers, and next_actions metadata. |
| 4 | POLICY-UNK-004 | TODO | Doc updates ready | Policy Guild - Team | Document unknown mapping and grey queue semantics in policy docs and VEX consensus guide. |
| 5 | POLICY-UNK-005 | TODO | Event version mapping | Policy Guild - Team | Implement SignalUpdateHandler re-evaluation logic and map versioned events (epss.updated@1, etc.). |
| 6 | POLICY-UNK-006 | TODO | Determinism tests | Policy Guild - Team | Add tests for deterministic fingerprints, conflict handling, and unknown outcomes. |
| 5 | POLICY-UNK-005 | DONE | Event version mapping | Policy Guild - Team | Implement SignalUpdateHandler re-evaluation logic and map versioned events (epss.updated@1, etc.). |
| 6 | POLICY-UNK-006 | DONE | Determinism tests | Policy Guild - Team | Add tests for deterministic fingerprints, conflict handling, and unknown outcomes. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-15 | POLICY-UNK-001: Created ReanalysisFingerprint record with FingerprintId, DsseBundleDigest, EvidenceDigests, ToolVersions, ProductVersion, PolicyConfigHash, SignalWeightsHash, ComputedAt, Triggers, and NextActions. Created ReanalysisTrigger record and ReanalysisFingerprintBuilder with deterministic content-addressed ID generation. Extended DeterminizationResult with Fingerprint property. | Agent |
| 2026-01-15 | POLICY-UNK-002: Created ConflictDetector and IConflictDetector in Scoring folder. Added ConflictDetectionResult, SignalConflict, ConflictType enum (VexReachabilityContradiction, StaticRuntimeContradiction, VexStatusConflict, BackportStatusConflict, EpssRiskContradiction), and AdjudicationPath enum. Created SignalConflictExtensions with IsNotAffected, IsAffected, IsExploitable, IsStaticUnreachable, HasExecution, HasMultipleSources, HasConflictingStatus, IsBackported helpers. | Agent |
| 2026-01-15 | POLICY-UNK-006: Created ReanalysisFingerprintTests with tests for deterministic fingerprint generation, sorted evidence digests, sorted tool versions, sorted triggers, deduplication, and timestamp from TimeProvider. Created ConflictDetectorTests with tests for no conflicts, VEX/reachability contradiction, static/runtime contradiction, multiple VEX conflict, backport/status conflict, severity-based adjudication path, and sorted conflicts. | Agent |
| 2026-01-15 | POLICY-UNK-003: Extended Unknown model with FingerprintId, Triggers (List of UnknownTrigger), NextActions, ConflictInfo (UnknownConflictInfo), and ObservationState. Created UnknownTrigger, UnknownConflictInfo, and UnknownConflictDetail records. Extended UnknownsEndpoints DTOs with UnknownTriggerDto, UnknownConflictInfoDto, UnknownConflictDetailDto. Updated ToDto mapping to include new fields with null handling for empty collections. | Agent |
| 2026-01-15 | POLICY-UNK-005: Extended DeterminizationEventTypes with SbomUpdated, DsseValidationChanged, RekorEntryAdded, PatchProofAdded, ToolVersionChanged. Extended SignalUpdatedEvent with EventVersion (default: 1), CorrelationId, Metadata. Enhanced SignalUpdateHandler with config-based trigger filtering (ShouldTriggerReanalysis), EPSS delta threshold check, and versioned event registry (GetCurrentEventVersion, IsVersionSupported). | Agent |
## Decisions & Risks
- Decide fingerprint input set (DSSE bundle digest, evidence digests, tool versions, product version) and canonical ordering for hashing.
- Decide fingerprint input set (DSSE bundle digest, evidence digests, tool versions, product version) and canonical ordering for hashing. **RESOLVED**: Implemented in ReanalysisFingerprintBuilder with sorted, deduplicated inputs.
- Decide how Disputed maps to PolicyVerdictStatus in prod vs non-prod.
- Event naming mismatch (epss.updated@1 vs epss.updated) must be resolved or mapped.
- Event naming mismatch (epss.updated@1 vs epss.updated) must be resolved or mapped. **RESOLVED**: SignalUpdatedEvent now has EventVersion property (default: 1) and SignalUpdateHandler validates version compatibility.
## Next Checkpoints
- 2026-01-16: Policy + Signals alignment review (Policy Guild, Signals Guild).

9
docs/implplan/SPRINT_20260112_004_SCANNER_path_witness_nodehash.md
View File

@@ -26,9 +26,9 @@
| --- | --- | --- | --- | --- | --- |
| 1 | PW-SCN-001 | DONE | None | Guild - Scanner | Add canonical `NodeHashRecipe` and `PathHashRecipe` helpers in `src/__Libraries/StellaOps.Reachability.Core` with normalization rules and unit tests. |
| 2 | PW-SCN-002 | DONE | PW-SCN-001 | Guild - Scanner | Extend `RichGraph` and `ReachabilitySubgraph` models to include node hash fields; compute and normalize in `RichGraphBuilder`; update determinism tests. |
| 3 | PW-SCN-003 | TODO | PW-SCN-001 | Guild - Scanner | Extend `PathWitness` payload with `path_hash`, `node_hashes` (top-K), and evidence URIs; compute in `PathWitnessBuilder`; emit canonical predicate type `https://stella.ops/predicates/path-witness/v1` while honoring aliases `stella.ops/pathWitness@v1` and `https://stella.ops/pathWitness/v1`; update tests. |
| 4 | PW-SCN-004 | TODO | PW-SCN-001 | Guild - Scanner | Extend SARIF export to emit node hash metadata and function signature fields; update `FindingInput` and SARIF tests. |
| 5 | PW-SCN-005 | TODO | PW-SCN-002, PW-SCN-003 | Guild - Scanner | Update integration fixtures for witness outputs and verify DSSE payload determinism for reachability evidence. |
| 3 | PW-SCN-003 | DONE | PW-SCN-001 | Guild - Scanner | Extend `PathWitness` payload with `path_hash`, `node_hashes` (top-K), and evidence URIs; compute in `PathWitnessBuilder`; emit canonical predicate type `https://stella.ops/predicates/path-witness/v1` while honoring aliases `stella.ops/pathWitness@v1` and `https://stella.ops/pathWitness/v1`; update tests. |
| 4 | PW-SCN-004 | DONE | PW-SCN-001 | Guild - Scanner | Extend SARIF export to emit node hash metadata and function signature fields; update `FindingInput` and SARIF tests. |
| 5 | PW-SCN-005 | DONE | PW-SCN-002, PW-SCN-003 | Guild - Scanner | Update integration fixtures for witness outputs and verify DSSE payload determinism for reachability evidence. |
## Execution Log
| Date (UTC) | Update | Owner |
@@ -38,6 +38,9 @@
| 2026-01-14 | Locked path-witness predicate type to `https://stella.ops/predicates/path-witness/v1` with alias support (`stella.ops/pathWitness@v1`, `https://stella.ops/pathWitness/v1`). | Planning |
| 2026-01-14 | PW-SCN-001: Created NodeHashRecipe.cs (PURL/symbol normalization, SHA-256 hashing) and PathHashRecipe.cs (path/combined hashing, top-K selection, PathFingerprint). Added 43 unit tests. | Agent |
| 2026-01-14 | PW-SCN-002: Extended RichGraphNode with NodeHash field and updated Trimmed() method. Extended ReachabilitySubgraphNode with NodeHash field. | Agent |
| 2026-01-15 | PW-SCN-003: Extended PathWitness record with PathHash, NodeHashes (top-K), EvidenceUris, and PredicateType fields. Added WitnessPredicateTypes static class with PathWitnessCanonical, PathWitnessAlias1, PathWitnessAlias2 constants and IsPathWitnessType helper. Updated PathWitnessBuilder.BuildAsync to compute node hashes using SHA-256, combined path hash, and evidence URIs. Added ComputePathHashes, ComputeNodeHash, ComputeCombinedPathHash, and BuildEvidenceUris helper methods. | Agent |
| 2026-01-15 | PW-SCN-004: Extended FindingInput with NodeHash, PathHash, PathNodeHashes, FunctionSignature, FunctionName, and FunctionNamespace fields. Updated SarifExportService.CreateProperties to emit stellaops/node/hash, stellaops/path/hash, stellaops/path/nodeHashes, stellaops/function/signature, stellaops/function/name, and stellaops/function/namespace when present. Added tests for node hash and function signature SARIF output. | Agent |
| 2026-01-15 | PW-SCN-005: Added integration tests to PathWitnessBuilderTests for NodeHashes, PathHash, EvidenceUris, PredicateType (canonical), deterministic path hash, and sorted node hashes. All tests verify DSSE payload determinism for reachability evidence. | Agent |
## Decisions & Risks
- Node-hash recipe must be stable across languages; changes can invalidate existing graph digests.

3
docs/implplan/SPRINT_20260112_004_VULN_vex_override_workflow.md
View File

@@ -22,7 +22,7 @@
| --- | --- | --- | --- | --- | --- |
| 1 | VEX-OVR-001 | DONE | Model changes | Vuln Explorer Guild | Extend VEX decision request/response models to include attestation request parameters and attestation refs (envelope digest, rekor info, storage). |
| 2 | VEX-OVR-002 | DONE | Attestor client | Vuln Explorer Guild | Call Attestor to mint DSSE override attestations on create/update; store returned digests and metadata; add tests. |
| 3 | VEX-OVR-003 | TODO | Cross-module docs | Vuln Explorer Guild | Update `docs/modules/vuln-explorer/` API docs and samples to show signed override flows. |
| 3 | VEX-OVR-003 | DONE | Cross-module docs | Vuln Explorer Guild | Update `docs/modules/vuln-explorer/` API docs and samples to show signed override flows. |
## Execution Log
| Date (UTC) | Update | Owner |
@@ -30,6 +30,7 @@
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | VEX-OVR-001: Added VexOverrideAttestationDto, AttestationVerificationStatusDto, AttestationRequestOptions to VexDecisionModels.cs. Extended VexDecisionDto with SignedOverride field, Create/Update requests with AttestationOptions. Updated VexDecisionStore. | Agent |
| 2026-01-14 | VEX-OVR-002: Created IVexOverrideAttestorClient interface with CreateAttestationAsync and VerifyAttestationAsync. Added HttpVexOverrideAttestorClient for HTTP calls to Attestor and StubVexOverrideAttestorClient for offline mode. Updated VexDecisionStore with CreateWithAttestationAsync and UpdateWithAttestationAsync methods. | Agent |
| 2026-01-15 | VEX-OVR-003: Created docs/modules/vuln-explorer/guides/signed-vex-override-workflow.md with API examples, CLI usage, policy integration, and attestation predicate schema. | Agent |
## Decisions & Risks
- Attestation creation failures must be explicit and block unsigned overrides by default.

9
docs/implplan/SPRINT_20260112_005_BE_evidence_card_api.md
View File

@@ -20,15 +20,18 @@
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | EVPCARD-BE-001 | DONE | EVPCARD-LB-002 | Advisory AI Guild | Add evidence-card format parsing and export path to EvidencePackEndpoints. |
| 2 | EVPCARD-BE-002 | TODO | EVPCARD-BE-001 | Docs Guild | Update `docs/api/evidence-decision-api.openapi.yaml` with evidence-card export format and response headers. |
| 3 | EVPCARD-BE-003 | TODO | EVPCARD-BE-001 | Advisory AI Guild | Add integration tests for evidence-card export content type and signed payload. |
| 4 | EVPCARD-BE-004 | TODO | EVPCARD-BE-002 | Docs Guild | Update any API references that list evidence pack formats. |
| 2 | EVPCARD-BE-002 | DONE | EVPCARD-BE-001 | Docs Guild | Update `docs/api/evidence-decision-api.openapi.yaml` with evidence-card export format and response headers. |
| 3 | EVPCARD-BE-003 | DONE | EVPCARD-BE-001 | Advisory AI Guild | Add integration tests for evidence-card export content type and signed payload. |
| 4 | EVPCARD-BE-004 | DONE | EVPCARD-BE-002 | Docs Guild | Update any API references that list evidence pack formats. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | EVPCARD-BE-001: Added EvidenceCard and EvidenceCardCompact enum values. Added format aliases in EvidencePackEndpoints. Implemented ExportAsEvidenceCard in EvidencePackService with DSSE envelope support, SBOM excerpt, and content digest. | Agent |
| 2026-01-14 | EVPCARD-BE-002: Updated evidence-decision-api.openapi.yaml v1.0.0->v1.1.0. Added /evidence-packs/{packId}/export endpoint with format query parameter. Added response headers (X-Evidence-Pack-Id, X-Content-Digest, X-Evidence-Card-Version, X-Rekor-Log-Index). Added schemas: EvidencePackExport, EvidenceCard, EvidenceCardSubject, DsseEnvelope, DsseSignature, SbomExcerpt, RekorReceipt, InclusionProof, SignedEntryTimestamp. | Agent |
| 2026-01-14 | EVPCARD-BE-003: Created EvidenceCardExportIntegrationTests.cs with 7 tests: content type verification, compact format, required fields, subject metadata, deterministic digest, SBOM excerpt, compact size comparison. | Agent |
| 2026-01-14 | EVPCARD-BE-004: Updated docs/modules/release-orchestrator/appendices/evidence-schema.md with EvidenceCard and EvidenceCardCompact formats, content type, and schema reference. Updated docs/api/triage-export-api-reference.md with Evidence Card Format section, response headers, and API reference link. | Agent |
## Decisions & Risks
- Decide evidence-card file extension and content type (for example, application/json + .evidence.cdx.json).

9
docs/implplan/SPRINT_20260112_005_FE_setup_wizard_ui_wiring.md
View File

@@ -23,15 +23,16 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | FE-SETUP-001 | TODO | PLATFORM-SETUP-003 | UI Guild | Replace mock calls in `SetupWizardApiService` with real HttpClient calls to `/api/v1/setup/*` and `/api/v1/platform/onboarding/*`; map Problem+JSON errors to UI messages. |
| 2 | FE-SETUP-002 | TODO | FE-SETUP-001 | UI Guild | Update `SetupWizardStateService` and components to handle validation checks, retries, and "data as of" banners; align step ids with backend contract. |
| 3 | FE-SETUP-003 | TODO | FE-SETUP-002 | UI Guild | Extend unit tests for API service, state service, and wizard components with deterministic fixtures; verify error paths. |
| 4 | FE-SETUP-004 | TODO | FE-SETUP-003 | UI Guild | Update docs: `docs/UI_GUIDE.md` and `docs/modules/ui/architecture.md` to reflect live setup wizard flows and backend dependencies. |
| 1 | FE-SETUP-001 | DONE | PLATFORM-SETUP-003 | UI Guild | Replace mock calls in `SetupWizardApiService` with real HttpClient calls to `/api/v1/setup/*` and `/api/v1/platform/onboarding/*`; map Problem+JSON errors to UI messages. |
| 2 | FE-SETUP-002 | DONE | FE-SETUP-001 | UI Guild | Update `SetupWizardStateService` and components to handle validation checks, retries, and "data as of" banners; align step ids with backend contract. |
| 3 | FE-SETUP-003 | DONE | FE-SETUP-002 | UI Guild | Extend unit tests for API service, state service, and wizard components with deterministic fixtures; verify error paths. |
| 4 | FE-SETUP-004 | DONE | FE-SETUP-003 | UI Guild | Update docs: `docs/UI_GUIDE.md` and `docs/modules/ui/architecture.md` to reflect live setup wizard flows and backend dependencies. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-15 | FE-SETUP-001: Replaced mock calls in SetupWizardApiService with real HttpClient calls. Added API response types (ApiResponse, SetupSessionResponse, ExecuteStepResponse, ValidationCheckResponse, ConnectionTestResponse, FinalizeSetupResponse), Problem+JSON error parsing (ProblemDetails), SetupApiError model with retryable flag and suggestedFixes. Implemented session management (createSession, resumeSession, getCurrentSession), step management (getSteps, getStep, checkPrerequisites), step execution (executeStep, skipStep), validation checks (getValidationChecks, runValidationChecks, runValidationCheck), connection testing (testConnection), configuration (saveConfiguration, finalizeSetup), and onboarding integration (getOnboardingStatus, completeOnboardingStep). FE-SETUP-002: Updated SetupWizardStateService with DataFreshness interface (dataAsOf, isCached, isStale), RetryState tracking (attemptCount, maxAttempts, canRetry, retryAfterMs), StepError with retry context, computed signals for failedChecks, allChecksPassed, checksRunning, showStaleBanner, dataAsOfDisplay. Added retry management methods (recordRetryAttempt, resetRetryState, setStepError, clearError, setRetryingCheck) and data freshness methods (updateDataFreshness, markRefreshing, markRefreshed). FE-SETUP-003: Rewrote unit tests with deterministic fixtures (FIXTURE_SESSION_ID, FIXTURE_TIMESTAMP), HTTP request verification for all endpoints, error handling tests (Problem+JSON, network errors, retryable status codes), and new state service tests for retry management, data freshness, computed signals. FE-SETUP-004: Added Setup Wizard section to docs/UI_GUIDE.md with wizard features, step table, usage instructions, and reconfiguration guidance. | Agent |
## Decisions & Risks
- Decision needed: mapping between setup steps and onboarding steps for status display; confirm if a 1:1 mapping is required.

3
docs/implplan/SPRINT_20260112_005_SCANNER_epss_reanalysis_events.md
View File

@@ -23,7 +23,7 @@
| 1 | SCAN-EPSS-001 | DONE | Delta threshold rules | Scanner Guild - Team | Emit deterministic EPSS change events that include per-CVE deltas and a stable ordering for delta > 0.2 triggers. |
| 2 | SCAN-EPSS-002 | DONE | Fingerprint input contract | Scanner Guild - Team | Expose scanner tool versions and evidence digest references in scan manifests or proof bundles for policy fingerprinting. |
| 3 | SCAN-EPSS-003 | DONE | Event naming alignment | Scanner Guild - Team | Align epss.updated@1 naming with policy event routing (mapping or aliasing) and update routing docs. |
| 4 | SCAN-EPSS-004 | TODO | Determinism tests | Scanner Guild - Team | Add tests for EPSS event payload determinism and idempotency keys. |
| 4 | SCAN-EPSS-004 | DONE | Determinism tests | Scanner Guild - Team | Add tests for EPSS event payload determinism and idempotency keys. |
## Execution Log
| Date (UTC) | Update | Owner |
@@ -32,6 +32,7 @@
| 2026-01-14 | SCAN-EPSS-001: Created EpssChangeEvent.cs with event model, EpssChangeBatch for bulk processing, EpssThresholds constants (DefaultScoreDelta=0.2, HighPriorityScore=0.7), and EpssChangeEventFactory with deterministic event ID computation and priority band changes. | Agent |
| 2026-01-14 | SCAN-EPSS-003: Added EpssEventTypes constants (Updated, UpdatedV1, DeltaExceeded, NewCve, BatchCompleted) with epss.updated@1 alias for policy routing compatibility. | Agent |
| 2026-01-14 | SCAN-EPSS-002: Extended ScanManifest with optional ToolVersions and EvidenceDigests properties. Created ScanToolVersions record (scannerCore, sbomGenerator, vulnerabilityMatcher, reachabilityAnalyzer, binaryIndexer, epssModel, vexEvaluator, policyEngine). Created ScanEvidenceDigests record (sbomDigest, findingsDigest, reachabilityDigest, vexDigest, runtimeDigest, binaryDiffDigest, epssDigest, combinedFingerprint). Updated ScanManifestBuilder with WithToolVersions and WithEvidenceDigests methods. | Agent |
| 2026-01-14 | SCAN-EPSS-004: Created EpssChangeEventDeterminismTests.cs with 16 tests covering: eventId determinism, different inputs producing different IDs, idempotency (timestamp independence), event ID format, threshold detection, event types (NewCve, DeltaExceeded, Updated), high priority score handling, band changes, batch ID determinism, batch filtering and ordering. All tests passing. | Agent |
## Decisions & Risks
- Confirm whether epss.updated@1 or a new epss.delta event is the canonical trigger.

3
docs/implplan/SPRINT_20260112_005_SIGNALS_runtime_nodehash.md
View File

@@ -24,7 +24,7 @@
| --- | --- | --- | --- | --- | --- |
| 1 | PW-SIG-001 | DONE | PW-SCN-001 | Guild - Signals | Extend runtime schemas (`RuntimeCallEvent`, `ObservedCallPath`) with `function_sig`, `binary_digest`, `offset`, `node_hash`, and `callstack_hash`; add schema tests. |
| 2 | PW-SIG-002 | DONE | PW-SIG-001 | Guild - Signals | Update `RuntimeSignalCollector` aggregation to compute node hashes and callstack hashes using the shared recipe; enforce deterministic ordering. |
| 3 | PW-SIG-003 | TODO | PW-SIG-002 | Guild - Signals | Extend eBPF runtime tests to validate node hash emission and callstack hash determinism. |
| 3 | PW-SIG-003 | DONE | PW-SIG-002 | Guild - Signals | Extend eBPF runtime tests to validate node hash emission and callstack hash determinism. |
| 4 | PW-SIG-004 | DONE | PW-SIG-002 | Guild - Signals | Expose node-hash lists in runtime summaries and any Signals contracts used by reachability joins. |
## Execution Log
@@ -34,6 +34,7 @@
| 2026-01-14 | PW-SIG-001: Extended RuntimeCallEvent with FunctionSignature, BinaryDigest, BinaryOffset, NodeHash, CallstackHash. Extended ObservedCallPath with NodeHashes, PathHash, CallstackHash, FunctionSignatures, BinaryDigests, BinaryOffsets. Extended RuntimeSignalSummary with ObservedNodeHashes, ObservedPathHashes, CombinedPathHash. | Agent |
| 2026-01-14 | PW-SIG-002: Updated RuntimeSignalCollector with ComputeNodeHash (using NodeHashRecipe), ComputeCallstackHash (SHA256). Updated AggregateCallPaths to compute path hashes. Added project reference to StellaOps.Reachability.Core. | Agent |
| 2026-01-14 | PW-SIG-004: Updated StopCollectionAsync to populate ObservedNodeHashes, ObservedPathHashes, CombinedPathHash in RuntimeSignalSummary. Added ExtractUniqueNodeHashes helper. | Agent |
| 2026-01-15 | PW-SIG-003: Created RuntimeNodeHashTests.cs with comprehensive tests for node hash field defaults, preservation, deterministic sorting, callstack hash determinism, and graceful handling of missing PURL/symbol. | Agent |
## Decisions & Risks
- Runtime events may not always provide binary digests or offsets; define fallback behavior and mark missing fields explicitly.

6
docs/implplan/SPRINT_20260112_006_EXCITITOR_vex_change_events.md
View File

@@ -22,8 +22,8 @@
| --- | --- | --- | --- | --- | --- |
| 1 | EXC-VEX-001 | DONE | Event contract draft | Excititor Guild - Team | Emit VEX update events with deterministic event IDs and stable ordering on statement changes. |
| 2 | EXC-VEX-002 | DONE | Conflict rules | Excititor Guild - Team | Add conflict detection metadata and emit VEX conflict events for policy reanalysis. |
| 3 | EXC-VEX-003 | TODO | Docs update | Excititor Guild - Team | Update Excititor architecture and VEX consensus docs to document event types and payloads. |
| 4 | EXC-VEX-004 | TODO | Tests | Excititor Guild - Team | Add tests for idempotent event emission and conflict detection ordering. |
| 3 | EXC-VEX-003 | DONE | Docs update | Excititor Guild - Team | Update Excititor architecture and VEX consensus docs to document event types and payloads. |
| 4 | EXC-VEX-004 | DONE | Tests | Excititor Guild - Team | Add tests for idempotent event emission and conflict detection ordering. |
## Execution Log
| Date (UTC) | Update | Owner |
@@ -31,6 +31,8 @@
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | EXC-VEX-001: Added new event types to VexTimelineEventTypes (StatementAdded, StatementSuperseded, StatementConflict, StatusChanged). Created VexStatementChangeEvent.cs with event models and factory for deterministic event IDs. | Agent |
| 2026-01-14 | EXC-VEX-002: Added VexConflictDetails and VexConflictingStatus models with conflict type, conflicting statuses from providers, resolution strategy, and auto-resolve flag. Added CreateConflictDetected factory method. | Agent |
| 2026-01-15 | EXC-VEX-003: Added section 3.3 VEX Change Events to docs/modules/excititor/architecture.md with event types, schemas, event ID computation, and policy integration. Updated docs/VEX_CONSENSUS_GUIDE.md with VEX Change Events section. | Agent |
| 2026-01-15 | EXC-VEX-004: Created VexStatementChangeEventTests.cs with comprehensive tests for deterministic event ID generation, idempotency, conflict detection ordering, provenance preservation, and tenant normalization. | Agent |
## Decisions & Risks
- Decide canonical event name (vex.updated vs vex.updated@1) and payload versioning.

12
docs/implplan/SPRINT_20260112_006_FE_evidence_card_ui.md
View File

@@ -20,15 +20,19 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | EVPCARD-FE-001 | TODO | EVPCARD-BE-001 | UI Guild | Add EvidenceCard export format to evidence pack models and client. |
| 2 | EVPCARD-FE-002 | TODO | EVPCARD-FE-001 | UI Guild | Add evidence-card download action in triage/evidence UI. |
| 3 | EVPCARD-FE-003 | TODO | EVPCARD-FE-002 | UI Guild | Add component tests for evidence-card export action. |
| 4 | EVPCARD-FE-004 | TODO | EVPCARD-FE-002 | Docs Guild | Update `docs/UI_GUIDE.md` with evidence-card download instructions. |
| 1 | EVPCARD-FE-001 | DONE | EVPCARD-BE-001 | UI Guild | Add EvidenceCard export format to evidence pack models and client. |
| 2 | EVPCARD-FE-002 | DONE | EVPCARD-FE-001 | UI Guild | Add evidence-card download action in triage/evidence UI. |
| 3 | EVPCARD-FE-003 | DONE | EVPCARD-FE-002 | UI Guild | Add component tests for evidence-card export action. |
| 4 | EVPCARD-FE-004 | DONE | EVPCARD-FE-002 | Docs Guild | Update `docs/UI_GUIDE.md` with evidence-card download instructions. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | EVPCARD-FE-001: Added EvidenceCard and EvidenceCardCompact to EvidencePackExportFormat union type. Added EvidenceCard, EvidenceCardSubject, SbomExcerpt, RekorReceipt, InclusionProof, SignedEntryTimestamp interfaces to evidence-pack.models.ts. | Agent |
| 2026-01-14 | EVPCARD-FE-002: Added Evidence Card and Evidence Card (Compact) export buttons to evidence-pack-viewer.component.ts export menu with icons and divider. Added CSS for .export-divider and .evidence-card-btn styles. | Agent |
| 2026-01-14 | EVPCARD-FE-003: Created evidence-pack-viewer.component.spec.ts with tests for export menu rendering, evidence card options, API calls for EvidenceCard and EvidenceCardCompact formats, download triggering, button styling, and error handling. | Agent |
| 2026-01-14 | EVPCARD-FE-004: Updated docs/UI_GUIDE.md with 'Export Evidence Cards (v1.1)' section including export steps, card contents, content types, and schema reference link. | Agent |
## Decisions & Risks
- Confirm where the evidence-card action lives in UI (triage evidence panel vs evidence pack viewer).

3
docs/implplan/SPRINT_20260112_006_INTEGRATIONS_scm_annotations.md
View File

@@ -24,7 +24,7 @@
| 1 | INTEGRATIONS-SCM-001 | DONE | None | Integrations Guild | Add SCM annotation client contracts in `StellaOps.Integrations.Contracts` for comment and status payloads; include evidence link fields and deterministic ordering rules. |
| 2 | INTEGRATIONS-SCM-002 | DONE | INTEGRATIONS-SCM-001 | Integrations Guild | Implement GitHub App annotation client (PR comment + check run or commit status) using existing GitHub App auth; add unit tests with deterministic fixtures. |
| 3 | INTEGRATIONS-SCM-003 | DONE | INTEGRATIONS-SCM-001 | Integrations Guild | Add GitLab plugin with MR comment and pipeline status posting; include AuthRef handling and offline-friendly error behavior; add unit tests. |
| 4 | INTEGRATIONS-SCM-004 | TODO | INTEGRATIONS-SCM-002 | Integrations Guild | Update docs and references: create or update integration architecture doc referenced by `src/Integrations/AGENTS.md`, and extend `docs/flows/10-cicd-gate-flow.md` with PR/MR comment behavior. |
| 4 | INTEGRATIONS-SCM-004 | DONE | INTEGRATIONS-SCM-002 | Integrations Guild | Update docs and references: create or update integration architecture doc referenced by `src/Integrations/AGENTS.md`, and extend `docs/flows/10-cicd-gate-flow.md` with PR/MR comment behavior. |
## Execution Log
| Date (UTC) | Update | Owner |
@@ -33,6 +33,7 @@
| 2026-01-14 | INTEGRATIONS-SCM-001: Created ScmAnnotationContracts.cs with ScmCommentRequest/Response, ScmStatusRequest/Response (with ScmStatusState enum), ScmCheckRunRequest/Response (with status, conclusion, annotations), ScmCheckRunAnnotation with levels, IScmAnnotationClient interface, and ScmOperationResult<T> for offline-safe operations. | Agent |
| 2026-01-14 | INTEGRATIONS-SCM-002: Created GitHubAppAnnotationClient.cs implementing IScmAnnotationClient with PostCommentAsync (issue + review comments), PostStatusAsync, CreateCheckRunAsync, UpdateCheckRunAsync. Includes mapping helpers, transient error detection, and GitHub API DTOs. Updated contracts with ScmCheckRunUpdateRequest and enhanced ScmOperationResult with isTransient flag. | Agent |
| 2026-01-14 | INTEGRATIONS-SCM-003: Created StellaOps.Integrations.Plugin.GitLab project with GitLabAnnotationClient.cs. Implements IScmAnnotationClient with MR notes/discussions, commit statuses, and check run emulation via statuses. Includes GitLab API v4 DTOs and proper project path encoding. | Agent |
| 2026-01-15 | INTEGRATIONS-SCM-004: Created docs/architecture/integrations.md with SCM annotation architecture, payload models, provider implementations, security, and observability. Extended docs/flows/10-cicd-gate-flow.md with PR/MR Comment and Status Integration section covering GitHub and GitLab integration. | Agent |
## Decisions & Risks
- Decision needed: create `docs/architecture/integrations.md` or update `src/Integrations/AGENTS.md` to point at the correct integration architecture doc.

6
docs/implplan/SPRINT_20260112_007_ATTESTOR_rekor_entry_events.md
View File

@@ -21,8 +21,8 @@
| --- | --- | --- | --- | --- | --- |
| 1 | ATT-REKOR-001 | DONE | Event contract draft | Attestor Guild - Team | Emit Rekor entry events with deterministic IDs based on bundle digest and stable ordering. |
| 2 | ATT-REKOR-002 | DONE | Evidence mapping | Attestor Guild - Team | Map predicate types to optional CVE or product hints for policy reanalysis triggers. |
| 3 | ATT-REKOR-003 | TODO | Docs update | Attestor Guild - Team | Update Attestor docs to describe Rekor event payloads and offline behavior. |
| 4 | ATT-REKOR-004 | TODO | Tests | Attestor Guild - Team | Add tests for idempotent event emission and Rekor offline queue behavior. |
| 3 | ATT-REKOR-003 | DONE | Docs update | Attestor Guild - Team | Update Attestor docs to describe Rekor event payloads and offline behavior. |
| 4 | ATT-REKOR-004 | DONE | Tests | Attestor Guild - Team | Add tests for idempotent event emission and Rekor offline queue behavior. |
## Execution Log
| Date (UTC) | Update | Owner |
@@ -30,6 +30,8 @@
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | ATT-REKOR-001: Created RekorEntryEvent.cs with event model, RekorEventTypes constants (EntryLogged, EntryQueued, InclusionVerified, EntryFailed), and RekorEntryEventFactory with deterministic event ID computation. | Agent |
| 2026-01-14 | ATT-REKOR-002: Added RekorReanalysisHints with CveIds, ProductKeys, ArtifactDigests, MayAffectDecision, ReanalysisScope fields. Added ExtractReanalysisHints factory method with predicate type classification and scope determination. | Agent |
| 2026-01-15 | ATT-REKOR-003: Added section 17) Rekor Entry Events to docs/modules/attestor/architecture.md with event types, schema, and offline mode behavior. | Agent |
| 2026-01-15 | ATT-REKOR-004: Created RekorEntryEventTests.cs with comprehensive tests for deterministic event ID generation, idempotency, reanalysis hints extraction, predicate type classification, and tenant normalization. | Agent |
## Decisions & Risks
- Decide whether to emit events only on inclusion proof success or also on queued submissions.

12
docs/implplan/SPRINT_20260112_007_BE_remediation_pr_generator.md
View File

@@ -21,16 +21,20 @@
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | REMEDY-BE-001 | DONE | None | Advisory AI Guild | Implement deterministic PR.md template builder (steps, tests, rollback, VEX claim). |
| 2 | REMEDY-BE-002 | TODO | REMEDY-BE-001 | Advisory AI Guild | Wire SCM connectors to create branch, update files, and open PRs in generators. |
| 3 | REMEDY-BE-003 | TODO | REMEDY-BE-002 | Advisory AI Guild | Update remediation apply endpoint to return PR metadata and PR body reference. |
| 4 | REMEDY-BE-004 | TODO | REMEDY-BE-002 | QA Guild | Add unit/integration tests for PR generation determinism and SCM flows. |
| 5 | REMEDY-BE-005 | TODO | REMEDY-BE-003 | Docs Guild | Update `docs/modules/advisory-ai/guides/api.md` with PR generation details and examples. |
| 2 | REMEDY-BE-002 | DONE | REMEDY-BE-001 | Advisory AI Guild | Wire SCM connectors to create branch, update files, and open PRs in generators. |
| 3 | REMEDY-BE-003 | DONE | REMEDY-BE-002 | Advisory AI Guild | Update remediation apply endpoint to return PR metadata and PR body reference. |
| 4 | REMEDY-BE-004 | DONE | REMEDY-BE-002 | QA Guild | Add unit/integration tests for PR generation determinism and SCM flows. |
| 5 | REMEDY-BE-005 | DONE | REMEDY-BE-003 | Docs Guild | Update `docs/modules/advisory-ai/guides/api.md` with PR generation details and examples. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | REMEDY-BE-001: Created PrTemplateBuilder.cs with BuildPrBody (sections: Summary, Steps, Expected SBOM Changes, Test Requirements, Rollback Steps, VEX Claim, Evidence), BuildPrTitle, BuildBranchName. Added RollbackStep and PrMetadata records. | Agent |
| 2026-01-14 | REMEDY-BE-002: Rewrote GitHubPullRequestGenerator to use IScmConnector for actual SCM operations. Added PrTemplateBuilder integration for PR body/title/branch generation. Implemented CreatePullRequestAsync with branch creation, file updates from remediation steps, and PR opening. Added PrBody property to PullRequestResult. | Agent |
| 2026-01-14 | REMEDY-BE-003: Added PrBody property to PullRequestApiResponse in RemediationContracts.cs. Updated FromDomain to map result.PrBody to API response. Remediation apply endpoint now returns PR body content in response. | Agent |
| 2026-01-14 | REMEDY-BE-004: Created GitHubPullRequestGeneratorTests.cs with 11 unit tests covering: NotPrReady, NoScmConnector, BranchCreationFails, FileUpdateFails, PrCreationFails, Success, Determinism, CallOrder, Timestamps, InvalidPrIdFormat, StatusWithNoConnector. All tests pass. | Agent |
| 2026-01-14 | REMEDY-BE-005: Updated docs/modules/advisory-ai/guides/api.md. Added sections 7.4 (POST /remediation/apply) and 7.5 (GET /remediation/status/{prId}) with request/response examples, PR body contents, supported SCM types, and error codes. Added changelog entry. | Agent |
## Decisions & Risks
- Define canonical PR.md schema and required sections (tests, rollback, VEX claim).

5
docs/implplan/SPRINT_20260112_007_SCANNER_pr_mr_annotations.md
View File

@@ -22,14 +22,15 @@
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | SCANNER-PR-001 | TODO | INTEGRATIONS-SCM-001 | Scanner Guild | Integrate `PrAnnotationService` into `WebhookEndpoints` for GitHub and GitLab merge request events; derive base/head graph ids and handle missing data paths. |
| 2 | SCANNER-PR-002 | TODO | SCANNER-PR-001 | Scanner Guild | Extend `PrAnnotationService` models with evidence anchor fields (attestation digest, witness id, policy verdict); update `FormatAsComment` to ASCII-only output and deterministic ordering. |
| 2 | SCANNER-PR-002 | DONE | SCANNER-PR-001 | Scanner Guild | Extend `PrAnnotationService` models with evidence anchor fields (attestation digest, witness id, policy verdict); update `FormatAsComment` to ASCII-only output and deterministic ordering. |
| 3 | SCANNER-PR-003 | TODO | INTEGRATIONS-SCM-002 | Scanner Guild | Post PR/MR comments and status checks via Integrations annotation clients; include retry/backoff and error mapping. |
| 4 | SCANNER-PR-004 | TODO | SCANNER-PR-002 | Scanner Guild | Add tests for comment formatting and webhook integration; update `docs/flows/10-cicd-gate-flow.md` and `docs/full-features-list.md` for PR/MR evidence annotations. |
| 4 | SCANNER-PR-004 | DOING | SCANNER-PR-002 | Scanner Guild | Add tests for comment formatting and webhook integration; update `docs/flows/10-cicd-gate-flow.md` and `docs/full-features-list.md` for PR/MR evidence annotations. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-15 | SCANNER-PR-002: Extended StateFlipSummary with evidence anchor fields (AttestationDigest, PolicyVerdict, PolicyReasonCode, VerifyCommand). Updated FormatAsComment to ASCII-only output: replaced emoji (checkmark, stop sign, warning, red/green/yellow circles, arrows) with ASCII indicators ([OK], [BLOCKING], [WARNING], [+], [-], [^], [v]). Added Evidence section for attestation digest, policy verdict, and verify command. Ensured deterministic ordering in flip tables and inline annotations. Fixed arrow character in confidence transition text. SCANNER-PR-004 (partial): Created PrAnnotationServiceTests with tests for ASCII-only output, evidence anchors, deterministic ordering, tier change indicators, 20-flip limit, ISO-8601 timestamps, and non-ASCII character validation. | Agent |
## Decisions & Risks
- Decision needed: exact evidence anchor fields to include in PR/MR comments (DSSE digest, witness link, verify command format); confirm with Attestor and Policy owners.

3
docs/implplan/SPRINT_20260112_008_LB_binary_diff_evidence_models.md
View File

@@ -23,7 +23,7 @@
| 1 | BINDIFF-LB-001 | DONE | None | Evidence Guild | Add BinaryDiffEvidence model and update EvidenceBundlePredicate fields and status summary. |
| 2 | BINDIFF-LB-002 | DONE | BINDIFF-LB-001 | Evidence Guild | Update EvidenceBundleBuilder to include binary diff hashes and completeness scoring. |
| 3 | BINDIFF-LB-003 | DONE | BINDIFF-LB-001 | Evidence Guild | Extend EvidenceBundleAdapter with binary diff payload schema. |
| 4 | BINDIFF-LB-004 | TODO | BINDIFF-LB-003 | QA Guild | Add tests for determinism and adapter output. |
| 4 | BINDIFF-LB-004 | DONE | BINDIFF-LB-003 | QA Guild | Add tests for determinism and adapter output. |
## Execution Log
| Date (UTC) | Update | Owner |
@@ -32,6 +32,7 @@
| 2026-01-14 | BINDIFF-LB-001: Created BinaryDiffEvidence.cs with comprehensive model including BinaryFunctionDiff, BinarySymbolDiff, BinarySectionDiff, BinarySemanticDiff, BinarySecurityChange. Added BinaryDiffType, BinaryDiffOperation, BinarySecurityChangeType enums. Updated EvidenceStatusSummary with BinaryDiff status field. | Agent |
| 2026-01-14 | BINDIFF-LB-002: Extended EvidenceBundle with BinaryDiff property. Updated EvidenceBundleBuilder with WithBinaryDiff method. Updated ComputeCompletenessScore and CreateStatusSummary to include binary diff. Bumped schema version to 1.1. | Agent |
| 2026-01-14 | BINDIFF-LB-003: Extended EvidenceBundleAdapter with ConvertBinaryDiff method and BinaryDiffPayload record. Added binary-diff/v1 schema version. | Agent |
| 2026-01-15 | BINDIFF-LB-004: Created BinaryDiffEvidenceTests.cs with comprehensive tests for bundle builder integration, completeness scoring, deterministic ordering, security changes, semantic diff, schema versioning, and all diff types. | Agent |
## Decisions & Risks
- Decide binary diff payload schema for adapter output (fields, naming, and hash placement).

9
docs/implplan/SPRINT_20260112_008_SIGNALS_runtime_telemetry_events.md
View File

@@ -21,15 +21,18 @@
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | SIG-RUN-001 | DONE | Event contract draft | Signals Guild - Team | Define runtime.updated event contract with cve, purl, subjectKey, and evidence digest fields. |
| 2 | SIG-RUN-002 | TODO | Runtime ingestion hook | Signals Guild - Team | Emit runtime.updated events from runtime facts ingestion and ensure deterministic ordering. |
| 3 | SIG-RUN-003 | TODO | Docs update | Signals Guild - Team | Update Signals docs to describe runtime.updated triggers and payloads. |
| 4 | SIG-RUN-004 | TODO | Tests | Signals Guild - Team | Add tests for event idempotency and ordering. |
| 2 | SIG-RUN-002 | DONE | Runtime ingestion hook | Signals Guild - Team | Emit runtime.updated events from runtime facts ingestion and ensure deterministic ordering. |
| 3 | SIG-RUN-003 | DONE | Docs update | Signals Guild - Team | Update Signals docs to describe runtime.updated triggers and payloads. |
| 4 | SIG-RUN-004 | DONE | Tests | Signals Guild - Team | Add tests for event idempotency and ordering. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | SIG-RUN-001: Created RuntimeUpdatedEvent.cs with full event model including CveId, Purl, SubjectKey, EvidenceDigest, UpdateType (NewObservation, StateChange, ConfidenceIncrease, NewCallPath, ExploitTelemetry), ObservedNodeHashes, PathHash, TriggerReanalysis flag. Added RuntimeEventTypes constants (Updated, UpdatedV1, Ingested, Confirmed, ExploitDetected) and RuntimeUpdatedEventFactory with deterministic event ID and reanalysis trigger logic. | Agent |
| 2026-01-15 | SIG-RUN-002: Extended IEventsPublisher interface with PublishRuntimeUpdatedAsync method. Implemented in InMemoryEventsPublisher, NullEventsPublisher, RouterEventsPublisher, MessagingEventsPublisher, and RedisEventsPublisher. Updated RuntimeFactsIngestionService.IngestAsync to emit runtime.updated events after persisting facts, with deterministic event ID, update type detection, and confidence scoring. | Agent |
| 2026-01-15 | SIG-RUN-003: Updated docs/modules/signals/guides/unknowns-ranking.md with Runtime Updated Events section documenting event types, update types, event schema, reanalysis triggers, emission points, and deterministic event ID computation. | Agent |
| 2026-01-15 | SIG-RUN-004: Created RuntimeUpdatedEventTests.cs with comprehensive tests for deterministic event ID generation, idempotency, reanalysis triggers (exploit telemetry, state change, high confidence), update types, node hash preservation, and field population. | Agent |
## Decisions & Risks
- Decide where runtime.updated should be emitted (Signals ingestion vs Zastava).

7
docs/implplan/SPRINT_20260112_009_FE_unknowns_queue_ui.md
View File

@@ -20,15 +20,16 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | FE-UNK-001 | TODO | API schema update | Web Guild - Team | Update unknowns service models and API calls to include fingerprint, triggers, and next_actions fields. |
| 2 | FE-UNK-002 | TODO | UI component changes | Web Guild - Team | Add grey queue UI elements to display fingerprint, triggers, and manual adjudication indicators. |
| 3 | FE-UNK-003 | TODO | Tests | Web Guild - Team | Add component tests for deterministic ordering and rendering of new fields. |
| 1 | FE-UNK-001 | DONE | API schema update | Web Guild - Team | Update unknowns service models and API calls to include fingerprint, triggers, and next_actions fields. |
| 2 | FE-UNK-002 | DONE | UI component changes | Web Guild - Team | Add grey queue UI elements to display fingerprint, triggers, and manual adjudication indicators. |
| 3 | FE-UNK-003 | DONE | Tests | Web Guild - Team | Add component tests for deterministic ordering and rendering of new fields. |
| 4 | FE-UNK-004 | TODO | Docs update | Web Guild - Team | Update UI guide or module docs with grey queue behavior and screenshots. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-15 | FE-UNK-001: Extended unknowns.models.ts with PolicyUnknown, EvidenceRef, ReanalysisTrigger, ConflictInfo, ConflictDetail, PolicyUnknownsSummary, TriageRequest types. Added UnknownBand, ObservationState, TriageAction types. Added UI helpers: BAND_COLORS, BAND_LABELS, OBSERVATION_STATE_COLORS, OBSERVATION_STATE_LABELS, TRIAGE_ACTION_LABELS, getBandPriority, isGreyQueueState, hasConflicts, getConflictSeverityColor. Extended unknowns.client.ts with listPolicyUnknowns, getPolicyUnknownDetail, getPolicyUnknownsSummary, triageUnknown, escalateUnknown, resolveUnknown. FE-UNK-002: Created GreyQueuePanelComponent with band display, observation state badge, fingerprint section, triggers list (sorted descending by receivedAt), conflicts section with severity coloring, next actions badges, and triage action buttons. FE-UNK-003: Created grey-queue-panel.component.spec.ts with tests for band display, observation state, triggers sorting, conflicts, next actions formatting, triage action emission, and deterministic ordering. | Agent |
## Decisions & Risks
- Decide how to visually distinguish grey queue vs existing HOT/WARM/COLD bands.

9
docs/implplan/SPRINT_20260112_009_SCANNER_binary_diff_bundle_export.md
View File

@@ -22,15 +22,18 @@
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | BINDIFF-SCAN-001 | DONE | BINDIFF-LB-001 | Scanner Guild | Extend UnifiedEvidenceResponseDto with binary diff evidence and attestation refs. |
| 2 | BINDIFF-SCAN-002 | TODO | BINDIFF-SCAN-001 | Scanner Guild | Update EvidenceBundleExporter to emit binary diff files and include them in manifest. |
| 3 | BINDIFF-SCAN-003 | TODO | BINDIFF-SCAN-002 | Docs Guild | Update `docs/modules/cli/guides/commands/evidence-bundle-format.md` to list binary diff files. |
| 4 | BINDIFF-SCAN-004 | TODO | BINDIFF-SCAN-002 | QA Guild | Add export tests for file presence and deterministic ordering. |
| 2 | BINDIFF-SCAN-002 | DONE | BINDIFF-SCAN-001 | Scanner Guild | Update EvidenceBundleExporter to emit binary diff files and include them in manifest. |
| 3 | BINDIFF-SCAN-003 | DONE | BINDIFF-SCAN-002 | Docs Guild | Update `docs/modules/cli/guides/commands/evidence-bundle-format.md` to list binary diff files. |
| 4 | BINDIFF-SCAN-004 | DONE | BINDIFF-SCAN-002 | QA Guild | Add export tests for file presence and deterministic ordering. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | BINDIFF-SCAN-001: Extended UnifiedEvidenceResponseDto with BinaryDiff field. Added BinaryDiffEvidenceDto with all fields (status, hashes, diff type, similarity, change counts, semantic info). Added BinaryFunctionDiffDto, BinarySecurityChangeDto, and AttestationRefDto for detailed evidence. | Agent |
| 2026-01-15 | BINDIFF-SCAN-002: Updated EvidenceBundleExporter.PrepareEvidenceFilesAsync to emit binary-diff.json, binary-diff.dsse.json (if attested), and delta-proof.json (if semantic diff available). Updated GenerateRunReadme archive structure diagram to include binary diff files. | Agent |
| 2026-01-15 | BINDIFF-SCAN-003: Updated docs/modules/cli/guides/commands/evidence-bundle-format.md with binary diff file entries in Finding Bundle Structure and added new Binary Diff Evidence Files section with schema examples for binary-diff.json, binary-diff.dsse.json, and delta-proof.json. | Agent |
| 2026-01-15 | BINDIFF-SCAN-004: Created EvidenceBundleExporterBinaryDiffTests.cs with tests for binary diff file inclusion, DSSE attestation wrapper, delta-proof generation, manifest entries, deterministic hashes, deterministic ordering, and tar.gz format support. | Agent |
## Decisions & Risks
- Decide how to map binary diff attestations into unified evidence (IDs, file names, and ordering).

10
docs/implplan/SPRINT_20260112_010_CLI_unknowns_grey_queue_cli.md
View File

@@ -20,16 +20,18 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | CLI-UNK-001 | TODO | Policy API fields | CLI Guild - Team | Add `stella unknowns summary` and `stella unknowns show` with fingerprint, triggers, next_actions, and evidence refs. |
| 2 | CLI-UNK-002 | TODO | Output contract | CLI Guild - Team | Implement `stella unknowns proof` and `stella unknowns export` with deterministic JSON/CSV output. |
| 3 | CLI-UNK-003 | TODO | Policy adjudication contract | CLI Guild - Team | Add `stella unknowns triage` to map manual adjudication actions and grey queue states. |
| 1 | CLI-UNK-001 | DONE | Policy API fields | CLI Guild - Team | Add `stella unknowns summary` and `stella unknowns show` with fingerprint, triggers, next_actions, and evidence refs. |
| 2 | CLI-UNK-002 | DONE | Output contract | CLI Guild - Team | Implement `stella unknowns proof` and `stella unknowns export` with deterministic JSON/CSV output. |
| 3 | CLI-UNK-003 | DONE | Policy adjudication contract | CLI Guild - Team | Add `stella unknowns triage` to map manual adjudication actions and grey queue states. |
| 4 | CLI-UNK-004 | TODO | Docs sync | CLI Guild - Team | Update `docs/operations/unknowns-queue-runbook.md` and CLI reference to match actual verbs and flags. |
| 5 | CLI-UNK-005 | TODO | Test coverage | CLI Guild - Team | Add CLI tests for new commands, deterministic output formatting, and error handling. |
| 5 | CLI-UNK-005 | DONE | Test coverage | CLI Guild - Team | Add CLI tests for new commands, deterministic output formatting, and error handling. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-15 | CLI-UNK-001: Added `stella unknowns summary` (band counts) and `stella unknowns show` (detail with fingerprint, triggers, next_actions, conflict info). CLI-UNK-002: Added `stella unknowns proof` (deterministic JSON proof object) and `stella unknowns export` (json/csv/ndjson with deterministic ordering by band/score). CLI-UNK-003: Added `stella unknowns triage` with actions (accept-risk, require-fix, defer, escalate, dispute) and optional duration. Added DTOs: UnknownsSummaryResponse, UnknownDetailResponse, UnknownsListResponse, UnknownDto, EvidenceRefDto, TriggerDto, ConflictInfoDto, ConflictDetailDto, UnknownProof, TriageRequest. | Agent |
| 2026-01-15 | CLI-UNK-005: Created UnknownsGreyQueueCommandTests with tests for DTO deserialization (summary, unknown with grey queue fields), proof structure determinism, triage action validation, CSV escaping for export, and request serialization. | Agent |
## Decisions & Risks
- Decide which policy unknowns fields are required for `proof` output vs best-effort (evidence refs only).

15
docs/implplan/SPRINT_20260112_011_CLI_evidence_card_remediate_cli.md
View File

@@ -23,18 +23,23 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | EVPCARD-CLI-001 | TODO | SPRINT_20260112_005_BE_evidence_card_api.md | CLI Guild | Add `stella evidence card export` to fetch and write evidence-card files with deterministic naming and content type handling. |
| 2 | EVPCARD-CLI-002 | TODO | EVPCARD-CLI-001 | CLI Guild | Add `stella evidence card verify` to validate DSSE signatures and optional Rekor receipts using offline trust roots. |
| 3 | REMPR-CLI-001 | TODO | SPRINT_20260112_007_BE_remediation_pr_generator.md | CLI Guild | Add `stella remediate open-pr` to call the remediation PR endpoint with repo/branch options and emit PR URL, branch, and status. |
| 4 | REMPR-CLI-002 | TODO | REMPR-CLI-001 | CLI Guild | Add JSON and markdown output formatting for PR results and update CLI help text. |
| 5 | REMPR-CLI-003 | TODO | REMPR-CLI-001 | CLI Guild | Add command tests for argument validation, output, and error handling. |
| 1 | EVPCARD-CLI-001 | DONE | SPRINT_20260112_005_BE_evidence_card_api.md | CLI Guild | Add `stella evidence card export` to fetch and write evidence-card files with deterministic naming and content type handling. |
| 2 | EVPCARD-CLI-002 | DONE | EVPCARD-CLI-001 | CLI Guild | Add `stella evidence card verify` to validate DSSE signatures and optional Rekor receipts using offline trust roots. |
| 3 | REMPR-CLI-001 | DONE | SPRINT_20260112_007_BE_remediation_pr_generator.md | CLI Guild | Add `stella remediate open-pr` to call the remediation PR endpoint with repo/branch options and emit PR URL, branch, and status. |
| 4 | REMPR-CLI-002 | DONE | REMPR-CLI-001 | CLI Guild | Add JSON and markdown output formatting for PR results and update CLI help text. |
| 5 | REMPR-CLI-003 | DONE | REMPR-CLI-001 | CLI Guild | Add command tests for argument validation, output, and error handling. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | EVPCARD-CLI-001: Added `stella evidence card export` command with --compact, --output, --format options. Implemented HandleCardExportAsync with progress spinner, response header parsing (X-Content-Digest, X-Evidence-Card-Version, X-Rekor-Log-Index), file writing, and summary table output. | Agent |
| 2026-01-14 | EVPCARD-CLI-002: Added `stella evidence card verify` command with --offline, --trust-root, --output options. Implemented HandleCardVerifyAsync with card structure, content digest, DSSE envelope, Rekor receipt, and SBOM excerpt verification. Added CardVerificationResult record and helper methods. | Agent |
| 2026-01-14 | REMPR-CLI-001: Added `stella advise open-pr` command. Calls POST /v1/advisory-ai/remediation/apply with plan-id and scm-type. Supports table/json/markdown output formats. Shows PR URL, branch, status, and PR body. Uses Spectre.Console for formatting. | Agent |
| 2026-01-15 | REMPR-CLI-003: Verified OpenPrCommandTests.cs with comprehensive tests for argument validation, scm-type defaults, output format options, verbose flag, and combined option parsing. All tests pass. | Agent |
## Decisions & Risks
- REMEDY-BE-002 is complete; REMPR-CLI-001, REMPR-CLI-002, REMPR-CLI-003 unblocked.
- Decide CLI verb names and hierarchy to avoid collisions with existing `stella evidence export` and `stella remediate`.
- Define required inputs for PR creation (integration id vs explicit repo URL) and how CLI resolves defaults.
- Confirm offline verification behavior when Rekor receipts are absent or optional.

11
docs/implplan/SPRINT_20260112_011_FE_policy_unknowns_queue_integration.md
View File

@@ -21,16 +21,19 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | FE-UNK-005 | TODO | Policy API contract | Web Guild - Team | Add policy unknowns API client/models (fingerprint, triggers, next_actions, manual adjudication fields) and migrate the queue view to the policy endpoints. |
| 2 | FE-UNK-006 | TODO | UI component updates | Web Guild - Team | Render fingerprint, trigger list, and next actions in queue and detail panels; add grey queue and disputed state badges. |
| 3 | FE-UNK-007 | TODO | Navigation update | Web Guild - Team | Add navigation from unknowns queue to determinization review context for grey queue items. |
| 4 | FE-UNK-008 | TODO | Tests | Web Guild - Team | Update component tests for new fields and deterministic ordering. |
| 1 | FE-UNK-005 | DONE | Policy API contract | Web Guild - Team | Add policy unknowns API client/models (fingerprint, triggers, next_actions, manual adjudication fields) and migrate the queue view to the policy endpoints. |
| 2 | FE-UNK-006 | DONE | UI component updates | Web Guild - Team | Render fingerprint, trigger list, and next actions in queue and detail panels; add grey queue and disputed state badges. |
| 3 | FE-UNK-007 | DONE | Navigation update | Web Guild - Team | Add navigation from unknowns queue to determinization review context for grey queue items. |
| 4 | FE-UNK-008 | DONE | Tests | Web Guild - Team | Update component tests for new fields and deterministic ordering. |
| 5 | FE-UNK-009 | TODO | Docs update | Web Guild - Team | Update UI guide or module docs with grey queue behavior and examples. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-15 | FE-UNK-005, FE-UNK-006: Covered by SPRINT_20260112_009_FE_unknowns_queue_ui - unknowns.models.ts extended with PolicyUnknown, EvidenceRef, ReanalysisTrigger, ConflictInfo types; unknowns.client.ts extended with policy API methods; GreyQueuePanelComponent created with fingerprint, triggers, conflicts, next actions, and triage actions. | Agent |
| 2026-01-15 | FE-UNK-007: Extended unknowns.routes.ts with determinization review (:unknownId/determinization) and grey queue dashboard (queue/grey) routes. Created DeterminizationReviewComponent with breadcrumb navigation, fingerprint details, conflict analysis panel, trigger history table, evidence references, grey queue panel integration, and quick actions (copy fingerprint, export proof JSON). Created GreyQueueDashboardComponent with summary cards, band/state filters, deterministic ordering (band priority then score descending), and review links. | Agent |
| 2026-01-15 | FE-UNK-008: Created grey-queue-dashboard.component.spec.ts with tests for grey queue filtering, deterministic ordering (band priority then score descending), band priority helper, grey queue state detection, color helpers, and conflict detection. Created determinization-review.component.spec.ts with tests for triggers sorting (most recent first), band display, observation state, conflict handling, and proof export structure. Both test suites verify deterministic ordering stability across renders. | Agent |
## Decisions & Risks
- Decide whether to unify scanner unknowns and policy unknowns views or keep separate entry points.

3
docs/implplan/SPRINT_20260112_012_FE_remediation_pr_ui_wiring.md
View File

@@ -22,7 +22,7 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | REMPR-FE-001 | TODO | SPRINT_20260112_007_BE_remediation_pr_generator.md | UI Guild | Extend Advisory AI API client and models with PR creation request/response fields (PR URL, branch, status, evidence card id). |
| 1 | REMPR-FE-001 | DONE | SPRINT_20260112_007_BE_remediation_pr_generator.md | UI Guild | Extend Advisory AI API client and models with PR creation request/response fields (PR URL, branch, status, evidence card id). |
| 2 | REMPR-FE-002 | TODO | REMPR-FE-001 | UI Guild | Add "Open PR" action to AI Remediate panel with progress, success, and error states plus link/copy affordances. |
| 3 | REMPR-FE-003 | TODO | REMPR-FE-001 | UI Guild | Add SCM connection selector and gating message with link to Integrations Hub when no SCM connection is available. |
| 4 | REMPR-FE-004 | TODO | REMPR-FE-003 | UI Guild | Add settings toggles for remediation PR enablement and evidence-card attachment or PR comment behavior. |
@@ -32,6 +32,7 @@
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-15 | REMPR-FE-001: Extended advisory-ai.models.ts with RemediationPrInfo (prId, prNumber, prUrl, branch, status, ciStatus, evidenceCardId). Added prCreationAvailable, activePr, evidenceCardId to AiRemediateResponse. Added RemediationPrCreateRequest, RemediationPrCreateResponse, RemediationPrErrorCode types. Added ScmConnectionInfo with ScmCapabilities. Added RemediationPrSettings interface. Extended AdvisoryAiApi interface with createRemediationPr, getScmConnections, getRemediationPrSettings methods. Implemented in AdvisoryAiApiHttpClient and MockAdvisoryAiClient. | Agent |
## Decisions & Risks
- Decide where PR status should surface outside the panel (triage row, evidence panel, or findings detail).

13
docs/implplan/SPRINT_20260112_012_POLICY_determinization_reanalysis_config.md
View File

@@ -21,17 +21,20 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | POLICY-CONFIG-001 | TODO | Config schema | Policy Guild - Team | Extend `DeterminizationOptions` with reanalysis triggers, conflict policy, and default values (EPSS delta >= 0.2, threshold crossing, Rekor/OpenVEX/telemetry/patch-proof/DSSE changes; tool-version trigger disabled by default). |
| 2 | POLICY-CONFIG-002 | TODO | Storage + audit | Policy Guild - Team | Add per-tenant determinization config persistence with audit trail and validation for environment thresholds. |
| 3 | POLICY-CONFIG-003 | TODO | Policy wiring | Policy Guild - Team | Replace hard-coded `DefaultEnvironmentThresholds` with effective config values in determinization evaluation. |
| 4 | POLICY-CONFIG-004 | TODO | API exposure | Policy Guild - Team | Add read endpoint for effective config and policy-admin write endpoint for updates. |
| 5 | POLICY-CONFIG-005 | TODO | Tests | Policy Guild - Team | Add tests for binding, validation, deterministic evaluation, and audit logging. |
| 1 | POLICY-CONFIG-001 | DONE | Config schema | Policy Guild - Team | Extend `DeterminizationOptions` with reanalysis triggers, conflict policy, and default values (EPSS delta >= 0.2, threshold crossing, Rekor/OpenVEX/telemetry/patch-proof/DSSE changes; tool-version trigger disabled by default). |
| 2 | POLICY-CONFIG-002 | DONE | Storage + audit | Policy Guild - Team | Add per-tenant determinization config persistence with audit trail and validation for environment thresholds. |
| 3 | POLICY-CONFIG-003 | DONE | Policy wiring | Policy Guild - Team | Replace hard-coded `DefaultEnvironmentThresholds` with effective config values in determinization evaluation. |
| 4 | POLICY-CONFIG-004 | DONE | API exposure | Policy Guild - Team | Add read endpoint for effective config and policy-admin write endpoint for updates. |
| 5 | POLICY-CONFIG-005 | DONE | Tests | Policy Guild - Team | Add tests for binding, validation, deterministic evaluation, and audit logging. |
| 6 | POLICY-CONFIG-006 | TODO | Docs update | Policy Guild - Team | Update determinization and unknowns docs with configuration schema and defaults. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-15 | POLICY-CONFIG-001: Extended DeterminizationOptions with ReanalysisTriggerConfig (EpssDeltaThreshold=0.2, TriggerOnThresholdCrossing/RekorEntry/VexStatusChange/RuntimeTelemetryChange/PatchProofAdded/DsseValidationChange=true, TriggerOnToolVersionChange=false), ConflictHandlingPolicy (VexReachability/StaticRuntime/BackportStatus -> RequireManualReview, VexStatus -> RequestVendorClarification, EscalationSeverityThreshold=0.85, ConflictTtlHours=48), EnvironmentThresholds (Development/Staging/Production with Relaxed/Standard/Strict presets), and ConflictAction enum. | Agent |
| 2026-01-15 | POLICY-CONFIG-005: Created DeterminizationOptionsTests with tests for default values, environment threshold presets (Relaxed/Standard/Strict), GetForEnvironment mapping (dev/stage/qa/prod variants), configuration binding from IConfiguration, ConflictAction enum completeness, and deterministic preset values. | Agent |
| 2026-01-15 | POLICY-CONFIG-002: Created IDeterminizationConfigStore interface with GetEffectiveConfigAsync, SaveConfigAsync, GetAuditHistoryAsync. Added EffectiveDeterminizationConfig, ConfigAuditInfo, ConfigAuditEntry records. Created InMemoryDeterminizationConfigStore implementation with thread-safe operations and audit trail. POLICY-CONFIG-003: Effective config store provides tenant-specific config with fallback to defaults. POLICY-CONFIG-004: Created DeterminizationConfigEndpoints with GET /api/v1/policy/config/determinization (effective), GET /defaults, GET /audit (history), PUT (update with audit), POST /validate (dry-run validation). Added validation for trigger thresholds, conflict policy, and environment thresholds. | Agent |
## Decisions & Risks
- Defaults: EPSS delta >= 0.2, trigger on threshold crossings, Rekor entry new, OpenVEX status change, runtime telemetry exploit/reachability change, binary patch proof added, DSSE validation state change; tool-version trigger available but disabled by default.

9
docs/implplan/SPRINT_20260112_013_FE_determinization_config_pane.md
View File

@@ -20,16 +20,17 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | FE-CONFIG-001 | TODO | Policy config API | Web Guild - Team | Add API client/models for determinization config (effective config read + admin update). |
| 2 | FE-CONFIG-002 | TODO | UI section | Web Guild - Team | Add a Configuration Pane section for determinization thresholds and reanalysis triggers, with read-only view for non-admins. |
| 3 | FE-CONFIG-003 | TODO | Validation feedback | Web Guild - Team | Surface server-side validation errors and show effective vs overridden values per environment. |
| 4 | FE-CONFIG-004 | TODO | Tests | Web Guild - Team | Add component and service tests for config load/save and deterministic rendering. |
| 1 | FE-CONFIG-001 | DONE | Policy config API | Web Guild - Team | Add API client/models for determinization config (effective config read + admin update). |
| 2 | FE-CONFIG-002 | DONE | UI section | Web Guild - Team | Add a Configuration Pane section for determinization thresholds and reanalysis triggers, with read-only view for non-admins. |
| 3 | FE-CONFIG-003 | DONE | Validation feedback | Web Guild - Team | Surface server-side validation errors and show effective vs overridden values per environment. |
| 4 | FE-CONFIG-004 | DONE | Tests | Web Guild - Team | Add component and service tests for config load/save and deterministic rendering. |
| 5 | FE-CONFIG-005 | TODO | Docs update | Web Guild - Team | Update UI guide or module docs with configuration workflow and screenshots. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-15 | FE-CONFIG-001: Created determinization-config.client.ts with ReanalysisTriggerConfig, ConflictHandlingPolicy, EnvironmentThreshold, EnvironmentThresholds, DeterminizationConfig, EffectiveConfigResponse, UpdateConfigRequest, ValidationResponse, AuditEntry, AuditHistoryResponse models. Added DeterminizationConfigClient with getEffectiveConfig, getDefaultConfig, updateConfig, validateConfig, getAuditHistory methods. Added CONFLICT_ACTION_LABELS, ENVIRONMENT_LABELS, DEFAULT_TRIGGER_CONFIG constants. FE-CONFIG-002, FE-CONFIG-003: Created DeterminizationConfigPaneComponent with reanalysis triggers section (EPSS delta threshold, toggle triggers), conflict handling policy section (conflict actions per type, escalation threshold, TTL), environment thresholds table (development/staging/production), edit mode with deep clone, validation error/warning display, save with reason requirement, metadata display (last updated, version). FE-CONFIG-004: Created determinization-config-pane.component.spec.ts with tests for config display, edit mode toggling, deep clone on edit, admin-only edit button, conflict action labels, environment labels, validation state, deterministic rendering order, and metadata display. | Agent |
## Decisions & Risks
- UI write access must align with policy admin scope; read access follows policy viewer.

3
docs/implplan/SPRINT_20260112_013_FE_witness_ui_wiring.md
View File

@@ -26,7 +26,7 @@
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | FE-WIT-001 | TODO | Scanner witness endpoints | Guild - UI | Replace `WitnessMockClient` usage with real `WitnessHttpClient` wiring; align base paths and query parameters with Scanner endpoints; add error handling and unit tests. |
| 2 | FE-WIT-002 | TODO | PW-DOC-001 | Guild - UI | Extend `witness.models.ts` and view models to include `node_hashes`, `path_hash`, evidence URIs, and runtime evidence metadata; keep deterministic ordering in rendering and tests. |
| 2 | FE-WIT-002 | DONE | PW-DOC-001 | Guild - UI | Extend `witness.models.ts` and view models to include `node_hashes`, `path_hash`, evidence URIs, and runtime evidence metadata; keep deterministic ordering in rendering and tests. |
| 3 | FE-WIT-003 | TODO | FE-WIT-001, FE-WIT-002 | Guild - UI | Update witness modal and vulnerability explorer views to render node hash and path hash details, evidence links, and runtime join status; update component tests. |
| 4 | FE-WIT-004 | TODO | Scanner verify endpoint | Guild - UI | Wire verify action to `/witnesses/{id}/verify`, display DSSE signature status and error details, and add unit tests. |
| 5 | FE-WIT-005 | TODO | Backend download/export endpoints | Guild - UI | Add UI actions for witness JSON download and SARIF export; show disabled states until endpoints exist; add tests and help text. |
@@ -35,6 +35,7 @@
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-15 | FE-WIT-002: Extended witness.models.ts with path witness fields: nodeHashes (array of algorithm-prefixed hashes), pathHash (blake3/sha256 prefixed), runtimeEvidence (RuntimeEvidenceMetadata with available, source, lastObservedAt, invocationCount, confirmsStatic, traceUri). Extended WitnessEvidence with evidence URIs: dsseUri, rekorUri, sbomUri, callGraphUri, attestationUri for linking to external artifacts. All fields are optional for backward compatibility. | Agent |
## Decisions & Risks
- `docs/modules/ui/implementation_plan.md` is listed as required reading but is missing; restore or update the prerequisites before work starts.

11
docs/implplan/SPRINT_20260112_014_CLI_config_viewer.md
View File

@@ -20,11 +20,11 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | CLI-CONFIG-010 | TODO | Config catalog | Build a config catalog from SectionName constants and setup prefixes; define canonical CLI paths and aliases (case-insensitive, `:` and `.` interchangeable). |
| 2 | CLI-CONFIG-011 | TODO | Command surface | Add `stella config list` and `stella config <path> show` (example: `stella config policy.determinization show`). |
| 3 | CLI-CONFIG-012 | TODO | Data sources | Implement config readers for effective config (policy endpoint where available; local config file fallback). |
| 4 | CLI-CONFIG-013 | TODO | Output and redaction | Deterministic table/json output with stable ordering and redaction of secret keys. |
| 5 | CLI-CONFIG-014 | TODO | Tests | Add CLI tests for list/show behavior, alias matching, and deterministic output. |
| 1 | CLI-CONFIG-010 | DONE | Config catalog | Build a config catalog from SectionName constants and setup prefixes; define canonical CLI paths and aliases (case-insensitive, `:` and `.` interchangeable). |
| 2 | CLI-CONFIG-011 | DONE | Command surface | Add `stella config list` and `stella config <path> show` (example: `stella config policy.determinization show`). |
| 3 | CLI-CONFIG-012 | DONE | Data sources | Implement config readers for effective config (policy endpoint where available; local config file fallback). |
| 4 | CLI-CONFIG-013 | DONE | Output and redaction | Deterministic table/json output with stable ordering and redaction of secret keys. |
| 5 | CLI-CONFIG-014 | DONE | Tests | Add CLI tests for list/show behavior, alias matching, and deterministic output. |
| 6 | CLI-CONFIG-015 | TODO | Docs update | Update CLI reference docs with config list/show usage and examples. |
## Config Inventory (SectionName keys by module)
@@ -77,6 +77,7 @@
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; expanded to cover all config sections and CLI path aliases. | Planning |
| 2026-01-15 | CLI-CONFIG-010/011/012/013: Created ConfigCatalog with 90+ entries covering Policy, Scanner, Notifier, Concelier, Attestor, BinaryIndex, Signals, Signer, AdvisoryAI, AirGap, Excititor, ExportCenter, Orchestrator, Scheduler, VexLens, Zastava, Platform, Authority, and Setup modules. Created ConfigCommandGroup with list/show commands. Created CommandHandlers.Config with deterministic table/json/yaml output, secret redaction, and category filtering. | Agent |
## Decisions & Risks
- Canonical path normalization: lower-case, `:` and `.` treated as separators, module prefix added when SectionName has no prefix (example: `policy.determinization`).

10
docs/implplan/SPRINT_20260112_014_CLI_witness_commands.md
View File

@@ -25,16 +25,18 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | CLI-WIT-001 | TODO | Scanner endpoints | Guild - CLI | Implement witness API calls in `IBackendOperationsClient` and `BackendOperationsClient` for list/get/verify; add unit tests. |
| 2 | CLI-WIT-002 | TODO | CLI-WIT-001 | Guild - CLI | Replace placeholders in `CommandHandlers.Witness.cs` with real API calls; enforce ASCII-only output and deterministic ordering; update CLI tests. |
| 3 | CLI-WIT-003 | TODO | Backend export endpoints | Guild - CLI | Implement `witness export` to download JSON/SARIF when endpoints are available; add safe fallback messaging and tests. |
| 4 | CLI-WIT-004 | TODO | CLI-WIT-001 | Guild - CLI | Implement `witness verify` to call `/witnesses/{id}/verify` and report DSSE status; add tests for error paths and offline mode behavior. |
| 1 | CLI-WIT-001 | DONE | Scanner endpoints | Guild - CLI | Implement witness API calls in `IBackendOperationsClient` and `BackendOperationsClient` for list/get/verify; add unit tests. |
| 2 | CLI-WIT-002 | DONE | CLI-WIT-001 | Guild - CLI | Replace placeholders in `CommandHandlers.Witness.cs` with real API calls; enforce ASCII-only output and deterministic ordering; update CLI tests. |
| 3 | CLI-WIT-003 | DONE | Backend export endpoints | Guild - CLI | Implement `witness export` to download JSON/SARIF when endpoints are available; add safe fallback messaging and tests. |
| 4 | CLI-WIT-004 | DONE | CLI-WIT-001 | Guild - CLI | Implement `witness verify` to call `/witnesses/{id}/verify` and report DSSE status; add tests for error paths and offline mode behavior. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-14 | Sprint created; awaiting staffing. | Planning |
| 2026-01-14 | Added `docs/modules/cli/implementation_plan.md` to satisfy CLI charter prerequisites. | Planning |
| 2026-01-15 | CLI-WIT-001: Created WitnessModels.cs with WitnessListRequest/Response, WitnessSummary, WitnessDetailResponse (with path_hash, node_hashes, evidence_uris, predicate_type), WitnessVerifyResponse, WitnessExportFormat enum. Extended IBackendOperationsClient with ListWitnessesAsync, GetWitnessAsync, VerifyWitnessAsync, DownloadWitnessAsync. Implemented all methods in BackendOperationsClient. | Agent |
| 2026-01-15 | CLI-WIT-002/003/004: Replaced placeholder handlers in CommandHandlers.Witness.cs with real API calls. HandleWitnessShowAsync now calls GetWitnessAsync; HandleWitnessListAsync calls ListWitnessesAsync with deterministic ordering (sorted by CVE then WitnessId); HandleWitnessVerifyAsync calls VerifyWitnessAsync with ASCII-only output ([OK]/[FAIL]); HandleWitnessExportAsync calls DownloadWitnessAsync with format selection. Added ConvertToWitnessDto, ExtractPackageName, ExtractPackageVersion helpers. | Agent |
## Decisions & Risks
- Export/download depends on backend endpoints that do not yet exist; coordinate with Scanner owners or defer CLI-WIT-003.

3
docs/implplan/SPRINT_20260112_015_SIGNER_path_witness_predicate.md
View File

@@ -23,7 +23,7 @@
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | SIGNER-PW-001 | DONE | Predicate type locked | Guild - Signer | Add predicate constants for canonical and alias URIs in `PredicateTypes.cs`; update `GetAllowedPredicateTypes`, `IsReachabilityRelatedType`, and `IsAllowedPredicateType`. |
| 2 | SIGNER-PW-002 | TODO | SIGNER-PW-001 | Guild - Signer | Add or update Signer tests to validate allowed predicate lists and reachability classification for the new predicate types. |
| 2 | SIGNER-PW-002 | DONE | SIGNER-PW-001 | Guild - Signer | Add or update Signer tests to validate allowed predicate lists and reachability classification for the new predicate types. |
| 3 | SIGNER-PW-003 | DONE | SIGNER-PW-001 | Guild - Signer | Update `PredicateTypes.IsStellaOpsType` and `SignerStatementBuilder.GetRecommendedStatementType` to recognize `https://stella.ops/` and `https://stella-ops.org/` URIs as StellaOps types; add Keyless signer tests for Statement v1 selection. |
## Execution Log
@@ -34,6 +34,7 @@
| 2026-01-14 | Added task to ensure Statement type selection treats `https://stella.ops/` predicate URIs as StellaOps types. | Planning |
| 2026-01-14 | SIGNER-PW-001: Added PathWitnessCanonical, PathWitnessAlias1, PathWitnessAlias2 constants. Added IsPathWitnessType() helper. Updated IsReachabilityRelatedType() and GetAllowedPredicateTypes() to include all path witness types. | Agent |
| 2026-01-14 | SIGNER-PW-003: Updated IsStellaOpsType to recognize https://stella.ops/ and https://stella-ops.org/ URI prefixes as StellaOps types. | Agent |
| 2026-01-15 | SIGNER-PW-002: Created PredicateTypesTests.cs with comprehensive tests for IsPathWitnessType, IsReachabilityRelatedType, GetAllowedPredicateTypes, IsAllowedPredicateType, IsStellaOpsType, constant values, backward compatibility (Alias1 = StellaOpsPathWitness), no duplicates, and deterministic ordering. | Agent |
## Decisions & Risks
- Predicate allowlist changes can affect downstream verification policies; coordinate with Attestor and Policy owners.

69
docs/implplan/SPRINT_20260112_016_CLI_attest_verify_offline.md Normal file
View File

@@ -0,0 +1,69 @@
# Sprint 20260112-016-CLI-attest-verify-offline - Offline Attestation Verification CLI
## Topic & Scope
- Implement `stella attest verify --offline` CLI command for air-gapped attestation verification.
- Current state evidence: `RekorOfflineReceiptVerifier` exists in AirGap module but no CLI exposure (`src/AirGap/StellaOps.AirGap.Importer/Validation/RekorOfflineReceiptVerifier.cs`).
- Evidence to produce: CLI command implementation, bundled verification script generation, and golden test fixtures.
- **Working directory:** `src/Cli`.
- **Compliance item:** Item 1 - Attestation caching (offline).
## Dependencies & Concurrency
- Depends on existing `RekorOfflineReceiptVerifier` and `OfflineVerifier` services.
- Parallel safe with other CLI sprints; no shared DB migrations.
## Documentation Prerequisites
- `docs/README.md`
- `docs/modules/attestor/architecture.md`
- `docs/modules/airgap/guides/portable-evidence-bundle-verification.md`
- `docs/modules/cli/guides/commands/attest.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | ATTEST-CLI-001 | TODO | None | CLI Guild | Add `AttestCommandGroup.cs` with `verify` subcommand skeleton. |
| 2 | ATTEST-CLI-002 | TODO | ATTEST-CLI-001 | CLI Guild | Implement `--offline` flag with bundle path input, checkpoint path, and trust root options. |
| 3 | ATTEST-CLI-003 | TODO | ATTEST-CLI-002 | CLI Guild | Wire `RekorOfflineReceiptVerifier` for Merkle proof validation without network. |
| 4 | ATTEST-CLI-004 | TODO | ATTEST-CLI-002 | CLI Guild | Wire `OfflineVerifier` for DSSE envelope and org signature validation. |
| 5 | ATTEST-CLI-005 | TODO | ATTEST-CLI-003 | CLI Guild | Add JSON/text output formatters for verification results (pass/fail + details). |
| 6 | ATTEST-CLI-006 | TODO | ATTEST-CLI-004 | CLI Guild | Generate `VERIFY.md` script in exported bundles with sha256 + signature chain report. |
| 7 | ATTEST-CLI-007 | TODO | ATTEST-CLI-005 | Testing Guild | Create golden test fixtures for cross-platform bundle verification. |
| 8 | ATTEST-CLI-008 | TODO | ATTEST-CLI-007 | Testing Guild | Add determinism tests verifying identical results across Windows/Linux/macOS. |
| 9 | ATTEST-CLI-009 | TODO | ATTEST-CLI-006 | Docs Guild | Update `docs/modules/cli/guides/commands/attest.md` with verify subcommand documentation. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: offline attestation verification CLI. | Planning |
## Decisions & Risks
- Decide on trust root bundling format (PEM directory vs single bundle file).
- Checkpoint signature verification requires bundled public keys; document sourcing procedure.
- Cross-platform hash determinism must be validated (UTF-8 BOM handling, line endings).
## Acceptance Criteria
```bash
# Demo: Verify attestation bundle offline (Wi-Fi off)
stella attest verify --offline \
--bundle evidence.tar.gz \
--checkpoint checkpoint.sig \
--trust-root /path/to/roots/
# Expected output:
# Attestation Verification Report
# ================================
# Bundle: evidence.tar.gz
# Status: VERIFIED
#
# Checks:
# [PASS] DSSE envelope signature valid
# [PASS] Merkle inclusion proof verified (log index: 12345)
# [PASS] Checkpoint signature valid (origin: rekor.sigstore.dev)
# [PASS] Content hash matches manifest
#
# Artifact: sha256:abc123...
# Signed by: identity@example.com
# Timestamp: 2026-01-14T10:30:00Z
```
## Next Checkpoints
- TBD (set once staffed).

73
docs/implplan/SPRINT_20260112_016_CLI_sbom_verify_offline.md Normal file
View File

@@ -0,0 +1,73 @@
# Sprint 20260112-016-CLI-sbom-verify-offline - Offline SBOM Verification CLI
## Topic & Scope
- Implement `stella sbom verify` CLI command for offline signed SBOM archive verification.
- Current state evidence: SBOM export exists (`SbomExportService.cs`) but no verification CLI; signing exists in Signer module.
- Evidence to produce: CLI command, offline verification workflow, and integration with signed SBOM archive format.
- **Working directory:** `src/Cli`.
- **Compliance item:** Item 3 - Signed SBOM archives (immutable).
## Dependencies & Concurrency
- Depends on `SPRINT_20260112_016_SCANNER_signed_sbom_archive_spec` for archive format.
- Parallel safe with attestation verify sprint.
## Documentation Prerequisites
- `docs/README.md`
- `docs/modules/sbom-service/architecture.md`
- `docs/modules/signer/architecture.md`
- `docs/modules/cli/guides/commands/sbom.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | SBOM-CLI-001 | TODO | None | CLI Guild | Add `SbomCommandGroup.cs` with `verify` subcommand skeleton. |
| 2 | SBOM-CLI-002 | TODO | SBOM-CLI-001 | CLI Guild | Implement `--offline` flag with archive path, trust root, and output format options. |
| 3 | SBOM-CLI-003 | TODO | SBOM-CLI-002 | CLI Guild | Implement archive extraction and manifest hash validation. |
| 4 | SBOM-CLI-004 | TODO | SBOM-CLI-003 | CLI Guild | Wire DSSE envelope verification for SBOM payload signature. |
| 5 | SBOM-CLI-005 | TODO | SBOM-CLI-004 | CLI Guild | Validate SBOM schema (SPDX/CycloneDX) against bundled JSON schemas. |
| 6 | SBOM-CLI-006 | TODO | SBOM-CLI-005 | CLI Guild | Verify tool version metadata matches expected format. |
| 7 | SBOM-CLI-007 | TODO | SBOM-CLI-006 | CLI Guild | Add JSON/HTML verification report output with pass/fail status. |
| 8 | SBOM-CLI-008 | TODO | SBOM-CLI-007 | Testing Guild | Create unit tests for archive parsing, hash validation, and signature verification. |
| 9 | SBOM-CLI-009 | TODO | SBOM-CLI-008 | Testing Guild | Create integration tests with sample signed SBOM archives. |
| 10 | SBOM-CLI-010 | TODO | SBOM-CLI-009 | Docs Guild | Update `docs/modules/cli/guides/commands/sbom.md` with verify documentation. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: offline SBOM verification CLI. | Planning |
## Decisions & Risks
- Archive format must align with `SPRINT_20260112_016_SCANNER_signed_sbom_archive_spec`.
- Need to bundle JSON schemas for SPDX 2.3/3.0.1 and CycloneDX 1.4-1.7 for offline validation.
- Consider Fulcio root bundling for keyless signature verification in offline mode.
## Acceptance Criteria
```bash
# Demo: Verify signed SBOM archive offline
stella sbom verify \
--archive signed-sbom-sha256-abc123-20260115.tar.gz \
--offline \
--trust-root /path/to/roots/
# Expected output:
# SBOM Verification Report
# ========================
# Archive: signed-sbom-sha256-abc123-20260115.tar.gz
# Status: VERIFIED
#
# Checks:
# [PASS] Archive integrity (all hashes match manifest)
# [PASS] DSSE envelope signature valid
# [PASS] SBOM schema valid (SPDX 2.3)
# [PASS] Tool version present (StellaOps Scanner v2027.Q1)
# [PASS] Timestamp within validity window
#
# SBOM Details:
# Format: SPDX 2.3
# Components: 142
# Artifact: sha256:abc123...
# Generated: 2026-01-14T10:30:00Z
```
## Next Checkpoints
- TBD (set once staffed).

53
docs/implplan/SPRINT_20260112_016_DOCS_blue_green_deployment.md Normal file
View File

@@ -0,0 +1,53 @@
# Sprint 20260112-016-DOCS-blue-green-deployment - Blue/Green Deployment Documentation
## Topic & Scope
- Create comprehensive blue/green deployment documentation for platform-level upgrades with evidence continuity.
- Current state evidence: Multi-tenant policy rollout exists (`docs/flows/14-multi-tenant-policy-rollout-flow.md`) but no platform-level deployment guide.
- Evidence to produce: Deployment guide, upgrade runbook, and evidence continuity procedures.
- **Working directory:** `docs/operations`.
- **Compliance item:** Item 7 - Upgrade & evidence-migration paths.
## Dependencies & Concurrency
- Depends on understanding of existing backup/restore procedures (`docs/modules/authority/operations/backup-restore.md`).
- Parallel safe with all other sprints.
## Documentation Prerequisites
- `docs/README.md`
- `docs/db/MIGRATION_STRATEGY.md`
- `docs/releases/VERSIONING.md`
- `docs/flows/13-evidence-bundle-export-flow.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | BG-DOC-001 | TODO | None | Docs Guild | Create `docs/operations/blue-green-deployment.md` skeleton. |
| 2 | BG-DOC-002 | TODO | BG-DOC-001 | Docs Guild | Document blue/green environment setup (namespaces, DNS, load balancer). |
| 3 | BG-DOC-003 | TODO | BG-DOC-002 | Docs Guild | Document pre-deployment checklist (backup, evidence export, health checks). |
| 4 | BG-DOC-004 | TODO | BG-DOC-003 | Docs Guild | Document deployment sequence (deploy green, validate, switch traffic). |
| 5 | BG-DOC-005 | TODO | BG-DOC-004 | Docs Guild | Document health check timing and validation procedures. |
| 6 | BG-DOC-006 | TODO | BG-DOC-005 | Docs Guild | Document traffic switching procedure (gradual vs instant). |
| 7 | BG-DOC-007 | TODO | BG-DOC-006 | Docs Guild | Document rollback procedure with evidence preservation. |
| 8 | BG-DOC-008 | TODO | BG-DOC-007 | Docs Guild | Document evidence bundle continuity during cutover. |
| 9 | BG-DOC-009 | TODO | BG-DOC-008 | Docs Guild | Create `docs/operations/upgrade-runbook.md` with step-by-step procedures. |
| 10 | BG-DOC-010 | TODO | BG-DOC-009 | Docs Guild | Document evidence locker health checks and integrity validation. |
| 11 | BG-DOC-011 | TODO | BG-DOC-010 | Docs Guild | Document post-upgrade verification report generation. |
| 12 | BG-DOC-012 | TODO | BG-DOC-011 | DevOps Guild | Create Helm values examples for blue/green deployment. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: blue/green deployment documentation. | Planning |
## Decisions & Risks
- Blue/green requires double infrastructure; document cost implications.
- Database migrations must be backward-compatible (N-1 version) for safe rollback.
- Evidence bundles created during cutover may reference both environments.
## Acceptance Criteria
- Complete blue/green deployment guide with diagrams.
- Step-by-step upgrade runbook with evidence continuity focus.
- Rollback procedure that preserves all evidence integrity.
- Health check procedures specific to evidence services.
## Next Checkpoints
- TBD (set once staffed).

90
docs/implplan/SPRINT_20260112_016_SCANNER_signed_sbom_archive_spec.md Normal file
View File

@@ -0,0 +1,90 @@
# Sprint 20260112-016-SCANNER-signed-sbom-archive-spec - Signed SBOM Archive Format Specification
## Topic & Scope
- Define and implement unified signed SBOM archive format combining SBOM, signatures, metadata, and verification materials.
- Current state evidence: Evidence bundles exist (`EvidenceBundleExporter.cs`) but no SBOM-specific signed archive format.
- Evidence to produce: Format specification, exporter implementation, and documentation.
- **Working directory:** `src/Scanner`.
- **Compliance item:** Item 3 - Signed SBOM archives (immutable).
## Dependencies & Concurrency
- Depends on existing `SbomExportService` and `SignerPipeline`.
- Blocks `SPRINT_20260112_016_CLI_sbom_verify_offline`.
## Documentation Prerequisites
- `docs/README.md`
- `docs/modules/sbom-service/architecture.md`
- `docs/modules/signer/architecture.md`
- `docs/modules/attestor/bundle-format.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | SBOM-SPEC-001 | TODO | None | Scanner Guild | Create `docs/modules/scanner/signed-sbom-archive-spec.md` with format specification. |
| 2 | SBOM-SPEC-002 | TODO | SBOM-SPEC-001 | Scanner Guild | Define archive structure: sbom.{spdx,cdx}.json, sbom.dsse.json, manifest.json, metadata.json, certs/, schemas/. |
| 3 | SBOM-SPEC-003 | TODO | SBOM-SPEC-002 | Scanner Guild | Implement `SignedSbomArchiveBuilder` service in Scanner module. |
| 4 | SBOM-SPEC-004 | TODO | SBOM-SPEC-003 | Scanner Guild | Capture tool versions in metadata.json (stellaOpsVersion, scannerVersion, signerVersion). |
| 5 | SBOM-SPEC-005 | TODO | SBOM-SPEC-004 | Scanner Guild | Capture source container digest (Scanner image digest) in metadata. |
| 6 | SBOM-SPEC-006 | TODO | SBOM-SPEC-005 | Scanner Guild | Add manifest.json with file inventory and SHA-256 hashes. |
| 7 | SBOM-SPEC-007 | TODO | SBOM-SPEC-006 | Signer Guild | Sign manifest as separate DSSE envelope OR include in SBOM predicate. |
| 8 | SBOM-SPEC-008 | TODO | SBOM-SPEC-007 | Scanner Guild | Bundle Fulcio root + Rekor public log for offline verification. |
| 9 | SBOM-SPEC-009 | TODO | SBOM-SPEC-008 | Scanner Guild | Generate VERIFY.md with one-click verification instructions. |
| 10 | SBOM-SPEC-010 | TODO | SBOM-SPEC-009 | Scanner Guild | Add API endpoint `GET /scans/{scanId}/exports/signed-sbom-archive`. |
| 11 | SBOM-SPEC-011 | TODO | SBOM-SPEC-010 | Testing Guild | Create unit tests for archive structure and content. |
| 12 | SBOM-SPEC-012 | TODO | SBOM-SPEC-011 | Docs Guild | Update OpenAPI spec with new export endpoint. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: signed SBOM archive specification. | Planning |
## Archive Format Specification
```
signed-sbom-{artifact_digest_short}-{timestamp}.tar.gz
|
+-- sbom.spdx.json # OR sbom.cdx.json (CycloneDX)
+-- sbom.dsse.json # DSSE envelope with signature
+-- manifest.json # File inventory with SHA-256 hashes
+-- metadata.json # Tool versions, timestamps, generation info
+-- certs/
| +-- signing-cert.pem # Certificate chain from signer
| +-- fulcio-root.pem # Fulcio root CA (for offline keyless verify)
+-- rekor-proof/ # Optional transparency log proof
| +-- inclusion-proof.json
| +-- checkpoint.sig
+-- schemas/ # Bundled JSON schemas for offline validation
| +-- spdx-2.3-schema.json
| +-- cyclonedx-1.7-schema.json
+-- VERIFY.md # One-click verification instructions
```
### metadata.json Schema
```json
{
"schemaVersion": "1.0.0",
"stellaOpsVersion": "2027.Q1",
"scannerVersion": "1.2.3",
"scannerDigest": "sha256:abc123...",
"signerVersion": "1.0.0",
"sbomServiceVersion": "1.1.0",
"generatedAt": "2026-01-15T12:34:56Z",
"generatedAtHlc": "...",
"input": {
"imageRef": "myregistry/app:1.0",
"imageDigest": "sha256:def456..."
},
"reproducibility": {
"deterministic": true,
"expectedDigest": "sha256:..."
}
}
```
## Decisions & Risks
- Choose between signing manifest separately vs including manifest hash in SBOM predicate.
- RFC 3161 TSA integration deferred to Phase 3 (medium-term).
- Decide compression format: tar.gz vs tar.zst (zstd preferred for smaller size).
## Next Checkpoints
- TBD (set once staffed).

89
docs/implplan/SPRINT_20260112_017_ATTESTOR_checkpoint_divergence_detection.md Normal file
View File

@@ -0,0 +1,89 @@
# Sprint 20260112-017-ATTESTOR-checkpoint-divergence-detection - Checkpoint Divergence Detection
## Topic & Scope
- Implement root hash divergence detection and mismatch alarms for Rekor checkpoints.
- Current state evidence: Checkpoint verification exists but no active monitoring for conflicting checkpoints.
- Evidence to produce: Divergence detector, monotonicity checks, and alerting integration.
- **Working directory:** `src/Attestor`.
- **Compliance item:** Item 5 - Local Rekor (transparency) mirrors.
## Dependencies & Concurrency
- Depends on `SPRINT_20260112_017_ATTESTOR_periodic_rekor_sync` for checkpoint storage.
- Parallel safe with other Attestor sprints after checkpoint store is available.
## Documentation Prerequisites
- `docs/README.md`
- `docs/modules/attestor/architecture.md`
- `docs/modules/attestor/rekor-verification-design.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | DIVERGE-001 | TODO | REKOR-SYNC-002 | Attestor Guild | Create `ICheckpointDivergenceDetector` interface. |
| 2 | DIVERGE-002 | TODO | DIVERGE-001 | Attestor Guild | Implement root hash comparison at same tree size. |
| 3 | DIVERGE-003 | TODO | DIVERGE-002 | Attestor Guild | Implement monotonicity check (tree size only increases). |
| 4 | DIVERGE-004 | TODO | DIVERGE-003 | Attestor Guild | Detect rollback attempts (tree size regression). |
| 5 | DIVERGE-005 | TODO | DIVERGE-004 | Attestor Guild | Implement cross-log consistency check (primary vs mirror). |
| 6 | DIVERGE-006 | TODO | DIVERGE-005 | Attestor Guild | Add metric: `attestor.rekor_checkpoint_mismatch_total{backend,origin}`. |
| 7 | DIVERGE-007 | TODO | DIVERGE-006 | Attestor Guild | Add metric: `attestor.rekor_checkpoint_rollback_detected_total`. |
| 8 | DIVERGE-008 | TODO | DIVERGE-007 | Notify Guild | Integrate with Notify service for alert dispatch. |
| 9 | DIVERGE-009 | TODO | DIVERGE-008 | Attestor Guild | Create `CheckpointDivergenceEvent` for audit trail. |
| 10 | DIVERGE-010 | TODO | DIVERGE-009 | Testing Guild | Create unit tests for divergence detection scenarios. |
| 11 | DIVERGE-011 | TODO | DIVERGE-010 | Testing Guild | Create integration tests simulating Byzantine scenarios. |
| 12 | DIVERGE-012 | TODO | DIVERGE-011 | Docs Guild | Document divergence detection and incident response procedures. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: checkpoint divergence detection. | Planning |
## Technical Specification
### Divergence Detection Rules
| Check | Condition | Severity | Action |
|-------|-----------|----------|--------|
| Root mismatch | Same tree_size, different root_hash | CRITICAL | Alert + quarantine |
| Monotonicity violation | New tree_size < stored tree_size | CRITICAL | Alert + reject |
| Cross-log divergence | Primary root != mirror root at same size | WARNING | Alert + investigate |
| Stale checkpoint | Checkpoint age > threshold | WARNING | Alert |
### Alert Payload
```json
{
"eventType": "rekor.checkpoint.divergence",
"severity": "critical",
"origin": "rekor.sigstore.dev",
"treeSize": 12345678,
"expectedRootHash": "sha256:abc123...",
"actualRootHash": "sha256:def456...",
"detectedAt": "2026-01-15T12:34:56Z",
"backend": "sigstore-prod",
"description": "Checkpoint root hash mismatch detected. Possible split-view attack."
}
```
### Metrics
```
# Counter: total checkpoint mismatches
attestor_rekor_checkpoint_mismatch_total{backend="sigstore-prod",origin="rekor.sigstore.dev"} 0
# Counter: rollback attempts detected
attestor_rekor_checkpoint_rollback_detected_total{backend="sigstore-prod"} 0
# Gauge: seconds since last valid checkpoint
attestor_rekor_checkpoint_age_seconds{backend="sigstore-prod"} 120
```
## Decisions & Risks
- Define response to detected divergence: quarantine all proofs or alert-only.
- Cross-log divergence may indicate network partition vs attack.
- False positive handling for transient network issues.
## Acceptance Criteria
- Alert triggered within 1 minute of divergence detection.
- Metrics visible in Grafana dashboard.
- Audit trail for all divergence events.
- Runbook for incident response to checkpoint divergence.
## Next Checkpoints
- TBD (set once staffed).

101
docs/implplan/SPRINT_20260112_017_ATTESTOR_periodic_rekor_sync.md Normal file
View File

@@ -0,0 +1,101 @@
# Sprint 20260112-017-ATTESTOR-periodic-rekor-sync - Periodic Rekor Checkpoint Sync
## Topic & Scope
- Implement background service for periodic Rekor checkpoint and tile synchronization.
- Current state evidence: `HttpRekorTileClient` exists for on-demand fetching but no periodic sync service.
- Evidence to produce: Background sync service, local checkpoint storage, and tile caching.
- **Working directory:** `src/Attestor`.
- **Compliance item:** Item 5 - Local Rekor (transparency) mirrors.
## Dependencies & Concurrency
- Depends on existing `IRekorTileClient` implementation.
- Parallel safe with checkpoint divergence detection sprint.
## Documentation Prerequisites
- `docs/README.md`
- `docs/modules/attestor/architecture.md`
- `docs/modules/attestor/rekor-verification-design.md`
- `docs/modules/attestor/transparency.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | REKOR-SYNC-001 | TODO | None | Attestor Guild | Create `IRekorCheckpointStore` interface for local checkpoint persistence. |
| 2 | REKOR-SYNC-002 | TODO | REKOR-SYNC-001 | Attestor Guild | Implement `PostgresRekorCheckpointStore` for checkpoint storage. |
| 3 | REKOR-SYNC-003 | TODO | REKOR-SYNC-002 | Attestor Guild | Create `IRekorTileCache` interface for tile storage. |
| 4 | REKOR-SYNC-004 | TODO | REKOR-SYNC-003 | Attestor Guild | Implement `FileSystemRekorTileCache` for air-gapped tile storage. |
| 5 | REKOR-SYNC-005 | TODO | REKOR-SYNC-004 | Attestor Guild | Create `RekorSyncBackgroundService` as IHostedService. |
| 6 | REKOR-SYNC-006 | TODO | REKOR-SYNC-005 | Attestor Guild | Implement periodic checkpoint fetching (configurable interval, default 5 min). |
| 7 | REKOR-SYNC-007 | TODO | REKOR-SYNC-006 | Attestor Guild | Implement incremental tile sync (only new entries since last sync). |
| 8 | REKOR-SYNC-008 | TODO | REKOR-SYNC-007 | Attestor Guild | Add checkpoint signature verification during sync. |
| 9 | REKOR-SYNC-009 | TODO | REKOR-SYNC-008 | Attestor Guild | Add metrics: `attestor.rekor_sync_checkpoint_age_seconds`, `attestor.rekor_sync_tiles_cached`. |
| 10 | REKOR-SYNC-010 | TODO | REKOR-SYNC-009 | Testing Guild | Create unit tests for sync service and stores. |
| 11 | REKOR-SYNC-011 | TODO | REKOR-SYNC-010 | Testing Guild | Create integration tests with mock Rekor server. |
| 12 | REKOR-SYNC-012 | TODO | REKOR-SYNC-011 | Docs Guild | Document sync configuration options and operational procedures. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: periodic Rekor checkpoint sync. | Planning |
## Technical Specification
### Checkpoint Store Schema
```sql
CREATE TABLE attestor.rekor_checkpoints (
checkpoint_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
origin TEXT NOT NULL,
tree_size BIGINT NOT NULL,
root_hash BYTEA NOT NULL,
signature BYTEA NOT NULL,
fetched_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
verified BOOLEAN NOT NULL DEFAULT FALSE,
UNIQUE(origin, tree_size)
);
CREATE INDEX idx_rekor_checkpoints_origin_tree_size
ON attestor.rekor_checkpoints(origin, tree_size DESC);
```
### Tile Cache Structure
```
/var/lib/stellaops/rekor-cache/
+-- {origin}/
+-- checkpoints/
| +-- checkpoint-{tree_size}.sig
+-- tiles/
+-- level-0/
| +-- tile-{index}.bin
+-- level-1/
+-- tile-{index}.bin
```
### Configuration
```yaml
attestor:
rekor:
sync:
enabled: true
intervalMinutes: 5
maxCheckpointAgeDays: 30
tileCachePath: "/var/lib/stellaops/rekor-cache"
tileCacheSizeMb: 1024
backends:
- name: "sigstore-prod"
url: "https://rekor.sigstore.dev"
publicKeyPath: "/etc/stellaops/rekor-sigstore-prod.pub"
```
## Decisions & Risks
- Tile cache size management: LRU eviction vs time-based.
- Multiple Rekor backend support for redundancy.
- Network failure handling: exponential backoff with jitter.
## Acceptance Criteria
- Background service syncing checkpoints every 5 minutes.
- Offline verification using cached tiles (no network).
- Metrics dashboard showing cache health and sync lag.
## Next Checkpoints
- TBD (set once staffed).

82
docs/implplan/SPRINT_20260112_017_CRYPTO_pkcs11_hsm_implementation.md Normal file
View File

@@ -0,0 +1,82 @@
# Sprint 20260112-017-CRYPTO-pkcs11-hsm-implementation - PKCS#11 HSM Implementation
## Topic & Scope
- Complete PKCS#11 HSM integration using Net.Pkcs11Interop library.
- Current state evidence: `HsmPlugin` exists with stub implementation (`src/Cryptography/StellaOps.Cryptography.Plugin.Hsm/HsmPlugin.cs`), `Pkcs11HsmClient` throws `NotImplementedException`.
- Evidence to produce: Working PKCS#11 client, HSM connectivity validation, and operational runbook.
- **Working directory:** `src/Cryptography`.
- **Compliance item:** Item 4 - HSM / key escrow patterns.
## Dependencies & Concurrency
- Depends on Net.Pkcs11Interop NuGet package addition.
- Parallel safe with Rekor sync sprint.
## Documentation Prerequisites
- `docs/README.md`
- `docs/modules/signer/architecture.md`
- `docs/operations/key-rotation-runbook.md`
- `docs/modules/authority/operations/key-rotation.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | HSM-001 | TODO | None | Crypto Guild | Add Net.Pkcs11Interop NuGet package to `src/Directory.Packages.props`. |
| 2 | HSM-002 | TODO | HSM-001 | Crypto Guild | Implement `Pkcs11HsmClient.SignAsync()` with PKCS#11 session management. |
| 3 | HSM-003 | TODO | HSM-002 | Crypto Guild | Implement `Pkcs11HsmClient.VerifyAsync()` for signature verification. |
| 4 | HSM-004 | TODO | HSM-003 | Crypto Guild | Add session pooling and reconnection logic for HSM connection stability. |
| 5 | HSM-005 | TODO | HSM-004 | Crypto Guild | Implement multi-slot failover support. |
| 6 | HSM-006 | TODO | HSM-005 | Crypto Guild | Add key attribute enforcement (CKA_PRIVATE, CKA_EXTRACTABLE policy). |
| 7 | HSM-007 | TODO | HSM-006 | Crypto Guild | Implement `GetMetadataAsync()` for key versioning info. |
| 8 | HSM-008 | TODO | HSM-007 | Testing Guild | Create SoftHSM2 test fixtures for integration testing. |
| 9 | HSM-009 | TODO | HSM-008 | Testing Guild | Add unit tests for session management, signing, and verification. |
| 10 | HSM-010 | TODO | HSM-009 | Doctor Guild | Update `HsmConnectivityCheck` to validate actual PKCS#11 operations. |
| 11 | HSM-011 | TODO | HSM-010 | Docs Guild | Create `docs/operations/hsm-setup-runbook.md` with configuration guide. |
| 12 | HSM-012 | TODO | HSM-011 | Docs Guild | Document SoftHSM2 test environment setup for development. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: PKCS#11 HSM implementation. | Planning |
## Technical Specification
### Supported Mechanisms
| Algorithm | PKCS#11 Mechanism | Status |
|-----------|------------------|--------|
| RSA-SHA256 | CKM_SHA256_RSA_PKCS | TODO |
| RSA-SHA384 | CKM_SHA384_RSA_PKCS | TODO |
| RSA-SHA512 | CKM_SHA512_RSA_PKCS | TODO |
| RSA-PSS | CKM_SHA256_RSA_PKCS_PSS | TODO |
| ECDSA-P256 | CKM_ECDSA_SHA256 | TODO |
| ECDSA-P384 | CKM_ECDSA_SHA384 | TODO |
| AES-GCM-128 | CKM_AES_GCM | TODO |
| AES-GCM-256 | CKM_AES_GCM | TODO |
### Configuration
```yaml
signing:
provider: "hsm"
hsm:
type: "pkcs11"
libraryPath: "/opt/hsm/libpkcs11.so"
slotId: 0
pin: "${HSM_PIN}"
tokenLabel: "StellaOps"
connectionTimeoutSeconds: 30
maxSessions: 10
sessionIdleTimeoutSeconds: 300
```
## Decisions & Risks
- SoftHSM2 for testing vs real HSM for production validation.
- PIN management via environment variable or secrets manager.
- Session exhaustion recovery strategy.
## Acceptance Criteria
- Working signing and verification with SoftHSM2.
- Key rotation demonstration with attestation continuity.
- Doctor check validating HSM connectivity.
- Runbook with step-by-step HSM configuration.
## Next Checkpoints
- TBD (set once staffed).

109
docs/implplan/SPRINT_20260112_017_POLICY_cvss_threshold_gate.md Normal file
View File

@@ -0,0 +1,109 @@
# Sprint 20260112-017-POLICY-cvss-threshold-gate - CVSS Threshold Policy Gate
## Topic & Scope
- Implement dedicated `CvssThresholdGate` for static CVSS score enforcement.
- Current state evidence: EPSS quarantine rules exist (priority 20) but no explicit CVSS threshold gate class.
- Evidence to produce: Gate implementation, configuration, and documentation.
- **Working directory:** `src/Policy`.
- **Compliance item:** Item 6 - Offline policy engine (OPA/Conftest-class).
## Dependencies & Concurrency
- Depends on existing `IPolicyGate` interface.
- Parallel safe with SBOM presence gate sprint.
## Documentation Prerequisites
- `docs/README.md`
- `docs/modules/policy/architecture.md`
- `docs/modules/policy/determinization-api.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | CVSS-GATE-001 | DONE | None | Policy Guild | Create `CvssThresholdGate` class implementing `IPolicyGate`. |
| 2 | CVSS-GATE-002 | DONE | CVSS-GATE-001 | Policy Guild | Support CVSS v3.1 base score threshold configuration. |
| 3 | CVSS-GATE-003 | DONE | CVSS-GATE-002 | Policy Guild | Support CVSS v4.0 base score threshold configuration. |
| 4 | CVSS-GATE-004 | DONE | CVSS-GATE-003 | Policy Guild | Add per-environment threshold overrides (prod: 7.0, staging: 8.0, dev: 9.0). |
| 5 | CVSS-GATE-005 | DONE | CVSS-GATE-004 | Policy Guild | Add CVE allowlist/denylist support for exceptions. |
| 6 | CVSS-GATE-006 | DONE | CVSS-GATE-005 | Policy Guild | Implement offline operation (no external lookups). |
| 7 | CVSS-GATE-007 | DONE | CVSS-GATE-006 | Policy Guild | Register gate in `PolicyGateRegistry` with configurable priority. |
| 8 | CVSS-GATE-008 | DONE | CVSS-GATE-007 | Testing Guild | Create unit tests for threshold enforcement. |
| 9 | CVSS-GATE-009 | DONE | CVSS-GATE-008 | Testing Guild | Create tests for environment-specific overrides. |
| 10 | CVSS-GATE-010 | TODO | CVSS-GATE-009 | Docs Guild | Update policy architecture docs with CVSS gate. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: CVSS threshold policy gate. | Planning |
| 2026-01-15 | CVSS-GATE-001 to 007: Created CvssThresholdGate implementing IPolicyGate with full feature set. Options: Enabled, Priority, DefaultThreshold, per-environment Thresholds (prod/staging/dev), CvssVersionPreference (v3.1/v4.0/highest), Allowlist, Denylist, FailOnMissingCvss, RequireAllVersionsPass. Gate evaluates CVSS v3.1 and v4.0 scores, supports offline operation via injectable lookup or context metadata. Created CvssThresholdGateExtensions for DI registration and PolicyGateRegistry integration. CVSS-GATE-008/009: Created CvssThresholdGateTests with 20+ test cases covering: disabled gate, denylist/allowlist, missing CVSS handling, threshold enforcement at various score levels, environment-specific thresholds (staging/dev), version preference (v3.1/v4.0/highest), RequireAllVersionsPass mode, metadata fallback, case-insensitive CVE matching, and complete details in result. | Agent |
## Technical Specification
### Gate Configuration
```yaml
policy:
gates:
cvssThreshold:
enabled: true
priority: 15
defaultThreshold: 7.0
thresholds:
production: 7.0
staging: 8.0
development: 9.0
cvssVersionPreference: "v4.0" # v3.1, v4.0, or highest
allowlist:
- "CVE-2024-12345" # Known false positive
denylist:
- "CVE-2024-99999" # Always block
```
### Gate Interface
```csharp
public sealed class CvssThresholdGate : IPolicyGate
{
public string Name => "CvssThreshold";
public int Priority => _options.Priority;
public Task<GateResult> EvaluateAsync(
GateContext context,
CancellationToken ct)
{
var finding = context.Finding;
var environment = context.Environment;
// Get CVSS score (prefer v4.0 if available)
var cvssScore = GetCvssScore(finding, _options.CvssVersionPreference);
// Check denylist first
if (_options.Denylist.Contains(finding.CveId))
return Task.FromResult(GateResult.Blocked($"CVE {finding.CveId} is denylisted"));
// Check allowlist
if (_options.Allowlist.Contains(finding.CveId))
return Task.FromResult(GateResult.Passed("CVE is allowlisted"));
// Get environment-specific threshold
var threshold = GetThreshold(environment);
if (cvssScore >= threshold)
return Task.FromResult(GateResult.Blocked(
$"CVSS {cvssScore:F1} exceeds threshold {threshold:F1} for {environment}"));
return Task.FromResult(GateResult.Passed());
}
}
```
## Decisions & Risks
- CVSS v4.0 adoption is emerging; fallback to v3.1 required.
- Denylist takes precedence over allowlist.
- Offline operation means CVSS scores must be pre-populated in findings.
## Acceptance Criteria
- Gate blocks CVEs exceeding configured threshold.
- Environment-specific thresholds enforced correctly.
- Allowlist/denylist exceptions work as expected.
- Gate operates without network (offline determinism).
## Next Checkpoints
- TBD (set once staffed).

128
docs/implplan/SPRINT_20260112_017_POLICY_sbom_presence_gate.md Normal file
View File

@@ -0,0 +1,128 @@
# Sprint 20260112-017-POLICY-sbom-presence-gate - SBOM Presence Policy Gate
## Topic & Scope
- Implement dedicated `SbomPresenceGate` for SBOM inventory validation.
- Current state evidence: `SbomLineageEvidence` mentioned in config but no dedicated presence gate.
- Evidence to produce: Gate implementation, schema validation, and configuration.
- **Working directory:** `src/Policy`.
- **Compliance item:** Item 6 - Offline policy engine (OPA/Conftest-class).
## Dependencies & Concurrency
- Depends on existing `IPolicyGate` interface.
- Parallel safe with CVSS threshold gate sprint.
## Documentation Prerequisites
- `docs/README.md`
- `docs/modules/policy/architecture.md`
- `docs/modules/sbom-service/architecture.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | SBOM-GATE-001 | DONE | None | Policy Guild | Create `SbomPresenceGate` class implementing `IPolicyGate`. |
| 2 | SBOM-GATE-002 | DONE | SBOM-GATE-001 | Policy Guild | Require SBOM presence for release artifacts. |
| 3 | SBOM-GATE-003 | DONE | SBOM-GATE-002 | Policy Guild | Validate SBOM format (SPDX 2.3/3.0.1, CycloneDX 1.4-1.7). |
| 4 | SBOM-GATE-004 | DONE | SBOM-GATE-003 | Policy Guild | Validate SBOM schema against bundled JSON schemas. |
| 5 | SBOM-GATE-005 | DONE | SBOM-GATE-004 | Policy Guild | Check minimum component inventory (configurable threshold). |
| 6 | SBOM-GATE-006 | DONE | SBOM-GATE-005 | Policy Guild | Add per-environment enforcement levels (prod: required, dev: optional). |
| 7 | SBOM-GATE-007 | DONE | SBOM-GATE-006 | Policy Guild | Add SBOM signature verification requirement option. |
| 8 | SBOM-GATE-008 | DONE | SBOM-GATE-007 | Policy Guild | Register gate in `PolicyGateRegistry`. |
| 9 | SBOM-GATE-009 | DONE | SBOM-GATE-008 | Testing Guild | Create unit tests for presence and schema validation. |
| 10 | SBOM-GATE-010 | TODO | SBOM-GATE-009 | Docs Guild | Update policy architecture docs with SBOM gate. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: SBOM presence policy gate. | Planning |
| 2026-01-15 | SBOM-GATE-001 to 008: Created SbomPresenceGate implementing IPolicyGate. Options: Enabled, Priority, per-environment Enforcement (Required/Recommended/Optional), AcceptedFormats (spdx-2.2/2.3/3.0.1, cyclonedx-1.4-1.7), MinimumComponents, RequireSignature, SchemaValidation, RequirePrimaryComponent. Gate validates SBOM presence, format normalization (handles case variations, cdx alias), component count, schema validity, signature requirement, and primary component. Created SbomPresenceGateExtensions for DI and registry integration. SbomInfo record captures all SBOM metadata. SBOM-GATE-009: Created SbomPresenceGateTests with 25+ test cases covering: disabled gate, enforcement levels (optional/recommended/required), missing SBOM handling, valid SBOM, accepted formats, invalid formats, insufficient components, schema validation, signature requirements (missing/invalid/valid), primary component requirement, environment-specific enforcement, default enforcement fallback, metadata parsing, format normalization variations, and optional metadata inclusion. | Agent |
## Technical Specification
### Gate Configuration
```yaml
policy:
gates:
sbomPresence:
enabled: true
priority: 5
enforcement:
production: required
staging: required
development: optional
formats:
- "spdx-2.3"
- "spdx-3.0.1"
- "cyclonedx-1.4"
- "cyclonedx-1.5"
- "cyclonedx-1.6"
- "cyclonedx-1.7"
minimumComponents: 1
requireSignature: false
schemaValidation: true
```
### Gate Interface
```csharp
public sealed class SbomPresenceGate : IPolicyGate
{
public string Name => "SbomPresence";
public int Priority => _options.Priority;
public Task<GateResult> EvaluateAsync(
GateContext context,
CancellationToken ct)
{
var artifact = context.Artifact;
var environment = context.Environment;
// Get enforcement level for environment
var enforcement = GetEnforcementLevel(environment);
if (enforcement == EnforcementLevel.Optional)
return Task.FromResult(GateResult.Passed("SBOM optional for environment"));
// Check SBOM presence
var sbom = context.Evidence.GetSbom(artifact.Digest);
if (sbom is null)
return Task.FromResult(GateResult.Blocked("SBOM not found for artifact"));
// Validate format
if (!_options.Formats.Contains(sbom.Format))
return Task.FromResult(GateResult.Blocked(
$"SBOM format '{sbom.Format}' not in allowed list"));
// Validate schema
if (_options.SchemaValidation)
{
var schemaResult = ValidateSchema(sbom);
if (!schemaResult.IsValid)
return Task.FromResult(GateResult.Blocked(
$"SBOM schema validation failed: {schemaResult.Error}"));
}
// Check minimum components
if (sbom.ComponentCount < _options.MinimumComponents)
return Task.FromResult(GateResult.Blocked(
$"SBOM has {sbom.ComponentCount} components, minimum is {_options.MinimumComponents}"));
// Check signature if required
if (_options.RequireSignature && !sbom.IsSigned)
return Task.FromResult(GateResult.Blocked("SBOM signature required but not present"));
return Task.FromResult(GateResult.Passed());
}
}
```
## Decisions & Risks
- Schema validation requires bundling JSON schemas for offline operation.
- Minimum component threshold prevents empty SBOMs.
- Signature requirement may be too strict for some environments.
## Acceptance Criteria
- Gate blocks artifacts without SBOM in production.
- Schema validation works offline with bundled schemas.
- Environment-specific enforcement works correctly.
- Signature verification optional but functional.
## Next Checkpoints
- TBD (set once staffed).

150
docs/implplan/SPRINT_20260112_017_POLICY_signature_required_gate.md Normal file
View File

@@ -0,0 +1,150 @@
# Sprint 20260112-017-POLICY-signature-required-gate - Signature Required Policy Gate
## Topic & Scope
- Implement standalone `SignatureRequiredGate` for generic payload signature enforcement.
- Current state evidence: `VexProofGate` has `RequireSignedStatements` but no standalone signature gate.
- Evidence to produce: Generic gate implementation for any evidence type.
- **Working directory:** `src/Policy`.
- **Compliance item:** Item 6 - Offline policy engine (OPA/Conftest-class).
## Dependencies & Concurrency
- Depends on existing `IPolicyGate` interface.
- Parallel safe with other policy gate sprints.
## Documentation Prerequisites
- `docs/README.md`
- `docs/modules/policy/architecture.md`
- `docs/modules/signer/architecture.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | SIG-GATE-001 | DONE | None | Policy Guild | Create `SignatureRequiredGate` class implementing `IPolicyGate`. |
| 2 | SIG-GATE-002 | DONE | SIG-GATE-001 | Policy Guild | Configure required signatures per evidence type (SBOM, VEX, attestation). |
| 3 | SIG-GATE-003 | DONE | SIG-GATE-002 | Policy Guild | Validate DSSE envelope structure. |
| 4 | SIG-GATE-004 | DONE | SIG-GATE-003 | Policy Guild | Verify signature against trusted key set. |
| 5 | SIG-GATE-005 | DONE | SIG-GATE-004 | Policy Guild | Support keyless (Fulcio) signature verification with bundled roots. |
| 6 | SIG-GATE-006 | DONE | SIG-GATE-005 | Policy Guild | Add per-environment signature requirements. |
| 7 | SIG-GATE-007 | DONE | SIG-GATE-006 | Policy Guild | Add issuer/identity constraints (e.g., only accept signatures from specific emails). |
| 8 | SIG-GATE-008 | DONE | SIG-GATE-007 | Policy Guild | Register gate in `PolicyGateRegistry`. |
| 9 | SIG-GATE-009 | DONE | SIG-GATE-008 | Testing Guild | Create unit tests for signature validation scenarios. |
| 10 | SIG-GATE-010 | TODO | SIG-GATE-009 | Docs Guild | Update policy architecture docs with signature gate. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: signature required policy gate. | Planning |
| 2026-01-15 | SIG-GATE-001 to 008: Created SignatureRequiredGate implementing IPolicyGate. Options: Enabled, Priority, EvidenceTypes (per-type config with Required, TrustedIssuers with wildcard support, TrustedKeyIds, AcceptedAlgorithms), Environments (RequiredOverride, AdditionalIssuers, SkipEvidenceTypes), EnableKeylessVerification, FulcioRoots, RekorUrl, RequireTransparencyLogInclusion. SignatureInfo record captures EvidenceType, HasSignature, SignatureValid, Algorithm, SignerIdentity, KeyId, IsKeyless, HasTransparencyLogInclusion, CertificateChainValid, VerificationErrors. Gate validates per-evidence-type signatures with issuer wildcard matching (*@domain.com), algorithm enforcement (ES256/RS256/EdDSA), key ID constraints, keyless (Fulcio) verification with transparency log requirement, certificate chain validation, and environment-specific overrides. Created SignatureRequiredGateExtensions for DI and registry integration. SIG-GATE-009: Created SignatureRequiredGateTests with 18+ test cases covering: disabled gate, missing/invalid signatures, issuer validation with wildcards, algorithm enforcement, key ID constraints, keyless signatures with/without transparency log, keyless disabled, environment overrides (skip types, additional issuers), certificate chain validation, and subdomain wildcard matching. | Agent |
## Technical Specification
### Gate Configuration
```yaml
policy:
gates:
signatureRequired:
enabled: true
priority: 3
evidenceTypes:
sbom:
required: true
trustedIssuers:
- "build@company.com"
- "release@company.com"
vex:
required: true
trustedIssuers:
- "security@company.com"
attestation:
required: true
trustedIssuers:
- "*@company.com" # Wildcard support
keylessVerification:
enabled: true
fulcioRootPath: "/etc/stellaops/fulcio-root.pem"
rekorPublicKeyPath: "/etc/stellaops/rekor.pub"
enforcement:
production: required
staging: required
development: optional
```
### Gate Interface
```csharp
public sealed class SignatureRequiredGate : IPolicyGate
{
public string Name => "SignatureRequired";
public int Priority => _options.Priority;
public Task<GateResult> EvaluateAsync(
GateContext context,
CancellationToken ct)
{
var environment = context.Environment;
var enforcement = GetEnforcementLevel(environment);
if (enforcement == EnforcementLevel.Optional)
return Task.FromResult(GateResult.Passed("Signatures optional"));
var failures = new List<string>();
foreach (var evidence in context.Evidence.All)
{
var config = GetEvidenceConfig(evidence.Type);
if (!config.Required) continue;
// Check signature presence
if (evidence.Signature is null)
{
failures.Add($"{evidence.Type}: No signature present");
continue;
}
// Validate DSSE envelope
var dsseResult = ValidateDsseEnvelope(evidence.Signature);
if (!dsseResult.IsValid)
{
failures.Add($"{evidence.Type}: Invalid DSSE - {dsseResult.Error}");
continue;
}
// Verify signature
var verifyResult = await VerifySignatureAsync(
evidence.Signature,
config.TrustedIssuers,
ct);
if (!verifyResult.IsValid)
{
failures.Add($"{evidence.Type}: Signature invalid - {verifyResult.Error}");
continue;
}
// Check issuer constraints
if (!MatchesIssuerConstraints(verifyResult.Issuer, config.TrustedIssuers))
{
failures.Add($"{evidence.Type}: Issuer '{verifyResult.Issuer}' not trusted");
}
}
if (failures.Count > 0)
return Task.FromResult(GateResult.Blocked(string.Join("; ", failures)));
return Task.FromResult(GateResult.Passed());
}
}
```
## Decisions & Risks
- Wildcard issuer matching syntax (e.g., `*@company.com`).
- Keyless verification requires bundled Fulcio root for offline.
- Performance impact of signature verification on every evaluation.
## Acceptance Criteria
- Gate blocks unsigned evidence when required.
- Issuer constraints enforced correctly.
- Keyless verification works offline with bundled roots.
- Environment-specific enforcement works correctly.
## Next Checkpoints
- TBD (set once staffed).

157
docs/implplan/SPRINT_20260112_018_AUTH_local_rbac_fallback.md Normal file
View File

@@ -0,0 +1,157 @@
# Sprint 20260112-018-AUTH-local-rbac-fallback - Local RBAC Policy Fallback
## Topic & Scope
- Implement local file-based RBAC policy fallback for offline/air-gapped Authority operation.
- Current state evidence: Authority is PostgreSQL-only; no local policy fallback exists.
- Evidence to produce: File-based policy store, fallback mechanism, and break-glass account.
- **Working directory:** `src/Authority`.
- **Compliance item:** Item 2 - Offline RBAC & break-glass.
## Dependencies & Concurrency
- Depends on existing Authority architecture understanding.
- Parallel safe with other Authority sprints.
## Documentation Prerequisites
- `docs/README.md`
- `docs/modules/authority/architecture.md`
- `docs/modules/authority/AUTHORITY.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | RBAC-001 | DONE | None | Authority Guild | Create `ILocalPolicyStore` interface. |
| 2 | RBAC-002 | DONE | RBAC-001 | Authority Guild | Implement `FileBasedPolicyStore` with YAML/JSON policy files. |
| 3 | RBAC-003 | DONE | RBAC-002 | Authority Guild | Define local policy file schema (roles, scopes, subjects). |
| 4 | RBAC-004 | DONE | RBAC-003 | Authority Guild | Implement policy file hot-reload with inotify/FileSystemWatcher. |
| 5 | RBAC-005 | DONE | RBAC-004 | Authority Guild | Create fallback mechanism when PostgreSQL is unavailable. |
| 6 | RBAC-006 | DONE | RBAC-005 | Authority Guild | Implement break-glass account with bootstrap credentials. |
| 7 | RBAC-007 | DONE | RBAC-006 | Authority Guild | Add break-glass usage audit logging (mandatory reason codes). |
| 8 | RBAC-008 | DONE | RBAC-007 | Authority Guild | Implement automatic break-glass session timeout (configurable, default 15 min). |
| 9 | RBAC-009 | DONE | RBAC-008 | Authority Guild | Add break-glass session extension with re-authentication. |
| 10 | RBAC-010 | TODO | RBAC-009 | AirGap Guild | Include local policy in Offline Kit bundles. |
| 11 | RBAC-011 | DONE | RBAC-010 | Testing Guild | Create unit tests for local policy store. |
| 12 | RBAC-012 | TODO | RBAC-011 | Testing Guild | Create integration tests for fallback scenarios. |
| 13 | RBAC-013 | TODO | RBAC-012 | Docs Guild | Create break-glass account runbook. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: local RBAC policy fallback. | Planning |
| 2026-01-15 | RBAC-001: Created ILocalPolicyStore interface with GetPolicyAsync, GetSubjectRolesAsync, GetRoleScopesAsync, HasScopeAsync, GetSubjectScopesAsync, ValidateBreakGlassCredentialAsync, IsAvailableAsync, ReloadAsync, and PolicyReloaded event. RBAC-002/003/004: Created FileBasedPolicyStore implementing ILocalPolicyStore with YAML/JSON loading via YamlDotNet, FileSystemWatcher hot-reload with debouncing, role inheritance resolution, subject index with tenant/expiration checks, schema version validation. Created LocalPolicyModels with LocalPolicy, LocalRole, LocalSubject, BreakGlassConfig, BreakGlassAccount, BreakGlassSession records. Created LocalPolicyStoreOptions with PolicyFilePath, EnableHotReload, RequireSignature, FallbackBehavior, SupportedSchemaVersions. RBAC-005: Created FallbackPolicyStore with IPrimaryPolicyStoreHealthCheck integration, PolicyStoreMode enum (Primary/Fallback/Degraded), automatic failover after FailureThreshold consecutive failures, recovery with MinFallbackDurationMs cooldown, ModeChanged event. RBAC-006/007/008/009: Created BreakGlassSessionManager with IBreakGlassSessionManager interface, session creation with credential validation (bcrypt), mandatory reason codes from AllowedReasonCodes, configurable SessionTimeoutMinutes (default 15), MaxExtensions with re-authentication, automatic expired session cleanup, IBreakGlassAuditLogger with BreakGlassAuditEvent (SessionCreated/Extended/Terminated/Expired/AuthenticationFailed/InvalidReasonCode/MaxExtensionsReached). RBAC-011: Created FileBasedPolicyStoreTests with 15+ unit tests covering policy serialization, role inheritance, subject enable/expiration, break-glass config, session validity, options defaults, mode change events. | Agent |
## Technical Specification
### Local Policy File Schema
```yaml
# /etc/stellaops/authority/local-policy.yaml
schemaVersion: "1.0.0"
lastUpdated: "2026-01-15T12:00:00Z"
signatureRequired: true
signature: "base64-encoded-dsse-signature"
roles:
- name: "admin"
scopes:
- "authority:read"
- "authority:write"
- "platform:admin"
- name: "operator"
scopes:
- "orch:operate"
- "orch:view"
- name: "auditor"
scopes:
- "audit:read"
- "obs:incident"
subjects:
- id: "user@company.com"
roles: ["admin"]
tenant: "default"
- id: "ops@company.com"
roles: ["operator"]
tenant: "default"
breakGlass:
enabled: true
accounts:
- id: "break-glass-admin"
passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$..."
roles: ["admin"]
sessionTimeoutMinutes: 15
maxExtensions: 2
requireReasonCode: true
allowedReasonCodes:
- "emergency-incident"
- "database-outage"
- "security-event"
- "scheduled-maintenance"
```
### Break-Glass Audit Event
```json
{
"eventType": "authority.break_glass.activated",
"severity": "warning",
"accountId": "break-glass-admin",
"reasonCode": "database-outage",
"reasonDetails": "PostgreSQL cluster unreachable",
"activatedAt": "2026-01-15T12:34:56Z",
"sessionId": "bg-session-abc123",
"expiresAt": "2026-01-15T12:49:56Z",
"clientIp": "10.0.0.5",
"userAgent": "StellaOps-CLI/2027.Q1"
}
```
### Configuration
```yaml
authority:
localPolicy:
enabled: true
policyPath: "/etc/stellaops/authority/local-policy.yaml"
fallbackMode: "on_db_unavailable" # on_db_unavailable, always_local, hybrid
reloadIntervalSeconds: 30
requireSignature: true
signaturePublicKeyPath: "/etc/stellaops/authority/policy-signing.pub"
breakGlass:
enabled: true
maxSessionMinutes: 60
alertOnActivation: true
alertChannels: ["email", "slack", "pagerduty"]
```
### Fallback Logic
```csharp
public async Task<AuthorizationResult> AuthorizeAsync(
AuthorizationRequest request,
CancellationToken ct)
{
// Try PostgreSQL first
if (await _postgresStore.IsAvailableAsync(ct))
{
return await _postgresStore.AuthorizeAsync(request, ct);
}
// Fallback to local policy
_logger.LogWarning("PostgreSQL unavailable, using local policy fallback");
_metrics.IncrementFallbackActivations();
return await _localPolicyStore.AuthorizeAsync(request, ct);
}
```
## Decisions & Risks
- Local policy must be signed to prevent tampering.
- Break-glass password storage: Argon2id hash in file.
- Alert-on-activation to notify security team.
- Policy sync between PostgreSQL and local file.
## Acceptance Criteria
- Local policy fallback activates when PostgreSQL unavailable.
- Break-glass account authenticates with reason code.
- Session timeout enforced with audit trail.
- Alert dispatched on break-glass activation.
## Next Checkpoints
- TBD (set once staffed).

143
docs/implplan/SPRINT_20260112_018_CRYPTO_key_escrow_shamir.md Normal file
View File

@@ -0,0 +1,143 @@
# Sprint 20260112-018-CRYPTO-key-escrow-shamir - Key Escrow with Shamir Secret Sharing
## Topic & Scope
- Implement key escrow mechanisms using Shamir's Secret Sharing for key recovery.
- Current state evidence: No key recovery or escrow mechanisms exist.
- Evidence to produce: Shamir splitting, escrow storage, and recovery procedures.
- **Working directory:** `src/Cryptography`.
- **Compliance item:** Item 4 - HSM / key escrow patterns.
## Dependencies & Concurrency
- Depends on `SPRINT_20260112_018_SIGNER_dual_control_ceremonies` for recovery ceremony.
- Parallel safe with other crypto sprints.
## Documentation Prerequisites
- `docs/README.md`
- `docs/modules/signer/architecture.md`
- `docs/operations/key-rotation-runbook.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | ESCROW-001 | TODO | None | Crypto Guild | Implement `ShamirSecretSharing` class with split/combine operations. |
| 2 | ESCROW-002 | TODO | ESCROW-001 | Crypto Guild | Use GF(2^8) for byte-level secret sharing. |
| 3 | ESCROW-003 | TODO | ESCROW-002 | Crypto Guild | Create `IKeyEscrowService` interface. |
| 4 | ESCROW-004 | TODO | ESCROW-003 | Crypto Guild | Implement key splitting with configurable M-of-N threshold. |
| 5 | ESCROW-005 | TODO | ESCROW-004 | Crypto Guild | Create `KeyShare` record with share index, data, and metadata. |
| 6 | ESCROW-006 | TODO | ESCROW-005 | Crypto Guild | Implement encrypted share storage (shares encrypted at rest). |
| 7 | ESCROW-007 | TODO | ESCROW-006 | Crypto Guild | Create `IEscrowAgentStore` interface for share custody. |
| 8 | ESCROW-008 | TODO | ESCROW-007 | Crypto Guild | Implement share distribution to escrow agents. |
| 9 | ESCROW-009 | TODO | ESCROW-008 | Crypto Guild | Create key recovery workflow with share collection. |
| 10 | ESCROW-010 | TODO | ESCROW-009 | Crypto Guild | Integrate with dual-control ceremonies for recovery authorization. |
| 11 | ESCROW-011 | TODO | ESCROW-010 | Testing Guild | Create unit tests for Shamir splitting/combining. |
| 12 | ESCROW-012 | TODO | ESCROW-011 | Testing Guild | Create integration tests for recovery workflow. |
| 13 | ESCROW-013 | TODO | ESCROW-012 | Docs Guild | Create key escrow and recovery runbook. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: key escrow with Shamir secret sharing. | Planning |
## Technical Specification
### Shamir Secret Sharing
```csharp
public sealed class ShamirSecretSharing
{
/// <summary>
/// Split a secret into N shares where any M shares can reconstruct.
/// Uses GF(2^8) arithmetic for byte-level operations.
/// </summary>
public IReadOnlyList<KeyShare> Split(
byte[] secret,
int threshold, // M - minimum shares needed
int totalShares, // N - total shares created
IGuidGenerator guidGenerator,
TimeProvider timeProvider)
{
// Validate: 2 <= M <= N <= 255
// For each byte of secret:
// 1. Generate random polynomial of degree M-1 with secret as constant term
// 2. Evaluate polynomial at points 1..N
// 3. Store evaluation results as share data
}
/// <summary>
/// Reconstruct secret from M or more shares using Lagrange interpolation.
/// </summary>
public byte[] Combine(IReadOnlyList<KeyShare> shares)
{
// Validate: shares.Count >= threshold
// Use Lagrange interpolation at x=0 to recover constant term (secret)
}
}
```
### Key Share Model
```csharp
public sealed record KeyShare
{
public required Guid ShareId { get; init; }
public required int Index { get; init; } // 1..N
public required byte[] EncryptedData { get; init; }
public required string KeyId { get; init; }
public required int Threshold { get; init; }
public required int TotalShares { get; init; }
public required DateTimeOffset CreatedAt { get; init; }
public required DateTimeOffset ExpiresAt { get; init; }
public required string CustodianId { get; init; }
public required string ChecksumHex { get; init; } // SHA-256 of unencrypted share
}
```
### Escrow Agent Configuration
```yaml
cryptography:
escrow:
enabled: true
defaultThreshold: 3
defaultTotalShares: 5
shareEncryptionKeyPath: "/etc/stellaops/escrow-encryption.key"
agents:
- id: "escrow-agent-1"
name: "Primary Security Officer"
email: "cso@company.com"
publicKeyPath: "/etc/stellaops/escrow-agents/agent1.pub"
- id: "escrow-agent-2"
name: "Backup Security Officer"
email: "backup-cso@company.com"
publicKeyPath: "/etc/stellaops/escrow-agents/agent2.pub"
- id: "escrow-agent-3"
name: "External Custodian"
email: "custodian@escrow-service.com"
publicKeyPath: "/etc/stellaops/escrow-agents/agent3.pub"
shareRetentionDays: 365
autoDeleteOnRecovery: false
```
### Recovery Workflow
```
1. Recovery request initiated (requires dual-control ceremony)
2. Notify escrow agents of recovery request
3. Each agent authenticates and submits their share
4. System collects shares until threshold reached
5. Secret reconstructed using Lagrange interpolation
6. Key imported/restored to target HSM or keystore
7. Recovery audit event logged
8. (Optional) Shares re-generated with new random polynomial
```
## Decisions & Risks
- Share storage security: encrypt shares at rest with separate key.
- Agent identity verification during recovery.
- Re-escrow after recovery to prevent share replay.
- External escrow agent integration complexity.
## Acceptance Criteria
- 3-of-5 Shamir splitting demonstrated.
- Key recovery from 3 shares successful.
- Escrow agent notification workflow functional.
- Recovery audit trail complete.
## Next Checkpoints
- TBD (set once staffed).

131
docs/implplan/SPRINT_20260112_018_DOCS_upgrade_runbook_evidence_continuity.md Normal file
View File

@@ -0,0 +1,131 @@
# Sprint 20260112-018-DOCS-upgrade-runbook-evidence-continuity - Upgrade Runbook with Evidence Continuity
## Topic & Scope
- Create comprehensive upgrade runbook with evidence continuity procedures.
- Current state evidence: DB migrations documented but no evidence-focused upgrade guide.
- Evidence to produce: Step-by-step runbook, pre-flight checklists, and validation procedures.
- **Working directory:** `docs/operations`.
- **Compliance item:** Item 7 - Upgrade & evidence-migration paths.
## Dependencies & Concurrency
- Depends on `SPRINT_20260112_016_DOCS_blue_green_deployment` for deployment procedures.
- Depends on `SPRINT_20260112_018_EVIDENCE_reindex_tooling` for CLI commands.
- Parallel safe with implementation sprints.
## Documentation Prerequisites
- `docs/README.md`
- `docs/db/MIGRATION_STRATEGY.md`
- `docs/releases/VERSIONING.md`
- `docs/flows/13-evidence-bundle-export-flow.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | RUNBOOK-001 | TODO | None | Docs Guild | Create `docs/operations/upgrade-runbook.md` structure. |
| 2 | RUNBOOK-002 | TODO | RUNBOOK-001 | Docs Guild | Document pre-upgrade checklist (backup, health checks, evidence export). |
| 3 | RUNBOOK-003 | TODO | RUNBOOK-002 | Docs Guild | Document evidence integrity pre-flight validation. |
| 4 | RUNBOOK-004 | TODO | RUNBOOK-003 | Docs Guild | Document database backup procedures with evidence focus. |
| 5 | RUNBOOK-005 | TODO | RUNBOOK-004 | Docs Guild | Document step-by-step upgrade sequence. |
| 6 | RUNBOOK-006 | TODO | RUNBOOK-005 | Docs Guild | Document evidence reindex procedures (reference CLI sprint). |
| 7 | RUNBOOK-007 | TODO | RUNBOOK-006 | Docs Guild | Document chain-of-custody verification steps. |
| 8 | RUNBOOK-008 | TODO | RUNBOOK-007 | Docs Guild | Document post-upgrade validation checklist. |
| 9 | RUNBOOK-009 | TODO | RUNBOOK-008 | Docs Guild | Document rollback procedures with evidence considerations. |
| 10 | RUNBOOK-010 | TODO | RUNBOOK-009 | Docs Guild | Document breaking changes matrix per version. |
| 11 | RUNBOOK-011 | TODO | RUNBOOK-010 | Docs Guild | Create `docs/operations/evidence-migration.md` for detailed procedures. |
| 12 | RUNBOOK-012 | TODO | RUNBOOK-011 | Docs Guild | Document air-gap upgrade path with evidence handling. |
| 13 | RUNBOOK-013 | TODO | RUNBOOK-012 | Docs Guild | Create troubleshooting section for common upgrade issues. |
| 14 | RUNBOOK-014 | TODO | RUNBOOK-013 | Docs Guild | Add version-specific migration notes template. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: upgrade runbook with evidence continuity. | Planning |
## Runbook Outline
### 1. Pre-Upgrade Phase
```markdown
## Pre-Upgrade Checklist
### 1.1 Environment Assessment
- [ ] Current version identified
- [ ] Target version confirmed compatible (see compatibility matrix)
- [ ] Resource requirements verified (CPU, memory, storage)
- [ ] Maintenance window scheduled
### 1.2 Backup Procedures
- [ ] PostgreSQL full backup completed
- [ ] Evidence Locker export completed (all tenants)
- [ ] Attestation bundles archived
- [ ] Configuration files backed up
- [ ] Backup integrity verified
### 1.3 Evidence Integrity Pre-Flight
- [ ] Run `stella evidence verify-all --output pre-upgrade-report.json`
- [ ] Verify all Merkle roots valid
- [ ] Export root cross-reference baseline
- [ ] Document current evidence count by type
### 1.4 Health Checks
- [ ] All services healthy (green status)
- [ ] No pending migrations
- [ ] Queue depths at zero
- [ ] Recent scan/attestation successful
```
### 2. Upgrade Phase
```markdown
## Upgrade Sequence
### 2.1 Blue/Green Preparation
- [ ] Deploy green environment with new version
- [ ] Apply database migrations (Category A: startup)
- [ ] Verify green environment health
### 2.2 Evidence Migration
- [ ] Run `stella evidence migrate --dry-run` on green
- [ ] Review migration impact report
- [ ] Execute evidence migration if needed
- [ ] Verify evidence integrity post-migration
### 2.3 Traffic Cutover
- [ ] Switch traffic to green (gradual or instant)
- [ ] Monitor error rates and latency
- [ ] Verify all services responding correctly
```
### 3. Post-Upgrade Phase
```markdown
## Post-Upgrade Validation
### 3.1 Evidence Continuity Verification
- [ ] Run `stella evidence verify-continuity --pre pre-upgrade-report.json`
- [ ] Confirm chain-of-custody preserved
- [ ] Verify artifact digests unchanged
- [ ] Generate continuity report for audit
### 3.2 Functional Validation
- [ ] Execute smoke test suite
- [ ] Verify scan capability
- [ ] Verify attestation generation
- [ ] Verify policy evaluation
### 3.3 Cleanup
- [ ] Decommission blue environment (after observation period)
- [ ] Archive upgrade artifacts
- [ ] Update documentation with version
```
## Decisions & Risks
- Minimum observation period before blue decommission (recommend 72 hours).
- Evidence export timing (before or during maintenance window).
- Rollback trigger criteria definition.
## Acceptance Criteria
- Complete runbook with all checklists.
- Evidence-focused procedures clearly documented.
- Rollback procedures tested and validated.
- Troubleshooting section covers common issues.
## Next Checkpoints
- TBD (set once staffed).

157
docs/implplan/SPRINT_20260112_018_EVIDENCE_reindex_tooling.md Normal file
View File

@@ -0,0 +1,157 @@
# Sprint 20260112-018-EVIDENCE-reindex-tooling - Evidence Re-Index Tooling
## Topic & Scope
- Implement CLI tooling for evidence re-indexing and chain-of-custody verification after upgrades.
- Current state evidence: Evidence bundles exist but no re-indexing or migration tooling.
- Evidence to produce: CLI commands, migration scripts, and verification reports.
- **Working directory:** `src/Cli`, `src/EvidenceLocker`.
- **Compliance item:** Item 7 - Upgrade & evidence-migration paths.
## Dependencies & Concurrency
- Depends on `SPRINT_20260112_016_DOCS_blue_green_deployment` for upgrade procedures.
- Parallel safe with other Evidence sprints.
## Documentation Prerequisites
- `docs/README.md`
- `docs/flows/13-evidence-bundle-export-flow.md`
- `docs/db/MIGRATION_STRATEGY.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | REINDEX-001 | TODO | None | CLI Guild | Add `stella evidence reindex` command skeleton. |
| 2 | REINDEX-002 | TODO | REINDEX-001 | CLI Guild | Implement `--dry-run` mode for impact assessment. |
| 3 | REINDEX-003 | TODO | REINDEX-002 | Evidence Guild | Create `IEvidenceReindexService` interface. |
| 4 | REINDEX-004 | TODO | REINDEX-003 | Evidence Guild | Implement Merkle root recomputation from existing evidence. |
| 5 | REINDEX-005 | TODO | REINDEX-004 | Evidence Guild | Create old/new root cross-reference mapping. |
| 6 | REINDEX-006 | TODO | REINDEX-005 | Evidence Guild | Implement chain-of-custody verification (old proofs still valid). |
| 7 | REINDEX-007 | TODO | REINDEX-006 | Evidence Guild | Add `stella evidence verify-continuity` command. |
| 8 | REINDEX-008 | TODO | REINDEX-007 | Evidence Guild | Generate verification report (JSON, HTML formats). |
| 9 | REINDEX-009 | TODO | REINDEX-008 | CLI Guild | Add `stella evidence migrate` command for schema migrations. |
| 10 | REINDEX-010 | TODO | REINDEX-009 | Evidence Guild | Implement batch processing with progress reporting. |
| 11 | REINDEX-011 | TODO | REINDEX-010 | Evidence Guild | Add rollback capability for failed migrations. |
| 12 | REINDEX-012 | TODO | REINDEX-011 | Testing Guild | Create unit tests for reindex operations. |
| 13 | REINDEX-013 | TODO | REINDEX-012 | Testing Guild | Create integration tests with sample evidence bundles. |
| 14 | REINDEX-014 | TODO | REINDEX-013 | Docs Guild | Document evidence migration procedures in upgrade runbook. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: evidence re-index tooling. | Planning |
## Technical Specification
### CLI Commands
```bash
# Dry-run reindex to assess impact
stella evidence reindex --dry-run --since 2026-01-01
# Execute reindex with progress
stella evidence reindex --since 2026-01-01 --batch-size 100
# Verify chain-of-custody after upgrade
stella evidence verify-continuity \
--old-root sha256:abc123... \
--new-root sha256:def456... \
--output report.html
# Migrate evidence schema
stella evidence migrate \
--from-version 1.0 \
--to-version 2.0 \
--dry-run
# Generate upgrade readiness report
stella evidence upgrade-check --target-version 2027.Q2
```
### Reindex Service Interface
```csharp
public interface IEvidenceReindexService
{
/// <summary>
/// Recompute Merkle roots for evidence bundles.
/// </summary>
Task<ReindexResult> ReindexAsync(
ReindexOptions options,
IProgress<ReindexProgress> progress,
CancellationToken ct);
/// <summary>
/// Verify chain-of-custody between old and new roots.
/// </summary>
Task<ContinuityVerificationResult> VerifyContinuityAsync(
string oldRoot,
string newRoot,
CancellationToken ct);
/// <summary>
/// Generate cross-reference mapping between old and new roots.
/// </summary>
Task<RootCrossReferenceMap> GenerateCrossReferenceAsync(
DateTimeOffset since,
CancellationToken ct);
}
```
### Cross-Reference Map
```json
{
"schemaVersion": "1.0.0",
"generatedAt": "2026-01-15T12:34:56Z",
"fromVersion": "2027.Q1",
"toVersion": "2027.Q2",
"entries": [
{
"bundleId": "bundle-abc123",
"oldRoot": "sha256:old123...",
"newRoot": "sha256:new456...",
"evidenceCount": 15,
"verified": true,
"digestsPreserved": true
}
],
"summary": {
"totalBundles": 1500,
"successfulMigrations": 1498,
"failedMigrations": 2,
"digestsPreserved": 1500
}
}
```
### Verification Report
```html
<!DOCTYPE html>
<html>
<head>
<title>Evidence Continuity Report - 2027.Q1 to 2027.Q2</title>
</head>
<body>
<h1>Evidence Continuity Verification Report</h1>
<h2>Summary</h2>
<ul>
<li>Upgrade: 2027.Q1 -> 2027.Q2</li>
<li>Bundles Verified: 1500</li>
<li>Chain-of-Custody: PRESERVED</li>
<li>Artifact Digests: UNCHANGED</li>
</ul>
<h2>Details</h2>
<!-- Bundle-by-bundle verification results -->
</body>
</html>
```
## Decisions & Risks
- Batch size tuning for large evidence stores.
- Rollback strategy for partial failures.
- Digest preservation guarantee documentation.
## Acceptance Criteria
- Dry-run mode shows accurate impact assessment.
- Reindex completes with progress reporting.
- Continuity verification confirms chain-of-custody.
- HTML report suitable for auditor review.
## Next Checkpoints
- TBD (set once staffed).

143
docs/implplan/SPRINT_20260112_018_SIGNER_dual_control_ceremonies.md Normal file
View File

@@ -0,0 +1,143 @@
# Sprint 20260112-018-SIGNER-dual-control-ceremonies - Dual-Control Signing Ceremonies
## Topic & Scope
- Implement M-of-N threshold signing ceremonies for high-assurance key operations.
- Current state evidence: Key rotation service exists but no dual-control or threshold signing.
- Evidence to produce: Ceremony protocol, approval workflow, and audit trail.
- **Working directory:** `src/Signer`.
- **Compliance item:** Item 4 - HSM / key escrow patterns.
## Dependencies & Concurrency
- Depends on `SPRINT_20260112_017_CRYPTO_pkcs11_hsm_implementation` for HSM integration.
- Parallel safe with key escrow sprint.
## Documentation Prerequisites
- `docs/README.md`
- `docs/modules/signer/architecture.md`
- `docs/operations/key-rotation-runbook.md`
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | DUAL-001 | DONE | None | Signer Guild | Design M-of-N ceremony protocol specification. |
| 2 | DUAL-002 | DONE | DUAL-001 | Signer Guild | Create `ICeremonyOrchestrator` interface. |
| 3 | DUAL-003 | DONE | DUAL-002 | Signer Guild | Implement ceremony state machine (Pending, PartiallyApproved, Approved, Executed, Expired). |
| 4 | DUAL-004 | DONE | DUAL-003 | Signer Guild | Create `CeremonyApproval` record with approver identity, timestamp, and signature. |
| 5 | DUAL-005 | DONE | DUAL-004 | Signer Guild | Implement approval collection with threshold checking. |
| 6 | DUAL-006 | DONE | DUAL-005 | Signer Guild | Add ceremony timeout and expiration handling. |
| 7 | DUAL-007 | DONE | DUAL-006 | Signer Guild | Integrate with Authority for approver identity verification. |
| 8 | DUAL-008 | DONE | DUAL-007 | Signer Guild | Create ceremony audit event (`signer.ceremony.initiated`, `.approved`, `.executed`). |
| 9 | DUAL-009 | DONE | DUAL-008 | DB Guild | Create `signer.ceremonies` PostgreSQL table for state persistence. |
| 10 | DUAL-010 | TODO | DUAL-009 | API Guild | Add ceremony API endpoints (`POST /ceremonies`, `POST /ceremonies/{id}/approve`). |
| 11 | DUAL-011 | DONE | DUAL-010 | Testing Guild | Create unit tests for ceremony state machine. |
| 12 | DUAL-012 | TODO | DUAL-011 | Testing Guild | Create integration tests for multi-approver workflows. |
| 13 | DUAL-013 | TODO | DUAL-012 | Docs Guild | Create dual-control ceremony runbook. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created for compliance readiness gap: dual-control signing ceremonies. | Planning |
| 2026-01-15 | DUAL-001: Protocol specification embedded in sprint. DUAL-002: Created ICeremonyOrchestrator interface with CreateCeremonyAsync, ApproveCeremonyAsync, GetCeremonyAsync, ListCeremoniesAsync, ExecuteCeremonyAsync, CancelCeremonyAsync, ProcessExpiredCeremoniesAsync methods. Added CeremonyFilter for list queries. DUAL-003: Created CeremonyStateMachine with IsValidTransition, ComputeStateAfterApproval, CanAcceptApproval, CanExecute, CanCancel, IsTerminalState, GetStateDescription methods. DUAL-004: Created CeremonyApproval record with ApprovalId, CeremonyId, ApproverIdentity, ApprovedAt, ApprovalSignature, ApprovalReason, SigningKeyId, SignatureAlgorithm. DUAL-005/006: Implemented CeremonyOrchestrator with threshold checking, expiration handling via ProcessExpiredCeremoniesAsync. DUAL-007: Created ICeremonyApproverValidator interface and ApproverValidationResult for Authority integration. DUAL-008: Created CeremonyAuditEvents constants and event records (CeremonyInitiatedEvent, CeremonyApprovedEvent, CeremonyExecutedEvent, CeremonyExpiredEvent, CeremonyCancelledEvent, CeremonyApprovalRejectedEvent). DUAL-009: Created ICeremonyRepository interface. DUAL-011: Created CeremonyStateMachineTests with 50+ test cases for state transitions, approval computation, and state queries. | Agent |
## Technical Specification
### Ceremony Protocol
```
1. Initiator creates ceremony request with operation details
2. System notifies required approvers
3. Each approver authenticates and provides approval + signature
4. System collects approvals until M-of-N threshold reached
5. Operation executes with audit trail
6. Ceremony marked complete with all approvals recorded
```
### Ceremony State Machine
```
+----------------+
| Pending |
+-------+--------+
|
(approval received)
v
+----------------------+
| PartiallyApproved |
+----------+-----------+
|
(threshold reached OR timeout)
|
+---------+---------+
v v
+-----------+ +-----------+
| Approved | | Expired |
+-----+-----+ +-----------+
|
(execution)
v
+-----------+
| Executed |
+-----------+
```
### Database Schema
```sql
CREATE TABLE signer.ceremonies (
ceremony_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
operation_type TEXT NOT NULL, -- key_generation, key_rotation, key_revocation
operation_payload JSONB NOT NULL,
threshold_required INT NOT NULL,
threshold_reached INT NOT NULL DEFAULT 0,
state TEXT NOT NULL DEFAULT 'pending',
initiated_by TEXT NOT NULL,
initiated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
expires_at TIMESTAMPTZ NOT NULL,
executed_at TIMESTAMPTZ,
CONSTRAINT valid_state CHECK (state IN ('pending', 'partially_approved', 'approved', 'executed', 'expired'))
);
CREATE TABLE signer.ceremony_approvals (
approval_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
ceremony_id UUID NOT NULL REFERENCES signer.ceremonies(ceremony_id),
approver_identity TEXT NOT NULL,
approved_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
approval_signature BYTEA NOT NULL,
approval_reason TEXT,
UNIQUE(ceremony_id, approver_identity)
);
```
### Configuration
```yaml
signer:
ceremonies:
enabled: true
defaultThreshold: 2
expirationMinutes: 60
operations:
key_generation:
threshold: 3
requiredRoles: ["crypto-custodian"]
key_rotation:
threshold: 2
requiredRoles: ["crypto-custodian", "security-admin"]
key_revocation:
threshold: 2
requiredRoles: ["crypto-custodian"]
notifications:
channels: ["email", "slack"]
```
## Decisions & Risks
- Threshold signing vs approval collection (approval is simpler, threshold signing is cryptographically stronger).
- Ceremony timeout to prevent indefinite pending operations.
- Approver identity must be verified via Authority.
## Acceptance Criteria
- 2-of-3 ceremony workflow demonstrated.
- Audit trail captures all approvals with signatures.
- Expired ceremonies handled gracefully.
- Runbook with step-by-step ceremony instructions.
## Next Checkpoints
- TBD (set once staffed).

53
docs/modules/advisory-ai/guides/api.md
View File

@@ -143,14 +143,62 @@ Produce remediation plan with fix versions and verification steps.
- **Response extensions:** `content.format` Markdown plus `context.remediation` with recommended fix versions (`package`, `fixedVersion`, `rationale`).
- **Errors:** `422 advisory.remediation.noFixAvailable` (vendor has not published fix), `409 advisory.remediation.policyHold` (policy forbids automated remediation).
### 7.4 `GET /v1/advisory-ai/outputs/{{outputHash}}`
### 7.4 `POST /v1/advisory-ai/remediation/apply`
Apply a remediation plan by creating a PR/MR in the target SCM. Requires `advisory-ai:operate` and tenant SCM connector configuration.
- **Request body:**
```json
{
"planId": "plan-abc123",
"scmType": "github"
}
```
- **Response:**
```json
{
"prId": "gh-pr-42",
"prNumber": 42,
"url": "https://github.com/owner/repo/pull/42",
"branchName": "stellaops/security-fix/plan-abc123",
"status": "Open",
"statusMessage": "Pull request created successfully",
"prBody": "## Security Remediation\n\n**Plan ID:** `plan-abc123`\n...",
"createdAt": "2026-01-14T12:00:00Z",
"updatedAt": "2026-01-14T12:00:00Z"
}
```
- **PR body includes:**
- Summary with vulnerability and component info
- Remediation steps (file changes)
- Expected SBOM changes (upgrades, additions, removals)
- Test requirements
- Rollback steps
- VEX claim context
- Evidence references
- **Supported SCM types:** `github`, `gitlab`, `azure-devops`, `gitea`
- **Errors:**
- `404 remediation.planNotFound` – plan does not exist
- `400 remediation.scmTypeNotSupported` – requested SCM type not configured
- `409 remediation.planNotReady` – plan is not PR-ready (see `notReadyReason`)
- `502 remediation.scmError` – SCM connector error (branch/file/PR creation failed)
### 7.5 `GET /v1/advisory-ai/remediation/status/{prId}`
Check the status of a PR created by the remediation apply endpoint.
- **Query parameters:** `scmType` (optional, defaults to `github`)
- **Response:** Same envelope as `POST /remediation/apply`
- **Errors:** `404 remediation.prNotFound`
### 7.6 `GET /v1/advisory-ai/outputs/{{outputHash}}`
Fetch cached artefact (same envelope as §6). Requires `advisory-ai:view`.
- **Headers:** Supports `If-None-Match` with the `outputHash` (Etag) for cache validation.
- **Errors:** `404 advisory.output.notFound` if cache expired or tenant lacks access.
### 7.5 `GET /v1/advisory-ai/plans/{{cacheKey}}` (optional)
### 7.7 `GET /v1/advisory-ai/plans/{{cacheKey}}` (optional)
When plan preview is enabled (feature flag `advisoryAi.planPreview.enabled`), this endpoint returns the orchestration plan using `AdvisoryPipelinePlanResponse` (task metadata, chunk/vector counts). Requires `advisory-ai:operate`.
@@ -208,3 +256,4 @@ Limits are enforced at the gateway; the API returns `429` with standard `Retry-A
| Date (UTC) | Change |
|------------|--------|
| 2025-11-03 | Initial sprint-110 preview covering summary/conflict/remediation endpoints, cache retrieval, plan preview, and error/rate limit model. |
| 2026-01-14 | Added PR generation endpoints (7.4, 7.5): `POST /remediation/apply` and `GET /remediation/status/{prId}`. PR body includes security remediation template with steps, expected changes, tests, rollback, VEX claim. Supported SCM types: github, gitlab, azure-devops, gitea. (SPRINT_20260112_007_BE_remediation_pr_generator) |

183
docs/modules/attestor/architecture.md
View File

@@ -1,20 +1,20 @@
# component_architecture_attestor.md — **Stella Ops Attestor** (2025Q4)
# component_architecture_attestor.md — **Stella Ops Attestor** (2025Q4)
> Derived from Epic 19 – Attestor Console with provenance hooks aligned to the Export Center bundle workflows scoped in Epic 10.
> Derived from Epic 19 – Attestor Console with provenance hooks aligned to the Export Center bundle workflows scoped in Epic 10.
> **Scope.** Implementation‑ready architecture for the **Attestor**: the service that **submits** DSSE envelopes to **Rekor v2**, retrieves/validates inclusion proofs, caches results, and exposes verification APIs. It accepts DSSE **only** from the **Signer** over mTLS, enforces chain‑of‑trust to Stella Ops roots, and returns `{uuid, index, proof, logURL}` to calling services (Scanner.WebService for SBOMs; backend for final reports; Excititor exports when configured).
> **Scope.** Implementation‑ready architecture for the **Attestor**: the service that **submits** DSSE envelopes to **Rekor v2**, retrieves/validates inclusion proofs, caches results, and exposes verification APIs. It accepts DSSE **only** from the **Signer** over mTLS, enforces chain‑of‑trust to Stella Ops roots, and returns `{uuid, index, proof, logURL}` to calling services (Scanner.WebService for SBOMs; backend for final reports; Excititor exports when configured).
---
## 0) Mission & boundaries
**Mission.** Turn a signed DSSE envelope from the Signer into a **transparency‑logged, verifiable fact** with a durable, replayable proof (Merkle inclusion + (optional) checkpoint anchoring). Provide **fast verification** for downstream consumers and a stable retrieval interface for UI/CLI.
**Mission.** Turn a signed DSSE envelope from the Signer into a **transparency‑logged, verifiable fact** with a durable, replayable proof (Merkle inclusion + (optional) checkpoint anchoring). Provide **fast verification** for downstream consumers and a stable retrieval interface for UI/CLI.
**Boundaries.**
* Attestor **does not sign**; it **must not** accept unsigned or third‑party‑signed bundles.
* Attestor **does not sign**; it **must not** accept unsigned or third‑party‑signed bundles.
* Attestor **does not decide PASS/FAIL**; it logs attestations for SBOMs, reports, and export artifacts.
* Rekor v2 backends may be **local** (self‑hosted) or **remote**; Attestor handles both with retries, backoff, and idempotency.
* Rekor v2 backends may be **local** (self‑hosted) or **remote**; Attestor handles both with retries, backoff, and idempotency.
---
@@ -24,22 +24,22 @@
**Dependencies:**
* **Signer** (caller) — authenticated via **mTLS** and **Authority** OpToks.
* **Rekor v2** — tile‑backed transparency log endpoint(s).
* **RustFS (S3-compatible)** — optional archive store for DSSE envelopes & verification bundles.
* **PostgreSQL** — local cache of `{uuid, index, proof, artifactSha256, bundleSha256}`; job state; audit.
* **Valkey** — dedupe/idempotency keys and short‑lived rate‑limit buckets.
* **Licensing Service (optional)** — “endorse” call for cross‑log publishing when customer opts‑in.
* **Signer** (caller) — authenticated via **mTLS** and **Authority** OpToks.
* **Rekor v2** — tile‑backed transparency log endpoint(s).
* **RustFS (S3-compatible)** — optional archive store for DSSE envelopes & verification bundles.
* **PostgreSQL** — local cache of `{uuid, index, proof, artifactSha256, bundleSha256}`; job state; audit.
* **Valkey** — dedupe/idempotency keys and short‑lived rate‑limit buckets.
* **Licensing Service (optional)** — “endorse” call for cross‑log publishing when customer opts‑in.
Trust boundary: **Only the Signer** is allowed to call submission endpoints; enforced by **mTLS peer cert allowlist** + `aud=attestor` OpTok.
---
### Roles, identities & scopes
- **Subjects** — immutable digests for artifacts (container images, SBOMs, reports) referenced in DSSE envelopes.
- **Issuers** — authenticated builders/scanners/policy engines signing evidence; tracked with mode (`keyless`, `kms`, `hsm`, `fido2`) and tenant scope.
- **Consumers** — Scanner, Export Center, CLI, Console, Policy Engine that verify proofs using Attestor APIs.
- **Authority scopes** — `attestor.write`, `attestor.verify`, `attestor.read`, and administrative scopes for key management; all calls mTLS/DPoP-bound.
- **Subjects** — immutable digests for artifacts (container images, SBOMs, reports) referenced in DSSE envelopes.
- **Issuers** — authenticated builders/scanners/policy engines signing evidence; tracked with mode (`keyless`, `kms`, `hsm`, `fido2`) and tenant scope.
- **Consumers** — Scanner, Export Center, CLI, Console, Policy Engine that verify proofs using Attestor APIs.
- **Authority scopes** — `attestor.write`, `attestor.verify`, `attestor.read`, and administrative scopes for key management; all calls mTLS/DPoP-bound.
### Supported predicate types
- `StellaOps.BuildProvenance@1`
@@ -75,9 +75,9 @@ Each predicate embeds subject digests, issuer metadata, policy context, material
The Attestor implements RFC 6962-compliant Merkle inclusion proof verification for Rekor transparency log entries:
**Components:**
- `MerkleProofVerifier` — Verifies Merkle audit paths per RFC 6962 Section 2.1.1
- `CheckpointSignatureVerifier` — Parses and verifies Rekor checkpoint signatures (ECDSA/Ed25519)
- `RekorVerificationOptions` — Configuration for public keys, offline mode, and checkpoint caching
- `MerkleProofVerifier` — Verifies Merkle audit paths per RFC 6962 Section 2.1.1
- `CheckpointSignatureVerifier` — Parses and verifies Rekor checkpoint signatures (ECDSA/Ed25519)
- `RekorVerificationOptions` — Configuration for public keys, offline mode, and checkpoint caching
**Verification Flow:**
1. Parse checkpoint body (origin, tree size, root hash)
@@ -92,10 +92,10 @@ The Attestor implements RFC 6962-compliant Merkle inclusion proof verification f
- `AllowOfflineWithoutSignature` for fully disconnected scenarios (reduced security)
**Metrics:**
- `attestor.rekor_inclusion_verify_total` — Verification attempts by result
- `attestor.rekor_checkpoint_verify_total` — Checkpoint signature verifications
- `attestor.rekor_offline_verify_total` — Offline mode verifications
- `attestor.rekor_checkpoint_cache_hits/misses` — Checkpoint cache performance
- `attestor.rekor_inclusion_verify_total` — Verification attempts by result
- `attestor.rekor_checkpoint_verify_total` — Checkpoint signature verifications
- `attestor.rekor_offline_verify_total` — Offline mode verifications
- `attestor.rekor_checkpoint_cache_hits/misses` — Checkpoint cache performance
### UI & CLI touchpoints
- Console: Evidence browser, verification report, chain-of-custody graph, issuer/key management, attestation workbench, bulk verification views.
@@ -103,9 +103,9 @@ The Attestor implements RFC 6962-compliant Merkle inclusion proof verification f
- SDKs expose sign/verify primitives for build pipelines.
### Performance & observability targets
- Throughput goal: ≥1 000 envelopes/minute per worker with cached verification.
- Throughput goal: ≥1 000 envelopes/minute per worker with cached verification.
- Metrics: `attestor_submission_total`, `attestor_verify_seconds`, `attestor_rekor_latency_seconds`, `attestor_cache_hit_ratio`.
- Logs include `tenant`, `issuer`, `subjectDigest`, `rekorUuid`, `proofStatus`; traces cover submission → Rekor → cache → response path.
- Logs include `tenant`, `issuer`, `subjectDigest`, `rekorUuid`, `proofStatus`; traces cover submission → Rekor → cache → response path.
---
@@ -171,8 +171,8 @@ Database: `attestor`
Indexes:
* `entries`: indexes on `artifact_sha256`, `bundle_sha256`, `created_at`, and composite `(status, created_at DESC)`.
* `dedupe`: unique index on `key`; scheduled job cleans rows where `ttl_at < NOW()` (24–48h retention).
* `audit`: index on `ts` for time‑range queries.
* `dedupe`: unique index on `key`; scheduled job cleans rows where `ttl_at < NOW()` (24–48h retention).
* `audit`: index on `ts` for time‑range queries.
---
@@ -330,10 +330,10 @@ SBOM-to-component linkage metadata.
**Attestor accepts only** DSSE envelopes that satisfy all of:
1. **mTLS** peer certificate maps to `signer` service (CA‑pinned).
1. **mTLS** peer certificate maps to `signer` service (CA‑pinned).
2. **Authority** OpTok with `aud=attestor`, `scope=attestor.write`, DPoP or mTLS bound.
3. DSSE envelope is **signed by the Signer’s key** (or includes a **Fulcio‑issued** cert chain) and **chains to configured roots** (Fulcio/KMS).
4. **Predicate type** is one of Stella Ops types (sbom/report/vex‑export) with valid schema.
3. DSSE envelope is **signed by the Signer’s key** (or includes a **Fulcio‑issued** cert chain) and **chains to configured roots** (Fulcio/KMS).
4. **Predicate type** is one of Stella Ops types (sbom/report/vex‑export) with valid schema.
5. `subject[*].digest.sha256` is present and canonicalized.
**Wire shape (JSON):**
@@ -360,7 +360,7 @@ SBOM-to-component linkage metadata.
`POST /api/v1/attestations:sign` *(mTLS + OpTok required)*
* **Purpose**: Deterministically wrap Stella Ops payloads in DSSE envelopes before Rekor submission. Reuses the submission rate limiter and honours caller tenancy/audience scopes.
* **Purpose**: Deterministically wrap Stella Ops payloads in DSSE envelopes before Rekor submission. Reuses the submission rate limiter and honours caller tenancy/audience scopes.
* **Body**:
```json
@@ -383,7 +383,7 @@ SBOM-to-component linkage metadata.
* **Behaviour**:
* Resolve the signing key from `attestor.signing.keys[]` (includes algorithm, provider, and optional KMS version).
* Compute DSSE pre‑authentication encoding, sign with the resolved provider (default EC, BouncyCastle Ed25519, or File‑KMS ES256), and add static + request certificate chains.
* Compute DSSE pre‑authentication encoding, sign with the resolved provider (default EC, BouncyCastle Ed25519, or File‑KMS ES256), and add static + request certificate chains.
* Canonicalise the resulting bundle, derive `bundleSha256`, and mirror the request meta shape used by `/api/v1/rekor/entries`.
* Emit `attestor.sign_total{result,algorithm,provider}` and `attestor.sign_latency_seconds{algorithm,provider}` metrics and append an audit row (`action=sign`).
* **Response 200**:
@@ -415,13 +415,13 @@ SBOM-to-component linkage metadata.
```json
{
"uuid": "…",
"uuid": "…",
"index": 123456,
"proof": {
"checkpoint": { "origin": "rekor@site", "size": 987654, "rootHash": "…", "timestamp": "…" },
"inclusion": { "leafHash": "…", "path": ["…","…"] }
"checkpoint": { "origin": "rekor@site", "size": 987654, "rootHash": "…", "timestamp": "…" },
"inclusion": { "leafHash": "…", "path": ["…","…"] }
},
"logURL": "https://rekor…/api/v2/log/…/entries/…",
"logURL": "https://rekor…/api/v2/log/…/entries/…",
"status": "included"
}
```
@@ -434,28 +434,28 @@ SBOM-to-component linkage metadata.
* Returns `entries` row (refreshes proof from Rekor if stale/missing).
* Accepts `?refresh=true` to force backend query.
### 4.4 Verification (third‑party or internal)
### 4.4 Verification (third‑party or internal)
`POST /api/v1/rekor/verify`
* **Body** (one of):
* `{ "uuid": "…" }`
* `{ "bundle": { …DSSE… } }`
* `{ "artifactSha256": "…" }` *(looks up most recent entry)*
* `{ "uuid": "…" }`
* `{ "bundle": { …DSSE… } }`
* `{ "artifactSha256": "…" }` *(looks up most recent entry)*
* **Checks**:
1. **Bundle signature** → cert chain to Fulcio/KMS roots configured.
2. **Inclusion proof** → recompute leaf hash; verify Merkle path against checkpoint root.
1. **Bundle signature** → cert chain to Fulcio/KMS roots configured.
2. **Inclusion proof** → recompute leaf hash; verify Merkle path against checkpoint root.
3. Optionally verify **checkpoint** against local trust anchors (if Rekor signs checkpoints).
4. Confirm **subject.digest** matches caller‑provided hash (when given).
4. Confirm **subject.digest** matches caller‑provided hash (when given).
5. Fetch **transparency witness** statement when enabled; cache results and downgrade status to WARN when endorsements are missing or mismatched.
* **Response**:
```json
{ "ok": true, "uuid": "…", "index": 123, "logURL": "…", "checkedAt": "…" }
{ "ok": true, "uuid": "…", "index": 123, "logURL": "…", "checkedAt": "…" }
```
### 4.5 Bulk verification
@@ -464,11 +464,11 @@ SBOM-to-component linkage metadata.
`GET /api/v1/rekor/verify:bulk/{jobId}` returns progress and per-item results (subject/uuid, status, issues, cached verification report if available). Jobs are tenant- and subject-scoped; only the initiating principal can read their progress.
**Worker path:** `BulkVerificationWorker` claims queued jobs (`status=queued → running`), executes items sequentially through the cached verification service, updates progress counters, and records metrics:
**Worker path:** `BulkVerificationWorker` claims queued jobs (`status=queued → running`), executes items sequentially through the cached verification service, updates progress counters, and records metrics:
- `attestor.bulk_jobs_total{status}` – completed/failed jobs
- `attestor.bulk_job_duration_seconds{status}` – job runtime
- `attestor.bulk_items_total{status}` – per-item outcomes (`succeeded`, `verification_failed`, `exception`)
- `attestor.bulk_jobs_total{status}` – completed/failed jobs
- `attestor.bulk_job_duration_seconds{status}` – job runtime
- `attestor.bulk_items_total{status}` – per-item outcomes (`succeeded`, `verification_failed`, `exception`)
The worker honours `bulkVerification.itemDelayMilliseconds` for throttling and reschedules persistence conflicts with optimistic version checks. Results hydrate the verification cache; failed items record the error reason without aborting the overall job.
@@ -478,7 +478,7 @@ The worker honours `bulkVerification.itemDelayMilliseconds` for throttling and r
* **Canonicalization**: DSSE envelopes are **normalized** (stable JSON ordering, no insignificant whitespace) before hashing and submission.
* **Transport**: HTTP/2 with retries (exponential backoff, jitter), budgeted timeouts.
* **Idempotency**: if backend returns “already exists,” map to existing `uuid`.
* **Idempotency**: if backend returns “already exists,” map to existing `uuid`.
* **Proof acquisition**:
* In synchronous mode, poll the log for inclusion up to `proofTimeoutMs`.
@@ -486,25 +486,25 @@ The worker honours `bulkVerification.itemDelayMilliseconds` for throttling and r
* **Mirrors/dual logs**:
* When `logPreference="both"`, submit to primary and mirror; store **both** UUIDs (primary canonical).
* Optional **cloud endorsement**: POST to the Stella Ops cloud `/attest/endorse` with `{uuid, artifactSha256}`; store returned endorsement id.
* Optional **cloud endorsement**: POST to the Stella Ops cloud `/attest/endorse` with `{uuid, artifactSha256}`; store returned endorsement id.
---
## 6) Security model
* **mTLS required** for submission from **Signer** (CA‑pinned).
* **mTLS required** for submission from **Signer** (CA‑pinned).
* **Authority token** with `aud=attestor` and DPoP/mTLS binding must be presented; Attestor verifies both.
* **Bundle acceptance policy**:
* DSSE signature must chain to the configured **Fulcio** (keyless) or **KMS/HSM** roots.
* SAN (Subject Alternative Name) must match **Signer identity** policy (e.g., `urn:stellaops:signer` or pinned OIDC issuer).
* Predicate `predicateType` must be on allowlist (sbom/report/vex-export).
* `subject.digest.sha256` values must be present and well‑formed (hex).
* `subject.digest.sha256` values must be present and well‑formed (hex).
* **No public submission** path. **Never** accept bundles from untrusted clients.
* **Client certificate allowlists**: optional `security.mtls.allowedSubjects` / `allowedThumbprints` tighten peer identity checks beyond CA pinning.
* **Rate limits**: token-bucket per caller derived from `quotas.perCaller` (QPS/burst) returns `429` + `Retry-After` when exceeded.
* **Scope enforcement**: API separates `attestor.write`, `attestor.verify`, and `attestor.read` policies; verification/list endpoints accept read or verify scopes while submission endpoints remain write-only.
* **Request hygiene**: JSON content-type is mandatory (415 returned otherwise); DSSE payloads are capped (default 2 MiB), certificate chains limited to six entries, and signatures to six per envelope to mitigate parsing abuse.
* **Request hygiene**: JSON content-type is mandatory (415 returned otherwise); DSSE payloads are capped (default 2 MiB), certificate chains limited to six entries, and signatures to six per envelope to mitigate parsing abuse.
* **Redaction**: Attestor never logs secret material; DSSE payloads **should** be public by design (SBOMs/reports). If customers require redaction, enforce policy at Signer (predicate minimization) **before** Attestor.
---
@@ -542,8 +542,8 @@ The worker honours `bulkVerification.itemDelayMilliseconds` for throttling and r
SLO guardrails:
* `attestor.verify_latency_seconds` P95 ≤ 2 s per policy.
* `attestor.verify_total{result="failed"}` ≤ 1 % of `attestor.verify_total` over 30 min rolling windows.
* `attestor.verify_latency_seconds` P95 ≤ 2 s per policy.
* `attestor.verify_total{result="failed"}` ≤ 1 % of `attestor.verify_total` over 30 min rolling windows.
**Correlation**:
@@ -636,7 +636,7 @@ attestor:
---
## 10) End‑to‑end sequences
## 10) End‑to‑end sequences
**A) Submit & include (happy path)**
@@ -695,19 +695,19 @@ sequenceDiagram
* Stateless; scale horizontally.
* **Targets**:
* Submit+proof P95 ≤ **300 ms** (warm log; local Rekor).
* Verify P95 ≤ **30 ms** from cache; ≤ **120 ms** with live proof fetch.
* Submit+proof P95 ≤ **300 ms** (warm log; local Rekor).
* Verify P95 ≤ **30 ms** from cache; ≤ **120 ms** with live proof fetch.
* 1k submissions/minute per replica sustained.
* **Hot caches**: `dedupe` (bundle hash → uuid), recent `entries` by artifact sha256.
* **Hot caches**: `dedupe` (bundle hash → uuid), recent `entries` by artifact sha256.
---
## 13) Testing matrix
* **Happy path**: valid DSSE, inclusion within timeout.
* **Idempotency**: resubmit same `bundleSha256` → same `uuid`.
* **Security**: reject non‑Signer mTLS, wrong `aud`, DPoP replay, untrusted cert chain, forbidden predicateType.
* **Rekor variants**: promise‑then‑proof, proof delayed, mirror dual‑submit, mirror failure.
* **Idempotency**: resubmit same `bundleSha256` → same `uuid`.
* **Security**: reject non‑Signer mTLS, wrong `aud`, DPoP replay, untrusted cert chain, forbidden predicateType.
* **Rekor variants**: promise‑then‑proof, proof delayed, mirror dual‑submit, mirror failure.
* **Verification**: corrupt leaf path, wrong root, tampered bundle.
* **Throughput**: soak test with 10k submissions; latency SLOs, zero drops.
@@ -718,16 +718,16 @@ sequenceDiagram
* Language: **.NET 10** minimal API; `HttpClient` with **sockets handler** tuned for HTTP/2.
* JSON: **canonical writer** for DSSE payload hashing.
* Crypto: use **BouncyCastle**/**System.Security.Cryptography**; PEM parsing for cert chains.
* Rekor client: pluggable driver; treat backend errors as retryable/non‑retryable with granular mapping.
* Safety: size caps on bundles; decompress bombs guarded; strict UTF‑8.
* Rekor client: pluggable driver; treat backend errors as retryable/non‑retryable with granular mapping.
* Safety: size caps on bundles; decompress bombs guarded; strict UTF‑8.
* CLI integration: `stellaops verify attestation <uuid|bundle|artifact>` calls `/rekor/verify`.
---
## 15) Optional features
* **Dual‑log** write (primary + mirror) and **cross‑log proof** packaging.
* **Cloud endorsement**: send `{uuid, artifactSha256}` to Stella Ops cloud; store returned endorsement id for marketing/chain‑of‑custody.
* **Dual‑log** write (primary + mirror) and **cross‑log proof** packaging.
* **Cloud endorsement**: send `{uuid, artifactSha256}` to Stella Ops cloud; store returned endorsement id for marketing/chain‑of‑custody.
* **Checkpoint pinning**: periodically pin latest Rekor checkpoints to an external audit store for independent monitoring.
---
@@ -739,3 +739,54 @@ sequenceDiagram
- Health endpoints: `/health/liveness`, `/health/readiness`, `/status`; verification probe `/api/attestations/verify` once demo bundle is available (see runbook).
- Alert hints: signing latency > 1s p99, verification failure spikes, tlog submission lag >10s, key rotation age over policy threshold, backlog above configured threshold.
---
## 17) Rekor Entry Events
> Sprint: SPRINT_20260112_007_ATTESTOR_rekor_entry_events
Attestor emits deterministic events when DSSE bundles are logged to Rekor and inclusion proofs become available. These events drive policy reanalysis.
### Event Types
| Event Type | Constant | Description |
|------------|----------|-------------|
| `rekor.entry.logged` | `RekorEventTypes.EntryLogged` | Bundle successfully logged with inclusion proof |
| `rekor.entry.queued` | `RekorEventTypes.EntryQueued` | Bundle queued for logging (async mode) |
| `rekor.entry.inclusion_verified` | `RekorEventTypes.InclusionVerified` | Inclusion proof independently verified |
| `rekor.entry.failed` | `RekorEventTypes.EntryFailed` | Logging or verification failed |
### RekorEntryEvent Schema
```jsonc
{
"eventId": "rekor-evt-sha256:...",
"eventType": "rekor.entry.logged",
"tenant": "default",
"bundleDigest": "sha256:abc123...",
"artifactDigest": "sha256:def456...",
"predicateType": "StellaOps.ScanResults@1",
"rekorEntry": {
"uuid": "24296fb24b8ad77a...",
"logIndex": 123456789,
"logUrl": "https://rekor.sigstore.dev",
"integratedTime": "2026-01-15T10:30:02Z"
},
"reanalysisHints": {
"cveIds": ["CVE-2026-1234"],
"productKeys": ["pkg:npm/lodash@4.17.21"],
"mayAffectDecision": true,
"reanalysisScope": "immediate"
},
"occurredAtUtc": "2026-01-15T10:30:05Z"
}
```
### Offline Mode Behavior
When operating in offline/air-gapped mode:
1. Events are not emitted when Rekor is unreachable
2. Bundles are queued locally for later submission
3. Verification uses bundled checkpoints
4. Events are generated when connectivity is restored

330
docs/modules/authority/operations/break-glass-account.md Normal file
View File

@@ -0,0 +1,330 @@
# Break-Glass Account Operations
This document describes the break-glass emergency access mechanism for Stella Ops Authority when normal authentication is unavailable.
## Overview
Break-glass accounts provide emergency administrative access when:
- PostgreSQL database is unavailable
- Identity provider (IdP) is unreachable
- Network partition isolates Authority service
- Disaster recovery scenarios
## Security Model
### Activation Requirements
| Requirement | Description |
|-------------|-------------|
| Reason code | Mandatory selection from approved list |
| Reason details | Free-text justification (logged) |
| Time limit | Maximum 15 minutes per session |
| Extensions | Maximum 2 extensions with re-authentication |
| Alert dispatch | Immediate notification to security team |
### Approved Reason Codes
| Code | Description | Use Case |
|------|-------------|----------|
| `emergency-incident` | Active security incident | Security team responding to breach |
| `database-outage` | PostgreSQL unavailable | DBA performing recovery |
| `security-event` | Proactive security response | Patching critical vulnerability |
| `scheduled-maintenance` | Planned maintenance window | Pre-approved maintenance |
| `disaster-recovery` | DR scenario activation | DR team executing runbook |
## Configuration
### Local Policy File
```yaml
# /etc/stellaops/authority/local-policy.yaml
schemaVersion: "1.0.0"
lastUpdated: "2026-01-15T12:00:00Z"
breakGlass:
enabled: true
accounts:
- id: "break-glass-admin"
name: "Emergency Administrator"
passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$..."
roles: ["admin"]
permissions:
- "authority:*"
- "platform:admin"
- "orch:operate"
sessionTimeoutMinutes: 15
maxExtensions: 2
requireReasonCode: true
allowedReasonCodes:
- "emergency-incident"
- "database-outage"
- "security-event"
- "scheduled-maintenance"
- "disaster-recovery"
- id: "break-glass-readonly"
name: "Emergency Read-Only"
passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$..."
roles: ["auditor"]
permissions:
- "audit:read"
- "obs:incident"
sessionTimeoutMinutes: 30
maxExtensions: 1
requireReasonCode: true
allowedReasonCodes:
- "emergency-incident"
- "security-event"
alerting:
onActivation: true
channels:
- type: "email"
recipients: ["security@company.com", "oncall@company.com"]
- type: "slack"
webhook: "${SLACK_SECURITY_WEBHOOK}"
- type: "pagerduty"
serviceKey: "${PAGERDUTY_SERVICE_KEY}"
```
### Password Generation
```bash
# Generate Argon2id hash for break-glass password
# Use a strong, unique password stored securely offline
# Option 1: Using argon2 CLI
echo -n "StrongBreakGlassPassword123!" | argon2 "$(openssl rand -hex 16)" -id -t 3 -m 16 -p 4 -e
# Option 2: Using Python
python3 << 'EOF'
from argon2 import PasswordHasher
ph = PasswordHasher(time_cost=3, memory_cost=65536, parallelism=4)
hash = ph.hash("StrongBreakGlassPassword123!")
print(hash)
EOF
```
### Secure Storage
Break-glass credentials should be:
1. Stored in a physical safe (not digital-only)
2. Split between multiple custodians (M-of-N)
3. Sealed with tamper-evident packaging
4. Inventoried and audited quarterly
## Activation Procedure
### Step 1: Initiate Break-Glass
```bash
# Via CLI
stella auth break-glass \
--account break-glass-admin \
--reason emergency-incident \
--details "PostgreSQL cluster unreachable, DBA on-call"
# Via API
curl -X POST https://authority.company.com/auth/break-glass \
-H "Content-Type: application/json" \
-d '{
"accountId": "break-glass-admin",
"password": "StrongBreakGlassPassword123!",
"reasonCode": "emergency-incident",
"reasonDetails": "PostgreSQL cluster unreachable, DBA on-call"
}'
```
### Step 2: Receive Session Token
```json
{
"sessionId": "bg-session-abc123",
"token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresAt": "2026-01-15T12:49:56Z",
"permissions": ["authority:*", "platform:admin", "orch:operate"],
"extensionsRemaining": 2
}
```
### Step 3: Perform Emergency Operations
```bash
# Use session token for operations
stella --token "${BG_TOKEN}" system status
stella --token "${BG_TOKEN}" service restart authority
```
### Step 4: Extend Session (If Needed)
```bash
# Extend session before expiration
stella auth break-glass extend \
--session bg-session-abc123 \
--reason "Recovery still in progress"
```
### Step 5: Terminate Session
```bash
# Always explicitly terminate when done
stella auth break-glass terminate \
--session bg-session-abc123 \
--resolution "Database recovered, normal auth restored"
```
## Audit Trail
### Event Types
| Event | Description | Severity |
|-------|-------------|----------|
| `break_glass.activated` | Session started | WARNING |
| `break_glass.extended` | Session extended | WARNING |
| `break_glass.terminated` | Session ended | INFO |
| `break_glass.expired` | Session timed out | WARNING |
| `break_glass.action` | Action performed | INFO |
| `break_glass.denied` | Access denied | ERROR |
### Sample Audit Entry
```json
{
"eventType": "authority.break_glass.activated",
"timestamp": "2026-01-15T12:34:56.789Z",
"severity": "warning",
"session": {
"id": "bg-session-abc123",
"accountId": "break-glass-admin",
"reasonCode": "database-outage",
"reasonDetails": "PostgreSQL cluster unreachable, DBA on-call"
},
"client": {
"ip": "10.0.0.5",
"userAgent": "StellaOps-CLI/2027.Q1"
},
"timing": {
"activatedAt": "2026-01-15T12:34:56Z",
"expiresAt": "2026-01-15T12:49:56Z",
"extensionsRemaining": 2
}
}
```
### Audit Query
```bash
# Query break-glass audit events
stella audit query \
--type "break_glass.*" \
--since "2026-01-01" \
--format json
# Generate break-glass usage report
stella audit report break-glass \
--period monthly \
--output break-glass-report.pdf
```
## Alert Configuration
### Email Template
```
Subject: [ALERT] Break-Glass Access Activated - ${REASON_CODE}
A break-glass account has been activated:
Account: ${ACCOUNT_ID}
Reason: ${REASON_CODE}
Details: ${REASON_DETAILS}
Session ID: ${SESSION_ID}
Activated: ${ACTIVATED_AT}
Expires: ${EXPIRES_AT}
Client IP: ${CLIENT_IP}
This session will automatically expire in 15 minutes.
If this activation was not authorized, take immediate action:
1. Terminate the session: stella auth break-glass terminate --session ${SESSION_ID}
2. Investigate the access attempt
3. Contact Security Operations
```
### Slack Alert
```json
{
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "Break-Glass Access Activated"
}
},
{
"type": "section",
"fields": [
{"type": "mrkdwn", "text": "*Account:*\n${ACCOUNT_ID}"},
{"type": "mrkdwn", "text": "*Reason:*\n${REASON_CODE}"},
{"type": "mrkdwn", "text": "*Session:*\n${SESSION_ID}"},
{"type": "mrkdwn", "text": "*Expires:*\n${EXPIRES_AT}"}
]
}
]
}
```
## Testing
### Quarterly Drill
Conduct quarterly break-glass activation drills:
1. Schedule maintenance window
2. Simulate database outage
3. Activate break-glass account
4. Perform test operations
5. Verify audit trail
6. Terminate session
7. Document drill results
### Test Checklist
- [ ] Break-glass activation successful
- [ ] Alerts dispatched correctly
- [ ] Session timeout enforced
- [ ] Extension mechanism works
- [ ] Audit events captured
- [ ] Session termination works
- [ ] Post-drill report generated
## Incident Response
### On Unauthorized Break-Glass Activation
1. **Immediate**: Terminate session
```bash
stella auth break-glass terminate --session ${SESSION_ID} --force
```
2. **Contain**: Disable break-glass temporarily
```bash
stella config set authority.breakGlass.enabled false --apply
```
3. **Investigate**: Query audit logs
```bash
stella audit query --type "break_glass.*" --session ${SESSION_ID}
```
4. **Remediate**: Rotate credentials if compromised
5. **Report**: File incident report per security policy
## Related Documentation
- [Local RBAC Fallback](../local-rbac-fallback.md)
- [Authority Architecture](../architecture.md)
- [Incident Response Playbook](../../security/incident-response.md)

77
docs/modules/cli/guides/commands/evidence-bundle-format.md
View File

@@ -54,6 +54,9 @@ evidence-{findingId}/
├── README.md # Human-readable documentation
├── sbom.cdx.json # CycloneDX SBOM slice
├── reachability.json # Reachability analysis data
├── binary-diff.json # Binary diff evidence (if available)
├── binary-diff.dsse.json # Signed binary diff envelope (if attested)
├── delta-proof.json # Semantic fingerprint diff summary (if available)
├── vex/
│ ├── vendor.json # Vendor VEX statements
│ ├── nvd.json # NVD VEX data
@@ -322,6 +325,80 @@ done
| `.md` | `text/markdown` | Markdown documentation |
| `.txt` | `text/plain` | Plain text |
## Binary Diff Evidence Files
> Sprint: SPRINT_20260112_009_SCANNER_binary_diff_bundle_export (BINDIFF-SCAN-003)
Evidence bundles may include binary diff files when comparing binary artifacts across versions:
### binary-diff.json
Contains binary diff evidence comparing current and previous binary versions:
```json
{
"status": "available",
"diffType": "semantic",
"previousBinaryDigest": "sha256:abc123...",
"currentBinaryDigest": "sha256:def456...",
"similarityScore": 0.95,
"functionChangeCount": 3,
"securityChangeCount": 1,
"functionChanges": [
{
"functionName": "process_input",
"operation": "modified",
"previousHash": "sha256:...",
"currentHash": "sha256:..."
}
],
"securityChanges": [
{
"changeType": "mitigation_added",
"description": "Stack canaries enabled",
"severity": "info"
}
],
"semanticDiff": {
"previousFingerprint": "fp:abc...",
"currentFingerprint": "fp:def...",
"similarityScore": 0.92,
"semanticChanges": ["control_flow_modified"]
}
}
```
### binary-diff.dsse.json
DSSE-signed wrapper when binary diff evidence is attested:
```json
{
"payloadType": "application/vnd.stellaops.binary-diff+json",
"payload": { /* binary-diff.json content */ },
"attestationRef": {
"id": "attest-12345",
"rekorLogIndex": 123456789,
"bundleDigest": "sha256:..."
}
}
```
### delta-proof.json
Semantic fingerprint summary for quick verification:
```json
{
"previousFingerprint": "fp:abc...",
"currentFingerprint": "fp:def...",
"similarityScore": 0.92,
"semanticChanges": ["control_flow_modified", "data_flow_changed"],
"functionChangeCount": 3,
"securityChangeCount": 1
}
```
## See Also
- [stella scan replay Command Reference](../cli/guides/commands/scan-replay.md)

105
docs/modules/excititor/architecture.md
View File

@@ -431,6 +431,111 @@ correlation: { replaces?: sha256, replacedBy?: sha256 }
* Indexes: `{type:1, occurredAt:-1}`, TTL on `occurredAt` for configurable retention.
### 3.3 VEX Change Events
> Sprint: SPRINT_20260112_006_EXCITITOR_vex_change_events
Excititor emits deterministic VEX change events when statements are added, superseded, or conflict. These events drive policy reanalysis in downstream systems.
#### Event Types
| Event Type | Constant | Description |
|------------|----------|-------------|
| `vex.statement.added` | `VexTimelineEventTypes.StatementAdded` | New VEX statement ingested |
| `vex.statement.superseded` | `VexTimelineEventTypes.StatementSuperseded` | Statement replaced by newer version |
| `vex.statement.conflict` | `VexTimelineEventTypes.StatementConflict` | Conflicting statuses detected |
| `vex.status.changed` | `VexTimelineEventTypes.StatusChanged` | Effective status changed for a product-vulnerability pair |
#### VexStatementChangeEvent Schema
```jsonc
{
"eventId": "vex-evt-sha256:abc123...", // Deterministic hash-based ID
"eventType": "vex.statement.added",
"tenant": "default",
"vulnerabilityId": "CVE-2026-1234",
"productKey": "pkg:npm/lodash@4.17.21",
"newStatus": "not_affected",
"previousStatus": null, // null for new statements
"providerId": "vendor:redhat",
"observationId": "default:redhat:VEX-2026-0001:v1",
"supersededBy": null,
"supersedes": [],
"provenance": {
"documentHash": "sha256:...",
"documentUri": "https://vendor/vex/...",
"sourceTimestamp": "2026-01-15T10:00:00Z",
"author": "security@vendor.com",
"trustScore": 0.95
},
"conflictDetails": null,
"occurredAtUtc": "2026-01-15T10:30:00Z",
"traceId": "trace-xyz789"
}
```
#### VexConflictDetails Schema
When `eventType` is `vex.statement.conflict`:
```jsonc
{
"conflictType": "status_mismatch", // status_mismatch | trust_tie | supersession_conflict
"conflictingStatuses": [
{
"providerId": "vendor:redhat",
"status": "not_affected",
"justification": "CODE_NOT_REACHABLE",
"trustScore": 0.95
},
{
"providerId": "vendor:ubuntu",
"status": "affected",
"justification": null,
"trustScore": 0.85
}
],
"resolutionStrategy": "highest_trust", // or null if unresolved
"autoResolved": false
}
```
#### Event ID Computation
Event IDs are deterministic SHA-256 hashes computed from:
- Event type
- Tenant
- Vulnerability ID
- Product key
- Observation ID
- Occurred timestamp (truncated to seconds)
This ensures idempotent event emission across retries.
#### Policy Engine Integration
Policy Engine subscribes to VEX events to trigger reanalysis:
```yaml
# Policy event subscription
subscriptions:
- event: vex.statement.*
action: reanalyze
filter:
trustScore: { $gte: 0.7 }
- event: vex.statement.conflict
action: queue_for_review
filter:
autoResolved: false
```
#### Emission Ordering
Events are emitted with deterministic ordering:
1. Statement events ordered by `occurredAtUtc` ascending
2. Conflict events emitted after all related statement events
3. Events for the same vulnerability sorted by provider ID
**`vex.consensus`** (optional rollups)
```

72
docs/modules/platform/platform-service.md
View File

@@ -84,3 +84,75 @@ Provide a single, deterministic aggregation layer for cross-service UX workflows
## Gateway exposure
The Platform Service is exposed via Gateway and registered through Router discovery. It does not expose direct ingress outside Gateway in production.
## Setup Wizard
The Platform Service exposes setup wizard endpoints to support first-run configuration and reconfiguration workflows. These endpoints replace UI-mock implementations with real backend state management.
### API surface (v1)
#### Sessions
- `GET /api/v1/setup/sessions` - Get current setup session for tenant
- `POST /api/v1/setup/sessions` - Create new setup session
- `POST /api/v1/setup/sessions/resume` - Resume existing or create new session
- `POST /api/v1/setup/sessions/finalize` - Finalize setup session
#### Steps
- `POST /api/v1/setup/steps/execute` - Execute a setup step (runs Doctor checks)
- `POST /api/v1/setup/steps/skip` - Skip an optional setup step
#### Definitions
- `GET /api/v1/setup/definitions/steps` - List all step definitions
### Setup step identifiers
| Step ID | Title | Required | Depends On |
|---------|-------|----------|------------|
| `Database` | Database Setup | Yes | - |
| `Valkey` | Valkey/Redis Setup | Yes | - |
| `Migrations` | Database Migrations | Yes | Database |
| `Admin` | Admin Bootstrap | Yes | Migrations |
| `Crypto` | Crypto Profile | Yes | Admin |
| `Vault` | Vault Integration | No | - |
| `Scm` | SCM Integration | No | - |
| `Notifications` | Notification Channels | No | - |
| `Environments` | Environment Definition | No | Admin |
| `Agents` | Agent Registration | No | Environments |
### Setup session states
| Status | Description |
|--------|-------------|
| `NotStarted` | Setup not begun |
| `InProgress` | Setup in progress |
| `Completed` | All steps completed |
| `CompletedPartial` | Required steps completed, optional skipped |
| `Failed` | Required step failed |
| `Abandoned` | Setup abandoned by user |
### Setup step states
| Status | Description |
|--------|-------------|
| `Pending` | Not yet started |
| `Current` | Currently active step |
| `Passed` | Completed successfully |
| `Failed` | Validation failed |
| `Skipped` | Explicitly skipped |
| `Blocked` | Blocked by dependency |
### Security and scopes
- Read: `platform.setup.read`
- Write: `platform.setup.write`
- Admin: `platform.setup.admin`
### Offline posture
- Sessions include `DataAsOfUtc` for offline rendering with stale indicators
- Step results cached with Doctor check pass/fail status
- Suggested fixes generated for failed checks
### Related documentation
- UX flow specification: `docs/setup/setup-wizard-ux.md`
- Repository inventory: `docs/setup/setup-wizard-inventory.md`
- Doctor checks: `docs/setup/setup-wizard-doctor-contract.md`

44
docs/modules/policy/determinization-api.md
View File

@@ -91,7 +91,49 @@ When receiving `GuardedPass`:
## 4. Determinization Rules
The gate evaluates rules in priority order:
The gate evaluates rules in priority order.
### 4.1 Anchored Evidence Rules (v1.1)
> **Sprint:** SPRINT_20260112_004_BE_policy_determinization_attested_rules
Anchored evidence (DSSE-signed with optional Rekor transparency) takes highest priority in rule evaluation. These rules short-circuit evaluation when cryptographically attested evidence is present.
| Priority | Rule | Condition | Result |
|----------|------|-----------|--------|
| 1 | AnchoredAffectedWithRuntimeHardFail | Anchored VEX affected + anchored runtime telemetry confirms loading | **Blocked** (hard fail) |
| 2 | AnchoredVexNotAffectedAllow | Anchored VEX not_affected or fixed | Pass (short-circuit) |
| 3 | AnchoredBackportProofAllow | Anchored backport proof detected | Pass (short-circuit) |
| 4 | AnchoredUnreachableAllow | Anchored reachability shows unreachable | Pass (short-circuit) |
**Anchor Metadata Fields:**
Evidence anchoring is tracked via these fields on each evidence type:
```json
{
"anchor": {
"anchored": true,
"envelope_digest": "sha256:abc123...",
"predicate_type": "https://stellaops.io/vex/v1",
"rekor_log_index": 12345678,
"rekor_entry_id": "24296fb24b8ad77a...",
"scope": "finding",
"verified": true,
"attested_at": "2026-01-14T12:00:00Z"
}
}
```
Evidence types with anchor support:
- `VexClaimSummary` (via `VexClaimAnchor`)
- `BackportEvidence`
- `RuntimeEvidence`
- `ReachabilityEvidence`
### 4.2 Standard Rules
Standard rules apply when no anchored evidence short-circuits evaluation:
| Priority | Rule | Condition | Result |
|----------|------|-----------|--------|

17
docs/modules/release-orchestrator/appendices/evidence-schema.md
View File

@@ -538,9 +538,26 @@ Evidence packets can be exported in multiple formats:
| Format | Use Case |
|--------|----------|
| JSON | API consumption, archival |
| SignedJSON | DSSE-signed JSON for verification workflows |
| Markdown | Human-readable documentation |
| HTML | Styled web reports |
| PDF | Human-readable compliance reports |
| CSV | Spreadsheet analysis |
| SLSA | SLSA provenance format |
| **EvidenceCard** | Single-file evidence card with SBOM excerpt, DSSE envelope, and Rekor receipt (v1.1) |
| **EvidenceCardCompact** | Compact evidence card without full SBOM (v1.1) |
### Evidence Card Format (v1.1)
The evidence-card format packages related artifacts into a single JSON file for offline verification:
- **SBOM Excerpt**: Relevant component information from the full SBOM
- **DSSE Envelope**: Dead Simple Signing Envelope containing the signed payload
- **Rekor Receipt**: Optional Sigstore Rekor transparency log receipt for audit trail
Content type: `application/vnd.stellaops.evidence-card+json`
See [Evidence Decision API](../../../api/evidence-decision-api.openapi.yaml) for schema details.
## References

334
docs/modules/scanner/signed-sbom-archive-spec.md Normal file
View File

@@ -0,0 +1,334 @@
# Signed SBOM Archive Specification
Version: 1.0.0
Status: Draft
Last Updated: 2026-01-15
## Overview
This specification defines a self-contained, cryptographically signed SBOM archive format that bundles:
- The SBOM document (SPDX or CycloneDX)
- DSSE signature envelope
- Verification materials (certificates, transparency proofs)
- Metadata (tool versions, timestamps)
- Offline verification resources
## Archive Structure
```
signed-sbom-{digest_short}-{timestamp}.tar.gz
|
+-- sbom.spdx.json # OR sbom.cdx.json (CycloneDX)
+-- sbom.dsse.json # DSSE envelope containing signature
+-- manifest.json # Archive inventory with hashes
+-- metadata.json # Generation metadata
+-- certs/
| +-- signing-cert.pem # Signing certificate
| +-- signing-chain.pem # Full certificate chain
| +-- fulcio-root.pem # Fulcio root CA (for keyless)
+-- rekor-proof/ # Optional: transparency log proof
| +-- inclusion-proof.json
| +-- checkpoint.sig
| +-- rekor-public.pem
+-- schemas/ # Bundled validation schemas
| +-- spdx-2.3.schema.json
| +-- spdx-3.0.1.schema.json
| +-- cyclonedx-1.7.schema.json
| +-- dsse.schema.json
+-- VERIFY.md # Human-readable verification guide
```
## File Specifications
### sbom.spdx.json / sbom.cdx.json
The primary SBOM document in either:
- **SPDX**: Versions 2.3 or 3.0.1 (JSON format)
- **CycloneDX**: Versions 1.4, 1.5, 1.6, or 1.7 (JSON format)
Requirements:
- UTF-8 encoding without BOM
- Canonical JSON formatting (RFC 8785 compliant)
- No trailing whitespace or newlines
### sbom.dsse.json
DSSE envelope containing the SBOM signature:
```json
{
"payloadType": "application/vnd.stellaops.sbom+json",
"payload": "<base64-encoded-sbom>",
"signatures": [
{
"keyid": "SHA256:abc123...",
"sig": "<base64-encoded-signature>"
}
]
}
```
### manifest.json
Archive inventory with integrity hashes:
```json
{
"schemaVersion": "1.0.0",
"archiveId": "signed-sbom-abc123-20260115T123456Z",
"generatedAt": "2026-01-15T12:34:56Z",
"files": [
{
"path": "sbom.spdx.json",
"sha256": "abc123...",
"size": 45678,
"mediaType": "application/spdx+json"
},
{
"path": "sbom.dsse.json",
"sha256": "def456...",
"size": 1234,
"mediaType": "application/vnd.dsse+json"
}
],
"merkleRoot": "sha256:789abc...",
"totalFiles": 12,
"totalSize": 98765
}
```
### metadata.json
Generation and tool metadata:
```json
{
"schemaVersion": "1.0.0",
"stellaOps": {
"suiteVersion": "2027.Q1",
"scannerVersion": "1.2.3",
"scannerDigest": "sha256:scanner-image-digest",
"signerVersion": "1.0.0",
"sbomServiceVersion": "1.1.0"
},
"generation": {
"timestamp": "2026-01-15T12:34:56Z",
"hlcTimestamp": "1737000000000000000",
"operator": "build@company.com"
},
"input": {
"imageRef": "registry.company.com/app:v1.0.0",
"imageDigest": "sha256:image-digest-here",
"platform": "linux/amd64"
},
"sbom": {
"format": "spdx-2.3",
"componentCount": 142,
"packageCount": 89,
"fileCount": 1247
},
"signature": {
"type": "keyless",
"issuer": "https://accounts.google.com",
"subject": "build@company.com",
"signedAt": "2026-01-15T12:34:57Z"
},
"reproducibility": {
"deterministic": true,
"expectedDigest": "sha256:expected-sbom-digest"
}
}
```
### VERIFY.md
Human-readable verification instructions:
```markdown
# SBOM Archive Verification
## Quick Verification
```bash
# Verify archive integrity
sha256sum -c <<EOF
abc123... sbom.spdx.json
def456... sbom.dsse.json
EOF
# Verify signature using cosign
cosign verify-blob \
--signature sbom.dsse.json \
--certificate certs/signing-cert.pem \
--certificate-chain certs/signing-chain.pem \
sbom.spdx.json
```
## Offline Verification
```bash
# Using bundled Fulcio root
cosign verify-blob \
--signature sbom.dsse.json \
--certificate certs/signing-cert.pem \
--certificate-chain certs/signing-chain.pem \
--certificate-oidc-issuer https://accounts.google.com \
--offline \
sbom.spdx.json
```
## Rekor Inclusion Proof
```bash
# Verify transparency log inclusion
rekor-cli verify \
--artifact sbom.spdx.json \
--signature sbom.dsse.json \
--public-key certs/signing-cert.pem \
--rekor-server https://rekor.sigstore.dev
```
```
## Cryptographic Requirements
### Hash Algorithms
| Purpose | Algorithm | Format |
|---------|-----------|--------|
| File hashes | SHA-256 | Lowercase hex |
| Merkle tree | SHA-256 | Lowercase hex with `sha256:` prefix |
| Certificate fingerprint | SHA-256 | Uppercase hex with colons |
### Signature Algorithms
Supported signature algorithms:
- **ECDSA-P256**: Recommended for keyless (Fulcio)
- **ECDSA-P384**: High-security environments
- **RSA-PSS-4096**: Legacy compatibility
- **Ed25519**: High-performance signing
### DSSE Envelope
DSSE (Dead Simple Signing Envelope) per specification:
- PAE (Pre-Authentication Encoding) for signing
- Base64 encoding for payload and signatures
- Multiple signatures supported for threshold signing
## Verification Process
### Step 1: Archive Integrity
```python
# Verify tar.gz integrity
import tarfile
import hashlib
with tarfile.open("signed-sbom.tar.gz", "r:gz") as tar:
manifest = json.load(tar.extractfile("manifest.json"))
for file_entry in manifest["files"]:
content = tar.extractfile(file_entry["path"]).read()
actual_hash = hashlib.sha256(content).hexdigest()
assert actual_hash == file_entry["sha256"]
```
### Step 2: Signature Verification
```python
# Verify DSSE signature
from sigstore.verify import Verifier
verifier = Verifier.production()
result = verifier.verify(
artifact=sbom_content,
signature=dsse_envelope,
certificate=signing_cert
)
assert result.success
```
### Step 3: Certificate Chain Validation
```python
# Validate certificate chain
from cryptography import x509
chain = load_certificate_chain("certs/signing-chain.pem")
root = load_certificate("certs/fulcio-root.pem")
validate_chain(chain, root)
```
### Step 4: Transparency Log (Optional)
```python
# Verify Rekor inclusion
from rekor_client import verify_inclusion
result = verify_inclusion(
artifact_hash=sbom_hash,
proof=inclusion_proof,
checkpoint=checkpoint
)
assert result.verified
```
## Compatibility
### SBOM Formats
| Format | Version | Status |
|--------|---------|--------|
| SPDX | 2.3 | Supported |
| SPDX | 3.0.1 | Supported |
| CycloneDX | 1.4 | Supported |
| CycloneDX | 1.5 | Supported |
| CycloneDX | 1.6 | Supported |
| CycloneDX | 1.7 | Supported |
### Compression
| Format | Extension | Status |
|--------|-----------|--------|
| gzip | .tar.gz | Default |
| zstd | .tar.zst | Recommended (smaller) |
| none | .tar | Supported |
## API Endpoint
```
GET /scans/{scanId}/exports/signed-sbom-archive
```
Query Parameters:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| format | string | spdx-2.3 | SBOM format |
| compression | string | gzip | Compression type |
| includeRekor | bool | true | Include Rekor proof |
| includeSchemas | bool | true | Bundle JSON schemas |
Response Headers:
| Header | Description |
|--------|-------------|
| Content-Type | application/gzip or application/zstd |
| Content-Disposition | attachment; filename="signed-sbom-{digest}.tar.gz" |
| X-SBOM-Digest | SHA-256 of SBOM content |
| X-Archive-Merkle-Root | Merkle root of archive |
| X-Rekor-Log-Index | Rekor log index (if applicable) |
## Security Considerations
1. **Determinism**: All outputs must be reproducible given same inputs
2. **Canonicalization**: JSON must be RFC 8785 canonical before signing
3. **Time sources**: Use injected TimeProvider, not system clock
4. **Key material**: Never include private keys in archives
5. **Offline verification**: Bundle all necessary verification materials
## Related Specifications
- [DSSE Specification](https://github.com/secure-systems-lab/dsse)
- [Sigstore Signing Specification](https://docs.sigstore.dev)
- [SPDX Specification](https://spdx.github.io/spdx-spec/)
- [CycloneDX Specification](https://cyclonedx.org/specification/)
- [Rekor Transparency Log](https://docs.sigstore.dev/rekor/)

80
docs/modules/signals/guides/unknowns-ranking.md
View File

@@ -376,6 +376,86 @@ The following metrics are exposed for monitoring:
| `signals_unknowns_scoring_duration_seconds` | Histogram | Scoring computation time |
| `signals_unknowns_band_transitions_total` | Counter | Band changes (e.g., WARM->HOT) |
---
## Runtime Updated Events
> Sprint: SPRINT_20260112_008_SIGNALS_runtime_telemetry_events
When runtime observations change for a CVE and product pair, the Signals module emits `runtime.updated` events to drive policy reanalysis of unknowns.
### Event Types
| Event Type | Constant | Description |
|------------|----------|-------------|
| `runtime.updated` | `RuntimeEventTypes.Updated` | Runtime observations changed for a subject |
| `runtime.ingested` | `RuntimeEventTypes.Ingested` | New runtime observation batch ingested |
| `runtime.confirmed` | `RuntimeEventTypes.Confirmed` | Runtime fact confirmed by additional evidence |
| `runtime.exploit_detected` | `RuntimeEventTypes.ExploitDetected` | Exploit behavior detected at runtime |
### Update Types
| Type | Description |
|------|-------------|
| `NewObservation` | First runtime observation for a subject |
| `StateChange` | Reachability state changed from previous observation |
| `ConfidenceIncrease` | Additional hits increased confidence score |
| `NewCallPath` | Previously unseen call path observed |
| `ExploitTelemetry` | Exploit behavior detected (always triggers reanalysis) |
### Event Schema
```jsonc
{
"eventId": "sha256:abc123...", // Deterministic based on content
"eventType": "runtime.updated",
"version": "1.0.0",
"tenant": "default",
"cveId": "CVE-2026-1234", // Optional
"purl": "pkg:npm/lodash@4.17.21", // Optional
"subjectKey": "cve:CVE-2026-1234|purl:pkg:npm/lodash@4.17.21",
"callgraphId": "cg-scan-001",
"evidenceDigest": "sha256:def456...", // Digest of runtime evidence
"updateType": "NewCallPath",
"previousState": "observed", // Null for new observations
"newState": "observed",
"confidence": 0.85, // 0.0-1.0
"fromRuntime": true,
"runtimeMethod": "ebpf", // "ebpf", "agent", "probe"
"observedNodeHashes": ["sha256:...", "sha256:..."],
"pathHash": "sha256:...", // Optional
"triggerReanalysis": true,
"reanalysisReason": "New call path observed at runtime",
"occurredAtUtc": "2026-01-15T10:30:00Z",
"traceId": "abc123" // Optional correlation ID
}
```
### Reanalysis Triggers
The `triggerReanalysis` flag is set to `true` when:
1. **Exploit telemetry detected** (always triggers)
2. **State change** from previous observation
3. **High-confidence runtime observation** (confidence >= 0.8 and fromRuntime=true)
4. **New observation** (no previous runtime data)
### Event Emission Points
Runtime updated events are emitted from:
1. `RuntimeFactsIngestionService.IngestAsync` - After runtime facts are persisted
2. `ReachabilityScoringService` - When scores are recomputed with new runtime data
### Deterministic Event IDs
Event IDs are computed deterministically using SHA-256 of:
- `subjectKey`
- `evidenceDigest`
- `occurredAtUtc` (ISO 8601 format)
This ensures idempotent event handling and deduplication.
## Related Documentation
- [Unknowns Registry](./unknowns-registry.md) - Data model and API for unknowns

247
docs/modules/vuln-explorer/guides/signed-vex-override-workflow.md Normal file
View File

@@ -0,0 +1,247 @@
# Signed VEX Override Workflow
This guide describes how to create and manage signed VEX override decisions using DSSE attestations for audit-grade provenance.
## Overview
VEX (Vulnerability Exploitability eXchange) decisions allow operators to mark vulnerabilities as not-affected, mitigated, or accepted-risk. When attestation signing is enabled, each override produces a DSSE envelope that:
1. Cryptographically binds the decision to the operator's identity
2. Records the decision in an immutable attestation log
3. Optionally anchors the attestation to Sigstore Rekor for transparency
4. Enables downstream policy engines to require signed overrides
## API Endpoints
### Create Signed Override
```http
POST /v1/vex-decisions
Content-Type: application/json
Authorization: Bearer <token>
{
"findingId": "find-abc123",
"status": "NOT_AFFECTED",
"justification": "CODE_NOT_REACHABLE",
"justificationText": "Static analysis confirms code path is unreachable in production configuration",
"scope": {
"environments": ["production"],
"projects": ["myapp"]
},
"validity": {
"notBefore": "2026-01-15T00:00:00Z",
"notAfter": "2026-07-15T00:00:00Z"
},
"attestationOptions": {
"sign": true,
"keyRef": "default-signing-key",
"rekorUpload": true,
"predicateType": "https://stella.ops/predicates/vex-override/v1"
}
}
```
### Response with Attestation Reference
```json
{
"id": "vex-dec-xyz789",
"findingId": "find-abc123",
"status": "NOT_AFFECTED",
"justification": "CODE_NOT_REACHABLE",
"justificationText": "Static analysis confirms code path is unreachable in production configuration",
"createdAt": "2026-01-15T10:30:00Z",
"createdBy": "user@example.com",
"signedOverride": {
"envelopeDigest": "sha256:abc123def456...",
"signatureAlgorithm": "ECDSA_P256_SHA256",
"signedAt": "2026-01-15T10:30:01Z",
"keyId": "default-signing-key",
"rekorInfo": {
"logIndex": 123456789,
"entryId": "24296fb24b8ad77a...",
"integratedTime": "2026-01-15T10:30:02Z",
"logId": "c0d23d6ad406973f..."
},
"verificationStatus": "VERIFIED"
}
}
```
### Update Signed Override
Updates create superseding records while preserving history:
```http
PATCH /v1/vex-decisions/{id}
Content-Type: application/json
Authorization: Bearer <token>
{
"status": "AFFECTED_MITIGATED",
"justification": "COMPENSATING_CONTROLS",
"justificationText": "WAF rule deployed to block exploit vectors",
"attestationOptions": {
"sign": true,
"supersedes": "vex-dec-xyz789"
}
}
```
### List Decisions with Attestation Filter
```http
GET /v1/vex-decisions?signedOnly=true&rekorAnchored=true
```
### Verify Attestation
```http
POST /v1/vex-decisions/{id}/verify
```
Response:
```json
{
"verified": true,
"signatureValid": true,
"rekorEntryValid": true,
"certificateChain": ["CN=signing-key,..."],
"verifiedAt": "2026-01-15T10:35:00Z"
}
```
## CLI Usage
### Create Signed Override
```bash
stella vex create \
--finding find-abc123 \
--status NOT_AFFECTED \
--justification CODE_NOT_REACHABLE \
--reason "Static analysis confirms unreachable" \
--sign \
--key default-signing-key \
--rekor
```
### View Override with Attestation
```bash
stella vex show vex-dec-xyz789 --include-attestation
```
Output:
```
VEX Decision: vex-dec-xyz789
Finding: find-abc123
Status: NOT_AFFECTED
Justification: CODE_NOT_REACHABLE
Created: 2026-01-15T10:30:00Z
Created By: user@example.com
Attestation:
Envelope Digest: sha256:abc123def456...
Algorithm: ECDSA_P256_SHA256
Signed At: 2026-01-15T10:30:01Z
Verification: VERIFIED
Rekor Entry:
Log Index: 123456789
Entry ID: 24296fb24b8ad77a...
Integrated Time: 2026-01-15T10:30:02Z
```
### Verify Override Attestation
```bash
stella vex verify vex-dec-xyz789
```
### Export Override Evidence
```bash
stella vex export vex-dec-xyz789 \
--format bundle \
--output override-evidence.zip
```
## Policy Engine Integration
Signed overrides can be required by policy rules:
```yaml
# Policy requiring signed VEX overrides
rules:
- id: require-signed-vex
condition: |
vex.status in ["NOT_AFFECTED", "AFFECTED_MITIGATED"]
and (vex.signedOverride == null or vex.signedOverride.verificationStatus != "VERIFIED")
action: FAIL
message: "VEX overrides must be signed and verified"
```
## Attestation Predicate Schema
The VEX override predicate follows in-toto attestation format:
```json
{
"_type": "https://in-toto.io/Statement/v1",
"subject": [
{
"name": "finding:find-abc123",
"digest": { "sha256": "..." }
}
],
"predicateType": "https://stella.ops/predicates/vex-override/v1",
"predicate": {
"decision": {
"id": "vex-dec-xyz789",
"status": "NOT_AFFECTED",
"justification": "CODE_NOT_REACHABLE",
"justificationText": "...",
"scope": { "environments": ["production"] },
"validity": { "notBefore": "...", "notAfter": "..." }
},
"finding": {
"id": "find-abc123",
"cve": "CVE-2026-1234",
"package": "example-pkg",
"version": "1.2.3"
},
"operator": {
"identity": "user@example.com",
"authorizedAt": "2026-01-15T10:30:00Z"
},
"supersedes": null
}
}
```
## Security Considerations
1. **Key Management**: Signing keys should be managed through Authority with appropriate access controls
2. **Rekor Anchoring**: Enable Rekor upload for public transparency; disable for air-gapped deployments
3. **Expiry**: Set appropriate validity windows; expired overrides surface warnings
4. **Audit Trail**: All signed overrides are recorded in the findings ledger history
## Offline/Air-Gap Mode
For air-gapped deployments:
1. Rekor upload is disabled automatically
2. Attestations are stored locally with envelope digests
3. Verification uses local trust roots
4. Export bundles include all attestation evidence for manual verification
## Related Documentation
- [VEX Consensus Guide](../../../VEX_CONSENSUS_GUIDE.md)
- [Attestor Architecture](../../attestor/architecture.md)
- [Findings Ledger](./findings-ledger.md)
- [Policy Integration](../../policy/guides/vex-trust-model.md)

294
docs/operations/blue-green-deployment.md Normal file
View File

@@ -0,0 +1,294 @@
# Blue/Green Deployment Guide
This guide documents the blue/green deployment strategy for Stella Ops platform upgrades with evidence continuity preservation.
## Overview
Blue/green deployment maintains two identical production environments:
- **Blue**: Current production environment
- **Green**: New version deployment target
This approach enables zero-downtime upgrades and instant rollback capability while preserving all evidence integrity.
## Prerequisites
### Infrastructure Requirements
| Component | Blue Environment | Green Environment |
|-----------|-----------------|-------------------|
| Kubernetes namespace | `stellaops-prod` | `stellaops-green` |
| PostgreSQL | Shared (with migration support) | Shared |
| Redis/Valkey | Separate instance | Separate instance |
| Object Storage | Shared (evidence bundles) | Shared |
| Load Balancer | Traffic routing | Traffic routing |
### Version Compatibility
Before upgrading, verify version compatibility:
```bash
# Check current version
stella version
# Check target version compatibility
stella upgrade check --target 2027.Q2
```
See `docs/releases/VERSIONING.md` for the full compatibility matrix.
## Deployment Phases
### Phase 1: Preparation
#### 1.1 Environment Assessment
```bash
# Verify current health
stella doctor --full
# Check pending migrations
stella system migrations-status
# Verify evidence integrity baseline
stella evidence verify-all --output pre-upgrade-baseline.json
```
#### 1.2 Backup Procedures
```bash
# PostgreSQL backup
pg_dump -Fc stellaops > backup-$(date +%Y%m%d-%H%M%S).dump
# Evidence bundle export
stella evidence export --all --output evidence-backup/
# Configuration backup
kubectl get configmap -n stellaops-prod -o yaml > configmaps-backup.yaml
kubectl get secret -n stellaops-prod -o yaml > secrets-backup.yaml
```
#### 1.3 Pre-Flight Checklist
- [ ] All services healthy
- [ ] No active scans or attestations in progress
- [ ] Queue depths at zero
- [ ] Backup completed and verified
- [ ] Evidence baseline captured
- [ ] Maintenance window communicated
### Phase 2: Green Environment Deployment
#### 2.1 Deploy New Version
```bash
# Deploy to green namespace
helm upgrade stellaops-green ./helm/stellaops \
--namespace stellaops-green \
--create-namespace \
--values values-production.yaml \
--set image.tag=2027.Q2 \
--wait
# Verify deployment
kubectl get pods -n stellaops-green
```
#### 2.2 Run Migrations
```bash
# Apply startup migrations (Category A)
stella system migrations-run --category A
# Verify migration status
stella system migrations-status
```
#### 2.3 Health Validation
```bash
# Run health checks on green
stella doctor --full --namespace stellaops-green
# Run smoke tests
stella test smoke --namespace stellaops-green
```
### Phase 3: Traffic Cutover
#### 3.1 Gradual Cutover (Recommended)
```yaml
# Update ingress for gradual traffic shift
# ingress-canary.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: stellaops-canary
annotations:
nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-weight: "10" # Start with 10%
spec:
rules:
- host: stellaops.company.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: stellaops-green
port:
number: 80
```
Increase weight gradually: 10% -> 25% -> 50% -> 100%
#### 3.2 Instant Cutover
```bash
# Switch DNS/load balancer to green
kubectl patch ingress stellaops-main \
-n stellaops-prod \
--type='json' \
-p='[{"op": "replace", "path": "/spec/rules/0/http/paths/0/backend/service/name", "value": "stellaops-green"}]'
```
#### 3.3 Monitoring During Cutover
Monitor these metrics during cutover:
- Error rate: `rate(http_requests_total{status=~"5.."}[1m])`
- Latency p99: `histogram_quantile(0.99, http_request_duration_seconds_bucket)`
- Evidence operations: `rate(evidence_operations_total[1m])`
- Attestation success: `rate(attestation_success_total[1m])`
### Phase 4: Post-Upgrade Validation
#### 4.1 Evidence Continuity Verification
```bash
# Verify evidence chain-of-custody
stella evidence verify-continuity \
--baseline pre-upgrade-baseline.json \
--output post-upgrade-report.html
# Generate audit report
stella evidence audit-report \
--since $(date -d '1 hour ago' --iso-8601) \
--output upgrade-audit.pdf
```
#### 4.2 Functional Validation
```bash
# Run full test suite
stella test integration
# Verify scan capability
stella scan --image test-image:latest --dry-run
# Verify attestation generation
stella attest verify --bundle test-bundle.tar.gz
```
#### 4.3 Documentation Update
- Update `CURRENT_VERSION.md` with new version
- Record upgrade in `CHANGELOG.md`
- Archive upgrade artifacts
### Phase 5: Cleanup
#### 5.1 Observation Period
Maintain blue environment for 72 hours minimum before decommission.
#### 5.2 Blue Environment Decommission
```bash
# After observation period, remove blue
helm uninstall stellaops-blue -n stellaops-prod
# Clean up resources
kubectl delete namespace stellaops-blue
```
## Rollback Procedures
### Immediate Rollback (During Cutover)
```bash
# Revert traffic to blue
kubectl patch ingress stellaops-main \
-n stellaops-prod \
--type='json' \
-p='[{"op": "replace", "path": "/spec/rules/0/http/paths/0/backend/service/name", "value": "stellaops-blue"}]'
```
### Post-Cutover Rollback
If rollback needed after cutover complete:
1. **Assess impact**: Run `stella evidence verify-continuity` to check evidence state
2. **Database considerations**: Backward-compatible migrations allow rollback; breaking migrations require restore
3. **Evidence preservation**: Evidence bundles created during green operation remain valid
```bash
# If database rollback needed
pg_restore -d stellaops backup-YYYYMMDD-HHMMSS.dump
# Redeploy blue version
helm upgrade stellaops ./helm/stellaops \
--namespace stellaops-prod \
--set image.tag=2027.Q1 \
--wait
```
## Evidence Continuity Guarantees
### Preserved During Upgrade
| Artifact | Guarantee |
|----------|-----------|
| OCI digests | Unchanged |
| SBOM content hashes | Unchanged |
| Merkle roots | Recomputed if schema changes (cross-reference maintained) |
| Attestation signatures | Valid |
| Rekor log entries | Immutable |
### Verification Commands
```bash
# Verify OCI digests unchanged
stella evidence verify-digests --report digests.json
# Verify attestation validity
stella attest verify-all --since $(date -d '7 days ago' --iso-8601)
# Generate compliance report
stella evidence compliance-report --format pdf
```
## Troubleshooting
### Common Issues
| Issue | Symptom | Resolution |
|-------|---------|------------|
| Migration timeout | Pod stuck in init | Increase `migrationTimeoutSeconds` |
| Health check failure | Ready probe failing | Check database connectivity |
| Evidence mismatch | Continuity check fails | Run `stella evidence reindex` |
| Traffic not routing | 502 errors | Verify service selector labels |
### Support Escalation
If upgrade issues cannot be resolved:
1. Capture diagnostics: `stella doctor --export diagnostics.tar.gz`
2. Rollback to blue environment
3. Contact support with diagnostics bundle
## Related Documentation
- [Upgrade Runbook](upgrade-runbook.md)
- [Evidence Migration](evidence-migration.md)
- [Database Migration Strategy](../db/MIGRATION_STRATEGY.md)
- [Versioning Policy](../releases/VERSIONING.md)

329
docs/operations/hsm-setup-runbook.md Normal file
View File

@@ -0,0 +1,329 @@
# HSM Setup and Configuration Runbook
This runbook provides step-by-step procedures for configuring Hardware Security Module (HSM) integration with Stella Ops.
## Overview
Stella Ops supports PKCS#11-compatible HSMs for cryptographic key storage and signing operations. This includes:
- YubiHSM 2
- Thales Luna Network HSM
- AWS CloudHSM
- SoftHSM2 (development/testing)
## Prerequisites
### Hardware Requirements
| Component | Requirement |
|-----------|-------------|
| HSM Device | PKCS#11 compatible |
| Network | HSM accessible from Stella Ops services |
| Backup | Secondary HSM for key backup |
### Software Requirements
```bash
# PKCS#11 library for your HSM
# Example for SoftHSM2 (development)
apt-get install softhsm2 opensc
# Verify installation
softhsm2-util --version
pkcs11-tool --version
```
## SoftHSM2 Setup (Development)
### Step 1: Initialize SoftHSM
```bash
# Create token directory
mkdir -p /var/lib/softhsm/tokens
chmod 700 /var/lib/softhsm/tokens
# Initialize token
softhsm2-util --init-token \
--slot 0 \
--label "StellaOps-Dev" \
--so-pin 12345678 \
--pin 87654321
# Verify token
softhsm2-util --show-slots
```
### Step 2: Generate Signing Key
```bash
# Generate ECDSA P-256 key
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
--login --pin 87654321 \
--keypairgen \
--key-type EC:prime256v1 \
--id 01 \
--label "stellaops-signing-2026"
# List keys
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
--login --pin 87654321 \
--list-objects
```
### Step 3: Export Public Key
```bash
# Export public key for distribution
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
--login --pin 87654321 \
--read-object \
--type pubkey \
--id 01 \
--output-file stellaops-signing-2026.pub.der
# Convert to PEM
openssl ec -pubin -inform DER \
-in stellaops-signing-2026.pub.der \
-outform PEM \
-out stellaops-signing-2026.pub.pem
```
## YubiHSM 2 Setup
### Step 1: Install YubiHSM SDK
```bash
# Download YubiHSM SDK
wget https://developers.yubico.com/YubiHSM2/Releases/yubihsm2-sdk-2023.01-ubuntu2204-amd64.tar.gz
tar xzf yubihsm2-sdk-*.tar.gz
cd yubihsm2-sdk
sudo ./install.sh
# Start connector
sudo systemctl enable yubihsm-connector
sudo systemctl start yubihsm-connector
```
### Step 2: Initialize YubiHSM
```bash
# Connect to YubiHSM shell
yubihsm-shell
# Authenticate with default auth key
connect
session open 1 password
# Create authentication key for Stella Ops
generate authkey 0 100 "StellaOps-Auth" 1 generate-asymmetric-key:sign-ecdsa:delete-asymmetric-key
# Generate signing key
generate asymmetric 0 200 "StellaOps-Signing" 1 sign-ecdsa ecp256
# Export public key
get public key 0 200 stellaops-yubihsm.pub
session close 0
quit
```
### Step 3: Configure PKCS#11
```bash
# Create PKCS#11 configuration
cat > /etc/yubihsm_pkcs11.conf <<EOF
connector = http://127.0.0.1:12345
EOF
# Test PKCS#11 access
pkcs11-tool --module /usr/lib/libyubihsm_pkcs11.so \
--list-slots
```
## Stella Ops Configuration
### Basic HSM Configuration
```yaml
# etc/stellaops.yaml
signing:
provider: "hsm"
hsm:
type: "pkcs11"
libraryPath: "/usr/lib/softhsm/libsofthsm2.so" # or /usr/lib/libyubihsm_pkcs11.so
slotId: 0
tokenLabel: "StellaOps-Dev"
pin: "${HSM_PIN}" # Use environment variable
keyId: "01"
keyLabel: "stellaops-signing-2026"
# Connection settings
connectionTimeoutSeconds: 30
maxSessions: 10
sessionIdleTimeoutSeconds: 300
# Retry settings
maxRetries: 3
retryDelayMs: 100
```
### Environment Variables
```bash
# Set HSM PIN securely
export HSM_PIN="87654321"
# Or use secrets manager
export HSM_PIN=$(aws secretsmanager get-secret-value \
--secret-id stellaops/hsm-pin \
--query SecretString --output text)
```
### Kubernetes Secret
```yaml
apiVersion: v1
kind: Secret
metadata:
name: stellaops-hsm
namespace: stellaops
type: Opaque
stringData:
HSM_PIN: "87654321"
```
## Verification
### Step 1: Connectivity Check
```bash
# Run HSM connectivity doctor check
stella doctor --check hsm
# Expected output:
# [PASS] HSM Connectivity
# - Library loaded: /usr/lib/softhsm/libsofthsm2.so
# - Slot available: 0 (StellaOps-Dev)
# - Key found: stellaops-signing-2026
# - Sign/verify test: PASSED
```
### Step 2: Signing Test
```bash
# Test signing operation
stella sign test \
--message "test message" \
--key-label "stellaops-signing-2026"
# Expected output:
# Signature: base64...
# Algorithm: ECDSA-P256
# Key ID: 01
```
### Step 3: Integration Test
```bash
# Run HSM integration tests
stella test integration --filter "HSM*"
```
## Key Rotation
### Step 1: Generate New Key
```bash
# Generate new key in HSM
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
--login --pin ${HSM_PIN} \
--keypairgen \
--key-type EC:prime256v1 \
--id 02 \
--label "stellaops-signing-2027"
```
### Step 2: Add to Trust Anchor
```bash
# Add new key to Stella Ops
stella key add \
--key-id "stellaops-signing-2027" \
--algorithm EC-P256 \
--public-key stellaops-signing-2027.pub.pem
```
### Step 3: Transition Period
```yaml
# Update configuration for dual-key
signing:
activeKeyId: "stellaops-signing-2027"
additionalKeys:
- keyId: "stellaops-signing-2026"
keyLabel: "stellaops-signing-2026"
```
### Step 4: Revoke Old Key
```bash
# After transition period (2-4 weeks)
stella key revoke \
--key-id "stellaops-signing-2026" \
--reason "scheduled-rotation"
```
## Troubleshooting
### Common Issues
| Issue | Symptom | Resolution |
|-------|---------|------------|
| Library not found | `PKCS11 library not found` | Verify `libraryPath` in config |
| Slot not available | `Slot 0 not found` | Run `pkcs11-tool --list-slots` |
| Key not found | `Key stellaops-signing not found` | Verify key label with `--list-objects` |
| Pin incorrect | `CKR_PIN_INCORRECT` | Check HSM_PIN environment variable |
| Session limit | `CKR_SESSION_COUNT` | Increase `maxSessions` or restart |
### Debug Logging
```yaml
# Enable HSM debug logging
logging:
levels:
StellaOps.Cryptography.Hsm: Debug
```
### Session Recovery
```bash
# If sessions exhausted, restart service
kubectl rollout restart deployment stellaops-signer -n stellaops
```
## Security Best Practices
1. **PIN Management**
- Never hardcode PINs in configuration files
- Use secrets management (Vault, AWS Secrets Manager)
- Rotate PINs periodically
2. **Key Backup**
- Configure HSM key backup/replication
- Test key recovery procedures regularly
- Document recovery process
3. **Access Control**
- Limit HSM access to required services only
- Use separate authentication keys per service
- Audit HSM access logs
4. **Network Security**
- Use TLS for network HSM connections
- Firewall HSM to authorized hosts only
- Monitor for unauthorized access attempts
## Related Documentation
- [Key Rotation Runbook](key-rotation-runbook.md)
- [Dual-Control Ceremonies](dual-control-ceremonies.md)
- [Signer Architecture](../modules/signer/architecture.md)

381
docs/operations/upgrade-runbook.md Normal file
View File

@@ -0,0 +1,381 @@
# Stella Ops Upgrade Runbook
This runbook provides step-by-step procedures for upgrading Stella Ops with evidence continuity preservation.
## Quick Reference
| Phase | Duration | Owner | Rollback Point |
|-------|----------|-------|----------------|
| Pre-Upgrade | 2-4 hours | Platform Team | N/A |
| Backup | 1-2 hours | DBA | Full restore |
| Deploy Green | 30-60 min | Platform Team | Abort deploy |
| Cutover | 15-30 min | Platform Team | Instant rollback |
| Validation | 1-2 hours | QA + Security | 72h observation |
| Cleanup | 30 min | Platform Team | N/A |
## Pre-Upgrade Checklist
### Environment Verification
```bash
# Step 1: Record current version
stella version > /tmp/pre-upgrade-version.txt
echo "Current version: $(cat /tmp/pre-upgrade-version.txt)"
# Step 2: Verify system health
stella doctor --full --output /tmp/pre-upgrade-health.json
if [ $? -ne 0 ]; then
echo "ABORT: System health check failed"
exit 1
fi
# Step 3: Check pending migrations
stella system migrations-status
# Ensure no pending migrations before upgrade
# Step 4: Verify queue depths
stella queue status --all
# All queues should be empty or near-empty
```
### Evidence Integrity Baseline
```bash
# Step 5: Capture evidence baseline
stella evidence verify-all \
--output /backup/pre-upgrade-evidence-baseline.json \
--include-merkle-roots
# Step 6: Export Merkle root summary
stella evidence roots-export \
--output /backup/pre-upgrade-merkle-roots.json
# Step 7: Record evidence counts
stella evidence stats > /backup/pre-upgrade-evidence-stats.txt
```
### Backup Procedures
```bash
# Step 8: PostgreSQL backup
BACKUP_TIMESTAMP=$(date +%Y%m%d-%H%M%S)
pg_dump -Fc -d stellaops -f /backup/stellaops-${BACKUP_TIMESTAMP}.dump
# Step 9: Verify backup integrity
pg_restore --list /backup/stellaops-${BACKUP_TIMESTAMP}.dump > /dev/null
if [ $? -ne 0 ]; then
echo "ABORT: Backup verification failed"
exit 1
fi
# Step 10: Evidence bundle backup
stella evidence export \
--all \
--output /backup/evidence-bundles-${BACKUP_TIMESTAMP}/
# Step 11: Configuration backup
kubectl get configmap -n stellaops -o yaml > /backup/configmaps-${BACKUP_TIMESTAMP}.yaml
kubectl get secret -n stellaops -o yaml > /backup/secrets-${BACKUP_TIMESTAMP}.yaml
```
### Pre-Flight Approval
Complete this checklist before proceeding:
- [ ] Current version documented
- [ ] System health: GREEN
- [ ] Evidence baseline captured
- [ ] PostgreSQL backup completed and verified
- [ ] Evidence bundles exported
- [ ] Configuration backed up
- [ ] Maintenance window approved
- [ ] Stakeholders notified
- [ ] Rollback plan reviewed
**Approver signature**: __________________ **Date**: __________
## Upgrade Execution
### Deploy Green Environment
```bash
# Step 12: Create green namespace
kubectl create namespace stellaops-green
# Step 13: Copy secrets to green namespace
kubectl get secret stellaops-secrets -n stellaops -o yaml | \
sed 's/namespace: stellaops/namespace: stellaops-green/' | \
kubectl apply -f -
# Step 14: Deploy new version
helm upgrade stellaops-green ./helm/stellaops \
--namespace stellaops-green \
--values values-production.yaml \
--set image.tag=${TARGET_VERSION} \
--wait --timeout 10m
# Step 15: Verify deployment
kubectl get pods -n stellaops-green -w
# Wait for all pods to be Running and Ready
```
### Run Migrations
```bash
# Step 16: Apply Category A migrations (startup)
stella system migrations-run \
--category A \
--namespace stellaops-green
# Step 17: Verify migration success
stella system migrations-status --namespace stellaops-green
# All migrations should show "Applied"
# Step 18: Apply Category B migrations if needed (manual)
# Review migration list first
stella system migrations-pending --category B
# Apply after review
stella system migrations-run \
--category B \
--namespace stellaops-green \
--confirm
```
### Evidence Migration (If Required)
```bash
# Step 19: Check if evidence migration needed
stella evidence migrate --dry-run --namespace stellaops-green
# Step 20: If migration needed, execute
stella evidence migrate \
--namespace stellaops-green \
--batch-size 100 \
--progress
# Step 21: Verify evidence integrity post-migration
stella evidence verify-all \
--namespace stellaops-green \
--output /tmp/post-migration-evidence.json
```
### Health Validation
```bash
# Step 22: Run health checks on green
stella doctor --full --namespace stellaops-green
# Step 23: Run smoke tests
stella test smoke --namespace stellaops-green
# Step 24: Verify critical paths
stella test critical-paths --namespace stellaops-green
```
## Traffic Cutover
### Gradual Cutover
```bash
# Step 25: Enable canary (10%)
kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: stellaops-canary
namespace: stellaops-green
annotations:
nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-weight: "10"
spec:
ingressClassName: nginx
rules:
- host: stellaops.company.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: stellaops-api
port:
number: 80
EOF
# Step 26: Monitor for 15 minutes
# Check error rates, latency, evidence operations
# Step 27: Increase to 50%
kubectl patch ingress stellaops-canary -n stellaops-green \
--type='json' \
-p='[{"op": "replace", "path": "/metadata/annotations/nginx.ingress.kubernetes.io~1canary-weight", "value": "50"}]'
# Step 28: Monitor for 15 minutes
# Step 29: Complete cutover (100%)
kubectl patch ingress stellaops-canary -n stellaops-green \
--type='json' \
-p='[{"op": "replace", "path": "/metadata/annotations/nginx.ingress.kubernetes.io~1canary-weight", "value": "100"}]'
```
### Monitoring During Cutover
Watch these dashboards:
- Grafana: Stella Ops Overview
- Grafana: Evidence Operations
- Grafana: Attestation Pipeline
Alert thresholds:
- Error rate > 1%: Pause cutover
- p99 latency > 5s: Investigate
- Evidence failures > 0: Rollback
## Post-Upgrade Validation
### Evidence Continuity Verification
```bash
# Step 30: Verify chain-of-custody
stella evidence verify-continuity \
--baseline /backup/pre-upgrade-evidence-baseline.json \
--output /reports/continuity-report.html
# Step 31: Verify Merkle roots
stella evidence verify-roots \
--baseline /backup/pre-upgrade-merkle-roots.json \
--output /reports/roots-verification.json
# Step 32: Compare evidence stats
stella evidence stats > /tmp/post-upgrade-evidence-stats.txt
diff /backup/pre-upgrade-evidence-stats.txt /tmp/post-upgrade-evidence-stats.txt
# Step 33: Generate audit report
stella evidence audit-report \
--since "${UPGRADE_START_TIME}" \
--format pdf \
--output /reports/upgrade-audit-$(date +%Y%m%d).pdf
```
### Functional Validation
```bash
# Step 34: Full integration test
stella test integration --full
# Step 35: Scan test
stella scan \
--image registry.company.com/test-app:latest \
--sbom-format spdx-2.3
# Step 36: Attestation test
stella attest \
--subject sha256:test123 \
--predicate-type slsa-provenance
# Step 37: Policy evaluation test
stella policy evaluate \
--artifact sha256:test123 \
--environment production
```
### Post-Upgrade Checklist
- [ ] Evidence continuity verified
- [ ] Merkle roots consistent
- [ ] All services healthy
- [ ] Integration tests passing
- [ ] Scan capability verified
- [ ] Attestation generation working
- [ ] Policy evaluation working
- [ ] No elevated error rates
- [ ] Latency within SLO
**Validator signature**: __________________ **Date**: __________
## Rollback Procedures
### Immediate Rollback (During Cutover)
```bash
# Revert canary to 0%
kubectl patch ingress stellaops-canary -n stellaops-green \
--type='json' \
-p='[{"op": "replace", "path": "/metadata/annotations/nginx.ingress.kubernetes.io~1canary-weight", "value": "0"}]'
# Or delete canary entirely
kubectl delete ingress stellaops-canary -n stellaops-green
```
### Full Rollback (After Cutover)
```bash
# Step R1: Assess database state
stella system migrations-status
# Step R2: If migrations are backward-compatible
# Simply redeploy previous version
helm upgrade stellaops ./helm/stellaops \
--namespace stellaops \
--set image.tag=${PREVIOUS_VERSION} \
--wait
# Step R3: If database restore needed
# Stop all services first
kubectl scale deployment --all --replicas=0 -n stellaops
# Restore database
pg_restore -d stellaops -c /backup/stellaops-${BACKUP_TIMESTAMP}.dump
# Redeploy previous version
helm upgrade stellaops ./helm/stellaops \
--namespace stellaops \
--set image.tag=${PREVIOUS_VERSION} \
--wait
# Step R4: Verify rollback
stella doctor --full
stella evidence verify-all
```
## Cleanup
### After 72-Hour Observation
```bash
# Step 40: Verify stable operation
stella doctor --full
stella evidence verify-all
# Step 41: Remove blue environment
kubectl delete namespace stellaops-blue
# Step 42: Archive upgrade artifacts
tar -czf /archive/upgrade-${UPGRADE_TIMESTAMP}.tar.gz \
/backup/ \
/reports/ \
/tmp/pre-upgrade-*.txt
# Step 43: Update documentation
echo "${TARGET_VERSION}" > docs/CURRENT_VERSION.md
```
## Appendix
### Version-Specific Notes
See `docs/releases/{version}/MIGRATION.md` for version-specific migration notes.
### Breaking Changes Matrix
| From | To | Breaking Changes | Migration Required |
|------|-----|-----------------|-------------------|
| 2027.Q1 | 2027.Q2 | None | No |
| 2026.Q4 | 2027.Q1 | Policy schema v2 | Yes |
### Support Contacts
- Platform Team: platform@company.com
- DBA Team: dba@company.com
- Security Team: security@company.com
- On-Call: +1-555-OPS-CALL

234
docs/product/stella_ops_offer_pricing.md Normal file
View File

@@ -0,0 +1,234 @@
# Stella Ops Suite (On‑Prem) — Offer & Pricing
_Self-hosted release governance + reachability-aware security gating for **non‑Kubernetes** container deployments._
**All features are included at every tier.**
You pay only for:
1) **Environments** (policy/config boundaries)
2) **New digests deep‑scanned per month** (evidence-grade analysis of new container artifacts)
…and optionally support **tickets** if you want help.
---
## 1) What Stella Ops Suite is
**Stella Ops Suite is a release control plane + evidence engine for containerized applications outside Kubernetes.**
It provides:
- **Centralized release orchestration** (environments, promotions, approvals, rollbacks, templates)
- **Practical security signal** (reachability + hybrid reachability) to reduce noise and focus on exploitable risk
- **Auditability and attestability** (evidence packets, deterministic decision records, exportable audit trail)
- **Toolchain interoperability** (plugins for SCM/CI/registry/vault/agents)
This is designed for:
- **Small teams** that want a real, usable free tier (not a toy)
- **Mid-size companies (10–100 people)** that need **certifiable**, audit-friendly releases with practical security gates, without running Kubernetes
- **On‑prem or air‑gapped environments** where SaaS-based governance is not an option
---
## 2) Key outcomes for customers
### Secure and certifiable releases (without Kubernetes)
- Gate promotions on **evidence** (SBOM + reachability + policy explain traces)
- Produce **audit-grade proof** of “who approved what, why, and based on which evidence”
- Keep “what is deployed where” authoritative, digest-based, and reproducible
### Reduce security noise and engineering churn
- Reachability-aware prioritization focuses attention on vulnerabilities that are actually on exploitable paths (vs. raw CVE count)
### Predictable cost
- No per-user cost
- No per-project/microservice tax
- No per-target/machine tax
- No surprise overages (add-ons are explicit and self-serve)
---
## 3) What every tier includes (no feature gating)
All tiers (including Free) include the full Stella Ops capability set:
### Release orchestration (non‑K8s)
- Environments, promotions, approvals, rollbacks
- Templates and step graphs (sequential/parallel)
- UI visualization of deployments in progress (per-step logs)
- Deployment inventory view (“what is deployed where”)
### Deployment execution (non‑K8s)
- Docker Compose deployments
- Scripted deployments (**.NET 10 scripting only**)
- Immutable generated deployment artifacts
- “Version sticker” written to deployment directory for traceability
- Support for replicas and controlled restarts/reloads (e.g., config update + nginx reload)
### Security & evidence
- Scan on build, gate on release, continuous re-evaluation on vuln intel updates
- Reachability + hybrid reachability
- Evidence packets and deterministic decision records (hashable, replayable)
- Exportable audit trail (for compliance, internal audit, incident reviews)
### Extensibility
- Plugin model for SCM/CI/registry/vault/agent providers
- Plugin-specific deployment steps supported by the workflow engine
### Operability
- **Doctor tooling** for self-service diagnostics (connectivity, agent health, configuration sanity, “why blocked?” traces)
---
## 4) Verified releases vs Unverified releases
Stella supports both operational styles.
### Verified releases (recommended for production)
A **Verified Release** is one where promotions require Stella evidence for each new digest:
- SBOM + reachability evidence
- policy evaluation records
- approval records (where required)
- exportable evidence packet
Verified releases are intended for teams that need “certifiable” releases and practical security.
### Unverified releases (CD-only usage)
Stella can also run “CD-only” workflows where evidence gates are bypassed:
- still orchestrated, logged, and visible
- useful for teams that want orchestration without security certification
**Note:** CD-only users are not the primary target audience for Stella Ops Suite. The product is optimized for verified releases and auditable security.
---
## 5) Pricing (On‑Prem Suite)
**Annual billing:** pay annually and get **1 month free** (pay for 11 months).
> **Important:** All tiers have the same features. Only the scale limits and included support channels differ.
### 5.1 Stella Ops Suite tiers
| Tier | Monthly | Annual (11×) | Environments | New digests deep‑scanned / month | Deployment targets | Support |
|---|---:|---:|---:|---:|---:|---|
| **Free** | $0 | $0 | **10** | **1,000** | **Unlimited** | Self-service (Doctor) + community forum |
| **Plus** | **$199** | **$2,189** | **10** | **10,000** | **Unlimited** | Same as Free |
| **Pro** | **$599** | **$6,589** | **100** | **100,000** | **Unlimited** | Priority forum + **2 tickets/month** (typical response ~3 business days; best-effort) |
| **Business** | **$2,999** | **$32,989** | **1,000** | **1,000,000** | **Unlimited** | Priority forum + email channel + **20 tickets/month** (typical response ~24 hours; best-effort) + fair use |
### 5.2 Add-ons (self-serve)
| Add-on | Price | Notes |
|---|---:|---|
| **+10 support tickets** | **$249** | For bursts/incidents or expansion without tier change |
| **+10,000 new digest deep scans** | **$249** | Burst capacity (premium) |
---
## 6) Definitions and how metering works
### Environment
An **Environment** is a policy/config boundary (e.g., dev/stage/prod; region splits; customer isolation boundaries), with its own:
- policy profile
- targets/agents selection
- secrets/config bindings
- promotion rules
### Deployment target
A **Deployment Target** is any endpoint that can receive a deployment (Docker host group, script target via SSH/WinRM provider, etc.).
**Targets are unlimited in licensing**. Fair use applies only in extreme abuse scenarios.
### New digest deep scan
A **New Digest Deep Scan** occurs the first time Stella deeply analyzes a unique OCI digest to produce:
- SBOM
- reachability/hybrid reachability evidence
- vulnerability findings + verdict
- evidence references for gating and audit
#### What does NOT consume deep scan quota
- Re-deploying or promoting an already-scanned digest
- Re-evaluation when vulnerability intelligence updates (CVE feed updates); Stella re-computes risk using existing evidence
### Tickets
A **ticket** is a support request handled by maintainers via the paid ticket channel. For fast resolution, tickets require:
- a clear problem statement
- reproduction steps
- the **Doctor bundle** output (when applicable)
Tickets are designed to be bounded, so Stella can remain self-serve by default.
---
## 7) Fair use (Business tier)
Business tier includes very high scale limits and support capacity. To keep pricing predictable and sustainable, fair use applies to:
- vulnerability feed mirroring bandwidth and frequency (if mirroring is enabled)
- audit confirmation/verification traffic (if configured)
- excessive support ticket volume beyond included entitlements
- abusive automation patterns that intentionally generate excessive duplicate work
Fair use is intended to prevent abuse, not to penalize normal operational usage.
---
## 8) Why Stella pricing is simpler than typical alternatives
### The common pain with “legacy” stacks
Many release and security tools charge based on organizational and deployment complexity:
- per developer/committer
- per project/microservice
- per deployment target/machine
- per add-on module
That pricing becomes unpredictable as your architecture grows.
### Stella’s approach
Stella is priced like infrastructure:
- **Scale with environments and new artifacts** (the two things that actually grow with your release and security footprint)
- Keep all features available at all tiers
- Keep adoption friction low for on‑prem teams
Stella is designed to replace (or reduce dependence on) a multi-tool stack:
- one tool for CD governance + evidence
- another tool for scanning
- plus “glue” for approvals, audit, and exceptions
---
## 9) Which tier is right for you?
### Free
Best for:
- startups and small teams
- evaluation in real workflows
- internal PoCs
- teams learning the verified-release model
### Plus ($199/month)
Best for:
- mid-size teams that want verified releases but do not want vendor support
- organizations that need a predictable monthly cost and on‑prem control
### Pro ($599/month)
Best for:
- teams operating many environments and high artifact churn
- those who want occasional maintainer help without a heavy support relationship
### Business ($2,999/month)
Best for:
- regulated and compliance-driven teams
- platform teams supporting multiple product groups
- customers who want best-effort response channels and bounded ticket entitlements
---
## 10) Commercial notes (On‑Prem)
- License delivered as an on‑prem entitlement (offline-friendly where required)
- Includes product updates during the subscription term
- Customer is responsible for compute/storage required for scanning and evidence retention
- Support channel access depends on tier and ticket entitlements
---
_This document is intended as a customer-facing offer summary. Final terms and definitions may be refined in the Stella Ops subscription agreement._

2
docs/security/README.md
View File

@@ -5,7 +5,7 @@ Authoritative sources for threat models, governance, compliance, and security op
## Policies & Governance
- [SECURITY_POLICY.md](../SECURITY_POLICY.md) - responsible disclosure, support windows.
- [GOVERNANCE.md](../GOVERNANCE.md) - project governance charter.
- [CODE_OF_CONDUCT.md](../code-of-conduct/CODE_OF_CONDUCT.md) - community expectations.
- [CODE_OF_CONDUCT.md](../code-of-conduct/CODE_OF_CONDUCT.md) - Code standards guidelines.
- [SECURITY_HARDENING_GUIDE.md](../SECURITY_HARDENING_GUIDE.md) - deployment hardening steps.
- [policy-governance.md](./policy-governance.md) - policy governance specifics.
- [LEGAL_FAQ_QUOTA.md](../LEGAL_FAQ_QUOTA.md) - legal interpretation of quota.

53
docs/setup/setup-wizard-inventory.md
View File

@@ -424,30 +424,65 @@ Features:
---
## 12. Gaps Identified
## 12. Setup Wizard Backend (Platform Service)
### 12.1 Missing Components
### 12.1 API Endpoints
The Platform Service now exposes setup wizard endpoints at `/api/v1/setup/*`:
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/setup/sessions` | GET | Get current setup session for tenant |
| `/api/v1/setup/sessions` | POST | Create new setup session |
| `/api/v1/setup/sessions/resume` | POST | Resume existing or create new session |
| `/api/v1/setup/sessions/finalize` | POST | Finalize setup session |
| `/api/v1/setup/steps/execute` | POST | Execute a setup step |
| `/api/v1/setup/steps/skip` | POST | Skip an optional setup step |
| `/api/v1/setup/definitions/steps` | GET | List all step definitions |
### 12.2 Backend Components
| Component | Path | Description |
|-----------|------|-------------|
| **Contracts** | `src/Platform/StellaOps.Platform.WebService/Contracts/SetupWizardModels.cs` | Step definitions, session state, API models |
| **Service** | `src/Platform/StellaOps.Platform.WebService/Services/PlatformSetupService.cs` | Session management, step execution, Doctor integration |
| **Store** | `src/Platform/StellaOps.Platform.WebService/Services/PlatformSetupService.cs` | In-memory tenant-scoped session store |
| **Endpoints** | `src/Platform/StellaOps.Platform.WebService/Endpoints/SetupEndpoints.cs` | HTTP endpoint handlers with Problem+JSON errors |
| **Policies** | `src/Platform/StellaOps.Platform.WebService/Constants/PlatformPolicies.cs` | Setup-specific authorization policies |
### 12.3 Scopes and Authorization
| Scope | Policy | Usage |
|-------|--------|-------|
| `platform.setup.read` | `SetupRead` | Read session state and step definitions |
| `platform.setup.write` | `SetupWrite` | Create/resume sessions, execute/skip steps |
| `platform.setup.admin` | `SetupAdmin` | Admin operations (list all sessions) |
---
## 13. Gaps Identified
### 13.1 Missing Components
| Gap | Description |
|-----|-------------|
| **`stella setup` command** | No dedicated interactive setup command exists |
| **First-run detection** | No blocking wizard on first launch |
| **Wizard UI entry** | No configuration wizard in Angular UI |
| **Admin bootstrap** | Admin creation via env vars only, not interactive |
| **Integration wizard** | No guided multi-connector setup |
| **Wizard UI wiring** | UI mock exists, needs wiring to backend endpoints |
| **Doctor integration** | Backend service has placeholder, needs real Doctor calls |
### 12.2 Partial Implementations
### 13.2 Partial Implementations
| Component | Current State | Gap |
|-----------|---------------|-----|
| **Onboarding Service** | In-memory, 5-step user flow | No infrastructure setup steps |
| **Doctor checks** | 48+ checks exist | No wizard integration for fix commands |
| **Setup Service** | In-memory store | Postgres persistence not implemented |
| **Doctor checks** | 48+ checks exist | Step execution uses mock pass results |
| **Migrations** | Automatic at startup | No interactive verification step |
| **Integrations** | Plugin architecture exists | No default suggestion logic |
---
## 13. Key Architectural Patterns to Follow
## 14. Key Architectural Patterns to Follow
1. **System.CommandLine** for CLI commands
2. **Signal-based state** in Angular components