npm package: @modular-intelligence/sbom-generator
Description: MCP server wrapping Syft and Grype for SBOM generation and vulnerability matching
Latest version: 1.0.2

# SBOM Generator MCP Server

MCP server for Software Bill of Materials (SBOM) generation and vulnerability scanning using **Syft** and **Grype**.

## Overview

This server provides comprehensive SBOM generation and vulnerability analysis capabilities:

- **Syft**: Generate SBOMs from container images, directories, and files
- **Grype**: Scan SBOMs and container images for known vulnerabilities
- **Diff**: Compare SBOMs to track dependency changes

## Prerequisites

### Required CLI Tools

1. **Syft** - SBOM generator
   ```bash
   # macOS
   brew install syft

   # Linux
   curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin

   # Verify installation
   syft version
   ```

2. **Grype** - Vulnerability scanner
   ```bash
   # macOS
   brew install grype

   # Linux
   curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin

   # Verify installation
   grype version
   ```

### Update Vulnerability Database

```bash
grype db update
```

## Installation

```bash
cd sbom-generator
bun install
bun run build
```

## Usage

### Start Server

```bash
bun run start
```

## Tools

### 1. syft_generate_sbom

Generate a Software Bill of Materials (SBOM) from a directory or container image.

**Parameters:**
- `source` (string, required): Path to directory/file or container image reference
- `format` (string, default: "json"): SBOM output format
  - Options: `json`, `cyclonedx-json`, `cyclonedx-xml`, `spdx-json`, `spdx-tag-value`, `syft-json`, `github-json`
- `timeout` (number, default: 120): Maximum command duration in seconds (30-600)

**Examples:**

```typescript
// Generate SBOM from container image
{
  "source": "nginx:latest",
  "format": "cyclonedx-json"
}

// Generate SBOM from local directory
{
  "source": "/path/to/project",
  "format": "spdx-json"
}

// Generate SBOM from a specific file
{
  "source": "/path/to/binary",
  "format": "json"
}
```

**Response:**
```json
{
  "format": "cyclonedx-json",
  "source": "nginx:latest",
  "sbom": {
    "bomFormat": "CycloneDX",
    "components": [...],
    ...
  }
}
```

### 2. syft_list_packages

List all packages and dependencies found in a directory or container image.

**Parameters:**
- `source` (string, required): Path to directory/file or container image
- `type` (string, optional): Filter by package type
  - Examples: `npm`, `pip`, `gem`, `go-module`, `apk`, `deb`, `rpm`, `java-archive`
- `timeout` (number, default: 120): Maximum command duration in seconds (30-600)

**Examples:**

```typescript
// List all packages in an image
{
  "source": "node:18-alpine"
}

// List only npm packages
{
  "source": "/path/to/project",
  "type": "npm"
}

// List Python packages
{
  "source": "python:3.11",
  "type": "python"
}
```

**Response:**
```json
{
  "packages": [
    {
      "name": "express",
      "version": "4.18.2",
      "type": "npm",
      "locations": ["/app/node_modules/express"]
    }
  ],
  "total": 156,
  "source": "node:18-alpine",
  "filter": "npm"
}
```

### 3. syft_catalogers_list

List available Syft catalogers (package detection plugins).

**Parameters:** None

**Example:**

```typescript
{}
```

**Response:**
```json
{
  "catalogers": [
    {
      "name": "alpm-db-cataloger",
      "description": "catalog packages from ALPM DB"
    },
    {
      "name": "apk-db-cataloger",
      "description": "catalog packages from APK DB"
    }
  ],
  "total": 42
}
```

### 4. grype_scan_sbom

Scan an SBOM file for known vulnerabilities using the Grype vulnerability database.

**Parameters:**
- `sbom_path` (string, required): Absolute path to SBOM file
- `severity` (string, optional): Minimum severity level to report
  - Options: `negligible`, `low`, `medium`, `high`, `critical`
- `timeout` (number, default: 120): Maximum command duration in seconds (30-600)

**Examples:**

```typescript
// Scan SBOM for all vulnerabilities
{
  "sbom_path": "/tmp/app-sbom.json"
}

// Only show critical and high severity
{
  "sbom_path": "/tmp/app-sbom.json",
  "severity": "high"
}
```

**Response:**
```json
{
  "vulnerabilities": [
    {
      "id": "CVE-2023-12345",
      "severity": "High",
      "package": "openssl",
      "version": "1.1.1k",
      "fixed_version": "1.1.1l",
      "description": "OpenSSL vulnerability allowing remote code execution"
    }
  ],
  "summary": {
    "total": 12,
    "critical": 2,
    "high": 4,
    "medium": 5,
    "low": 1,
    "negligible": 0
  },
  "sbom_path": "/tmp/app-sbom.json"
}
```

### 5. grype_scan_image

Scan a container image directly for vulnerabilities without generating an intermediate SBOM.

