mirror of
https://github.com/kubescape/kubescape.git
synced 2026-04-15 06:58:11 +00:00
update readme
This commit is contained in:
David Wertenteil
+77
-15
@@ -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": <str>, // scan ID
|
||||
"type": "busy", // response object type
|
||||
"response": <message:string> // 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=<string>` -> 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=<string>` -> 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": <str>, // scan ID
|
||||
"type": "v1results", // response object type
|
||||
"response": <object:v1results> // v1 results payload
|
||||
}
|
||||
```
|
||||
|
||||
When scanning failed
|
||||
```
|
||||
{
|
||||
"id": <str>, // scan ID
|
||||
"type": "error", // response object type
|
||||
"response": <error:string> // error string
|
||||
}
|
||||
```
|
||||
|
||||
When scanning is in progress
|
||||
```
|
||||
{
|
||||
"id": <str>, // scan ID
|
||||
"type": "busy", // response object type
|
||||
"response": <message:string> // 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=<string>` -> 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": <str>, // scan ID
|
||||
"type": "busy", // response object type
|
||||
"response": <message:string> // message indicating scanning is still in process
|
||||
}
|
||||
```
|
||||
|
||||
When scanning is not in progress
|
||||
```
|
||||
{
|
||||
"id": <str>, // scan ID
|
||||
"type": "notBusy", // response object type
|
||||
"response": <message:string> // 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=<string>`: 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": <str>, // results format [default: json] (same as 'kubescape scan --format')
|
||||
@@ -51,7 +110,8 @@ body:
|
||||
}
|
||||
```
|
||||
|
||||
Response body:
|
||||
### Response object
|
||||
|
||||
```
|
||||
{
|
||||
"id": <str>, // scan ID
|
||||
@@ -59,10 +119,12 @@ Response body:
|
||||
"response": <object:interface> // 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
|
||||
|
||||
@@ -110,13 +110,4 @@ kubescape_control_count_resources_excluded{name="<control name>",url="<docs url>
|
||||
kubescape_control_count_resources_passed{name="<control name>",url="<docs url>",severity="<control severity>"} <counter>
|
||||
```
|
||||
|
||||
#### 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="<>"} <counter>
|
||||
|
||||
# Number of controls that where excluded for this particular resource
|
||||
kubescape_resource_count_controls_excluded{apiVersion="<>",kind="<>",namespace="<>",name="<>"} <counter>
|
||||
```
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user