old sprints work, new sprints for exposing functionality via cli, improve code_of_conduct and other agents instructions

2026-01-15 18:37:59 +02:00
parent c631bacee2
commit 88a85cdd92
208 changed files with 32271 additions and 2287 deletions
--- a/docs/modules/excititor/architecture.md
+++ b/docs/modules/excititor/architecture.md
@@ -431,6 +431,111 @@ correlation: { replaces?: sha256, replacedBy?: sha256 }

  * Indexes: `{type:1, occurredAt:-1}`, TTL on `occurredAt` for configurable retention.

+### 3.3 VEX Change Events
+
+> Sprint: SPRINT_20260112_006_EXCITITOR_vex_change_events
+
+Excititor emits deterministic VEX change events when statements are added, superseded, or conflict. These events drive policy reanalysis in downstream systems.
+
+#### Event Types
+
+| Event Type | Constant | Description |
+|------------|----------|-------------|
+| `vex.statement.added` | `VexTimelineEventTypes.StatementAdded` | New VEX statement ingested |
+| `vex.statement.superseded` | `VexTimelineEventTypes.StatementSuperseded` | Statement replaced by newer version |
+| `vex.statement.conflict` | `VexTimelineEventTypes.StatementConflict` | Conflicting statuses detected |
+| `vex.status.changed` | `VexTimelineEventTypes.StatusChanged` | Effective status changed for a product-vulnerability pair |
+
+#### VexStatementChangeEvent Schema
+
+```jsonc
+{
+  "eventId": "vex-evt-sha256:abc123...",    // Deterministic hash-based ID
+  "eventType": "vex.statement.added",
+  "tenant": "default",
+  "vulnerabilityId": "CVE-2026-1234",
+  "productKey": "pkg:npm/lodash@4.17.21",
+  "newStatus": "not_affected",
+  "previousStatus": null,                    // null for new statements
+  "providerId": "vendor:redhat",
+  "observationId": "default:redhat:VEX-2026-0001:v1",
+  "supersededBy": null,
+  "supersedes": [],
+  "provenance": {
+    "documentHash": "sha256:...",
+    "documentUri": "https://vendor/vex/...",
+    "sourceTimestamp": "2026-01-15T10:00:00Z",
+    "author": "security@vendor.com",
+    "trustScore": 0.95
+  },
+  "conflictDetails": null,
+  "occurredAtUtc": "2026-01-15T10:30:00Z",
+  "traceId": "trace-xyz789"
+}
+```
+
+#### VexConflictDetails Schema
+
+When `eventType` is `vex.statement.conflict`:
+
+```jsonc
+{
+  "conflictType": "status_mismatch",        // status_mismatch | trust_tie | supersession_conflict
+  "conflictingStatuses": [
+    {
+      "providerId": "vendor:redhat",
+      "status": "not_affected",
+      "justification": "CODE_NOT_REACHABLE",
+      "trustScore": 0.95
+    },
+    {
+      "providerId": "vendor:ubuntu",
+      "status": "affected",
+      "justification": null,
+      "trustScore": 0.85
+    }
+  ],
+  "resolutionStrategy": "highest_trust",    // or null if unresolved
+  "autoResolved": false
+}
+```
+
+#### Event ID Computation
+
+Event IDs are deterministic SHA-256 hashes computed from:
+- Event type
+- Tenant
+- Vulnerability ID
+- Product key
+- Observation ID
+- Occurred timestamp (truncated to seconds)
+
+This ensures idempotent event emission across retries.
+
+#### Policy Engine Integration
+
+Policy Engine subscribes to VEX events to trigger reanalysis:
+
+```yaml
+# Policy event subscription
+subscriptions:
+  - event: vex.statement.*
+    action: reanalyze
+    filter:
+      trustScore: { $gte: 0.7 }
+  - event: vex.statement.conflict
+    action: queue_for_review
+    filter:
+      autoResolved: false
+```
+
+#### Emission Ordering
+
+Events are emitted with deterministic ordering:
+1. Statement events ordered by `occurredAtUtc` ascending
+2. Conflict events emitted after all related statement events
+3. Events for the same vulnerability sorted by provider ID
+
 **`vex.consensus`** (optional rollups)

 ```