npm package: @modular-intelligence/defectdojo
Description: MCP server for DefectDojo vulnerability management platform API
Latest version: 1.0.2

# DefectDojo MCP Server

A Model Context Protocol (MCP) server that provides comprehensive integration with DefectDojo, an open-source vulnerability management platform. This server enables AI assistants to interact with DefectDojo's API for security testing workflow automation, vulnerability tracking, and security metrics analysis.

## Features

- **Findings Management**: List and retrieve detailed security findings
- **Product & Engagement Tracking**: Manage products, engagements, and tests
- **Scan Import**: Import results from popular security scanners
- **Security Metrics**: Analyze vulnerability trends and statistics
- **Secure API Access**: HTTPS enforcement with localhost exception for development

## Prerequisites

1. **DefectDojo Instance**: A running DefectDojo server (self-hosted or cloud)
2. **API Token**: Valid DefectDojo API token with appropriate permissions
3. **Bun Runtime**: Bun v1.0 or higher installed

## Installation

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

## Configuration

Set the following environment variables:

```bash
# Required: DefectDojo API URL (must be HTTPS or localhost)
export DEFECTDOJO_API_URL="https://your-defectdojo-instance.com"

# Required: DefectDojo API token
export DEFECTDOJO_API_KEY="your-api-token-here"
```

### Security Notes

- **HTTPS Required**: The API URL must use HTTPS in production environments
- **Localhost Exception**: HTTP is permitted only for localhost/127.0.0.1 (development)
- **Token Security**: Never commit API tokens to version control
- **Authorization**: Scan import operations require explicit authorization confirmation

## Usage

### Start the Server

```bash
bun run start
```

### Build the Server

```bash
bun run build
```

## Available Tools

### 1. defectdojo_findings_list

List security findings with advanced filtering options.

**Parameters:**
- `severity` (optional): Filter by severity (Critical, High, Medium, Low, Info)
- `active` (optional): Filter active findings (boolean)
- `verified` (optional): Filter verified findings (boolean)
- `product_id` (optional): Filter by product ID (number)
- `limit` (optional): Max results per page (1-200, default: 25)
- `offset` (optional): Pagination offset (default: 0)

**Example:**
```json
{
  "severity": "Critical",
  "active": true,
  "product_id": 42,
  "limit": 50
}
```

**Returns:**
```json
{
  "count": 150,
  "results": [
    {
      "id": 1234,
      "title": "SQL Injection in login form",
      "severity": "Critical",
      "cwe": 89,
      "file_path": "/app/login.php",
      "line": 42,
      "active": true,
      "verified": true,
      "duplicate": false,
      "date": "2024-01-15",
      "component_name": "auth-module"
    }
  ]
}
```

### 2. defectdojo_finding_detail

Get comprehensive details about a specific finding.

**Parameters:**
- `finding_id` (required): Finding ID (positive integer)

**Example:**
```json
{
  "finding_id": 1234
}
```

**Returns:**
```json
{
  "id": 1234,
  "title": "SQL Injection in login form",
  "description": "Detailed description...",
  "severity": "Critical",
  "cwe": 89,
  "cvssv3": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H",
  "cvssv3_score": 10.0,
  "mitigation": "Use parameterized queries...",
  "impact": "Complete system compromise possible...",
  "references": "https://owasp.org/...",
  "steps_to_reproduce": "1. Navigate to /login...",
  "file_path": "/app/login.php",
  "line": 42,
  "component_name": "auth-module",
  "endpoints": [1, 2, 3],
  "tags": ["injection", "authentication"]
}
```

### 3. defectdojo_product_list

List all products in DefectDojo.

**Parameters:**
- `name` (optional): Filter by product name (string)
- `limit` (optional): Max results per page (1-200, default: 25)
- `offset` (optional): Pagination offset (default: 0)

**Example:**
```json
{
  "name": "Web Application",
  "limit": 25
}
```

**Returns:**
```json
{
  "count": 10,
  "results": [
    {
      "id": 42,
      "name": "Web Application",
      "description": "Main customer-facing application",
      "prod_type": 1,
      "findings_count": 150,
      "active_findings_count": 45
    }
  ]
}
```

