Update

2025-10-21 18:54:26 +03:00
parent 791e12baab
commit cfaea5efd9
50 changed files with 3027 additions and 596 deletions
--- a/docs/ARCHITECTURE_EXCITITOR_MIRRORS.md
+++ b/docs/ARCHITECTURE_EXCITITOR_MIRRORS.md
@@ -44,7 +44,26 @@ Excititor:
              vulnId: CVE-2025-0001
 ```

-### Field reference
+### Root settings
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `outputRoot` | – | Filesystem root where mirror artefacts are written. Defaults to the Excititor file-system artifact store root when omitted. |
+| `directoryName` | – | Optional subdirectory created under `outputRoot`; defaults to `mirror`. |
+| `targetRepository` | – | Hint propagated to manifests/index files indicating the operator-visible location (for example `s3://mirror/excititor`). |
+| `signing` | – | Bundle signing configuration. When enabled, the exporter emits a detached JWS (`bundle.json.jws`) alongside each domain bundle. |
+
+`signing` supports the following fields:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `enabled` | – | Toggles detached signing for domain bundles. |
+| `algorithm` | – | Signing algorithm identifier (default `ES256`). |
+| `keyId` | ✅ (when `enabled`) | Signing key identifier resolved via the configured crypto provider registry. |
+| `provider` | – | Optional provider hint when multiple registries are available. |
+| `keyPath` | – | Optional PEM path used to seed the provider when the key is not already loaded. |
+
+### Domain field reference

 | Field | Required | Description |
 | --- | --- | --- |
@@ -53,13 +72,13 @@ Excititor:
 | `requireAuthentication` | – | When `true` the service enforces that the caller is authenticated (Authority token). |
 | `maxIndexRequestsPerHour` | – | Per-domain quota for index endpoints. `0`/negative disables the guard. |
 | `maxDownloadRequestsPerHour` | – | Per-domain quota for artifact downloads. |
-| `exports` | ✅ | Collection of export projections. |
+| `exports` | ✅ | Collection of export projections. |

 Export-level fields:

 | Field | Required | Description |
 | --- | --- | --- |
-| `key` | ✅ | Unique key within the domain. Used in URLs (`/exports/{key}`) and filenames. |
+| `key` | ✅ | Unique key within the domain. Used in URLs (`/exports/{key}`) and filenames/bundle entries. |
 | `format` | ✅ | One of `json`, `jsonl`, `openvex`, `csaf`. Maps to `VexExportFormat`. |
 | `filters` | – | Key/value pairs executed via `VexQueryFilter`. Keys must match export data source columns (e.g., `vulnId`, `productKey`). |
 | `sort` | – | Key/boolean map (false = descending). |
@@ -117,7 +136,14 @@ Recommended workflow:
   * `GET /download` when new
   * Verify digest + attestation

-When the export team lands deterministic mirror bundles (Sprint 7 tasks 01-005/006/007), these configurations can be generated automatically.
+When the export engine runs, it materializes the following artefacts under `outputRoot/<directoryName>`:
+
+- `index.json` – canonical index listing each configured domain, manifest/bundle descriptors (with SHA-256 digests), and available export keys.
+- `<domain>/manifest.json` – per-domain summary with export metadata (query signature, consensus/score digests, source providers) and a descriptor pointing at the bundle.
+- `<domain>/bundle.json` – canonical payload containing serialized consensus, score envelopes, and normalized VEX claims for the matching export definitions.
+- `<domain>/bundle.json.jws` – optional detached JWS when signing is enabled.
+
+Downstream automation reads `manifest.json`/`bundle.json` directly, while `/excititor/mirror` endpoints stream the same artefacts through authenticated HTTP.

 ---

