feat: Document completed tasks for KMS, Cryptography, and Plugin Libraries

- Added detailed task completion records for KMS interface implementation and CLI support for file-based keys. - Documented security enhancements including Argon2id password hashing, audit event contracts, and rate limiting configurations. - Included scoped service support and integration updates for the Plugin platform, ensuring proper DI handling and testing coverage.
2025-10-31 14:33:05 +02:00
parent 240e8ff25d
commit 9e5e958d42
312 changed files with 6399 additions and 3319 deletions
--- a/docs/events/README.md
+++ b/docs/events/README.md
@@ -35,7 +35,7 @@ Additive payload changes (new optional fields) can stay within the same version.
 | `payload` | `object` | Event-specific body; schemas embed the canonical report and DSSE envelope. |
 | `attributes` | `object` | Optional metadata bag (`string` keys/values) for downstream correlation. |

-For Scanner orchestrator events, `links` include console and API deep links (`ui`, `report`, and `policy`) plus an optional `attestation` URL when a DSSE envelope is present. See [`orchestrator-scanner-events.md`](orchestrator-scanner-events.md) for details.
+For Scanner orchestrator events, `links` include console and API deep links (`report.ui`, `report.api`, etc.) plus optional attestation references when a DSSE envelope is present. See [`orchestrator-scanner-events.md`](orchestrator-scanner-events.md) for details.

 ### Legacy Redis envelope
 | Field | Type | Notes |
--- a/docs/events/orchestrator-scanner-events.md
+++ b/docs/events/orchestrator-scanner-events.md
@@ -35,10 +35,12 @@ Emitted once a signed report is persisted and attested. Payload highlights:
 - `reportId` / `scanId` — identifiers for the persisted report and originating scan. Until Scan IDs are surfaced by the API, `scanId` mirrors `reportId` so downstream correlators can stabilise on a single key.
 - **Attributes:** `reportId`, `policyRevisionId`, `policyDigest`, `verdict` — pre-sorted for deterministic routing.
 - **Links:**
-  - `ui` → `/ui/reports/{reportId}` on the current host.
-  - `report` → `{apiBasePath}/{reportsSegment}/{reportId}` (defaults to `/api/v1/reports/{reportId}`).
-  - `policy` → `{apiBasePath}/{policySegment}/revisions/{revisionId}` when a revision is present.
-  - `attestation` → `/ui/attestations/{reportId}` when a DSSE envelope is included.
+  - `report.ui` → `/ui/reports/{reportId}` on the current host.
+  - `report.api` → `{apiBasePath}/{reportsSegment}/{reportId}` (defaults to `/api/v1/reports/{reportId}`).
+  - `policy.ui` → `/ui/policy/revisions/{revisionId}` when a revision is present.
+  - `policy.api` → `{apiBasePath}/{policySegment}/revisions/{revisionId}` when a revision is present.
+  - `attestation.ui` → `/ui/attestations/{reportId}` when a DSSE envelope is included.
+  - `attestation.api` → `{apiBasePath}/{reportsSegment}/{reportId}/attestation` when a DSSE envelope is included.
 - `imageDigest` — OCI image digest associated with the analysis.
 - `generatedAt` — report generation timestamp (ISO-8601 UTC).
 - `verdict` — `pass`, `warn`, or `fail` after policy evaluation.
@@ -59,7 +61,7 @@ Emitted after scan execution finishes (success or policy failure). Payload highl

 - `reportId` / `scanId` / `imageDigest` — identifiers mirroring the report-ready event. As with the report-ready payload, `scanId` currently mirrors `reportId` as a temporary shim.
 - **Attributes:** `reportId`, `policyRevisionId`, `policyDigest`, `verdict`.
- **Links:** same as above (`ui`, `report`, `policy`) with `attestation` populated when DSSE metadata exists.
+- **Links:** same as above (`report.*`, `policy.*`) with `attestation.*` populated when DSSE metadata exists.
 - `verdict`, `summary`, `delta`, `policy` — same semantics as above.
 - `findings` — array of surfaced findings with `id`, `severity`, optional `cve`, `purl`, and `reachability`.
 - `links`, `dsse`, `report` — same structure as §2.1 (allows Notifier to reuse signatures).
--- a/docs/events/samples/scanner.event.report.ready@1.sample.json
+++ b/docs/events/samples/scanner.event.report.ready@1.sample.json
@@ -45,12 +45,20 @@
      "digest": "digest-123",
      "revisionId": "rev-42"
    },
