work

docs/modules/vuln-explorer/api.md

@@ -0,0 +1,7 @@
+# Vuln Explorer API – draft v1 (2025-11-25)
+
+- OpenAPI: `docs/modules/vuln-explorer/openapi/vuln-explorer.v1.yaml`
+- Scope: read-only vulnerability listing/detail for Console/CLI; deterministic ordering (score desc, id asc) with opaque page tokens.
+- Required headers: `x-stella-tenant`; optional `policyVersion`.
+- Filters: CVE, PURL, severity band, exploitability flag, fixAvailable.
+- Responses include policyVersion + rationaleId for explainability; provenance anchors back to Findings Ledger/evidence bundles.

docs/modules/vuln-explorer/openapi/vuln-explorer.v1.yaml

@@ -0,0 +1,188 @@
+# Vuln Explorer API · v1 (draft 2025-11-25)
+openapi: 3.0.3
+info:
+  title: StellaOps Vuln Explorer API
+  version: "1.0.0-draft.2025-11-25"
+  description: >
+    Read-only vulnerability exploration surface. All responses are deterministic
+    under identical inputs and include policy version + rationale identifiers.
+servers:
+  - url: https://{host}
+    variables:
+      host:
+        default: vuln-explorer.local
+tags:
+  - name: Vulns
+paths:
+  /vulns:
+    get:
+      summary: List vulnerabilities
+      tags: [Vulns]
+      parameters:
+        - $ref: '#/components/parameters/Tenant'
+        - $ref: '#/components/parameters/PolicyVersion'
+        - $ref: '#/components/parameters/PageSize'
+        - $ref: '#/components/parameters/PageToken'
+        - $ref: '#/components/parameters/Cve'
+        - $ref: '#/components/parameters/Purl'
+        - $ref: '#/components/parameters/Severity'
+        - $ref: '#/components/parameters/Exploitability'
+        - $ref: '#/components/parameters/FixAvailable'
+      responses:
+        '200':
+          description: Paged vulnerabilities ordered by (score desc, id asc).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VulnListResponse'
+  /vulns/{id}:
+    get:
+      summary: Get vulnerability by stable ID
+      tags: [Vulns]
+      parameters:
+        - $ref: '#/components/parameters/Tenant'
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Stable vulnerability id (hash over source ids+purls).
+      responses:
+        '200':
+          description: Vulnerability detail with evidence/provenance.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Vuln'
+        '404':
+          description: Not found for tenant/policy scope.
+
+components:
+  parameters:
+    Tenant:
+      name: x-stella-tenant
+      in: header
+      required: true
+      schema: { type: string }
+      description: Tenant identifier; required for all endpoints.
+    PolicyVersion:
+      name: policyVersion
+      in: query
+      schema: { type: string }
+      description: Policy version/rationale to contextualise scores.
+    PageSize:
+      name: pageSize
+      in: query
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 200
+        default: 50
+      description: Max items per page.
+    PageToken:
+      name: pageToken
+      in: query
+      schema: { type: string }
+      description: Opaque token encoding last (score,id) tuple.
+    Cve:
+      name: cve
+      in: query
+      schema: { type: array, items: { type: string }, minItems: 1 }
+      style: form
+      explode: true
+      description: Filter by CVE ids.
+    Purl:
+      name: purl
+      in: query
+      schema: { type: array, items: { type: string }, minItems: 1 }
+      style: form
+      explode: true
+      description: Filter by PURL(s); matches affected packages.
+    Severity:
+      name: severity
+      in: query
+      schema:
+        type: array
+        items:
+          type: string
+          enum: [CRITICAL, HIGH, MEDIUM, LOW, NONE]
+      style: form
+      explode: true
+      description: Filter by normalized severity band.
+    Exploitability:
+      name: exploitability
+      in: query
+      schema:
+        type: string
+        enum: [known, likely, unknown, none]
+      description: Derived exploitability flag (from KEV + VEX + telemetry).
+    FixAvailable:
+      name: fixAvailable
+      in: query
+      schema: { type: boolean }
+      description: Whether at least one fix is available.
+
+  schemas:
+    VulnListResponse:
+      type: object
+      properties:
+        items:
+          type: array
+          items: { $ref: '#/components/schemas/Vuln' }
+        nextPageToken:
+          type: string
+          description: Opaque token encoding last (score,id) tuple.
+      required: [items]
+    Vuln:
+      type: object
+      properties:
+        id: { type: string, description: Stable hash id }
+        source:
+          type: object
+          properties:
+            feed: { type: string, description: Original source/feed name }
+            advisoryId: { type: string }
+        cveIds:
+          type: array
+          items: { type: string }
+        ghsaIds:
+          type: array
+          items: { type: string }
+        purls:
+          type: array
+          items: { type: string }
+        severity: { type: string, enum: [CRITICAL, HIGH, MEDIUM, LOW, NONE] }
+        score: { type: number, format: double, minimum: 0, maximum: 10 }
+        kev: { type: boolean }
+        exploitability: { type: string, enum: [known, likely, unknown, none] }
+        fixAvailable: { type: boolean }
+        summary: { type: string }
+        affectedPackages:
+          type: array
+          items:
+            type: object
+            properties:
+              purl: { type: string }
+              versions: { type: array, items: { type: string } }
+        firstSeen: { type: string, format: date-time }
+        lastSeen: { type: string, format: date-time }
+        advisoryRefs:
+          type: array
+          items:
+            type: object
+            properties:
+              url: { type: string, format: uri }
+              title: { type: string }
+        policyVersion: { type: string }
+        rationaleId: { type: string }
+        provenance:
+          type: object
+          properties:
+            ledgerEntryId: { type: string }
+            evidenceBundleId: { type: string }
+      required:
+        - id
+        - severity
+        - score
+        - policyVersion
+        - rationaleId