**Parameters:**
- `image` (string, required): Container image reference (e.g., `nginx:latest`, `registry/repo:tag`)
- `severity` (string, optional): Minimum severity level to report
- `only_fixed` (boolean, default: false): Only show vulnerabilities with available fixes
- `timeout` (number, default: 120): Maximum command duration in seconds (30-600)

**Examples:**

```typescript
// Scan image for all vulnerabilities
{
  "image": "nginx:1.21"
}

// Only show vulnerabilities with fixes available
{
  "image": "postgres:14-alpine",
  "only_fixed": true,
  "severity": "medium"
}

// Scan from private registry
{
  "image": "registry.example.com/myapp:v1.2.3",
  "severity": "high"
}
```

**Response:**
```json
{
  "vulnerabilities": [
    {
      "id": "CVE-2023-45678",
      "severity": "Critical",
      "package": "libssl3",
      "version": "3.0.2-0ubuntu1.10",
      "fixed_version": "3.0.2-0ubuntu1.12",
      "description": "Critical SSL vulnerability",
      "urls": ["https://nvd.nist.gov/vuln/detail/CVE-2023-45678"]
    }
  ],
  "summary": {
    "total": 8,
    "critical": 1,
    "high": 3,
    "medium": 3,
    "low": 1,
    "negligible": 0,
    "with_fix": 6
  },
  "image": "nginx:1.21",
  "only_fixed": false
}
```

### 6. grype_db_status

Check the status and freshness of the Grype vulnerability database.

**Parameters:** None

**Example:**

```typescript
{}
```

**Response:**
```json
{
  "built": "2024-02-09T10:30:45Z",
  "schema_version": "5",
  "location": "/Users/user/.cache/grype/db/5",
  "status": "valid",
  "age": "2 hours"
}
```

**Interpretation:**
- Check database age regularly - update if older than 24-48 hours
- Run `grype db update` to refresh the vulnerability data

### 7. sbom_diff

Compare two SBOMs to identify added, removed, and changed packages.

**Parameters:**
- `sbom_a` (string, required): Path to first SBOM file (baseline)
- `sbom_b` (string, required): Path to second SBOM file (comparison)
- `timeout` (number, default: 120): Maximum command duration in seconds (30-600)

**Examples:**

```typescript
// Compare production vs development dependencies
{
  "sbom_a": "/tmp/prod-sbom.json",
  "sbom_b": "/tmp/dev-sbom.json"
}

// Compare before and after upgrade
{
  "sbom_a": "/tmp/app-v1.0-sbom.json",
  "sbom_b": "/tmp/app-v1.1-sbom.json"
}
```

**Response:**
```json
{
  "added": [
    {
      "name": "new-dependency",
      "version": "2.1.0",
      "type": "npm"
    }
  ],
  "removed": [
    {
      "name": "deprecated-package",
      "version": "1.0.0",
      "type": "npm"
    }
  ],
  "changed": [
    {
      "name": "express",
      "type": "npm",
      "old_version": "4.18.0",
      "new_version": "4.18.2"
    }
  ],
  "unchanged_count": 143,
  "summary": {
    "total_changes": 8,
    "added_count": 3,
    "removed_count": 2,
    "changed_count": 3,
    "unchanged_count": 143
  },
  "sbom_a": "/tmp/prod-sbom.json",
  "sbom_b": "/tmp/dev-sbom.json"
}
```

## Security Features

### Path Validation
- All file paths must be absolute
- Path traversal (`..`) is blocked
- Null bytes are rejected
- System directories (`/etc`, `/proc`, `/sys`, `/dev`) are protected

### Image Name Validation
- Must start with alphanumeric character
- Allows: alphanumeric, dots, hyphens, underscores, slashes, colons, `@` symbols
- Maximum length: 256 characters
- Prevents command injection

### Resource Limits
- Maximum SBOM size: 10MB
- Command timeout: 30-600 seconds (configurable)
- Maximum buffer: 10MB per command

### Format Validation
- Only whitelisted SBOM formats allowed
- Prevents arbitrary format string injection

## Workflows

### Basic Vulnerability Assessment

```typescript
// 1. Check Grype database status
grype_db_status()

// 2. Generate SBOM from container image
syft_generate_sbom({
  "source": "myapp:latest",
  "format": "json"
})

// 3. Scan image for vulnerabilities
grype_scan_image({
  "image": "myapp:latest",
  "severity": "medium"
})
```

### Dependency Tracking

```typescript
// 1. Generate baseline SBOM
syft_generate_sbom({
  "source": "/path/to/app-v1.0",
  "format": "json"
})
// Save to /tmp/baseline-sbom.json

// 2. Generate current SBOM
syft_generate_sbom({
  "source": "/path/to/app-v1.1",
  "format": "json"
})
// Save to /tmp/current-sbom.json

// 3. Compare SBOMs
sbom_diff({
  "sbom_a": "/tmp/baseline-sbom.json",
  "sbom_b": "/tmp/current-sbom.json"
})
```

