npm package: @modular-intelligence/container-security
Description: MCP server for container and Kubernetes security scanning
Latest version: 1.0.2

# Container Security MCP Server

A comprehensive container and Kubernetes security scanning service that integrates with industry-leading security tools. This MCP (Model Context Protocol) server enables Claude to perform vulnerability scanning, security audits, and compliance checks on container images, filesystems, and Kubernetes clusters.

## Overview

This server provides access to four major container and Kubernetes security platforms through a unified interface:

- **Trivy** - Vulnerability and misconfiguration scanning for container images and filesystems
- **Kube-bench** - CIS Kubernetes benchmark security assessment and compliance validation
- **Docker** - Container image inspection and layer analysis
- **kubectl** - Kubernetes pod security auditing and security context validation

Perfect for container security assessments, supply chain security, compliance auditing, and vulnerability management.

## Tools

| Tool | CLI Tool | Description |
|------|----------|-------------|
| `trivy_scan_image` | Trivy | Scan container images for vulnerabilities and misconfigurations |
| `trivy_scan_fs` | Trivy | Scan filesystem/project directories for vulnerabilities |
| `kube_bench` | kube-bench | Run CIS Kubernetes benchmark security checks |
| `docker_inspect` | Docker | Inspect container image configuration and layers |
| `k8s_pod_security` | kubectl | Audit Kubernetes pods for security standard violations |
| `dockerfile_lint` | native | Lint Dockerfiles for security issues and best practices |

### Trivy Image Scan

Scan a container image for vulnerabilities and security misconfigurations using Trivy.

**Input Parameters:**
```typescript
{
  image: string              // Container image name (e.g., 'nginx:latest', 'registry.io/repo:tag')
  severity: string           // Minimum severity filter: UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL (optional)
  timeout: number            // Timeout in seconds (10-600, default: 120)
}
```

**Example Request:**
```json
{
  "image": "nginx:1.21",
  "severity": "HIGH",
  "timeout": 120
}
```

**Example Output:**
```json
{
  "image": "nginx:1.21",
  "scan_date": "2024-01-15T10:30:45.000Z",
  "total_vulnerabilities": 5,
  "summary": {
    "critical": 1,
    "high": 3,
    "medium": 1,
    "low": 0
  },
  "vulnerabilities": [
    {
      "id": "CVE-2021-1234",
      "severity": "CRITICAL",
      "pkg_name": "openssl",
      "installed_version": "1.1.1g",
      "fixed_version": "1.1.1h",
      "title": "OpenSSL Buffer Overflow",
      "description": "A remote code execution vulnerability in OpenSSL 1.1.1g and earlier"
    },
    {
      "id": "CVE-2021-5678",
      "severity": "HIGH",
      "pkg_name": "libc6",
      "installed_version": "2.31-1",
      "fixed_version": "2.31-13",
      "title": "Memory Corruption in libc",
      "description": "Memory corruption vulnerability allowing privilege escalation"
    }
  ]
}
```

### Trivy Filesystem Scan

Scan a filesystem or project directory for vulnerabilities, misconfigurations, and secrets using Trivy.

**Input Parameters:**
```typescript
{
  path: string               // Absolute path to file or directory
  severity: string           // Minimum severity filter: UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL (optional)
  timeout: number            // Timeout in seconds (10-600, default: 120)
}
```

**Example Request:**
```json
{
  "path": "/home/user/myproject",
  "severity": "HIGH",
  "timeout": 180
}
```

**Example Output:**
```json
{
  "path": "/home/user/myproject",
  "scan_date": "2024-01-15T10:35:20.000Z",
  "total_vulnerabilities": 8,
  "summary": {
    "critical": 0,
    "high": 2,
    "medium": 4,
    "low": 2
  },
  "vulnerabilities": [
    {
      "id": "CVE-2023-4567",
      "severity": "HIGH",
      "pkg_name": "requests",
      "installed_version": "2.25.1",
      "fixed_version": "2.28.0",
      "title": "HTTP Request Smuggling in requests library",
      "description": "Vulnerability in requests library authentication handling"
    },
    {
      "id": "GHSA-1234-5678-90ab",
      "severity": "MEDIUM",
      "pkg_name": "pyyaml",
      "installed_version": "5.3",
      "fixed_version": "5.4.1",
      "title": "YAML Deserialization RCE",
      "description": "Remote code execution via YAML deserialization"
    }
  ]
}
```

