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
• API Reference
  • Trigger Scan
  • Get Results
  • Check Status
  • Delete Results
• Request/Response Objects
• API Examples
• Environment Variables
• Deployment Examples
• Debugging

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:

Request Body: See Trigger Scan Object

Response (async):

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

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

The service accepts a bounded number of pending scans. If the queue is full, the endpoint returns 429 Too Many Requests with a Retry-After header. A request body larger than the configured limit returns 413 Request Entity Too Large before the scan is admitted.

Get Results

Endpoint: GET /v1/results

Retrieve scan results.

Query Parameters:

Response (success):

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

Response (error):

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

Response (in progress):

{
  "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:

Response (in progress):

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

Response (complete):

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

Delete Results

Endpoint: DELETE /v1/results

Delete cached scan results.

Query Parameters:

Request/Response Objects

Trigger Scan Object

{
  "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"]
}

Response Object

{
  "id": "scan-12345",
  "type": "v1results",
  "response": { /* payload */ }
}

Response Types:

API Examples

Basic Scan (Async)

# 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

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

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

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

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

Environment Variables

Configure the HTTP handler using environment variables:

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:

export KS_LOGGER_LEVEL=debug

Performance Profiling

The pprof debug server is off by default and binds to 127.0.0.1 only, so it's reachable from inside the pod's network namespace but not from the network. Enable it and reach it via kubectl port-forward:

export KS_PPROF_ENABLED=true
# then, e.g.: kubectl port-forward <pod> 6060:6060

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

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

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

Set KS_PPROF_ADDR to change the bind address (e.g. if 6060 collides with a sidecar in the pod). Binding to anything other than loopback is a deliberate, explicit choice — do so only on a trusted network.

For more information on pprof, see the pprof documentation.

Related Documentation

• CLI Reference
• Architecture
• Getting Started Guide
• Troubleshooting