### 4. defectdojo_engagement_list

List security test engagements.

**Parameters:**
- `product_id` (optional): Filter by product ID (number)
- `status` (optional): Filter by status (Not Started, In Progress, Completed)
- `limit` (optional): Max results per page (1-200, default: 25)
- `offset` (optional): Pagination offset (default: 0)

**Example:**
```json
{
  "product_id": 42,
  "status": "In Progress",
  "limit": 25
}
```

**Returns:**
```json
{
  "count": 5,
  "results": [
    {
      "id": 100,
      "name": "Q1 2024 Penetration Test",
      "target_start": "2024-01-01",
      "target_end": "2024-01-31",
      "status": "In Progress",
      "product": 42,
      "lead": 5,
      "test_count": 8
    }
  ]
}
```

### 5. defectdojo_test_list

List security tests.

**Parameters:**
- `engagement_id` (optional): Filter by engagement ID (number)
- `test_type` (optional): Filter by test type (string)
- `limit` (optional): Max results per page (1-200, default: 25)
- `offset` (optional): Pagination offset (default: 0)

**Example:**
```json
{
  "engagement_id": 100,
  "test_type": "ZAP Scan",
  "limit": 25
}
```

**Returns:**
```json
{
  "count": 8,
  "results": [
    {
      "id": 200,
      "title": "ZAP Full Scan - Production",
      "test_type": "ZAP Scan",
      "environment": "Production",
      "target_start": "2024-01-15",
      "target_end": "2024-01-15",
      "finding_count": 23
    }
  ]
}
```

### 6. defectdojo_import_scan

Import security scan results into DefectDojo.

**Parameters:**
- `product_id` (required): Product ID to import into (number)
- `scan_type` (required): Scanner type (enum)
- `scan_file_path` (required): Path to scan results file (string)
- `engagement_name` (optional): Engagement name (auto-created if needed) (string)
- `authorized` (required): Confirm authorization (boolean)

**Supported Scan Types:**
- ZAP Scan
- Nmap Scan
- Burp Scan
- Trivy Scan
- Semgrep JSON Report
- Checkov Report
- Generic Findings Import

**Security Requirements:**
- Maximum file size: 50MB
- Requires explicit authorization (`authorized: true`)
- User must have import permissions in DefectDojo

**Example:**
```json
{
  "product_id": 42,
  "scan_type": "ZAP Scan",
  "scan_file_path": "/path/to/zap-report.json",
  "engagement_name": "Q1 2024 Scan",
  "authorized": true
}
```

**Returns:**
```json
{
  "test_id": 200,
  "finding_count": 23,
  "scan_type": "ZAP Scan",
  "created_findings": 15,
  "closed_findings": 3
}
```

### 7. defectdojo_metrics

Get security metrics and analytics.

**Parameters:**
- `product_id` (optional): Filter by product ID (number)
- `date_range` (optional): Date range for trend analysis
  - `start` (required): Start date in YYYY-MM-DD format
  - `end` (required): End date in YYYY-MM-DD format

**Example:**
```json
{
  "product_id": 42,
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  }
}
```

**Returns:**
```json
{
  "total_findings": 150,
  "by_severity": {
    "Critical": 5,
    "High": 20,
    "Medium": 50,
    "Low": 60,
    "Info": 15
  },
  "active_vs_closed": {
    "active": 45,
    "closed": 105
  },
  "mean_time_to_remediate_days": 14.5,
  "trend": [
    {
      "date": "2024-01-01",
      "new": 10,
      "closed": 2
    },
    {
      "date": "2024-01-02",
      "new": 5,
      "closed": 8
    }
  ],
  "top_cwes": [
    { "cwe": 89, "count": 15 },
    { "cwe": 79, "count": 12 },
    { "cwe": 352, "count": 8 }
  ]
}
```

## Architecture

```
defectdojo/
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── README.md            # This file
└── src/
    ├── index.ts         # Main server implementation
    ├── schemas.ts       # Zod validation schemas
    ├── security.ts      # Security utilities
    └── tools/           # Tool implementations
        ├── defectdojo-findings-list.ts
        ├── defectdojo-finding-detail.ts
        ├── defectdojo-product-list.ts
        ├── defectdojo-engagement-list.ts
        ├── defectdojo-test-list.ts
        ├── defectdojo-import-scan.ts
        └── defectdojo-metrics.ts
```

