Bernstein Sbom API

openapi: 3.2.0
info:
  title: Bernstein Task Server Sbom API
  description: 'Bernstein REST API - the open-source governance layer for AI agents, one git worktree per task.


    ## Authentication


    Authentication is ENABLED by default. Include a Bearer token in all requests:


    ```

    Authorization: Bearer

    ```


    To run without auth (development only), set `BERNSTEIN_AUTH_DISABLED=1` - this logs a loud warning and passes every request through.


    Public endpoints (no auth required): `/health`, `/health/ready`, `/health/live`, `/ready`, `/alive`, `/.well-known/agent.json`, `/docs`, `/openapi.json`, and the auth-flow endpoints (`/auth/login`, `/auth/oidc/callback`, etc.).


    Webhook and hook endpoints (`/webhook`, `/webhooks/*`, `/hooks/{session_id}`) authenticate via HMAC-SHA256 signatures - they do NOT accept Bearer tokens.


    ## Base URL


    Default: `http://127.0.0.1:8052`. Override with env vars `BERNSTEIN_HOST` and `BERNSTEIN_PORT`.


    ## Error Format


    All errors return JSON with a `detail` field:


    ```json

    {"detail": "Task not found: task-xyz"}

    ```


    | Status | Meaning |

    |--------|---------|

    | 400 | Bad request (validation error) |

    | 401 | Unauthorized (missing/invalid token) |

    | 403 | Forbidden (IP not in allowlist) |

    | 404 | Resource not found |

    | 409 | Conflict (task already in terminal state) |

    | 429 | Rate limited - respect the `Retry-After` header |

    | 500 | Internal server error |'
  version: 3.22.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: Alex Chernysh
    url: https://github.com/sipyourdrink-ltd/bernstein
servers:
- url: http://{host}:{port}
  description: Task server started by the Bernstein CLI on the operator's own machine. There is no hosted instance; substitute the host and port of your install.
  variables:
    host:
      default: 127.0.0.1
      description: Interface the task server binds to. Loopback by default.
    port:
      default: '8052'
      description: Task server port. Override with BERNSTEIN_PORT.
tags:
- name: sbom
paths:
  /sbom/generate:
    post:
      tags:
      - sbom
      summary: Generate SBOM and optionally run vulnerability scan
      description: 'Generate a CycloneDX or SPDX SBOM from installed packages.


        After generation, optionally run ``osv-scanner`` or ``grype`` for

        vulnerability scanning. When ``block_on_critical=true`` and critical

        findings are detected, responds with HTTP 422 so CI/CD pipelines can

        gate merges on vulnerability status.


        SBOM artifacts are written to ``.sdd/artifacts/sbom/``.'
      operationId: generate_sbom_sbom_generate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SBOMGenerateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SBOMGenerateResponse'
        '400':
          description: Unknown SBOM format
        '422':
          description: Critical vulnerabilities found (gate blocked)
        '503':
          description: Server workdir not configured
  /sbom/artifacts:
    get:
      tags:
      - sbom
      summary: List generated SBOM artifact files
      description: List previously generated SBOM artifact files from ``.sdd/artifacts/sbom/``.
      operationId: list_sbom_artifacts_sbom_artifacts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SBOMListResponse'
        '503':
          description: Server workdir not configured
  /api/v1/sbom/generate:
    post:
      tags:
      - sbom
      summary: Generate SBOM and optionally run vulnerability scan
      description: 'Generate a CycloneDX or SPDX SBOM from installed packages.


        After generation, optionally run ``osv-scanner`` or ``grype`` for

        vulnerability scanning. When ``block_on_critical=true`` and critical

        findings are detected, responds with HTTP 422 so CI/CD pipelines can

        gate merges on vulnerability status.


        SBOM artifacts are written to ``.sdd/artifacts/sbom/``.'
      operationId: generate_sbom_api_v1_sbom_generate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SBOMGenerateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SBOMGenerateResponse'
        '400':
          description: Unknown SBOM format
        '422':
          description: Critical vulnerabilities found (gate blocked)
        '503':
          description: Server workdir not configured
  /api/v1/sbom/artifacts:
    get:
      tags:
      - sbom
      summary: List generated SBOM artifact files
      description: List previously generated SBOM artifact files from ``.sdd/artifacts/sbom/``.
      operationId: list_sbom_artifacts_api_v1_sbom_artifacts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SBOMListResponse'
        '503':
          description: Server workdir not configured
components:
  schemas:
    SBOMGenerateRequest:
      properties:
        sbom_format:
          type: string
          title: Sbom Format
          description: 'Output format: ''cyclonedx-json'' or ''spdx-json''.'
          default: cyclonedx-json
        source:
          type: string
          title: Source
          description: Package source label (pip, npm, requirements.txt, etc.).
          default: pip
        run_scan:
          type: boolean
          title: Run Scan
          description: Run vulnerability scanning (osv-scanner or grype) after generation.
          default: true
        block_on_critical:
          type: boolean
          title: Block On Critical
          description: Raise 422 when critical vulnerabilities are found.
          default: true
      type: object
      title: SBOMGenerateRequest
      description: Body for POST /sbom/generate.
    SBOMListResponse:
      properties:
        artifacts:
          items:
            $ref: '#/components/schemas/SBOMArtifactEntry'
          type: array
          title: Artifacts
        artifact_dir:
          type: string
          title: Artifact Dir
      type: object
      required:
      - artifacts
      - artifact_dir
      title: SBOMListResponse
      description: Response from GET /sbom/artifacts.
    SBOMVulnFindingResponse:
      properties:
        component_name:
          type: string
          title: Component Name
        component_version:
          type: string
          title: Component Version
        vuln_id:
          type: string
          title: Vuln Id
        severity:
          type: string
          title: Severity
        summary:
          type: string
          title: Summary
        fix_version:
          type: string
          title: Fix Version
        scanner:
          type: string
          title: Scanner
      type: object
      required:
      - component_name
      - component_version
      - vuln_id
      - severity
      - summary
      - fix_version
      - scanner
      title: SBOMVulnFindingResponse
      description: Serialised vulnerability finding.
    SBOMGenerateResponse:
      properties:
        serial_number:
          type: string
          title: Serial Number
        sbom_format:
          type: string
          title: Sbom Format
        component_count:
          type: integer
          title: Component Count
        artifact_path:
          type: string
          title: Artifact Path
        scan_result:
          anyOf:
          - $ref: '#/components/schemas/SBOMScanResultResponse'
          - type: 'null'
      type: object
      required:
      - serial_number
      - sbom_format
      - component_count
      - artifact_path
      title: SBOMGenerateResponse
      description: Response from POST /sbom/generate.
    SBOMArtifactEntry:
      properties:
        filename:
          type: string
          title: Filename
        path:
          type: string
          title: Path
        size_bytes:
          type: integer
          title: Size Bytes
      type: object
      required:
      - filename
      - path
      - size_bytes
      title: SBOMArtifactEntry
      description: A single SBOM artifact file entry.
    SBOMScanResultResponse:
      properties:
        scanner:
          type: string
          title: Scanner
        finding_count:
          type: integer
          title: Finding Count
        highest_severity:
          type: string
          title: Highest Severity
        findings:
          items:
            $ref: '#/components/schemas/SBOMVulnFindingResponse'
          type: array
          title: Findings
        errors:
          items:
            type: string
          type: array
          title: Errors
        passed_gate:
          type: boolean
          title: Passed Gate
      type: object
      required:
      - scanner
      - finding_count
      - highest_severity
      - findings
      - errors
      - passed_gate
      title: SBOMScanResultResponse
      description: Serialised scan result.