--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -13,7 +13,7 @@
 | DOCS-EVENTS-09-002 | DONE (2025-10-19) | Docs Guild, Platform Events | SCANNER-EVENTS-15-201 | Publish event schema catalog (`docs/events/`) for `scanner.report.ready@1`, `scheduler.rescan.delta@1`, `attestor.logged@1`. | Schemas validated (Ajv CI hooked); docs/events/README summarises usage; Platform Events notified via `docs/updates/2025-10-18-docs-guild.md`. |
 | DOCS-EVENTS-09-003 | DONE (2025-10-19) | Docs Guild | DOCS-EVENTS-09-002 | Add human-readable envelope field references and canonical payload samples for published events, including offline validation workflow. | Tables explain common headers/payload segments; versioned sample payloads committed; README links to validation instructions and samples. |
 | DOCS-EVENTS-09-004 | DONE (2025-10-19) | Docs Guild, Scanner WebService | SCANNER-EVENTS-15-201 | Refresh scanner event docs to mirror DSSE-backed report fields, document `scanner.scan.completed`, and capture canonical sample validation. | Schemas updated for new payload shape; README references DSSE reuse and validation test; samples align with emitted events. |
-| PLATFORM-EVENTS-09-401 | DONE (2025-10-19) | Platform Events Guild | DOCS-EVENTS-09-003 | Embed canonical event samples into contract/integration tests and ensure CI validates payloads against published schemas. | Notify/Scheduler contract suites exercise samples; CI job validates samples with `ajv-cli`; Platform Events changelog notes coverage. |
+| PLATFORM-EVENTS-09-401 | DONE (2025-10-21) | Platform Events Guild | DOCS-EVENTS-09-003 | Embed canonical event samples into contract/integration tests and ensure CI validates payloads against published schemas. | Notify models tests now run schema validation against `docs/events/*.json`, event schemas allow optional `attributes`, and docs capture the new validation workflow. |
 | RUNTIME-GUILD-09-402 | DONE (2025-10-19) | Runtime Guild | SCANNER-POLICY-09-107 | Confirm Scanner WebService surfaces `quietedFindingCount` and progress hints to runtime consumers; document readiness checklist. | Runtime verification run captures enriched payload; checklist/doc updates merged; stakeholders acknowledge availability. |
 | DOCS-CONCELIER-07-201 | TODO | Docs Guild, Concelier WebService | FEEDWEB-DOCS-01-001 | Final editorial review and publish pass for Concelier authority toggle documentation (Quickstart + operator guide). | Review feedback resolved, publish PR merged, release notes updated with documentation pointer. |
 | DOCS-RUNTIME-17-004 | TODO | Docs Guild, Runtime Guild | SCANNER-EMIT-17-701, ZASTAVA-OBS-17-005, DEVOPS-REL-17-002 | Document build-id workflows: SBOM exposure, runtime event payloads, debug-store layout, and operator guidance for symbol retrieval. | Architecture + operator docs updated with build-id sections, examples show `readelf` output + debuginfod usage, references linked from Offline Kit/Release guides. |
--- a/docs/events/README.md
+++ b/docs/events/README.md
@@ -20,12 +20,13 @@ All event envelopes share the same deterministic header. Use the following table
 | `tenant` | `string` | Multi‑tenant isolation key; mirror the value recorded in queue/Mongo metadata. |
 | `ts` | `date-time` | RFC 3339 UTC timestamp. Use monotonic clocks or atomic offsets so ordering survives retries. |
 | `scope` | `object` | Optional block used when the event concerns a specific image or repository. See schema for required fields (e.g., `repo`, `digest`). |
-| `payload` | `object` | Event-specific body. Schemas allow additional properties so producers can add optional hints (e.g., `reportId`, `quietedFindingCount`) without breaking consumers. For scanner events, payloads embed both the canonical report document and the DSSE envelope so consumers can reuse signatures without recomputing them. See `docs/runtime/SCANNER_RUNTIME_READINESS.md` for the runtime consumer checklist covering these hints. |
+| `payload` | `object` | Event-specific body. Schemas allow additional properties so producers can add optional hints (e.g., `reportId`, `quietedFindingCount`) without breaking consumers. For scanner events, payloads embed both the canonical report document and the DSSE envelope so consumers can reuse signatures without recomputing them. See `docs/runtime/SCANNER_RUNTIME_READINESS.md` for the runtime consumer checklist covering these hints. |
+| `attributes` | `object` | Optional metadata bag (`string` keys/values) for downstream correlation (e.g., pipeline identifiers). Omit when unused to keep payloads concise. |

 When adding new optional fields, document the behaviour in the schema’s `description` block and update the consumer checklist in the next sprint sync.

 ## Canonical samples & validation