### Kube-bench

Run CIS Kubernetes benchmark security checks on your Kubernetes cluster.

**Input Parameters:**
```typescript
{
  target: string             // Specific target to benchmark: master, node, etcd, policies (optional)
  timeout: number            // Timeout in seconds (10-600, default: 120)
}
```

**Example Request:**
```json
{
  "target": "master",
  "timeout": 120
}
```

**Example Output:**
```json
{
  "scan_date": "2024-01-15T11:00:00.000Z",
  "target": "master",
  "total_tests": 24,
  "summary": {
    "PASS": 18,
    "FAIL": 4,
    "WARN": 2,
    "INFO": 0
  },
  "results": [
    {
      "section": "1. Master Node Security Configuration",
      "number": "1.1.1",
      "description": "Ensure that the apiserver pod specification file permissions are set to 644 or more restrictive",
      "status": "PASS",
      "remediation": "Run the command: chmod 644 /etc/kubernetes/manifests/kube-apiserver.yaml"
    },
    {
      "section": "1. Master Node Security Configuration",
      "number": "1.1.5",
      "description": "Ensure that the API server certificate authorities file permissions are set to 644 or more restrictive",
      "status": "FAIL",
      "remediation": "Run the command: chmod 644 /etc/kubernetes/pki/ca.crt"
    },
    {
      "section": "4. Policies",
      "number": "4.1.1",
      "description": "Ensure that the cluster-admin role is only used where required",
      "status": "WARN",
      "remediation": "Review RBAC policies and restrict cluster-admin role usage"
    }
  ]
}
```

### Docker Inspect

Inspect a container image to retrieve configuration, layers, and metadata.

**Input Parameters:**
```typescript
{
  image: string              // Container image name (e.g., 'nginx:latest', 'registry.io/repo:tag')
  timeout: number            // Timeout in seconds (10-600, default: 120)
}
```

**Example Request:**
```json
{
  "image": "python:3.11-slim",
  "timeout": 120
}
```

**Example Output:**
```json
{
  "image": "python:3.11-slim",
  "created": "2024-01-10T12:30:45.000Z",
  "size": 167772160,
  "architecture": "amd64",
  "os": "linux",
  "config": {
    "env": [
      "PATH=/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
      "LANG=C.UTF-8",
      "PYTHON_VERSION=3.11.1"
    ],
    "cmd": ["python3"],
    "entrypoint": null,
    "exposed_ports": ["8000"],
    "user": "root",
    "working_dir": "/app",
    "labels": {
      "org.opencontainers.image.vendor": "Debian"
    }
  },
  "total_layers": 8,
  "layers": [
    {
      "created": "2024-01-09T08:15:30.000Z",
      "created_by": "/bin/sh -c #(nop) ADD file:abc123 in / ",
      "size": 80621568,
      "comment": ""
    },
    {
      "created": "2024-01-09T08:16:00.000Z",
      "created_by": "/bin/sh -c apt-get update && apt-get install -y python3",
      "size": 87150592,
      "comment": ""
    }
  ]
}
```

### Kubernetes Pod Security Audit

Audit Kubernetes pods in a namespace for security standard violations and misconfigurations.

**Input Parameters:**
```typescript
{
  namespace: string          // Kubernetes namespace (default: 'default')
  pod_name: string           // Specific pod name to audit (optional)
  timeout: number            // Timeout in seconds (10-600, default: 120)
}
```

**Example Request:**
```json
{
  "namespace": "production",
  "pod_name": "app-deployment-xyz",
  "timeout": 120
}
```

