up

docs/modules/concelier/feeds/icscisa-kisa.md

@@ -1,4 +1,4 @@
-# ICSCISA / KISA Feed Remediation Plan (v0.1 · 2025-11-19)
+# ICSCISA / KISA Feed Remediation Plan (v0.2 - 2025-12-07)
 
 ## Purpose
 Define a minimal, actionable plan to refresh overdue ICSCISA and KISA connectors, restore provenance freshness, and publish normalized payload fields for downstream Advisory AI and Concelier consumers.
@@ -11,28 +11,30 @@ Define a minimal, actionable plan to refresh overdue ICSCISA and KISA connectors
 ## Scope & cadence
 - Feeds: ICSCISA, KISA (security advisories)
 - Refresh cadence: weekly pull; publish hashlist and timestamps per run
-- Staleness budget: <14 days; alert if exceeded
+- Staleness budget: <14 days; alert if exceeded; flag any run skipped or retried
+- Execution window (v0.2): first refreshed run by 2025-12-10; weekly thereafter
 
 ## Deliverables (for PREP-FEEDCONN-ICS-KISA-PLAN)
 1) **Provenance refresh SOP**
-   - Mirror source URLs to internal cache
-   - Record `source_url`, `fetched_at` (UTC), `sha256`, `signature` (if present)
-   - Store run log under `out/feeds/icscisa-kisa/<YYYYMMDD>/fetch.log`
+   - Mirror source URLs to internal cache before parsing; record request/response headers.
+   - Record per-advisory `source_url`, `fetched_at` (UTC), `sha256`, `signature` (if present), and `run_id`.
+   - Store run log under `out/feeds/icscisa-kisa/<YYYYMMDD>/fetch.log` with start/end time, HTTP status histogram, and retry counts.
 2) **Normalized payload fields**
-   - `advisory_id`, `title`, `summary`, `published`, `updated`, `severity` (pass-through), `cvss` (if provided), `cwe`, `affected_products` (list), `references` (list of URL strings), `signature` (object or null)
-   - Preserve source values; no inference or merging
+   - Required fields: `advisory_id`, `title`, `summary`, `published`, `updated`, `severity` (pass-through), `cvss` (if provided), `cwe`, `affected_products` (list), `references` (list of URL strings), `signature` (object or null).
+   - Preserve source values; no inference or merging; emit deterministic field ordering in NDJSON.
 3) **Backlog cleanup**
-   - Reprocess last 60 days; compare hash to prior ingests; flag changed advisories
-   - Emit delta report (`out/feeds/icscisa-kisa/<YYYYMMDD>/delta.json`): added/updated/removed ids, counts
+   - Reprocess last 60 days; compare hash to prior ingests; flag changed advisories.
+   - Emit delta report (`out/feeds/icscisa-kisa/<YYYYMMDD>/delta.json`) with `{run_id, added[], updated[], removed[], totals}`; include sha256 of prior vs current payload when changed.
 4) **Provenance note**
-   - Publish `docs/modules/concelier/feeds/icscisa-kisa-provenance.md` with current signing keys/fingerprints, expected headers, and fallback when signatures missing
+   - Publish `docs/modules/concelier/feeds/icscisa-kisa-provenance.md` with current signing keys/fingerprints, expected headers, and fallback when signatures missing.
+   - Note any unsigned advisories per run with `skip_reason`, and capture verification tooling used.
 5) **Next review date**
-   - Set to 2025-12-03 (two-week check) and capture SIG verification status
+   - Set to 2025-12-21 (two-week check from v0.2) and capture SIG verification status + open deltas.
 
-## Actions & timeline
-- T0 (2025-11-19): adopt SOP + field map; create delta report template
-- T0+2d (2025-11-21): run backlog reprocess, publish artefacts + hashes
-- T0+14d (2025-12-03): review staleness, adjust cadence if needed
+## Actions & timeline (v0.2 refresh)
+- T0 (2025-12-08): adopt SOP + field map; create delta report template; preflight cache paths.
+- T0+2d (2025-12-10): run backlog reprocess, publish artefacts + hashes for both feeds; capture unsigned counts and retry reasons.
+- T0+14d (2025-12-21): review staleness, adjust cadence if needed; reset review date and owners.
 
 ## Artefact locations
 - Normalized advisories: `out/feeds/icscisa-kisa/<YYYYMMDD>/advisories.ndjson`
@@ -41,6 +43,6 @@ Define a minimal, actionable plan to refresh overdue ICSCISA and KISA connectors
 - Provenance note: `docs/modules/concelier/feeds/icscisa-kisa-provenance.md`
 
 ## Risks & mitigations
-- Source downtime → mirror last good snapshot; retry daily for 3 days.
-- Missing signatures → record `signature=null`, log `skip_reason` in provenance note; do not infer validity.
-- Schema drift → treat as new fields, store raw, add to field map after review (no drop).
+- Source downtime -> mirror last good snapshot; retry daily for 3 days.
+- Missing signatures -> record `signature=null`, log `skip_reason` in provenance note; do not infer validity.
+- Schema drift -> treat as new fields, store raw, add to field map after review (no drop).

