github/kubescape
1
0
Fork 0
mirror of https://github.com/kubescape/kubescape.git synced 2026-02-14 09:59:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Revamp documentation and reduce host sensor workers

Browse Source 
Signed-off-by: Matthias Bertschy <matthias.bertschy@gmail.com>
This commit is contained in:
Matthias Bertschy
2025-11-28 19:01:25 +01:00
parent acc9b54b2b
commit b6a4e282f9
15 changed files with 4040 additions and 398 deletions
Download Patch File Download Diff File Expand all files Collapse all files

469
README.md
View File

@@ -8,6 +8,7 @@
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkubescape%2Fkubescape.svg?type=shield&issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fkubescape%2Fkubescape?ref=badge_shield&issueType=license)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/6944/badge)](https://www.bestpractices.dev/projects/6944)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/kubescape/kubescape/badge)](https://securityscorecards.dev/viewer/?uri=github.com/kubescape/kubescape)
[![Docs](https://img.shields.io/badge/docs-latest-brightgreen?logo=gitbook)](https://kubescape.io/docs/)
[![Stars](https://img.shields.io/github/stars/kubescape/kubescape?style=social)](https://github.com/kubescape/kubescape/stargazers)
[![Twitter Follow](https://img.shields.io/twitter/follow/kubescape?style=social)](https://twitter.com/kubescape)
[![Slack](https://img.shields.io/badge/slack-kubescape-blueviolet?logo=slack)](https://cloud-native.slack.com/archives/C04EY3ZF9GE)
@@ -22,97 +23,475 @@
_Comprehensive Kubernetes Security from Development to Runtime_
Kubescape is an open-source Kubernetes security platform that provides comprehensive security coverage, from left to right across the entire development and deployment lifecycle. It offers hardening, posture management, and runtime security capabilities to ensure robust protection for Kubernetes environments. It saves Kubernetes users and admins precious time, effort, and resources.
Kubescape scans clusters, YAML files, and Helm charts. It detects misconfigurations according to multiple frameworks (including [NSA-CISA](https://www.armosec.io/blog/kubernetes-hardening-guidance-summary-by-armo/?utm_source=github&utm_medium=repository), [MITRE ATT&CK®](https://www.armosec.io/glossary/mitre-attck-framework/?utm_source=github&utm_medium=repository) and the [CIS Benchmark](https://www.armosec.io/blog/cis-kubernetes-benchmark-framework-scanning-tools-comparison/?utm_source=github&utm_medium=repository)).
Kubescape is an open-source Kubernetes security platform that provides comprehensive security coverage, from left to right across the entire development and deployment lifecycle. It offers hardening, posture management, and runtime security capabilities to ensure robust protection for Kubernetes environments.
Kubescape was created by [ARMO](https://www.armosec.io/?utm_source=github&utm_medium=repository) and is a [Cloud Native Computing Foundation (CNCF) incubating project](https://www.cncf.io/projects/).
_Please [star ⭐](https://github.com/kubescape/kubescape/stargazers) the repo if you want us to continue developing and improving Kubescape! 😀_
_Please [star ⭐](https://github.com/kubescape/kubescape/stargazers) the repo if you want us to continue developing and improving Kubescape!_
## Demo
---
Kubescape has a command line tool that you can use to quickly get a report on the security posture of a Kubernetes cluster:
## 📑 Table of Contents
<img src="docs/img/demo-v3.gif">
- [Features](#-features)
- [Demo](#-demo)
- [Quick Start](#-quick-start)
- [Installation](#-installation)
- [CLI Commands](#-cli-commands)
- [Usage Examples](#-usage-examples)
- [Architecture](#-architecture)
- [In-Cluster Operator](#-in-cluster-operator)
- [Integrations](#-integrations)
- [Community](#-community)
- [Changelog](#changelog)
- [License](#license)
## Getting started
---
Experimenting with Kubescape is as easy as:
## ✨ Features
| Feature | Description |
|---------|-------------|
| 🔍 **Misconfiguration Scanning** | Scan clusters, YAML files, and Helm charts against NSA-CISA, MITRE ATT&CK®, and CIS Benchmarks |
| 🐳 **Image Vulnerability Scanning** | Detect CVEs in container images using [Grype](https://github.com/anchore/grype) |
| 🩹 **Image Patching** | Automatically patch vulnerable images using [Copacetic](https://github.com/project-copacetic/copacetic) |
| 🔧 **Auto-Remediation** | Automatically fix misconfigurations in Kubernetes manifests |
| 🛡️ **Admission Control** | Enforce security policies with Validating Admission Policies (VAP) |
| 📊 **Runtime Security** | eBPF-based runtime monitoring via [Inspektor Gadget](https://github.com/inspektor-gadget) |
| 🤖 **AI Integration** | MCP server for AI assistant integration |
---
## 🎬 Demo
<img src="docs/img/demo-v3.gif" alt="Kubescape CLI demo">
---
## 🚀 Quick Start
### 1. Install Kubescape
```sh
curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash
```
This script will automatically download the latest Kubescape CLI release and scan the Kubernetes cluster in your current kubectl context.
> 💡 See [Installation](#-installation) for more options (Homebrew, Krew, Windows, etc.)
Learn more about:
### 2. Run Your First Scan
* [Installing the Kubescape CLI](https://kubescape.io/docs/install-cli/)
* [Running your first scan](https://kubescape.io/docs/scanning/)
* [Accepting risk with exceptions](https://kubescape.io/docs/accepting-risk/)
```sh
# Scan your current cluster
kubescape scan
_Did you know you can use Kubescape in all these places?_
# Scan a specific YAML file or directory
kubescape scan /path/to/manifests/
# Scan a container image for vulnerabilities
kubescape scan image nginx:latest
```
### 3. Explore the Results
Kubescape provides a detailed security posture overview including:
- Control plane security status
- Access control risks
- Workload misconfigurations
- Network policy gaps
- Compliance scores (MITRE, NSA)
---
## 📦 Installation
### One-Line Install (Linux/macOS)
```bash
curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash
```
### Package Managers
| Platform | Command |
|----------|---------|
| **Homebrew** | `brew install kubescape` |
| **Krew** | `kubectl krew install kubescape` |
| **Arch Linux** | `yay -S kubescape` |
| **Ubuntu** | `sudo add-apt-repository ppa:kubescape/kubescape && sudo apt install kubescape` |
| **NixOS** | `nix-shell -p kubescape` |
| **Chocolatey** | `choco install kubescape` |
| **Scoop** | `scoop install kubescape` |
### Windows (PowerShell)
```powershell
iwr -useb https://raw.githubusercontent.com/kubescape/kubescape/master/install.ps1 | iex
```
📖 **[Full Installation Guide →](docs/installation.md)**
---
## 🛠️ CLI Commands
Kubescape provides a comprehensive CLI with the following commands:
| Command | Description |
|---------|-------------|
| [`kubescape scan`](#scanning) | Scan cluster, files, or images for security issues |
| [`kubescape scan image`](#image-scanning) | Scan container images for vulnerabilities |
| [`kubescape fix`](#auto-fix) | Auto-fix misconfigurations in manifest files |
| [`kubescape patch`](#image-patching) | Patch container images to fix vulnerabilities |
| [`kubescape list`](#list-frameworks-and-controls) | List available frameworks and controls |
| [`kubescape download`](#offline-support) | Download artifacts for offline/air-gapped use |
| [`kubescape config`](#configuration) | Manage cached configurations |
| [`kubescape operator`](#operator-commands) | Interact with in-cluster Kubescape operator |
| [`kubescape vap`](#validating-admission-policies) | Manage Validating Admission Policies |
| [`kubescape mcpserver`](#mcp-server) | Start MCP server for AI assistant integration |
| `kubescape completion` | Generate shell completion scripts |
| `kubescape version` | Display version information |
---
## 📖 Usage Examples
### Scanning
#### Scan a Running Cluster
```bash
# Default scan (all frameworks)
kubescape scan
# Scan with a specific framework
kubescape scan framework nsa
kubescape scan framework mitre
kubescape scan framework cis-v1.23-t1.0.1
# Scan a specific control
kubescape scan control C-0005 -v
```
#### Scan Files and Repositories
```bash
# Scan local YAML files
kubescape scan /path/to/manifests/
# Scan a Helm chart
kubescape scan /path/to/helm/chart/
# Scan a Git repository
kubescape scan https://github.com/kubescape/kubescape
# Scan with Kustomize
kubescape scan /path/to/kustomize/directory/
```
#### Scan Options
```bash
# Include/exclude namespaces
kubescape scan --include-namespaces production,staging
kubescape scan --exclude-namespaces kube-system,kube-public
# Use alternative kubeconfig
kubescape scan --kubeconfig /path/to/kubeconfig
# Set compliance threshold (exit code 1 if below threshold)
kubescape scan --compliance-threshold 80
# Set severity threshold
kubescape scan --severity-threshold high
```
#### Output Formats
```bash
# JSON output
kubescape scan --format json --output results.json
# JUnit XML (for CI/CD)
kubescape scan --format junit --output results.xml
# SARIF (for GitHub Code Scanning)
kubescape scan --format sarif --output results.sarif
# HTML report
kubescape scan --format html --output report.html
# PDF report
kubescape scan --format pdf --output report.pdf
```
### Image Scanning
```bash
# Scan a public image
kubescape scan image nginx:1.21
# Scan with verbose output
kubescape scan image nginx:1.21 -v
# Scan a private registry image
kubescape scan image myregistry/myimage:tag --username user --password pass
```
### Auto-Fix
Automatically fix misconfigurations in your manifest files:
```bash
# First, scan and save results to JSON
kubescape scan /path/to/manifests --format json --output results.json
# Then apply fixes
kubescape fix results.json
# Dry run (preview changes without applying)
kubescape fix results.json --dry-run
# Apply fixes without confirmation prompts
kubescape fix results.json --no-confirm
```
### Image Patching
Patch container images to fix OS-level vulnerabilities:
```bash
# Start buildkitd (required)
sudo buildkitd &
# Patch an image
sudo kubescape patch --image docker.io/library/nginx:1.22
# Specify custom output tag
sudo kubescape patch --image nginx:1.22 --tag nginx:1.22-patched
# See detailed vulnerability report
sudo kubescape patch --image nginx:1.22 -v
```
📖 **[Full Patch Command Documentation →](cmd/patch/README.md)**
### List Frameworks and Controls
```bash
# List available frameworks
kubescape list frameworks
# List all controls
kubescape list controls
# Output as JSON
kubescape list controls --format json
```
### Offline Support
Download artifacts for air-gapped environments:
```bash
# Download all artifacts
kubescape download artifacts --output /path/to/offline/dir
# Download a specific framework
kubescape download framework nsa --output /path/to/nsa.json
# Scan using downloaded artifacts
kubescape scan --use-artifacts-from /path/to/offline/dir
```
### Configuration
```bash
# View current configuration
kubescape config view
# Set account ID
kubescape config set accountID <your-account-id>
# Delete cached configuration
kubescape config delete
```
### Operator Commands
Interact with the in-cluster Kubescape operator:
```bash
# Trigger a configuration scan
kubescape operator scan configurations
# Trigger a vulnerability scan
kubescape operator scan vulnerabilities
```
### Validating Admission Policies
Manage Kubernetes Validating Admission Policies:
```bash
# Deploy the Kubescape CEL admission policy library
kubescape vap deploy-library | kubectl apply -f -
# Create a policy binding
kubescape vap create-policy-binding \
--name my-policy-binding \
--policy c-0016 \
--namespace my-namespace | kubectl apply -f -
```
### MCP Server
Start an MCP (Model Context Protocol) server for AI assistant integration:
```bash
kubescape mcpserver
```
The MCP server exposes Kubescape's vulnerability and configuration scan data to AI assistants, enabling natural language queries about your cluster's security posture.
**Available MCP Tools:**
- `list_vulnerability_manifests` - Discover vulnerability manifests
- `list_vulnerabilities_in_manifest` - List CVEs in a manifest
- `list_vulnerability_matches_for_cve` - Get details for a specific CVE
- `list_configuration_security_scan_manifests` - List configuration scan results
- `get_configuration_security_scan_manifest` - Get configuration scan details
---
## 🏗️ Architecture
Kubescape can run in two modes:
### CLI Mode
The CLI is a standalone tool that scans clusters, files, and images on-demand.
<div align="center">
<img src="docs/img/ksfromcodetodeploy.png" alt="Places you can use Kubescape: in your IDE, CI, CD, or against a running cluster.">
<img src="docs/img/ks-cli-arch.png" width="600" alt="CLI Architecture">
</div>
### Continuous security monitoring with the Kubescape Operator
**Key Components:**
- **[Open Policy Agent (OPA)](https://github.com/open-policy-agent/opa)** - Policy evaluation engine
- **[Regolibrary](https://github.com/kubescape/regolibrary)** - Library of security controls
- **[Grype](https://github.com/anchore/grype)** - Image vulnerability scanning
- **[Copacetic](https://github.com/project-copacetic/copacetic)** - Image patching
As well as a CLI, Kubescape provides an in-cluster mode, which is installed via a Helm chart. Kubescape in-cluster provides extensive features such as continuous scanning, image vulnerability scanning, runtime analysis, network policy generation, and more. [Learn more about the Kubescape operator](https://kubescape.io/docs/operator/).
### Operator Mode (In-Cluster)
### Using Kubescape as a GitHub Action
For continuous monitoring, deploy the Kubescape operator via Helm.
Kubescape can be used as a GitHub Action. This is a great way to integrate Kubescape into your CI/CD pipeline. You can find the Kubescape GitHub Action in the [GitHub Action marketplace](https://github.com/marketplace/actions/kubescape).
<div align="center">
<img src="docs/img/ks-operator-arch.png" width="600" alt="Operator Architecture">
</div>
## Under the hood
**Additional Capabilities:**
- Continuous configuration scanning
- Image vulnerability scanning
- Runtime analysis with eBPF
- Network policy generation
Kubescape uses [Open Policy Agent](https://github.com/open-policy-agent/opa) to verify Kubernetes objects against [a library of posture controls](https://github.com/kubescape/regolibrary).
For image scanning, it uses [Grype](https://github.com/anchore/grype).
For image patching, it uses [Copacetic](https://github.com/project-copacetic/copacetic).
For eBPF, it uses [Inspektor Gadget](https://github.com/inspektor-gadget)
📖 **[Full Architecture Documentation →](docs/architecture.md)**
By default, CLI scan results are printed in a console-friendly manner, but they can be:
---
* exported to JSON, junit XML or SARIF
* rendered to HTML or PDF
* submitted to a [cloud service](docs/providers.md)
## ☸️ In-Cluster Operator
### In-cluster architecture
The Kubescape operator provides continuous security monitoring in your cluster:
![Architecture diagram](docs/img/architecture-diagram.png)
```bash
# Add the Kubescape Helm repository
helm repo add kubescape https://kubescape.github.io/helm-charts/
## Community
# Install the operator
helm upgrade --install kubescape kubescape/kubescape-operator \
--namespace kubescape \
--create-namespace
```
Kubescape is an open source project. We welcome your feedback and ideas for improvement. We are part of the CNCF community and are evolving Kubescape in sync with the security needs of Kubernetes users. To learn more about where Kubescape is heading, please check out our [ROADMAP](https://github.com/kubescape/project-governance/blob/main/ROADMAP.md).
**Operator Features:**
- 🔄 Continuous misconfiguration scanning
- 🐳 Image vulnerability scanning for all workloads
- 🔍 Runtime threat detection (eBPF-based)
- 🌐 Network policy generation
- 📈 Prometheus metrics integration
If you feel inspired to contribute to Kubescape, check out our [CONTRIBUTING](https://github.com/kubescape/project-governance/blob/main/CONTRIBUTING.md) file to learn how. You can find the issues we are working on (triage to development) on the [Kubescaping board](https://github.com/orgs/kubescape/projects/4/views/1)
📖 **[Operator Installation Guide →](https://kubescape.io/docs/operator/)**
* Feel free to pick a task from the [board](https://github.com/orgs/kubescape/projects/4) or suggest a feature of your own.
* Open an issue on the board. We aim to respond to all issues within 48 hours.
* [Join the CNCF Slack](https://slack.cncf.io/) and then our [users](https://cloud-native.slack.com/archives/C04EY3ZF9GE) or [developers](https://cloud-native.slack.com/archives/C04GY6H082K) channel.
---
The Kubescape project follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
## 🔌 Integrations
For more information about the Kubescape community, please visit [COMMUNITY](https://github.com/kubescape/project-governance/blob/main/COMMUNITY.md).
### CI/CD
| Platform | Integration |
|----------|-------------|
| **GitHub Actions** | [kubescape/github-action](https://github.com/marketplace/actions/kubescape) |
| **GitLab CI** | [Documentation](https://kubescape.io/docs/integrations/gitlab/) |
| **Jenkins** | [Documentation](https://kubescape.io/docs/integrations/jenkins/) |
We would like to take this opportunity to thank all our contibutors to date.
### IDE Extensions
<br>
| IDE | Extension |
|-----|-----------|
| **VS Code** | [Kubescape Extension](https://marketplace.visualstudio.com/items?itemName=kubescape.kubescape) |
| **Lens** | [Kubescape Lens Extension](https://github.com/armosec/lens-kubescape) |
<a href = "https://github.com/kubescape/kubescape/graphs/contributors">
<img src = "https://contrib.rocks/image?repo=kubescape/kubescape"/>
### Where You Can Use Kubescape
<div align="center">
<img src="docs/img/ksfromcodetodeploy.png" alt="Kubescape integration points: IDE, CI, CD, Runtime">
</div>
---
## 👥 Community
Kubescape is a CNCF incubating project with an active community.
### Get Involved
- 💬 **[Slack - Users Channel](https://cloud-native.slack.com/archives/C04EY3ZF9GE)** - Ask questions, get help
- 💬 **[Slack - Developers Channel](https://cloud-native.slack.com/archives/C04GY6H082K)** - Contribute to development
- 🐛 **[GitHub Issues](https://github.com/kubescape/kubescape/issues)** - Report bugs and request features
- 📋 **[Project Board](https://github.com/orgs/kubescape/projects/4)** - See what we're working on
- 🗺️ **[Roadmap](https://github.com/kubescape/project-governance/blob/main/ROADMAP.md)** - Future plans
### Contributing
We welcome contributions! Please see our:
- **[Contributing Guide](https://github.com/kubescape/project-governance/blob/main/CONTRIBUTING.md)**
- **[Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)**
### Community Resources
- **[Community Info](https://github.com/kubescape/project-governance/blob/main/COMMUNITY.md)**
- **[Governance](https://github.com/kubescape/project-governance/blob/main/GOVERNANCE.md)**
- **[Security Policy](https://github.com/kubescape/project-governance/blob/main/SECURITY.md)**
- **[Maintainers](https://github.com/kubescape/project-governance/blob/main/MAINTAINERS.md)**
### Contributors
<a href="https://github.com/kubescape/kubescape/graphs/contributors">
<img src="https://contrib.rocks/image?repo=kubescape/kubescape"/>
</a>
---
## Changelog
Kubescape changes are tracked on the [release](https://github.com/kubescape/kubescape/releases) page.
Kubescape changes are tracked on the [releases page](https://github.com/kubescape/kubescape/releases).
---
## License
Copyright 2021-2025, the Kubescape Authors. All rights reserved. Kubescape is released under the Apache 2.0 license. See the [LICENSE](LICENSE) file for details.
Copyright 2021-2025, the Kubescape Authors. All rights reserved.
Kubescape is released under the [Apache 2.0 license](LICENSE).
Kubescape is a [Cloud Native Computing Foundation (CNCF) incubating project](https://www.cncf.io/projects/kubescape/) and was contributed by [ARMO](https://www.armosec.io/?utm_source=github&utm_medium=repository).

263
build/README.md
View File

@@ -1,19 +1,264 @@
## Docker Build
# Building Kubescape
### Build your own Docker image
This guide covers how to build Kubescape from source.
1. Clone Project
```
git clone https://github.com/kubescape/kubescape.git kubescape && cd "$_"
## Table of Contents
- [Prerequisites](#prerequisites)
- [Building the CLI](#building-the-cli)
- [Building Docker Images](#building-docker-images)
- [Build Options](#build-options)
- [Development Setup](#development-setup)
- [Troubleshooting](#troubleshooting)
---
## Prerequisites
### Required
- **Go 1.23+** - [Installation Guide](https://golang.org/doc/install)
- **Git** - For cloning the repository
- **Make** - For running build commands
### Optional (for Docker builds)
- **Docker** - [Installation Guide](https://docs.docker.com/get-docker/)
- **Docker Buildx** - For multi-platform builds (included with Docker Desktop)
### Verify Prerequisites
```bash
go version # Should be 1.21 or higher
git --version
make --version
docker --version # Optional
```
2. Build kubescape CLI Docker image
---
## Building the CLI
### Clone the Repository
```bash
git clone https://github.com/kubescape/kubescape.git
cd kubescape
```
### Build with Make
```bash
# Build for your current platform
make build
# The binary will be at ./kubescape
./kubescape version
```
### Build Directly with Go
```bash
go build -o kubescape .
```
### Cross-Compilation
Build for different platforms:
```bash
# Linux (amd64)
GOOS=linux GOARCH=amd64 go build -o kubescape-linux-amd64 .
# Linux (arm64)
GOOS=linux GOARCH=arm64 go build -o kubescape-linux-arm64 .
# macOS (amd64)
GOOS=darwin GOARCH=amd64 go build -o kubescape-darwin-amd64 .
# macOS (arm64 / Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o kubescape-darwin-arm64 .
# Windows (amd64)
GOOS=windows GOARCH=amd64 go build -o kubescape-windows-amd64.exe .
```
---
## Building Docker Images
### Build All Images
```bash
make all
docker buildx build -t kubescape-cli -f build/kubescape-cli.Dockerfile --build-arg="ks_binary=kubescape" --load .
```
3. Build kubescape Docker image
### Build CLI Docker Image
Build a Docker image containing only the Kubescape CLI:
```bash
# First build the binary
make build
# Then build the Docker image
docker buildx build \
-t kubescape-cli:latest \
-f build/kubescape-cli.Dockerfile \
--build-arg="ks_binary=kubescape" \
--load .
```
docker buildx build -t kubescape -f build/Dockerfile --load .
### Build Full Kubescape Image
Build the complete Kubescape image (includes HTTP handler):
```bash
docker buildx build \
-t kubescape:latest \
-f build/Dockerfile \
--load .
```
### Multi-Platform Build
Build for multiple architectures:
```bash
docker buildx build \
-t kubescape:latest \
-f build/Dockerfile \
--platform linux/amd64,linux/arm64 \
--push .
```
---
## Build Options
### Make Targets
| Target | Description |
|--------|-------------|
| `make build` | Build the Kubescape binary |
| `make test` | Run unit tests |
| `make all` | Build everything |
| `make clean` | Remove build artifacts |
### Build Tags
You can use Go build tags to customize the build:
```bash
# Example with build tags
go build -tags "netgo" -o kubescape .
```
### Version Information
To embed version information in the build:
```bash
VERSION=$(git describe --tags --always)
BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
COMMIT=$(git rev-parse HEAD)
go build -ldflags "-X main.version=$VERSION -X main.buildDate=$BUILD_DATE -X main.commit=$COMMIT" -o kubescape .
```
---
## Development Setup
### Install Development Dependencies
```bash
# Install golangci-lint for linting
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
# Install other tools as needed
go mod download
```
### Run Tests
```bash
# Run all tests
make test
# Run tests with coverage
go test -cover ./...
# Run specific package tests
go test ./core/...
```
### Run Linter
```bash
golangci-lint run
```
### Code Formatting
```bash
go fmt ./...
```
---
## Troubleshooting
### Build Fails with "module not found"
```bash
# Update dependencies
go mod tidy
go mod download
```
### CGO-related Errors
If you encounter CGO errors, try building with CGO disabled:
```bash
CGO_ENABLED=0 go build -o kubescape .
```
### Docker Build Fails
Ensure Docker daemon is running and you have sufficient permissions:
```bash
# Check Docker status
docker info
# Run with sudo if needed (Linux)
sudo docker buildx build ...
```
### Out of Memory During Build
For systems with limited memory:
```bash
# Limit Go's memory usage
GOGC=50 go build -o kubescape .
```
---
## Dockerfiles
| File | Description |
|------|-------------|
| `build/Dockerfile` | Full Kubescape image with HTTP handler |
| `build/kubescape-cli.Dockerfile` | Minimal CLI-only image |
---
## Related Documentation
- [Contributing Guide](https://github.com/kubescape/project-governance/blob/main/CONTRIBUTING.md)
- [Architecture](../docs/architecture.md)
- [Getting Started](../docs/getting-started.md)

248
core/README.md
View File

@@ -1,14 +1,248 @@
# Kubescape core package
# Kubescape Core Package
The `core` package provides the main Kubescape scanning engine as a Go library, allowing you to integrate Kubescape security scanning directly into your applications.
## Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [API Reference](#api-reference)
- [Examples](#examples)
- [Configuration Options](#configuration-options)
---
## Installation
```bash
go get github.com/kubescape/kubescape/v3/core
```
---
## Quick Start
```go
package main
// initialize kubescape
ks := core.NewKubescape()
import (
"context"
"fmt"
"log"
// scan cluster
results, err := ks.Scan(&cautils.ScanInfo{})
"github.com/kubescape/kubescape/v3/core"
"github.com/kubescape/kubescape/v3/core/cautils"
)
// convert scan results to json
jsonRes, err := results.ToJson()
func main() {
ctx := context.Background()
// Initialize Kubescape
ks := core.NewKubescape(ctx)
// Configure scan
scanInfo := &cautils.ScanInfo{
// Scan the current cluster
ScanAll: true,
}
// Run scan
results, err := ks.Scan(scanInfo)
if err != nil {
log.Fatalf("Scan failed: %v", err)
}
// Convert results to JSON
jsonRes, err := results.ToJson()
if err != nil {
log.Fatalf("Failed to convert results: %v", err)
}
fmt.Println(string(jsonRes))
}
```
---
## API Reference
### Creating a Kubescape Instance
```go
// Create with context
ks := core.NewKubescape(ctx)
```
### Scanning
```go
// Scan with configuration
results, err := ks.Scan(scanInfo)
```
### Listing Frameworks and Controls
```go
// List available policies
err := ks.List(listPolicies)
```
### Downloading Artifacts
```go
// Download for offline use
err := ks.Download(downloadInfo)
```
### Image Scanning
```go
// Scan container image
exceedsSeverity, err := ks.ScanImage(imgScanInfo, scanInfo)
```
### Fixing Misconfigurations
```go
// Apply fixes to manifests
err := ks.Fix(fixInfo)
```
---
## Examples
### Scan a Specific Framework
```go
scanInfo := &cautils.ScanInfo{}
scanInfo.SetPolicyIdentifiers([]string{"nsa"}, "framework")
results, err := ks.Scan(scanInfo)
```
### Scan Specific Namespaces
```go
scanInfo := &cautils.ScanInfo{
IncludeNamespaces: "production,staging",
}
results, err := ks.Scan(scanInfo)
```
### Scan Local YAML Files
```go
scanInfo := &cautils.ScanInfo{
InputPatterns: []string{"/path/to/manifests"},
}
scanInfo.SetScanType(cautils.ScanTypeRepo)
results, err := ks.Scan(scanInfo)
```
### Export Results to Different Formats
```go
results, _ := ks.Scan(scanInfo)
// JSON
jsonData, _ := results.ToJson()
// Get summary
summary := results.GetData().Report.SummaryDetails
fmt.Printf("Compliance Score: %.2f%%\n", summary.ComplianceScore)
```
### Scan with Compliance Threshold
```go
scanInfo := &cautils.ScanInfo{
ComplianceThreshold: 80.0, // Fail if below 80%
}
results, err := ks.Scan(scanInfo)
if err != nil {
// Handle scan failure
}
// Check if threshold was exceeded
if results.GetData().Report.SummaryDetails.ComplianceScore < scanInfo.ComplianceThreshold {
log.Fatal("Compliance score below threshold")
}
```
---
## Configuration Options
### ScanInfo Fields
| Field | Type | Description |
|-------|------|-------------|
| `AccountID` | string | Kubescape SaaS account ID |
| `AccessKey` | string | Kubescape SaaS access key |
| `InputPatterns` | []string | Paths to scan (files, directories, URLs) |
| `ExcludedNamespaces` | string | Comma-separated namespaces to exclude |
| `IncludeNamespaces` | string | Comma-separated namespaces to include |
| `Format` | string | Output format (json, junit, sarif, etc.) |
| `Output` | string | Output file path |
| `VerboseMode` | bool | Show all resources in output |
| `FailThreshold` | float32 | Fail threshold percentage |
| `ComplianceThreshold` | float32 | Compliance threshold percentage |
| `UseExceptions` | string | Path to exceptions file |
| `UseArtifactsFrom` | string | Path to offline artifacts |
| `Submit` | bool | Submit results to SaaS |
| `Local` | bool | Keep results local (don't submit) |
---
## Error Handling
```go
results, err := ks.Scan(scanInfo)
if err != nil {
switch {
case errors.Is(err, context.DeadlineExceeded):
log.Fatal("Scan timed out")
case errors.Is(err, context.Canceled):
log.Fatal("Scan was canceled")
default:
log.Fatalf("Scan error: %v", err)
}
}
```
---
## Thread Safety
The Kubescape instance is safe for concurrent use. You can run multiple scans in parallel:
```go
var wg sync.WaitGroup
for _, ns := range namespaces {
wg.Add(1)
go func(namespace string) {
defer wg.Done()
scanInfo := &cautils.ScanInfo{
IncludeNamespaces: namespace,
}
results, _ := ks.Scan(scanInfo)
// Process results...
}(ns)
}
wg.Wait()
```
---
## Related Documentation
- [CLI Reference](../docs/cli-reference.md)
- [Getting Started Guide](../docs/getting-started.md)
- [Architecture](../docs/architecture.md)

97
docs/README.md Normal file
View File

@@ -0,0 +1,97 @@
# Kubescape Documentation
Welcome to the Kubescape documentation. This directory contains detailed guides and references for using Kubescape.
[![Docs](https://img.shields.io/badge/docs-latest-brightgreen?logo=gitbook)](https://kubescape.io/docs/)
[![GitHub](https://img.shields.io/github/license/kubescape/kubescape)](https://github.com/kubescape/kubescape/blob/master/LICENSE)
[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](https://github.com/kubescape/project-governance/blob/main/CONTRIBUTING.md)
## 📚 Documentation Index
### Getting Started
| Document | Description |
|----------|-------------|
| [Installation Guide](installation.md) | How to install Kubescape on various platforms |
| [Getting Started](getting-started.md) | First steps with Kubescape, basic usage examples |
### Reference
| Document | Description |
|----------|-------------|
| [CLI Reference](cli-reference.md) | Complete command-line reference for all Kubescape commands |
| [Architecture](architecture.md) | Technical architecture of Kubescape CLI and Operator |
### Features
| Document | Description |
|----------|-------------|
| [MCP Server](mcp-server.md) | AI assistant integration via Model Context Protocol |
| [Providers](providers.md) | Backend services compatible with Kubescape |
### Support
| Document | Description |
|----------|-------------|
| [Troubleshooting](troubleshooting.md) | Common issues and solutions |
### Additional Resources
| Document | Description |
|----------|-------------|
| [Environment Dependencies Policy](environment-dependencies-policy.md) | Policy on external dependencies |
| [Roadmap](roadmap.md) | Project roadmap (see centralized governance repo) |
## 📁 Subdirectories
| Directory | Description |
|-----------|-------------|
| [img/](img/) | Images and diagrams used in documentation |
| [proposals/](proposals/) | Design proposals and RFCs |
| [providers/](providers/) | Provider-specific documentation |
## 🔗 External Documentation
- **[Kubescape Website](https://kubescape.io)** - Official website with additional guides
- **[Kubescape Docs Hub](https://kubescape.io/docs/)** - Comprehensive online documentation
- **[Controls Reference](https://kubescape.io/docs/controls/)** - List of all security controls
- **[Helm Charts](https://github.com/kubescape/helm-charts)** - Operator installation
- **[Regolibrary](https://github.com/kubescape/regolibrary)** - Security controls library
## 🤝 Contributing to Documentation
We welcome contributions to improve our documentation! Please see the [Contributing Guide](https://github.com/kubescape/project-governance/blob/main/CONTRIBUTING.md) for details.
### Documentation Style
- Use clear, concise language
- Include code examples where applicable
- Keep command examples copy-pasteable
- Update the table of contents when adding sections
- Test all commands before documenting them
## 📝 Document Status
| Document | Status | Description |
|----------|--------|-------------|
| [installation.md](installation.md) | ✅ Current | Installation methods for all platforms |
| [getting-started.md](getting-started.md) | ✅ Current | Quick start and usage examples |
| [cli-reference.md](cli-reference.md) | ✅ Current | Complete CLI command reference |
| [architecture.md](architecture.md) | ✅ Current | Technical architecture documentation |
| [mcp-server.md](mcp-server.md) | ✅ Current | AI assistant integration (MCP) |
| [troubleshooting.md](troubleshooting.md) | ✅ Current | Common issues and solutions |
| [providers.md](providers.md) | ✅ Current | Backend service providers |
| [environment-dependencies-policy.md](environment-dependencies-policy.md) | ✅ Current | Dependency policies |
---
## 📖 Quick Links
| I want to... | Go to... |
|--------------|----------|
| Install Kubescape | [Installation Guide](installation.md) |
| Run my first scan | [Getting Started](getting-started.md#run-your-first-scan) |
| See all CLI options | [CLI Reference](cli-reference.md) |
| Use Kubescape with AI assistants | [MCP Server](mcp-server.md) |
| Fix a problem | [Troubleshooting](troubleshooting.md) |
| Understand the architecture | [Architecture](architecture.md) |

347
docs/architecture.md
View File

@@ -1,19 +1,346 @@
# Kubescape architecture
# Kubescape Architecture
_Please check back soon for more: until then, enjoy these fine diagrams._
This document describes the architecture of Kubescape, covering both the CLI tool and the in-cluster operator.
### [Component architecture](img/architecture.drawio.svg)
## Overview
Kubescape is designed as a modular security platform that can run in two primary modes:
1. **CLI Mode** - On-demand scanning from your local machine
2. **Operator Mode** - Continuous monitoring within your Kubernetes cluster
Both modes share core scanning logic but differ in how they collect data and report results.
---
## CLI Architecture
The Kubescape CLI is a standalone binary that performs security assessments on-demand.
<div align="center">
<img src="img/architecture.drawio.svg" width="600" alt="Component architecture">
<img src="img/ks-cli-arch.png" width="600" alt="CLI Architecture Diagram">
</div>
### [CLI](#kubescape-cli)
### Core Components
#### 1. Command Layer (`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 |
#### 2. Core Engine (`core/`)
The main scanning engine that:
- Loads and parses Kubernetes resources
- Evaluates resources against security controls
- Aggregates and formats results
- Manages scan lifecycle and configuration
#### 3. Policy Evaluation (OPA/Rego)
Kubescape uses [Open Policy Agent (OPA)](https://www.openpolicyagent.org/) 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](https://github.com/kubescape/regolibrary)** contains:
- Security controls (200+)
- Framework definitions (NSA-CISA, MITRE ATT&CK®, CIS Benchmarks)
- Control metadata and remediation guidance
#### 4. Image Scanner (Grype Integration)
For vulnerability scanning, Kubescape integrates [Grype](https://github.com/anchore/grype):
```
┌─────────────────────────────────────────────────────────────┐
│ Image Scanning Pipeline │
├─────────────────────────────────────────────────────────────┤
│ │
│ Container Image ──► SBOM Generation ──► Vulnerability DB │
│ │ │ │
│ ▼ ▼ │
│ Syft Engine Grype Matching │
│ │ │ │
│ └────────┬───────────┘ │
│ ▼ │
│ CVE Results │
│ │
└─────────────────────────────────────────────────────────────┘
```
#### 5. Image Patcher (Copacetic Integration)
For patching vulnerable images, Kubescape uses [Copacetic](https://github.com/project-copacetic/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 │
│ │
└─────────────────────────────────────────────────────────────┘
```
### Data Flow (CLI Scan)
```
┌──────────────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └─────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
```
---
## Operator Architecture (In-Cluster)
The Kubescape Operator provides continuous security monitoring within the cluster.
<div align="center">
<img src="img/ks-cli-arch.png" width="600" alt="cli-diagram">
<img src="img/ks-operator-arch.png" width="600" alt="Operator Architecture Diagram">
</div>
### [Operator](https://github.com/kubescape/helm-charts#readme)
<div align="center">
<img src="img/ks-operator-arch.png" width="600" alt="operator-diagram">
</div>
### Components
#### 1. Kubescape Operator
The main controller that:
- Watches for changes to Kubernetes resources
- Triggers scans on schedule or on-demand
- Manages scan lifecycle
- Stores results in Custom Resources
#### 2. Kubevuln
Handles container image vulnerability scanning:
- Scans images running in the cluster
- Generates SBOMs (Software Bill of Materials)
- Matches against vulnerability databases
- Creates `VulnerabilityManifest` CRs
#### 3. Host Scanner
Collects security-relevant information from cluster nodes:
- Kernel parameters
- Kubelet configuration
- Container runtime settings
- File permissions
#### 4. Storage
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 |
#### 5. Node Agent (Runtime Security)
For runtime security, the Node Agent uses eBPF via [Inspektor Gadget](https://github.com/inspektor-gadget/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 │
│ │
└─────────────────────────────────────────────────────────────┘
```
### Data Flow (Operator)
```
┌──────────────────────────────────────────────────────────────────────┐
│ Operator Data Flow │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Kubernetes │ │ Kubescape │ │ Custom Resources │ │
│ │ API Server │────►│ Operator │────►│ (Scan Results) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│ │ │ │ │
│ │ │ ▼ │
│ │ │ ┌─────────────────────────┐ │
│ │ │ │ Prometheus Metrics │ │
│ │ │ └─────────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Kubevuln │ │ Node Agent │ │ External Integrations │ │
│ │ (Images) │ │ (Runtime) │ │ (ARMO Platform, etc.) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
```
---
## Frameworks and Controls
Kubescape evaluates resources against security frameworks:
### Supported 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 Structure
```yaml
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
```
---
## Security Model
### CLI Mode
- Runs with the permissions of the executing user
- Uses kubeconfig for cluster access
- No persistent state in the cluster
- Results stored locally or sent to configured backend
### Operator Mode
- Runs as a Kubernetes workload
- Uses ServiceAccount with defined RBAC
- Stores results as Custom Resources
- Can send data to external backends (optional)
### Network Requirements
| Component | Outbound Connections |
|-----------|---------------------|
| CLI | Vulnerability DB updates, framework downloads |
| Operator | Vulnerability DB updates, optional backend |
| Offline | All artifacts can be pre-downloaded |
---
## Extensibility
### Custom Controls
You can create custom controls using Rego:
```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"}]
}
}
```
### Integration Points
- **HTTP API** - For programmatic access ([see httphandler docs](../httphandler/README.md))
- **MCP Server** - For AI assistant integration ([see mcp-server docs](mcp-server.md))
- **Prometheus Metrics** - For monitoring and alerting
- **Webhook** - For external notifications
---
## Further Reading
- [Getting Started Guide](getting-started.md)
- [Installation Guide](installation.md)
- [Regolibrary (Controls)](https://github.com/kubescape/regolibrary)
- [Helm Charts](https://github.com/kubescape/helm-charts)
- [ARMO Platform Integration](providers.md)

581
docs/cli-reference.md Normal file
View File

@@ -0,0 +1,581 @@
# Kubescape CLI Reference
This document provides a complete reference for all Kubescape CLI commands and options.
## Global Options
These options are available for all commands:
| Option | Description |
|--------|-------------|
| `--cache-dir <path>` | Cache directory (default: `~/.kubescape`) |
| `--kube-context <context>` | Kubernetes context to use (default: current-context) |
| `-l, --logger <level>` | Log level: `debug`, `info`, `warning`, `error`, `fatal` |
| `--server <url>` | Backend discovery server URL |
| `-h, --help` | Help for any command |
---
## kubescape scan
Scan Kubernetes clusters, files, or images for security issues.
### Synopsis
```bash
kubescape scan [target] [flags]
```
### Target Types
- No target: Scans the current cluster
- Path: Scans local YAML files, Helm charts, or Kustomize directories
- URL: Scans a Git repository
### Flags
| Flag | Description | Default |
|------|-------------|---------|
| `--account <id>` | Kubescape SaaS account ID | from cache |
| `--access-key <key>` | Kubescape SaaS access key | from cache |
| `--compliance-threshold <float>` | Fail if compliance score is below threshold | `0` |
| `--controls-config <path>` | Path to controls configuration file | - |
| `-e, --exclude-namespaces <ns>` | Namespaces to exclude (comma-separated) | - |
| `--exceptions <path>` | Path to exceptions file | - |
| `-f, --format <format>` | Output format: `pretty-printer`, `json`, `junit`, `sarif`, `html`, `pdf`, `prometheus` | `pretty-printer` |
| `--include-namespaces <ns>` | Namespaces to include (comma-separated) | - |
| `--keep-local` | Don't report results to backend | `false` |
| `--kubeconfig <path>` | Path to kubeconfig file | - |
| `-o, --output <path>` | Output file path | stdout |
| `--scan-images` | Also scan container images for vulnerabilities | `false` |
| `--severity-threshold <sev>` | Fail if findings at or above severity: `low`, `medium`, `high`, `critical` | - |
| `--submit` | Submit results to Kubescape SaaS | `false` |
| `--use-artifacts-from <path>` | Load artifacts from local directory (offline mode) | - |
| `--use-from <path>` | Load specific policy from path | - |
| `-v, --verbose` | Display all resources, not just failed ones | `false` |
| `--view <type>` | View type: `security`, `control`, `resource` | `security` |
### Examples
```bash
# Scan current cluster
kubescape scan
# Scan with specific framework
kubescape scan framework nsa
kubescape scan framework mitre
kubescape scan framework cis-v1.23-t1.0.1
# Scan specific control
kubescape scan control C-0005 -v
# Scan local files
kubescape scan /path/to/manifests/
# Scan Git repository
kubescape scan https://github.com/org/repo
# Output to JSON file
kubescape scan --format json --output results.json
# Set compliance threshold (exit 1 if below)
kubescape scan --compliance-threshold 80
# Exclude namespaces
kubescape scan --exclude-namespaces kube-system,kube-public
```
---
## kubescape scan framework
Scan against a specific security framework.
### Synopsis
```bash
kubescape scan framework <framework-name> [target] [flags]
```
### Available Frameworks
| Framework | Description |
|-----------|-------------|
| `nsa` | NSA-CISA Kubernetes Hardening Guidance |
| `mitre` | MITRE ATT&CK® for Kubernetes |
| `cis-v1.23-t1.0.1` | CIS Kubernetes Benchmark |
| `soc2` | SOC 2 compliance |
| `pci-dss` | PCI DSS compliance |
| `hipaa` | HIPAA compliance |
### Examples
```bash
kubescape scan framework nsa
kubescape scan framework mitre --include-namespaces production
kubescape scan framework cis-v1.23-t1.0.1 /path/to/manifests
```
---
## kubescape scan control
Scan for a specific control.
### Synopsis
```bash
kubescape scan control <control-id> [target] [flags]
```
### Examples
```bash
# Scan for privileged containers
kubescape scan control C-0057 -v
# Scan specific files for a control
kubescape scan control C-0013 /path/to/deployment.yaml
```
---
## kubescape scan workload
Scan a specific workload.
### Synopsis
```bash
kubescape scan workload <kind>/<name> [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--namespace <ns>` | Namespace of the workload |
### Examples
```bash
kubescape scan workload Deployment/nginx --namespace default
kubescape scan workload DaemonSet/fluentd --namespace logging
```
---
## kubescape scan image
Scan a container image for vulnerabilities.
### Synopsis
```bash
kubescape scan image <image>:<tag> [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--exceptions <path>` | Path to exceptions file |
| `-p, --password <pass>` | Registry password |
| `-u, --username <user>` | Registry username |
| `--use-default-matchers` | Use default vulnerability matchers | `true` |
### Examples
```bash
# Scan public image
kubescape scan image nginx:1.21
# Scan with verbose output
kubescape scan image nginx:1.21 -v
# Scan private registry image
kubescape scan image myregistry.io/myimage:tag -u myuser -p mypass
```
---
## kubescape fix
Auto-fix misconfigurations in Kubernetes manifest files.
### Synopsis
```bash
kubescape fix <report-file> [flags]
```
### Flags
| Flag | Description | Default |
|------|-------------|---------|
| `--dry-run` | Preview changes without applying | `false` |
| `--no-confirm` | Apply without confirmation | `false` |
| `--skip-user-values` | Skip changes requiring user values | `true` |
### Examples
```bash
# Generate scan results
kubescape scan /path/to/manifests --format json --output results.json
# Apply fixes
kubescape fix results.json
# Preview fixes
kubescape fix results.json --dry-run
# Apply without prompts
kubescape fix results.json --no-confirm
```
---
## kubescape patch
Patch container images to fix OS-level vulnerabilities.
### Synopsis
```bash
kubescape patch [flags]
```
### Flags
| Flag | Description | Default |
|------|-------------|---------|
| `-i, --image <image>` | Image to patch (required) | - |
| `-t, --tag <tag>` | Output image tag | `<image>-patched` |
| `-a, --addr <addr>` | BuildKit daemon address | `unix:///run/buildkit/buildkitd.sock` |
| `--timeout <duration>` | Patching timeout | `5m` |
| `--ignore-errors` | Continue on errors | `false` |
| `-u, --username <user>` | Registry username | - |
| `-p, --password <pass>` | Registry password | - |
| `-f, --format <format>` | Output format | - |
| `-o, --output <path>` | Output file | stdout |
| `-v, --verbose` | Verbose output | `false` |
### Examples
```bash
# Start buildkitd first
sudo buildkitd &
# Patch an image
sudo kubescape patch --image nginx:1.22
# Custom output tag
sudo kubescape patch --image nginx:1.22 --tag nginx:1.22-fixed
# Verbose output
sudo kubescape patch --image nginx:1.22 -v
```
---
## kubescape list
List available frameworks and controls.
### Synopsis
```bash
kubescape list <type> [flags]
```
### Types
| Type | Description |
|------|-------------|
| `frameworks` | List available security frameworks |
| `controls` | List available security controls |
### Flags
| Flag | Description | Default |
|------|-------------|---------|
| `--account <id>` | Account ID for custom frameworks | - |
| `--access-key <key>` | Access key | - |
| `--format <format>` | Output format: `pretty-print`, `json` | `pretty-print` |
### Examples
```bash
kubescape list frameworks
kubescape list controls
kubescape list controls --format json
```
---
## kubescape download
Download artifacts for offline/air-gapped use.
### Synopsis
```bash
kubescape download <type> [name] [flags]
```
### Types
| Type | Description |
|------|-------------|
| `artifacts` | Download all artifacts (frameworks, controls, config) |
| `framework` | Download a specific framework |
| `control` | Download a specific control |
### Flags
| Flag | Description | Default |
|------|-------------|---------|
| `-o, --output <path>` | Output path | `~/.kubescape` |
| `--account <id>` | Account ID | - |
| `--access-key <key>` | Access key | - |
### Examples
```bash
# Download all artifacts
kubescape download artifacts --output /path/to/offline
# Download specific framework
kubescape download framework nsa --output /path/to/nsa.json
# Use downloaded artifacts
kubescape scan --use-artifacts-from /path/to/offline
```
---
## kubescape config
Manage Kubescape configuration.
### Subcommands
| Subcommand | Description |
|------------|-------------|
| `view` | View current configuration |
| `set` | Set configuration value |
| `delete` | Delete cached configuration |
### Examples
```bash
# View configuration
kubescape config view
# Set account ID
kubescape config set accountID <account-id>
# Set cloud report URL
kubescape config set cloudReportURL https://api.example.com
# Delete configuration
kubescape config delete
```
---
## kubescape operator
Interact with the in-cluster Kubescape operator.
### Synopsis
```bash
kubescape operator scan <type> [flags]
```
### Scan Types
| Type | Description |
|------|-------------|
| `configurations` | Trigger configuration scan |
| `vulnerabilities` | Trigger vulnerability scan |
### Examples
```bash
kubescape operator scan configurations
kubescape operator scan vulnerabilities
```
---
## kubescape vap
Manage Kubernetes Validating Admission Policies.
### Subcommands
#### deploy-library
Deploy the Kubescape CEL admission policy library.
```bash
kubescape vap deploy-library | kubectl apply -f -
```
#### create-policy-binding
Create a ValidatingAdmissionPolicyBinding.
```bash
kubescape vap create-policy-binding [flags]
```
**Flags:**
| Flag | Description | Required |
|------|-------------|----------|
| `-n, --name <name>` | Binding name | Yes |
| `-p, --policy <id>` | Policy/control ID | Yes |
| `--namespace <ns>` | Namespace selector (repeatable) | No |
| `--label <k=v>` | Label selector (repeatable) | No |
| `-a, --action <action>` | Action: `Deny`, `Audit`, `Warn` | No (default: `Deny`) |
| `-r, --parameter-reference <name>` | Parameter reference | No |
### Examples
```bash
# Deploy policy library
kubescape vap deploy-library | kubectl apply -f -
# Create binding
kubescape vap create-policy-binding \
--name deny-privileged \
--policy c-0057 \
--namespace production \
--action Deny | kubectl apply -f -
```
---
## kubescape mcpserver
Start the MCP (Model Context Protocol) server for AI assistant integration.
### Synopsis
```bash
kubescape mcpserver
```
### Description
Starts an MCP server that exposes Kubescape data to AI assistants. The server communicates via stdio.
### Prerequisites
- Kubescape operator installed in the cluster
- kubectl configured with cluster access
### Examples
```bash
# Start MCP server
kubescape mcpserver
```
### Claude Desktop Configuration
```json
{
"mcpServers": {
"kubescape": {
"command": "kubescape",
"args": ["mcpserver"]
}
}
}
```
---
## kubescape version
Display version information.
### Synopsis
```bash
kubescape version
```
---
## kubescape completion
Generate shell completion scripts.
### Synopsis
```bash
kubescape completion <shell>
```
### Supported Shells
- `bash`
- `zsh`
- `fish`
- `powershell`
### Examples
```bash
# Bash
kubescape completion bash > /etc/bash_completion.d/kubescape
# Zsh
kubescape completion zsh > "${fpath[1]}/_kubescape"
# Fish
kubescape completion fish > ~/.config/fish/completions/kubescape.fish
```
---
## Environment Variables
Kubescape respects the following environment variables:
| Variable | Description |
|----------|-------------|
| `KS_ACCOUNT` | Default account ID |
| `KS_CACHE_DIR` | Cache directory path |
| `KS_EXCLUDE_NAMESPACES` | Default namespaces to exclude |
| `KS_INCLUDE_NAMESPACES` | Default namespaces to include |
| `KS_FORMAT` | Default output format |
| `KS_LOGGER` | Log level |
| `KS_LOGGER_NAME` | Logger name |
| `KUBECONFIG` | Path to kubeconfig file |
| `HTTPS_PROXY` | HTTPS proxy URL |
| `HTTP_PROXY` | HTTP proxy URL |
| `NO_PROXY` | Hosts to exclude from proxy |
---
## Exit Codes
| Code | Description |
|------|-------------|
| `0` | Success |
| `1` | Failure (threshold exceeded, scan failed, etc.) |
---
## See Also
- [Getting Started Guide](getting-started.md)
- [Architecture](architecture.md)
- [Troubleshooting](troubleshooting.md)
- [MCP Server Documentation](mcp-server.md)

221
docs/getting-started.md
View File

@@ -4,6 +4,22 @@ Kubescape can run as a command line tool on a client, as an operator inside a cl
The best way to get started with Kubescape is to download it to the machine you use to manage your Kubernetes cluster.
## Table of Contents
- [Install Kubescape](#install-kubescape)
- [Run your first scan](#run-your-first-scan)
- [Usage](#usage)
- [Misconfigurations Scanning](#misconfigurations-scanning)
- [Image Scanning](#image-scanning)
- [Auto-Fix Misconfigurations](#auto-fix-misconfigurations)
- [Image Patching](#image-patching)
- [Validating Admission Policies (VAP)](#validating-admission-policies-vap)
- [MCP Server (AI Integration)](#mcp-server-ai-integration)
- [Configuration Management](#configuration-management)
- [Offline/Air-gapped Support](#offlineair-gapped-environment-support)
- [Other Ways to Use Kubescape](#other-ways-to-use-kubescape)
- [Tutorial Videos](#tutorial-videos)
## Install Kubescape
```bash
@@ -170,7 +186,7 @@ kubescape scan --exclude-namespaces kube-system,kube-public
#### Scan local YAML files
```sh
kubescape scan /path/to/directory-or-directory
kubescape scan /path/to/directory-or-file
```
Take a look at the [example](https://youtu.be/Ox6DaR7_4ZI).
@@ -305,7 +321,7 @@ You can also download a single artifact, and scan with the `--use-from` flag:
```
## Image scanning
Kubescape can scan container images for vulnerabilities. It uses [Grype]() to scan the images.
Kubescape can scan container images for vulnerabilities. It uses [Grype](https://github.com/anchore/grype) to scan the images.
### Examples
@@ -347,6 +363,207 @@ View Kubescape scan results directly in the [Lens IDE](https://k8slens.dev/) usi
Experiment with Kubescape in the [Kubescape playground](https://killercoda.com/saiyampathak/scenario/kubescape): this scenario will install a K3s cluster and Kubescape. You can start with any of the `kubescape scan` commands in the [examples](#examples).
## Auto-Fix Misconfigurations
Kubescape can automatically fix misconfigurations found in your Kubernetes manifest files.
### Usage
```bash
# First, scan and save results to JSON
kubescape scan /path/to/manifests --format json --output results.json
# Then apply fixes based on the scan results
kubescape fix results.json
```
### Options
| Flag | Description |
|------|-------------|
| `--dry-run` | Preview changes without applying them |
| `--no-confirm` | Apply fixes without confirmation prompts |
| `--skip-user-values` | Skip changes that require user-defined values (default: true) |
### Example
```bash
# Preview fixes without applying
kubescape fix results.json --dry-run
# Apply fixes without prompts (useful for CI/CD)
kubescape fix results.json --no-confirm
```
> **Warning**
> The fix command modifies files in-place. Always review changes or use `--dry-run` first.
## Image Patching
Kubescape can patch container images to fix OS-level vulnerabilities using [Copacetic](https://github.com/project-copacetic/copacetic) and [BuildKit](https://github.com/moby/buildkit).
### Prerequisites
- Docker daemon installed and running
- BuildKit daemon installed
### Usage
```bash
# Start buildkitd (if not already running)
sudo buildkitd &
# Patch an image
sudo kubescape patch --image docker.io/library/nginx:1.22
```
### Options
| Flag | Description | Default |
|------|-------------|---------|
| `-i, --image` | Image name to patch (required) | - |
| `-t, --tag` | Tag for the patched image | `<image>-patched` |
| `-a, --addr` | BuildKit daemon address | `unix:///run/buildkit/buildkitd.sock` |
| `--timeout` | Patching timeout | `5m` |
| `-u, --username` | Registry username | - |
| `-p, --password` | Registry password | - |
| `-v, --verbose` | Show detailed output | `false` |
### Example without sudo
```bash
export BUILDKIT_VERSION=v0.11.4
export BUILDKIT_PORT=8888
# Start BuildKit in Docker
docker run --detach --rm --privileged \
-p 127.0.0.1:$BUILDKIT_PORT:$BUILDKIT_PORT/tcp \
--name buildkitd \
--entrypoint buildkitd \
"moby/buildkit:$BUILDKIT_VERSION" \
--addr tcp://0.0.0.0:$BUILDKIT_PORT
# Patch using TCP connection
kubescape patch -i nginx:1.22 -a tcp://0.0.0.0:$BUILDKIT_PORT
```
> **Note**
> Image patching can only fix OS-level vulnerabilities, not application-level ones.
For more details, see the [Patch Command Documentation](/cmd/patch/README.md).
## Validating Admission Policies (VAP)
Kubescape can help manage Kubernetes [Validating Admission Policies](https://kubernetes.io/docs/reference/access-authn-authz/validating-admission-policy/) using CEL (Common Expression Language).
### Deploy the Policy Library
Install the Kubescape CEL admission policy library:
```bash
kubescape vap deploy-library | kubectl apply -f -
```
This deploys:
- Policy configuration CRD
- Basic control configurations
- Kubescape validating admission policies
### Create Policy Bindings
Bind policies to specific resources:
```bash
kubescape vap create-policy-binding \
--name my-policy-binding \
--policy c-0016 \
--namespace my-namespace | kubectl apply -f -
```
### Options for `create-policy-binding`
| Flag | Description | Required |
|------|-------------|----------|
| `-n, --name` | Name of the policy binding | Yes |
| `-p, --policy` | Policy/control to bind | Yes |
| `--namespace` | Namespace selector (can be repeated) | No |
| `--label` | Label selector in `key=value` format | No |
| `-a, --action` | Action on failure: `Deny`, `Audit`, `Warn` | No (default: `Deny`) |
| `-r, --parameter-reference` | Parameter reference object name | No |
### Example
```bash
# Create a policy that denies non-compliant resources in production
kubescape vap create-policy-binding \
--name deny-privileged-containers \
--policy c-0057 \
--namespace production \
--action Deny | kubectl apply -f -
```
## MCP Server (AI Integration)
Kubescape provides an MCP (Model Context Protocol) server for AI assistant integration, allowing natural language queries about your cluster's security posture.
### Prerequisites
- Kubescape operator installed in your cluster
- kubectl configured with cluster access
### Start the Server
```bash
kubescape mcpserver
```
### Available Tools
The MCP server exposes these tools to AI assistants:
| Tool | Description |
|------|-------------|
| `list_vulnerability_manifests` | Discover vulnerability scan results |
| `list_vulnerabilities_in_manifest` | List CVEs in a specific manifest |
| `list_vulnerability_matches_for_cve` | Get details for a specific CVE |
| `list_configuration_security_scan_manifests` | List configuration scan results |
| `get_configuration_security_scan_manifest` | Get configuration scan details |
### Integration with Claude Desktop
Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"kubescape": {
"command": "kubescape",
"args": ["mcpserver"]
}
}
}
```
For more details, see the [MCP Server Documentation](mcp-server.md).
## Configuration Management
Manage Kubescape's cached configurations:
```bash
# View current configuration
kubescape config view
# Set account ID
kubescape config set accountID <your-account-id>
# Set cloud report URL
kubescape config set cloudReportURL <url>
# Delete cached configuration
kubescape config delete
```
## Tutorial videos
* [Kubescape overview](https://youtu.be/wdBkt_0Qhbg)

265
docs/installation.md
View File

@@ -1,116 +1,251 @@
# Installation
## Manually
> **Note**: We do not recommend this method if you want to get auto-updating from package managers or have more platforms supported.
### X86_64 or ARM64 (M1/M2) Linux / macOS
# Installation Guide
This guide covers all the ways to install Kubescape on your system.
## Table of Contents
- [Quick Install](#quick-install)
- [Package Managers](#package-managers)
- [Manual Installation](#manual-installation)
- [Verification](#verification)
- [Updating](#updating)
- [Uninstalling](#uninstalling)
---
## Quick Install
### Linux / macOS (Recommended)
```bash
curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash
```
To install a previous version, you can specify it in the command line.
This script:
- Detects your OS and architecture (x86_64, ARM64/M1/M2)
- Downloads the latest release
- Installs to `~/.kubescape/`
- Adds to your PATH
```bash
curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash -s -- -v v2.3.6
```
### Windows (PowerShell)
Requires PowerShell v5.0 or higher:
### X86_64 Windows
You must have PowerShell v5.0 or higher:
```powershell
iwr -useb https://raw.githubusercontent.com/kubescape/kubescape/master/install.ps1 | iex
```
If you get an error, you may need to change the execution policy:
If you get an execution policy error:
```powershell
Set-ExecutionPolicy RemoteSigned -scope CurrentUser
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```
## openSUSE
> **Note**: openSUSE community-supported.
### Install a Specific Version
```bash
sudo zypper refresh
sudo zypper install kubescape
curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash -s -- -v v3.0.0
```
## Arch
---
## Package Managers
### Homebrew (macOS/Linux)
```bash
yay -S kubescape
```
If you would like to save some time and do not want to compile, install `kubescape-bin` instead:
> **Note**: kubescape-bin is AUR community-supported.
```bash
yay -S kubescape-bin
brew install kubescape
```
## Ubuntu
> **Note**: The [official Homebrew formula](https://formulae.brew.sh/formula/kubescape#default) has git scanning disabled. For full functionality:
> ```bash
> brew tap kubescape/tap
> brew install kubescape-cli
> ```
### Krew (kubectl plugin)
```bash
kubectl krew update
kubectl krew install kubescape
# Use as kubectl plugin
kubectl kubescape scan
```
### Ubuntu / Debian
```bash
sudo add-apt-repository ppa:kubescape/kubescape
sudo apt update
sudo apt install kubescape
```
## Other Debian-based or RPM-based Linux Distros
Please follow the [guidelines here](https://software.opensuse.org/download.html?project=home%3Akubescape&package=kubescape).
For other Debian-based or RPM-based distributions, see the [OpenSUSE Build Service](https://software.opensuse.org/download.html?project=home%3Akubescape&package=kubescape).
## Homebrew
> **Note**: The kubescape delivered by [official Homebrew](https://formulae.brew.sh/formula/kubescape#default) comes with git disabled.
### Arch Linux
```bash
brew install kubescape
# Build from source
yay -S kubescape
# Or install pre-built binary (faster)
yay -S kubescape-bin
```
If you want to have the git enabled one, you can install via the [homebrew-tap](https://github.com/kubescape/homebrew-tap):
> **Note**: AUR packages are community-supported.
### openSUSE
```bash
brew tap kubescape/tap
brew install kubescape-cli
sudo zypper refresh
sudo zypper install kubescape
```
## Chocolatey
> **Note**: Chocolatey [community-supported](https://community.chocolatey.org/packages/kubescape).
> **Note**: Community-supported.
### NixOS / Nix
```bash
# Try in ephemeral shell
nix-shell -p kubescape
# Or add to configuration.nix
environment.systemPackages = with pkgs; [ kubescape ];
# Or with home-manager
home.packages = with pkgs; [ kubescape ];
```
> **Note**: Community-supported. See [NixOS support](https://nixos.wiki/wiki/Support) for issues.
### Snap
[![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-white.svg)](https://snapcraft.io/kubescape)
```bash
sudo snap install kubescape
```
### Chocolatey (Windows)
```powershell
choco install kubescape
```
## Scoop
> **Note**: Scoop [community-supported](https://scoop.sh/#/apps?q=kubescape&s=0&d=1&o=true&id=1f5ae05eaafe3e7a26505f0889101e0da91ffe91).
> **Note**: [Community-supported](https://community.chocolatey.org/packages/kubescape).
### Scoop (Windows)
```powershell
scoop install kubescape
```
## Krew
> **Note**: [Community-supported](https://scoop.sh/#/apps?q=kubescape).
---
## Manual Installation
### Download from GitHub Releases
1. Go to the [Releases page](https://github.com/kubescape/kubescape/releases)
2. Download the appropriate binary for your OS/architecture
3. Make it executable and move to your PATH:
```bash
kubectl krew update
kubectl krew install kubescape
kubectl kubescape
# Linux/macOS example
chmod +x kubescape
sudo mv kubescape /usr/local/bin/
```
## Snap
[![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-white.svg)](https://snapcraft.io/kubescape)
### Build from Source
## NixOS or with nix
> **Note**: This method is community-supported. If you are having trouble, please reach out to [NixOS support](https://nixos.wiki/wiki/Support).
You can use `nix` on Linux or macOS.
Try it out in an ephemeral shell: `nix-shell -p kubescape`.
NixOS:
```
# your other config ...
environment.systemPackages = with pkgs; [
# your other packages ...
kubescape
];
```bash
git clone https://github.com/kubescape/kubescape.git
cd kubescape
make build
```
home-manager:
---
```
# your other config ...
home.packages = with pkgs; [
# your other packages ...
kubescape
];
## Verification
After installation, verify Kubescape is working:
```bash
# Check version
kubescape version
# Run a simple scan (requires cluster access)
kubescape scan
# Or scan a sample file
kubescape scan https://raw.githubusercontent.com/kubernetes/examples/master/guestbook/all-in-one/guestbook-all-in-one.yaml
```
Or, to your profile (not preferred): `nix-env --install -A nixpkgs.kubescape`.
### Expected Output
```
Kubescape version: vX.X.X
```
---
## Updating
### Script Installation
Re-run the install script to get the latest version:
```bash
curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash
```
### Package Managers
Use your package manager's update command:
```bash
# Homebrew
brew upgrade kubescape
# apt
sudo apt update && sudo apt upgrade kubescape
# Krew
kubectl krew upgrade kubescape
```
---
## Uninstalling
### Script Installation
```bash
rm -rf ~/.kubescape
# Remove from PATH in your shell config (.bashrc, .zshrc, etc.)
```
### Package Managers
Use your package manager's uninstall command:
```bash
# Homebrew
brew uninstall kubescape
# apt
sudo apt remove kubescape
# Krew
kubectl krew uninstall kubescape
```
---
## Next Steps
- [Getting Started Guide](getting-started.md) - Run your first scan
- [CLI Reference](cli-reference.md) - Full command reference
- [Troubleshooting](troubleshooting.md) - Common issues and solutions

259
docs/mcp-server.md Normal file
View File

@@ -0,0 +1,259 @@
# Kubescape MCP Server
The Kubescape MCP (Model Context Protocol) Server enables AI assistants to query your Kubernetes cluster's security posture using natural language. It exposes Kubescape's vulnerability and configuration scan data through the [MCP protocol](https://modelcontextprotocol.io/).
## Overview
The MCP server allows AI assistants (like Claude, ChatGPT, or custom AI tools) to:
- List and query vulnerability manifests for images and workloads
- Retrieve CVE details and vulnerability matches
- Access configuration security scan results
- Provide security recommendations based on real cluster data
## Prerequisites
Before using the MCP server, you need:
1. **Kubescape Operator installed in your cluster** - The MCP server reads data from Custom Resources created by the operator
2. **kubectl configured** - With access to the cluster running the Kubescape operator
3. **Kubescape CLI** - Version 3.x or later
### Installing the Kubescape Operator
```bash
helm repo add kubescape https://kubescape.github.io/helm-charts/
helm repo update
helm upgrade --install kubescape kubescape/kubescape-operator \
--namespace kubescape \
--create-namespace \
--set capabilities.vulnerabilityScan=enable \
--set capabilities.configurationScan=enable
```
Wait for the operator to complete initial scans:
```bash
kubectl -n kubescape get vulnerabilitymanifests
kubectl -n kubescape get workloadconfigurationscans
```
## Starting the MCP Server
```bash
kubescape mcpserver
```
The server starts and communicates via stdio, making it compatible with MCP-enabled AI tools.
## Available Tools
The MCP server exposes the following tools to AI assistants:
### Vulnerability Tools
#### `list_vulnerability_manifests`
Discover available vulnerability manifests at image and workload levels.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | No | Filter by namespace |
| `level` | string | No | Type of manifests: `"image"`, `"workload"`, or `"both"` (default) |
**Example Response:**
```json
{
"vulnerability_manifests": {
"manifests": [
{
"type": "workload",
"namespace": "default",
"manifest_name": "deployment-nginx-nginx",
"image-level": false,
"workload-level": true,
"image-id": "sha256:abc123...",
"image-tag": "nginx:1.21",
"resource_uri": "kubescape://vulnerability-manifests/default/deployment-nginx-nginx"
}
]
}
}
```
#### `list_vulnerabilities_in_manifest`
List all vulnerabilities (CVEs) found in a specific manifest.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | No | Namespace of the manifest (default: `"kubescape"`) |
| `manifest_name` | string | Yes | Name of the manifest |
**Example Response:**
```json
[
{
"id": "CVE-2023-12345",
"severity": "High",
"description": "Buffer overflow in libfoo",
"fix": {
"versions": ["1.2.4"],
"state": "fixed"
}
}
]
```
#### `list_vulnerability_matches_for_cve`
Get detailed information about a specific CVE in a manifest, including affected packages and fix information.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | No | Namespace of the manifest (default: `"kubescape"`) |
| `manifest_name` | string | Yes | Name of the manifest |
| `cve_id` | string | Yes | CVE identifier (e.g., `"CVE-2023-12345"`) |
### Configuration Tools
#### `list_configuration_security_scan_manifests`
Discover available security configuration scan results at the workload level.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | No | Filter by namespace (default: `"kubescape"`) |
**Example Response:**
```json
{
"configuration_manifests": {
"manifests": [
{
"namespace": "default",
"manifest_name": "deployment-nginx",
"resource_uri": "kubescape://configuration-manifests/default/deployment-nginx"
}
]
}
}
```
#### `get_configuration_security_scan_manifest`
Get detailed configuration scan results for a specific workload, including failed controls and remediation guidance.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `namespace` | string | No | Namespace of the manifest (default: `"kubescape"`) |
| `manifest_name` | string | Yes | Name of the configuration manifest |
## Resource Templates
The MCP server also exposes resource templates for direct access to data:
### Vulnerability Manifest
```
kubescape://vulnerability-manifests/{namespace}/{manifest_name}
```
### Configuration Manifest
```
kubescape://configuration-manifests/{namespace}/{manifest_name}
```
## Integration with AI Assistants
### Claude Desktop
Add to your Claude Desktop configuration (`~/.config/claude/config.json` on Linux or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"kubescape": {
"command": "kubescape",
"args": ["mcpserver"]
}
}
}
```
### Custom Integration
For custom AI applications using the MCP SDK:
```python
from mcp import Client
async with Client("kubescape", ["kubescape", "mcpserver"]) as client:
# List vulnerability manifests
result = await client.call_tool(
"list_vulnerability_manifests",
{"level": "workload"}
)
print(result)
```
## Example AI Queries
Once connected, you can ask your AI assistant questions like:
- "What vulnerabilities exist in my production namespace?"
- "Show me all critical CVEs affecting my nginx deployments"
- "What configuration issues does my cluster have?"
- "Which workloads have the most security issues?"
- "Give me details about CVE-2023-12345 in my cluster"
## Troubleshooting
### No vulnerability manifests found
Ensure the Kubescape operator has completed vulnerability scanning:
```bash
kubectl -n kubescape get vulnerabilitymanifests
```
If empty, check operator logs:
```bash
kubectl -n kubescape logs -l app=kubescape
```
### Connection issues
Verify your kubeconfig is correctly configured:
```bash
kubectl get nodes
```
### MCP server not responding
Check that you're running Kubescape v3.x or later:
```bash
kubescape version
```
## Security Considerations
- The MCP server runs with the same Kubernetes permissions as your kubeconfig
- It provides read-only access to vulnerability and configuration data
- No cluster modifications are made through the MCP server
- Consider running with a service account that has limited permissions in production
## Related Documentation
- [Kubescape Operator Installation](https://kubescape.io/docs/operator/)
- [Vulnerability Scanning](https://kubescape.io/docs/vulnerabilities/)
- [Configuration Scanning](https://kubescape.io/docs/configuration-scanning/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)

528
docs/troubleshooting.md Normal file
View File

@@ -0,0 +1,528 @@
# Troubleshooting Guide
This guide covers common issues you may encounter when using Kubescape and how to resolve them.
## Table of Contents
- [Installation Issues](#installation-issues)
- [Scanning Issues](#scanning-issues)
- [Image Scanning Issues](#image-scanning-issues)
- [Image Patching Issues](#image-patching-issues)
- [Operator Issues](#operator-issues)
- [MCP Server Issues](#mcp-server-issues)
- [Output and Reporting Issues](#output-and-reporting-issues)
- [Performance Issues](#performance-issues)
- [Getting Help](#getting-help)
---
## Installation Issues
### Command not found after installation
**Symptom:** After running the install script, `kubescape` command is not found.
**Solution:**
1. Check if the binary was installed:
```bash
ls -la ~/.kubescape/kubescape
```
2. Add to your PATH:
```bash
# For bash
echo 'export PATH=$PATH:~/.kubescape' >> ~/.bashrc
source ~/.bashrc
# For zsh
echo 'export PATH=$PATH:~/.kubescape' >> ~/.zshrc
source ~/.zshrc
```
3. Alternatively, move the binary to a directory already in your PATH:
```bash
sudo mv ~/.kubescape/kubescape /usr/local/bin/
```
### Permission denied during installation
**Symptom:** Installation fails with permission errors.
**Solution:**
```bash
# Create the directory with proper permissions
mkdir -p ~/.kubescape
chmod 755 ~/.kubescape
# Re-run the installation
curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash
```
### Installation fails on Windows
**Symptom:** PowerShell script fails to execute.
**Solution:**
1. Check PowerShell version (must be v5.0+):
```powershell
$PSVersionTable.PSVersion
```
2. Set execution policy:
```powershell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```
3. Retry installation:
```powershell
iwr -useb https://raw.githubusercontent.com/kubescape/kubescape/master/install.ps1 | iex
```
---
## Scanning Issues
### Cannot connect to cluster
**Symptom:** `kubescape scan` fails with connection errors.
**Solutions:**
1. Verify kubectl works:
```bash
kubectl get nodes
```
2. Check your kubeconfig:
```bash
kubectl config current-context
kubectl config view
```
3. Use an explicit kubeconfig:
```bash
kubescape scan --kubeconfig /path/to/kubeconfig
```
4. Use a specific context:
```bash
kubescape scan --kube-context my-context
```
### Scan times out
**Symptom:** Scanning large clusters takes too long or times out.
**Solutions:**
1. Scan specific namespaces:
```bash
kubescape scan --include-namespaces production,staging
```
2. Exclude non-essential namespaces:
```bash
kubescape scan --exclude-namespaces kube-system,kube-public,monitoring
```
3. Scan a specific framework instead of all:
```bash
kubescape scan framework nsa
```
### No results returned
**Symptom:** Scan completes but shows no results.
**Solutions:**
1. Check if the cluster has workloads:
```bash
kubectl get pods --all-namespaces
```
2. Run with verbose output:
```bash
kubescape scan -v
```
3. Check for namespace filtering issues:
```bash
# Make sure you're not excluding all namespaces
kubescape scan --include-namespaces default
```
### Framework or control not found
**Symptom:** Error about unknown framework or control.
**Solutions:**
1. List available frameworks:
```bash
kubescape list frameworks
```
2. List available controls:
```bash
kubescape list controls
```
3. Update Kubescape to get latest controls:
```bash
# Re-run installation to get latest version
curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash
```
4. Download latest artifacts:
```bash
kubescape download artifacts
```
### RBAC errors during scan
**Symptom:** Scan fails with permission denied errors.
**Solution:**
Ensure your kubeconfig user has sufficient permissions. At minimum, you need read access to:
- Deployments, DaemonSets, StatefulSets, Jobs, CronJobs
- Pods, Services, ConfigMaps, Secrets
- Roles, RoleBindings, ClusterRoles, ClusterRoleBindings
- NetworkPolicies
- ServiceAccounts
---
## Image Scanning Issues
### Image not found
**Symptom:** `kubescape scan image` fails to find the image.
**Solutions:**
1. Use the full image reference:
```bash
kubescape scan image docker.io/library/nginx:1.21
```
2. For private registries, provide credentials:
```bash
kubescape scan image myregistry.io/myimage:tag \
--username myuser \
--password mypassword
```
3. Check if the image exists locally:
```bash
docker images | grep myimage
```
### Authentication failed for private registry
**Symptom:** Scan fails with authentication errors.
**Solutions:**
1. Verify credentials work with docker:
```bash
docker login myregistry.io
docker pull myregistry.io/myimage:tag
```
2. Use environment variables for credentials:
```bash
export KUBESCAPE_REGISTRY_USERNAME=myuser
export KUBESCAPE_REGISTRY_PASSWORD=mypassword
kubescape scan image myregistry.io/myimage:tag
```
### Vulnerability database outdated
**Symptom:** Known CVEs are not being detected.
**Solution:**
The vulnerability database is updated automatically. To force an update:
```bash
# Clear the cache
rm -rf ~/.kubescape/grype-db
# Run a new scan
kubescape scan image nginx:latest
```
---
## Image Patching Issues
### BuildKit not running
**Symptom:** `kubescape patch` fails with BuildKit connection errors.
**Solutions:**
1. Start BuildKit:
```bash
sudo buildkitd &
```
2. Or run BuildKit in Docker:
```bash
docker run --detach --rm --privileged \
-p 127.0.0.1:8888:8888/tcp \
--name buildkitd \
--entrypoint buildkitd \
moby/buildkit:latest \
--addr tcp://0.0.0.0:8888
kubescape patch -i nginx:1.22 -a tcp://0.0.0.0:8888
```
3. Check BuildKit socket:
```bash
ls -la /run/buildkit/buildkitd.sock
```
### Patching fails with no fixes available
**Symptom:** Patch command reports no patches available.
**Explanation:** Image patching only fixes OS-level vulnerabilities that have available patches. Application-level vulnerabilities or vulnerabilities without fixes cannot be patched.
**Solution:**
1. Check the vulnerability report:
```bash
kubescape scan image myimage:tag -v
```
2. Look for vulnerabilities marked as "wont-fix" or without fix versions.
3. Consider updating the base image to a newer version.
### Permission denied during patching
**Symptom:** Patch fails with permission errors.
**Solution:**
Run with sudo when using the default Unix socket:
```bash
sudo kubescape patch --image nginx:1.22
```
Or use the Docker-based BuildKit approach which doesn't require sudo.
---
## Operator Issues
### Operator not responding to CLI commands
**Symptom:** `kubescape operator scan` hangs or fails.
**Solutions:**
1. Verify the operator is installed:
```bash
kubectl -n kubescape get pods
```
2. Check operator logs:
```bash
kubectl -n kubescape logs -l app=kubescape-operator
```
3. Verify the operator service:
```bash
kubectl -n kubescape get svc
```
### No vulnerability manifests in cluster
**Symptom:** No VulnerabilityManifest CRs found.
**Solutions:**
1. Check if vulnerability scanning is enabled:
```bash
kubectl -n kubescape get configmap kubescape-config -o yaml
```
2. Verify kubevuln is running:
```bash
kubectl -n kubescape get pods -l app=kubevuln
```
3. Check kubevuln logs:
```bash
kubectl -n kubescape logs -l app=kubevuln
```
---
## MCP Server Issues
### MCP server fails to start
**Symptom:** `kubescape mcpserver` exits with errors.
**Solutions:**
1. Verify kubectl connectivity:
```bash
kubectl get nodes
```
2. Check if the operator CRDs are installed:
```bash
kubectl get crd vulnerabilitymanifests.spdx.softwarecomposition.kubescape.io
kubectl get crd workloadconfigurationscans.spdx.softwarecomposition.kubescape.io
```
3. Install the Kubescape operator if not present:
```bash
helm repo add kubescape https://kubescape.github.io/helm-charts/
helm upgrade --install kubescape kubescape/kubescape-operator \
--namespace kubescape --create-namespace
```
### AI assistant cannot connect to MCP server
**Symptom:** AI tool reports connection failures.
**Solutions:**
1. Verify the MCP server is running:
```bash
kubescape mcpserver
```
2. Check your AI tool's MCP configuration:
```json
{
"mcpServers": {
"kubescape": {
"command": "kubescape",
"args": ["mcpserver"]
}
}
}
```
3. Ensure kubescape is in your PATH.
---
## Output and Reporting Issues
### JSON output is malformed
**Symptom:** JSON output cannot be parsed.
**Solution:**
Ensure you're redirecting to a file, not mixing with console output:
```bash
kubescape scan --format json --output results.json
```
### SARIF format fails
**Symptom:** SARIF output not working.
**Note:** SARIF format is only supported for file/repository scans, not live cluster scans.
**Solution:**
```bash
# This works
kubescape scan /path/to/manifests --format sarif --output results.sarif
# This does NOT work
kubescape scan --format sarif --output results.sarif # cluster scan
```
### HTML/PDF report generation fails
**Symptom:** Report generation fails or produces empty files.
**Solutions:**
1. Ensure you have write permissions to the output directory.
2. Check available disk space.
3. Try JSON first to verify scan works:
```bash
kubescape scan --format json --output test.json
```
---
## Performance Issues
### High memory usage during scan
**Solutions:**
1. Scan fewer namespaces:
```bash
kubescape scan --include-namespaces production
```
2. Scan one framework at a time:
```bash
kubescape scan framework nsa
```
3. Use the operator for large clusters instead of CLI scanning.
### Slow vulnerability database downloads
**Solutions:**
1. Use offline mode with pre-downloaded artifacts:
```bash
# On a machine with good connectivity
kubescape download artifacts --output /path/to/artifacts
# On the target machine
kubescape scan --use-artifacts-from /path/to/artifacts
```
2. Configure a proxy if needed:
```bash
export HTTPS_PROXY=http://proxy:8080
kubescape scan
```
---
## Getting Help
If you're still experiencing issues:
1. **Check the logs** with debug logging:
```bash
kubescape scan -l debug
```
2. **Search existing issues:**
https://github.com/kubescape/kubescape/issues
3. **Join the community Slack:**
- [Users Channel](https://cloud-native.slack.com/archives/C04EY3ZF9GE)
- [Developers Channel](https://cloud-native.slack.com/archives/C04GY6H082K)
4. **Open a new issue** with:
- Kubescape version (`kubescape version`)
- Kubernetes version (`kubectl version`)
- Full error message
- Steps to reproduce
- Debug logs (`kubescape scan -l debug 2>&1 | tee debug.log`)

322
examples/exceptions/README.md
View File

@@ -1,111 +1,129 @@
# Kubescape Exceptions
Kubescape Exceptions is the proper way of excluding failed resources from affecting the risk score.
Kubescape Exceptions allow you to exclude specific resources from affecting your security risk score. This is useful when certain resources intentionally deviate from security best practices and you want to acknowledge this without impacting your overall compliance metrics.
e.g. When a `kube-system` resource fails and it is ok, simply add the resource to the exceptions configurations.
## Table of Contents
## Definitions
- [Use Cases](#use-cases)
- [Exception Structure](#exception-structure)
- [Usage](#usage)
- [Examples](#examples)
- [Related Documentation](#related-documentation)
---
* `name`- Exception name - unique name representing the exception
* `policyType`- Do not change
* `actions`- List of available actions. Currently, alertOnly is supported
* `resources`- List of resources to apply this exception on
* `designatorType: Attributes`- An attribute-based declaration {key: value}
Supported keys:
* `name`: k8s resource name (case-sensitive, regex supported)
* `kind`: k8s resource kind (case-sensitive, regex supported)
* `namespace`: k8s resource namespace (case-sensitive, regex supported)
* `cluster`: k8s cluster name (usually it is the `current-context`) (case-sensitive, regex supported)
* resource labels as key value (case-sensitive, regex NOT supported)
* `posturePolicies`- An attribute-based declaration {key: value}
* `frameworkName` - Framework names can be found [here](https://github.com/armosec/regolibrary/tree/master/frameworks) (regex supported)
* `controlName` - Control names can be found [here](https://github.com/armosec/regolibrary/tree/master/controls) (regex supported)
* `controlID` - Control ID can be found [here](https://github.com/armosec/regolibrary/tree/master/controls) (regex supported)
## Use Cases
You can find [here](https://github.com/kubescape/kubescape/tree/master/examples/exceptions) some examples of exceptions files
- Exclude `kube-system` resources that are expected to have elevated privileges
- Ignore development/test namespaces from production compliance reports
- Accept known risks for specific workloads after security review
- Temporarily exclude resources while fixes are being implemented
---
## Exception Structure
An exception file is a JSON array containing one or more exception objects:
```json
[
{
"name": "exception-name",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [...],
"posturePolicies": [...]
}
]
```
### Fields
| Field | Description |
|-------|-------------|
| `name` | Unique name for this exception |
| `policyType` | Must be `"postureExceptionPolicy"` |
| `actions` | List of actions. Currently only `"alertOnly"` is supported |
| `resources` | List of resources to apply this exception to |
| `posturePolicies` | List of policies/controls to exclude |
### Resource Attributes
Resources are defined using attribute-based selectors. Supported attributes:
| Attribute | Description | Regex Support |
|-----------|-------------|---------------|
| `name` | Kubernetes resource name | ✅ Yes |
| `kind` | Kubernetes resource kind (e.g., `Deployment`, `Pod`) | ✅ Yes |
| `namespace` | Kubernetes namespace | ✅ Yes |
| `cluster` | Cluster name (usually the `current-context`) | ✅ Yes |
| `<label-key>` | Any resource label (e.g., `app`, `environment`) | ❌ No |
### Policy Attributes
Policies can be specified by:
| Attribute | Description | Regex Support |
|-----------|-------------|---------------|
| `frameworkName` | Framework name (e.g., `NSA`, `MITRE`) | ✅ Yes |
| `controlName` | Control name (e.g., `HostPath mount`) | ✅ Yes |
| `controlID` | Control ID (e.g., `C-0048`) | ✅ Yes |
Find framework names in the [frameworks directory](https://github.com/kubescape/regolibrary/tree/master/frameworks) and control information in the [controls directory](https://github.com/kubescape/regolibrary/tree/master/controls).
---
## Usage
The `resources` list and `posturePolicies` list are designed to be a combination of the resources and policies to exclude.
### Running a Scan with Exceptions
> **Warning**
> You must declare at least one resource and one policy.
e.g. If you wish to exclude all namespaces with the label `"environment": "dev"`, the resource list should look as follows:
```bash
kubescape scan --exceptions /path/to/exceptions.json
```
Resources matching exceptions will be marked as `excluded` rather than `failed` in the results.
### Logic Rules
> ⚠️ **Important**: You must declare at least one resource AND one policy in each exception.
#### Within a list: OR logic
Multiple items in the `resources` list are evaluated with **OR** logic:
```json
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"namespace": ".*",
"environment": "dev"
}
}
{ "attributes": { "namespace": "dev" } },
{ "attributes": { "namespace": "test" } }
]
```
This matches resources in the `dev` namespace **OR** the `test` namespace.
But if you wish to exclude all namespaces **OR** any resource with the label `"environment": "dev"`, the resource list should look as follows:
```
#### Within an object: AND logic
Multiple attributes in a single object are evaluated with **AND** logic:
```json
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"namespace": ".*"
}
},
{
"designatorType": "Attributes",
"attributes": {
"environment": "dev"
}
}
{ "attributes": { "namespace": "production", "kind": "Deployment" } }
]
```
This matches only `Deployment` resources **AND** in the `production` namespace.
Same works with the `posturePolicies` list ->
e.g. If you wish to exclude the resources declared in the `resources` list that failed when scanning the `NSA` framework **AND** failed the `HostPath mount` control, the `posturePolicies` list should look as follows:
```
"posturePolicies": [
{
"frameworkName": "NSA",
"controlName": "HostPath mount"
}
]
```
But if you wish to exclude the resources declared in the `resources` list that failed when scanning the `NSA` framework **OR** failed the `HostPath mount` control, the `posturePolicies` list should look as follows:
```
"posturePolicies": [
{
"frameworkName": "NSA"
},
{
"controlName": "HostPath mount"
}
]
```
---
## Examples
Here are some examples demonstrating the different ways the exceptions file can be configured
### Exclude a Specific Control Everywhere
Exclude control [C-0048 (HostPath mount)](https://kubescape.io/docs/controls/c-0048/) for all resources:
### Exclude control
Exclude the [C-0060 control](https://github.com/armosec/regolibrary/blob/master/controls/allowedhostpath.json#L2) by declaring the control ID in the `"posturePolicies"` section.
The resources
```
```json
[
{
"name": "exclude-allowed-hostPath-control",
"name": "exclude-hostpath-control",
"policyType": "postureExceptionPolicy",
"actions": [
"alertOnly"
],
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
@@ -116,22 +134,48 @@ The resources
],
"posturePolicies": [
{
"controlID": "C-0060"
"controlID": "C-0048"
}
]
}
]
```
### Exclude deployments in the default namespace that failed the "HostPath mount" control
```
### Exclude All kube-system Resources
Exclude all resources in the `kube-system` namespace from all frameworks:
```json
[
{
"name": "exclude-deployments-in-ns-default",
"name": "exclude-kube-system",
"policyType": "postureExceptionPolicy",
"actions": [
"alertOnly"
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"namespace": "kube-system"
}
}
],
"posturePolicies": [
{
"frameworkName": ".*"
}
]
}
]
```
### Exclude Deployments in Default Namespace for a Specific Control
```json
[
{
"name": "exclude-deployments-in-default",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
@@ -150,21 +194,21 @@ The resources
]
```
### Exclude resources with label "app=nginx" running in a minikube cluster that failed the "NSA" or "MITRE" framework
```
### Exclude Resources by Label
Exclude resources with label `environment=dev` from NSA and MITRE frameworks:
```json
[
{
"name": "exclude-nginx-minikube",
"name": "exclude-dev-environment",
"policyType": "postureExceptionPolicy",
"actions": [
"alertOnly"
],
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"cluster": "minikube",
"app": "nginx"
"environment": "dev"
}
}
],
@@ -179,3 +223,93 @@ The resources
}
]
```
### Exclude Specific Workload in Specific Cluster
Exclude nginx resources in a minikube cluster:
```json
[
{
"name": "exclude-nginx-minikube",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"cluster": "minikube",
"app": "nginx"
}
}
],
"posturePolicies": [
{
"frameworkName": ".*"
}
]
}
]
```
### Multiple Exceptions in One File
You can combine multiple exceptions in a single file:
```json
[
{
"name": "exclude-kube-namespaces",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"namespace": "kube-system"
}
},
{
"designatorType": "Attributes",
"attributes": {
"namespace": "kube-public"
}
}
],
"posturePolicies": [
{
"frameworkName": ".*"
}
]
},
{
"name": "exclude-privileged-control-for-monitoring",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"namespace": "monitoring"
}
}
],
"posturePolicies": [
{
"controlID": "C-0057"
}
]
}
]
```
---
## Related Documentation
- [Getting Started Guide](../../docs/getting-started.md)
- [CLI Reference](../../docs/cli-reference.md)
- [Controls Reference](https://kubescape.io/docs/controls/)
- [Regolibrary - Frameworks](https://github.com/kubescape/regolibrary/tree/master/frameworks)
- [Regolibrary - Controls](https://github.com/kubescape/regolibrary/tree/master/controls)
- [Accepting Risk Documentation](https://kubescape.io/docs/accepting-risk/)

63
examples/helm_chart/README.md
View File

@@ -1,26 +1,47 @@
# Helm chart - DEPRECATED
# Helm Chart Examples
[helm chart repo](https://github.com/armosec/armo-helm)
> ⚠️ **DEPRECATED**: This directory contains legacy Helm chart examples that are no longer maintained.
## Current Helm Charts
## Values
For the latest Kubescape Helm charts, please visit:
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| affinity | object | `{}` | |
| configMap | object | `{"create":true,"params":{"clusterName":"<MyK8sClusterName>","customerGUID":"<MyGUID>,"}}` | ARMO customer information |
| fullnameOverride | string | `""` | |
| image | object | `{"imageName":"kubescape","pullPolicy":"IfNotPresent","repository":"quay.io/armosec","tag":"latest"}` | Image and version to deploy |
| imagePullSecrets | list | `[]` | |
| nameOverride | string | `""` | |
| nodeSelector | object | `{}` | |
| podAnnotations | object | `{}` | |
| podSecurityContext | object | `{}` | |
| resources | object | `{"limits":{"cpu":"500m","memory":"512Mi"},"requests":{"cpu":"200m","memory":"256Mi"}}` | Default resources for running the service in cluster |
| schedule | string | `"0 0 * * *"` | Frequency of running the scan |
| securityContext | object | `{}` | |
| serviceAccount | object | `{"annotations":{},"create":true,"name":"kubescape-discovery"}` | Service account that runs the scan and has permissions to view the cluster |
| tolerations | list | `[]` | |
**[Kubescape Helm Charts Repository](https://github.com/kubescape/helm-charts)**
----------------------------------------------
Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0)
## Quick Install
```bash
# Add the Kubescape Helm repository
helm repo add kubescape https://kubescape.github.io/helm-charts/
helm repo update
# Install the Kubescape operator
helm upgrade --install kubescape kubescape/kubescape-operator \
--namespace kubescape \
--create-namespace
```
## Available Charts
| Chart | Description |
|-------|-------------|
| [kubescape-operator](https://github.com/kubescape/helm-charts/tree/main/charts/kubescape-operator) | Full Kubescape in-cluster operator |
## Documentation
- [Operator Installation Guide](https://kubescape.io/docs/install-operator/)
- [Operator Configuration Options](https://github.com/kubescape/helm-charts/blob/main/charts/kubescape-operator/README.md)
- [Prometheus Integration](https://github.com/kubescape/helm-charts/blob/main/charts/kubescape-operator/README.md#kubescape-prometheus-integration)
## Migration from Legacy Charts
If you were using the legacy `armo-helm` charts, please migrate to the new `kubescape/helm-charts` repository. The new charts provide:
- Continuous vulnerability scanning
- Configuration scanning
- Runtime threat detection (eBPF-based)
- Network policy generation
- Prometheus metrics
- And more...
See the [migration guide](https://kubescape.io/docs/install-operator/) for detailed instructions.

408
httphandler/README.md
View File

@@ -1,174 +1,340 @@
# Kubescape HTTP Handler Package
# Kubescape HTTP Handler
Running `kubescape` will start up a web-server on port `8080` which will serve the following API's:
The HTTP Handler provides a REST API for running Kubescape scans programmatically. This enables integration with CI/CD pipelines, custom dashboards, and automation workflows.
### Trigger scan
## Table of Contents
* POST `/v1/scan` - triggers a Kubescape scan. The server will return an ID and will execute the scanning asynchronously. The request body should look [as follows](#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`
- [Overview](#overview)
- [API Reference](#api-reference)
- [Trigger Scan](#trigger-scan)
- [Get Results](#get-results)
- [Check Status](#check-status)
- [Delete Results](#delete-results)
- [Request/Response Objects](#requestresponse-objects)
- [API Examples](#api-examples)
- [Environment Variables](#environment-variables)
- [Deployment Examples](#deployment-examples)
- [Debugging](#debugging)
[Response](#response-object):
---
```
## 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:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `wait` | bool | `false` | Wait for scan to complete (synchronous mode) |
| `keep` | bool | `false` | Keep results in cache after returning |
**Request Body:** See [Trigger Scan Object](#trigger-scan-object)
**Response (async):**
```json
{
"id": <str>, // scan ID
"type": "busy", // response object type
"response": <message:string> // message indicating scanning is still in progress
"id": "scan-12345",
"type": "busy",
"response": "scanning in progress"
}
```
> When scanning was triggered with the `wait=true` query param, the response is like the [`/v1/results` API](#get-results) response
**Response (sync with `wait=true`):** Same as [Get Results](#get-results) response.
### Get results
* GET `/v1/results` - request kubescape scan results
* * query `id=<string>` -> request results of a specific scan ID. If empty will return the 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):
### Get Results
When scanning was done successfully
```
**Endpoint:** `GET /v1/results`
Retrieve scan results.
**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id` | string | - | Scan ID. If empty, returns latest results |
| `keep` | bool | `false` | Keep results in cache after returning |
**Response (success):**
```json
{
"id": <str>, // scan ID
"type": "v1results", // response object type
"response": <object:v1results> // v1 results payload
"id": "scan-12345",
"type": "v1results",
"response": { /* scan results object */ }
}
```
When scanning failed
```
**Response (error):**
```json
{
"id": <str>, // scan ID
"type": "error", // response object type
"response": <error:string> // error string
"id": "scan-12345",
"type": "error",
"response": "error message"
}
```
When scanning is in progress
```
**Response (in progress):**
```json
{
"id": <str>, // scan ID
"type": "busy", // response object type
"response": <message:string> // message indicating scanning is still in progress
}
```
### 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, it will check if any scan is still 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
"id": "scan-12345",
"type": "busy",
"response": "scanning in progress"
}
```
When scanning is not 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:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id` | string | - | Scan ID. If empty, checks if any scan is in progress |
**Response (in progress):**
```json
{
"id": <str>, // scan ID
"type": "notBusy", // response object type
"response": <message:string> // message indicating scanning is successfully done
"id": "scan-12345",
"type": "busy",
"response": "scanning in progress"
}
```
### Delete cached results
* DELETE `/v1/results` - Delete kubescape scan results from storage. If empty will delete the latest results
* * query `id=<string>`: Delete ID of specific results
* * query `all`: Delete all cached results
**Response (complete):**
## Objects
### Trigger scan object
```
```json
{
"format": <str>, // results format [default: json] (same as 'kubescape scan --format')
"excludedNamespaces": [<str>], // list of namespaces to exclude (same as 'kubescape scan --excluded-namespaces')
"includeNamespaces": [<str>], // list of namespaces to include (same as 'kubescape scan --include-namespaces')
"useCachedArtifacts"`: <bool>, // use the cached artifacts instead of downloading (offline support)
"hostScanner": <bool>, // deploy Kubescape host-sensor daemonset in the scanned cluster. Deleting it right after we collecting the data. Required to collect valuable data from cluster nodes for certain controls
"keepLocal": <bool>, // do not submit results to Kubescape cloud (same as 'kubescape scan --keep-local')
"account": <str>, // account ID (same as 'kubescape scan --account')
"access-key": <str>, // account ID (same as 'kubescape scan --accessKey')
"targetType": <str>, // framework/control
"targetNames": [<str>] // names. e.g. when targetType==framework, targetNames=["nsa", "mitre"]
"id": "scan-12345",
"type": "notBusy",
"response": "scanning completed"
}
```
### Response object
---
```
### Delete Results
**Endpoint:** `DELETE /v1/results`
Delete cached scan results.
**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id` | string | - | Scan ID to delete. If empty, deletes latest |
| `all` | bool | `false` | Delete all cached results |
---
## Request/Response Objects
### Trigger Scan Object
```json
{
"id": <str>, // scan ID
"type": <responseType:str>, // response object type
"response": <object:interface> // response payload as list of bytes
"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 types
* "v1results" - v1 results object
* "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
| Field | Type | Description |
|-------|------|-------------|
| `format` | string | Output format (default: `json`) |
| `excludedNamespaces` | []string | Namespaces to exclude from scan |
| `includeNamespaces` | []string | Namespaces to include in scan |
| `useCachedArtifacts` | bool | Use cached artifacts (offline mode) |
| `keepLocal` | bool | Don't submit results to backend |
| `account` | string | Kubescape SaaS account ID |
| `accessKey` | string | Kubescape SaaS access key |
| `targetType` | string | `"framework"` or `"control"` |
| `targetNames` | []string | Frameworks/controls to scan |
### Response Object
```json
{
"id": "scan-12345",
"type": "v1results",
"response": { /* payload */ }
}
```
| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Scan identifier |
| `type` | string | Response type (see below) |
| `response` | any | Response payload |
**Response Types:**
| Type | Description |
|------|-------------|
| `v1results` | Scan results object |
| `busy` | Scan in progress |
| `notBusy` | No scan in progress |
| `ready` | Scan complete, results ready |
| `error` | Error occurred |
---
## API Examples
#### Default scan
1. Trigger kubescape scan
```bash
curl --header "Content-Type: application/json" --request POST --data '{"hostScanner":true}' http://127.0.0.1:8080/v1/scan
```
2. Get kubescape scan results
```bash
curl --request GET http://127.0.0.1:8080/v1/results -o response.json
```
#### Trigger scan and wait for the scan to end
### Basic Scan (Async)
```bash
curl --header "Content-Type: application/json" --request POST --data '{"hostScanner":true}' http://127.0.0.1:8080/v1/scan?wait -o scan_results.json
```
#### Scan single namespace with a specific framework
```bash
curl --header "Content-Type: application/json" \
--request POST \
--data '{"hostScanner":true, "includeNamespaces": ["kubescape"], "targetType": "framework", "targetNames": ["nsa"] }' \
http://127.0.0.1:8080/v1/scan
# 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
```
#### Data profiling
Analyze profiled data using [pprof](https://github.com/google/pprof/blob/main/doc/README.md).
[How to use](https://pkg.go.dev/net/http/pprof)
### Synchronous Scan
example:
```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:
| Variable | Description | Example |
|----------|-------------|---------|
| `KS_ACCOUNT` | Default account ID | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| `KS_EXCLUDE_NAMESPACES` | Default namespaces to exclude | `kube-system,kube-public` |
| `KS_INCLUDE_NAMESPACES` | Default namespaces to include | `production,staging` |
| `KS_FORMAT` | Default output format | `json` |
| `KS_LOGGER_NAME` | Logger name | `kubescape` |
| `KS_LOGGER_LEVEL` | Log level | `info`, `debug`, `warning`, `error` |
| `KS_DOWNLOAD_ARTIFACTS` | Download artifacts on each scan | `true`, `false` |
---
## Deployment Examples
### Microservice Deployment
Deploy Kubescape as a microservice in your cluster for API-driven scanning.
📖 **[Microservice Deployment Guide →](examples/microservice/README.md)**
### Prometheus Integration
Expose Kubescape metrics for Prometheus scraping.
📖 **[Prometheus Integration Guide →](examples/prometheus/README.md)**
---
## 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
```
## Examples
For more information on pprof, see the [pprof documentation](https://pkg.go.dev/net/http/pprof).
* [Prometheus](examples/prometheus/README.md)
* [Microservice](examples/microservice/README.md)
---
## Related Documentation
## Supported environment variables
* `KS_ACCOUNT`: Account ID
* `KS_EXCLUDE_NAMESPACES`: List of namespaces to exclude, e.g. `KS_EXCLUDE_NAMESPACES=kube-system,kube-public`
* `KS_INCLUDE_NAMESPACES`: List of namespaces to include, rest of the namespaces will be ignored. e.g. `KS_INCLUDE_NAMESPACES=dev,prod`
* `KS_HOST_SCAN_YAML`: Full path to the host scanner YAML
* `KS_FORMAT`: Output file format. default is json
* `KS_ENABLE_HOST_SCANNER`: Enable the host scanner feature
* `KS_DOWNLOAD_ARTIFACTS`: Download the artifacts every scan
* `KS_LOGGER_NAME`: Set logger name
* `KS_LOGGER_LEVEL`: Set logger level
- [CLI Reference](../docs/cli-reference.md)
- [Architecture](../docs/architecture.md)
- [Getting Started Guide](../docs/getting-started.md)
- [Troubleshooting](../docs/troubleshooting.md)

289
httphandler/examples/microservice/README.md
View File

@@ -1,21 +1,274 @@
# Kubescape as a microservice
# Kubescape as a Microservice
1. Deploy kubescape microservice
```bash
kubectl apply -f ks-deployment.yaml
```
> **Note**
> Make sure the configurations suit your cluster (e.g. `serviceType`, namespace, etc.)
This guide explains how to deploy Kubescape as a microservice in your Kubernetes cluster, enabling API-driven security scanning.
2. Trigger scan
```bash
curl --header "Content-Type: application/json" \
--request POST \
--data '{"account":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX","hostScanner":true}' \
http://127.0.0.1:8080/v1/scan
```
## Table of Contents
3. Get results
```bash
curl --request GET http://127.0.0.1:8080/v1/results -o results.json
```
- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Deployment](#deployment)
- [API Usage](#api-usage)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
---
## Overview
Running Kubescape as a microservice allows you to:
- Trigger security scans via REST API
- Integrate with CI/CD pipelines
- Build custom dashboards and automation
- Schedule and manage scans programmatically
---
## Prerequisites
- Kubernetes cluster with `kubectl` access
- Cluster admin permissions (for RBAC setup)
- Network access to the Kubescape service endpoint
---
## Deployment
### 1. Deploy Kubescape Microservice
```bash
kubectl apply -f ks-deployment.yaml
```
> **Note**: Review and modify `ks-deployment.yaml` to match your cluster configuration:
> - `serviceType` (ClusterIP, NodePort, LoadBalancer)
> - Namespace
> - Resource limits
> - Service account permissions
### 2. Verify Deployment
```bash
# Check pod status
kubectl get pods -l app=kubescape
# Check service
kubectl get svc kubescape
```
### 3. Access the Service
```bash
# Port-forward for local access
kubectl port-forward svc/kubescape 8080:8080
# Or get the external IP (if using LoadBalancer)
kubectl get svc kubescape -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
```
---
## API Usage
### Trigger a Scan
```bash
curl --header "Content-Type: application/json" \
--request POST \
--data '{
"account": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"targetType": "framework",
"targetNames": ["nsa", "mitre"]
}' \
http://127.0.0.1:8080/v1/scan
```
**Response:**
```json
{
"id": "scan-12345",
"type": "busy",
"response": "scanning in progress"
}
```
### Trigger Scan and Wait for Results
```bash
curl --header "Content-Type: application/json" \
--request POST \
--data '{"targetType": "framework", "targetNames": ["nsa"]}' \
"http://127.0.0.1:8080/v1/scan?wait=true" \
-o results.json
```
### Check Scan Status
```bash
curl --request GET "http://127.0.0.1:8080/v1/status?id=scan-12345"
```
### Get Scan Results
```bash
curl --request GET "http://127.0.0.1:8080/v1/results?id=scan-12345" -o results.json
```
### Get Latest Results
```bash
curl --request GET http://127.0.0.1:8080/v1/results -o results.json
```
### Delete Cached Results
```bash
# Delete specific results
curl --request DELETE "http://127.0.0.1:8080/v1/results?id=scan-12345"
# Delete all cached results
curl --request DELETE "http://127.0.0.1:8080/v1/results?all=true"
```
---
## Configuration
### Scan Request Options
| Field | Type | Description |
|-------|------|-------------|
| `account` | string | Kubescape SaaS account ID (optional) |
| `accessKey` | string | Kubescape SaaS access key (optional) |
| `targetType` | string | `"framework"` or `"control"` |
| `targetNames` | array | List of frameworks/controls to scan |
| `excludedNamespaces` | array | Namespaces to exclude |
| `includeNamespaces` | array | Namespaces to include |
| `format` | string | Output format (default: `"json"`) |
| `keepLocal` | boolean | Don't submit results to backend |
| `useCachedArtifacts` | boolean | Use cached artifacts (offline mode) |
### Query Parameters
| Parameter | Description |
|-----------|-------------|
| `wait=true` | Wait for scan to complete (synchronous) |
| `keep=true` | Keep results in cache after returning |
| `id=<scan-id>` | Specify a particular scan ID |
### Environment Variables
Configure the microservice using environment variables in your deployment:
| Variable | Description |
|----------|-------------|
| `KS_ACCOUNT` | Default account ID |
| `KS_EXCLUDE_NAMESPACES` | Default namespaces to exclude |
| `KS_INCLUDE_NAMESPACES` | Default namespaces to include |
| `KS_FORMAT` | Default output format |
| `KS_LOGGER_LEVEL` | Log level (`debug`, `info`, `warning`, `error`) |
---
## Example Workflows
### CI/CD Integration
```bash
#!/bin/bash
# Trigger scan and wait for results
RESULT=$(curl -s --header "Content-Type: application/json" \
--request POST \
--data '{"targetType": "framework", "targetNames": ["nsa"]}' \
"http://kubescape:8080/v1/scan?wait=true")
# Extract compliance score
SCORE=$(echo $RESULT | jq '.response.summaryDetails.complianceScore')
# Fail pipeline if score is below threshold
if (( $(echo "$SCORE < 80" | bc -l) )); then
echo "Compliance score $SCORE is below threshold (80)"
exit 1
fi
```
### Scheduled Scanning
Use a Kubernetes CronJob to trigger regular scans:
```yaml
apiVersion: batch/v1
kind: CronJob
metadata:
name: kubescape-scheduled-scan
spec:
schedule: "0 */6 * * *" # Every 6 hours
jobTemplate:
spec:
template:
spec:
containers:
- name: scanner
image: curlimages/curl
command:
- /bin/sh
- -c
- |
curl -X POST http://kubescape:8080/v1/scan \
-H "Content-Type: application/json" \
-d '{"targetType": "framework", "targetNames": ["nsa", "mitre"]}'
restartPolicy: OnFailure
```
---
## Troubleshooting
### Service Not Accessible
```bash
# Check pod logs
kubectl logs -l app=kubescape
# Check service endpoints
kubectl get endpoints kubescape
# Verify network policies
kubectl get networkpolicies
```
### Scan Times Out
For large clusters, use asynchronous scanning:
```bash
# Trigger scan (returns immediately)
curl -X POST http://127.0.0.1:8080/v1/scan \
-H "Content-Type: application/json" \
-d '{"targetType": "framework", "targetNames": ["nsa"]}'
# Poll for status
while true; do
STATUS=$(curl -s http://127.0.0.1:8080/v1/status | jq -r '.type')
if [ "$STATUS" != "busy" ]; then
break
fi
sleep 10
done
# Get results
curl http://127.0.0.1:8080/v1/results -o results.json
```
### Permission Errors
Ensure the service account has sufficient RBAC permissions to read cluster resources.
---
## Related Documentation
- [HTTP Handler API Reference](../../README.md)
- [Kubescape CLI Reference](../../../docs/cli-reference.md)
- [Prometheus Integration](../prometheus/README.md)
- [Getting Started Guide](../../../docs/getting-started.md)

70
httphandler/examples/prometheus/README.md
View File

@@ -1,3 +1,69 @@
# Prometheus Kubescape Integration
# Prometheus Integration
Please find the new documentation at the following link: [Kubescape Prometheus Integration](https://github.com/kubescape/helm-charts/blob/main/charts/kubescape-operator/README.md#kubescape-prometheus-integration)
> **Note**: The Prometheus integration documentation has moved to the Kubescape Helm Charts repository.
## Current Documentation
For the latest Prometheus integration guide, please visit:
**[Kubescape Prometheus Integration →](https://github.com/kubescape/helm-charts/blob/main/charts/kubescape-operator/README.md#kubescape-prometheus-integration)**
## Quick Overview
The Kubescape Operator exposes Prometheus metrics for monitoring your cluster's security posture.
### Features
- Compliance score metrics per framework
- Control pass/fail counts
- Vulnerability counts by severity
- Resource scan statistics
### Installation with Prometheus Support
```bash
helm repo add kubescape https://kubescape.github.io/helm-charts/
helm repo update
helm upgrade --install kubescape kubescape/kubescape-operator \
--namespace kubescape \
--create-namespace \
--set capabilities.prometheusExporter=enable
```
### Available Metrics
| Metric | Description |
|--------|-------------|
| `kubescape_compliance_score` | Compliance score per framework (0-100) |
| `kubescape_controls_passed` | Number of passed controls |
| `kubescape_controls_failed` | Number of failed controls |
| `kubescape_resources_scanned` | Total resources scanned |
| `kubescape_vulnerabilities_total` | Vulnerabilities by severity |
### ServiceMonitor (for Prometheus Operator)
If you're using the Prometheus Operator, the Helm chart can create a ServiceMonitor:
```bash
helm upgrade --install kubescape kubescape/kubescape-operator \
--namespace kubescape \
--create-namespace \
--set capabilities.prometheusExporter=enable \
--set serviceMonitor.enabled=true
```
### Grafana Dashboard
A pre-built Grafana dashboard is available for visualizing Kubescape metrics:
- [Kubescape Grafana Dashboard](https://grafana.com/grafana/dashboards/18183-kubescape/)
---
## Related Documentation
- [Kubescape Operator Installation](https://kubescape.io/docs/install-operator/)
- [Helm Charts Repository](https://github.com/kubescape/helm-charts)
- [HTTP Handler API](../../README.md)
- [Microservice Deployment](../microservice/README.md)