**Example Output:**
```json
{
  "namespace": "production",
  "pod_name": "app-deployment-xyz",
  "scan_date": "2024-01-15T11:15:30.000Z",
  "total_pods": 1,
  "total_findings": 4,
  "summary": {
    "critical": 1,
    "high": 2,
    "medium": 1,
    "low": 0
  },
  "findings": [
    {
      "pod_name": "app-deployment-xyz",
      "namespace": "production",
      "container_name": "app",
      "issue": "privileged container",
      "severity": "CRITICAL",
      "details": "Container runs in privileged mode"
    },
    {
      "pod_name": "app-deployment-xyz",
      "namespace": "production",
      "container_name": "app",
      "issue": "hostNetwork enabled",
      "severity": "HIGH",
      "details": "Pod has access to host network namespace"
    },
    {
      "pod_name": "app-deployment-xyz",
      "namespace": "production",
      "container_name": "app",
      "issue": "running as root",
      "severity": "MEDIUM",
      "details": "Container may run as root user"
    },
    {
      "pod_name": "app-deployment-xyz",
      "namespace": "production",
      "container_name": "app",
      "issue": "writable root filesystem",
      "severity": "LOW",
      "details": "Container root filesystem is writable"
    }
  ]
}
```

### Dockerfile Lint

Lint a Dockerfile for security issues, best practices, and misconfigurations.

**Input Parameters:**
```typescript
{
  file_path: string          // Absolute path to Dockerfile
  timeout: number            // Timeout in seconds (10-600, default: 120)
}
```

**Example Request:**
```json
{
  "file_path": "/home/user/myproject/Dockerfile",
  "timeout": 60
}
```

**Example Output:**
```json
{
  "file_path": "/home/user/myproject/Dockerfile",
  "scan_date": "2024-01-15T11:20:15.000Z",
  "total_findings": 5,
  "summary": {
    "high": 1,
    "medium": 2,
    "low": 2
  },
  "findings": [
    {
      "severity": "HIGH",
      "rule": "missing-user",
      "line_number": 0,
      "message": "No USER instruction found - container will run as root"
    },
    {
      "severity": "HIGH",
      "rule": "hardcoded-secret",
      "line_number": 8,
      "message": "Possible hardcoded secret in ENV variable",
      "line_content": "ENV API_KEY=sk-1234567890abcdef"
    },
    {
      "severity": "MEDIUM",
      "rule": "latest-tag",
      "line_number": 1,
      "message": "Using ':latest' tag is not recommended for reproducible builds",
      "line_content": "FROM ubuntu:latest"
    },
    {
      "severity": "LOW",
      "rule": "apt-install-recommends",
      "line_number": 10,
      "message": "apt-get install should use --no-install-recommends to reduce image size",
      "line_content": "RUN apt-get install -y curl wget"
    },
    {
      "severity": "LOW",
      "rule": "missing-healthcheck",
      "line_number": 0,
      "message": "No HEALTHCHECK instruction found - container health cannot be monitored"
    }
  ]
}
```

## Configuration

### Environment Variables

This server does not require external API keys. However, it requires command-line tools to be installed and configured in your system PATH:

```bash
# Install tools (varies by operating system)
# The tools must be accessible as commands: trivy, kube-bench, docker, kubectl
```

### Tool Dependencies

The server expects these tools to be available in your system:

| Tool | Purpose | Installation |
|------|---------|--------------|
| Trivy | Vulnerability scanning | https://github.com/aquasecurity/trivy |
| kube-bench | Kubernetes CIS benchmarks | https://github.com/aquasecurity/kube-bench |
| Docker | Container inspection | https://docs.docker.com/get-docker/ |
| kubectl | Kubernetes access | https://kubernetes.io/docs/tasks/tools/ |

## Prerequisites

### System Requirements

- Bun runtime (version 1.x or later) or Node.js 18+
- Linux, macOS, or Windows (with WSL)

### Required Tools

**Trivy** (for image and filesystem scanning)
- Download from: https://github.com/aquasecurity/trivy/releases
- macOS: `brew install trivy`
- Linux: `curl https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s`
- Verify: `trivy version`

**kube-bench** (for Kubernetes CIS benchmark checks)
- Download from: https://github.com/aquasecurity/kube-bench/releases
- macOS: `brew install kube-bench`
- Linux: Install from releases or build from source
- Requires: kubectl access to your cluster
- Verify: `kube-bench version`

**Docker** (for container image inspection)
- Download from: https://docs.docker.com/get-docker/
- Verify: `docker --version`
- Ensure Docker daemon is running and you have access permissions

**kubectl** (for Kubernetes pod security auditing)
- Download from: https://kubernetes.io/docs/tasks/tools/
- macOS: `brew install kubectl`
- Requires: Valid kubeconfig file (typically ~/.kube/config)
- Verify: `kubectl version`

## Installation

### Steps

