docs/architecture.md
This document describes the architecture of Kubescape, covering both the CLI tool and the in-cluster operator.
Kubescape is designed as a modular security platform that can run in two primary modes:
Both modes share core scanning logic but differ in how they collect data and report results.
The Kubescape CLI is a standalone binary that performs security assessments on-demand.
<div align="center"> </div>cmd/)The entry point for all CLI operations. Key commands include:
| Command | Description |
|---|---|
scan | Orchestrates misconfiguration and vulnerability scanning |
scan image | Container image vulnerability scanning |
fix | Auto-remediation of misconfigurations |
patch | Container image patching |
list | Lists available frameworks and controls |
download | Downloads artifacts for offline use |
vap | Validating Admission Policy management |
mcpserver | MCP server for AI integration |
operator | Communicates with in-cluster operator |
core/)The main scanning engine that:
Kubescape uses Open Policy Agent (OPA) as its policy engine:
┌─────────────────────────────────────────────────────────────┐
│ Policy Evaluation Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ K8s Resources ──► OPA Engine ──► Rego Policies ──► Results │
│ │ │ │
│ │ ▼ │
│ │ Regolibrary │
│ │ (Control Library) │
│ │ │
│ ▼ │
│ - YAML files │
│ - Helm charts │
│ - Live cluster │
│ - Git repositories │
│ │
└─────────────────────────────────────────────────────────────┘
Regolibrary contains:
For vulnerability scanning, Kubescape integrates Grype:
┌─────────────────────────────────────────────────────────────┐
│ Image Scanning Pipeline │
├─────────────────────────────────────────────────────────────┤
│ │
│ Container Image ──► SBOM Generation ──► Vulnerability DB │
│ │ │ │
│ ▼ ▼ │
│ Syft Engine Grype Matching │
│ │ │ │
│ └────────┬───────────┘ │
│ ▼ │
│ CVE Results │
│ │
└─────────────────────────────────────────────────────────────┘
For patching vulnerable images, Kubescape uses Copacetic:
┌─────────────────────────────────────────────────────────────┐
│ Image Patching Pipeline │
├─────────────────────────────────────────────────────────────┤
│ │
│ Vulnerable Image ──► Copa ──► BuildKit ──► Patched Image │
│ │ │ │
│ ▼ ▼ │
│ - Scan for CVEs - Apply OS patches │
│ - Identify fixes - Rebuild layers │
│ - Generate patch plan - Push to registry │
│ │
└─────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────┐
│ CLI Scan Data Flow │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ Input Sources Processing Output │
│ ───────────── ────────── ────── │
│ │
│ ┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Kubernetes │────────►│ │ │ Console │ │
│ │ Cluster │ │ │───►│ (pretty-print) │ │
│ └─────────────┘ │ │ └─────────────────┘ │
│ │ │ │
│ ┌─────────────┐ │ Kubescape │ ┌─────────────────┐ │
│ │ YAML Files │────────►│ Core Engine │───►│ JSON/SARIF │ │
│ └─────────────┘ │ │ └─────────────────┘ │
│ │ │ │
│ ┌─────────────┐ │ │ ┌─────────────────┐ │
│ │ Helm Charts │────────►│ │───►│ HTML/PDF │ │
│ └─────────────┘ │ │ └─────────────────┘ │
│ │ │ │
│ ┌─────────────┐ │ │ ┌─────────────────┐ │
│ │ Git Repos │────────►│ │───►│ JUnit XML │ │
│ └─────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
The Kubescape Operator provides continuous security monitoring within the cluster.
<div align="center"> </div>The main controller that:
Handles container image vulnerability scanning:
VulnerabilityManifest CRsCollects security-relevant information from cluster nodes:
Kubescape uses Custom Resources to store scan results:
| CRD | Description |
|---|---|
VulnerabilityManifest | Image vulnerability scan results |
VulnerabilityManifestSummary | Aggregated vulnerability summaries |
WorkloadConfigurationScan | Misconfiguration scan results |
WorkloadConfigurationScanSummary | Aggregated configuration summaries |
ApplicationProfile | Runtime behavior profiles |
NetworkNeighborhood | Observed network connections |
For runtime security, the Node Agent uses eBPF via Inspektor Gadget:
┌─────────────────────────────────────────────────────────────┐
│ Runtime Security Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ Kernel ──► eBPF Probes ──► Node Agent ──► Kubescape │
│ │ │ │
│ ▼ ▼ │
│ System calls - Process exec │
│ Network events - File access │
│ File operations - Network connections │
│ - Anomaly detection │
│ │
└─────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────┐
│ Operator Data Flow │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Kubernetes │ │ Kubescape │ │ Custom Resources │ │
│ │ API Server │────►│ Operator │────►│ (Scan Results) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│ │ │ │ │
│ │ │ ▼ │
│ │ │ ┌─────────────────────────┐ │
│ │ │ │ Prometheus Metrics │ │
│ │ │ └─────────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Kubevuln │ │ Node Agent │ │ External Integrations │ │
│ │ (Images) │ │ (Runtime) │ │ (ARMO Platform, etc.) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
Kubescape evaluates resources against security frameworks:
| Framework | Description |
|---|---|
| NSA-CISA | Kubernetes Hardening Guidance |
| MITRE ATT&CK® | Threat-based security framework |
| CIS Benchmarks | Center for Internet Security best practices |
| SOC2 | Service Organization Control 2 |
| HIPAA | Healthcare compliance requirements |
| PCI-DSS | Payment Card Industry standards |
Control:
id: C-0005
name: API server insecure port is enabled
description: Check if the API server insecure port is enabled
frameworks:
- NSA
- MITRE
severity: High
remediation: |
Disable the insecure port by setting --insecure-port=0
rules:
- rego: |
# OPA/Rego policy code
| Component | Outbound Connections |
|---|---|
| CLI | Vulnerability DB updates, framework downloads |
| Operator | Vulnerability DB updates, optional backend |
| Offline | All artifacts can be pre-downloaded |
You can create custom controls using Rego:
package armo_builtins
deny[msga] {
# Your custom policy logic
input.kind == "Deployment"
not input.spec.template.spec.securityContext.runAsNonRoot
msga := {
"alertMessage": "Deployment should run as non-root",
"alertScore": 7,
"failedPaths": ["spec.template.spec.securityContext.runAsNonRoot"],
"fixPaths": [{"path": "spec.template.spec.securityContext.runAsNonRoot", "value": "true"}]
}
}