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

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

Configuration

Set the following environment variables:

# 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

bun run start

Build the Server

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:

{
  "severity": "Critical",
  "active": true,
  "product_id": 42,
  "limit": 50
}

Returns:

{
  "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:

{
  "finding_id": 1234
}

Returns:

{
  "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:

{
  "name": "Web Application",
  "limit": 25
}

Returns:

{
  "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:

{
  "product_id": 42,
  "status": "In Progress",
  "limit": 25
}

Returns:

{
  "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:

{
  "engagement_id": 100,
  "test_type": "ZAP Scan",
  "limit": 25
}

Returns:

{
  "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:

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

Returns:

{
  "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:

{
  "product_id": 42,
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  }
}

Returns:

{
  "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:

# 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