Kubescape MCP Server

Model Context Protocol (MCP) server that wraps the Kubescape CLI for Kubernetes security posture scanning.

Overview

This MCP server provides comprehensive Kubernetes security scanning capabilities through Kubescape, enabling AI assistants to:

• Scan clusters against security frameworks (NSA, MITRE, CIS, etc.)
• Analyze specific security controls
• Scan workload manifests for vulnerabilities
• Scan container images for CVEs
• Check compliance scores and exceptions

Prerequisites

Required Dependencies

1. Kubescape CLI: Install the Kubescape command-line tool

   # macOS
   brew install kubescape
   
   # Linux
   curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash
   
   # Windows
   iwr -useb https://raw.githubusercontent.com/kubescape/kubescape/master/install.ps1 | iex

2. kubectl: Kubernetes CLI with configured cluster access

   # Verify kubectl is configured
   kubectl cluster-info
   kubectl get nodes

3. Bun: JavaScript runtime (for running the server)

   curl -fsSL https://bun.sh/install | bash

Kubernetes Access

The server requires kubectl to be configured with access to your Kubernetes cluster:

# List available contexts
kubectl config get-contexts

# Set current context
kubectl config use-context <context-name>

# Verify access
kubectl auth can-i get pods --all-namespaces

Installation

1. Clone or download this server:

   cd /path/to/mi-mcp-servers/packages/kubescape

2. Install dependencies:

   bun install

3. Build the server:

   bun run build

Usage

Running the Server

Start the server using stdio transport:

bun run start

Or run directly:

bun run src/index.ts

Available Tools

1. kubescape_scan_framework

Scan a Kubernetes cluster against a security framework.

Parameters:

• framework (required): Security framework to scan against
  • Options: NSA, MITRE, CIS, AllControls, ArmoBest, DevOpsBest, SOC2
• namespace (optional): Kubernetes namespace to scan
• kube_context (optional): Kubernetes context name
• exclude_namespaces (optional): Array of namespaces to exclude
• severity (optional): Minimum severity level (critical, high, medium, low)
• timeout (optional): Scan timeout in seconds (default: 120, max: 600)

Returns:

{
  "framework": "NSA",
  "results": [
    {
      "control_id": "C-0001",
      "control_name": "Host PID/IPC privileges",
      "severity": "high",
      "status": "failed",
      "failed_resources": 2,
      "total_resources": 10,
      "description": "Controls should not share host process ID namespace",
      "remediation": "Set hostPID and hostIPC to false"
    }
  ],
  "summary": {
    "passed": 25,
    "failed": 5,
    "skipped": 2,
    "total": 32
  },
  "compliance_score": 78.125
}

Example:

{
  "framework": "NSA",
  "namespace": "production",
  "severity": "high",
  "timeout": 180
}

2. kubescape_scan_control

Scan a specific security control by ID.

Parameters:

• control_id (required): Control ID (e.g., C-0001 or c-0001)
• namespace (optional): Kubernetes namespace
• kube_context (optional): Kubernetes context
• timeout (optional): Scan timeout in seconds

Returns:

{
  "control_id": "C-0001",
  "control_name": "Host PID/IPC privileges",
  "description": "Checks if containers are sharing the host process ID namespace",
  "remediation": "Set hostPID and hostIPC to false in pod specifications",
  "resources": [
    {
      "kind": "Pod",
      "name": "nginx-deployment-abc123",
      "namespace": "default",
      "status": "failed",
      "failed_paths": ["spec.hostPID", "spec.hostIPC"]
    }
  ]
}

3. kubescape_scan_workload

Scan a workload manifest file for security issues.

Parameters:

• workload_path (required): Path to YAML manifest file
• framework (optional): Framework to scan against
• timeout (optional): Scan timeout in seconds

Returns:

{
  "file": "/path/to/deployment.yaml",
  "results": [
    {
      "control_id": "C-0009",
      "control_name": "Resource limits",
      "severity": "medium",
      "status": "failed",
      "failed_paths": ["spec.containers[0].resources.limits"]
    }
  ],
  "summary": {
    "passed": 15,
    "failed": 3,
    "skipped": 0,
    "total": 18
  }
}

4. kubescape_scan_image

Scan a container image for vulnerabilities.

Parameters:

• image (required): Container image reference (e.g., nginx:latest)
• timeout (optional): Scan timeout in seconds

Returns:

{
  "image": "nginx:latest",
  "vulnerabilities": [
    {
      "cve": "CVE-2024-1234",
      "severity": "high",
      "package": "libssl",
      "version": "1.1.1",
      "fix_version": "1.1.2"
    }
  ],
  "summary": {
    "critical": 0,
    "high": 3,
    "medium": 12,
    "low": 45,
    "total": 60
  }
}

5. kubescape_list_frameworks

List all available security frameworks.

Parameters: None

Returns:

