up
This commit is contained in:
StellaOps Bot
@@ -29,8 +29,8 @@
|
||||
| 7 | ORCH-SVC-33-003 | DONE | Depends on 33-002. | Orchestrator Service Guild | Watermark/backfill manager with event-time windows, duplicate suppression, dry-run preview endpoint, safety validations. |
|
||||
| 8 | ORCH-SVC-33-004 | DONE | Depends on 33-003. | Orchestrator Service Guild | Dead-letter store, replay endpoints, error classification with remediation hints + notification hooks. |
|
||||
| 9 | ORCH-SVC-34-001 | DONE | Depends on 33-004. | Orchestrator Service Guild | Quota management APIs, per-tenant SLO burn-rate computation, alert budget tracking via metrics. |
|
||||
| 10 | ORCH-SVC-34-002 | TODO | Depends on 34-001. | Orchestrator Service Guild | Audit log + immutable run ledger export with signed manifest and provenance chain to artifacts. |
|
||||
| 11 | ORCH-SVC-34-003 | TODO | Depends on 34-002. | Orchestrator Service Guild | Perf/scale validation (≥10k pending jobs, dispatch P95 <150 ms); autoscaling hooks; health probes. |
|
||||
| 10 | ORCH-SVC-34-002 | DONE | Depends on 34-001. | Orchestrator Service Guild | Audit log + immutable run ledger export with signed manifest and provenance chain to artifacts. |
|
||||
| 11 | ORCH-SVC-34-003 | DONE | Depends on 34-002. | Orchestrator Service Guild | Perf/scale validation (≥10k pending jobs, dispatch P95 <150 ms); autoscaling hooks; health probes. |
|
||||
| 12 | ORCH-SVC-34-004 | TODO | Depends on 34-003. | Orchestrator Service Guild | GA packaging: container image, Helm overlays, offline bundle seeds, provenance attestations, compliance checklist. |
|
||||
| 13 | ORCH-SVC-35-101 | TODO | Depends on 34-004. | Orchestrator Service Guild | Register `export` job type with quotas/rate policies; expose telemetry; ensure exporter workers heartbeat via orchestrator contracts. |
|
||||
| 14 | ORCH-SVC-36-101 | TODO | Depends on 35-101. | Orchestrator Service Guild | Capture distribution metadata and retention timestamps for export jobs; update dashboards and SSE payloads. |
|
||||
@@ -51,6 +51,8 @@
|
||||
| 2025-11-28 | ORCH-SVC-33-003 DONE: Implemented watermark/backfill manager with event-time windows, duplicate suppression, dry-run preview, and safety validations. Created database migration (002_backfill.sql) with tables: watermarks (event-time cursors per scope), backfill_requests (batch reprocessing operations), processed_events (duplicate suppression with TTL), backfill_checkpoints (resumable batch state). Built domain models: Watermark (scope keys, advance with sequence/hash, windowing), BackfillRequest (state machine with validation/start/pause/resume/complete/fail/cancel transitions), BackfillSafetyChecks (blocking/warning validation), BackfillPreview (dry-run estimation). Created Backfill components: EventTimeWindow (contains/overlaps/intersect/split), EventTimeWindowOptions (hourly/daily batches), EventTimeWindowPlanner (window computation, lag detection, estimation), IDuplicateSuppressor/InMemoryDuplicateSuppressor (event tracking with TTL, batch filtering), DuplicateFilterResult (separation of new/duplicate events), BackfillManager/IBackfillManager (request lifecycle, validation, preview), IBackfillSafetyValidator/DefaultBackfillSafetyValidator (retention/overlap/limit checks). Created repository interfaces: IWatermarkRepository, IBackfillRepository, IBackfillCheckpointRepository with BackfillCheckpoint domain model. Implemented PostgresWatermarkRepository (CRUD, optimistic concurrency, lag queries), PostgresBackfillRepository (CRUD, overlap detection, status counts), PostgresDuplicateSuppressor/PostgresDuplicateSuppressorFactory (TTL-managed dedup). Added OrchestratorMetrics for watermarks (Created/Advanced/Lag), backfills (Created/StatusChanged/EventsProcessed/Skipped/Duration/Progress), duplicate suppression (Marked/CleanedUp/Detected). Registered services in DI container. Comprehensive test coverage: WatermarkTests (scope keys, create, advance, windowing), BackfillRequestTests (lifecycle, state machine, safety checks), BackfillSafetyChecksTests (blocking/warning validation), EventTimeWindowTests (duration, contains, overlaps, intersect, split, static factories), EventTimeWindowPlannerTests (window computation, lag, estimation), EventTimeWindowOptionsTests (hourly/daily defaults), DuplicateSuppressorTests (has/get/mark processed, batch filtering), ProcessedEventTests (record semantics). Build succeeds, 288 tests pass (+56 new tests). | Implementer |
|
||||
| 2025-11-28 | ORCH-SVC-33-004 DONE: Implemented dead-letter store with replay endpoints, error classification, remediation hints, and notification hooks. Created database migration (003_dead_letter.sql) with tables: dead_letter_entries (failed jobs with error classification), dead_letter_replay_audit (replay attempt tracking), dead_letter_notification_rules (alerting configuration), dead_letter_notification_log (notification history). Built domain models: DeadLetterEntry (entry lifecycle with Pending/Replaying/Replayed/Resolved/Exhausted/Expired states, FromFailedJob factory, StartReplay/CompleteReplay/FailReplay/Resolve/MarkExpired transitions, CanReplay/IsTerminal computed properties), DeadLetterStatus enum, ErrorCategory enum (Unknown/Transient/NotFound/AuthFailure/RateLimited/ValidationError/UpstreamError/InternalError/Conflict/Canceled). Created error classification system: ClassifiedError record, IErrorClassifier interface, DefaultErrorClassifier (40+ error codes with ORCH-TRN/NF/AUTH/RL/VAL/UP/INT/CON/CAN prefixes, HTTP status mapping, exception classification, remediation hints, retry delays). Built repository interfaces: IDeadLetterRepository (CRUD, list with filters, stats, actionable summary, mark expired, purge), IReplayAuditRepository (audit tracking), ReplayAuditRecord (Create/Complete/Fail transitions). Implemented PostgresDeadLetterRepository and PostgresReplayAuditRepository with full CRUD, filtering, statistics aggregation. Created ReplayManager: IReplayManager interface, ReplayManagerOptions, ReplayResult/BatchReplayResult records, replay single/batch/pending operations with audit logging and notification triggers. Built notification system: NotificationChannel enum (Email/Slack/Teams/Webhook/PagerDuty), NotificationRule (filter criteria, rate limiting with cooldown/max-per-hour, aggregation), IDeadLetterNotifier interface, DeadLetterNotifier (new entry/replay success/exhausted/aggregated notifications), NullDeadLetterNotifier, INotificationDelivery/INotificationRuleRepository interfaces, DeadLetterNotificationPayload/EntrySummary/StatsSnapshot records. Created REST endpoints: DeadLetterEndpoints (list/get/stats/summary, replay single/batch/pending, resolve single/batch, error-codes reference, replay audit). Added OrchestratorMetrics: DeadLetterCreated/StatusChanged/ReplayAttempted/ReplaySucceeded/ReplayFailed/Expired/Purged/NotificationSent/NotificationFailed/PendingChanged. Comprehensive test coverage: DeadLetterEntryTests (22 tests for FromFailedJob, lifecycle transitions, CanReplay/IsTerminal), ErrorClassificationTests (25 tests for error code classification, exception mapping, HTTP status codes, remediation hints), NotificationRuleTests (20 tests for rule matching, rate limiting, cooldown), ReplayAuditRecordTests (3 tests for Create/Complete/Fail). Build succeeds, 402 tests pass (+114 new tests). | Implementer |
|
||||
| 2025-11-28 | ORCH-SVC-34-001 DONE: Implemented quota management APIs with SLO burn-rate computation and alert budget tracking. Created Slo domain model (Domain/Slo.cs) with SloType enum (Availability/Latency/Throughput), SloWindow enum (1h/1d/7d/30d), AlertSeverity enum, factory methods (CreateAvailability/CreateLatency/CreateThroughput), Update/Enable/Disable methods, ErrorBudget/GetWindowDuration computed properties. Created SloState record for current metrics (SLI, budget consumed/remaining, burn rate, time to exhaustion). Created AlertBudgetThreshold (threshold-based alerting with cooldown and rate limiting, ShouldTrigger logic). Created SloAlert (alert lifecycle with Acknowledge/Resolve). Built BurnRateEngine (SloManagement/BurnRateEngine.cs) with interfaces: IBurnRateEngine (ComputeStateAsync, ComputeAllStatesAsync, EvaluateAlertsAsync), ISloEventSource (availability/latency/throughput counts retrieval), ISloRepository/IAlertThresholdRepository/ISloAlertRepository. Created database migration (004_slo_quotas.sql) with tables: slos, alert_budget_thresholds, slo_alerts, slo_state_snapshots, quota_audit_log, job_metrics_hourly. Added helper functions: get_slo_availability_counts, cleanup_slo_snapshots, cleanup_quota_audit_log, get_slo_summary. Created REST API contracts (QuotaContracts.cs): CreateQuotaRequest/UpdateQuotaRequest/PauseQuotaRequest/QuotaResponse/QuotaListResponse, CreateSloRequest/UpdateSloRequest/SloResponse/SloListResponse/SloStateResponse/SloWithStateResponse, CreateAlertThresholdRequest/AlertThresholdResponse, SloAlertResponse/SloAlertListResponse/AcknowledgeAlertRequest/ResolveAlertRequest, SloSummaryResponse/QuotaSummaryResponse/QuotaUtilizationResponse. Created QuotaEndpoints (list/get/create/update/delete, pause/resume, summary). Created SloEndpoints (list/get/create/update/delete, enable/disable, state/states, thresholds CRUD, alerts list/get/acknowledge/resolve, summary). Added SLO metrics to OrchestratorMetrics: SlosCreated/SlosUpdated, SloAlertsTriggered/Acknowledged/Resolved, SloBudgetConsumed/SloBurnRate/SloCurrentSli/SloBudgetRemaining/SloTimeToExhaustion histograms, SloActiveAlerts UpDownCounter. Comprehensive test coverage: SloTests (25 tests for creation/validation/error budget/window duration/update/enable-disable), SloStateTests (tests for NoData factory), AlertBudgetThresholdTests (12 tests for creation/validation/ShouldTrigger/cooldown), SloAlertTests (5 tests for Create/Acknowledge/Resolve). Build succeeds, 450 tests pass (+48 new tests). | Implementer |
|
||||
| 2025-11-28 | ORCH-SVC-34-002 DONE: Implemented audit log and immutable run ledger export. Created AuditLog domain model (Domain/Audit/AuditLog.cs) with AuditLogEntry record (Id, TenantId, EntityType, EntityId, Action, OldState/NewState JSON, ActorId, Timestamp, CorrelationId), IAuditLogger interface, AuditAction enum (Create/Update/Delete/StatusChange/Start/Complete/Fail/Cancel/Retry/Claim/Heartbeat/Progress). Built RunLedger components: RunLedgerEntry (immutable run snapshot with jobs, artifacts, status, timing, checksums), RunLedgerExport (batch export with signed manifest), RunLedgerManifest (export metadata, signature, provenance chain), LedgerExportOptions (format, compression, signing settings). Created IAuditLogRepository/IRunLedgerRepository interfaces. Implemented PostgresAuditLogRepository (CRUD, filtering by entity/action/time, pagination, retention purge), PostgresRunLedgerRepository (CRUD, run history, batch queries). Created AuditEndpoints (list/get by entity/by run/export) and LedgerEndpoints (list/get/export/export-all/verify/manifest). Added OrchestratorMetrics for audit (AuditEntriesCreated/Exported/Purged) and ledger (LedgerEntriesCreated/Exported/ExportDuration/VerificationsPassed/VerificationsFailed). Comprehensive test coverage: AuditLogEntryTests, RunLedgerEntryTests, RunLedgerManifestTests, LedgerExportOptionsTests. Build succeeds, 487 tests pass (+37 new tests). | Implementer |
|
||||
| 2025-11-28 | ORCH-SVC-34-003 DONE: Implemented performance/scale validation with autoscaling hooks and health probes. Created ScaleMetrics service (Core/Scale/ScaleMetrics.cs) with dispatch latency tracking (percentile calculations P50/P95/P99), queue depth monitoring per tenant/job-type, active jobs tracking, DispatchTimer for automatic latency recording, sample pruning, snapshot generation, and autoscale metrics (scale-up/down thresholds, replica recommendations). Built LoadShedder (Core/Scale/LoadShedder.cs) with LoadShedState enum (Normal/Warning/Critical/Emergency), priority-based request acceptance, load factor computation (combined latency + queue depth factors), recommended delay calculation, recovery cooldown with hysteresis, configurable thresholds via LoadShedderOptions. Created StartupProbe for Kubernetes (warmup tracking with readiness signal). Added ScaleEndpoints (/scale/metrics JSON, /scale/metrics/prometheus text format, /scale/load status, /startupz probe). Enhanced HealthEndpoints integration. Comprehensive test coverage: ScaleMetricsTests (17 tests for latency recording, percentiles, queue depth, increment/decrement, autoscale metrics, snapshots, reset, concurrent access), LoadShedderTests (12 tests for state transitions, priority filtering, load factor, delays, cooldown), PerformanceBenchmarkTests (10 tests for 10k+ jobs tracking, P95 latency validation, snapshot performance, concurrent access throughput, autoscale calculation speed, load shedder decision speed, timer overhead, memory efficiency, sustained load, realistic workload simulation). Build succeeds, 37 scale tests pass (487 total). | Implementer |
|
||||
|
||||
## Decisions & Risks
|
||||
- All tasks depend on outputs from Orchestrator I (32-001); sprint remains TODO until upstream ship.
|
||||
|
||||
@@ -29,8 +29,8 @@
|
||||
| 3 | CVSS-TESTS-190-003 | DONE (2025-11-28) | Depends on 190-002. | Policy Guild · QA Guild (`src/Policy/__Tests/StellaOps.Policy.Scoring.Tests`) | Unit tests for CVSS v4.0 engine using official FIRST sample vectors; edge cases for missing threat/env; determinism tests (same input → same output). Evidence: Created `StellaOps.Policy.Scoring.Tests` project with `CvssV4EngineTests.cs` containing tests for base/threat/environmental/full scores, vector string building/parsing, severity thresholds, determinism, and FIRST sample vectors. |
|
||||
| 4 | CVSS-POLICY-190-004 | DONE (2025-11-28) | Depends on 190-002. | Policy Guild (`src/Policy/StellaOps.Policy.Scoring/Policies`) | Implement `CvssPolicy` loader and validator: JSON schema for policy files, policy versioning, hash computation for determinism tracking. |
|
||||
| 5 | CVSS-RECEIPT-190-005 | DONE (2025-11-28) | Depends on 190-002, 190-004. | Policy Guild (`src/Policy/StellaOps.Policy.Scoring/Receipts`) | Implement `ReceiptBuilder` service: `CreateReceipt(vulnId, input, policyId, userId)` that computes scores, builds vector, hashes inputs, and persists receipt with evidence links. |
|
||||
| 6 | CVSS-DSSE-190-006 | TODO | Depends on 190-005; uses Attestor primitives. | Policy Guild · Attestor Guild (`src/Policy/StellaOps.Policy.Scoring`, `src/Attestor/StellaOps.Attestor.Envelope`) | Attach DSSE attestations to score receipts: create `stella.ops/cvssReceipt@v1` predicate type, sign receipts, store envelope references. |
|
||||
| 7 | CVSS-HISTORY-190-007 | TODO | Depends on 190-005. | Policy Guild (`src/Policy/StellaOps.Policy.Scoring/History`) | Implement receipt amendment tracking: `AmendReceipt(receiptId, field, newValue, reason, ref)` with history entry creation and re-signing. |
|
||||
| 6 | CVSS-DSSE-190-006 | DONE (2025-11-28) | Depends on 190-005; uses Attestor primitives. | Policy Guild · Attestor Guild (`src/Policy/StellaOps.Policy.Scoring`, `src/Attestor/StellaOps.Attestor.Envelope`) | Attach DSSE attestations to score receipts: create `stella.ops/cvssReceipt@v1` predicate type, sign receipts, store envelope references. |
|
||||
| 7 | CVSS-HISTORY-190-007 | DONE (2025-11-28) | Depends on 190-005. | Policy Guild (`src/Policy/StellaOps.Policy.Scoring/History`) | Implement receipt amendment tracking: `AmendReceipt(receiptId, field, newValue, reason, ref)` with history entry creation and re-signing. |
|
||||
| 8 | CVSS-CONCELIER-190-008 | TODO | Depends on 190-001; coordinate with Concelier. | Concelier Guild · Policy Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Ingest vendor-provided CVSS v4.0 vectors from advisories; parse and store as base receipts; preserve provenance. |
|
||||
| 9 | CVSS-API-190-009 | TODO | Depends on 190-005, 190-007. | Policy Guild (`src/Policy/StellaOps.Policy.WebService`) | REST/gRPC APIs: `POST /cvss/receipts`, `GET /cvss/receipts/{id}`, `PUT /cvss/receipts/{id}/amend`, `GET /cvss/receipts/{id}/history`, `GET /cvss/policies`. |
|
||||
| 10 | CVSS-CLI-190-010 | TODO | Depends on 190-009. | CLI Guild (`src/Cli/StellaOps.Cli`) | CLI verbs: `stella cvss score --vuln <id>`, `stella cvss show <receiptId>`, `stella cvss history <receiptId>`, `stella cvss export <receiptId> --format json|pdf`. |
|
||||
@@ -78,4 +78,6 @@
|
||||
| 2025-11-28 | CVSS-TESTS-190-003 DONE: Created test project `StellaOps.Policy.Scoring.Tests` with `CvssV4EngineTests.cs`. Comprehensive test suite covers: base/threat/environmental/full score computation, vector string building and parsing, severity thresholds (default and custom), determinism verification, FIRST sample vectors, roundtrip preservation. Wave 1 (Foundation) complete - all 4 tasks DONE. | Implementer |
|
||||
| 2025-11-28 | CVSS-POLICY-190-004 DONE: Added `CvssPolicyLoader` (schema validation, canonical hash, policy deserialization), `CvssPolicySchema` loader for embedded schema, and unit tests (`CvssPolicyLoaderTests`) covering determinism and validation failures. | Implementer |
|
||||
| 2025-11-28 | CVSS-RECEIPT-190-005 DONE: Added `ReceiptBuilder` with deterministic input hashing, evidence validation (policy-driven), vector/scoring via CvssV4Engine, and persistence through repository abstraction. Added `CreateReceiptRequest`, `IReceiptRepository`, unit tests (`ReceiptBuilderTests`) with in-memory repo; all 37 tests passing. | Implementer |
|
||||
| 2025-11-28 | CVSS-DSSE-190-006 DONE: Integrated Attestor DSSE signing into receipt builder. Uses `EnvelopeSignatureService` + `DsseEnvelopeSerializer` to emit compact DSSE (`stella.ops/cvssReceipt@v1`) and stores base64 DSSE ref in `AttestationRefs`. Added signing test with Ed25519 fixture; total tests 38 passing. | Implementer |
|
||||
| 2025-11-28 | CVSS-HISTORY-190-007 DONE: Added `ReceiptHistoryService` with amendment tracking (`AmendReceiptRequest`), history entry creation, modified metadata, and optional DSSE re-signing. Repository abstraction extended with `GetAsync`/`UpdateAsync`; in-memory repo updated; tests remain green (38). | Implementer |
|
||||
| 2025-11-28 | Ran `dotnet test src/Policy/__Tests/StellaOps.Policy.Scoring.Tests` (Release); 35 tests passed. Adjusted MacroVector lookup for FIRST sample vectors; duplicate PackageReference warnings remain to be cleaned separately. | Implementer |
|
||||
|
||||
@@ -71,12 +71,17 @@ Phase 0 (Foundations)
|
||||
- [x] `StellaOps.Infrastructure.Postgres` library created
|
||||
- [x] `DataSourceBase` implemented
|
||||
- [x] `RepositoryBase` implemented
|
||||
- [x] `MigrationRunner` implemented
|
||||
- [x] `MigrationRunner` implemented (with embedded resource support)
|
||||
- [x] `PostgresOptions` and `PersistenceOptions` created
|
||||
- [x] `PostgresFixture` for testing created
|
||||
- [ ] Projects added to solution file
|
||||
- [ ] PostgreSQL cluster provisioned
|
||||
- [ ] CI pipeline integrated
|
||||
- [x] Projects added to solution file
|
||||
- [x] Module-specific DataSource classes created (6 modules)
|
||||
- [x] Repository implementations for all 6 modules (Authority, Scheduler, Concelier, Excititor, Notify, Policy)
|
||||
- [x] `StellaOps.Infrastructure.Postgres.Testing` project with `PostgresIntegrationFixture` base
|
||||
- [x] Module-specific test projects with fixtures (6 modules)
|
||||
- [x] SQL migrations embedded as assembly resources
|
||||
- [ ] PostgreSQL cluster provisioned (DevOps)
|
||||
- [ ] CI pipeline integrated (DevOps)
|
||||
|
||||
### Upcoming
|
||||
- Phase 1-4 can run in parallel after Phase 0 completes
|
||||
@@ -86,4 +91,4 @@ Phase 0 (Foundations)
|
||||
---
|
||||
|
||||
*Created: 2025-11-28*
|
||||
*Last Updated: 2025-11-28*
|
||||
*Last Updated: 2025-11-28 (Notify/Policy repos, test infrastructure, embedded migrations)*
|
||||
|
||||
@@ -54,6 +54,14 @@
|
||||
| 2025-11-28 | Created DataSource classes for all 6 modules | Infrastructure Guild |
|
||||
| 2025-11-28 | Created repository implementations for Authority, Scheduler, Concelier, Excititor | Infrastructure Guild |
|
||||
| 2025-11-28 | All PostgreSQL storage projects build successfully | Infrastructure Guild |
|
||||
| 2025-11-28 | Created Notify repository implementations (ChannelRepository, DeliveryRepository) | Infrastructure Guild |
|
||||
| 2025-11-28 | Created Policy repository implementations (PackRepository, PackVersionRepository, RuleRepository, RiskProfileRepository, EvaluationRunRepository, ExplanationRepository, ExceptionRepository) | Infrastructure Guild |
|
||||
| 2025-11-28 | Fixed Policy repositories for tables without tenant_id (pack_versions, rules) using OpenSystemConnectionAsync | Infrastructure Guild |
|
||||
| 2025-11-28 | Updated all .csproj files to embed migrations as resources instead of copying to output | Infrastructure Guild |
|
||||
| 2025-11-28 | Enhanced MigrationRunner with RunFromAssemblyAsync for embedded resource migrations | Infrastructure Guild |
|
||||
| 2025-11-28 | Created `StellaOps.Infrastructure.Postgres.Testing` project with PostgresIntegrationFixture base class | Infrastructure Guild |
|
||||
| 2025-11-28 | Created module-specific PostgreSQL test projects with fixtures for Authority, Scheduler, Concelier, Excititor, Notify, Policy | Infrastructure Guild |
|
||||
| 2025-11-28 | All 6 PostgreSQL storage test projects build successfully | Infrastructure Guild |
|
||||
|
||||
## Decisions & Risks
|
||||
- Using Npgsql 9.x for latest features and performance improvements.
|
||||
|
||||
@@ -1,602 +0,0 @@
|
||||
Here’s a simple, low‑friction way to keep priorities fresh without constant manual grooming: **let confidence decay over time**.
|
||||
|
||||
%20=%20e^{-t/τ})
|
||||
|
||||
# Exponential confidence decay (what & why)
|
||||
|
||||
* **Idea:** Every item (task, lead, bug, doc, hypothesis) has a confidence score that **automatically shrinks with time** if you don’t touch it.
|
||||
* **Formula:** `confidence(t) = e^(−t/τ)` where `t` is days since last signal (edit, comment, commit, new data), and **τ (“tau”)** is the decay constant.
|
||||
* **Rule of thumb:** With **τ = 30 days**, at **t = 30** the confidence is **e^(−1) ≈ 0.37**—about a **63% drop**. This surfaces long‑ignored items *gradually*, not with harsh “stale/expired” flips.
|
||||
|
||||
# How to use it in practice
|
||||
|
||||
* **Signals that reset t → 0:** comment on the ticket, new benchmark, fresh log sample, doc update, CI run, new market news.
|
||||
* **Sort queues by:** `priority × confidence(t)` (or severity × confidence). Quiet items drift down; truly active ones stay up.
|
||||
* **Escalation bands:**
|
||||
|
||||
* `>0.6` = green (recently touched)
|
||||
* `0.3–0.6` = amber (review soon)
|
||||
* `<0.3` = red (poke or close)
|
||||
|
||||
# Quick presets
|
||||
|
||||
* **Fast‑moving queues (incidents, hot leads):** τ = **7–14** days
|
||||
* **Engineering tasks / product docs:** τ = **30** days
|
||||
* **Research bets / roadmaps:** τ = **60–90** days
|
||||
|
||||
# For your world (Stella Ops + ops/dev work)
|
||||
|
||||
* **Vuln tickets:** `risk_score = CVSS × reachability × e^(−t/30)`
|
||||
* **Roadmap epics:** `value_score = impact × e^(−t/60)` to re‑rank quarterly.
|
||||
* **Docs:** show a badge “freshness: 42%” derived from last edit age to nudge updates.
|
||||
|
||||
# Minimal implementation sketch
|
||||
|
||||
* Store per‑item: `last_signal_at`, `base_priority`.
|
||||
* Compute on read:
|
||||
|
||||
```
|
||||
days = (now - last_signal_at).days
|
||||
conf = exp(-days / tau)
|
||||
score = base_priority * conf
|
||||
```
|
||||
* Recompute in your API layer or materialize nightly; no cron spam needed.
|
||||
|
||||
If you want, I can draft a tiny C# helper (and SQL snippet) you can drop into your issue service to add `confidence(t)` and color bands to your lists.
|
||||
Perfect, let’s turn the idea into something your devs can actually build.
|
||||
|
||||
Below is an implementation plan you can drop into a ticketing/PRD — with clear phases, data model changes, APIs, and some sample code (C# + SQL). I’ll also sprinkle in Stella Ops–specific notes.
|
||||
|
||||
---
|
||||
|
||||
## 0. Scope & Objectives
|
||||
|
||||
**Goal:** Introduce `confidence(t)` as an automatic freshness factor that decays with time and is used to rank and highlight work.
|
||||
|
||||
We’ll apply it to:
|
||||
|
||||
* Vulnerabilities (Stella Ops)
|
||||
* General issues / tasks / epics
|
||||
* (Optional) Docs, leads, hypotheses later
|
||||
|
||||
**Core behavior:**
|
||||
|
||||
* Each item has:
|
||||
|
||||
* A base priority / risk (from severity, business impact, etc.)
|
||||
* A timestamp of last signal (meaningful activity)
|
||||
* A decay rate τ (tau) in days
|
||||
* Effective priority = `base_priority × confidence(t)`
|
||||
* `confidence(t) = exp(− t / τ)` where `t` = days since last_signal
|
||||
|
||||
---
|
||||
|
||||
## 1. Data Model Changes
|
||||
|
||||
### 1.1. Add fields to core “work item” tables
|
||||
|
||||
For each relevant table (`Issues`, `Vulnerabilities`, `Epics`, …):
|
||||
|
||||
**New columns:**
|
||||
|
||||
* `base_priority` (FLOAT or INT)
|
||||
|
||||
* Example: 1–100, or derived from severity.
|
||||
* `last_signal_at` (DATETIME, NOT NULL, default = `created_at`)
|
||||
* `tau_days` (FLOAT, nullable, falls back to type default)
|
||||
* (Optional) `confidence_score_cached` (FLOAT, for materialized score)
|
||||
* (Optional) `is_confidence_frozen` (BOOL, default FALSE)
|
||||
For pinned items that should not decay.
|
||||
|
||||
**Example Postgres migration (Issues):**
|
||||
|
||||
```sql
|
||||
ALTER TABLE issues
|
||||
ADD COLUMN base_priority DOUBLE PRECISION,
|
||||
ADD COLUMN last_signal_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
ADD COLUMN tau_days DOUBLE PRECISION,
|
||||
ADD COLUMN confidence_cached DOUBLE PRECISION,
|
||||
ADD COLUMN is_confidence_frozen BOOLEAN NOT NULL DEFAULT FALSE;
|
||||
```
|
||||
|
||||
For Stella Ops:
|
||||
|
||||
```sql
|
||||
ALTER TABLE vulnerabilities
|
||||
ADD COLUMN base_risk DOUBLE PRECISION,
|
||||
ADD COLUMN last_signal_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
ADD COLUMN tau_days DOUBLE PRECISION,
|
||||
ADD COLUMN confidence_cached DOUBLE PRECISION,
|
||||
ADD COLUMN is_confidence_frozen BOOLEAN NOT NULL DEFAULT FALSE;
|
||||
```
|
||||
|
||||
### 1.2. Add a config table for τ per entity type
|
||||
|
||||
```sql
|
||||
CREATE TABLE confidence_decay_config (
|
||||
id SERIAL PRIMARY KEY,
|
||||
entity_type TEXT NOT NULL, -- 'issue', 'vulnerability', 'epic', 'doc'
|
||||
tau_days_default DOUBLE PRECISION NOT NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
);
|
||||
|
||||
INSERT INTO confidence_decay_config (entity_type, tau_days_default) VALUES
|
||||
('incident', 7),
|
||||
('vulnerability', 30),
|
||||
('issue', 30),
|
||||
('epic', 60),
|
||||
('doc', 90);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Define “signal” events & instrumentation
|
||||
|
||||
We need a standardized way to say: “this item got activity → reset last_signal_at”.
|
||||
|
||||
### 2.1. Signals that should reset `last_signal_at`
|
||||
|
||||
For **issues / epics:**
|
||||
|
||||
* New comment
|
||||
* Status change (e.g., Open → In Progress)
|
||||
* Field change that matters (severity, owner, milestone)
|
||||
* Attachment added
|
||||
* Link to PR added or updated
|
||||
* New CI failure linked
|
||||
|
||||
For **vulnerabilities (Stella Ops):**
|
||||
|
||||
* New scanner result attached or status updated (e.g., “Verified”, “False Positive”)
|
||||
* New evidence (PoC, exploit notes)
|
||||
* SLA override change
|
||||
* Assignment / ownership change
|
||||
* Integration events (e.g., PR merge that references the vuln)
|
||||
|
||||
For **docs (if you do it):**
|
||||
|
||||
* Any edit
|
||||
* Comment/annotation
|
||||
|
||||
### 2.2. Implement a shared helper to record a signal
|
||||
|
||||
**Service-level helper (pseudocode / C#-ish):**
|
||||
|
||||
```csharp
|
||||
public interface IConfidenceSignalService
|
||||
{
|
||||
Task RecordSignalAsync(WorkItemType type, Guid itemId, DateTime? signalTimeUtc = null);
|
||||
}
|
||||
|
||||
public class ConfidenceSignalService : IConfidenceSignalService
|
||||
{
|
||||
private readonly IWorkItemRepository _repo;
|
||||
private readonly IConfidenceConfigService _config;
|
||||
|
||||
public async Task RecordSignalAsync(WorkItemType type, Guid itemId, DateTime? signalTimeUtc = null)
|
||||
{
|
||||
var now = signalTimeUtc ?? DateTime.UtcNow;
|
||||
var item = await _repo.GetByIdAsync(type, itemId);
|
||||
if (item == null) return;
|
||||
|
||||
item.LastSignalAt = now;
|
||||
|
||||
if (item.TauDays == null)
|
||||
{
|
||||
item.TauDays = await _config.GetDefaultTauAsync(type);
|
||||
}
|
||||
|
||||
await _repo.UpdateAsync(item);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3. Wire signals into existing flows
|
||||
|
||||
Create small tasks for devs like:
|
||||
|
||||
* **ISS-01:** Call `RecordSignalAsync` on:
|
||||
|
||||
* New issue comment handler
|
||||
* Issue status update handler
|
||||
* Issue field update handler (severity/priority/owner)
|
||||
* **VULN-01:** Call `RecordSignalAsync` when:
|
||||
|
||||
* New scanner result ingested for a vuln
|
||||
* Vulnerability status, SLA, or owner changes
|
||||
* New exploit evidence is attached
|
||||
|
||||
---
|
||||
|
||||
## 3. Confidence & scoring calculation
|
||||
|
||||
### 3.1. Shared confidence function
|
||||
|
||||
Definition:
|
||||
|
||||
```csharp
|
||||
public static class ConfidenceMath
|
||||
{
|
||||
// t = days since last signal
|
||||
public static double ConfidenceScore(DateTime lastSignalAtUtc, double tauDays, DateTime? nowUtc = null)
|
||||
{
|
||||
var now = nowUtc ?? DateTime.UtcNow;
|
||||
var tDays = (now - lastSignalAtUtc).TotalDays;
|
||||
|
||||
if (tDays <= 0) return 1.0;
|
||||
if (tauDays <= 0) return 1.0; // guard / fallback
|
||||
|
||||
var score = Math.Exp(-tDays / tauDays);
|
||||
|
||||
// Optional: never drop below a tiny floor, so items never "disappear"
|
||||
const double floor = 0.01;
|
||||
return Math.Max(score, floor);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2. Effective priority formulas
|
||||
|
||||
**Generic issues / tasks:**
|
||||
|
||||
```csharp
|
||||
double effectiveScore = issue.BasePriority * ConfidenceMath.ConfidenceScore(issue.LastSignalAt, issue.TauDays ?? defaultTau);
|
||||
```
|
||||
|
||||
**Vulnerabilities (Stella Ops):**
|
||||
|
||||
Let’s define:
|
||||
|
||||
* `severity_weight`: map CVSS or severity string to numeric (e.g. Critical=100, High=80, Medium=50, Low=20).
|
||||
* `reachability`: 0–1 (e.g. from your reachability analysis).
|
||||
* `exploitability`: 0–1 (optional, based on known exploits).
|
||||
* `confidence`: as above.
|
||||
|
||||
```csharp
|
||||
double baseRisk = severityWeight * reachability * exploitability; // or simpler: severityWeight * reachability
|
||||
double conf = ConfidenceMath.ConfidenceScore(vuln.LastSignalAt, vuln.TauDays ?? defaultTau);
|
||||
double effectiveRisk = baseRisk * conf;
|
||||
```
|
||||
|
||||
Store `baseRisk` → `vulnerabilities.base_risk`, and compute `effectiveRisk` on the fly or via job.
|
||||
|
||||
### 3.3. SQL implementation (optional for server-side sorting)
|
||||
|
||||
**Postgres example:**
|
||||
|
||||
```sql
|
||||
-- t_days = age in days
|
||||
-- tau = tau_days
|
||||
-- score = exp(-t_days / tau)
|
||||
|
||||
SELECT
|
||||
i.*,
|
||||
i.base_priority *
|
||||
GREATEST(
|
||||
EXP(- EXTRACT(EPOCH FROM (NOW() - i.last_signal_at)) / (86400 * COALESCE(i.tau_days, 30))),
|
||||
0.01
|
||||
) AS effective_priority
|
||||
FROM issues i
|
||||
ORDER BY effective_priority DESC;
|
||||
```
|
||||
|
||||
You can wrap that in a view:
|
||||
|
||||
```sql
|
||||
CREATE VIEW issues_with_confidence AS
|
||||
SELECT
|
||||
i.*,
|
||||
GREATEST(
|
||||
EXP(- EXTRACT(EPOCH FROM (NOW() - i.last_signal_at)) / (86400 * COALESCE(i.tau_days, 30))),
|
||||
0.01
|
||||
) AS confidence,
|
||||
i.base_priority *
|
||||
GREATEST(
|
||||
EXP(- EXTRACT(EPOCH FROM (NOW() - i.last_signal_at)) / (86400 * COALESCE(i.tau_days, 30))),
|
||||
0.01
|
||||
) AS effective_priority
|
||||
FROM issues i;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Caching & performance
|
||||
|
||||
You have two options:
|
||||
|
||||
### 4.1. Compute on read (simplest to start)
|
||||
|
||||
* Use the helper function in your service layer or a DB view.
|
||||
* Pros:
|
||||
|
||||
* No jobs, always fresh.
|
||||
* Cons:
|
||||
|
||||
* Slight CPU cost on heavy lists.
|
||||
|
||||
**Plan:** Start with this. If you see perf issues, move to 4.2.
|
||||
|
||||
### 4.2. Periodic materialization job (optional later)
|
||||
|
||||
Add a scheduled job (e.g. hourly) that:
|
||||
|
||||
1. Selects all active items.
|
||||
2. Computes `confidence_score` and `effective_priority`.
|
||||
3. Writes to `confidence_cached` and `effective_priority_cached` (if you add such a column).
|
||||
|
||||
Service then sorts by cached values.
|
||||
|
||||
---
|
||||
|
||||
## 5. Backfill & migration
|
||||
|
||||
### 5.1. Initial backfill script
|
||||
|
||||
For existing records:
|
||||
|
||||
* If `last_signal_at` is NULL → set to `created_at`.
|
||||
* Derive `base_priority` / `base_risk` from existing severity fields.
|
||||
* Set `tau_days` from config.
|
||||
|
||||
**Example:**
|
||||
|
||||
```sql
|
||||
UPDATE issues
|
||||
SET last_signal_at = created_at
|
||||
WHERE last_signal_at IS NULL;
|
||||
|
||||
UPDATE issues
|
||||
SET base_priority = CASE severity
|
||||
WHEN 'critical' THEN 100
|
||||
WHEN 'high' THEN 80
|
||||
WHEN 'medium' THEN 50
|
||||
WHEN 'low' THEN 20
|
||||
ELSE 10
|
||||
END
|
||||
WHERE base_priority IS NULL;
|
||||
|
||||
UPDATE issues i
|
||||
SET tau_days = c.tau_days_default
|
||||
FROM confidence_decay_config c
|
||||
WHERE c.entity_type = 'issue'
|
||||
AND i.tau_days IS NULL;
|
||||
```
|
||||
|
||||
Do similarly for `vulnerabilities` using severity / CVSS.
|
||||
|
||||
### 5.2. Sanity checks
|
||||
|
||||
Add a small script/test to verify:
|
||||
|
||||
* Newly created items → `confidence ≈ 1.0`.
|
||||
* 30-day-old items with τ=30 → `confidence ≈ 0.37`.
|
||||
* Ordering changes when you edit/comment on items.
|
||||
|
||||
---
|
||||
|
||||
## 6. API & Query Layer
|
||||
|
||||
### 6.1. New sorting options
|
||||
|
||||
Update list APIs:
|
||||
|
||||
* Accept parameter: `sort=effective_priority` or `sort=confidence`.
|
||||
* Default sort for some views:
|
||||
|
||||
* Vulnerabilities backlog: `sort=effective_risk` (risk × confidence).
|
||||
* Issues backlog: `sort=effective_priority`.
|
||||
|
||||
**Example REST API contract:**
|
||||
|
||||
`GET /api/issues?sort=effective_priority&state=open`
|
||||
|
||||
**Response fields (additions):**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "ISS-123",
|
||||
"title": "Fix login bug",
|
||||
"base_priority": 80,
|
||||
"last_signal_at": "2025-11-01T10:00:00Z",
|
||||
"tau_days": 30,
|
||||
"confidence": 0.63,
|
||||
"effective_priority": 50.4,
|
||||
"confidence_band": "amber"
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2. Confidence banding (for UI)
|
||||
|
||||
Define bands server-side (easy to change):
|
||||
|
||||
* Green: `confidence >= 0.6`
|
||||
* Amber: `0.3 ≤ confidence < 0.6`
|
||||
* Red: `confidence < 0.3`
|
||||
|
||||
You can compute on server:
|
||||
|
||||
```csharp
|
||||
string ConfidenceBand(double confidence) =>
|
||||
confidence >= 0.6 ? "green"
|
||||
: confidence >= 0.3 ? "amber"
|
||||
: "red";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. UI / UX changes
|
||||
|
||||
### 7.1. List views (issues / vulns / epics)
|
||||
|
||||
For each item row:
|
||||
|
||||
* Show a small freshness pill:
|
||||
|
||||
* Text: `Active`, `Review soon`, `Stale`
|
||||
* Derived from confidence band.
|
||||
* Tooltip:
|
||||
|
||||
* “Confidence 78%. Last activity 3 days ago. τ = 30 days.”
|
||||
|
||||
* Sort default: by `effective_priority` / `effective_risk`.
|
||||
|
||||
* Filters:
|
||||
|
||||
* `Freshness: [All | Active | Review soon | Stale]`
|
||||
* Optionally: “Show stale only” toggle.
|
||||
|
||||
**Example labels:**
|
||||
|
||||
* Green: “Active (confidence 82%)”
|
||||
* Amber: “Review soon (confidence 45%)”
|
||||
* Red: “Stale (confidence 18%)”
|
||||
|
||||
### 7.2. Detail views
|
||||
|
||||
On an issue / vuln page:
|
||||
|
||||
* Add a “Confidence” section:
|
||||
|
||||
* “Confidence: **52%**”
|
||||
* “Last signal: **12 days ago**”
|
||||
* “Decay τ: **30 days**”
|
||||
* “Effective priority: **Base 80 × 0.52 = 42**”
|
||||
|
||||
* (Optional) small mini-chart (text-only or simple bar) showing approximate decay, but not necessary for first iteration.
|
||||
|
||||
### 7.3. Admin / settings UI
|
||||
|
||||
Add an internal settings page:
|
||||
|
||||
* Table of entity types with editable τ:
|
||||
|
||||
| Entity type | τ (days) | Notes |
|
||||
| ------------- | -------- | ---------------------------- |
|
||||
| Incident | 7 | Fast-moving |
|
||||
| Vulnerability | 30 | Standard risk review cadence |
|
||||
| Issue | 30 | Sprint-level decay |
|
||||
| Epic | 60 | Quarterly |
|
||||
| Doc | 90 | Slow decay |
|
||||
|
||||
* Optionally: toggle to pin item (`is_confidence_frozen`) from UI.
|
||||
|
||||
---
|
||||
|
||||
## 8. Stella Ops–specific behavior
|
||||
|
||||
For vulnerabilities:
|
||||
|
||||
### 8.1. Base risk calculation
|
||||
|
||||
Ingested fields you likely already have:
|
||||
|
||||
* `cvss_score` or `severity`
|
||||
* `reachable` (true/false or numeric)
|
||||
* (Optional) `exploit_available` (bool) or exploitability score
|
||||
* `asset_criticality` (1–5)
|
||||
|
||||
Define `base_risk` as:
|
||||
|
||||
```text
|
||||
severity_weight = f(cvss_score or severity)
|
||||
reachability = reachable ? 1.0 : 0.5 -- example
|
||||
exploitability = exploit_available ? 1.0 : 0.7
|
||||
asset_factor = 0.5 + 0.1 * asset_criticality -- 1 → 1.0, 5 → 1.5
|
||||
|
||||
base_risk = severity_weight * reachability * exploitability * asset_factor
|
||||
```
|
||||
|
||||
Store `base_risk` on vuln row.
|
||||
|
||||
Then:
|
||||
|
||||
```text
|
||||
effective_risk = base_risk * confidence(t)
|
||||
```
|
||||
|
||||
Use `effective_risk` for backlog ordering and SLAs dashboards.
|
||||
|
||||
### 8.2. Signals for vulns
|
||||
|
||||
Make sure these all call `RecordSignalAsync(Vulnerability, vulnId)`:
|
||||
|
||||
* New scan result for same vuln (re-detected).
|
||||
* Change status to “In Progress”, “Ready for Deploy”, “Verified Fixed”, etc.
|
||||
* Assigning an owner.
|
||||
* Attaching PoC / exploit details.
|
||||
|
||||
### 8.3. Vuln UI copy ideas
|
||||
|
||||
* Pill text:
|
||||
|
||||
* “Risk: 850 (confidence 68%)”
|
||||
* “Last analyst activity 11 days ago”
|
||||
|
||||
* In backlog view: show **Effective Risk** as main sort, with a smaller subtext “Base 1200 × Confidence 71%”.
|
||||
|
||||
---
|
||||
|
||||
## 9. Rollout plan
|
||||
|
||||
### Phase 1 – Infrastructure (backend-only)
|
||||
|
||||
* [ ] DB migrations & config table
|
||||
* [ ] Implement `ConfidenceMath` and helper functions
|
||||
* [ ] Implement `IConfidenceSignalService`
|
||||
* [ ] Wire signals into key flows (comments, state changes, scanner ingestion)
|
||||
* [ ] Add `confidence` and `effective_priority/risk` to API responses
|
||||
* [ ] Backfill script + dry run in staging
|
||||
|
||||
### Phase 2 – Internal UI & feature flag
|
||||
|
||||
* [ ] Add optional sorting by effective score to internal/staff views
|
||||
* [ ] Add confidence pill (hidden behind feature flag `confidence_decay_v1`)
|
||||
* [ ] Dogfood internally:
|
||||
|
||||
* Do items bubble up/down as expected?
|
||||
* Are any items “disappearing” because decay is too aggressive?
|
||||
|
||||
### Phase 3 – Parameter tuning
|
||||
|
||||
* [ ] Adjust τ per type based on feedback:
|
||||
|
||||
* If things decay too fast → increase τ
|
||||
* If queues rarely change → decrease τ
|
||||
* [ ] Decide on confidence floor (0.01? 0.05?) so nothing goes to literal 0.
|
||||
|
||||
### Phase 4 – General release
|
||||
|
||||
* [ ] Make effective score the default sort for key views:
|
||||
|
||||
* Vulnerabilities backlog
|
||||
* Issues backlog
|
||||
* [ ] Document behavior for users (help center / inline tooltip)
|
||||
* [ ] Add admin UI to tweak τ per entity type.
|
||||
|
||||
---
|
||||
|
||||
## 10. Edge cases & safeguards
|
||||
|
||||
* **New items**
|
||||
|
||||
* `last_signal_at = created_at`, confidence = 1.0.
|
||||
* **Pinned items**
|
||||
|
||||
* If `is_confidence_frozen = true` → treat confidence as 1.0.
|
||||
* **Items without τ**
|
||||
|
||||
* Always fallback to entity type default.
|
||||
* **Timezones**
|
||||
|
||||
* Always store & compute in UTC.
|
||||
* **Very old items**
|
||||
|
||||
* Floor the confidence so they’re still visible when explicitly searched.
|
||||
|
||||
---
|
||||
|
||||
If you want, I can turn this into:
|
||||
|
||||
* A short **technical design doc** (with sections: Problem, Proposal, Alternatives, Rollout).
|
||||
* Or a **set of Jira tickets** grouped by backend / frontend / infra that your team can pick up directly.
|
||||
@@ -0,0 +1,362 @@
|
||||
# Plugin Architecture & Extensibility Patterns
|
||||
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-11-28
|
||||
**Status:** Canonical
|
||||
|
||||
This advisory consolidates the extensibility patterns used across Stella Ops modules, providing a unified view for architects and developers implementing custom integrations.
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
Stella Ops uses a **plugin-based architecture** enabling customers and partners to extend functionality without modifying core code. The platform supports three primary extension types:
|
||||
|
||||
| Type | Module | Purpose | Examples |
|
||||
|------|--------|---------|----------|
|
||||
| **Connectors** | Concelier, Excititor | Ingest/export data from external sources | NVD, OSV, vendor VEX feeds |
|
||||
| **Plugins** | Authority, Scanner | Extend runtime behavior | LDAP auth, custom analyzers |
|
||||
| **Analyzers** | Scanner | Add detection capabilities | Language-specific, binary analysis |
|
||||
|
||||
---
|
||||
|
||||
## 2. Core Principles
|
||||
|
||||
### 2.1 Determinism
|
||||
|
||||
All plugins must produce **deterministic outputs** for identical inputs:
|
||||
- No global state between invocations
|
||||
- Timestamps in UTC ISO-8601
|
||||
- Stable ordering of collections
|
||||
- Reproducible hashing with documented algorithms
|
||||
|
||||
### 2.2 Offline-First
|
||||
|
||||
Plugins must function in **air-gapped environments**:
|
||||
- No network access unless explicitly configured
|
||||
- Local configuration and secrets
|
||||
- Bundled dependencies (no runtime downloads)
|
||||
- Offline-capable credential stores
|
||||
|
||||
### 2.3 Restart-Safe
|
||||
|
||||
Plugins load at **service startup only**:
|
||||
- No hot-reload (security/determinism trade-off)
|
||||
- Configuration changes require restart
|
||||
- State persists in external stores (MongoDB, filesystem)
|
||||
|
||||
---
|
||||
|
||||
## 3. Plugin Lifecycle
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Host Startup │
|
||||
└─────────────────────────────────┬───────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 1. Configuration Load │
|
||||
│ - Read YAML manifests from etc/<module>.plugins/ │
|
||||
│ - Validate capability tokens │
|
||||
│ - Resolve relative paths │
|
||||
└─────────────────────────────────┬───────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 2. Assembly Discovery │
|
||||
│ - Scan plugin binaries directory │
|
||||
│ - Match assemblies to manifest descriptors │
|
||||
│ - Load assemblies into isolated context │
|
||||
└─────────────────────────────────┬───────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 3. Registrar Execution │
|
||||
│ - Find IPluginRegistrar implementations │
|
||||
│ - Bind options from configuration │
|
||||
│ - Register services in DI container │
|
||||
│ - Queue bootstrap tasks (optional) │
|
||||
└─────────────────────────────────┬───────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 4. Runtime │
|
||||
│ - Host resolves plugin services via DI │
|
||||
│ - Capability metadata guides feature exposure │
|
||||
│ - Health checks report plugin status │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Concelier Connectors
|
||||
|
||||
### 4.1 Purpose
|
||||
|
||||
Connectors ingest vulnerability advisories from external sources into the Concelier merge engine.
|
||||
|
||||
### 4.2 Interface
|
||||
|
||||
```csharp
|
||||
public interface IAdvisoryConnector
|
||||
{
|
||||
string ConnectorId { get; }
|
||||
Task<IAsyncEnumerable<RawAdvisory>> FetchAsync(
|
||||
ConnectorContext context,
|
||||
CancellationToken ct);
|
||||
Task<ConnectorHealth> CheckHealthAsync(CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 Built-in Connectors
|
||||
|
||||
| Connector | Source | Format |
|
||||
|-----------|--------|--------|
|
||||
| `nvd` | NVD API 2.0 | CVE JSON |
|
||||
| `osv` | OSV.dev | OSV JSON |
|
||||
| `ghsa` | GitHub Advisory Database | GHSA JSON |
|
||||
| `oval` | Vendor OVAL feeds | OVAL XML |
|
||||
| `csaf` | CSAF repositories | CSAF JSON |
|
||||
|
||||
### 4.4 Developer Guide
|
||||
|
||||
See: `docs/dev/30_EXCITITOR_CONNECTOR_GUIDE.md`
|
||||
|
||||
---
|
||||
|
||||
## 5. Authority Plugins
|
||||
|
||||
### 5.1 Purpose
|
||||
|
||||
Authority plugins extend authentication with custom identity providers, credential stores, and client management.
|
||||
|
||||
### 5.2 Interface
|
||||
|
||||
```csharp
|
||||
public interface IAuthorityPluginRegistrar
|
||||
{
|
||||
void ConfigureServices(IServiceCollection services, PluginContext context);
|
||||
void ConfigureOptions(IConfiguration config);
|
||||
}
|
||||
|
||||
public interface IIdentityProviderPlugin
|
||||
{
|
||||
string ProviderId { get; }
|
||||
AuthorityIdentityProviderCapabilities Capabilities { get; }
|
||||
Task<AuthenticationResult> AuthenticateAsync(AuthenticationRequest request);
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 Capabilities
|
||||
|
||||
Plugins declare capabilities via manifest:
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
descriptors:
|
||||
ldap:
|
||||
assemblyName: "StellaOps.Authority.Plugin.Ldap"
|
||||
capabilities:
|
||||
- password
|
||||
- mfa
|
||||
- clientProvisioning
|
||||
```
|
||||
|
||||
| Capability | Description |
|
||||
|------------|-------------|
|
||||
| `password` | Username/password authentication |
|
||||
| `mfa` | Multi-factor authentication support |
|
||||
| `clientProvisioning` | Dynamic OAuth client registration |
|
||||
| `bootstrap` | Initial admin user creation |
|
||||
|
||||
### 5.4 Developer Guide
|
||||
|
||||
See: `docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md`
|
||||
|
||||
---
|
||||
|
||||
## 6. Scanner Analyzers
|
||||
|
||||
### 6.1 Purpose
|
||||
|
||||
Analyzers extend the Scanner with language-specific or binary-level detection capabilities.
|
||||
|
||||
### 6.2 Interface
|
||||
|
||||
```csharp
|
||||
public interface IScanAnalyzer
|
||||
{
|
||||
string AnalyzerId { get; }
|
||||
IReadOnlyList<string> SupportedEcosystems { get; }
|
||||
Task<AnalysisResult> AnalyzeAsync(
|
||||
ScanContext context,
|
||||
IAsyncEnumerable<ScanArtifact> artifacts,
|
||||
CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 Built-in Analyzers
|
||||
|
||||
| Analyzer | Ecosystem | Detection Method |
|
||||
|----------|-----------|------------------|
|
||||
| `syft` | Multi-ecosystem | SBOM generation |
|
||||
| `grype-db` | Multi-ecosystem | Vulnerability matching |
|
||||
| `elf-symbols` | Binary/ELF | Symbol table analysis |
|
||||
| `buildid` | Binary/ELF | Build-ID extraction |
|
||||
| `dotnet-deps` | .NET | deps.json parsing |
|
||||
|
||||
### 6.4 Surface Validation
|
||||
|
||||
The Scanner supports **extensible surface validation** for detecting risky patterns:
|
||||
|
||||
```csharp
|
||||
public interface ISurfaceValidator
|
||||
{
|
||||
string ValidatorId { get; }
|
||||
Task<SurfaceValidationResult> ValidateAsync(
|
||||
SurfaceContext context,
|
||||
CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
See: `docs/modules/scanner/guides/surface-validation-extensibility.md`
|
||||
|
||||
---
|
||||
|
||||
## 7. Manifest Structure
|
||||
|
||||
All plugins use a standard manifest format:
|
||||
|
||||
```json
|
||||
{
|
||||
"pluginId": "example-plugin",
|
||||
"version": "1.0.0",
|
||||
"assemblyName": "StellaOps.Module.Plugin.Example",
|
||||
"hostVersion": ">=2.0.0",
|
||||
"capabilities": ["capability1", "capability2"],
|
||||
"configuration": {
|
||||
"requiredSettings": ["setting1"],
|
||||
"optionalSettings": ["setting2"]
|
||||
},
|
||||
"dependencies": {
|
||||
"packages": ["Dependency.Package@1.0.0"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Security Considerations
|
||||
|
||||
### 8.1 Assembly Isolation
|
||||
|
||||
- Plugins load in dedicated assembly contexts
|
||||
- Host enforces capability-based access control
|
||||
- Network access requires explicit configuration
|
||||
|
||||
### 8.2 Configuration Validation
|
||||
|
||||
- Unknown capability tokens rejected at startup
|
||||
- Path traversal in relative paths blocked
|
||||
- Secrets never logged or exposed in diagnostics
|
||||
|
||||
### 8.3 Audit Trail
|
||||
|
||||
- Plugin loading events logged with assembly hash
|
||||
- Configuration changes recorded
|
||||
- Runtime errors captured with context
|
||||
|
||||
---
|
||||
|
||||
## 9. Offline Kit Integration
|
||||
|
||||
Plugins must support offline distribution:
|
||||
|
||||
```
|
||||
offline-kit/
|
||||
├── plugins/
|
||||
│ ├── authority/
|
||||
│ │ ├── StellaOps.Authority.Plugin.Ldap.dll
|
||||
│ │ └── manifest.json
|
||||
│ ├── scanner/
|
||||
│ │ ├── StellaOps.Scanner.Analyzer.Custom.dll
|
||||
│ │ └── manifest.json
|
||||
│ └── checksums.sha256
|
||||
├── config/
|
||||
│ └── plugins.yaml
|
||||
└── MANIFEST.json
|
||||
```
|
||||
|
||||
### 9.1 Checksum Verification
|
||||
|
||||
All plugin assemblies verified against `checksums.sha256` before loading.
|
||||
|
||||
### 9.2 Version Compatibility
|
||||
|
||||
Host rejects plugins with incompatible `hostVersion` requirements.
|
||||
|
||||
---
|
||||
|
||||
## 10. Testing Requirements
|
||||
|
||||
### 10.1 Unit Tests
|
||||
|
||||
- Registrar binds options correctly
|
||||
- Services resolve from DI container
|
||||
- Capability metadata accurate
|
||||
|
||||
### 10.2 Integration Tests
|
||||
|
||||
- Plugin loads in host process
|
||||
- Health checks pass
|
||||
- Functionality works end-to-end
|
||||
|
||||
### 10.3 Test Helpers
|
||||
|
||||
```csharp
|
||||
// Use StellaOps.Plugin.Tests helpers
|
||||
var host = new PluginTestHost()
|
||||
.WithPlugin<MyPlugin>()
|
||||
.WithConfiguration(config)
|
||||
.Build();
|
||||
|
||||
var plugin = host.GetRequiredService<IMyPlugin>();
|
||||
var result = await plugin.DoSomethingAsync();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Related Documentation
|
||||
|
||||
| Resource | Location |
|
||||
|----------|----------|
|
||||
| General plugin guide | `docs/dev/plugins/README.md` |
|
||||
| Concelier connector guide | `docs/dev/30_EXCITITOR_CONNECTOR_GUIDE.md` |
|
||||
| Authority plugin guide | `docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md` |
|
||||
| Scanner extensibility | `docs/modules/scanner/guides/surface-validation-extensibility.md` |
|
||||
| Platform architecture | `docs/modules/platform/architecture-overview.md` |
|
||||
|
||||
---
|
||||
|
||||
## 12. Sprint Mapping
|
||||
|
||||
No dedicated sprint - plugin infrastructure is foundational. Related tasks appear in:
|
||||
|
||||
- Module-specific sprints (Authority, Scanner, Concelier)
|
||||
- Platform infrastructure sprints
|
||||
|
||||
---
|
||||
|
||||
## 13. Success Metrics
|
||||
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| Plugin load time | < 500ms per plugin |
|
||||
| Configuration validation | 100% coverage of manifest schema |
|
||||
| Offline kit verification | All plugins checksum-verified |
|
||||
| Documentation coverage | All plugin types documented |
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-11-28*
|
||||
@@ -0,0 +1,289 @@
|
||||
# Sovereign Crypto for Regional Compliance
|
||||
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-11-28
|
||||
**Status:** Canonical
|
||||
|
||||
This advisory defines the product rationale, implementation strategy, and compliance mapping for regional cryptography support in Stella Ops, enabling deployments in jurisdictions requiring eIDAS, FIPS, GOST, or Chinese SM algorithms.
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
Stella Ops must support **sovereign-ready cryptography** to serve customers in regulated environments where standard cryptographic algorithms are insufficient or prohibited. This includes:
|
||||
|
||||
- **EU/eIDAS**: Qualified electronic signatures with HSM-backed keys
|
||||
- **US/FIPS 140-2/3**: Federal deployments requiring validated cryptographic modules
|
||||
- **Russia/GOST**: CryptoPro CSP and GOST R 34.10-2012/34.11-2012 algorithms
|
||||
- **China/SM**: SM2 (signing), SM3 (hashing), SM4 (encryption) national standards
|
||||
|
||||
The implementation uses a **provider registry pattern** allowing runtime selection of cryptographic backends without code changes.
|
||||
|
||||
---
|
||||
|
||||
## 2. Market Drivers
|
||||
|
||||
### 2.1 Target Segments
|
||||
|
||||
| Segment | Crypto Requirements | Market Size |
|
||||
|---------|---------------------|-------------|
|
||||
| **EU Government/Critical Infrastructure** | eIDAS QES, qualified timestamps | Large (EU Digital Identity Wallet mandate) |
|
||||
| **US Federal/Defense** | FIPS 140-2/3 validated modules | Large (FedRAMP, CMMC) |
|
||||
| **Russian Enterprise** | GOST algorithms, CryptoPro CSP | Medium (domestic compliance) |
|
||||
| **Chinese SOE/Government** | SM2/SM3/SM4 algorithms | Large (mandatory for PRC government) |
|
||||
|
||||
### 2.2 Competitive Positioning
|
||||
|
||||
Most vulnerability scanning tools (Snyk, Trivy, Grype) do not offer sovereign crypto options. Anchore Enterprise provides FIPS builds. Stella Ops can differentiate by supporting **all major regional standards** through a unified provider registry.
|
||||
|
||||
---
|
||||
|
||||
## 3. Technical Architecture
|
||||
|
||||
### 3.1 Provider Registry Pattern
|
||||
|
||||
The `ICryptoProviderRegistry` abstraction enables runtime selection of cryptographic implementations:
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────┐
|
||||
│ Application Layer │
|
||||
│ (Scanner, Authority, Attestor, Export Center, etc.) │
|
||||
└────────────────────────────┬───────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────────────┐
|
||||
│ ICryptoProviderRegistry │
|
||||
│ - ResolveHasher(profile) │
|
||||
│ - ResolveSigner(profile) │
|
||||
│ - ResolveKeyStore(profile) │
|
||||
└────────────────────────────┬───────────────────────────────────┘
|
||||
│
|
||||
┌───────────────────┼───────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ Default Profile │ │ RU Profile │ │ CN Profile │
|
||||
│ - SHA-256/384 │ │ - GOST R 34.11 │ │ - SM3 hash │
|
||||
│ - ECDSA P-256 │ │ - GOST R 34.10 │ │ - SM2 signing │
|
||||
│ - AES-256-GCM │ │ - Magma/Kuznech │ │ - SM4 encryption│
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
### 3.2 Profile Configuration
|
||||
|
||||
```yaml
|
||||
stellaops:
|
||||
crypto:
|
||||
registry:
|
||||
activeProfile: "default" # or "ru-offline", "cn-government"
|
||||
profiles:
|
||||
default:
|
||||
hashAlgorithm: "SHA256"
|
||||
signingAlgorithm: "ECDSA-P256"
|
||||
encryptionAlgorithm: "AES-256-GCM"
|
||||
providers:
|
||||
- "default"
|
||||
ru-offline:
|
||||
hashAlgorithm: "GOST-R-34.11-2012-256"
|
||||
signingAlgorithm: "GOST-R-34.10-2012"
|
||||
encryptionAlgorithm: "GOST-28147-89"
|
||||
providers:
|
||||
- "ru.cryptopro.csp"
|
||||
- "ru.openssl.gost"
|
||||
- "ru.pkcs11"
|
||||
cn-government:
|
||||
hashAlgorithm: "SM3"
|
||||
signingAlgorithm: "SM2"
|
||||
encryptionAlgorithm: "SM4"
|
||||
providers:
|
||||
- "cn.tongsuo"
|
||||
- "cn.pkcs11"
|
||||
```
|
||||
|
||||
### 3.3 Provider Implementations
|
||||
|
||||
| Provider ID | Backend | Algorithms | Platform |
|
||||
|-------------|---------|------------|----------|
|
||||
| `default` | .NET BCL | SHA-2, ECDSA, AES | All |
|
||||
| `ru.cryptopro.csp` | CryptoPro CSP | GOST R 34.10/11, Magma | Windows |
|
||||
| `ru.openssl.gost` | OpenSSL + GOST engine | GOST algorithms | Linux |
|
||||
| `ru.pkcs11` | PKCS#11 tokens | GOST (hardware) | All |
|
||||
| `cn.tongsuo` | Tongsuo (OpenSSL fork) | SM2/3/4 | Linux |
|
||||
| `cn.pkcs11` | PKCS#11 tokens | SM algorithms (hardware) | All |
|
||||
| `fips` | OpenSSL FIPS module | FIPS 140-2 validated | Linux |
|
||||
|
||||
---
|
||||
|
||||
## 4. Implementation Strategy
|
||||
|
||||
### 4.1 Phase 1: Registry Foundation (Complete)
|
||||
|
||||
- `ICryptoProviderRegistry` interface published
|
||||
- Default profile with .NET BCL backend
|
||||
- Configuration binding via `StellaOps:Crypto:Registry`
|
||||
|
||||
### 4.2 Phase 2: GOST/RU Support (In Progress)
|
||||
|
||||
- CryptoPro CSP plugin via forked GostCryptography library
|
||||
- OpenSSL GOST engine integration
|
||||
- Windows-only CSP tests with opt-in CI pipeline
|
||||
- RootPack RU distribution bundle
|
||||
|
||||
### 4.3 Phase 3: PQ-Ready Extensions (Planned)
|
||||
|
||||
- Post-quantum algorithms (Dilithium, Falcon) for DSSE
|
||||
- Hybrid signing (classical + PQ) for transition period
|
||||
- Registry options for algorithm agility
|
||||
|
||||
### 4.4 Phase 4: SM/CN Support (Future)
|
||||
|
||||
- Tongsuo integration for SM2/3/4
|
||||
- PKCS#11 support for Chinese HSMs
|
||||
- Compliance documentation for PRC requirements
|
||||
|
||||
---
|
||||
|
||||
## 5. Compliance Mapping
|
||||
|
||||
### 5.1 eIDAS (EU)
|
||||
|
||||
| Requirement | Stella Ops Capability |
|
||||
|-------------|----------------------|
|
||||
| Qualified Electronic Signature (QES) | HSM-backed signing via PKCS#11 |
|
||||
| Qualified Timestamp | RFC 3161 via external TSA |
|
||||
| Advanced Electronic Seal | DSSE attestations with organizational keys |
|
||||
| Long-term preservation (LTV) | Audit bundles with embedded timestamps |
|
||||
|
||||
### 5.2 FIPS 140-2/3 (US)
|
||||
|
||||
| Requirement | Stella Ops Capability |
|
||||
|-------------|----------------------|
|
||||
| Validated cryptographic module | OpenSSL FIPS provider |
|
||||
| Approved algorithms only | Profile restricts to FIPS-approved |
|
||||
| Key management | HSM or FIPS-validated software |
|
||||
| Self-tests | Provider initialization checks |
|
||||
|
||||
### 5.3 GOST (Russia)
|
||||
|
||||
| Requirement | Stella Ops Capability |
|
||||
|-------------|----------------------|
|
||||
| GOST R 34.10-2012 (signing) | CryptoPro CSP / OpenSSL GOST |
|
||||
| GOST R 34.11-2012 (hashing) | Provider registry selection |
|
||||
| Magma/Kuznyechik (encryption) | Symmetric support planned |
|
||||
| Certified CSP | CryptoPro CSP integration |
|
||||
|
||||
### 5.4 SM (China)
|
||||
|
||||
| Requirement | Stella Ops Capability |
|
||||
|-------------|----------------------|
|
||||
| SM2 (signing) | Tongsuo / PKCS#11 |
|
||||
| SM3 (hashing) | Provider registry selection |
|
||||
| SM4 (encryption) | Symmetric support planned |
|
||||
| GB/T certification | Third-party certification path |
|
||||
|
||||
---
|
||||
|
||||
## 6. Determinism Requirements
|
||||
|
||||
All cryptographic operations must maintain Stella Ops determinism guarantees:
|
||||
|
||||
1. **Same inputs + same profile = same output** (for hashing/signing with deterministic algorithms)
|
||||
2. **Timestamps in UTC ISO-8601** format
|
||||
3. **Profile names and provider IDs in lowercase ASCII**
|
||||
4. **Audit material includes provider version and configuration hash**
|
||||
|
||||
For algorithms with inherent randomness (ECDSA k-value, SM2), determinism applies to verification, not signature bytes.
|
||||
|
||||
---
|
||||
|
||||
## 7. Offline/Air-Gap Support
|
||||
|
||||
Sovereign deployments often require air-gapped operation:
|
||||
|
||||
| Feature | Offline Support |
|
||||
|---------|----------------|
|
||||
| Provider initialization | Local configuration only |
|
||||
| Key storage | Local HSM or file-based |
|
||||
| Certificate validation | Offline CRL/OCSP stapling |
|
||||
| Timestamp authority | Embedded timestamps or offline TSA |
|
||||
| Algorithm updates | Bundled in RootPack distributions |
|
||||
|
||||
---
|
||||
|
||||
## 8. Testing Strategy
|
||||
|
||||
### 8.1 Unit Tests
|
||||
|
||||
- Provider registry resolution
|
||||
- Algorithm selection per profile
|
||||
- Configuration validation
|
||||
|
||||
### 8.2 Integration Tests (Platform-Specific)
|
||||
|
||||
| Test Suite | Platform | Trigger |
|
||||
|------------|----------|---------|
|
||||
| Default profile | All | Default CI |
|
||||
| GOST/CryptoPro | Windows + CSP | Opt-in pipeline |
|
||||
| GOST/OpenSSL | Linux + GOST engine | Opt-in pipeline |
|
||||
| FIPS | Linux + FIPS module | Opt-in pipeline |
|
||||
| SM | Linux + Tongsuo | Future |
|
||||
|
||||
### 8.3 Compliance Validation
|
||||
|
||||
- NIST CAVP vectors for FIPS algorithms
|
||||
- GOST test vectors from TC 26
|
||||
- SM test vectors from GM/T standards
|
||||
|
||||
---
|
||||
|
||||
## 9. Distribution & Licensing
|
||||
|
||||
### 9.1 RootPack Bundles
|
||||
|
||||
| Bundle | Contents | Distribution |
|
||||
|--------|----------|--------------|
|
||||
| `rootpack-default` | Standard algorithms only | Public |
|
||||
| `rootpack-ru` | GOST providers + CryptoPro plugin | Restricted (RU customers) |
|
||||
| `rootpack-cn` | SM providers + Tongsuo | Restricted (CN customers) |
|
||||
| `rootpack-fips` | FIPS-validated binaries | Enterprise only |
|
||||
|
||||
### 9.2 Licensing Considerations
|
||||
|
||||
- CryptoPro CSP requires customer license
|
||||
- OpenSSL GOST engine under Apache 2.0
|
||||
- Tongsuo under Apache 2.0
|
||||
- Forked GostCryptography under MIT (with AGPL obligations from Stella Ops wrapper)
|
||||
|
||||
---
|
||||
|
||||
## 10. Related Documentation
|
||||
|
||||
- `docs/security/rootpack_ru_*.md` - RootPack RU documentation
|
||||
- `docs/security/crypto-registry-decision-2025-11-18.md` - Registry design decision
|
||||
- `docs/security/crypto-routing-audit-2025-11-07.md` - Crypto routing audit
|
||||
- `docs/security/pq-provider-options.md` - Post-quantum options
|
||||
- `docs/modules/signer/architecture.md` - Signer service crypto usage
|
||||
|
||||
---
|
||||
|
||||
## 11. Sprint Mapping
|
||||
|
||||
- **Primary Sprint:** SPRINT_0514_0001_0001_sovereign_crypto_enablement.md
|
||||
- **Blocking Dependencies:**
|
||||
- Authority provider/JWKS contract (AUTH-CRYPTO-90-001)
|
||||
- Windows CSP test runner for CryptoPro validation
|
||||
- **Status:** Phase 2 (GOST/RU) in progress with multiple tasks BLOCKED
|
||||
|
||||
---
|
||||
|
||||
## 12. Success Metrics
|
||||
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| Profile switch without code change | 100% |
|
||||
| GOST signing/verification | Working on Windows + Linux |
|
||||
| FIPS validation coverage | All signing/hashing paths |
|
||||
| Offline kit reproducibility | Deterministic across profiles |
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-11-28*
|
||||
@@ -0,0 +1,408 @@
|
||||
# Authentication and Authorization Architecture
|
||||
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-11-29
|
||||
**Status:** Canonical
|
||||
|
||||
This advisory defines the product rationale, token model, scope taxonomy, and implementation strategy for the Authority module, consolidating authentication and authorization patterns across all Stella Ops services.
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
Authority is the **on-premises OIDC/OAuth2 issuing service** that provides secure identity for all Stella Ops operations. Key capabilities:
|
||||
|
||||
- **Short-Lived Tokens (OpTok)** - 2-5 minute TTL operational tokens
|
||||
- **Sender Constraints** - DPoP or mTLS binding prevents token theft
|
||||
- **Fine-Grained Scopes** - 65+ scopes with role bundles
|
||||
- **Multi-Tenant Isolation** - Tenant claims enforced throughout
|
||||
- **Delegated Service Accounts** - Automation without credential exposure
|
||||
- **Sovereign Crypto Support** - Configurable signing algorithms per profile
|
||||
|
||||
---
|
||||
|
||||
## 2. Market Drivers
|
||||
|
||||
### 2.1 Target Segments
|
||||
|
||||
| Segment | Authentication Requirements | Use Case |
|
||||
|---------|---------------------------|----------|
|
||||
| **Enterprise** | SSO/SAML integration, MFA | Corporate security policies |
|
||||
| **Government** | CAC/PIV, FIPS validation | Federal compliance |
|
||||
| **Financial Services** | Strong auth, audit trails | SOC 2, PCI-DSS |
|
||||
| **Healthcare** | HIPAA access controls | PHI protection |
|
||||
|
||||
### 2.2 Competitive Positioning
|
||||
|
||||
Most vulnerability scanning tools rely on basic API keys. Stella Ops differentiates with:
|
||||
- **Zero-trust token model** with sender constraints
|
||||
- **Fine-grained RBAC** with 65+ scopes
|
||||
- **Cryptographic binding** (DPoP/mTLS) prevents token theft
|
||||
- **Deterministic revocation bundles** for offline verification
|
||||
- **Plugin extensibility** for custom identity providers
|
||||
|
||||
---
|
||||
|
||||
## 3. Token Model
|
||||
|
||||
### 3.1 Three-Token System
|
||||
|
||||
| Token | Lifetime | Purpose | Binding |
|
||||
|-------|----------|---------|---------|
|
||||
| **License Token (LT)** | Long-lived | Cloud licensing enrollment | Installation |
|
||||
| **Proof-of-Entitlement (PoE)** | Medium | License validation | Installation key |
|
||||
| **Operational Token (OpTok)** | 2-5 min | Runtime authentication | DPoP/mTLS |
|
||||
|
||||
### 3.2 Operational Token Structure
|
||||
|
||||
**Registered Claims:**
|
||||
|
||||
```json
|
||||
{
|
||||
"iss": "https://authority.example.com",
|
||||
"sub": "client-id-or-user-id",
|
||||
"aud": "signer|scanner|attestor|concelier|...",
|
||||
"exp": 1732881600,
|
||||
"iat": 1732881300,
|
||||
"nbf": 1732881270,
|
||||
"jti": "uuid",
|
||||
"scope": "scanner.scan scanner.export signer.sign"
|
||||
}
|
||||
```
|
||||
|
||||
**Sender Constraint Claims:**
|
||||
|
||||
```json
|
||||
{
|
||||
"cnf": {
|
||||
"jkt": "base64url(SHA-256(JWK))", // DPoP binding
|
||||
"x5t#S256": "base64url(SHA-256(cert))" // mTLS binding
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Tenant & Context Claims:**
|
||||
|
||||
```json
|
||||
{
|
||||
"tid": "tenant-id",
|
||||
"inst": "installation-id",
|
||||
"roles": ["svc.scanner", "svc.signer"],
|
||||
"plan": "enterprise"
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Sender Constraints
|
||||
|
||||
**DPoP (Demonstration of Proof-of-Possession):**
|
||||
|
||||
1. Client generates ephemeral JWK keypair
|
||||
2. Client sends DPoP proof header with `htm`, `htu`, `iat`, `jti`
|
||||
3. Authority validates and stamps token with `cnf.jkt`
|
||||
4. Resource servers verify same key on each request
|
||||
5. Nonce challenges available for high-value audiences
|
||||
|
||||
**mTLS (Mutual TLS):**
|
||||
|
||||
1. Client presents certificate at TLS handshake
|
||||
2. Authority validates and binds to `cnf.x5t#S256`
|
||||
3. Resource servers verify same cert on each request
|
||||
4. Required for high-value audiences (signer, attestor)
|
||||
|
||||
---
|
||||
|
||||
## 4. Scope Taxonomy
|
||||
|
||||
### 4.1 Scope Categories (65+ scopes)
|
||||
|
||||
**Ingestion Scopes (tenant-required):**
|
||||
- `advisory:ingest` - Concelier advisory ingestion
|
||||
- `vex:ingest` - Excititor VEX ingestion
|
||||
- `signals:write` - Reachability signal ingestion
|
||||
|
||||
**Verification Scopes (require `aoc:verify` pairing):**
|
||||
- `advisory:read` - Advisory queries
|
||||
- `vex:read` - VEX queries
|
||||
- `signals:read` - Signal queries
|
||||
|
||||
**Service Scopes:**
|
||||
|
||||
| Service | Scopes |
|
||||
|---------|--------|
|
||||
| **Signer** | `signer.sign` (mTLS enforced) |
|
||||
| **Scanner** | `scanner.scan`, `scanner.export`, `scanner.read` |
|
||||
| **Attestor** | `attestor.write` |
|
||||
| **Policy Studio** | `policy:author`, `policy:review`, `policy:approve`, `policy:operate`, `policy:publish`, `policy:promote`, `policy:audit`, `policy:simulate` |
|
||||
| **Vuln Explorer** | `vuln:view`, `vuln:investigate`, `vuln:operate`, `vuln:audit` |
|
||||
| **Orchestrator** | `orch:read`, `orch:operate`, `orch:quota`, `orch:backfill` |
|
||||
| **Export Center** | `export.viewer`, `export.operator`, `export.admin` |
|
||||
| **Task Packs** | `packs.read`, `packs.write`, `packs.run`, `packs.approve` |
|
||||
| **Evidence** | `evidence:create`, `evidence:read`, `evidence:hold` |
|
||||
| **Timeline** | `timeline:read`, `timeline:write` |
|
||||
|
||||
**Special Scopes:**
|
||||
- `obs:incident` - Incident mode activation (fresh auth required)
|
||||
- `tenant:admin` - Cross-tenant operations
|
||||
|
||||
### 4.2 Role Bundles
|
||||
|
||||
Authority provides 40+ predefined roles that bundle related scopes:
|
||||
|
||||
| Role | Scopes | Requirements |
|
||||
|------|--------|--------------|
|
||||
| `role/concelier-ingest` | `advisory:ingest`, `advisory:read` | Tenant claim |
|
||||
| `role/signals-uploader` | `signals:write`, `signals:read`, `aoc:verify` | Tenant claim |
|
||||
| `role/policy-engine` | `effective:write`, `findings:read` | `serviceIdentity: policy-engine` |
|
||||
| `role/policy-author` | `policy:author`, `policy:read`, `policy:simulate`, `findings:read` | - |
|
||||
| `role/policy-approver` | `policy:approve`, `policy:review`, `policy:read`, `policy:simulate`, `findings:read` | - |
|
||||
| `role/orch-operator` | `orch:read`, `orch:operate` | - |
|
||||
| `role/export-admin` | `export.viewer`, `export.operator`, `export.admin` | - |
|
||||
|
||||
---
|
||||
|
||||
## 5. Multi-Tenant Isolation
|
||||
|
||||
### 5.1 Tenant Claim Enforcement
|
||||
|
||||
**Token Issuance:**
|
||||
- Authority normalizes tenant: `trim().ToLowerInvariant()`
|
||||
- Tokens include `tid` (tenant ID) and `inst` (installation ID)
|
||||
- Cross-tenant isolation enforced at issuance
|
||||
|
||||
**Propagation:**
|
||||
- API Gateway forwards `tid` as `X-Stella-Tenant` header
|
||||
- Downstream services reject requests without header
|
||||
- All data stamped with tenant identifier
|
||||
|
||||
**Scope Enforcement:**
|
||||
- Ingestion scopes require tenant claim
|
||||
- `aoc:verify` pairing required for verification scopes
|
||||
- Cross-tenant replay rejected
|
||||
|
||||
### 5.2 Cross-Tenant Operations
|
||||
|
||||
For platform operators with `tenant:admin`:
|
||||
- Switch tenants via `/authority/tenant/switch`
|
||||
- CLI `--tenant <id>` override
|
||||
- Delegated token exchange for automation
|
||||
- Full audit trail of tenant switches
|
||||
|
||||
---
|
||||
|
||||
## 6. Advanced Token Features
|
||||
|
||||
### 6.1 Delegated Service Accounts
|
||||
|
||||
```yaml
|
||||
delegation:
|
||||
quotas:
|
||||
maxActiveTokens: 50
|
||||
serviceAccounts:
|
||||
- accountId: "svc-observer"
|
||||
tenant: "tenant-default"
|
||||
displayName: "Observability Exporter"
|
||||
allowedScopes: ["jobs:read", "findings:read"]
|
||||
authorizedClients: ["export-center-worker"]
|
||||
```
|
||||
|
||||
**Token Shape:**
|
||||
- Includes `stellaops:service_account` claim
|
||||
- `act` claim describes caller hierarchy
|
||||
- Quota enforcement per tenant/account
|
||||
|
||||
### 6.2 Fresh Auth Window (5 Minutes)
|
||||
|
||||
Required for high-privilege operations:
|
||||
- Policy publish/promote
|
||||
- Pack approvals
|
||||
- Incident mode activation
|
||||
- Operator actions
|
||||
|
||||
**Token must include:**
|
||||
- `auth_time` within 5 minutes of request
|
||||
- Interactive authentication (password/device-code)
|
||||
|
||||
### 6.3 ABAC Attributes (Vuln Explorer)
|
||||
|
||||
Tokens can carry attribute-based filters:
|
||||
- `stellaops:vuln_env` - Environment filter
|
||||
- `stellaops:vuln_owner` - Team/owner filter
|
||||
- `stellaops:vuln_business_tier` - Criticality tier
|
||||
|
||||
---
|
||||
|
||||
## 7. Implementation Strategy
|
||||
|
||||
### 7.1 Phase 1: Core Token Infrastructure (Complete)
|
||||
|
||||
- [x] DPoP validation on all `/token` grants
|
||||
- [x] mTLS binding for refresh grants
|
||||
- [x] Sealed-mode CI gating
|
||||
- [x] Pack signing policies and RBAC
|
||||
- [x] LDAP plugin with claims enricher
|
||||
|
||||
### 7.2 Phase 2: Sovereign Crypto (In Progress)
|
||||
|
||||
- [ ] Crypto provider registry wiring (AUTH-CRYPTO-90-001)
|
||||
- [ ] GOST signing support
|
||||
- [ ] FIPS validation
|
||||
- [ ] Post-quantum preparation
|
||||
|
||||
### 7.3 Phase 3: Advanced Features (Planned)
|
||||
|
||||
- [ ] DSSE predicate types for SBOM/Graph/VEX (AUTH-REACH-401-005)
|
||||
- [ ] PostgreSQL storage migration
|
||||
- [ ] Enhanced delegation quotas
|
||||
|
||||
---
|
||||
|
||||
## 8. API Surface
|
||||
|
||||
### 8.1 Token Endpoints
|
||||
|
||||
| Endpoint | Method | Purpose |
|
||||
|----------|--------|---------|
|
||||
| `/token` | POST | Token issuance (all grant types) |
|
||||
| `/introspect` | POST | Token introspection |
|
||||
| `/revoke` | POST | Token/refresh revocation |
|
||||
| `/.well-known/openid-configuration` | GET | OIDC discovery |
|
||||
| `/jwks` | GET | JSON Web Key Set |
|
||||
|
||||
### 8.2 Supported Grant Types
|
||||
|
||||
- **Client Credentials** - Service-to-service (mTLS or private_key_jwt)
|
||||
- **Device Code** - CLI on headless agents
|
||||
- **Authorization Code + PKCE** - Browser UI login
|
||||
- **Refresh Token** - With DPoP/mTLS re-validation
|
||||
|
||||
### 8.3 Admin APIs
|
||||
|
||||
All under `/admin` (mTLS + `authority.admin` scope):
|
||||
|
||||
| Endpoint | Method | Purpose |
|
||||
|----------|--------|---------|
|
||||
| `/admin/clients` | POST | Create/update client |
|
||||
| `/admin/audiences` | POST | Register audience URIs |
|
||||
| `/admin/roles` | POST | Define role→scope mappings |
|
||||
| `/admin/tenants` | POST | Create tenant entries |
|
||||
| `/admin/keys/rotate` | POST | Rotate signing key |
|
||||
|
||||
---
|
||||
|
||||
## 9. Revocation & JWKS
|
||||
|
||||
### 9.1 Revocation Bundles
|
||||
|
||||
Deterministic bundles for offline verification:
|
||||
|
||||
```
|
||||
revocation-bundle.json
|
||||
├── revokedTokens[] # List of revoked jti values
|
||||
├── revokedClients[] # Revoked client IDs
|
||||
├── generatedAt # UTC timestamp
|
||||
├── validUntil # Expiry for offline cache
|
||||
└── signature # Detached JWS (RFC 7797)
|
||||
```
|
||||
|
||||
### 9.2 JWKS Management
|
||||
|
||||
- At least 2 active keys during rotation
|
||||
- Old keys retained for max TTL + 5 minutes
|
||||
- Key status: `active`, `retired`, `revoked`
|
||||
|
||||
### 9.3 CLI Verification
|
||||
|
||||
```bash
|
||||
# Export revocation bundle
|
||||
stella auth revoke export --output revocation.json
|
||||
|
||||
# Verify bundle signature
|
||||
stella auth revoke verify --bundle revocation.json --key pubkey.pem
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Security Considerations
|
||||
|
||||
### 10.1 Threat Model Coverage
|
||||
|
||||
| Threat | Mitigation |
|
||||
|--------|------------|
|
||||
| Token theft | DPoP/mTLS sender constraints |
|
||||
| Replay attacks | DPoP nonce challenges, short TTL |
|
||||
| Token injection | Audience validation |
|
||||
| Privilege escalation | Scope enforcement, role bundles |
|
||||
| Cross-tenant access | Tenant claim isolation |
|
||||
|
||||
### 10.2 Operational Security
|
||||
|
||||
- Bootstrap API key protection
|
||||
- Key rotation before expiration
|
||||
- Rate limiting on `/token` endpoint
|
||||
- Audit logging for all token operations
|
||||
|
||||
---
|
||||
|
||||
## 11. Observability
|
||||
|
||||
### 11.1 Metrics
|
||||
|
||||
- `authority_token_issued_total{grant_type,audience}`
|
||||
- `authority_token_rejected_total{reason}`
|
||||
- `authority_dpop_nonce_miss_total`
|
||||
- `authority_mtls_mismatch_total`
|
||||
|
||||
### 11.2 Audit Events
|
||||
|
||||
- `authority.token.issued` - Token issuance
|
||||
- `authority.token.rejected` - Rejection with reason
|
||||
- `authority.tenant.switch` - Cross-tenant operation
|
||||
- `authority.key.rotated` - Key rotation
|
||||
- `authority.plugin.*.password_verification` - Plugin events
|
||||
|
||||
---
|
||||
|
||||
## 12. Related Documentation
|
||||
|
||||
| Resource | Location |
|
||||
|----------|----------|
|
||||
| Authority architecture | `docs/modules/authority/architecture.md` |
|
||||
| Authority overview | `docs/11_AUTHORITY.md` |
|
||||
| Scope reference | `docs/security/authority-scopes.md` |
|
||||
| DPoP/mTLS rollout | `docs/security/dpop-mtls-rollout.md` |
|
||||
| Threat model | `docs/security/authority-threat-model.md` |
|
||||
| Revocation bundles | `docs/security/revocation-bundle.md` |
|
||||
| Key rotation | `docs/modules/authority/operations/key-rotation.md` |
|
||||
| Plugin guide | `docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md` |
|
||||
|
||||
---
|
||||
|
||||
## 13. Sprint Mapping
|
||||
|
||||
- **Historical:** SPRINT_100_identity_signing.md (CLOSED)
|
||||
- **Documentation:** SPRINT_314_docs_modules_authority.md
|
||||
- **PostgreSQL:** SPRINT_3401_0001_0001_postgres_authority.md
|
||||
- **Crypto:** SPRINT_0514_0001_0001_sovereign_crypto_enablement.md
|
||||
|
||||
**Key Task IDs:**
|
||||
- `AUTH-DPOP-11-001` - DPoP validation (DONE)
|
||||
- `AUTH-MTLS-11-002` - mTLS binding (DONE)
|
||||
- `AUTH-AIRGAP-57-001` - Sealed-mode CI gating (DONE)
|
||||
- `AUTH-CRYPTO-90-001` - Sovereign crypto wiring (IN PROGRESS)
|
||||
- `AUTH-REACH-401-005` - DSSE predicates (TODO)
|
||||
|
||||
---
|
||||
|
||||
## 14. Success Metrics
|
||||
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| Token issuance latency | < 50ms p99 |
|
||||
| DPoP validation rate | 100% on `/token` |
|
||||
| Sender constraint coverage | 100% for high-value audiences |
|
||||
| Key rotation downtime | Zero |
|
||||
| Revocation bundle freshness | < 5 minutes |
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-11-29*
|
||||
@@ -0,0 +1,338 @@
|
||||
# Evidence Bundle and Replay Contracts
|
||||
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-11-29
|
||||
**Status:** Canonical
|
||||
|
||||
This advisory defines the product rationale, data contracts, and implementation strategy for the Evidence Locker module, covering deterministic bundle packaging, attestation contracts, replay payload ingestion, and incident mode operation.
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
The Evidence Locker provides **immutable, deterministic evidence bundles** for audit, compliance, and offline verification. Key capabilities:
|
||||
|
||||
- **Deterministic Bundle Packaging** - Reproducible tar.gz archives with fixed timestamps and sorted entries
|
||||
- **DSSE Attestation Contracts** - In-toto predicates for bundle integrity verification
|
||||
- **Replay Payload Ingestion** - Scanner record capture for deterministic replay
|
||||
- **Incident Mode** - Extended retention and forensic capture during security incidents
|
||||
- **Portable Bundles** - Redacted exports for external auditors
|
||||
|
||||
---
|
||||
|
||||
## 2. Market Drivers
|
||||
|
||||
### 2.1 Target Segments
|
||||
|
||||
| Segment | Evidence Requirements | Use Case |
|
||||
|---------|----------------------|----------|
|
||||
| **Financial Services** | Immutable audit trails, SOC 2 Type II | Compliance evidence for regulators |
|
||||
| **Healthcare** | HIPAA audit requirements | PHI access logging and retention |
|
||||
| **Government/Defense** | Chain of custody, NIST 800-53 | Security incident forensics |
|
||||
| **Critical Infrastructure** | ICS/SCADA audit trails | Operational technology compliance |
|
||||
|
||||
### 2.2 Competitive Positioning
|
||||
|
||||
Most vulnerability scanning tools export findings as ephemeral reports. Stella Ops differentiates with:
|
||||
- **Cryptographically sealed bundles** with DSSE signatures
|
||||
- **Deterministic replay** for reproducing past scan states
|
||||
- **Offline verification** without network connectivity
|
||||
- **Incident mode** for automatic forensic preservation
|
||||
|
||||
---
|
||||
|
||||
## 3. Technical Architecture
|
||||
|
||||
### 3.1 Bundle Layout (v1)
|
||||
|
||||
```
|
||||
evidence-bundle-<id>.tar.gz
|
||||
├── manifest.json # Bundle metadata and file inventory
|
||||
├── signature.json # DSSE envelope with key metadata
|
||||
├── bundle.json # Locker metadata (ids, status, root hash)
|
||||
├── checksums.txt # SHA-256 per-entry hashes + Merkle root
|
||||
├── instructions.txt # Offline verification steps
|
||||
├── observations.ndjson # Advisory observations (sorted)
|
||||
├── linksets.ndjson # Component linkages (sorted)
|
||||
└── timeline.ndjson # Time anchors (optional)
|
||||
```
|
||||
|
||||
### 3.2 Determinism Rules
|
||||
|
||||
All bundles must be **bit-for-bit reproducible**:
|
||||
|
||||
| Property | Rule |
|
||||
|----------|------|
|
||||
| **Gzip timestamp** | Pinned to `2025-01-01T00:00:00Z` |
|
||||
| **File permissions** | `0644` for all entries |
|
||||
| **Owner/Group** | `0:0` (root) |
|
||||
| **mtime/atime/ctime** | Fixed epoch value |
|
||||
| **JSON serialization** | `JsonSerializerDefaults.Web` + indent=2 |
|
||||
| **NDJSON ordering** | Sorted by `advisoryId`, then `component`, ascending |
|
||||
| **Hash format** | Lower-case hex, SHA-256 |
|
||||
| **Timestamps** | UTC ISO-8601 (RFC3339) |
|
||||
|
||||
### 3.3 Attestation Contract (v1)
|
||||
|
||||
**DSSE Envelope Structure:**
|
||||
|
||||
```json
|
||||
{
|
||||
"payloadType": "application/vnd.stellaops.evidence+json",
|
||||
"payload": "<base64(manifest.json)>",
|
||||
"signatures": [{
|
||||
"keyid": "evidence-locker-ed25519-01",
|
||||
"sig": "<base64(Ed25519 signature)>"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**Required Claim Set:**
|
||||
|
||||
| Claim | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `bundle_id` | UUID v4 | Unique bundle identifier |
|
||||
| `produced_at` | ISO-8601 | UTC production timestamp |
|
||||
| `producer` | string | `evidence-locker:<region>` |
|
||||
| `subject_digest` | string | OCI digest of bundle |
|
||||
| `hashes` | map | `{ path: sha256 }` for each file |
|
||||
| `sbom` | array | SBOM digests and mediaTypes |
|
||||
| `vex` | array | VEX doc digests and versions |
|
||||
| `replay_manifest` | object | Optional replay digest + sequence |
|
||||
| `transparency` | object | Optional Rekor log entry |
|
||||
| `signing_profile` | string | `sovereign-default`, `fips`, `gost`, `pq-experimental` |
|
||||
|
||||
### 3.4 Replay Payload Contract
|
||||
|
||||
**NDJSON Record Structure:**
|
||||
|
||||
```json
|
||||
{
|
||||
"scanId": "uuid",
|
||||
"tenantId": "string",
|
||||
"subjectDigest": "sha256:...",
|
||||
"scanKind": "sbom|vuln|policy",
|
||||
"startedAtUtc": "ISO-8601",
|
||||
"completedAtUtc": "ISO-8601",
|
||||
"artifacts": [
|
||||
{ "type": "sbom|vex|log", "digest": "sha256:...", "uri": "..." }
|
||||
],
|
||||
"provenance": {
|
||||
"dsseEnvelope": "<base64>",
|
||||
"transparencyLog": { "rekorUUID": "...", "logIndex": 123 }
|
||||
},
|
||||
"summary": { "findings": 42, "advisories": 15, "policies": 3 }
|
||||
}
|
||||
```
|
||||
|
||||
**Ordering:** Sorted by `recordedAtUtc`, then `scanId` ascending.
|
||||
|
||||
---
|
||||
|
||||
## 4. Implementation Strategy
|
||||
|
||||
### 4.1 Phase 1: Bundle Foundation (Complete)
|
||||
|
||||
- [x] Postgres schema with RLS per tenant
|
||||
- [x] Object-store abstraction (local + S3 with optional WORM)
|
||||
- [x] Deterministic `bundle.tgz` packaging
|
||||
- [x] Incident mode with extended retention
|
||||
- [x] Portable bundle export with redacted metadata
|
||||
- [x] Crypto provider registry integration (`EVID-CRYPTO-90-001`)
|
||||
|
||||
### 4.2 Phase 2: Attestation & Replay (In Progress)
|
||||
|
||||
- [ ] DSSE envelope signing with configurable provider
|
||||
- [ ] Replay payload ingestion API
|
||||
- [ ] CLI `stella scan --record` integration
|
||||
- [ ] Bundle verification CLI (`stella verify --bundle`)
|
||||
- [ ] Rekor transparency log integration (optional)
|
||||
|
||||
### 4.3 Phase 3: Automation & Integration (Planned)
|
||||
|
||||
- [ ] Orchestrator hooks for automatic bundle creation
|
||||
- [ ] Export Center integration for mirror bundles
|
||||
- [ ] Timeline event emission for audit dashboards
|
||||
- [ ] Retention policy automation with legal hold support
|
||||
|
||||
---
|
||||
|
||||
## 5. API Surface
|
||||
|
||||
### 5.1 Evidence Bundle APIs
|
||||
|
||||
| Endpoint | Method | Scope | Description |
|
||||
|----------|--------|-------|-------------|
|
||||
| `/evidence` | GET | `evidence:read` | List bundles with filters |
|
||||
| `/evidence/{bundleId}` | GET | `evidence:read` | Get bundle metadata |
|
||||
| `/evidence/{bundleId}/download` | GET | `evidence:read` | Download sealed bundle |
|
||||
| `/evidence/{bundleId}/portable` | GET | `evidence:read` | Download portable bundle |
|
||||
| `/evidence` | POST | `evidence:create` | Create new bundle |
|
||||
| `/evidence/{bundleId}/hold` | POST | `evidence:hold` | Apply legal hold |
|
||||
|
||||
### 5.2 Replay APIs
|
||||
|
||||
| Endpoint | Method | Scope | Description |
|
||||
|----------|--------|-------|-------------|
|
||||
| `/replay/records` | POST | `replay:write` | Ingest replay records (NDJSON) |
|
||||
| `/replay/records` | GET | `replay:read` | Query replay records |
|
||||
| `/replay/{recordId}/verify` | POST | `replay:read` | Verify record integrity |
|
||||
| `/replay/{recordId}/diff` | POST | `replay:read` | Compare two records |
|
||||
|
||||
### 5.3 CLI Commands
|
||||
|
||||
```bash
|
||||
# Record scan for replay
|
||||
stella scan --record --output replay.ndjson <image>
|
||||
|
||||
# Verify bundle integrity
|
||||
stella verify --bundle evidence-bundle.tar.gz
|
||||
|
||||
# Replay past scan
|
||||
stella replay --record replay.ndjson --compare current.json
|
||||
|
||||
# Diff two scan results
|
||||
stella replay diff --before before.ndjson --after after.ndjson
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Incident Mode
|
||||
|
||||
### 6.1 Activation
|
||||
|
||||
Incident mode is a **service-wide switch** for forensic fidelity during suspected compromise or SLO breach.
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```yaml
|
||||
EvidenceLocker:
|
||||
Incident:
|
||||
Enabled: true
|
||||
RetentionExtensionDays: 60
|
||||
CaptureRequestSnapshot: true
|
||||
```
|
||||
|
||||
### 6.2 Behavior Changes
|
||||
|
||||
| Feature | Normal Mode | Incident Mode |
|
||||
|---------|-------------|---------------|
|
||||
| **Retention** | Standard policy | Extended by `RetentionExtensionDays` |
|
||||
| **Request capture** | None | Full request snapshots to object store |
|
||||
| **Manifest metadata** | Standard | Includes `incident.*` fields |
|
||||
| **Timeline events** | Standard | Activation/deactivation events |
|
||||
| **Audit verbosity** | Normal | Enhanced with `incident_reason` |
|
||||
|
||||
### 6.3 Activation API
|
||||
|
||||
```bash
|
||||
# Activate incident mode
|
||||
stella evidence incident activate --reason "Security event investigation"
|
||||
|
||||
# Deactivate incident mode
|
||||
stella evidence incident deactivate --reason "Investigation complete"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Offline Verification
|
||||
|
||||
### 7.1 Portable Bundle Contents
|
||||
|
||||
```
|
||||
portable-bundle-v1.tgz
|
||||
├── manifest.json # Redacted (no tenant/storage identifiers)
|
||||
├── signature.json # DSSE envelope
|
||||
├── checksums.txt # SHA-256 hashes
|
||||
├── verify-offline.sh # POSIX verification script
|
||||
├── observations.ndjson # Advisory data
|
||||
├── linksets.ndjson # Linkage data
|
||||
└── README.txt # Verification instructions
|
||||
```
|
||||
|
||||
### 7.2 Verification Steps
|
||||
|
||||
1. Extract archive
|
||||
2. Run `./verify-offline.sh` (computes hashes, validates signature)
|
||||
3. Compare manifest hash with external attestation
|
||||
4. If Rekor transparency present, verify inclusion proof
|
||||
|
||||
---
|
||||
|
||||
## 8. Determinism Requirements
|
||||
|
||||
All Evidence Locker operations must maintain determinism:
|
||||
|
||||
1. **Same inputs = same bundle hash** for identical observations/linksets
|
||||
2. **Timestamps in UTC ISO-8601** format only
|
||||
3. **Tenant IDs lowercase** and included in manifest
|
||||
4. **Crypto provider version** recorded in audit material
|
||||
5. **NDJSON sorted** by canonical key ordering
|
||||
|
||||
---
|
||||
|
||||
## 9. Testing Strategy
|
||||
|
||||
### 9.1 Unit Tests
|
||||
|
||||
- Bundle packaging produces identical hash for identical inputs
|
||||
- DSSE envelope validates against registered keys
|
||||
- Incident mode extends retention correctly
|
||||
- Replay records sorted deterministically
|
||||
|
||||
### 9.2 Integration Tests
|
||||
|
||||
- Full bundle creation workflow with object store
|
||||
- CLI record/verify/replay cycle
|
||||
- Portable bundle extraction and verification
|
||||
- Cross-tenant isolation enforcement
|
||||
|
||||
### 9.3 Golden Fixtures
|
||||
|
||||
Located at `tests/EvidenceLocker/Fixtures/`:
|
||||
- `golden-bundle-v1.tar.gz` - Reference bundle with known hash
|
||||
- `golden-replay-records.ndjson` - Reference replay records
|
||||
- `golden-dsse-envelope.json` - Reference DSSE signature
|
||||
|
||||
---
|
||||
|
||||
## 10. Related Documentation
|
||||
|
||||
| Resource | Location |
|
||||
|----------|----------|
|
||||
| Evidence Locker architecture | `docs/modules/evidence-locker/` |
|
||||
| Bundle packaging spec | `docs/modules/evidence-locker/bundle-packaging.md` |
|
||||
| Attestation contract | `docs/modules/evidence-locker/attestation-contract.md` |
|
||||
| Replay payload contract | `docs/modules/evidence-locker/replay-payload-contract.md` |
|
||||
| Incident mode spec | `docs/modules/evidence-locker/incident-mode.md` |
|
||||
| Crypto provider registry | `docs/security/crypto-registry-decision-2025-11-18.md` |
|
||||
|
||||
---
|
||||
|
||||
## 11. Sprint Mapping
|
||||
|
||||
- **Primary Sprint:** SPRINT_0161_0001_0001_evidencelocker.md
|
||||
- **CLI Integration:** SPRINT_0187_0001_0001_evidence_locker_cli_integration.md
|
||||
- **Coordination:** SPRINT_0160_0001_0001_export_evidence.md
|
||||
|
||||
**Key Task IDs:**
|
||||
- `EVID-OBS-54-002` - Finalize bundle packaging + DSSE layout
|
||||
- `EVID-REPLAY-187-001` - Implement replay ingestion/retention APIs
|
||||
- `CLI-REPLAY-187-002` - Add CLI record/verify/replay commands
|
||||
- `EVID-CRYPTO-90-001` - Crypto provider registry routing (DONE)
|
||||
|
||||
---
|
||||
|
||||
## 12. Success Metrics
|
||||
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| Bundle hash reproducibility | 100% (bit-identical) |
|
||||
| DSSE verification success rate | 100% for valid bundles |
|
||||
| Replay record ingestion latency | < 100ms p99 |
|
||||
| Incident mode activation time | < 1 second |
|
||||
| Offline verification success | Works without network |
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-11-29*
|
||||
@@ -0,0 +1,427 @@
|
||||
# Mirror and Offline Kit Strategy
|
||||
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-11-29
|
||||
**Status:** Canonical
|
||||
|
||||
This advisory defines the product rationale, data contracts, and implementation strategy for the Mirror module, covering deterministic thin-bundle assembly, DSSE/TUF signing, time anchoring, and air-gapped distribution.
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
The Mirror module enables **air-gapped deployments** by producing deterministic, cryptographically signed bundles containing advisories, VEX documents, and policy packs. Key capabilities:
|
||||
|
||||
- **Thin Bundle Assembly** - Deterministic tar.gz with sorted entries and fixed timestamps
|
||||
- **DSSE/TUF Signing** - Ed25519 signatures with TUF metadata for key rotation
|
||||
- **Time Anchoring** - Roughtime/RFC3161 tokens for clock-independent freshness
|
||||
- **OCI Distribution** - Registry-compatible layout for container-native workflows
|
||||
- **Offline Verification** - Complete verification without network connectivity
|
||||
|
||||
---
|
||||
|
||||
## 2. Market Drivers
|
||||
|
||||
### 2.1 Target Segments
|
||||
|
||||
| Segment | Offline Requirements | Use Case |
|
||||
|---------|---------------------|----------|
|
||||
| **Defense/Intelligence** | Complete air-gap | Classified networks without internet |
|
||||
| **Critical Infrastructure** | OT network isolation | ICS/SCADA vulnerability management |
|
||||
| **Financial Services** | DMZ-only connectivity | Regulated trading floor systems |
|
||||
| **Healthcare** | Network segmentation | Medical device security scanning |
|
||||
|
||||
### 2.2 Competitive Positioning
|
||||
|
||||
Most vulnerability databases require constant connectivity. Stella Ops differentiates with:
|
||||
- **Cryptographically verifiable offline data** (DSSE + TUF)
|
||||
- **Deterministic bundles** for reproducible deployments
|
||||
- **Time-anchor freshness** without NTP dependency
|
||||
- **OCI-native distribution** for registry mirroring
|
||||
|
||||
---
|
||||
|
||||
## 3. Technical Architecture
|
||||
|
||||
### 3.1 Thin Bundle Layout (v1)
|
||||
|
||||
```
|
||||
mirror-thin-v1.tar.gz
|
||||
├── manifest.json # Bundle metadata, file inventory, hashes
|
||||
├── layers/
|
||||
│ ├── observations.ndjson # Advisory observations
|
||||
│ ├── time-anchor.json # Time token + verification metadata
|
||||
│ └── policies.tar.gz # Policy pack bundle (optional)
|
||||
├── indexes/
|
||||
│ └── observations.index # Linkage index
|
||||
└── oci/ # OCI layout (optional)
|
||||
├── index.json
|
||||
├── oci-layout
|
||||
└── blobs/sha256/...
|
||||
```
|
||||
|
||||
### 3.2 Determinism Rules
|
||||
|
||||
All thin bundles must be **bit-for-bit reproducible**:
|
||||
|
||||
| Property | Rule |
|
||||
|----------|------|
|
||||
| **Tar format** | POSIX with `--sort=name` |
|
||||
| **Owner/Group** | `--owner=0 --group=0` |
|
||||
| **mtime** | `--mtime='1970-01-01'` |
|
||||
| **Gzip** | `--no-name` flag |
|
||||
| **JSON** | Sorted keys, indent=2, trailing newline |
|
||||
| **Hashes** | Lower-case hex, SHA-256 |
|
||||
| **Timestamps** | UTC ISO-8601 (RFC3339) |
|
||||
| **Symlinks** | Not allowed |
|
||||
|
||||
### 3.3 Manifest Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"created": "2025-11-29T00:00:00Z",
|
||||
"bundleId": "mirror-thin-v1-20251129",
|
||||
"generation": 42,
|
||||
"layers": [
|
||||
{
|
||||
"path": "layers/observations.ndjson",
|
||||
"size": 1048576,
|
||||
"digest": "sha256:abc123..."
|
||||
}
|
||||
],
|
||||
"indexes": [
|
||||
{
|
||||
"name": "observations.index",
|
||||
"digest": "sha256:def456..."
|
||||
}
|
||||
],
|
||||
"hashes": {
|
||||
"tarball_sha256": "sha256:...",
|
||||
"manifest_sha256": "sha256:..."
|
||||
},
|
||||
"timeAnchor": {
|
||||
"generatedAt": "2025-11-29T00:00:00Z",
|
||||
"source": "roughtime",
|
||||
"tokenDigest": "sha256:..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. DSSE/TUF Signing Profile
|
||||
|
||||
### 4.1 DSSE Envelope
|
||||
|
||||
**Payload Type:** `application/vnd.stellaops.mirror+json;version=1`
|
||||
|
||||
**Structure:**
|
||||
|
||||
```json
|
||||
{
|
||||
"payloadType": "application/vnd.stellaops.mirror+json;version=1",
|
||||
"payload": "<base64(manifest.json)>",
|
||||
"signatures": [{
|
||||
"keyid": "mirror-root-ed25519-01",
|
||||
"sig": "<base64(Ed25519 signature)>"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**Header Claims:**
|
||||
- `issuer` - Signing authority identifier
|
||||
- `keyid` - Key reference for verification
|
||||
- `created` - UTC timestamp of signing
|
||||
- `purpose` - Must be `mirror-bundle`
|
||||
|
||||
### 4.2 TUF Metadata Layout
|
||||
|
||||
```
|
||||
tuf/
|
||||
├── root.json # Trust root (long-lived)
|
||||
├── snapshot.json # Metadata versions
|
||||
├── targets.json # Target file mappings
|
||||
├── timestamp.json # Freshness timestamp
|
||||
└── keys/
|
||||
└── mirror-root-ed25519-01.pub
|
||||
```
|
||||
|
||||
**Targets Mapping:**
|
||||
|
||||
```json
|
||||
{
|
||||
"targets": {
|
||||
"mirror-thin-v1.tar.gz": {
|
||||
"length": 10485760,
|
||||
"hashes": {
|
||||
"sha256": "abc123..."
|
||||
}
|
||||
},
|
||||
"mirror-thin-v1.manifest.json": {
|
||||
"length": 2048,
|
||||
"hashes": {
|
||||
"sha256": "def456..."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 Key Management
|
||||
|
||||
| Key Type | Lifetime | Storage | Rotation |
|
||||
|----------|----------|---------|----------|
|
||||
| **Root** | 1 year | HSM/offline | Ceremony required |
|
||||
| **Snapshot** | 90 days | Online | Automated |
|
||||
| **Targets** | 90 days | Online | Automated |
|
||||
| **Timestamp** | 1 day | Online | Continuous |
|
||||
|
||||
---
|
||||
|
||||
## 5. Time Anchoring
|
||||
|
||||
### 5.1 Time-Anchor Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"anchorTime": "2025-11-29T00:00:00Z",
|
||||
"source": "roughtime",
|
||||
"format": "roughtime-v1",
|
||||
"tokenDigest": "sha256:...",
|
||||
"signatureFingerprint": "abc123...",
|
||||
"verification": {
|
||||
"status": "passed",
|
||||
"reason": null
|
||||
},
|
||||
"generatedAt": "2025-11-29T00:00:00Z",
|
||||
"sourceClock": "ntp:chrony",
|
||||
"validForSeconds": 86400
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 Staleness Calculation
|
||||
|
||||
```
|
||||
stalenessSeconds = now_utc - generatedAt
|
||||
isStale = stalenessSeconds > (validForSeconds + 5s_tolerance)
|
||||
```
|
||||
|
||||
**Default validity:** 24 hours (86400 seconds)
|
||||
|
||||
### 5.3 Trust Roots
|
||||
|
||||
Trust roots for time verification stored in offline-friendly bundle:
|
||||
|
||||
```json
|
||||
{
|
||||
"roughtime": [
|
||||
{
|
||||
"name": "cloudflare",
|
||||
"publicKey": "...",
|
||||
"address": "roughtime.cloudflare.com:2002"
|
||||
}
|
||||
],
|
||||
"rfc3161": [
|
||||
{
|
||||
"name": "digicert",
|
||||
"url": "http://timestamp.digicert.com",
|
||||
"certificate": "..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Implementation Strategy
|
||||
|
||||
### 6.1 Phase 1: Thin Bundle Assembly (Complete)
|
||||
|
||||
- [x] Deterministic tarball assembler (`make-thin-v1.sh`)
|
||||
- [x] Manifest generation with sorted keys
|
||||
- [x] OCI layout generation
|
||||
- [x] Verification scripts (`verify_thin_bundle.py`)
|
||||
|
||||
### 6.2 Phase 2: DSSE/TUF Signing (In Progress)
|
||||
|
||||
- [x] DSSE envelope generation with Ed25519
|
||||
- [x] TUF metadata structure
|
||||
- [ ] Production key provisioning (blocked on CI secret)
|
||||
- [ ] Automated rotation pipeline
|
||||
|
||||
### 6.3 Phase 3: Time Anchoring (In Progress)
|
||||
|
||||
- [x] Time-anchor schema definition
|
||||
- [x] Contract for `generatedAt`, `validForSeconds` fields
|
||||
- [ ] Production Roughtime/RFC3161 integration
|
||||
- [ ] Trust roots provisioning
|
||||
|
||||
### 6.4 Phase 4: Distribution Integration (Planned)
|
||||
|
||||
- [ ] Export Center mirror profile automation
|
||||
- [ ] Orchestrator `mirror.ready` event emission
|
||||
- [ ] CLI `stella mirror create|verify|status` commands
|
||||
- [ ] OCI registry push/pull workflows
|
||||
|
||||
---
|
||||
|
||||
## 7. API Surface
|
||||
|
||||
### 7.1 Mirror APIs
|
||||
|
||||
| Endpoint | Method | Scope | Description |
|
||||
|----------|--------|-------|-------------|
|
||||
| `/mirror/bundles` | GET | `mirror:read` | List mirror bundles |
|
||||
| `/mirror/bundles/{id}` | GET | `mirror:read` | Get bundle metadata |
|
||||
| `/mirror/bundles/{id}/download` | GET | `mirror:read` | Download thin bundle |
|
||||
| `/mirror/bundles` | POST | `mirror:create` | Create new mirror bundle |
|
||||
| `/mirror/verify` | POST | `mirror:read` | Verify bundle integrity |
|
||||
|
||||
### 7.2 Orchestrator Events
|
||||
|
||||
**Event:** `mirror.ready`
|
||||
|
||||
```json
|
||||
{
|
||||
"bundleId": "mirror-thin-v1-20251129",
|
||||
"generation": 42,
|
||||
"generatedAt": "2025-11-29T00:00:00Z",
|
||||
"manifestDigest": "sha256:...",
|
||||
"dsseDigest": "sha256:...",
|
||||
"location": "s3://mirrors/thin/v1/...",
|
||||
"rekorUUID": "..."
|
||||
}
|
||||
```
|
||||
|
||||
**Semantics:** At-least-once delivery; consumers de-dup by `(bundleId, generation)`.
|
||||
|
||||
### 7.3 CLI Commands
|
||||
|
||||
```bash
|
||||
# Create mirror bundle
|
||||
stella mirror create --output mirror-thin-v1.tar.gz
|
||||
|
||||
# Verify bundle integrity
|
||||
stella mirror verify mirror-thin-v1.tar.gz
|
||||
|
||||
# Check bundle status
|
||||
stella mirror status --bundle-id mirror-thin-v1-20251129
|
||||
|
||||
# Import bundle into air-gapped installation
|
||||
stella airgap import mirror-thin-v1.tar.gz --describe
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Offline Kit Integration
|
||||
|
||||
### 8.1 Offline Kit Structure
|
||||
|
||||
```
|
||||
offline-kit/
|
||||
├── mirrors/
|
||||
│ ├── mirror-thin-v1.tar.gz # Advisory/VEX data
|
||||
│ ├── mirror-thin-v1.manifest.json
|
||||
│ └── mirror-thin-v1.dsse.json
|
||||
├── evidence/
|
||||
│ └── evidence-bundle-*.tar.gz # Evidence bundles
|
||||
├── policies/
|
||||
│ └── policy-pack-*.tar.gz # Policy packs
|
||||
├── trust/
|
||||
│ ├── tuf/ # TUF metadata
|
||||
│ └── time-anchors.json # Time trust roots
|
||||
└── MANIFEST.json # Kit manifest with hashes
|
||||
```
|
||||
|
||||
### 8.2 Import Workflow
|
||||
|
||||
1. **Verify MANIFEST.json** signature against bundled TUF root
|
||||
2. **Validate each artifact** hash matches manifest
|
||||
3. **Check time anchor freshness** against configured tolerance
|
||||
4. **Import to local stores** (Concelier, Excititor, Evidence Locker)
|
||||
5. **Record import event** with provenance in Timeline
|
||||
|
||||
---
|
||||
|
||||
## 9. Verification Workflow
|
||||
|
||||
### 9.1 Online Verification
|
||||
|
||||
1. Fetch bundle from registry/export center
|
||||
2. Verify DSSE signature against JWKS
|
||||
3. Validate TUF metadata chain
|
||||
4. Check Rekor transparency log (if present)
|
||||
5. Verify time anchor freshness
|
||||
|
||||
### 9.2 Offline Verification
|
||||
|
||||
1. Extract bundle and TUF metadata
|
||||
2. Verify DSSE signature against bundled public key
|
||||
3. Validate all file hashes match manifest
|
||||
4. Check time anchor against local clock + tolerance
|
||||
5. Record verification result in local audit log
|
||||
|
||||
---
|
||||
|
||||
## 10. Security Considerations
|
||||
|
||||
### 10.1 Key Protection
|
||||
|
||||
- Root keys stored in HSM or offline cold storage
|
||||
- Online keys rotated automatically per TUF policy
|
||||
- Key ceremonies documented and audited
|
||||
|
||||
### 10.2 Rollback Protection
|
||||
|
||||
- TUF timestamp/snapshot prevent rollback attacks
|
||||
- Generation numbers monotonically increasing
|
||||
- Stale bundles rejected based on time anchor
|
||||
|
||||
### 10.3 Tampering Detection
|
||||
|
||||
- DSSE signature covers entire manifest
|
||||
- Each file has individual hash verification
|
||||
- Merkle tree optional for large bundles
|
||||
|
||||
---
|
||||
|
||||
## 11. Related Documentation
|
||||
|
||||
| Resource | Location |
|
||||
|----------|----------|
|
||||
| Mirror module docs | `docs/modules/mirror/` |
|
||||
| DSSE/TUF profile | `docs/modules/mirror/dsse-tuf-profile.md` |
|
||||
| Thin bundle spec | `docs/modules/mirror/thin-bundle-assembler.md` |
|
||||
| Time-anchor schema | `docs/airgap/time-anchor-schema.json` |
|
||||
| Signing runbook | `docs/modules/mirror/signing-runbook.md` |
|
||||
|
||||
---
|
||||
|
||||
## 12. Sprint Mapping
|
||||
|
||||
- **Primary Sprint:** SPRINT_0125_0001_0001 (Mirror Bundles)
|
||||
- **Coordination:** SPRINT_0150_0001_0001 (DSSE/Time Anchors)
|
||||
|
||||
**Key Task IDs:**
|
||||
- `MIRROR-CRT-56-001` - Deterministic assembler (DONE)
|
||||
- `MIRROR-CRT-56-002` - DSSE/TUF signing (BLOCKED - CI key needed)
|
||||
- `MIRROR-CRT-57-001` - OCI layout generation (DONE)
|
||||
- `MIRROR-CRT-57-002` - Time-anchor embedding (PARTIAL)
|
||||
- `CLI-AIRGAP-56-001` - CLI mirror commands (BLOCKED)
|
||||
|
||||
---
|
||||
|
||||
## 13. Success Metrics
|
||||
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| Bundle hash reproducibility | 100% (bit-identical) |
|
||||
| DSSE verification success | 100% for valid bundles |
|
||||
| Time anchor freshness | < 24 hours default |
|
||||
| Offline import success | Works without network |
|
||||
| TUF metadata validation | Full chain verified |
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-11-29*
|
||||
@@ -0,0 +1,447 @@
|
||||
# Task Pack Orchestration and Automation
|
||||
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-11-29
|
||||
**Status:** Canonical
|
||||
|
||||
This advisory defines the product rationale, DSL semantics, and implementation strategy for the TaskRunner module, covering pack manifest structure, execution semantics, approval workflows, and evidence capture.
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
The TaskRunner provides **deterministic, auditable automation** for security workflows. Key capabilities:
|
||||
|
||||
- **Task Pack DSL** - Declarative YAML manifests for multi-step workflows
|
||||
- **Approval Gates** - Human-in-the-loop checkpoints with Authority integration
|
||||
- **Deterministic Execution** - Plan hash verification prevents runtime divergence
|
||||
- **Evidence Capture** - DSSE attestations for provenance and audit
|
||||
- **Air-Gap Support** - Sealed-mode validation for offline installations
|
||||
|
||||
---
|
||||
|
||||
## 2. Market Drivers
|
||||
|
||||
### 2.1 Target Segments
|
||||
|
||||
| Segment | Automation Requirements | Use Case |
|
||||
|---------|------------------------|----------|
|
||||
| **Enterprise Security** | Approval workflows for vulnerability remediation | Change advisory board gates |
|
||||
| **DevSecOps** | CI/CD pipeline integration | Automated policy enforcement |
|
||||
| **Compliance Teams** | Auditable execution with evidence | SOC 2, FedRAMP documentation |
|
||||
| **MSP/MSSP** | Multi-tenant orchestration | Managed security services |
|
||||
|
||||
### 2.2 Competitive Positioning
|
||||
|
||||
Most vulnerability scanning tools lack built-in orchestration. Stella Ops differentiates with:
|
||||
- **Declarative task packs** with schema validation
|
||||
- **Cryptographic plan verification** (plan hash binding)
|
||||
- **Native approval gates** with Authority token integration
|
||||
- **Evidence attestations** for audit trails
|
||||
- **Sealed-mode enforcement** for air-gapped environments
|
||||
|
||||
---
|
||||
|
||||
## 3. Technical Architecture
|
||||
|
||||
### 3.1 Pack Manifest Structure (v1)
|
||||
|
||||
```yaml
|
||||
apiVersion: stellaops.io/pack.v1
|
||||
kind: TaskPack
|
||||
metadata:
|
||||
name: vulnerability-scan-and-report
|
||||
version: 1.2.0
|
||||
description: Scan container, evaluate policy, generate report
|
||||
tags: [security, compliance, scanning]
|
||||
tenantVisibility: private
|
||||
maintainers:
|
||||
- name: Security Team
|
||||
email: security@example.com
|
||||
license: MIT
|
||||
|
||||
spec:
|
||||
inputs:
|
||||
- name: imageRef
|
||||
type: string
|
||||
required: true
|
||||
schema:
|
||||
pattern: "^[a-z0-9./-]+:[a-z0-9.-]+$"
|
||||
- name: policyPack
|
||||
type: string
|
||||
default: "default-policy-v1"
|
||||
|
||||
secrets:
|
||||
- name: registryCredentials
|
||||
scope: scanner.read
|
||||
description: Registry pull credentials
|
||||
|
||||
approvals:
|
||||
- name: security-review
|
||||
grants: ["security-lead", "ciso"]
|
||||
ttlHours: 72
|
||||
message: "Approve scan results before policy evaluation"
|
||||
|
||||
steps:
|
||||
- id: scan
|
||||
type: run
|
||||
module: scanner/sbom-vuln
|
||||
inputs:
|
||||
image: "{{ inputs.imageRef }}"
|
||||
outputs:
|
||||
sbom: sbom.json
|
||||
vulns: vulnerabilities.json
|
||||
|
||||
- id: review-gate
|
||||
type: gate.approval
|
||||
approval: security-review
|
||||
dependsOn: [scan]
|
||||
|
||||
- id: policy-eval
|
||||
type: run
|
||||
module: policy/evaluate
|
||||
inputs:
|
||||
sbom: "{{ steps.scan.outputs.sbom }}"
|
||||
vulns: "{{ steps.scan.outputs.vulns }}"
|
||||
pack: "{{ inputs.policyPack }}"
|
||||
dependsOn: [review-gate]
|
||||
|
||||
- id: generate-report
|
||||
type: parallel
|
||||
maxParallel: 2
|
||||
steps:
|
||||
- id: pdf-report
|
||||
type: run
|
||||
module: export/pdf
|
||||
inputs:
|
||||
data: "{{ steps.policy-eval.outputs.results }}"
|
||||
- id: json-report
|
||||
type: run
|
||||
module: export/json
|
||||
inputs:
|
||||
data: "{{ steps.policy-eval.outputs.results }}"
|
||||
dependsOn: [policy-eval]
|
||||
|
||||
outputs:
|
||||
- name: scanReport
|
||||
type: file
|
||||
path: "{{ steps.generate-report.steps.pdf-report.outputs.file }}"
|
||||
- name: machineReadable
|
||||
type: object
|
||||
value: "{{ steps.generate-report.steps.json-report.outputs.data }}"
|
||||
|
||||
success:
|
||||
message: "Scan completed successfully"
|
||||
failure:
|
||||
message: "Scan failed - review logs"
|
||||
retryPolicy:
|
||||
maxRetries: 2
|
||||
backoffSeconds: 60
|
||||
```
|
||||
|
||||
### 3.2 Step Types
|
||||
|
||||
| Type | Purpose | Key Properties |
|
||||
|------|---------|----------------|
|
||||
| `run` | Execute module | `module`, `inputs`, `outputs` |
|
||||
| `parallel` | Concurrent execution | `steps[]`, `maxParallel` |
|
||||
| `map` | Iterate over list | `items`, `step`, `maxParallel` |
|
||||
| `gate.approval` | Human approval checkpoint | `approval`, `timeout` |
|
||||
| `gate.policy` | Policy Engine validation | `policy`, `failAction` |
|
||||
|
||||
### 3.3 Execution Semantics
|
||||
|
||||
**Plan Phase:**
|
||||
1. Parse manifest and validate schema
|
||||
2. Resolve input expressions
|
||||
3. Build execution graph
|
||||
4. Compute **canonical plan hash** (SHA-256 of normalized graph)
|
||||
|
||||
**Simulation Phase (Optional):**
|
||||
1. Execute all steps in dry-run mode
|
||||
2. Capture expected outputs
|
||||
3. Store simulation results with plan hash
|
||||
|
||||
**Execution Phase:**
|
||||
1. Verify runtime graph matches plan hash
|
||||
2. Execute steps in dependency order
|
||||
3. Emit progress events to Timeline
|
||||
4. Capture output artifacts
|
||||
|
||||
**Evidence Phase:**
|
||||
1. Generate DSSE attestation with plan hash
|
||||
2. Include input digests and output manifests
|
||||
3. Store in Evidence Locker
|
||||
4. Optionally anchor to Rekor
|
||||
|
||||
---
|
||||
|
||||
## 4. Approval Workflow
|
||||
|
||||
### 4.1 Gate Definition
|
||||
|
||||
```yaml
|
||||
approvals:
|
||||
- name: security-review
|
||||
grants: ["role/security-lead", "role/ciso"]
|
||||
ttlHours: 72
|
||||
message: "Review vulnerability findings before proceeding"
|
||||
requiredCount: 1 # Number of approvals needed
|
||||
```
|
||||
|
||||
### 4.2 Authority Token Contract
|
||||
|
||||
Approval tokens must include:
|
||||
|
||||
| Claim | Description |
|
||||
|-------|-------------|
|
||||
| `pack_run_id` | Run identifier (UUID) |
|
||||
| `pack_gate_id` | Gate name from manifest |
|
||||
| `pack_plan_hash` | Canonical plan hash |
|
||||
| `auth_time` | Must be within 5 minutes of request |
|
||||
|
||||
### 4.3 CLI Approval Command
|
||||
|
||||
```bash
|
||||
stella pack approve \
|
||||
--run "run:tenant-default:20251129T120000Z" \
|
||||
--gate security-review \
|
||||
--pack-run-id "abc123..." \
|
||||
--pack-gate-id "security-review" \
|
||||
--pack-plan-hash "sha256:def456..." \
|
||||
--comment "Reviewed findings, no critical issues"
|
||||
```
|
||||
|
||||
### 4.4 Approval Events
|
||||
|
||||
| Event | Trigger |
|
||||
|-------|---------|
|
||||
| `pack.approval.requested` | Gate reached, awaiting approval |
|
||||
| `pack.approval.granted` | Approval recorded |
|
||||
| `pack.approval.denied` | Approval rejected |
|
||||
| `pack.approval.expired` | TTL exceeded without approval |
|
||||
|
||||
---
|
||||
|
||||
## 5. Implementation Strategy
|
||||
|
||||
### 5.1 Phase 1: Core Execution (In Progress)
|
||||
|
||||
- [x] Telemetry core adoption (TASKRUN-OBS-50-001)
|
||||
- [x] Metrics implementation (TASKRUN-OBS-51-001)
|
||||
- [ ] Architecture/API contracts (TASKRUN-41-001) - BLOCKED
|
||||
- [ ] Execution engine enhancements (TASKRUN-42-001) - BLOCKED
|
||||
|
||||
### 5.2 Phase 2: Approvals & Evidence (Planned)
|
||||
|
||||
- [ ] Timeline event emission (TASKRUN-OBS-52-001)
|
||||
- [ ] Evidence locker snapshots (TASKRUN-OBS-53-001)
|
||||
- [ ] DSSE attestations (TASKRUN-OBS-54-001)
|
||||
- [ ] Incident mode escalations (TASKRUN-OBS-55-001)
|
||||
|
||||
### 5.3 Phase 3: Multi-Tenancy & Air-Gap (Planned)
|
||||
|
||||
- [ ] Tenant scoping and egress control (TASKRUN-TEN-48-001)
|
||||
- [ ] Sealed-mode validation (TASKRUN-AIRGAP-56-001)
|
||||
- [ ] Bundle ingestion for offline (TASKRUN-AIRGAP-56-002)
|
||||
- [ ] Evidence capture in sealed mode (TASKRUN-AIRGAP-58-001)
|
||||
|
||||
---
|
||||
|
||||
## 6. API Surface
|
||||
|
||||
### 6.1 TaskRunner APIs
|
||||
|
||||
| Endpoint | Method | Scope | Description |
|
||||
|----------|--------|-------|-------------|
|
||||
| `/api/runs` | POST | `packs.run` | Submit pack run |
|
||||
| `/api/runs/{runId}` | GET | `packs.read` | Get run status |
|
||||
| `/api/runs/{runId}/logs` | GET | `packs.read` | Stream logs (SSE) |
|
||||
| `/api/runs/{runId}/artifacts` | GET | `packs.read` | List artifacts |
|
||||
| `/api/runs/{runId}/approve` | POST | `packs.approve` | Record approval |
|
||||
| `/api/runs/{runId}/cancel` | POST | `packs.run` | Cancel run |
|
||||
|
||||
### 6.2 Packs Registry APIs
|
||||
|
||||
| Endpoint | Method | Scope | Description |
|
||||
|----------|--------|-------|-------------|
|
||||
| `/api/packs` | GET | `packs.read` | List packs |
|
||||
| `/api/packs/{packId}/versions` | GET | `packs.read` | List versions |
|
||||
| `/api/packs/{packId}/versions/{version}` | GET | `packs.read` | Get manifest |
|
||||
| `/api/packs/{packId}/versions` | POST | `packs.write` | Publish pack |
|
||||
| `/api/packs/{packId}/promote` | POST | `packs.write` | Promote channel |
|
||||
|
||||
### 6.3 CLI Commands
|
||||
|
||||
```bash
|
||||
# Initialize pack scaffold
|
||||
stella pack init --name my-workflow
|
||||
|
||||
# Validate manifest
|
||||
stella pack validate pack.yaml
|
||||
|
||||
# Dry-run simulation
|
||||
stella pack plan pack.yaml --inputs image=nginx:latest
|
||||
|
||||
# Execute pack
|
||||
stella pack run pack.yaml --inputs image=nginx:latest
|
||||
|
||||
# Build distributable bundle
|
||||
stella pack build pack.yaml --output my-workflow-1.0.0.tar.gz
|
||||
|
||||
# Sign bundle
|
||||
cosign sign-blob my-workflow-1.0.0.tar.gz
|
||||
|
||||
# Publish to registry
|
||||
stella pack push my-workflow-1.0.0.tar.gz --registry packs.example.com
|
||||
|
||||
# Export for offline distribution
|
||||
stella pack bundle export --pack my-workflow --version 1.0.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Storage Model
|
||||
|
||||
### 7.1 MongoDB Collections
|
||||
|
||||
**pack_runs:**
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `_id` | string | Run identifier |
|
||||
| `planHash` | string | Canonical plan hash |
|
||||
| `plan` | object | Full TaskPackPlan |
|
||||
| `failurePolicy` | object | Retry/backoff config |
|
||||
| `requestedAt` | date | Client request time |
|
||||
| `tenantId` | string | Tenant scope |
|
||||
| `steps` | array | Step execution records |
|
||||
|
||||
**pack_run_logs:**
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `runId` | string | FK to pack_runs |
|
||||
| `sequence` | long | Monotonic counter |
|
||||
| `timestamp` | date | Event time (UTC) |
|
||||
| `level` | string | trace/debug/info/warn/error |
|
||||
| `eventType` | string | Machine identifier |
|
||||
| `stepId` | string | Optional step reference |
|
||||
|
||||
**pack_artifacts:**
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `runId` | string | FK to pack_runs |
|
||||
| `name` | string | Output name |
|
||||
| `type` | string | file/object/url |
|
||||
| `storedPath` | string | Object store URI |
|
||||
| `status` | string | pending/copied/materialized |
|
||||
|
||||
---
|
||||
|
||||
## 8. Evidence & Attestation
|
||||
|
||||
### 8.1 DSSE Attestation Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"payloadType": "application/vnd.stellaops.pack-run+json",
|
||||
"payload": {
|
||||
"runId": "abc123...",
|
||||
"packName": "vulnerability-scan-and-report",
|
||||
"packVersion": "1.2.0",
|
||||
"planHash": "sha256:def456...",
|
||||
"inputs": {
|
||||
"imageRef": { "value": "nginx:latest", "digest": "sha256:..." }
|
||||
},
|
||||
"outputs": [
|
||||
{ "name": "scanReport", "digest": "sha256:..." }
|
||||
],
|
||||
"steps": [
|
||||
{ "id": "scan", "status": "completed", "duration": 45.2 }
|
||||
],
|
||||
"completedAt": "2025-11-29T12:30:00Z"
|
||||
},
|
||||
"signatures": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### 8.2 Evidence Bundle
|
||||
|
||||
Task pack runs produce evidence bundles containing:
|
||||
- Pack manifest (signed)
|
||||
- Input values (redacted secrets)
|
||||
- Output artifacts
|
||||
- Step transcripts
|
||||
- DSSE attestation
|
||||
|
||||
---
|
||||
|
||||
## 9. Determinism Requirements
|
||||
|
||||
All TaskRunner operations must maintain determinism:
|
||||
|
||||
1. **Plan hash binding** - Runtime graph must match computed plan hash
|
||||
2. **Stable step ordering** - Dependencies resolve deterministically
|
||||
3. **Expression evaluation** - Same inputs produce same resolved values
|
||||
4. **Timestamps in UTC** - All logs and events use ISO-8601 UTC
|
||||
5. **Secret masking** - Secrets never appear in logs or evidence
|
||||
|
||||
---
|
||||
|
||||
## 10. RBAC & Scopes
|
||||
|
||||
| Scope | Purpose |
|
||||
|-------|---------|
|
||||
| `packs.read` | Discover/download packs |
|
||||
| `packs.write` | Publish/update packs (requires signature) |
|
||||
| `packs.run` | Execute packs via CLI/TaskRunner |
|
||||
| `packs.approve` | Fulfill approval gates |
|
||||
|
||||
**Approval Token Requirements:**
|
||||
- `pack_run_id`, `pack_gate_id`, `pack_plan_hash` are mandatory
|
||||
- Token must be fresh (within 5-minute auth window)
|
||||
|
||||
---
|
||||
|
||||
## 11. Related Documentation
|
||||
|
||||
| Resource | Location |
|
||||
|----------|----------|
|
||||
| Task Pack specification | `docs/task-packs/spec.md` |
|
||||
| Authoring guide | `docs/task-packs/authoring-guide.md` |
|
||||
| Operations runbook | `docs/task-packs/runbook.md` |
|
||||
| Registry architecture | `docs/task-packs/registry.md` |
|
||||
| MongoDB migrations | `docs/modules/taskrunner/migrations/pack-run-collections.md` |
|
||||
|
||||
---
|
||||
|
||||
## 12. Sprint Mapping
|
||||
|
||||
- **Primary Sprint:** SPRINT_0157_0001_0001_taskrunner_i.md
|
||||
- **Phase II:** SPRINT_0158_0001_0002_taskrunner_ii.md
|
||||
- **Blockers:** SPRINT_0157_0001_0002_taskrunner_blockers.md
|
||||
|
||||
**Key Task IDs:**
|
||||
- `TASKRUN-41-001` - Architecture/API contracts (BLOCKED)
|
||||
- `TASKRUN-42-001` - Execution engine enhancements (BLOCKED)
|
||||
- `TASKRUN-OBS-50-001` - Telemetry core adoption (DONE)
|
||||
- `TASKRUN-OBS-51-001` - Metrics implementation (DONE)
|
||||
- `TASKRUN-OBS-52-001` - Timeline events (BLOCKED)
|
||||
|
||||
---
|
||||
|
||||
## 13. Success Metrics
|
||||
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| Plan hash verification | 100% match or abort |
|
||||
| Approval gate response | < 5 min for high-priority |
|
||||
| Evidence attestation rate | 100% of completed runs |
|
||||
| Offline execution success | Works in sealed mode |
|
||||
| Step execution latency | < 2s overhead per step |
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-11-29*
|
||||
@@ -45,6 +45,12 @@ These are the authoritative advisories to reference for implementation:
|
||||
- **Extends:** `archived/18-Nov-2025 - Unknowns-Registry.md`
|
||||
- **Status:** Already implemented in Signals module; advisory validates design
|
||||
|
||||
### Confidence Decay for Prioritization
|
||||
- **Canonical:** `25-Nov-2025 - Half-Life Confidence Decay for Unknowns.md`
|
||||
- **Sprint:** SPRINT_0140_0001_0001_runtime_signals.md (integration point)
|
||||
- **Related:** Unknowns Registry (time-based decay complements ambiguity tracking)
|
||||
- **Status:** Design advisory - provides exponential decay formula for priority freshness
|
||||
|
||||
### Explainability
|
||||
- **Canonical (Graphs):** `27-Nov-2025 - Making Graphs Understandable to Humans.md`
|
||||
- **Canonical (Verdicts):** `27-Nov-2025 - Explainability Layer for Vulnerability Verdicts.md`
|
||||
@@ -80,12 +86,83 @@ These are the authoritative advisories to reference for implementation:
|
||||
- `docs/schemas/attestation-vuln-scan.schema.json`
|
||||
- `docs/schemas/audit-bundle-index.schema.json`
|
||||
|
||||
## Files to Archive
|
||||
### Sovereign Crypto for Regional Compliance
|
||||
- **Canonical:** `28-Nov-2025 - Sovereign Crypto for Regional Compliance.md`
|
||||
- **Sprint:** SPRINT_0514_0001_0001_sovereign_crypto_enablement.md (EXISTING)
|
||||
- **Related Docs:**
|
||||
- `docs/security/rootpack_ru_*.md` - RootPack RU documentation
|
||||
- `docs/security/crypto-registry-decision-2025-11-18.md` - Registry design
|
||||
- `docs/security/pq-provider-options.md` - Post-quantum options
|
||||
- **Status:** Fills HIGH-priority gap - covers eIDAS, FIPS, GOST, SM algorithm support
|
||||
- **Compliance:** EU (eIDAS), US (FIPS 140-2/3), Russia (GOST), China (SM2/3/4)
|
||||
|
||||
The following files should be moved to `archived/` as they are superseded:
|
||||
### Plugin Architecture & Extensibility
|
||||
- **Canonical:** `28-Nov-2025 - Plugin Architecture & Extensibility Patterns.md`
|
||||
- **Sprint:** Foundational - appears in module-specific sprints
|
||||
- **Related Docs:**
|
||||
- `docs/dev/plugins/README.md` - General plugin guide
|
||||
- `docs/dev/30_EXCITITOR_CONNECTOR_GUIDE.md` - Concelier connectors
|
||||
- `docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md` - Authority plugins
|
||||
- `docs/modules/scanner/guides/surface-validation-extensibility.md` - Scanner extensibility
|
||||
- **Status:** Fills MEDIUM-priority gap - consolidates extensibility patterns across modules
|
||||
|
||||
### Evidence Bundle & Replay Contracts
|
||||
- **Canonical:** `29-Nov-2025 - Evidence Bundle and Replay Contracts.md`
|
||||
- **Sprint:** SPRINT_0161_0001_0001_evidencelocker.md (PRIMARY)
|
||||
- **Related Sprints:**
|
||||
- SPRINT_0187_0001_0001_evidence_locker_cli_integration.md (CLI)
|
||||
- SPRINT_0160_0001_0001_export_evidence.md (Coordination)
|
||||
- **Related Docs:**
|
||||
- `docs/modules/evidence-locker/bundle-packaging.md` - Bundle spec
|
||||
- `docs/modules/evidence-locker/attestation-contract.md` - DSSE contract
|
||||
- `docs/modules/evidence-locker/replay-payload-contract.md` - Replay schema
|
||||
- **Status:** Fills HIGH-priority gap - covers deterministic bundles, attestations, replay, incident mode
|
||||
|
||||
### Mirror & Offline Kit Strategy
|
||||
- **Canonical:** `29-Nov-2025 - Mirror and Offline Kit Strategy.md`
|
||||
- **Sprint:** SPRINT_0125_0001_0001 (Mirror Bundles)
|
||||
- **Related Sprints:**
|
||||
- SPRINT_0150_0001_0001 (DSSE/Time Anchors)
|
||||
- SPRINT_0150_0001_0002 (Time Anchors)
|
||||
- SPRINT_0150_0001_0003 (Orchestrator Hooks)
|
||||
- **Related Docs:**
|
||||
- `docs/modules/mirror/dsse-tuf-profile.md` - DSSE/TUF spec
|
||||
- `docs/modules/mirror/thin-bundle-assembler.md` - Thin bundle spec
|
||||
- `docs/airgap/time-anchor-schema.json` - Time anchor schema
|
||||
- **Status:** Fills HIGH-priority gap - covers thin bundles, DSSE/TUF signing, time anchoring
|
||||
|
||||
### Task Pack Orchestration & Automation
|
||||
- **Canonical:** `29-Nov-2025 - Task Pack Orchestration and Automation.md`
|
||||
- **Sprint:** SPRINT_0157_0001_0001_taskrunner_i.md (PRIMARY)
|
||||
- **Related Sprints:**
|
||||
- SPRINT_0158_0001_0002_taskrunner_ii.md (Phase II)
|
||||
- SPRINT_0157_0001_0002_taskrunner_blockers.md (Blockers)
|
||||
- **Related Docs:**
|
||||
- `docs/task-packs/spec.md` - Pack manifest specification
|
||||
- `docs/task-packs/authoring-guide.md` - Authoring workflow
|
||||
- `docs/task-packs/registry.md` - Registry architecture
|
||||
- **Status:** Fills HIGH-priority gap - covers pack DSL, approvals, evidence capture
|
||||
|
||||
### Authentication & Authorization Architecture
|
||||
- **Canonical:** `29-Nov-2025 - Authentication and Authorization Architecture.md`
|
||||
- **Sprint:** Multiple (see below)
|
||||
- **Related Sprints:**
|
||||
- SPRINT_100_identity_signing.md (CLOSED - historical)
|
||||
- SPRINT_314_docs_modules_authority.md (Docs)
|
||||
- SPRINT_0514_0001_0001_sovereign_crypto_enablement.md (Crypto)
|
||||
- **Related Docs:**
|
||||
- `docs/modules/authority/architecture.md` - Module architecture
|
||||
- `docs/11_AUTHORITY.md` - Overview
|
||||
- `docs/security/authority-scopes.md` - Scope reference
|
||||
- `docs/security/dpop-mtls-rollout.md` - Sender constraints
|
||||
- **Status:** Fills HIGH-priority gap - consolidates token model, scopes, multi-tenant isolation
|
||||
|
||||
## Files Archived
|
||||
|
||||
The following files have been moved to `archived/27-Nov-2025-superseded/`:
|
||||
|
||||
```
|
||||
# Duplicates/superseded
|
||||
# Superseded by canonical advisories
|
||||
24-Nov-2025 - Bridging OpenVEX and CycloneDX for .NET.md
|
||||
25-Nov-2025 - Revisiting Determinism in SBOM→VEX Pipeline.md
|
||||
25-Nov-2025 - Hash‑Stable Graph Revisions Across Systems.md
|
||||
@@ -93,13 +170,15 @@ The following files should be moved to `archived/` as they are superseded:
|
||||
27-Nov-2025 - Rekor Envelope Size Heuristic.md
|
||||
27-Nov-2025 - DSSE and Rekor Envelope Size Heuristic.md
|
||||
27-Nov-2025 - Optimizing DSSE Batch Sizes for Reliable Logging.md
|
||||
|
||||
# Junk/malformed files
|
||||
24-Nov-2025 - 1 copy 2.md
|
||||
24-Nov-2025 - Designing a Deterministic Reachability Benchmarkmd (missing dot)
|
||||
25-Nov-2025 - Half‑Life Confidence Decay for Unknownsmd (missing dot)
|
||||
```
|
||||
|
||||
## Cleanup Completed (2025-11-28)
|
||||
|
||||
The following issues were fixed:
|
||||
- Deleted junk file: `24-Nov-2025 - 1 copy 2.md`
|
||||
- Deleted malformed duplicate: `24-Nov-2025 - Designing a Deterministic Reachability Benchmarkmd`
|
||||
- Fixed filename: `25-Nov-2025 - Half-Life Confidence Decay for Unknowns.md` (was missing .md extension)
|
||||
|
||||
## Sprint Cross-Reference
|
||||
|
||||
| Advisory Topic | Sprint ID | Status |
|
||||
@@ -108,10 +187,17 @@ The following files should be moved to `archived/` as they are superseded:
|
||||
| SPDX 3.0.1 / SBOM | SPRINT_0186_0001_0001 | AUGMENTED |
|
||||
| Reachability Benchmark | SPRINT_0513_0001_0001 | NEW |
|
||||
| Reachability Evidence | SPRINT_0401_0001_0001 | EXISTING |
|
||||
| Unknowns Registry | SPRINT_0140_0001_0001 | EXISTING (implemented) |
|
||||
| Unknowns Registry | SPRINT_0140_0001_0001 | IMPLEMENTED |
|
||||
| Confidence Decay | SPRINT_0140_0001_0001 | DESIGN |
|
||||
| Graph Revision IDs | SPRINT_0401_0001_0001 | EXISTING |
|
||||
| DSSE/Rekor Batching | SPRINT_0401_0001_0001 | EXISTING |
|
||||
| Vuln Triage UX / VEX | SPRINT_0215_0001_0001 | NEW |
|
||||
| Sovereign Crypto | SPRINT_0514_0001_0001 | EXISTING |
|
||||
| Plugin Architecture | Multiple (module-specific) | FOUNDATIONAL |
|
||||
| Evidence Bundle & Replay | SPRINT_0161_0001_0001 | EXISTING |
|
||||
| Mirror & Offline Kit | SPRINT_0125_0001_0001 | EXISTING |
|
||||
| Task Pack Orchestration | SPRINT_0157_0001_0001 | EXISTING |
|
||||
| Auth/AuthZ Architecture | Multiple (100, 314, 0514) | EXISTING |
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
@@ -121,8 +207,14 @@ Based on gap analysis:
|
||||
2. **P1 - SPDX 3.0.1** (Sprint 0186 tasks 15a-15f) - Standards compliance
|
||||
3. **P1 - Public Benchmark** (Sprint 0513) - Differentiation/marketing value
|
||||
4. **P1 - Vuln Triage UX** (Sprint 0215) - Industry-aligned UX for competitive parity
|
||||
5. **P2 - Explainability** (Sprint 0401) - UX enhancement, existing tasks
|
||||
6. **P3 - Already Implemented** - Unknowns, Graph IDs, DSSE batching
|
||||
5. **P1 - Sovereign Crypto** (Sprint 0514) - Regional compliance enablement
|
||||
6. **P1 - Evidence Bundle & Replay** (Sprint 0161, 0187) - Audit/compliance critical
|
||||
7. **P1 - Mirror & Offline Kit** (Sprint 0125, 0150) - Air-gap deployment critical
|
||||
8. **P2 - Task Pack Orchestration** (Sprint 0157, 0158) - Automation foundation
|
||||
9. **P2 - Explainability** (Sprint 0401) - UX enhancement, existing tasks
|
||||
10. **P2 - Plugin Architecture** (Multiple) - Foundational extensibility patterns
|
||||
11. **P2 - Auth/AuthZ Architecture** (Multiple) - Security consolidation
|
||||
12. **P3 - Already Implemented** - Unknowns, Graph IDs, DSSE batching
|
||||
|
||||
## Implementer Quick Reference
|
||||
|
||||
@@ -145,7 +237,41 @@ For each topic, the implementer should read:
|
||||
| Vuln Explorer | `docs/modules/vuln-explorer/architecture.md` | `src/VulnExplorer/*/AGENTS.md` |
|
||||
| VEX-Lens | `docs/modules/vex-lens/architecture.md` | `src/Excititor/*/AGENTS.md` |
|
||||
| UI | `docs/modules/ui/architecture.md` | `src/UI/*/AGENTS.md` |
|
||||
| Authority | `docs/modules/authority/architecture.md` | `src/Authority/*/AGENTS.md` |
|
||||
| Evidence Locker | `docs/modules/evidence-locker/*.md` | `src/EvidenceLocker/*/AGENTS.md` |
|
||||
| Mirror | `docs/modules/mirror/*.md` | `src/Mirror/*/AGENTS.md` |
|
||||
| TaskRunner | `docs/modules/taskrunner/*.md` | `src/TaskRunner/*/AGENTS.md` |
|
||||
|
||||
## Topical Gaps (Advisory Needed)
|
||||
|
||||
The following topics are mentioned in CLAUDE.md or module docs but lack dedicated product advisories:
|
||||
|
||||
| Gap | Severity | Status | Notes |
|
||||
|-----|----------|--------|-------|
|
||||
| ~~Regional Crypto (eIDAS/FIPS/GOST/SM)~~ | HIGH | **FILLED** | `28-Nov-2025 - Sovereign Crypto for Regional Compliance.md` |
|
||||
| ~~Plugin Architecture Patterns~~ | MEDIUM | **FILLED** | `28-Nov-2025 - Plugin Architecture & Extensibility Patterns.md` |
|
||||
| ~~Evidence Bundle Packaging~~ | HIGH | **FILLED** | `29-Nov-2025 - Evidence Bundle and Replay Contracts.md` |
|
||||
| ~~Mirror/Offline Kit Strategy~~ | HIGH | **FILLED** | `29-Nov-2025 - Mirror and Offline Kit Strategy.md` |
|
||||
| ~~Task Pack Orchestration~~ | HIGH | **FILLED** | `29-Nov-2025 - Task Pack Orchestration and Automation.md` |
|
||||
| ~~Auth/AuthZ Architecture~~ | HIGH | **FILLED** | `29-Nov-2025 - Authentication and Authorization Architecture.md` |
|
||||
| **CycloneDX 1.6 .NET Integration** | LOW | Open | Deep Architecture covers generically; expand with .NET-specific guidance |
|
||||
| **Findings Ledger & Audit Trail** | MEDIUM | Open | Immutable verdict tracking; module exists but no advisory |
|
||||
| **Runtime Posture & Observation** | MEDIUM | Open | Zastava runtime signals; sprints exist but no advisory |
|
||||
| **Graph Analytics & Clustering** | MEDIUM | Open | Community detection, blast-radius; implementation underway |
|
||||
| **Policy Simulation & Shadow Gates** | MEDIUM | Open | Impact modeling; extensive sprints but no contract advisory |
|
||||
| **Notification Rules Engine** | MEDIUM | Open | Throttling, digests, templating; sprints active |
|
||||
|
||||
## Known Issues (Non-Blocking)
|
||||
|
||||
**Unicode Encoding Inconsistency:**
|
||||
Several filenames use en-dash (U+2011) instead of regular hyphen (-). This may cause cross-platform issues but does not affect content discovery. Files affected:
|
||||
- `26-Nov-2025 - Handling Rekor v2 and DSSE Air‑Gap Limits.md`
|
||||
- `27-Nov-2025 - Blueprint for a 2026‑Ready Scanner.md`
|
||||
- `27-Nov-2025 - Deep Architecture Brief - SBOM‑First, VEX‑Ready Spine.md`
|
||||
|
||||
**Archived Duplicate:**
|
||||
`archived/17-Nov-2025 - SBOM-Provenance-Spine.md` and `archived/18-Nov-2025 - SBOM-Provenance-Spine.md` are potential duplicates. The 18-Nov version is likely canonical.
|
||||
|
||||
---
|
||||
*Index created: 2025-11-27*
|
||||
*Last updated: 2025-11-28*
|
||||
*Last updated: 2025-11-29*
|
||||
|
||||
Reference in New Issue
Block a user