diff --git a/httphandler/docs/docs.go b/httphandler/docs/docs.go new file mode 100644 index 00000000..b1d82a98 --- /dev/null +++ b/httphandler/docs/docs.go @@ -0,0 +1,24 @@ +// Package classification kubescape_microservice +// +// Documentation of our awesome API. +// +// Schemes: http +// BasePath: / +// Version: 1.0.0 +// Host: example.com +// +// Consumes: +// - application/json +// +// Produces: +// - application/json +// +// Security: +// - basic +// +// SecurityDefinitions: +// basic: +// type: basic +// +// swagger:meta +package docs diff --git a/httphandler/docs/ksMicroservice_swagger.go b/httphandler/docs/ksMicroservice_swagger.go new file mode 100644 index 00000000..2af3a0a5 --- /dev/null +++ b/httphandler/docs/ksMicroservice_swagger.go @@ -0,0 +1,148 @@ +package docs + +// swagger:route POST /v1/metrics metrics enableMetrics +// Trigger Kubescape support for Prometheus +// +// Enables support for Prometheus metrics. +// +// Responses: +// 200: enableMetricsResponse + +type enableMetricsResponse struct{} + +// swagger:response enableMetricsResponse +type enableMetricsResponseWrapper struct { + // in:body + Body enableMetricsResponse +} + +// swagger:route POST /v1/scan scanning triggerScan +// Trigger a kubescape scan. +// +// The server will return an ID and will execute the scanning asynchronously. +// +// Responses: +// 200: triggerScanResponse + +// swagger:enum TriggerScanTargetType +type TriggerScanTargetType string + +const ( + Framework TriggerScanTargetType = "framework" + Control TriggerScanTargetType = "control" +) + +type triggerScanParams struct { + // Results format. Same as `kubescape scan --format` + // + // default: json + // example: json + Format string `json:"format"` + // List of namespaces to exclude. Same as `kubescape scan --excluded-namespaces` + // + // example: ["kube-system", "armo-system"] + ExcludedNamespaces []string `json:"excludedNamespaces"` + // List of namespaces to include. Same as `kubescape scan --include-namespaces` + // + // example: ["litmus-tests", "known-bad"] + IncludeNamespaces []string `json:"includeNamespaces"` + // Use the cached artifacts instead of downloading (offline support) + // + // example: false + UseCachedArtifacts bool `json:"useCachedArtifacts"` + // Submit results to Kubescape Cloud. Same as `kubescape scan --submit`. + // + // example: true + Submit bool `json:"submit"` + // Deploy Kubescape K8s host-scanner DeamonSet in the scanned cluster (same as `kubescape scan --enable-host-scan`) + // + // example: true + HostScanner bool `json:"hostScanner"` + // Do not submit results to Kubescape Cloud. + // + // Same as `kubescape scan --keep-local` + KeepLocal bool `json:"keepLocal"` + // A Kubescape account ID to use for scanning. + // + // Same as `kubescape scan --account`. + // example: NewGuid() + Account string `json:"account"` + // Type of the scan target: either `framework` or `control`. + // + // example: framework + TargetType TriggerScanTargetType `json:"targetType"` + // 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"] + TargetNames []string `json:"targetNames"` +} + +// swagger:parameters triggerScan +type triggerScanParamsWrapper struct { + // Trigger scan parameters + // in:body + Body triggerScanParams + // Whether to wait for the result to complete. + // + // Triggers a synchronous scan. A synchronous scan returns the Scan results, and not a scan ID. Use synchronous scanning only in small clusters or with an increased timeout + // + // default: false + Wait bool `json:"wait"` + // Keep the results in local storage after returning. + // + // default: false + Keep bool `json:"keep"` +} + +// swagger:enum ScanResponseType +type ScanResponseType string + +const ( + V1Results ScanResponseType = "v1results" + Busy ScanResponseType = "busy" + NotBusy ScanResponseType = "notBusy" + Ready ScanResponseType = "ready" + Error ScanResponseType = "error" +) + +type triggerScanResponse struct { + // ID of the performed scan + Id string `json:"id"` + // Type of the response object + Type ScanResponseType `json:"type"` + // Response payload as list of bytes + Response interface{} `json:"response"` +} + +// The triggerScan response object +// swagger:response triggerScanResponse +type triggerScanResponseWrapper struct { + // in:body + Body triggerScanResponse +} + +// swagger:route GET /v1/results/{scanID} scanning getScanResults +// Read results of a previously performed scan. +// +// Responses: +// 200: getScanResultsResponse + + +// swagger:parameters getScanResults +type getScanResultsRequestWrapper struct { + // in:path + ScanID string `json:"scanID"` +} + +type getScanResultsResponse struct { + ID string `json:"id"` + Type string `json:"type"` + Response interface{} `json:"response"` +} + +// swagger:response +type getScanResultsResponseWrapper struct { + // in:body + Body getScanResultsResponse +} diff --git a/httphandler/main.go b/httphandler/main.go index 08035f2a..6fa1d25d 100644 --- a/httphandler/main.go +++ b/httphandler/main.go @@ -1,6 +1,7 @@ package main import ( + _ "github.com/armosec/kubescape/v2/httphandler/docs" "github.com/armosec/kubescape/v2/httphandler/listener" logger "github.com/dwertent/go-logger" ) diff --git a/swagger.yaml b/swagger.yaml new file mode 100644 index 00000000..6bcd1956 --- /dev/null +++ b/swagger.yaml @@ -0,0 +1,226 @@ +basePath: / +consumes: +- application/json +definitions: + enableMetricsResponse: + type: object + x-go-package: github.com/armosec/kubescape/v2/httphandler/docs + getScanResultsResponse: + properties: + id: + type: string + x-go-name: ID + response: + type: object + x-go-name: Response + type: + type: string + x-go-name: Type + type: object + x-go-package: github.com/armosec/kubescape/v2/httphandler/docs + triggerScanParams: + properties: + account: + description: |- + A Kubescape account ID to use for scanning. + + Same as `kubescape scan --account`. + example: NewGuid() + type: string + x-go-name: Account + excludedNamespaces: + description: List of namespaces to exclude. Same as `kubescape scan --excluded-namespaces` + example: + - kube-system + - armo-system + items: + type: string + type: array + x-go-name: ExcludedNamespaces + format: + default: json + description: Results format. Same as `kubescape scan --format` + example: json + type: string + x-go-name: Format + hostScanner: + description: Deploy Kubescape K8s host-scanner DeamonSet in the scanned cluster + (same as `kubescape scan --enable-host-scan`) + example: true + type: boolean + x-go-name: HostScanner + includeNamespaces: + description: List of 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` + type: boolean + x-go-name: KeepLocal + submit: + description: Submit results to Kubescape Cloud. Same as `kubescape scan --submit`. + example: true + type: boolean + x-go-name: Submit + targetNames: + 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: + description: |- + Type of the scan target: either `framework` or `control`. + framework Framework + control Control + enum: + - framework + - control + example: framework + type: string + x-go-enum-desc: |- + framework Framework + control Control + 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/armosec/kubescape/v2/httphandler/docs + triggerScanResponse: + properties: + id: + description: ID of the performed scan + type: string + x-go-name: Id + response: + description: Response payload as list of bytes + type: object + x-go-name: Response + type: + description: |- + Type of the response object + v1results V1Results + busy Busy + notBusy NotBusy + ready Ready + error Error + enum: + - v1results + - busy + - notBusy + - ready + - error + type: string + x-go-enum-desc: |- + v1results V1Results + busy Busy + notBusy NotBusy + ready Ready + error Error + x-go-name: Type + type: object + x-go-package: github.com/armosec/kubescape/v2/httphandler/docs +host: example.com +info: + description: Documentation of our awesome API. + title: kubescape_microservice + version: 1.0.0 +paths: + /v1/metrics: + post: + description: Enables support for Prometheus metrics + operationId: enableMetrics + responses: + "200": + $ref: '#/responses/enableMetricsResponse' + summary: Trigger Kubescape support for Prometheus + tags: + - metrics + /v1/results/{scanID}: + get: + operationId: getScanResults + parameters: + - in: path + name: scanID + required: true + type: string + x-go-name: ScanID + responses: + "200": + description: getScanResultsResponse + schema: + $ref: '#/definitions/getScanResultsResponse' + summary: Read results of a previously performed scan. + tags: + - scanning + /v1/scan: + post: + description: |- + The server will return an ID and will execute the + scanning asynchronously. + operationId: triggerScan + parameters: + - description: Trigger scan parameters + in: body + name: Body + schema: + $ref: '#/definitions/triggerScanParams' + - default: false + description: |- + Whether to wait for the result to complete. + + Triggers a synchronous scan. A synchronous scan returns the Scan results, and not a scan ID. Use synchronous scanning only in small clusters or with an increased timeout + in: query + name: wait + type: boolean + x-go-name: Wait + - default: false + description: Keep the results in local storage after returning. + in: query + name: keep + type: boolean + x-go-name: Keep + responses: + "200": + $ref: '#/responses/triggerScanResponse' + summary: Trigger a kubescape scan. + tags: + - scanning +produces: +- application/json +responses: + enableMetricsResponse: + description: "" + schema: + $ref: '#/definitions/enableMetricsResponse' + getScanResultsResponseWrapper: + description: "" + schema: + $ref: '#/definitions/getScanResultsResponse' + triggerScanResponse: + description: The triggerScan response object + schema: + $ref: '#/definitions/triggerScanResponse' +schemes: +- http +securityDefinitions: + basic: + type: basic +swagger: "2.0"