From ac5e7069daaf0a8cb7ed835e0519339936dae9fb Mon Sep 17 00:00:00 2001 From: David Wertenteil Date: Sun, 22 May 2022 10:59:48 +0300 Subject: [PATCH] update readme --- httphandler/README.md | 92 ++++++++++++++++--- httphandler/examples/prometheus/README.md | 11 +-- .../handlerequests/v1/requestshandler.go | 4 +- 3 files changed, 80 insertions(+), 27 deletions(-) diff --git a/httphandler/README.md b/httphandler/README.md index cfb51045..18fc0871 100644 --- a/httphandler/README.md +++ b/httphandler/README.md @@ -1,26 +1,85 @@ # Kubescape HTTP Handler Package -> This is a beta version, we might make some changes before publishing the official Prometheus support - -Running `kubescape` will start up a webserver on port `8080` which will serve the following paths: +Running `kubescape` will start up a webserver on port `8080` which will serve the following API's: ### Trigger scan -* POST `/v1/scan` - Trigger a kubescape scan. The server will return an ID and will execute the scanning asynchronously -* * `wait=true`: scan synchronously (return results and not ID). Use only in small clusters are with an increased timeout. default is `wait=false` -* * `keep=true`: Do not delete results from local storage after returning. default is `keep=false` +* POST `/v1/scan` - trigger a kubescape scan. The server will return an ID and will execute the scanning asynchronously. the request body should look [as followed](#trigger-scan-object). +* * `wait=true`: scan synchronously (return results and not ID). Use only in small clusters or with an increased timeout. default is `wait=false` +* * `keep=true`: do not delete results from local storage after returning. default is `keep=false` +* POST `/v1/metrics` - trigger kubescape for Prometheus support. [read more](examples/prometheus/README.md) + +[Response](#response-object): + +``` +{ + "id": , // scan ID + "type": "busy", // response object type + "response": // message indicating scanning is still in process +} +``` + +> When scanning was triggered with the `wait=true` query param, the response is like the [`/v1/results` API](#get-results) response ### Get results -* GET `/v1/results` - Request kubescape scan results -* * query `id=` -> ID returned when triggering the scan action. If empty will return latest results -* * query `keep=true` -> Do not delete results from local storage after returning. default is `keep=false` +* GET `/v1/results` - request kubescape scan results +* * query `id=` -> request results of a specific scan ID. If empty will return latest results +* * query `keep=true` -> keep the results in the local storage after returning. default is `keep=false` - the results will be deleted from local storage after they are returned +[Response](#response-object): + +When scanning was done successfully +``` +{ + "id": , // scan ID + "type": "v1results", // response object type + "response": // v1 results payload +} +``` + +When scanning failed +``` +{ + "id": , // scan ID + "type": "error", // response object type + "response": // error string +} +``` + +When scanning is in progress +``` +{ + "id": , // scan ID + "type": "busy", // response object type + "response": // message indicating scanning is still in process +} +``` ### Check scanning progress status Check the scanning status - is the scanning in progress or done. This is meant for a waiting mechanize since the API does not return the entire results object when the scanning is done * GET `/v1/status` - Request kubescape scan status * * query `id=` -> Check status of a specific scan. If empty will check if any scan is in progress +[Response](#response-object): + +When scanning is in progress +``` +{ + "id": , // scan ID + "type": "busy", // response object type + "response": // message indicating scanning is still in process +} +``` + +When scanning is not in progress +``` +{ + "id": , // scan ID + "type": "notBusy", // response object type + "response": // message indicating scanning is done in process +} +``` + ### Delete cached results * DELETE `/v1/results` - Delete kubescape scan results from storage. If empty will delete latest results * * query `id=`: Delete ID of specific results @@ -32,10 +91,10 @@ Check the scanning status - is the scanning in progress or done. This is meant f * `/livez` - will respond 200 is server is alive * `/readyz` - will respond 200 if server can receive requests -## Trigger Kubescape scan +## Objects + +### Trigger scan object -POST /v1/scan -body: ``` { "format": , // results format [default: json] (same as 'kubescape scan --format') @@ -51,7 +110,8 @@ body: } ``` -Response body: +### Response object + ``` { "id": , // scan ID @@ -59,10 +119,12 @@ Response body: "response": // response payload as list of bytes } ``` +#### Response object types -Response body types: * "v1results" - v1 results object -* "id" - id string +* "busy" - server is busy processing previous requests +* "notBusy" - server is not busy processing previous requests +* "ready" - server is done processing request and results are ready * "error" - error object ## API Examples diff --git a/httphandler/examples/prometheus/README.md b/httphandler/examples/prometheus/README.md index 8d283b97..d97da1ee 100644 --- a/httphandler/examples/prometheus/README.md +++ b/httphandler/examples/prometheus/README.md @@ -110,13 +110,4 @@ kubescape_control_count_resources_excluded{name="",url=" kubescape_control_count_resources_passed{name="",url="",severity=""} ``` -#### Resources metrics -The resources metrics give you the ability to prioritize fixing the resources by the number of controls that failed - -``` -# Number of controls that failed for this particular resource -kubescape_resource_count_controls_failed{apiVersion="<>",kind="<>",namespace="<>",name="<>"} - -# Number of controls that where excluded for this particular resource -kubescape_resource_count_controls_excluded{apiVersion="<>",kind="<>",namespace="<>",name="<>"} -``` \ No newline at end of file + \ No newline at end of file diff --git a/httphandler/handlerequests/v1/requestshandler.go b/httphandler/handlerequests/v1/requestshandler.go index d259e726..a69eefcc 100644 --- a/httphandler/handlerequests/v1/requestshandler.go +++ b/httphandler/handlerequests/v1/requestshandler.go @@ -148,8 +148,8 @@ func (handler *HTTPHandler) Results(w http.ResponseWriter, r *http.Request) { if resultsQueryParams.ScanID == "" { // if no scan found logger.L().Info("empty scan ID") - w.WriteHeader(http.StatusBadRequest) // Should we return ok? - response.Response = "latest scan not found. trigger again" + w.WriteHeader(http.StatusBadRequest) + response.Response = "latest scan not found" response.Type = utilsapisv1.ErrorScanResponseType w.Write(responseToBytes(&response)) return