@modular-intelligence/checkov 1.0.0

package/README.md

@@ -0,0 +1,442 @@
+# 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 /Users/ehenry/Documents/code/mcp-servers/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", "/Users/ehenry/Documents/code/mcp-servers/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