## Security Features

### API Security
- **HTTPS Enforcement**: Production URLs must use HTTPS
- **Localhost Exception**: HTTP allowed for 127.0.0.1/localhost development
- **Token-based Auth**: Uses DefectDojo API tokens via Authorization header

### Input Validation
- All inputs validated using Zod schemas
- ID validation ensures positive integers
- File size limits (50MB) for scan imports
- Pagination limits (1-200 results per page)

### Authorization
- Scan import requires explicit `authorized: true` confirmation
- Prevents accidental data modifications
- Clear error messages for authorization failures

## Error Handling

The server provides detailed error messages for common scenarios:

- Missing environment variables
- Invalid API URLs (non-HTTPS in production)
- Invalid API tokens
- Missing authorization for protected operations
- File size limit violations
- Invalid IDs or parameters
- DefectDojo API errors (with status codes)

## Development

### File Structure
- `src/index.ts`: MCP server setup and tool routing
- `src/security.ts`: Authentication and validation utilities
- `src/schemas.ts`: Reusable Zod schemas
- `src/tools/`: Individual tool implementations

### Adding New Tools
1. Create a new file in `src/tools/`
2. Define Zod schema with `.describe()` on all fields
3. Implement tool function
4. Export schema and function
5. Register in `src/index.ts`

### Testing
Test with a local DefectDojo instance:

```bash
# Start DefectDojo (Docker)
docker-compose up -d

# Set environment variables
export DEFECTDOJO_API_URL="http://localhost:8080"
export DEFECTDOJO_API_KEY="your-token"

# Run server
bun run start
```

## Common Use Cases

### 1. Vulnerability Triage
```
1. List critical findings: defectdojo_findings_list (severity: Critical, active: true)
2. Get finding details: defectdojo_finding_detail (finding_id: X)
3. Review mitigation steps and assign remediation
```

### 2. Security Scan Automation
```
1. Run external scanner (ZAP, Trivy, etc.)
2. Import results: defectdojo_import_scan
3. Review new findings: defectdojo_findings_list
4. Generate metrics: defectdojo_metrics
```

### 3. Security Metrics Reporting
```
1. Get product metrics: defectdojo_metrics (product_id: X)
2. Analyze severity distribution
3. Track remediation trends
4. Identify top CWEs for focused remediation
```

### 4. Engagement Management
```
1. List products: defectdojo_product_list
2. Create/view engagements: defectdojo_engagement_list
3. Track tests: defectdojo_test_list
4. Monitor progress and findings
```

## Troubleshooting

### Connection Issues
- Verify `DEFECTDOJO_API_URL` is correct and accessible
- Check HTTPS requirement (or localhost exception)
- Confirm network connectivity to DefectDojo instance

### Authentication Issues
- Verify `DEFECTDOJO_API_KEY` is valid
- Check token permissions in DefectDojo
- Ensure token hasn't expired

### Import Issues
- Confirm file path is correct and readable
- Check file size (max 50MB)
- Verify scan type matches file format
- Ensure `authorized: true` is set
- Check user has import permissions

### Pagination
- Use `limit` and `offset` for large result sets
- Maximum limit is 200 results per page
- Check `count` field for total results

## Contributing

Contributions welcome! Please ensure:
- All Zod schemas have `.describe()` on fields
- Security validations are in place
- Error messages are clear and actionable
- README is updated for new features

## License

MIT License - see LICENSE file for details

## Support

- DefectDojo Documentation: https://documentation.defectdojo.com/
- DefectDojo API Reference: https://demo.defectdojo.org/api/v2/doc/
- MCP SDK: https://github.com/anthropics/modelcontextprotocol

## Version History

- **1.0.0** (2024): Initial release
  - 7 core tools for DefectDojo integration
  - Comprehensive security validations
  - Full API coverage for findings, products, engagements, tests
  - Scan import support for 7+ scanner types
  - Advanced metrics and analytics