npm package: @modular-intelligence/kubescape
Description: MCP server wrapping Kubescape for Kubernetes security posture scanning
Latest version: 1.0.2

# Kubescape MCP Server

Model Context Protocol (MCP) server that wraps the [Kubescape](https://github.com/kubescape/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
   ```bash
   # 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
   ```bash
   # Verify kubectl is configured
   kubectl cluster-info
   kubectl get nodes
   ```

3. **Bun**: JavaScript runtime (for running the server)
   ```bash
   curl -fsSL https://bun.sh/install | bash
   ```

### Kubernetes Access

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

```bash
# 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:
   ```bash
   cd /path/to/mi-mcp-servers/packages/kubescape
   ```

2. Install dependencies:
   ```bash
   bun install
   ```

3. Build the server:
   ```bash
   bun run build
   ```

## Usage

### Running the Server

Start the server using stdio transport:

```bash
bun run start
```

Or run directly:

```bash
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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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):

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

```yaml
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

```bash
bun run build
```

### Testing

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

```bash
# 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](https://kubescape.io/docs/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Kubernetes Security](https://kubernetes.io/docs/concepts/security/)

## Support

For issues related to:
- **MCP server**: Check this README and server logs
- **Kubescape CLI**: See [Kubescape GitHub](https://github.com/kubescape/kubescape)
- **Kubernetes access**: See [kubectl documentation](https://kubernetes.io/docs/reference/kubectl/)