### Supply Chain Analysis

```typescript
// 1. List all packages
syft_list_packages({
  "source": "myapp:latest"
})

// 2. Filter by ecosystem
syft_list_packages({
  "source": "myapp:latest",
  "type": "npm"
})

// 3. Scan for vulnerabilities with fixes
grype_scan_image({
  "image": "myapp:latest",
  "only_fixed": true,
  "severity": "high"
})
```

### Continuous Monitoring

```typescript
// Daily workflow:

// 1. Update vulnerability database
grype_db_status()  // Check age
// Run: grype db update (if needed)

// 2. Scan production images
grype_scan_image({
  "image": "production/api:latest",
  "severity": "critical"
})

// 3. Scan infrastructure images
grype_scan_image({
  "image": "nginx:stable",
  "only_fixed": true
})
```

## Output Formats

### Syft SBOM Formats

- **json**: Syft's native JSON format
- **cyclonedx-json**: CycloneDX JSON format (OWASP standard)
- **cyclonedx-xml**: CycloneDX XML format
- **spdx-json**: SPDX JSON format (Linux Foundation standard)
- **spdx-tag-value**: SPDX tag-value format
- **syft-json**: Syft detailed JSON (includes file metadata)
- **github-json**: GitHub dependency graph format

### Grype Output

All Grype scans return structured JSON with:
- Vulnerability ID (CVE, GHSA, etc.)
- Severity level
- Affected package and version
- Fixed version (if available)
- Description and URLs

## Best Practices

### SBOM Generation

1. **Use specific tags**: Prefer `nginx:1.21.6` over `nginx:latest`
2. **Generate regularly**: Create SBOMs for each release
3. **Version control**: Store SBOMs alongside code
4. **Standard formats**: Use CycloneDX or SPDX for interoperability

### Vulnerability Scanning

1. **Update database**: Run `grype db update` daily
2. **Set thresholds**: Use `severity` filter to focus on critical issues
3. **Track fixes**: Use `only_fixed: true` to prioritize actionable items
4. **Automate**: Integrate scans into CI/CD pipelines

### Dependency Management

1. **Baseline tracking**: Maintain SBOMs for production releases
2. **Monitor changes**: Use `sbom_diff` to review dependency updates
3. **Type filtering**: Use package type filters to audit specific ecosystems
4. **Regular audits**: Review dependencies quarterly

## Troubleshooting

### Syft Issues

```bash
# Verify Syft installation
syft version

# Test SBOM generation
syft nginx:latest -o json

# Check supported formats
syft --help
```

### Grype Issues

```bash
# Verify Grype installation
grype version

# Update vulnerability database
grype db update

# Check database status
grype db status

# Test vulnerability scan
grype nginx:latest
```

### Common Errors

**"Path must be absolute"**
- Ensure file paths start with `/`
- Use absolute paths, not relative

**"Invalid image name"**
- Check image name format: `[registry/]repository[:tag]`
- Avoid special characters

**"SBOM content exceeds maximum size"**
- Generated SBOM is too large (>10MB)
- Consider filtering or splitting the analysis

**"Timeout"**
- Large images may need longer timeout
- Increase `timeout` parameter (max 600 seconds)

## Integration Examples

### Claude Desktop

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

### CI/CD Pipeline

```yaml
# GitHub Actions example
- name: Generate SBOM
  run: |
    echo '{"source":".", "format":"cyclonedx-json"}' | \
    bun run /path/to/sbom-generator/src/index.ts

- name: Scan for vulnerabilities
  run: |
    echo '{"image":"myapp:${{ github.sha }}", "severity":"high"}' | \
    bun run /path/to/sbom-generator/src/index.ts
```

## Standards Compliance

- **SBOM**: Supports SPDX (ISO/IEC 5962:2021) and CycloneDX (OWASP) standards
- **Vulnerability Data**: Uses NIST NVD, GitHub Security Advisories, and vendor-specific databases
- **Security**: Implements input validation and resource limits per OWASP guidelines

## License

This MCP server is a wrapper around:
- **Syft** - Apache 2.0 License (Anchore, Inc.)
- **Grype** - Apache 2.0 License (Anchore, Inc.)

## Related Tools

- [Trivy](https://github.com/aquasecurity/trivy) - Alternative SBOM/vulnerability scanner
- [OSV-Scanner](https://github.com/google/osv-scanner) - Google's vulnerability scanner
- [Dependency-Track](https://dependencytrack.org/) - SBOM analysis platform
- [Snyk](https://snyk.io/) - Commercial security platform

## References

- [Syft Documentation](https://github.com/anchore/syft)
- [Grype Documentation](https://github.com/anchore/grype)
- [CycloneDX Specification](https://cyclonedx.org/)
- [SPDX Specification](https://spdx.dev/)
- [NIST SBOM Resources](https://www.ntia.gov/SBOM)