{
  "frameworks": [
    {
      "name": "NSA",
      "description": "NSA and CISA Kubernetes Hardening Guidance",
      "controls_count": 32
    },
    {
      "name": "MITRE",
      "description": "MITRE ATT&CK framework for Kubernetes",
      "controls_count": 28
    }
  ]
}

6. kubescape_exceptions

List configured exceptions (suppressed findings).

Parameters:

• namespace (optional): Kubernetes namespace
• kube_context (optional): Kubernetes context

Returns:

{
  "exceptions": [
    {
      "name": "allow-hostpath",
      "policy_type": "postureExceptionPolicy",
      "actions": ["alertOnly"],
      "resources": ["Pod/nginx"],
      "controls": ["C-0045", "C-0046"]
    }
  ],
  "total": 1
}

7. kubescape_compliance_score

Get detailed compliance score with breakdown by severity.

Parameters:

• framework (required): Security framework
• namespace (optional): Kubernetes namespace
• kube_context (optional): Kubernetes context
• timeout (optional): Scan timeout in seconds

Returns:

{
  "framework": "NSA",
  "namespace": "production",
  "compliance_score": 78.125,
  "total_controls": 32,
  "passed": 25,
  "failed": 7,
  "by_severity": {
    "critical": { "passed": 5, "failed": 0 },
    "high": { "passed": 8, "failed": 3 },
    "medium": { "passed": 10, "failed": 3 },
    "low": { "passed": 2, "failed": 1 }
  },
  "top_failures": [
    {
      "control_id": "C-0009",
      "name": "Resource limits",
      "severity": "medium",
      "failed_resources": 15
    }
  ]
}

Security Features

Input Validation

The server implements strict input validation to prevent command injection:

• Namespace validation: Must match /^[a-z0-9][a-z0-9\-]*[a-z0-9]$/
• Context validation: Must match /^[a-zA-Z0-9._\-@/]+$/
• Framework whitelist: Only allows predefined frameworks
• Control ID format: Must match [A-Z]-XXXX or c-XXXX pattern

Blocked Flags

The following flags are blocked for security reasons:

• --submit: Prevents submitting data to external services
• --account: Prevents account-related operations
• --enable-host-scan: Prevents host-level scanning

Resource Limits

• Timeout: Maximum 600 seconds (10 minutes)
• Buffer size: 10MB maximum output
• Kill signal: SIGKILL for stuck processes

Configuration

Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "kubescape": {
      "command": "bun",
      "args": ["run", "/path/to/mi-mcp-servers/packages/kubescape/src/index.ts"]
    }
  }
}

Environment Variables

The server respects standard Kubernetes environment variables:

• KUBECONFIG: Path to kubeconfig file
• KUBERNETES_SERVICE_HOST: Kubernetes API server host
• KUBERNETES_SERVICE_PORT: Kubernetes API server port

Permissions

The server operates in read-only mode and does not modify cluster state. Required permissions:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kubescape-scanner
rules:
- apiGroups: ["*"]
  resources: ["*"]
  verbs: ["get", "list"]

Troubleshooting

Kubescape Not Found

If you get "Kubescape CLI not found":

1. Verify installation: which kubescape
2. Check PATH: echo $PATH
3. Reinstall if needed

Cluster Access Issues

If scans fail with authentication errors:

1. Verify kubectl access: kubectl get nodes
2. Check current context: kubectl config current-context
3. Verify permissions: kubectl auth can-i get pods --all-namespaces

Timeout Errors

If scans timeout:

1. Increase timeout parameter
2. Reduce scan scope (use specific namespace)
3. Check cluster responsiveness

JSON Parsing Errors

If output parsing fails:

1. Run kubescape directly to verify output format
2. Check Kubescape version: kubescape version
3. Update Kubescape if needed

Development

Project Structure

kubescape/
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── README.md            # Documentation
└── src/
    ├── index.ts         # MCP server entry point
    ├── schemas.ts       # Zod parameter schemas
    ├── security.ts      # Input validation
    ├── cli-executor.ts  # Command execution
    └── tools/
        ├── kubescape-scan-framework.ts
        ├── kubescape-scan-control.ts
        ├── kubescape-scan-workload.ts
        ├── kubescape-scan-image.ts
        ├── kubescape-list-frameworks.ts
        ├── kubescape-exceptions.ts
        └── kubescape-compliance-score.ts

Building

bun run build

Testing

Test individual tools using the MCP Inspector or by running kubescape commands directly:

# Test framework scan
kubescape scan framework NSA --format json

# Test control scan
kubescape scan control C-0001 --format json

# Test workload scan
kubescape scan deployment.yaml --format json

License

This MCP server is provided as-is for use with Kubescape. See Kubescape's license for CLI tool licensing.

Related Links

• Kubescape Documentation
• Model Context Protocol
• Kubernetes Security

Support

For issues related to:

• MCP server: Check this README and server logs
• Kubescape CLI: See Kubescape GitHub
• Kubernetes access: See kubectl documentation