api.yaml

# Assisted by: Gemini 2.5 Pro
openapi: 3.0.3
info:
  title: Compass Service API
  version: 0.1.0
  description: |
    API for the Compass service. This service provides control-based attribute enrichment for telemetry data,
    leveraging internal domain logic and the Compass project's compliance knowledge.
    It's designed to be called by an OpenTelemetry Collector's custom processor to enrich logs, metrics, and traces.

paths:
  /v1/enrich:
    post:
      summary: Enrich telemetry attributes with compliance control data
      description: |
        Accepts a set of key telemetry attributes (e.g., asset ID, policy name, user ID) and
        returns additional compliance-related attributes based on internal domain logic.
        This endpoint is intended to be called by an OpenTelemetry Collector's custom processor.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichmentRequest'
      responses:
        '200':
          description: Successfully enriched attributes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    EnrichmentRequest:
      type: object
      description: Request payload for telemetry attribute enrichment
      properties:
        evidence:
          $ref: '#/components/schemas/Evidence'
      required:
        - evidence
      example:
        evidence:
          timestamp: "2024-01-15T10:30:00Z"
          policyEngineName: "OPA"
          policyRuleId: "deny-root-user"
          policyEvaluationStatus: "Failed"
          rawData:
            result: "deny"
            reason: "Root user access is not allowed"
    Evidence:
      type: object
      description: "Complete evidence log from policy engines and compliance assessment tools"
      properties:
        timestamp:
          type: string
          format: date-time
          description: The time when the raw evidence was generated
          example: "2024-01-15T10:30:00Z"

        # Policy Engine Identity
        policyEngineName:
          type: string
          description: Name of the policy engine that performed the evaluation or enforcement action
          example: "OPA"
        policyRuleId:
          type: string
          description: Unique identifier for the policy rule being evaluated or enforced
          example: "deny-root-user"
        
        # Policy Evaluation
        policyEvaluationStatus:
          type: string
          enum: ["Not Run", "Passed", "Failed", "Needs Review", "Not Applicable", "Unknown"]
          description: Result of the policy evaluation
          example: "Failed"
        
        rawData:
          type: object
          description: Raw JSON output from the policy engine
          example:
            result: "deny"
            reason: "Root user access is not allowed"
            metadata:
              timestamp: "2024-01-15T10:30:00Z"
              version: "1.0"
      required:
        - timestamp
        - policyEngineName
        - policyRuleId
        - policyEvaluationStatus

    EnrichmentResponse:
      type: object
      description: "Enriched compliance finding with risk attributes and threat mappings."
      properties:
        compliance:
          $ref: '#/components/schemas/Compliance'
      required:
        - compliance
      example:
        compliance:
          control:
            id: "OSPS-QA-07.01"
            category: "Access Control"
            catalogId: "OSPS-B"
            applicability: ["Production", "Staging"]
            remediationDescription: "Remove root user access and implement proper IAM policies"
          frameworks:
            frameworks: ["NIST-800-53", "SOC-2"]
            requirements: ["AC-1", "CC6.1"]
          risk:
            level: "High"
          status: "Non-Compliant"
          enrichmentStatus: "Success"

# Inspired by: https://schema.ocsf.io/1.5.0/objects/compliance
    Compliance:
      type: object
      title: "Compliance"
      description: "Compliance details from OCSF Security Control Profile."
      properties:
        control:
          $ref: '#/components/schemas/ComplianceControl'
        frameworks:
          $ref: '#/components/schemas/ComplianceFrameworks'
        risk:
          $ref: '#/components/schemas/ComplianceRisk'
        status:
          type: string
          enum:
            - Compliant
            - Non-Compliant
            - Exempt
            - Not Applicable
            - Unknown
          description: "Compliance status"
          example: "Non-Compliant"
        enrichmentStatus:
          type: string
          description: "Status of the compliance enrichment process: Success, Unmapped, Partial, Unknown, or Skipped."
          enum: ["Success", "Unmapped", "Partial", "Unknown", "Skipped"]
          example: "Success"
      additionalProperties: false
      required:
        - control
        - frameworks
        - status
        - enrichmentStatus

    # Compliance Control Schema
    ComplianceControl:
      type: object
      description: "Security control information for compliance assessment"
      properties:
        id:
          type: string
          description: Unique identifier for the security control being assessed
          example: "OSPS-QA-07.01"
        category:
          type: string
          description: Category or family that the security control belongs to
          example: "Access Control"
        catalogId:
          type: string
          description: Unique identifier for the security control catalog or framework
          example: "OSPS-B"
        applicability:
          type: array
          items:
            type: string
          description: Environments or contexts where this control applies
          example: ["Production", "Staging"]
        remediationDescription:
          type: string
          description: Description of the recommended remediation strategy for this control
          example: "Remove root user access and implement proper IAM policies"
      required:
        - id
        - catalogId
        - category

    # Compliance Frameworks Schema
    ComplianceFrameworks:
      type: object
      description: "Compliance framework and requirement information"
      properties:
        frameworks:
          type: array
          items:
            type: string
          description: Regulatory or industry standards being evaluated for compliance
          example: ["NIST-800-53", "SOC-2"]
        requirements:
          type: array
          items:
            type: string
          description: Compliance requirement identifiers from the frameworks being evaluated
          example: ["AC-1", "CC6.1"]
      required:
        - frameworks
        - requirements

    # Compliance Risk Schema
    ComplianceRisk:
      type: object
      description: "Compliance risk assessment information"
      properties:
        level:
          type: string
          enum: ["Critical", "High", "Medium", "Low", "Informational"]
          description: Risk level associated with non-compliance
          example: "High"

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: HTTP status code
          example: 400
        message:
          type: string
          description: Error message