basePath: /
consumes:
- application/json
definitions:
  PostScanRequest:
    description: A request to trigger a Kubescape scan
    properties:
      account:
        description: |-
          A Kubescape account ID to use for scanning.

          Same as `kubescape scan --account`.
        example: d13791eb-19b1-4222-867b-9a7c1799cfac
        format: uuid4
        type: string
        x-go-name: Account
      excludedNamespaces:
        description: |-
          Namespaces to exclude.

          Same as `kubescape scan --excluded-namespaces`.
        example:
        - kubescape
        - kube-system
        items:
          type: string
        type: array
        x-go-name: ExcludedNamespaces
      failThreshold:
        description: |-
          Threshold for a failing score.

          Scores higher than the provided value will be considered failing.
        example: 42
        format: float
        type: number
        x-go-name: FailThreshold
      complianceThreshold:
        description: |-
          Threshold for a failing score.

          Scores lower than the provided value will be considered failing.
        example: 42
        format: float
        type: number
        x-go-name: ComplianceThreshold
      format:
        description: |-
          Format of the results.

          Same as `kubescape scan --format`.
        example: json
        type: string
        x-go-name: Format
      hostScanner:
        description: |-
          Deploy the Kubescape Kubernetes Host Scanner

          Deploys the Armo K8s Host Scanner DeamonSet in the scanned cluster to collect data from certain controls.
        example: true
        type: boolean
        x-go-name: HostScanner
      includeNamespaces:
        description: |-
          Namespaces to include.

          Same as `kubescape scan --include-namespaces`.
        example:
        - litmus-tests
        - known-bad
        items:
          type: string
        type: array
        x-go-name: IncludeNamespaces
      keepLocal:
        description: |-
          Do not submit results to Kubescape Cloud.

          Same as `kubescape scan --keep-local`
        example: true
        type: boolean
        x-go-name: KeepLocal
      submit:
        description: |-
          Submit results to Kubescape Cloud.

        type: boolean
        x-go-name: Submit
      targetNames:
        default:
        - all
        description: |-
          Name of the scan targets.

          For example, if you select `targetType: "framework"`, you can trigger a scan using the NSA and MITRE ATT&CK Framework by passing `targetNames: ["nsa", "mitre"].
        example:
        - nsa
        - mitre
        items:
          type: string
        type: array
        x-go-name: TargetNames
      targetType:
        default: framework
        description: |-
          Type of the target. "framework" or "control".
          Framework KindFramework
          Control KindControl
          Rule KindRule
        enum:
        - Framework
        - Control
        - Rule
        example: control
        type: string
        x-go-enum-desc: |-
          Framework KindFramework
          Control KindControl
          Rule KindRule
        x-go-name: TargetType
      useCachedArtifacts:
        description: Use the cached artifacts instead of downloading (offline support)
        example: false
        type: boolean
        x-go-name: UseCachedArtifacts
    type: object
    x-go-package: github.com/kubescape/opa-utils/httpserver/meta/v1
  Response:
    description: A Scan Response object
    properties:
      id:
        description: ID of the scan
        example: d13791eb-19b1-4222-867b-9a7c1799cfac
        format: uuid4
        type: string
        x-go-name: ID
      response:
        description: The actual Response payload
        example: d13791eb-19b1-4222-867b-9a7c1799cfac
        type: object
        x-go-name: Response
      type:
        description: |-
          Type of this response
          id IDScanResponseType  Deprecated: will return busy / notBusy instead
          error ErrorScanResponseType  ErrorScanResponseType indicates a response that reports an error
          v1results ResultsV1ScanResponseType  ResultsV1ScanResponseType indicates a response that carries a v1 Results object as payload
          busy BusyScanResponseType  BusyScanResponseType indicates that a server is busy with a previous request
          notBusy NotBusyScanResponseType  NotBusyScanResponseType indicates that a server is not busy with a previous request
          ready ReadyScanResponseType  ReadyScanResponseType indicates that a server has successfully completed a request
        enum:
        - id
        - error
        - v1results
        - busy
        - notBusy
        - ready
        example: busy
        type: string
        x-go-enum-desc: |-
          id IDScanResponseType  Deprecated: will return busy / notBusy instead
          error ErrorScanResponseType  ErrorScanResponseType indicates a response that reports an error
          v1results ResultsV1ScanResponseType  ResultsV1ScanResponseType indicates a response that carries a v1 Results object as payload
          busy BusyScanResponseType  BusyScanResponseType indicates that a server is busy with a previous request
          notBusy NotBusyScanResponseType  NotBusyScanResponseType indicates that a server is not busy with a previous request
          ready ReadyScanResponseType  ReadyScanResponseType indicates that a server has successfully completed a request
        x-go-name: Type
    type: object
    x-go-package: github.com/kubescape/opa-utils/httpserver/meta/v1
info:
  description: 'The Kubescape Microservice API allows clients to interact with a Kubescape
    instance running in a Kubernetes cluster: trigger scans, retrieve and delete their
    results, enable exporting metrics to Prometheus etc.'
  title: Kubescape Microservice
  version: 1.0.0
paths:
  /livez:
    get:
      description: Returns the liveness status of the Kubescape microservice.
      operationId: getLiveness
      responses:
        "200":
          $ref: '#/responses/livenessProbeOK'
      summary: Returns Kubescape’s liveness status
      tags:
      - metrics
  /readyz:
    get:
      description: Returns the readiness status of the Kubescape microservice.
      operationId: getReadiness
      responses:
        "200":
          $ref: '#/responses/readinessProbeOK'
      summary: Returns Kubescape’s readiness status
      tags:
      - metrics
  /v1/metrics:
    get:
      description: Enables support for Prometheus metrics, runs a scan and returns
        its result in Prometheus metrics format.
      operationId: getMetrics
      responses:
        "200":
          $ref: '#/responses/enableMetricsResponse'
      summary: Returns current scan metrics in Prometheus format
      tags:
      - metrics
  /v1/results:
    delete:
      description: Deletes Kubescape scan results from storage.
      operationId: deleteScanResults
      parameters:
      - description: ID of the requested scan. If empty or not provided, defaults
          to the latest scan.
        in: query
        name: id
        type: string
        x-go-name: ScanID
      - default: false
        description: |-
          Keep the results in local storage after returning them.

          By default, the Kubescape Microservice will delete scan results.
        in: query
        name: keep
        type: boolean
        x-go-name: KeepResults
      - default: false
        description: Whether to delete all results
        in: query
        name: all
        type: boolean
        x-go-name: AllResults
      responses:
        "200":
          $ref: '#/responses/scanResponse'
        "400":
          $ref: '#/responses/scanResponseBadRequest'
      summary: Deletes results of a scan
      tags:
      - scanning
    get:
      description: Returns the results of Kubescape scans
      operationId: getScanResults
      parameters:
      - description: ID of the requested scan. If empty or not provided, defaults
          to the latest scan.
        in: query
        name: id
        type: string
        x-go-name: ScanID
      - default: false
        description: |-
          Keep the results in local storage after returning them.

          By default, the Kubescape Microservice will delete scan results.
        in: query
        name: keep
        type: boolean
        x-go-name: KeepResults
      responses:
        "200":
          $ref: '#/responses/scanResponse'
        "204":
          $ref: '#/responses/scanResponseNoContent'
        "400":
          $ref: '#/responses/scanResponseBadRequest'
      summary: Returns results of a scan
      tags:
      - scanning
  /v1/scan:
    post:
      description: The server will return a scan ID and execute the scan.
      operationId: triggerScan
      parameters:
      - default: false
        description: Wait for scanning to complete (synchronous request)
        in: query
        name: wait
        type: boolean
        x-go-name: ReturnResults
      - default: false
        description: Do not delete results after returning (relevant only for synchronous
          requests)
        in: query
        name: keep
        type: boolean
        x-go-name: KeepResults
      - description: Scan parameters
        in: body
        name: Body
        schema:
          $ref: '#/definitions/PostScanRequest'
      responses:
        "200":
          $ref: '#/responses/scanResponse'
        "400":
          $ref: '#/responses/scanResponseBadRequest'
        "500":
          $ref: '#/responses/scanResponseInternalServerError'
      summary: Triggers a Kubescape scan
      tags:
      - scanning
  /v1/status:
    get:
      description: |-
        Returns the current status of a scan with a given ID: whether it completed or not. Intended for asynchronous scanning, so you can check when a result is ready and fetch the results.

        When a scan is in progress, the response's `type` will be `busy`. When a scan is complete, `type` is `notBusy`.
      operationId: getStatus
      parameters:
      - description: ID of the scan to check
        format: uuid4
        in: query
        name: id
        type: string
        x-go-name: ScanID
      responses:
        "200":
          $ref: '#/responses/scanResponse'
      summary: Returns a scan’s status
      tags:
      - scanning
produces:
- application/json
responses:
  enableMetricsResponse:
    description: Provided Prometheus metrics
    schema:
      type: string
  livenessProbeOK:
    description: Kubescape Microservice API is alive
  readinessProbeOK:
    description: Kubescape Microservice API is ready to serve requests
  scanResponse:
    description: A Scan Response object
    schema:
      $ref: '#/definitions/Response'
  scanResponseBadRequest:
    description: A Scan Response that occures after malformed requests
    schema:
      allOf:
      - properties:
          id:
            description: ID of the scan
            example: d13791eb-19b1-4222-867b-9a7c1799cfac
            format: uuid4
            type: string
            x-go-name: ID
          response:
            description: The actual Response payload
            example: d13791eb-19b1-4222-867b-9a7c1799cfac
            type: object
            x-go-name: Response
          type:
            description: |-
              Type of this response
              id IDScanResponseType  Deprecated: will return busy / notBusy instead
              error ErrorScanResponseType  ErrorScanResponseType indicates a response that reports an error
              v1results ResultsV1ScanResponseType  ResultsV1ScanResponseType indicates a response that carries a v1 Results object as payload
              busy BusyScanResponseType  BusyScanResponseType indicates that a server is busy with a previous request
              notBusy NotBusyScanResponseType  NotBusyScanResponseType indicates that a server is not busy with a previous request
              ready ReadyScanResponseType  ReadyScanResponseType indicates that a server has successfully completed a request
            enum:
            - id
            - error
            - v1results
            - busy
            - notBusy
            - ready
            example: busy
            type: string
            x-go-enum-desc: |-
              id IDScanResponseType  Deprecated: will return busy / notBusy instead
              error ErrorScanResponseType  ErrorScanResponseType indicates a response that reports an error
              v1results ResultsV1ScanResponseType  ResultsV1ScanResponseType indicates a response that carries a v1 Results object as payload
              busy BusyScanResponseType  BusyScanResponseType indicates that a server is busy with a previous request
              notBusy NotBusyScanResponseType  NotBusyScanResponseType indicates that a server is not busy with a previous request
              ready ReadyScanResponseType  ReadyScanResponseType indicates that a server has successfully completed a request
            x-go-name: Type
        type: object
      - properties:
          response:
            example: 'failed to parse query params, reason: schema: invalid path "waitr"'
            type: object
            x-go-name: Resp
          type:
            example: error
            type: string
            x-go-name: Type
        type: object
  scanResponseInternalServerError:
    description: A Scan Response that occures after malformed requests
    schema:
      allOf:
      - properties:
          id:
            description: ID of the scan
            example: d13791eb-19b1-4222-867b-9a7c1799cfac
            format: uuid4
            type: string
            x-go-name: ID
          response:
            description: The actual Response payload
            example: d13791eb-19b1-4222-867b-9a7c1799cfac
            type: object
            x-go-name: Response
          type:
            description: |-
              Type of this response
              id IDScanResponseType  Deprecated: will return busy / notBusy instead
              error ErrorScanResponseType  ErrorScanResponseType indicates a response that reports an error
              v1results ResultsV1ScanResponseType  ResultsV1ScanResponseType indicates a response that carries a v1 Results object as payload
              busy BusyScanResponseType  BusyScanResponseType indicates that a server is busy with a previous request
              notBusy NotBusyScanResponseType  NotBusyScanResponseType indicates that a server is not busy with a previous request
              ready ReadyScanResponseType  ReadyScanResponseType indicates that a server has successfully completed a request
            enum:
            - id
            - error
            - v1results
            - busy
            - notBusy
            - ready
            example: busy
            type: string
            x-go-enum-desc: |-
              id IDScanResponseType  Deprecated: will return busy / notBusy instead
              error ErrorScanResponseType  ErrorScanResponseType indicates a response that reports an error
              v1results ResultsV1ScanResponseType  ResultsV1ScanResponseType indicates a response that carries a v1 Results object as payload
              busy BusyScanResponseType  BusyScanResponseType indicates that a server is busy with a previous request
              notBusy NotBusyScanResponseType  NotBusyScanResponseType indicates that a server is not busy with a previous request
              ready ReadyScanResponseType  ReadyScanResponseType indicates that a server has successfully completed a request
            x-go-name: Type
        type: object
      - properties:
          id:
            example: '""'
            type: string
            x-go-name: ID
          response:
            example: 'failed to scan. reason: ''empty list of resources'''
            type: object
            x-go-name: Resp
          type:
            example: error
            type: string
            x-go-name: Type
        type: object
  scanResponseNoContent:
    description: |-
      A Scan Response that indicates no response body.

      Kubescape generates this response, for example, when results with given ID do not exist.
schemes:
- http
swagger: "2.0"
