Checkmarx SCA API

openapi: 3.1.0
info:
  title: Checkmarx SCA API
  description: >-
    REST API for Checkmarx Software Composition Analysis (SCA),
    enabling programmatic management of open source security scanning,
    vulnerability detection, license compliance analysis, and
    dependency inventory for software projects.
  version: '1.0'
  contact:
    name: Checkmarx Support
    url: https://support.checkmarx.com/
  termsOfService: https://checkmarx.com/terms-of-use/
externalDocs:
  description: Checkmarx SCA API Documentation
  url: https://checkmarx.com/resource/documents/en/34965-68617-api.html
servers:
  - url: https://api-sca.checkmarx.net
    description: Checkmarx SCA Cloud (Production)
tags:
  - name: Authentication
    description: Obtain and manage authentication tokens
  - name: Packages
    description: Query open source package information
  - name: Projects
    description: Manage SCA projects
  - name: Risk Reports
    description: Retrieve vulnerability and risk analysis results
  - name: Scans
    description: Trigger and monitor dependency scans
  - name: Settings
    description: Manage project and organization settings
security:
  - bearerAuth: []
paths:
  /identity/connect/token:
    post:
      operationId: authenticate
      summary: Checkmarx Obtain access token
      description: >-
        Authenticate using OAuth 2.0 client credentials to obtain a
        bearer token for accessing the Checkmarx SCA API.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - username
                - password
                - acr_values
                - scope
              properties:
                grant_type:
                  type: string
                  enum:
                    - password
                  description: OAuth 2.0 grant type
                username:
                  type: string
                  description: SCA account username
                password:
                  type: string
                  description: SCA account password
                acr_values:
                  type: string
                  description: Tenant identifier
                  example: Tenant:your-tenant
                scope:
                  type: string
                  description: API access scope
                  example: sca_api
                client_id:
                  type: string
                  description: OAuth client ID
                  example: sca_resource_owner
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Invalid credentials
      security: []
  /risk-management/projects:
    get:
      operationId: listProjects
      summary: Checkmarx List all projects
      description: Retrieve a list of all SCA projects for the authenticated tenant.
      tags:
        - Projects
      responses:
        '200':
          description: List of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized
    post:
      operationId: createProject
      summary: Checkmarx Create a new project
      description: Create a new SCA project for scanning open source dependencies.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /risk-management/projects/{projectId}:
    get:
      operationId: getProject
      summary: Checkmarx Get project details
      description: Retrieve details of a specific SCA project.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    put:
      operationId: updateProject
      summary: Checkmarx Update a project
      description: Update the configuration of an existing SCA project.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
      responses:
        '204':
          description: Project updated
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    delete:
      operationId: deleteProject
      summary: Checkmarx Delete a project
      description: Delete an SCA project and all associated scan data.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '204':
          description: Project deleted
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /risk-management/scans:
    get:
      operationId: listScans
      summary: Checkmarx List scans
      description: >-
        Retrieve a list of SCA scans with optional filtering by
        project ID.
      tags:
        - Scans
      parameters:
        - name: projectId
          in: query
          description: Filter by project ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of scans
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Scan'
        '401':
          description: Unauthorized
    post:
      operationId: createScan
      summary: Checkmarx Trigger a new scan
      description: >-
        Initiate a new SCA scan for a project by uploading a source
        archive or pointing to a repository.
      tags:
        - Scans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScanRequest'
      responses:
        '201':
          description: Scan created and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /risk-management/scans/{scanId}:
    get:
      operationId: getScan
      summary: Checkmarx Get scan details
      description: Retrieve details and status of a specific SCA scan.
      tags:
        - Scans
      parameters:
        - $ref: '#/components/parameters/scanId'
      responses:
        '200':
          description: Scan details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scan'
        '401':
          description: Unauthorized
        '404':
          description: Scan not found
  /risk-management/risk-reports/{projectId}:
    get:
      operationId: getRiskReport
      summary: Checkmarx Get project risk report
      description: >-
        Retrieve the risk report for a project, including vulnerability
        summary and risk score.
      tags:
        - Risk Reports
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Risk report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskReport'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /risk-management/risk-reports/{projectId}/vulnerabilities:
    get:
      operationId: listProjectVulnerabilities
      summary: Checkmarx List project vulnerabilities
      description: >-
        Retrieve all vulnerabilities found in a project from the most
        recent scan.
      tags:
        - Risk Reports
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: List of vulnerabilities
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Vulnerability'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /risk-management/risk-reports/{projectId}/packages:
    get:
      operationId: listProjectPackages
      summary: Checkmarx List project packages
      description: >-
        Retrieve all open source packages detected in a project with
        their license and vulnerability information.
      tags:
        - Risk Reports
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: List of packages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Package'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /risk-management/risk-reports/{projectId}/licenses:
    get:
      operationId: listProjectLicenses
      summary: Checkmarx List project licenses
      description: >-
        Retrieve all licenses detected across open source packages in
        a project.
      tags:
        - Risk Reports
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: List of licenses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/License'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /packages/{packageType}/{packageName}/{version}:
    get:
      operationId: getPackageDetails
      summary: Checkmarx Get package details
      description: >-
        Retrieve detailed information about a specific open source
        package version, including known vulnerabilities.
      tags:
        - Packages
      parameters:
        - name: packageType
          in: path
          required: true
          description: Package ecosystem type
          schema:
            type: string
            enum:
              - npm
              - maven
              - nuget
              - pypi
              - rubygems
              - go
              - packagist
              - cargo
        - name: packageName
          in: path
          required: true
          description: Package name
          schema:
            type: string
        - name: version
          in: path
          required: true
          description: Package version
          schema:
            type: string
      responses:
        '200':
          description: Package details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageDetails'
        '401':
          description: Unauthorized
        '404':
          description: Package not found
  /settings/projects/{projectId}:
    get:
      operationId: getProjectSettings
      summary: Checkmarx Get project settings
      description: Retrieve scan and policy settings for a project.
      tags:
        - Settings
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Project settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectSettings'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    put:
      operationId: updateProjectSettings
      summary: Checkmarx Update project settings
      description: Update scan and policy settings for a project.
      tags:
        - Settings
      parameters:
        - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectSettings'
      responses:
        '204':
          description: Settings updated
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '404':
          description: Project not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 bearer token obtained from the authentication endpoint
  parameters:
    projectId:
      name: projectId
      in: path
      required: true
      description: Project unique identifier
      schema:
        type: string
        format: uuid
    scanId:
      name: scanId
      in: path
      required: true
      description: Scan unique identifier
      schema:
        type: string
        format: uuid
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: OAuth 2.0 access token
        token_type:
          type: string
          description: Token type
          example: Bearer
        expires_in:
          type: integer
          description: Token expiration time in seconds
    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Project unique identifier
        name:
          type: string
          description: Project name
        createdOn:
          type: string
          format: date-time
          description: Project creation timestamp
        tenantId:
          type: string
          description: Tenant identifier
        assignedTeams:
          type: array
          items:
            type: string
          description: Teams assigned to the project
        lastScanDate:
          type: string
          format: date-time
          description: Timestamp of the most recent scan
        riskScore:
          type: number
          format: float
          description: Overall risk score for the project
        totalPackages:
          type: integer
          description: Total number of packages detected
        highVulnerabilityCount:
          type: integer
          description: Number of high severity vulnerabilities
        mediumVulnerabilityCount:
          type: integer
          description: Number of medium severity vulnerabilities
        lowVulnerabilityCount:
          type: integer
          description: Number of low severity vulnerabilities
    CreateProjectRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Project name
        assignedTeams:
          type: array
          items:
            type: string
          description: Team IDs to assign to the project
    UpdateProjectRequest:
      type: object
      properties:
        name:
          type: string
          description: Updated project name
        assignedTeams:
          type: array
          items:
            type: string
          description: Updated team assignments
    Scan:
      type: object
      properties:
        scanId:
          type: string
          format: uuid
          description: Scan unique identifier
        projectId:
          type: string
          format: uuid
          description: Associated project ID
        status:
          type: string
          enum:
            - Queued
            - Scanning
            - Done
            - Failed
            - Canceled
          description: Current scan status
        createdOn:
          type: string
          format: date-time
          description: Scan creation timestamp
        updatedOn:
          type: string
          format: date-time
          description: Last update timestamp
        origin:
          type: string
          description: Scan trigger origin
          enum:
            - API
            - CLI
            - Plugin
            - Upload
        riskReportId:
          type: string
          format: uuid
          description: Associated risk report ID
    CreateScanRequest:
      type: object
      required:
        - projectId
      properties:
        projectId:
          type: string
          format: uuid
          description: Project to scan
        sourceType:
          type: string
          enum:
            - Upload
            - RemoteRepository
          description: Source code input method
    RiskReport:
      type: object
      properties:
        projectId:
          type: string
          format: uuid
          description: Project identifier
        riskScore:
          type: number
          format: float
          description: Overall risk score (0-10)
        totalPackages:
          type: integer
          description: Total number of open source packages
        directPackages:
          type: integer
          description: Number of direct dependency packages
        totalOutdatedPackages:
          type: integer
          description: Number of outdated packages
        vulnerabilitySummary:
          $ref: '#/components/schemas/VulnerabilitySummary'
    VulnerabilitySummary:
      type: object
      properties:
        highVulnerabilityCount:
          type: integer
          description: Number of high severity vulnerabilities
        mediumVulnerabilityCount:
          type: integer
          description: Number of medium severity vulnerabilities
        lowVulnerabilityCount:
          type: integer
          description: Number of low severity vulnerabilities
        totalVulnerabilityCount:
          type: integer
          description: Total number of vulnerabilities
    Vulnerability:
      type: object
      properties:
        id:
          type: string
          description: Vulnerability identifier (CVE ID)
        cveName:
          type: string
          description: CVE name
        score:
          type: number
          format: float
          description: CVSS score
        severity:
          type: string
          enum:
            - High
            - Medium
            - Low
          description: Vulnerability severity
        publishDate:
          type: string
          format: date-time
          description: Vulnerability publish date
        packageId:
          type: string
          description: Affected package identifier
        description:
          type: string
          description: Vulnerability description
        recommendations:
          type: string
          description: Recommended remediation
        cwe:
          type: string
          description: CWE identifier
        isIgnored:
          type: boolean
          description: Whether the vulnerability has been marked as ignored
        references:
          type: array
          items:
            type: string
            format: uri
          description: External reference URLs
    Package:
      type: object
      properties:
        id:
          type: string
          description: Package identifier
        name:
          type: string
          description: Package name
        version:
          type: string
          description: Package version
        packageRepository:
          type: string
          description: Package ecosystem (npm, maven, etc.)
        isDirectDependency:
          type: boolean
          description: Whether this is a direct dependency
        licenses:
          type: array
          items:
            type: string
          description: License names
        highVulnerabilityCount:
          type: integer
          description: Number of high severity vulnerabilities
        mediumVulnerabilityCount:
          type: integer
          description: Number of medium severity vulnerabilities
        lowVulnerabilityCount:
          type: integer
          description: Number of low severity vulnerabilities
        riskScore:
          type: number
          format: float
          description: Package risk score
        outdated:
          type: boolean
          description: Whether the package is outdated
        newestVersion:
          type: string
          description: Newest available version
    PackageDetails:
      type: object
      properties:
        type:
          type: string
          description: Package ecosystem type
        name:
          type: string
          description: Package name
        version:
          type: string
          description: Package version
        description:
          type: string
          description: Package description
        licenses:
          type: array
          items:
            type: string
          description: Package licenses
        vulnerabilities:
          type: array
          items:
            $ref: '#/components/schemas/Vulnerability'
          description: Known vulnerabilities for this package
    License:
      type: object
      properties:
        name:
          type: string
          description: License name
        riskLevel:
          type: string
          enum:
            - High
            - Medium
            - Low
            - Unknown
          description: License risk level
        copyleftType:
          type: string
          enum:
            - Yes
            - Partial
            - No
            - Unknown
          description: Whether the license has copyleft requirements
        referenceUrl:
          type: string
          format: uri
          description: License reference URL
        packageCount:
          type: integer
          description: Number of packages using this license
    ProjectSettings:
      type: object
      properties:
        enableExploitablePath:
          type: boolean
          description: Enable exploitable path analysis
        enableSastIntegration:
          type: boolean
          description: Enable SAST integration for contextual risk
        policySeverity:
          type: string
          enum:
            - High
            - Medium
            - Low
            - None
          description: Minimum severity to enforce policies