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/excititor/vex_linksets_api.md
+++ b/docs/modules/excititor/vex_linksets_api.md
@@ -0,0 +1,104 @@
+# Excititor VEX linkset APIs (observations + linksets)
+
+> Draft examples for Sprint 119 (EXCITITOR-LNM-21-203). Aligns with WebService endpoints implemented in `src/Excititor/StellaOps.Excititor.WebService/Program.cs`.
+
+## /v1/vex/observations
+
+### List
+```
+GET /v1/vex/observations?vulnerabilityId=CVE-2024-0001&productKey=pkg:maven/org.demo/app@1.2.3&providerId=ubuntu-csaf&status=affected&limit=2
+Headers:
+  Authorization: Bearer <token>
+  X-Tenant: default
+Response 200 (application/json):
+{
+  "items": [
+    {
+      "tenant": "default",
+      "observationId": "vex:obs:sha256:...",
+      "providerId": "ubuntu-csaf",
+      "document": {
+        "digest": "sha256:...",
+        "uri": "https://example.com/csaf/1.json",
+        "signature": null
+      },
+      "scope": {
+        "vulnerabilityId": "CVE-2024-0001",
+        "productKey": "pkg:maven/org.demo/app@1.2.3"
+      },
+      "statements": [
+        {
+          "vulnerabilityId": "CVE-2024-0001",
+          "productKey": "pkg:maven/org.demo/app@1.2.3",
+          "status": "affected",
+          "justification": {
+            "type": "component_not_present",
+            "reason": "Not shipped in base profile"
+          },
+          "signals": { "severity": { "score": 7.5 } },
+          "provenance": {
+            "providerId": "ubuntu-csaf",
+            "sourceId": "USN-9999-1",
+            "fieldMasks": ["statements"]
+          }
+        }
+      ],
+      "linkset": {
+        "aliases": ["USN-9999-1"],
+        "purls": ["pkg:maven/org.demo/app"],
+        "cpes": [],
+        "references": [{"type": "advisory", "url": "https://..."}],
+        "disagreements": []
+      },
+      "createdAt": "2025-11-18T12:34:56Z"
+    }
+  ],
+  "nextCursor": "eyJ2dWxuZXJhYmlsaXR5SWQiOiJDVkUtMjAyNC0wMDAxIiwiY3JlYXRlZEF0IjoiMjAyNS0xMS0xOFQxMjozNDo1NloifQ=="
+}
+```
+
+### Get by key
+```
+GET /v1/vex/observations/CVE-2024-0001/pkg:maven/org.demo/app@1.2.3
+Headers: Authorization + X-Tenant
+Response 200: same projection shape as list items (single object).
+```
+
+## /v1/vex/linksets
+```
+GET /v1/vex/linksets?vulnerabilityId=CVE-2024-0001&productKey=pkg:maven/org.demo/app@1.2.3&status=affected&limit=2
+Headers: Authorization + X-Tenant
+Response 200:
+{
+  "items": [
+    {
+      "linksetId": "CVE-2024-0001:pkg:maven/org.demo/app@1.2.3",
+      "tenant": "default",
+      "vulnerabilityId": "CVE-2024-0001",
+      "productKey": "pkg:maven/org.demo/app@1.2.3",
+      "providers": ["ubuntu-csaf", "suse-csaf"],
+      "statuses": ["affected", "fixed"],
+      "aliases": ["USN-9999-1"],
+      "purls": ["pkg:maven/org.demo/app"],
+      "cpes": [],
+      "references": [{"type": "advisory", "url": "https://..."}],
+      "disagreements": [{"providerId": "suse-csaf", "status": "fixed", "justification": null, "confidence": null}],
+      "observations": [
+        {"observationId": "vex:obs:...", "providerId": "ubuntu-csaf", "status": "affected", "severity": 7.5},
+        {"observationId": "vex:obs:...", "providerId": "suse-csaf", "status": "fixed", "severity": null}
+      ],
+      "createdAt": "2025-11-18T12:34:56Z"
+    }
+  ],
+  "nextCursor": null
+}
+```
+
+## Notes
+- Pagination: `limit` (default 200, max 500) + `cursor` (opaque base64 of `vulnerabilityId` + `createdAt`).
+- Filters: `vulnerabilityId`, `productKey`, `providerId`, `status`; multiple query values allowed.
+- Headers: `Excititor-Results-Count`, `Excititor-Results-Cursor` (observations) and `Excititor-Results-Total` / `Excititor-Results-Truncated` (chunks) already implemented.
+- Determinism: responses sorted by `vulnerabilityId`, then `productKey`; arrays sorted lexicographically.
+
+## SDK generation
+- Use this file plus `vex_observations.md` as the source of truth for SDK examples in EXCITITOR-LNM-21-203.