npm package: @modular-intelligence/trivy
Description: MCP server wrapping trivy for IaC, SBOM, secrets, and license scanning
Latest version: 1.0.2

# Trivy MCP Server

A Model Context Protocol (MCP) server that wraps [Trivy](https://aquasecurity.github.io/trivy/) for comprehensive security scanning including Infrastructure as Code (IaC), Software Bill of Materials (SBOM), secrets detection, license compliance, and more.

## Overview

This MCP server provides 8 specialized tools for security scanning using Trivy. It complements the existing `container-security` server (which provides `trivy_scan_image` and `trivy_scan_fs`) by covering all other Trivy scanning capabilities.

## Features

- **IaC Security Scanning**: Detect misconfigurations in Terraform, CloudFormation, Kubernetes manifests, Dockerfiles, and more
- **SBOM Generation**: Create Software Bill of Materials in CycloneDX or SPDX format
- **Secret Detection**: Find exposed credentials, API keys, and passwords (with automatic redaction)
- **License Compliance**: Identify problematic or incompatible licenses in dependencies
- **Repository Scanning**: Scan remote Git repositories without cloning
- **Configuration Analysis**: Validate configuration files with custom policies
- **Kubernetes Security**: Scan running K8s clusters for vulnerabilities
- **Root Filesystem Analysis**: Deep scan of filesystem directories

## Prerequisites

- [Bun](https://bun.sh) runtime
- [Trivy](https://aquasecurity.github.io/trivy/) CLI installed and in PATH
- For Kubernetes scanning: `kubectl` configured with cluster access

### Installing Trivy

```bash
# macOS
brew install aquasecurity/trivy/trivy

# Linux
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | sudo apt-key add -
echo "deb https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install trivy

# Docker
docker pull aquasec/trivy
```

## Installation

```bash
cd /path/to/mi-mcp-servers/packages/trivy
bun install
```

## Usage

### Building

```bash
bun run build
```

### Running

```bash
bun run start
```

## Available Tools

### 1. trivy_iac_scan

Scan Infrastructure as Code files for security misconfigurations.

**Parameters:**
- `path` (string, required): Path to file or directory to scan
- `severity` (array, optional): Filter by severity levels (UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL)
- `skip_dirs` (array, optional): Directories to exclude from scanning
- `timeout` (number, optional): Maximum scan duration in seconds (default: 120)

**Supported IaC formats:**
- Terraform
- CloudFormation
- Kubernetes manifests
- Helm charts
- Dockerfiles
- Azure ARM templates
- And more

**Example:**
```json
{
  "path": "/path/to/terraform",
  "severity": ["HIGH", "CRITICAL"],
  "skip_dirs": ["node_modules", ".terraform"],
  "timeout": 180
}
```

### 2. trivy_sbom_generate

Generate a Software Bill of Materials for dependency tracking.

**Parameters:**
- `path` (string, required): Path to project directory
- `format` (enum, optional): SBOM format - `cyclonedx`, `spdx`, or `spdx-json` (default: cyclonedx)
- `timeout` (number, optional): Maximum generation time in seconds (default: 120)

**Example:**
```json
{
  "path": "/path/to/project",
  "format": "cyclonedx",
  "timeout": 120
}
```

### 3. trivy_secret_scan

Scan for exposed secrets, credentials, and API keys.

**Parameters:**
- `path` (string, required): Path to scan
- `timeout` (number, optional): Maximum scan duration in seconds (default: 120)

**Security Features:**
- Automatic secret redaction (shows only first/last 4 characters)
- Detects AWS keys, GitHub tokens, private keys, passwords, and more
- Reports file location and line numbers

**Example:**
```json
{
  "path": "/path/to/repository",
  "timeout": 120
}
```

### 4. trivy_license_scan

Scan dependencies for license compliance issues.

**Parameters:**
- `path` (string, required): Path to project
- `severity` (array, optional): Filter by severity levels
- `timeout` (number, optional): Maximum scan duration in seconds (default: 120)

**Identifies:**
- Restrictive licenses (GPL, AGPL)
- Commercial licenses
- Incompatible license combinations
- Unknown or missing licenses

**Example:**
```json
{
  "path": "/path/to/project",
  "severity": ["HIGH", "CRITICAL"],
  "timeout": 120
}
```

### 5. trivy_repo_scan

Scan remote Git repositories for vulnerabilities without cloning.

**Parameters:**
- `repo_url` (string, required): HTTPS Git repository URL
- `branch` (string, optional): Specific branch to scan
- `severity` (array, optional): Filter by severity levels
- `timeout` (number, optional): Maximum scan duration in seconds (default: 120)

**Security:**
- HTTPS only (no SSH or file:// URLs)
- Blocks private IP addresses
- No credential exposure

**Example:**
```json
{
  "repo_url": "https://github.com/example/repo",
  "branch": "main",
  "severity": ["HIGH", "CRITICAL"],
  "timeout": 180
}
```

### 6. trivy_config_scan

Scan configuration files with optional custom policy enforcement.

**Parameters:**
- `path` (string, required): Path to configuration files
- `policy_paths` (array, optional): Paths to custom Rego policy files
- `timeout` (number, optional): Maximum scan duration in seconds (default: 120)

**Example:**
```json
{
  "path": "/path/to/configs",
  "policy_paths": ["/path/to/custom-policies"],
  "timeout": 120
}
```

### 7. trivy_k8s_scan

Scan Kubernetes clusters for security issues in running workloads.

**Parameters:**
- `namespace` (string, optional): Specific namespace to scan
- `all_namespaces` (boolean, optional): Scan all namespaces (default: false)
- `severity` (array, optional): Filter by severity levels
- `timeout` (number, optional): Maximum scan duration in seconds (default: 300)

**Requirements:**
- `kubectl` configured with cluster access
- Read permissions on cluster resources

**Example:**
```json
{
  "namespace": "production",
  "severity": ["HIGH", "CRITICAL"],
  "timeout": 300
}
```

### 8. trivy_rootfs_scan

Scan root filesystem directories for vulnerabilities and misconfigurations.

**Parameters:**
- `path` (string, required): Path to root filesystem
- `severity` (array, optional): Filter by severity levels
- `timeout` (number, optional): Maximum scan duration in seconds (default: 120)

**Use cases:**
- Container image analysis (mounted filesystems)
- System security audits
- Pre-deployment validation

**Example:**
```json
{
  "path": "/var/lib/docker/overlay2/container-fs",
  "severity": ["CRITICAL"],
  "timeout": 180
}
```

## Security Features

### Path Validation
- Only absolute paths allowed
- Path traversal prevention (blocks `..`)
- Null byte injection protection
- System directory blocking (`/etc/shadow`, `/proc`, `/sys`, etc.)

### URL Validation
- HTTPS only for repository scanning
- Private IP address blocking
- URL format validation

### Command Safety
- Blocked flags: `--server`, `--token`, `--custom-headers` (prevents remote server abuse)
- Timeout enforcement with SIGKILL safety net
- 10MB output buffer limit

### Secret Redaction
All detected secrets are automatically redacted to show only:
- First 4 characters
- Last 4 characters
- Middle replaced with `****`

Example: `ghp_1234567890abcdef` becomes `ghp_****cdef`

## Output Format

All tools return JSON with consistent structure:

```json
{
  "findings": [...],
  "summary": {
    "total_*": 0,
    "by_severity": {
      "CRITICAL": 5,
      "HIGH": 12,
      "MEDIUM": 23,
      "LOW": 8
    }
  }
}
```

## Error Handling

The server provides descriptive error messages for:
- Missing Trivy installation
- Invalid paths or URLs
- Timeout exceeded
- Permission denied
- Invalid input parameters

## Relationship to Other Servers

This server complements the existing security infrastructure:

- **container-security**: Provides `trivy_scan_image` and `trivy_scan_fs` for container image scanning
- **trivy** (this server): Provides all other Trivy capabilities (IaC, SBOM, secrets, licenses, repos, configs, K8s, rootfs)

Together, these servers provide comprehensive Trivy coverage across all scanning modes.

## Development

### Project Structure

```
trivy/
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── index.ts              # MCP server setup and tool registration
│   ├── schemas.ts            # Zod schemas for input validation
│   ├── security.ts           # Security validation functions
│   ├── cli-executor.ts       # Trivy command execution
│   └── tools/
│       ├── trivy-iac-scan.ts
│       ├── trivy-sbom-generate.ts
│       ├── trivy-secret-scan.ts
│       ├── trivy-license-scan.ts
│       ├── trivy-repo-scan.ts
│       ├── trivy-config-scan.ts
│       ├── trivy-k8s-scan.ts
│       └── trivy-rootfs-scan.ts
```

### Adding Custom Policies

For `trivy_config_scan`, you can provide custom Rego policies:

```rego
# custom-policy.rego
package user.custom

deny[msg] {
  input.kind == "Deployment"
  not input.spec.template.spec.securityContext.runAsNonRoot
  msg := "Containers must not run as root"
}
```

Then reference it in the scan:

```json
{
  "path": "/path/to/manifests",
  "policy_paths": ["/path/to/custom-policy.rego"]
}
```

## License

MIT

## Contributing

Contributions welcome! Please ensure:
- All Zod fields include `.describe()` descriptions
- Security validations are comprehensive
- Error messages are descriptive
- Output formats are consistent

## Resources

- [Trivy Documentation](https://aquasecurity.github.io/trivy/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Trivy GitHub](https://github.com/aquasecurity/trivy)