up

docs/modules/attestor/airgap.md

@@ -0,0 +1,42 @@
+# Attestor Air-Gap Guide (DOCS-ATTEST-75-001)
+
+Last updated: 2025-11-25
+
+## Goal
+Run attestation verification entirely offline while keeping determinism and tenant safety intact.
+
+## Inputs & prerequisites
+- **Trust bundle**: DSSE signing keys + certificate chains packaged under `out/offline/attestor/trust-bundle/` (hash manifest included).
+- **Transparency checkpoints (optional)**: Rekor or equivalent checkpoints mirrored to `out/offline/attestor/transparency/`.
+- **Authority scopes**: `attest:verify` and tenant scoping (`X-Stella-Tenant`) are still required even in sealed mode.
+- **No external calls**: Outbound network must be disabled; attestor uses only the provided bundles.
+
+## Configuration (sealed mode)
+Set the following environment flags on WebService/Worker:
+- `Attestor__Offline__Enabled=true`
+- `Attestor__TrustBundlePath=/app/offline/trust-bundle`
+- `Attestor__Transparency__CheckpointPath=/app/offline/transparency` (optional)
+- `Attestor__Verification__DisableHttpFetch=true`
+
+Mount the bundle directories read-only; keep hashes alongside the payloads for audit.
+
+## Verification flow (offline)
+1. Client submits a DSSE envelope to `/api/v1/attestations/verify` with tenant header.
+2. Service loads keys from the offline trust bundle; issuer lookup is strictly local.
+3. If transparency data is present, the server verifies inclusion against the mirrored checkpoint; otherwise it records `transparency=skipped` in the rationale.
+4. Result is returned with deterministic fields: `subject`, `statementDigest`, `verified=true|false`, `transparency=passed|skipped|failed`, `rationale[]`.
+
+## Determinism safeguards
+- All hashes are lowercase hex; timestamps are UTC ISO-8601.
+- Sorting: multiple statements are ordered by `subject` then `statementDigest`.
+- No network retries or clock drift compensation; rely on bundle timestamps.
+
+## Operations checklist
+- [ ] Refresh trust bundle hashes before each deploy; compare against signed manifest.
+- [ ] Rotate keys by replacing the bundle atomically; restart workers to pick up changes.
+- [ ] Record verification results in the delivery ledger for replay/audit.
+
+## Related docs
+- `docs/modules/attestor/overview.md`
+- `docs/modules/attestor/keys-and-issuers.md`
+- `docs/modules/attestor/transparency.md`

docs/modules/excititor/operations/graph-linkouts-implementation.md

@@ -1,4 +1,4 @@
-# Excititor · Graph Linkouts & Overlays — Implementation Notes (Graph 21-001/002/005)
+# Excititor · Graph Linkouts & Overlays — Implementation Notes (Graph 21-001/002/005/24-101/24-102)
 
 - **Date:** 2025-11-21
 - **Scope:** EXCITITOR-GRAPH-21-001, EXCITITOR-GRAPH-21-002, EXCITITOR-GRAPH-21-005
@@ -14,6 +14,14 @@
    - `GET /v1/graph/overlays?purl=<purl>&purl=<purl>&includeJustifications=true|false`  
    - Response per PURL: `summary` counts (`open`, `not_affected`, `under_investigation`, `no_statement`), `latestModifiedAt`, `justifications[]` (unique, sorted), `provenance` (`sources[]`, `lastEvidenceHash`), `cached`, `cacheAgeMs`.
 
+3) **Status summaries (24-101)**  
+   - `GET /v1/graph/status?purl=<purl>&purl=<purl>`  
+   - Response mirrors overlay summaries but omits justification payloads; includes `sources[]`, `lastEvidenceHash`, `cached`, `cacheAgeMs`. Intended for Vuln Explorer status colouring.
+
+4) **Batch observations for tooltips (24-102)**  
+   - `GET /v1/graph/observations?purl=<purl>[&purl=...]&includeJustifications=true|false[&limitPerPurl=50][&cursor=<base64>]`  
+   - Response per PURL: ordered `observations[]` (`observationId`, `advisoryId`, `status`, `justification?`, `providerId`, `modifiedAt`, `evidenceHash`, `dsseEnvelopeHash?`) plus `truncated`; top-level `nextCursor`, `hasMore` enable paging. Limits enforced per PURL and globally.
+
 ## Storage & Indexes (21-005)
 - `vex_observations` indexes:  
   - `{ tenant: 1, component.purl: 1, advisoryId: 1, source: 1, modifiedAt: -1 }`  
