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"