up
This commit is contained in:
StellaOps Bot
@@ -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