Refactor code structure for improved readability and maintainability; removed redundant code blocks and optimized function calls.

2025-11-20 07:50:52 +02:00
parent 616ec73133
commit 10212d67c0
473 changed files with 316758 additions and 388 deletions
--- a/docs/modules/concelier/bridges/vuln-29-001.md
+++ b/docs/modules/concelier/bridges/vuln-29-001.md
@@ -0,0 +1,81 @@
+# CONCELIER-VULN-29-001 · Concelier ↔ Vuln Explorer bridge (contract v0.1)
+
+Purpose: unblock PREP-CONCELIER-VULN-29-001 by defining the request/response contract Concelier must expose for Vuln Explorer and VEX Lens to consume advisory evidence without merge semantics.
+
+## API shape (Concelier WebService)
+- Endpoint: `POST /v1/advisories/search`
+- Auth: tenant-scoped token (`concelier.read` scope) with `mergeAllowed=false`.
+- Request body:
+  ```json
+  {
+    "query": {
+      "advisory_keys": ["GHSA-xxxx-xxxx"],
+      "purls": ["pkg:maven/org.example/app@1.2.3"],
+      "component_hashes": ["sha256:..."],
+      "has_vex": true
+    },
+    "page": {
+      "size": 50,
+      "cursor": null
+    }
+  }
+  ```
+- Response body:
+  ```json
+  {
+    "results": [
+      {
+        "advisory_key": "GHSA-xxxx-xxxx",
+        "source": "ghsa",
+        "observations": [{
+          "id": "obs-123",
+          "purl": "pkg:maven/org.example/app@1.2.3",
+          "version_range": "[1.2.0,2.0.0)",
+          "status": "affected",
+          "published": "2025-11-01T00:00:00Z",
+          "fixed": null,
+          "provenance": {
+            "source": "ghsa",
+            "retrieved_at": "2025-11-18T12:00:00Z",
+            "hash": "sha256:..."
+          }
+        }],
+        "vex": [{
+          "statement_id": "st-001",
+          "status": "not_affected",
+          "justification": "component_not_present",
+          "impact_statement": "Library not shipped",
+          "provenance": {
+            "source": "vendor-vex",
+            "retrieved_at": "2025-11-18T12:00:00Z",
+            "hash": "sha256:..."
+          }
+        }]
+      }
+    ],
+    "page": {"cursor": "next-token", "size": 50}
+  }
+  ```
+
+## Determinism requirements
+- Sort observations by `purl`, then `published`, then `id`.
+- Sort VEX statements by `statement_id`.
+- Timestamps UTC ISO-8601 with `Z`.
+- Omit merge-derived fields; only surface source-provided values.
+
+## Fields Vuln Explorer expects
+- `advisory_key`, `source`, `observations[*].purl`, `observations[*].status`, `observations[*].provenance.hash`.
+- VEX fields: `status`, `justification`, `impact_statement`, `provenance.hash`.
+- Optional: `fix_version` when present; keep absent otherwise (no empty strings).
+
+## Test fixtures
+- Location: `docs/samples/console/console-vex-30-001.json` already includes VEX sample keyed by advisory; add Concelier response sample to `docs/samples/console/concelier-vuln-29-001.json` (to be generated alongside implementation).
+
+## Owners
+- Concelier WebService Guild (producer)
+- Vuln Explorer Guild / VEX Lens Guild (consumers)
+
+## Next actions to unblock work
+- Implement endpoint stub with deterministic ordering and fixture from above sample.
+- Hook to Link-Not-Merge storage (fact-only) once available.
+- Add contract reference to OAS (Sprint 0114 CONCELIER-OAS-61-001 depends on this).