@@ -28,6 +36,8 @@
 - `excititor:graph:overlayTtlSeconds` (default 300)
 - `excititor:graph:maxPurls` (default 500)
 - `excititor:graph:maxAdvisoriesPerPurl` (default 200)
+- `excititor:graph:maxTooltipItemsPerPurl` (default 50)
+- `excititor:graph:maxTooltipTotal` (default 1000)
 
 ## Telemetry
 - Counter `excititor.graph.linkouts.requests` tags: `tenant`, `includeJustifications`, `includeProvenance`.

docs/modules/excititor/operations/vex-raw-validator.md

@@ -0,0 +1,31 @@
+# Excititor · VEX Raw Collection Validator (AOC-19-001/002)
+
+- **Date:** 2025-11-25
+- **Scope:** EXCITITOR-STORE-AOC-19-001 / 19-002
+- **Working directory:** `src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo`
+
+## What shipped
+- `$jsonSchema` validator applied to `vex_raw` (migration `20251125-vex-raw-json-schema`) with `validationAction=warn`, `validationLevel=moderate` to surface contract violations without impacting ingestion.
+- Schema lives at `docs/modules/excititor/schemas/vex_raw.schema.json` (mirrors Mongo validator fields: digest/id, providerId, format, sourceUri, retrievedAt, optional content/GridFS object id, metadata strings).
+- Migration is auto-registered in DI; hosted migration runner applies it on service start. New collections created with the validator if missing.
+
+## How to run (online/offline)
+1) Ensure Excititor WebService/Worker starts with Mongo credentials that allow `collMod`.
+2) Validator applies automatically via migration runner. To force manually:
+   ```bash
+   mongosh "$MONGO_URI" --eval 'db.runCommand({collMod:"vex_raw", validator:'$(cat docs/modules/excititor/schemas/vex_raw.schema.json)', validationAction:"warn", validationLevel:"moderate"})'
+   ```
+3) Offline kit: bundle `docs/modules/excititor/schemas/vex_raw.schema.json` with release artifacts; ops can apply via `mongosh` or `mongo` offline against snapshots.
+
+## Rollback / relax
+- To relax validation (e.g., hotfix window): `db.runCommand({collMod:"vex_raw", validator:{}, validationAction:"warn", validationLevel:"off"})`.
+- Reapplying the migration restores the schema.
+
+## Compatibility notes
+- Validator keeps `additionalProperties=true` to avoid blocking future fields; required set is minimal to guarantee provenance + content hash presence.
+- Action is `warn` to avoid breaking existing feeds; flip to `error` once downstream datasets are clean.
+
+## Acceptance
+- Contract + schema captured.
+- Migration in code and auto-applied.
+- Rollback path documented.

docs/modules/excititor/schemas/vex_raw.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://stellaops.dev/schemas/excititor/vex_raw.schema.json",
+  "title": "Excititor VEX Raw Document",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["_id", "providerId", "format", "sourceUri", "retrievedAt", "digest"],
+  "properties": {
+    "_id": {
+      "type": "string",
+      "description": "Content-addressed digest; equals `digest`."
+    },
+    "providerId": { "type": "string", "minLength": 1 },
+    "format": { "type": "string", "enum": ["csaf", "cyclonedx", "openvex"] },
+    "sourceUri": { "type": "string", "minLength": 1 },
+    "retrievedAt": { "type": "string", "format": "date-time" },
+    "digest": { "type": "string", "minLength": 32 },
+    "content": {
+      "oneOf": [
+        { "type": "string", "contentEncoding": "base64" },
+        { "type": "string" }
+      ],
+      "description": "Inline payload if below GridFS threshold; may be empty when stored in GridFS."
+    },
+    "gridFsObjectId": {
+      "anyOf": [
+        { "type": "string" },
+        { "type": "null" }
+      ]
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    }
+  }
+}