mirror of
https://github.com/kubescape/kubescape.git
synced 2026-04-05 02:07:01 +00:00
95e88f8581
* add compliance-threshold, deprecate fail-threshold Signed-off-by: YiscahLevySilas1 <yiscahls@armosec.io> * update opa-utils version Signed-off-by: YiscahLevySilas1 <yiscahls@armosec.io> * update opa-utils version for fix in compliance score Signed-off-by: YiscahLevySilas1 <yiscahls@armosec.io> --------- Signed-off-by: YiscahLevySilas1 <yiscahls@armosec.io>
457 lines
16 KiB
YAML
457 lines
16 KiB
YAML
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"
|