Refactor code structure for improved readability and maintainability; optimize performance in key functions.

docs/schemas/findings-evidence-api.openapi.yaml

@@ -0,0 +1,219 @@
+openapi: 3.1.0
+info:
+  title: StellaOps Findings Evidence API
+  version: 1.0.0
+  description: |
+    OpenAPI specification for the findings evidence endpoint.
+    Supports explainable triage evidence retrieval for a finding or batch.
+  contact:
+    name: StellaOps API Team
+    email: api@stella-ops.org
+  license:
+    name: AGPL-3.0-or-later
+    identifier: AGPL-3.0-or-later
+
+servers:
+  - url: https://api.stella-ops.org
+    description: Production
+  - url: https://api.staging.stella-ops.org
+    description: Staging
+
+tags:
+  - name: evidence
+    description: Evidence lookups for findings
+
+paths:
+  /api/v1/findings/{findingId}/evidence:
+    get:
+      operationId: getFindingEvidence
+      summary: Get consolidated evidence for a finding
+      tags: [evidence]
+      parameters:
+        - name: findingId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Finding identifier (UUID).
+        - name: includeRaw
+          in: query
+          required: false
+          schema:
+            type: boolean
+            default: false
+          description: Include raw source locations (requires elevated scope).
+      responses:
+        "200":
+          description: Evidence retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FindingEvidenceResponse"
+        "403":
+          description: Insufficient permissions for raw source.
+        "404":
+          description: Finding not found.
+  /api/v1/findings/evidence/batch:
+    post:
+      operationId: getFindingsEvidenceBatch
+      summary: Get evidence for multiple findings
+      tags: [evidence]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/BatchEvidenceRequest"
+      responses:
+        "200":
+          description: Evidence batch retrieved.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BatchEvidenceResponse"
+        "400":
+          description: Invalid batch request.
+
+components:
+  schemas:
+    FindingEvidenceResponse:
+      type: object
+      required: [finding_id, cve, component, last_seen, freshness]
+      properties:
+        finding_id:
+          type: string
+        cve:
+          type: string
+        component:
+          $ref: "#/components/schemas/ComponentInfo"
+        reachable_path:
+          type: array
+          items:
+            type: string
+        entrypoint:
+          $ref: "#/components/schemas/EntrypointInfo"
+        vex:
+          $ref: "#/components/schemas/VexStatusInfo"
+        last_seen:
+          type: string
+          format: date-time
+        attestation_refs:
+          type: array
+          items:
+            type: string
+        score:
+          $ref: "#/components/schemas/ScoreInfo"
+        boundary:
+          $ref: "#/components/schemas/BoundaryInfo"
+        freshness:
+          $ref: "#/components/schemas/FreshnessInfo"
+    ComponentInfo:
+      type: object
+      required: [name, version]
+      properties:
+        name:
+          type: string
+        version:
+          type: string
+        purl:
+          type: string
+        ecosystem:
+          type: string
+    EntrypointInfo:
+      type: object
+      required: [type]
+      properties:
+        type:
+          type: string
+        route:
+          type: string
+        method:
+          type: string
+        auth:
+          type: string
+    VexStatusInfo:
+      type: object
+      required: [status]
+      properties:
+        status:
+          type: string
+        justification:
+          type: string
+        timestamp:
+          type: string
+          format: date-time
+        issuer:
+          type: string
+    ScoreInfo:
+      type: object
+      required: [risk_score]
+      properties:
+        risk_score:
+          type: integer
+          minimum: 0
+          maximum: 100
+        contributions:
+          type: array
+          items:
+            $ref: "#/components/schemas/ScoreContribution"
+    ScoreContribution:
+      type: object
+      required: [factor, value]
+      properties:
+        factor:
+          type: string
+        value:
+          type: integer
+        reason:
+          type: string
+    BoundaryInfo:
+      type: object
+      required: [surface, exposure]
+      properties:
+        surface:
+          type: string
+        exposure:
+          type: string
+        auth:
+          $ref: "#/components/schemas/AuthInfo"
+        controls:
+          type: array
+          items:
+            type: string
+    AuthInfo:
+      type: object
+      required: [mechanism]
+      properties:
+        mechanism:
+          type: string
+        required_scopes:
+          type: array
+          items:
+            type: string
+    FreshnessInfo:
+      type: object
+      required: [is_stale]
+      properties:
+        is_stale:
+          type: boolean
+        expires_at:
+          type: string
+          format: date-time
+        ttl_remaining_hours:
+          type: integer
+    BatchEvidenceRequest:
+      type: object
+      required: [finding_ids]
+      properties:
+        finding_ids:
+          type: array
+          items:
+            type: string
+    BatchEvidenceResponse:
+      type: object
+      required: [findings]
+      properties:
+        findings:
+          type: array
+          items:
+            $ref: "#/components/schemas/FindingEvidenceResponse"