openapi: 3.0.3
info:
  title: CycloneDX Generator (cdxgen) Server
  description: |-
    [cdxgen](https://github.com/cdxgen/cdxgen) is a CLI tool, library, REPL, and server to create a valid and compliant CycloneDX Bill of Materials (BOM) containing an aggregate of all project dependencies for C/C++, Node.js, PHP, Python, Ruby, Rust, Java, .Net, Dart, Haskell, Elixir, and Go projects in JSON format.

    CycloneDX is a full-stack BOM specification that is easily created, human and machine-readable, and simple to parse.


    Some useful links:
    - [Documentation](https://cdxgen.github.io/cdxgen/#/)
    - [Source API definition](https://github.com/cdxgen/cdxgen/blob/master/lib/server/openapi.yaml)
    - [CycloneDX Specification](https://cyclonedx.org/specification/overview/)
    - [CycloneDX JSON Schema Specification](https://github.com/CycloneDX/specification/blob/1.6/schema/bom-1.6.schema.json)
  contact:
    name: Slack (CycloneDX Workspace)
    url: https://cyclonedx.slack.com/archives/C04NFFE1962
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: latest
servers:
  - url: http://localhost:9090
tags:
  - name: health
    description: Service health checks
  - name: sbom
    description: Generate Software Bill of Materials
paths:
  /health:
    get:
      tags:
        - health
      summary: Check service health
      description: Check the health of the cdxgen server endpoint
      operationId: healthCheck
      responses:
        '200':
          description: Service operational
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
  /sbom:
    get:
      tags:
        - sbom
      summary: Generate Software Bill of Materials (SBOM)
      description: Generate a new Software Bill of Materials (SBOM)
      operationId: GetSBOM
      parameters:
        - name: type
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/type'
        - name: multiProject
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/multiProject'
        - name: requiredOnly
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/requiredOnly'
        - name: noBabel
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/noBabel'
        - name: installDeps
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/installDeps'
        - name: projectId
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/projectId'
        - name: projectName
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/projectName'
        - name: projectGroup
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/projectGroup'
        - name: projectVersion
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/projectVersion'
        - name: autoCreate
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/autoCreate'
        - name: isLatest
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/isLatest'
        - name: parentUUID
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/parentUUID'
        - name: parentProjectName
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/parentProjectName'
        - name: parentProjectVersion
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/parentProjectVersion'
        - name: serverUrl
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/serverUrl'
        - name: apiKey
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/apiKey'
        - name: specVersion
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/specVersion'
        - name: format
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/format'
        - name: filter
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/filter'
        - name: only
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/only'
        - name: autoCompositions
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/autoCompositions'
        - name: gitBranch
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/gitBranch'
        - name: lifecycle
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/lifecycle'
        - name: deep
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/deep'
        - name: profile
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/profile'
        - name: exclude
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/exclude'
        - name: includeCrypto
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/includeCrypto'
        - name: standard
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CDXGEN/properties/standard'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CycloneDXSBOM'
        '500':
          description: Failed operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    post:
      tags:
        - sbom
      summary: Generate Software Bill of Materials (SBOM)
      description: Generate a new Software Bill of Materials (SBOM)
      operationId: generateSBOM
      requestBody:
        description: cdxgen server configuration options
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CDXGEN'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CycloneDXSBOM'

components:
  schemas:
    Health:
      type: object
      properties:
        status:
          type: string
          example: "OK"
    CDXGEN:
      type: object
      properties:
        type:
          type: array
          items:
            type: string
          description: Project Types
          default: "universal"
          externalDocs:
            description: Single or comma separated values. See supported project types
            url: https://cdxgen.github.io/cdxgen/#/PROJECT_TYPES
        excludeType:
          type: array
          items:
            type: string
          description: Exclude Types
          externalDocs:
            description: Project types to exclude
            url: https://cdxgen.github.io/cdxgen/#/PROJECT_TYPES
        multiProject:
          type: boolean
        requiredOnly:
          type: boolean
          description: Include only the packages with required scope on the SBOM
        noBabel:
          type: boolean
          description: Do not use babel to perform usage analysis for JavaScript/TypeScript projects
        installDeps:
          type: boolean
          description: Install dependencies automatically for some projects. Defaults to true but disabled for containers and oci scans
          default: true
        projectId:
          type: string
          description: The UUID of the project. You must provide the UUID or the projectName and projectVersion (or all three)
        projectName:
          type: string
          description: Dependency Track project name. Default use the directory name
        projectGroup:
          type: string
          description: Dependency Track project group
        projectVersion:
          type: string
          description: Dependency Track project version
          default: ""
        autoCreate:
          type: boolean
          description: Dependency Track autoCreate value for BOM submissions
          default: true
        isLatest:
          type: boolean
          description: Dependency Track isLatest value for BOM submissions
        parentUUID:
          type: string
          description: UUID of the parent Dependency Track project
        parentProjectName:
          type: string
          description: Name of the parent Dependency Track project
        parentProjectVersion:
          type: string
          description: Version of the parent Dependency Track project
        serverUrl:
          type: string
          description: URL to the Dependency Track API server
        apiKey:
          type: string
          description: API key for the Dependency Track API server
        specVersion:
          type: string
          description: CycloneDX Specification version to use
          default: "1.7"
        format:
          type: array
          items:
            type: string
            enum:
              - cyclonedx
              - cdx
              - spdx
              - spdx-json
              - spdx3
              - spdx3-json
          description: Export format(s). Supports cyclonedx and spdx.
        filter:
          type: array
          items:
            type: string
          description: Filter components containing this word in purl. Multiple values allowed
        only:
          type: array
          items:
            type: string
          description: Include components only containing this word in purl. Useful to generate BOM with first party components alone. Multiple values allowed
        autoCompositions:
          type: boolean
          description: Automatically set compositions when the BOM was filtered. [boolean]
          default: true
        gitBranch:
          type: string
          description: Git branch used when cloning the repository. If not specified will use the default branch assigned to the repository
        lifecycle:
          type: string
          description: Product lifecycle for the generated BOM. Choices are pre-build, build, post-build.
        deep:
          type: boolean
          description: Perform deep searches for components. Useful while scanning C/C++ apps, live OS and oci images.
          default: false
        profile:
          type: string
          description: BOM profile to use for generation. Default generic. Choices are appsec, research.
          default: generic
        exclude:
          type: array
          items:
            type: string
          description: Additional glob pattern(s) to ignore
        includeCrypto:
          type: boolean
          description: Include crypto libraries as components.
          default: false
        standard:
          type: string
          description: The list of standards which may consist of regulations, industry or organizational-specific standards, maturity models, best practices, or any other requirements which can be evaluated against or attested to. Choices are asvs-4.0.3, bsimm-v13, masvs-2.0.0, nist_ssdf-1.1, pcissc-secure-slc-1.1, scvs-1.0.0, ssaf-DRAFT-2023-11
        minConfidence:
          type: number
          description: Minimum confidence needed for the identity of a component from 0 - 1, where 1 is 100% confidence.
        technique:
          type: array
          items:
            type: string
          description: Analysis technique to use
    CycloneDXSBOM:
      type: object
      externalDocs:
        description: See JSON Schema
        url: https://github.com/CycloneDX/specification/blob/1.6/schema/bom-1.6.schema.json
      properties:
        bomFormat:
          type: string
          description: Bill of Material format
          example: CycloneDX
        specVersion:
          type: string
          description: Specification version
          example: "1.6"
          enum:
            - "1.4"
            - "1.5"
            - "1.6"
        serialNumber:
          type: string
          description: Unique serial number
          example: "urn:uuid:f8f03e77-3c04-4c10-b1c2-ddaf0bd955ec"
        version:
          type: integer
          format: int64
          example: 1
        metadata:
          $ref: '#/components/schemas/Metadata'
        components:
          $ref: '#/components/schemas/Components'
        services:
          $ref: '#/components/schemas/Services'
        dependencies:
          $ref: '#/components/schemas/Dependencies'
        annotations:
          $ref: '#/components/schemas/Annotations'
        formulation:
          $ref: '#/components/schemas/Formulation'

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Message explaining the reason of the error
        details:
          type: array
          items:
            type: string
          description: Optionally gives details about the error

    Metadata:
      type: object

    Components:
      type: object

    Services:
      type: object

    Dependencies:
      type: object

    Annotations:
      type: object

    Formulation:
      type: object