npm package: @modular-intelligence/checkov
Description: MCP server wrapping checkov for Infrastructure-as-Code security scanning
Latest version: 1.0.2

# Checkov MCP Server

MCP server wrapping [Checkov](https://www.checkov.io/) for Infrastructure-as-Code (IaC) security scanning and Software Composition Analysis (SCA).

## Overview

This MCP server provides a secure interface to Checkov, enabling automated security scanning of infrastructure code including Terraform, CloudFormation, Kubernetes, Dockerfiles, and more. It includes comprehensive security controls to prevent command injection and path traversal attacks.

## Tools

| Tool | Description | Primary Use Case |
|------|-------------|------------------|
| `checkov_scan` | Scan IaC files for security misconfigurations | Daily security scans of infrastructure code |
| `checkov_scan_plan` | Scan Terraform plan files before apply | CI/CD pipeline validation |
| `checkov_list_checks` | List available security checks by framework | Discovery and compliance mapping |
| `checkov_check_detail` | Get detailed information about a specific check | Understanding and remediation guidance |
| `checkov_scan_sca` | Scan package dependencies for vulnerabilities | Software supply chain security |
| `checkov_baseline` | Run incremental scans against a baseline | Progressive security improvement |

## Tool Details

### checkov_scan

Scan IaC files or directories for security misconfigurations.

**Input:**
```json
{
  "path": "/path/to/terraform",
  "framework": "terraform",
  "severity": "HIGH",
  "skip_checks": ["CKV_AWS_1", "CKV_AWS_2"],
  "compact": false,
  "timeout": 120
}
```

**Output:**
```json
{
  "passed": 45,
  "failed": 12,
  "skipped": 3,
  "parsing_errors": 0,
  "results": [
    {
      "check_id": "CKV_AWS_1",
      "check_name": "Ensure S3 bucket has versioning enabled",
      "result": "FAILED",
      "resource": "aws_s3_bucket.example",
      "file_path": "/path/to/terraform/s3.tf",
      "guideline": "https://docs.bridgecrew.io/docs/s3_16"
    }
  ]
}
```

**Parameters:**
- `path` (string, required): Path to IaC file or directory
- `framework` (enum, default: "all"): One of terraform, cloudformation, kubernetes, dockerfile, helm, arm, bicep, serverless, ansible, all
- `severity` (enum, optional): Filter by minimum severity - LOW, MEDIUM, HIGH, CRITICAL
- `skip_checks` (array, optional): List of check IDs to skip
- `compact` (boolean, default: false): Enable compact output
- `timeout` (number, default: 120): Max scan duration in seconds (30-600)

### checkov_scan_plan

Scan a Terraform plan JSON file for security issues before applying changes.

**Input:**
```json
{
  "plan_file": "/path/to/tfplan.json",
  "timeout": 120
}
```

**Output:**
```json
{
  "passed": 30,
  "failed": 5,
  "skipped": 1,
  "parsing_errors": 0,
  "results": [
    {
      "check_id": "CKV_AWS_23",
      "check_name": "Ensure security group ingress is not open to 0.0.0.0/0",
      "result": "FAILED",
      "resource": "aws_security_group.allow_all",
      "file_path": "/path/to/tfplan.json",
      "guideline": "https://docs.bridgecrew.io/docs/networking_1"
    }
  ]
}
```

**Parameters:**
- `plan_file` (string, required): Path to Terraform plan JSON file
- `timeout` (number, default: 120): Max scan duration in seconds (30-600)

### checkov_list_checks

List all available Checkov security checks for a given framework.

**Input:**
```json
{
  "framework": "terraform"
}
```

**Output:**
```json
{
  "checks": [
    {
      "id": "CKV_AWS_1",
      "name": "Ensure S3 bucket has versioning enabled",
      "framework": "terraform"
    },
    {
      "id": "CKV_AWS_2",
      "name": "Ensure S3 bucket has logging enabled",
      "framework": "terraform"
    }
  ],
  "total": 456
}
```

**Parameters:**
- `framework` (enum, default: "all"): Framework to list checks for

### checkov_check_detail

Get detailed information about a specific Checkov check.

**Input:**
```json
{
  "check_id": "CKV_AWS_1"
}
```

**Output:**
```json
{
  "id": "CKV_AWS_1",
  "name": "Ensure S3 bucket has versioning enabled",
  "framework": "terraform",
  "description": "S3 bucket versioning protects against accidental deletion",
  "guideline_url": "https://docs.bridgecrew.io/docs/s3_16"
}
```

**Parameters:**
- `check_id` (string, required): Checkov check ID (format: CKV_XXX_N, CKV2_XXX_N, or BC_XXX_N)

### checkov_scan_sca

Scan package dependencies for known vulnerabilities using Software Composition Analysis.

**Input:**
```json
{
  "path": "/path/to/project",
  "package_type": "npm",
  "timeout": 120
}
```

**Output:**
```json
{
  "total_vulnerabilities": 23,
  "critical": 2,
  "high": 8,
  "medium": 10,
  "low": 3,
  "vulnerabilities": [
    {
      "cve_id": "CVE-2023-12345",
      "severity": "CRITICAL",
      "package_name": "lodash",
      "package_version": "4.17.15",
      "fixed_version": "4.17.21",
      "description": "Prototype pollution vulnerability"
    }
  ]
}
```

**Parameters:**
- `path` (string, required): Path to project directory
- `package_type` (enum, optional): One of npm, pip, go, maven, gradle, nuget, ruby
- `timeout` (number, default: 120): Max scan duration in seconds (30-600)

### checkov_baseline

Run Checkov scan with baseline comparison for incremental scanning.

**Input:**
```json
{
  "path": "/path/to/terraform",
  "framework": "terraform",
  "baseline_path": "/path/to/.checkov.baseline",
  "timeout": 120
}
```

**Output:**
```json
{
  "baseline_exists": true,
  "new_failures": 3,
  "new_failures_details": [
    {
      "check_id": "CKV_AWS_45",
      "check_name": "Ensure EBS volumes are encrypted",
      "resource": "aws_ebs_volume.data",
      "file_path": "/path/to/terraform/ebs.tf",
      "guideline": "https://docs.bridgecrew.io/docs/general_13"
    }
  ],
  "total_failures": 15
}
```

**Parameters:**
- `path` (string, required): Path to IaC directory
- `framework` (enum, default: "all"): Framework to scan
- `baseline_path` (string, optional): Path to baseline file. If not provided, creates a new baseline
- `timeout` (number, default: 120): Max scan duration in seconds (30-600)

## Security

This MCP server implements comprehensive security controls:

### Path Validation
- Blocks path traversal attempts (`../`, `~`)
- Blocks null bytes in paths
- Blocks access to system directories (`/etc`, `/proc`, `/sys`, `/dev`)
- Validates all paths exist before execution
- Converts all paths to absolute paths

### Framework Validation
- Whitelist-only validation for frameworks
- Allowed: terraform, cloudformation, kubernetes, dockerfile, helm, arm, bicep, serverless, ansible, all

### Check ID Validation
- Pattern validation: `^(CKV|CKV2|BC)_[A-Z_]+_\d+$`
- Examples: `CKV_AWS_1`, `CKV2_AZURE_12`, `BC_AWS_GENERAL_45`

### Blocked Flags
The following dangerous Checkov flags are blocked:
- `--external-checks-git` (prevents arbitrary code execution)
- `--external-checks-dir` (prevents arbitrary code execution)
- `--repo-id` (prevents unintended API calls)

### Execution Controls
- Configurable timeouts (30-600 seconds)
- Hard kill after timeout + 5 seconds
- 10MB output buffer limit
- All commands executed with controlled argument arrays (no shell injection)

## Prerequisites

### Required
- **Checkov CLI**: Install via pip, brew, or docker
  ```bash
  # Option 1: pip
  pip install checkov

  # Option 2: brew (macOS)
  brew install checkov

  # Option 3: docker
  docker pull bridgecrew/checkov
  ```

- **Bun**: For running the MCP server
  ```bash
  curl -fsSL https://bun.sh/install | bash
  ```

### Optional
- **BC_API_KEY**: Bridgecrew API key for enhanced features
  ```bash
  export BC_API_KEY="your-api-key"
  ```

## Installation

1. Clone or navigate to the checkov directory:
   ```bash
   cd /path/to/mi-mcp-servers/packages/checkov
   ```

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

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

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

## Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "checkov": {
      "command": "bun",
      "args": ["run", "/path/to/mi-mcp-servers/packages/checkov/src/index.ts"],
      "env": {
        "BC_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Usage Examples

### Example 1: Scan Terraform Directory
```json
{
  "tool": "checkov_scan",
  "input": {
    "path": "/path/to/terraform",
    "framework": "terraform",
    "severity": "HIGH"
  }
}
```

### Example 2: Scan Terraform Plan in CI/CD
```json
{
  "tool": "checkov_scan_plan",
  "input": {
    "plan_file": "/tmp/tfplan.json",
    "timeout": 180
  }
}
```

### Example 3: List All Kubernetes Checks
```json
{
  "tool": "checkov_list_checks",
  "input": {
    "framework": "kubernetes"
  }
}
```

### Example 4: Get Check Details
```json
{
  "tool": "checkov_check_detail",
  "input": {
    "check_id": "CKV_AWS_18"
  }
}
```

### Example 5: SCA Scan for NPM Vulnerabilities
```json
{
  "tool": "checkov_scan_sca",
  "input": {
    "path": "/path/to/nodejs-project",
    "package_type": "npm"
  }
}
```

### Example 6: Baseline Scanning
```json
{
  "tool": "checkov_baseline",
  "input": {
    "path": "/path/to/terraform",
    "framework": "terraform",
    "baseline_path": "/path/to/.checkov.baseline"
  }
}
```

## Development

### Build
```bash
bun run build
```

### Run Locally
```bash
bun run start
```

### Project Structure
```
checkov/
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── README.md             # This file
└── src/
    ├── index.ts          # MCP server entry point
    ├── schemas.ts        # Zod schemas for validation
    ├── security.ts       # Security validation functions
    ├── cli-executor.ts   # Checkov CLI execution wrapper
    └── tools/
        ├── checkov-scan.ts
        ├── checkov-scan-plan.ts
        ├── checkov-list-checks.ts
        ├── checkov-check-detail.ts
        ├── checkov-scan-sca.ts
        └── checkov-baseline.ts
```

## License

MIT

## Support

For issues and questions:
- Checkov documentation: https://www.checkov.io/
- MCP SDK: https://github.com/modelcontextprotocol/sdk