-Reference payloads live under `docs/events/samples/`, mirroring the schema version (`<event-name>@<version>.sample.json`). They illustrate common field combinations, including the optional attributes that downstream teams rely on for UI affordances and audit trails. Scanner samples reuse the exact DSSE envelope checked into `samples/api/reports/report-sample.dsse.json`, and a unit test (`ReportSamplesTests`) guards that the payload/base64 remain canonical.
+Reference payloads live under `docs/events/samples/`, mirroring the schema version (`<event-name>@<version>.sample.json`). They illustrate common field combinations, including the optional attributes that downstream teams rely on for UI affordances and audit trails. Scanner samples reuse the exact DSSE envelope checked into `samples/api/reports/report-sample.dsse.json`, and unit tests (`ReportSamplesTests`, `PlatformEventSchemaValidationTests`) guard that payloads stay canonical and continue to satisfy the published schemas.

 Run the following loop offline to validate both schemas and samples:

--- a/docs/events/attestor.logged@1.json
+++ b/docs/events/attestor.logged@1.json
@@ -8,8 +8,8 @@
    "kind": {"const": "attestor.logged"},
    "tenant": {"type": "string"},
    "ts": {"type": "string", "format": "date-time"},
-    "payload": {
-      "type": "object",
+    "payload": {
+      "type": "object",
      "required": ["artifactSha256", "rekor", "subject"],
      "properties": {
        "artifactSha256": {"type": "string"},
@@ -30,9 +30,14 @@
            "name": {"type": "string"}
          }
        }
-      },
-      "additionalProperties": true
-    }
-  },
-  "additionalProperties": false
-}
+      },
+      "additionalProperties": true
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Optional event attributes for downstream correlation.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}
--- a/docs/events/scanner.report.ready@1.json
+++ b/docs/events/scanner.report.ready@1.json
@@ -17,10 +17,10 @@
        "digest": {"type": "string"}
      }
    },
-    "payload": {
-      "type": "object",
-      "required": ["verdict", "delta", "links"],
-      "properties": {
+    "payload": {
+      "type": "object",
+      "required": ["verdict", "delta", "links"],
+      "properties": {
        "reportId": {"type": "string"},
        "generatedAt": {"type": "string", "format": "date-time"},
        "verdict": {"enum": ["pass", "warn", "fail"]},
@@ -76,9 +76,14 @@
          },
          "additionalProperties": false
        }
-      },
-      "additionalProperties": true
-    }
-  },
-  "additionalProperties": false
-}
+      },
+      "additionalProperties": true
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Optional event attributes for downstream correlation.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}
--- a/docs/events/scanner.scan.completed@1.json
+++ b/docs/events/scanner.scan.completed@1.json
@@ -17,8 +17,8 @@
        "digest": {"type": "string"}
      }
    },
-    "payload": {
-      "type": "object",
+    "payload": {
+      "type": "object",
      "required": ["reportId", "digest", "verdict", "summary"],
      "properties": {
        "reportId": {"type": "string"},
@@ -90,8 +90,13 @@
          "additionalProperties": false
        }
      },
-      "additionalProperties": true
-    }
-  },
-  "additionalProperties": false
-}
+      "additionalProperties": true
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Optional event attributes for downstream correlation.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}
--- a/docs/events/scheduler.rescan.delta@1.json
+++ b/docs/events/scheduler.rescan.delta@1.json
@@ -8,8 +8,8 @@
    "kind": {"const": "scheduler.rescan.delta"},
    "tenant": {"type": "string"},
    "ts": {"type": "string", "format": "date-time"},
-    "payload": {
-      "type": "object",
+    "payload": {
+      "type": "object",
      "required": ["scheduleId", "impactedDigests", "summary"],
      "properties": {
        "scheduleId": {"type": "string"},
@@ -26,8 +26,13 @@
          }
        }
      },
-      "additionalProperties": true
-    }
-  },
-  "additionalProperties": false
-}
+      "additionalProperties": true
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Optional event attributes for downstream correlation.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}