ContextQMD
Back to Kubescape

Kubescape HTTP Handler

httphandler/README.md

4.0.67.6 KB
Original Source

Kubescape HTTP Handler

The HTTP Handler provides a REST API for running Kubescape scans programmatically. This enables integration with CI/CD pipelines, custom dashboards, and automation workflows.

Table of Contents

Overview

When running Kubescape as a service, it starts a web server on port 8080 that exposes REST APIs for:

  • Triggering security scans (async or sync)
  • Retrieving scan results
  • Checking scan status
  • Managing cached results

API Reference

Trigger Scan

Endpoint: POST /v1/scan

Triggers a Kubescape scan. By default, scans run asynchronously and return a scan ID immediately.

Query Parameters:

ParameterTypeDefaultDescription
waitboolfalseWait for scan to complete (synchronous mode)
keepboolfalseKeep results in cache after returning

Request Body: See Trigger Scan Object

Response (async):

json
{
  "id": "scan-12345",
  "type": "busy",
  "response": "scanning in progress"
}

Response (sync with wait=true): Same as Get Results response.

Get Results

Endpoint: GET /v1/results

Retrieve scan results.

Query Parameters:

ParameterTypeDefaultDescription
idstring-Scan ID. If empty, returns latest results
keepboolfalseKeep results in cache after returning

Response (success):

json
{
  "id": "scan-12345",
  "type": "v1results",
  "response": { /* scan results object */ }
}

Response (error):

json
{
  "id": "scan-12345",
  "type": "error",
  "response": "error message"
}

Response (in progress):

json
{
  "id": "scan-12345",
  "type": "busy",
  "response": "scanning in progress"
}

Check Status

Endpoint: GET /v1/status

Check if a scan is still in progress. Useful for polling without retrieving full results.

Query Parameters:

ParameterTypeDefaultDescription
idstring-Scan ID. If empty, checks if any scan is in progress

Response (in progress):

json
{
  "id": "scan-12345",
  "type": "busy",
  "response": "scanning in progress"
}

Response (complete):

json
{
  "id": "scan-12345",
  "type": "notBusy",
  "response": "scanning completed"
}

Delete Results

Endpoint: DELETE /v1/results

Delete cached scan results.

Query Parameters:

ParameterTypeDefaultDescription
idstring-Scan ID to delete. If empty, deletes latest
allboolfalseDelete all cached results

Request/Response Objects

Trigger Scan Object

json
{
  "format": "json",
  "excludedNamespaces": ["kube-system", "kube-public"],
  "includeNamespaces": ["production", "staging"],
  "useCachedArtifacts": false,
  "keepLocal": true,
  "account": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "accessKey": "your-access-key",
  "targetType": "framework",
  "targetNames": ["nsa", "mitre"]
}
FieldTypeDescription
formatstringOutput format (default: json)
excludedNamespaces[]stringNamespaces to exclude from scan
includeNamespaces[]stringNamespaces to include in scan
useCachedArtifactsboolUse cached artifacts (offline mode)
keepLocalboolDon't submit results to backend
accountstringKubescape SaaS account ID
accessKeystringKubescape SaaS access key
targetTypestring"framework" or "control"
targetNames[]stringFrameworks/controls to scan

Response Object

json
{
  "id": "scan-12345",
  "type": "v1results",
  "response": { /* payload */ }
}
FieldTypeDescription
idstringScan identifier
typestringResponse type (see below)
responseanyResponse payload

Response Types:

TypeDescription
v1resultsScan results object
busyScan in progress
notBusyNo scan in progress
readyScan complete, results ready
errorError occurred

API Examples

Basic Scan (Async)

bash
# 1. Trigger scan
curl -X POST http://127.0.0.1:8080/v1/scan \
  -H "Content-Type: application/json" \
  -d '{"targetType": "framework", "targetNames": ["nsa"]}'

# 2. Check status
curl http://127.0.0.1:8080/v1/status

# 3. Get results
curl http://127.0.0.1:8080/v1/results -o results.json

Synchronous Scan

bash
curl -X POST "http://127.0.0.1:8080/v1/scan?wait=true" \
  -H "Content-Type: application/json" \
  -d '{"targetType": "framework", "targetNames": ["nsa"]}' \
  -o results.json

Scan Specific Namespaces

bash
curl -X POST http://127.0.0.1:8080/v1/scan \
  -H "Content-Type: application/json" \
  -d '{
    "includeNamespaces": ["production"],
    "targetType": "framework",
    "targetNames": ["nsa", "mitre"]
  }'

Scan with Account Integration

bash
curl -X POST http://127.0.0.1:8080/v1/scan \
  -H "Content-Type: application/json" \
  -d '{
    "account": "YOUR-ACCOUNT-ID",
    "accessKey": "YOUR-ACCESS-KEY",
    "targetType": "framework",
    "targetNames": ["nsa"]
  }'

Delete All Cached Results

bash
curl -X DELETE "http://127.0.0.1:8080/v1/results?all=true"

Environment Variables

Configure the HTTP handler using environment variables:

VariableDescriptionExample
KS_ACCOUNTDefault account IDxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
KS_EXCLUDE_NAMESPACESDefault namespaces to excludekube-system,kube-public
KS_INCLUDE_NAMESPACESDefault namespaces to includeproduction,staging
KS_FORMATDefault output formatjson
KS_LOGGER_NAMELogger namekubescape
KS_LOGGER_LEVELLog levelinfo, debug, warning, error
KS_DOWNLOAD_ARTIFACTSDownload artifacts on each scantrue, false

Deployment Examples

Microservice Deployment

Deploy Kubescape as a microservice in your cluster for API-driven scanning.

šŸ“– Microservice Deployment Guide ā†’

Prometheus Integration

Expose Kubescape metrics for Prometheus scraping.

šŸ“– Prometheus Integration Guide ā†’

Debugging

Enable Debug Logging

Set the log level to debug for more verbose output:

bash
export KS_LOGGER_LEVEL=debug

Performance Profiling

The HTTP handler exposes pprof endpoints for performance analysis:

bash
# Heap profile
go tool pprof http://localhost:6060/debug/pprof/heap

# CPU profile
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# Goroutine profile
go tool pprof http://localhost:6060/debug/pprof/goroutine

For more information on pprof, see the pprof documentation.