1. Clone or download this repository:
```bash
git clone <repo-url>
cd container-security
```

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

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

4. Verify all required tools are installed and accessible:
```bash
which trivy kube-bench docker kubectl
```

5. Configure Kubernetes access (if using k8s tools):
```bash
# Ensure kubeconfig is set up
kubectl config current-context
```

6. Run the server:
```bash
bun run start
```

The server will start listening on stdio transport.

## Usage

### Running the Server

Start the server with Bun:

```bash
bun run src/index.ts
```

The server implements the Model Context Protocol (MCP) and communicates via stdio transport. It can be integrated with Claude or other MCP clients.

### Claude Desktop Configuration

Add the server to your Claude Desktop configuration at `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "container-security": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/container-security/src/index.ts"
      ]
    }
  }
}
```

### Claude Code MCP Settings

Configure the server in Claude Code's MCP settings (typically in `.mcp.json` or via settings UI):

```json
{
  "servers": {
    "container-security": {
      "transport": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/container-security/src/index.ts"]
    }
  }
}
```

### Example Usage in Claude

Once configured, you can use the tools directly in conversations with Claude:

**Request:**
"Scan the nginx:1.21 container image for high-severity vulnerabilities"

**Claude will call:**
```json
{
  "tool": "trivy_scan_image",
  "input": {
    "image": "nginx:1.21",
    "severity": "HIGH",
    "timeout": 120
  }
}
```

**Request:**
"Check my Kubernetes cluster for CIS benchmark failures on the master nodes"

**Claude will call:**
```json
{
  "tool": "kube_bench",
  "input": {
    "target": "master",
    "timeout": 120
  }
}
```

**Request:**
"Audit all pods in the production namespace for security context violations"

**Claude will call:**
```json
{
  "tool": "k8s_pod_security",
  "input": {
    "namespace": "production",
    "timeout": 120
  }
}
```

**Request:**
"Lint this Dockerfile for security issues: /home/user/myproject/Dockerfile"

**Claude will call:**
```json
{
  "tool": "dockerfile_lint",
  "input": {
    "file_path": "/home/user/myproject/Dockerfile",
    "timeout": 60
  }
}
```

**Request:**
"Scan the /home/user/myproject directory for vulnerabilities in dependencies"

**Claude will call:**
```json
{
  "tool": "trivy_scan_fs",
  "input": {
    "path": "/home/user/myproject",
    "severity": "MEDIUM",
    "timeout": 180
  }
}
```

## Security

This server implements comprehensive input validation and security measures to prevent injection attacks and command execution:

### Input Validation

**Container Image Name Validation**
- Validates image name format (registry/repo:tag@digest)
- Supports Docker Hub, private registries, and digest references
- Maximum length: 500 characters
- Pattern: `^[a-zA-Z0-9][a-zA-Z0-9._\/-]*(?::[a-zA-Z0-9._-]+)?(?:@sha256:[a-fA-F0-9]{64})?$`
- Rejects invalid characters and malformed references

**File Path Validation**
- Validates absolute file paths only
- Blocks access to sensitive system paths: /etc/shadow, /proc, /sys, /dev
- Maximum file size: 10MB (for Dockerfiles and similar)
- Verifies files exist and are regular files (not directories or symlinks)
- Uses normalized path resolution to prevent traversal attacks

**Kubernetes Namespace Validation**
- Requires valid Kubernetes naming conventions
- Maximum length: 63 characters
- Pattern: `^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`
- Rejects invalid characters and namespace names

**Timeout Validation**
- Timeout range: 10-600 seconds (default: 120)
- Prevents extremely long-running commands
- Validates numeric type and bounds

### What Gets Blocked

The server rejects:
- Invalid container image name formats
- Docker privileged operations: `--privileged`, `--cap-add`, volume mounts to /, `--pid=host`, `--network=host`
- Docker exec and run subcommands (only inspect allowed)
- Access to sensitive filesystem paths
- Kubernetes namespace names with invalid formats
- Oversized input files
- Timeouts outside the allowed range

### Error Handling

- Invalid inputs return descriptive error messages
- CLI tool errors are caught and reported with context
- Missing required tools trigger helpful error messages
- Timeouts are handled with explicit messages
- File access errors provide clear feedback

## License

ISC License - see LICENSE file for details