feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes. - Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes. - Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables. - Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
This commit is contained in:
430
docs/moat.md
Normal file
430
docs/moat.md
Normal file
@@ -0,0 +1,430 @@
|
||||
# StellaOps Moat Track — Spec Outline v0.3
|
||||
|
||||
**Scope of this doc:**
|
||||
(1) Deterministic Replayable Scans (SRM), (2) Policy Engine & Lattice UI, (3) Sovereign Readiness (CryptoProfile + RootPack), (4) Attestation Observability Graph (AOG), (5) Procurement‑Grade Trust Statement, (6) Third‑Party Proof Channel, (7) Zastava differential SBOM + AI scheduler.
|
||||
|
||||
Cross‑cutting principles: offline‑first, cryptographic determinism, evidence‑bound decisions, regional crypto compliance, minimal operational friction.
|
||||
|
||||
---
|
||||
|
||||
## 0) Shared Concepts (applies to all 7)
|
||||
|
||||
* **Artifact identity:** digest-first (OCI image digest, file sha256).
|
||||
* **Canonicalization:** all structured payloads (SBOM, SRM, Trust Statement JSON, VEX) are normalized via Canonical JSON (RFC‑8785‑like) prior to hashing/signing.
|
||||
* **Signatures:** DSSE envelopes; **dual‑signing** supported (e.g., FIPS ECDSA + GOST R 34.10; or ECDSA + SM2).
|
||||
* **Attestation chain:** each decision (scan, VEX merge, policy evaluation) yields a signed, replayable record.
|
||||
* **Profiles & Packs:** **CryptoProfile** (algorithm + root policy) and **RootPack** (trust anchors + OCSP/CRL/TSA mirrors) are versioned and importable.
|
||||
* **Policy Unit Tests:** any policy/lattice bundle ships with fixtures expected to pass during CI.
|
||||
|
||||
---
|
||||
|
||||
## 1) Deterministic Replayable Scans — SRM
|
||||
|
||||
### Objective
|
||||
|
||||
Make every scan a **provable, re‑executable fact**. Auditors can replay; results are bit‑for‑bit reproducible.
|
||||
|
||||
### Deliverables
|
||||
|
||||
* **SRM v0.1** schema (YAML/JSON)
|
||||
* Deterministic executor + `stella replay`
|
||||
* Replay diffing and result hashing
|
||||
|
||||
### SRM (Stella Replay Manifest) — schema (abridged)
|
||||
|
||||
```yaml
|
||||
apiVersion: srm.stellaops.dev/v0.1
|
||||
scan:
|
||||
id: uuid
|
||||
timestamp: ISO8601
|
||||
engine: { name: "stella-scan", version: "1.7.3", build_sha: "<sha>" }
|
||||
environment:
|
||||
os_image: <digest>
|
||||
kernel: { uname: "...", cgroups: "v2" }
|
||||
cpu_features: [avx2, sse4.2]
|
||||
inputs:
|
||||
image: { name: "reg/app:1.9.2", digest: "<sha>", layers: ["<sha>", ...] }
|
||||
sbom: { type: "cyclonedx@1.5", digest: "<sha>" }
|
||||
vex_set: [{ type: "openvex", digest: "<sha>" }]
|
||||
lattice_policy: { id: "corp-policy@2025-08-15", digest: "<sha>" }
|
||||
rules_and_feeds:
|
||||
rulesets: [{ name: "vuln-core", version: "2025.08.30", digest: "<sha>" }]
|
||||
feeds:
|
||||
- { name: "nvd", snapshot_date: "2025-08-30", archive_digest: "<sha>" }
|
||||
execution:
|
||||
mode: deterministic
|
||||
random_seed: 314159
|
||||
ordering: lexical
|
||||
heuristics: { binary_scan: true, secrets: false }
|
||||
evidence:
|
||||
files_hashed: 12873
|
||||
samples: [{ path: "/usr/lib/libssl.so.3", sha256: "<sha>" }]
|
||||
outputs:
|
||||
report_digest: "<sha>" # canonical JSON root hash
|
||||
artifacts:
|
||||
- { name: "findings.json", sha256: "<sha>" }
|
||||
signatures:
|
||||
- { scheme: "DSSE", CryptoProfile: "FIPS-140-3", signer: "build-ca@corp" }
|
||||
- { scheme: "DSSE", CryptoProfile: "GOST-2012", signer: "ru-ca@corp" }
|
||||
rekor: { entries: ["<uuid>", ...] } # optional (offline allowed)
|
||||
```
|
||||
|
||||
### CLI & API
|
||||
|
||||
* `stella scan --image reg/app@sha256:... --srm-out srm.yaml --findings findings.json`
|
||||
* `stella replay srm.yaml --out replay.json --assert-digest <sha>`
|
||||
* `POST /v1/srm/replay` → returns `ok`, `replay_report_digest`, `diff` (if any).
|
||||
|
||||
### Determinism Rules
|
||||
|
||||
* Single thread or ordered parallel with stable scheduling; sorted inputs; fixed random seed; pinned rules/feeds/policies from SRM; identical canonicalization routines.
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
* Replaying SRM on a different host returns identical `report_digest`.
|
||||
* If any feed archive differs by 1 bit, replay fails with a precise diff.
|
||||
* SRM size ≤ 25 MB for a typical microservice image (excludes large feed archives, which may be referenced by digest and bundled as a side‑car tar).
|
||||
|
||||
---
|
||||
|
||||
## 2) Policy Engine & Lattice UI
|
||||
|
||||
### Objective
|
||||
|
||||
Turn VEX merging and severity logic into **programmable, testable algebra** with explainability.
|
||||
|
||||
### Model
|
||||
|
||||
* **Domain:** partial order over vulnerability states:
|
||||
`unknown < under_investigation < affected || not_affected < fixed`.
|
||||
Cross‑product with *scope*: `{runtime_path, build_path, optional_path}` and *confidence*: `{low, med, high}`.
|
||||
* **Merge semantics:** monotonic lattice joins; conflict resolution rules prioritized by signed source trust and policy precedence.
|
||||
|
||||
### DSL (sketch)
|
||||
|
||||
```hocon
|
||||
policy "corp-runtime" version "2025.08.15" {
|
||||
sources {
|
||||
trust_order = ["vendor:redhat", "internal:appsec", "public:nvd"]
|
||||
require_signatures = true
|
||||
}
|
||||
|
||||
rules {
|
||||
when vex.statement == "not_affected"
|
||||
and evidence.entrypoint_exposes == false
|
||||
then state := not_affected with confidence := high;
|
||||
|
||||
when package.is_dev_dependency == true
|
||||
then scope := optional_path;
|
||||
|
||||
when cvss >= 9.0 and reachable == true
|
||||
then priority := "block";
|
||||
}
|
||||
|
||||
guards {
|
||||
forbid unsigned_sources;
|
||||
forbid downgrade_of_state_below previous_state;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### UI (“Trust Algebra Studio”)
|
||||
|
||||
* Drag‑and‑drop rule blocks, precedence editor, **simulation mode** on sample SBOM/VEX; **policy unit tests**.
|
||||
* Export **signed** `.lattice.json`; importable into CI.
|
||||
|
||||
### CLI & API
|
||||
|
||||
* `stella policy lint corp-runtime.lattice.json`
|
||||
* `stella policy test --fixtures fixtures/`
|
||||
* `POST /v1/policy/evaluate` → normalized decision + proof trail.
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
* Given same inputs, policy evaluation yields identical decision + proof trail hash.
|
||||
* UI can round‑trip DSL ⇄ JSON with no semantic drift.
|
||||
* Policy pack signature required to run in “enforced” mode.
|
||||
|
||||
---
|
||||
|
||||
## 3) Sovereign Readiness — CryptoProfile + RootPack
|
||||
|
||||
### Objective
|
||||
|
||||
**Drop‑in regional cryptography** (Russia/China/EU/US) with offline operation.
|
||||
|
||||
### CryptoProfile (attached to every signature/attestation)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "GOST-2012@v1",
|
||||
"algorithms": {"sign":"GOST R 34.10-2012","hash":"GOST R 34.11-2012","cipher":"GOST 34.12-2015"},
|
||||
"key_policy": {"curve":"id-tc26-gost-3410-2012-256","hsm_required": true},
|
||||
"time_stamping": {"tsa": "rootpack://ru/tsa1"},
|
||||
"roots": ["rootpack://ru/trustanchors/gost-ca1"]
|
||||
}
|
||||
```
|
||||
|
||||
### RootPack
|
||||
|
||||
* Tarball containing: trust anchors, intermediate CAs, OCSP/CRL snapshots, TSA profiles, policy constraints (e.g., no cross‑sign with foreign roots), and region metadata.
|
||||
* Installed via: `stella rootpack import rootpack_ru_v1.tar.gz`.
|
||||
|
||||
### Dual‑Signing & Guardrails
|
||||
|
||||
* Policy flags like `allow_dual_signing FIPS+GOST`, `forbid_sm2_for_us_exports` (example only).
|
||||
* Enforcement happens at signing time and verification time.
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
* Offline verification using RootPack succeeds; online OCSP disabled per policy.
|
||||
* Mis‑profiled signatures are rejected with explicit reason codes.
|
||||
* Dual‑signed DSSE verifies under both profiles when allowed.
|
||||
|
||||
---
|
||||
|
||||
## 4) Attestation Observability Graph (AOG)
|
||||
|
||||
### Objective
|
||||
|
||||
Make trust **observable**. Expose SLIs/SLOs for cryptographic posture & policy compliance.
|
||||
|
||||
### Data Model
|
||||
|
||||
* Nodes: `{artifact, sbom, policy, vex, srm, signature, rootpack, runtime_instance}`
|
||||
* Edges: `derived_from`, `signed_by`, `evaluated_by`, `replayed_by`, `runs_as`
|
||||
|
||||
### Metrics (OpenTelemetry/Prometheus)
|
||||
|
||||
* `stella_trust_sli{service,env}` = fraction of running pods whose image has a valid SRM‑backed attestation chain under the active policy.
|
||||
* `stella_attestation_latency_seconds` (P50/P95) from build to verified‑ready.
|
||||
* `stella_policy_drift_events_total` (increment when running policy != signed policy).
|
||||
* `stella_exception_without_proof_total` (must be 0).
|
||||
* `stella_replay_success_ratio` (per week).
|
||||
|
||||
**SLO Example**
|
||||
|
||||
* **Trust SLO ≥ 99.9%** measured hourly; error budget resets monthly.
|
||||
|
||||
### Interfaces
|
||||
|
||||
* `stella aog export --format otlp`
|
||||
* `GET /v1/aog/graph?artifactDigest=...` → subgraph JSON (with signed edge proofs).
|
||||
* Grafana dashboards (packaged).
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
* AOG can reconstruct the full trust lineage for any running pod in ≤ 2s (p95) on a 1k‑service cluster.
|
||||
* Metrics cardinality bounded (service/env/policy only).
|
||||
|
||||
---
|
||||
|
||||
## 5) Procurement‑Grade “Trust Statement”
|
||||
|
||||
### Objective
|
||||
|
||||
One **board‑ready** artifact that unifies security posture across vendors; machine‑readable twin for ERP/GRC.
|
||||
|
||||
### Outputs
|
||||
|
||||
* **PDF** (human): signed, watermark, controlled fields for vendor name/version/date, summary graphs, SLOs, exceptions with PCE (proof‑carrying exceptions).
|
||||
* **JSON** (machine): normalized schema below; DSSE‑signed; includes SRM and policy references.
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "trust-statement.stellaops.dev/v1",
|
||||
"vendor": {"name": "Acme","product":"Payments API","version":"1.9.2"},
|
||||
"build": {"image_digest":"sha256:...","srm_digest":"sha256:..."},
|
||||
"policy": {"id":"corp-runtime@2025-08-15","digest":"sha256:..."},
|
||||
"summary": {
|
||||
"trust_sli": 0.9992,
|
||||
"exceptions": 1,
|
||||
"open_findings": {"critical":0,"high":2,"medium":4,"low":12}
|
||||
},
|
||||
"exceptions": [{
|
||||
"id":"EXC-2025-0912",
|
||||
"reason":"not_affected-via-vex",
|
||||
"proof_digest":"sha256:...",
|
||||
"expiry":"2026-01-15"
|
||||
}],
|
||||
"signatures": [{ "CryptoProfile":"FIPS-140-3" }]
|
||||
}
|
||||
```
|
||||
|
||||
### Integrations
|
||||
|
||||
* Push connectors: **SAP Ariba, ServiceNow, Archer, Jira** (webhooks or SFTP in offline flows).
|
||||
* CLI: `stella trust-statement generate --srm srm.yaml --policy corp-runtime.lattice.json --out acme-1.9.2.trust.json --pdf`.
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
* JSON validates against schema; PDF and JSON hashes match the DSSE statement.
|
||||
* ERP ingest POC: Ariba/ServiceNow field mapping validated.
|
||||
|
||||
---
|
||||
|
||||
## 6) Third‑Party Proof Channel
|
||||
|
||||
### Objective
|
||||
|
||||
Create a **publisher ecosystem** for upstream proofs: SBOM, VEX, and **VDR (Vulnerability Derivation Reason)**.
|
||||
|
||||
### Publisher Model
|
||||
|
||||
* **Identity:** publishers obtain a **Publisher Certificate** (could be verified via RootPack‑anchored CA or cross‑signed).
|
||||
* **Submission:** `stella ledger publish --type {sbom|vex|vdr} --artifact <digest> --file proof.json --sign`.
|
||||
* **Moderation & Revocation:** CRL‑like **Proof Revocation List (PRL)** with signed reasons.
|
||||
|
||||
### VDR (schema sketch)
|
||||
|
||||
```json
|
||||
{
|
||||
"schema":"vdr.stellaops.dev/v1",
|
||||
"artifact":"sha256:...",
|
||||
"cve":"CVE-2025-12345",
|
||||
"claim":"not_affected",
|
||||
"method":"entrypoint_unreachable|abi_mismatch|dead_code",
|
||||
"evidence_refs":[{"type":"symbol_map","digest":"sha256:..."}],
|
||||
"publisher":"redhat://rhel",
|
||||
"signatures":[...]
|
||||
}
|
||||
```
|
||||
|
||||
### Consumption
|
||||
|
||||
* Policies can **prioritize** publisher channels by trust level.
|
||||
* AOG shows which proofs originated from which publishers.
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
* At least one upstream (e.g., base image vendor) can publish and your policy can consume & rank it.
|
||||
* PRL revokes a proof and AOG reflects the change within 5 minutes.
|
||||
|
||||
---
|
||||
|
||||
## 7) Zastava — differential SBOM + AI enrichment scheduler
|
||||
|
||||
### Objective
|
||||
|
||||
Produce **entrypoint‑aware differential SBOMs** and continually **re‑enrich** new/old SBOMs with AI context and exposure‑aware prioritization.
|
||||
|
||||
### Concepts
|
||||
|
||||
* **dSBOM:** SBOM that reflects effective dependency set for a specific `ENTRYPOINT/CMD` and runtime flags (e.g., `--server.urls`, `DOTNET_...`).
|
||||
* **Scheduler:** rescans **old SBOMs** when: (a) new CVE feeds arrive, (b) new VEX/VDR appear, (c) policy changes, or (d) AI models learn new exploitability signals.
|
||||
|
||||
### Pipeline
|
||||
|
||||
1. **Static slice:** infer reachable packages from entrypoint (e.g., `.NET Kestrel` vs CLI tool).
|
||||
2. **Runtime slice (optional):** collect process tree, open sockets, and imported modules at startup in a **shadow run** or mirrored traffic.
|
||||
3. **Diff:** `dSBOM = SBOM ∩ (static_reachable ∪ runtime_observed)`.
|
||||
4. **AI Enrichment:** Zastava annotates each finding with *context weights* (exposed/not exposed, network scope, RBAC, secrets proximity).
|
||||
5. **Plan:** produce PRs (Dockerfile base bump, package pin, k8s Service change).
|
||||
6. **Scheduler:**
|
||||
|
||||
* `stella zastava schedule --query 'service=payments AND env=prod' --interval 6h`
|
||||
* Triggers re‑evaluation and emits updated SRM + Trust deltas.
|
||||
|
||||
### dSBOM format (addon)
|
||||
|
||||
```json
|
||||
{
|
||||
"schema":"cyclonedx+stella-diff@1.0",
|
||||
"base_sbom":"sha256:...",
|
||||
"entrypoint": ["/app/bin/Release/net8.0/app.dll"],
|
||||
"cmd": ["--urls","http://127.0.0.1:8080"],
|
||||
"static_reachable": ["pkg:nuget/Kestrel@*", "pkg:nuget/System.Data@*"],
|
||||
"runtime_observed": ["pkg:rpm/openssl@3.0.9"],
|
||||
"excluded_paths": ["/usr/share/docs/**"],
|
||||
"digest":"sha256:..."
|
||||
}
|
||||
```
|
||||
|
||||
### Kestrel example (priority logic)
|
||||
|
||||
* If Kestrel present but Service is `ClusterIP` and no Ingress, **deprioritize**; if `LoadBalancer`/`NodePort` with 0‑RTT TLS disabled, **prioritize**.
|
||||
* Zastava produces an **explainable card**: “Priority lowered due to non‑exposed runtime path; evidence: `kubectl get svc`, `netstat`, policy rule #42.”
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
* Changing `ENTRYPOINT` produces a different, signed dSBOM and updated priorities.
|
||||
* Scheduler updates stale SBOMs and issues signed deltas without network access (when RootPacks + feed mirrors are available).
|
||||
|
||||
---
|
||||
|
||||
## Cross‑Cutting Security & Compliance
|
||||
|
||||
* **Sanctions & Guardrails:** per‑profile constraints (e.g., forbid dual‑signing across certain jurisdictions). Policy‑enforced at sign/verify time.
|
||||
* **HSM Integrations:** PKCS#11 providers for each profile (FIPS, GOST, SM2).
|
||||
* **Data handling:** SRMs and Trust Statements may contain paths and hashes; optional redaction profiles for vendor sharing.
|
||||
|
||||
---
|
||||
|
||||
## Interfaces Summary (CLI)
|
||||
|
||||
```bash
|
||||
# Scans / Replay
|
||||
stella scan --image <digest> --srm-out srm.yaml
|
||||
stella replay srm.yaml --assert-digest <sha>
|
||||
|
||||
# Policy & Lattice
|
||||
stella policy lint corp.lattice.json
|
||||
stella policy test --fixtures fixtures/
|
||||
stella policy sign --profile FIPS-140-3
|
||||
|
||||
# Crypto Sovereign
|
||||
stella rootpack import rootpack_ru_v1.tar.gz
|
||||
stella attest sign --profile GOST-2012 --in srm.yaml
|
||||
stella attest verify --profiles GOST-2012,FIPS-140-3
|
||||
|
||||
# AOG
|
||||
stella aog export --format otlp
|
||||
stella aog graph --artifact <digest>
|
||||
|
||||
# Trust Statement
|
||||
stella trust-statement generate --srm srm.yaml --policy corp.lattice.json --pdf out.pdf --json out.json
|
||||
|
||||
# Third-Party Proof Channel
|
||||
stella ledger publish --type vdr --artifact <digest> --file vdr.json --sign
|
||||
stella ledger revoke --id <proof-id> --reason "superseded"
|
||||
|
||||
# Zastava
|
||||
stella zastava diff-sbom --image <digest> --entrypoint "<cmd>" --out dsbom.json
|
||||
stella zastava enrich --sbom dsbom.json --findings findings.json
|
||||
stella zastava schedule --query 'env=prod' --interval 6h
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics (per pillar)
|
||||
|
||||
* **SRM:** ≥ 99% of production images have SRM attached; **Replay Success Ratio** ≥ 0.99 weekly.
|
||||
* **Policy/Lattice:** 100% of exceptions carry proof; policy test coverage ≥ 90% on top CVE classes.
|
||||
* **Sovereign:** RootPacks for RU/CN/EU/US verified; dual‑signing working in CI; offline verification median < 200 ms.
|
||||
* **AOG:** Trust SLO ≥ 99.9%; lineage lookup p95 ≤ 2s.
|
||||
* **Trust Statement:** Accepted by at least one ERP (pilot); generation time ≤ 15s.
|
||||
* **Third‑Party Channel:** ≥ 3 upstream publishers integrated; PRL revocations flow to AOG within 5 minutes.
|
||||
* **Zastava:** dSBOM reduces non‑reachable high/critical findings by ≥ 35% without raising exposure incidents.
|
||||
|
||||
---
|
||||
|
||||
## Risks & Mitigations
|
||||
|
||||
* **Crypto complexity:** profile misuse → strict guardrails + default safe profiles, strong linting.
|
||||
* **Cardinality/telemetry blow‑ups:** AOG label hygiene + sampling.
|
||||
* **Vendor adoption (Proof Channel):** seed with your own base images and internal frameworks; provide SDKs and reference publishers.
|
||||
* **Determinism regressions:** CI runs replay tests on golden SRMs; any drift fails the build.
|
||||
|
||||
---
|
||||
|
||||
## 90‑Day Moat‑First Milestones
|
||||
|
||||
1. **SRM v0.1**: schema, deterministic executor, CLI replay, golden tests.
|
||||
2. **Policy Engine MVP**: DSL + evaluator + UI simulation; policy unit tests; signed policy packs.
|
||||
3. **CryptoProfile/RootPack MVP**: FIPS + GOST working; dual‑signing; offline verify.
|
||||
4. **AOG MVP**: lineage service + OTLP exporter + Grafana pack; Trust SLI.
|
||||
5. **Trust Statement MVP**: JSON + PDF; ServiceNow ingest POC.
|
||||
6. **Proof Channel alpha**: publisher identity + VDR schema + local ledger; PRL.
|
||||
7. **Zastava α**: `diff-sbom` + exposure heuristics for `.NET Kestrel`; scheduler with offline mirrors.
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user