docs/modules/policy/cvss-v4.md

@@ -61,3 +61,70 @@ Source advisory: `docs/product-advisories/25-Nov-2025 - Add CVSS v4.0 Score Re
 - Store conversion metadata for v3.1 sources.
 - Verify evidence CAS/DSSE on ingest; fail closed.
 - Expose metrics/alerts listed above.
+
+## Receipt model (API shape)
+- `receiptId`, `schemaVersion`, `format`, `vulnerabilityId`, `tenantId`, `createdAt/by`, `modifiedAt/by`.
+- Metric inputs: `baseMetrics`, optional `threatMetrics` and `environmentalMetrics`, optional `supplementalMetrics`.
+- Computed outputs: `scores` (base/threat/environmental/full plus `effectiveScore` and `effectiveScoreType`), `vectorString`, `severity`.
+- Policy link: `policyRef { policyId, version, hash, activatedAt }` plus `inputHash` (JCS + SHA-256) and optional `exportHash`.
+- Evidence: `evidence[]` (type, uri, description, source, collectedAt, dsseRef, isAuthoritative, isRedacted, verifiedAt, retentionClass).
+- Attestation + history: `attestationRefs[]` (DSSE envelopes), `history[]` (field, previousValue, newValue, actor, reason, referenceUri, when), `amendsReceiptId`, `supersedesReceiptId`, `isActive`.
+
+## Gateway API (Policy Engine via Gateway)
+- Base path: `/api/cvss` (Policy Gateway). Scopes: `policy.run` for create/amend; `findings.read` for read/history/policies.
+- Endpoints:
+  - `POST /api/cvss/receipts` – Create a receipt and optional DSSE envelope.
+  - `GET /api/cvss/receipts/{id}` – Fetch the latest receipt with scores, evidence, and hashes.
+  - `PUT /api/cvss/receipts/{id}/amend` – Append a history entry (e.g., policy change, evidence fix); re-sign when `signingKey` is provided.
+  - `GET /api/cvss/receipts/{id}/history` – Return ordered history entries for the receipt.
+  - `GET /api/cvss/policies` – List available `CvssPolicy` documents (id/version/hash/effective window).
+
+**Create receipt (minimal example)**
+
+```
+POST /api/cvss/receipts
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "vulnerabilityId": "CVE-2025-1234",
+  "policy": {
+    "policyId": "default",
+    "version": "1.0.0",
+    "name": "Default CVSS policy",
+    "effectiveFrom": "2025-12-01T00:00:00Z",
+    "hash": "sha256:..."
+  },
+  "baseMetrics": { "av": "Network", "ac": "Low", "at": "None", "pr": "None", "ui": "None", "vc": "High", "vi": "High", "va": "High", "sc": "High", "si": "High", "sa": "High" },
+  "environmentalMetrics": { "cr": "High", "ir": "High", "ar": "Medium" },
+  "signingKey": { "keyId": "cvss-dev", "store": "local" },
+  "createdBy": "cli"
+}
+```
+
+**Response 200 (abridged)**
+
+```json
+{
+  "receiptId": "cvss-20251207-01",
+  "vectorString": "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:H/SI:H/SA:H/CR:H/IR:H/AR:M",
+  "scores": { "baseScore": 9.3, "threatScore": 9.3, "environmentalScore": 9.1, "fullScore": 9.1, "effectiveScore": 9.1, "effectiveScoreType": "Environmental" },
+  "severity": "Critical",
+  "policyRef": { "policyId": "default", "version": "1.0.0", "hash": "sha256:..." },
+  "inputHash": "sha256:...",
+  "attestationRefs": ["dsse:stella.ops/cvssReceipt@v1/sha256:..."],
+  "evidence": [],
+  "history": []
+}
+```
+
+## CLI and UI usage
+- CLI (`stella cvss ...` via `src/Cli/StellaOps.Cli`):
+  - `stella cvss score --vuln CVE-2025-1234 --policy-file cvss-policy.json --vector CVSS:4.0/AV:N/... [--json]`
+  - `stella cvss show <receiptId> [--json]`
+  - `stella cvss history <receiptId> [--json]`
+  - `stella cvss export <receiptId> --format json --out cvss-receipt.json`
+  - Uses Policy Gateway `/api/cvss/...` endpoints, enforces tenant scoping via `--tenant`/profile, and reuses `CvssV4Engine` locally for vector parsing.
+- Console (`src/Web/StellaOps.Web`):
+  - Route `/cvss/receipts/:receiptId` renders a receipt viewer with score badge, vector summary, and tabs for Base/Threat/Environmental/Evidence/Policy/History.
+  - Export and "Recalculate with my env" flows reuse the same receipt payload; UI expects deterministic ordering and stable hashes.