-  "links": {
-    "ui": "https://scanner.example/ui/reports/report-abc",
-    "report": "https://scanner.example/api/v1/reports/report-abc",
-    "policy": "https://scanner.example/api/v1/policy/revisions/rev-42",
-    "attestation": "https://scanner.example/ui/attestations/report-abc"
-  },
+  "links": {
+    "report": {
+      "ui": "https://scanner.example/ui/reports/report-abc",
+      "api": "https://scanner.example/api/v1/reports/report-abc"
+    },
+    "policy": {
+      "ui": "https://scanner.example/ui/policy/revisions/rev-42",
+      "api": "https://scanner.example/api/v1/policy/revisions/rev-42"
+    },
+    "attestation": {
+      "ui": "https://scanner.example/ui/attestations/report-abc",
+      "api": "https://scanner.example/api/v1/reports/report-abc/attestation"
+    }
+  },
    "dsse": {
      "payloadType": "application/vnd.stellaops.report+json",
      "payload": "eyJyZXBvcnRJZCI6InJlcG9ydC1hYmMiLCJpbWFnZURpZ2VzdCI6InNoYTI1NjpmZWVkZmFjZSIsImdlbmVyYXRlZEF0IjoiMjAyNS0xMC0xOVQxMjozNDo1NiswMDowMCIsInZlcmRpY3QiOiJibG9ja2VkIiwicG9saWN5Ijp7InJldmlzaW9uSWQiOiJyZXYtNDIiLCJkaWdlc3QiOiJkaWdlc3QtMTIzIn0sInN1bW1hcnkiOnsidG90YWwiOjEsImJsb2NrZWQiOjEsIndhcm5lZCI6MCwiaWdub3JlZCI6MCwicXVpZXRlZCI6MH0sInZlcmRpY3RzIjpbeyJmaW5kaW5nSWQiOiJmaW5kaW5nLTEiLCJzdGF0dXMiOiJCbG9ja2VkIiwic2NvcmUiOjQ3LjUsInNvdXJjZVRydXN0IjoiTlZEIiwicmVhY2hhYmlsaXR5IjoicnVudGltZSJ9XSwiaXNzdWVzIjpbXX0=",
--- a/docs/events/samples/scanner.event.scan.completed@1.sample.json
+++ b/docs/events/samples/scanner.event.scan.completed@1.sample.json
@@ -51,12 +51,20 @@
        "reachability": "runtime"
      }
    ],
-    "links": {
-      "ui": "https://scanner.example/ui/reports/report-abc",
-      "report": "https://scanner.example/api/v1/reports/report-abc",
-      "policy": "https://scanner.example/api/v1/policy/revisions/rev-42",
-      "attestation": "https://scanner.example/ui/attestations/report-abc"
-    },
+    "links": {
+      "report": {
+        "ui": "https://scanner.example/ui/reports/report-abc",
+        "api": "https://scanner.example/api/v1/reports/report-abc"
+      },
+      "policy": {
+        "ui": "https://scanner.example/ui/policy/revisions/rev-42",
+        "api": "https://scanner.example/api/v1/policy/revisions/rev-42"
+      },
+      "attestation": {
+        "ui": "https://scanner.example/ui/attestations/report-abc",
+        "api": "https://scanner.example/api/v1/reports/report-abc/attestation"
+      }
+    },
    "dsse": {
      "payloadType": "application/vnd.stellaops.report+json",
      "payload": "eyJyZXBvcnRJZCI6InJlcG9ydC1hYmMiLCJpbWFnZURpZ2VzdCI6InNoYTI1NjpmZWVkZmFjZSIsImdlbmVyYXRlZEF0IjoiMjAyNS0xMC0xOVQxMjozNDo1NiswMDowMCIsInZlcmRpY3QiOiJibG9ja2VkIiwicG9saWN5Ijp7InJldmlzaW9uSWQiOiJyZXYtNDIiLCJkaWdlc3QiOiJkaWdlc3QtMTIzIn0sInN1bW1hcnkiOnsidG90YWwiOjEsImJsb2NrZWQiOjEsIndhcm5lZCI6MCwiaWdub3JlZCI6MCwicXVpZXRlZCI6MH0sInZlcmRpY3RzIjpbeyJmaW5kaW5nSWQiOiJmaW5kaW5nLTEiLCJzdGF0dXMiOiJCbG9ja2VkIiwic2NvcmUiOjQ3LjUsInNvdXJjZVRydXN0IjoiTlZEIiwicmVhY2hhYmlsaXR5IjoicnVudGltZSJ9XSwiaXNzdWVzIjpbXX0=",
--- a/docs/events/scanner.event.report.ready@1.json
+++ b/docs/events/scanner.event.report.ready@1.json
@@ -122,16 +122,15 @@
          "type": "object",
          "description": "Policy revision metadata surfaced alongside the report."
        },
-        "links": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "ui": {"type": "string", "format": "uri"},
-            "report": {"type": "string", "format": "uri"},
-            "policy": {"type": "string", "format": "uri"},
-            "attestation": {"type": "string", "format": "uri"}
-          }
-        },
+        "links": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "report": {"$ref": "#/definitions/linkTarget"},
+            "policy": {"$ref": "#/definitions/linkTarget"},
+            "attestation": {"$ref": "#/definitions/linkTarget"}
+          }
+        },
        "dsse": {
          "type": "object",
          "additionalProperties": false,
@@ -161,4 +160,14 @@
      }
    }
  }
-}
+  "definitions": {
+    "linkTarget": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ui": {"type": "string", "format": "uri"},
+        "api": {"type": "string", "format": "uri"}
+      }
+    }
+  }
+}
--- a/docs/events/scanner.event.scan.completed@1.json
+++ b/docs/events/scanner.event.scan.completed@1.json
@@ -132,16 +132,15 @@
            }
          }
        },
-        "links": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "ui": {"type": "string", "format": "uri"},
-            "report": {"type": "string", "format": "uri"},
-            "policy": {"type": "string", "format": "uri"},
-            "attestation": {"type": "string", "format": "uri"}
-          }
-        },
+        "links": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "report": {"$ref": "#/definitions/linkTarget"},
+            "policy": {"$ref": "#/definitions/linkTarget"},
+            "attestation": {"$ref": "#/definitions/linkTarget"}
+          }
+        },
        "dsse": {
          "type": "object",
          "additionalProperties": false,
@@ -171,4 +170,14 @@
      }
    }
  }
-}
+  "definitions": {
+    "linkTarget": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ui": {"type": "string", "format": "uri"},
+        "api": {"type": "string", "format": "uri"}
+      }
+    }
+  }
+}