DefectDojo Integration Module for MCP Clients

This repository supplies a specialized implementation of the Model Context Protocol (MCP) service layer designed to interface with DefectDojo, a widely adopted open-source system for managing security weaknesses. This adapter enables artificial intelligence entities and other MCP consumers to interact with the DefectDojo REST API systematically.

Core Functionality

This MCP service endpoint exposes operations to manipulate primary DefectDojo objects:

• Security Findings: Retrieval, query execution, creation, status modification, and annotation logging.
• Asset Definitions (Products): Enumeration of existing product entities.
• Assessment Cycles (Engagements): Listing, detail fetching, initiation, modification, and finalization.

Deployment and Initialization

Two primary methods exist for launching this server component:

Utilizing uvx (Preferred Method)

uvx automates Python application execution by creating ephemeral environments and resolving dependencies on the fly.

uvx vulnerability-inventory-adapter-for-dd

Standard pip Installation

Install the package directly into your existing Python environment via pip.

# Install from local source directory
pip install .

# Or, assuming availability on the official repository
pip install vulnerability-inventory-adapter-for-dd

After pip installation, invoke the service executable:

vulnerability-inventory-adapter-for-dd

Configuration Parameters

The service mandates specific environmental variables for successful linkage to the target DefectDojo deployment:

• DEFECTDOJO_API_TOKEN (Mandatory): The requisite authentication credential (API Key) for DefectDojo access.
• DEFECTDOJO_API_BASE (Mandatory): The root Uniform Resource Locator (URL) pointing to the DefectDojo installation (e.g., https://my-security-dashboard.corp.net).

These settings must be established within the calling MCP client's operational context. Example configuration for an agent invoking via uvx:

{
  "mcpServers": {
    "defectdojo": {
      "command": "uvx",
      "args": ["vulnerability-inventory-adapter-for-dd"],
      "env": {
        "DEFECTDOJO_API_TOKEN": "SECRET_TOKEN_VALUE",
        "DEFECTDOJO_API_BASE": "https://your-defectdojo-instance.com"
      }
    }
  }
}

If using the executables installed via pip, the configuration structure shifts slightly:

{
  "mcpServers": {
    "defectdojo": {
      "command": "vulnerability-inventory-adapter-for-dd",
      "args": [],
      "env": {
        "DEFECTDOJO_API_TOKEN": "SECRET_TOKEN_VALUE",
        "DEFECTDOJO_API_BASE": "https://your-defectdojo-instance.com"
      }
    }
  }
}

Exposed Interface Methods

The following operations are accessible through the MCP layer:

• get_findings: Retrieve vulnerability records, supporting filtering (by asset name, status, risk level) and paging (limit, offset).
• search_findings: Execute full-text searches across findings, with optional filtering and pagination.
• update_finding_status: Modify the lifecycle stage of a specific finding (e.g., transitioning to 'Remediated', 'Accepted').
• add_finding_note: Append a narrative annotation to an existing finding record.
• create_finding: Inject a new vulnerability record linked to a specific testing event.
• list_products: Retrieve a catalog of registered assets, allowing filtering (by label, type) and paging.
• list_engagements: Fetch a roster of assessment activities, supporting filtering (by asset identifier, state, cycle name) and paging.
• get_engagement: Obtain detailed metadata for a specified assessment cycle via its unique identifier.
• create_engagement: Initiate a new security assessment cycle tied to an asset.
• update_engagement: Modify attributes of an ongoing assessment cycle.
• close_engagement: Designate an assessment cycle as formally finished.

(Refer to the original source documentation for detailed operational syntax for each method)

Operational Walkthroughs

(These examples presume the MCP client utility, use_mcp_tool, is available)

Retrieving Vulnerabilities

# Fetching high-risk, currently active issues (max 10 records)
records = await use_mcp_tool("defectdojo", "get_findings", {
    "status": "Active",
    "severity": "High",
    "limit": 10
})

Searching Records

# Locating all entries mentioning 'Cross-Site Scripting'
search_results = await use_mcp_tool("defectdojo", "search_findings", {
    "query": "Cross-Site Scripting"
})

Status Modification

# Classifying finding ID 123 as 'Validated'
update_response = await use_mcp_tool("defectdojo", "update_finding_status", {
    "finding_id": 123,
    "status": "Verified"
})

Annotation Addition

# Attaching context to finding 123
note_result = await use_mcp_tool("defectdojo", "add_finding_note", {
    "finding_id": 123,
    "note": "Verification confirms exploitability in the UAT environment."
})

New Vulnerability Registration

# Submitting a novel issue linked to test run 55
new_issue = await use_mcp_tool("defectdojo", "create_finding", {
    "title": "Improper Input Validation on User Profile",
    "test_id": 55, 
    "severity": "Medium",
    "description": "Failure to cleanse user-supplied data in the profile update endpoint.",
    "cwe": 89
})

Product Index Listing

# Querying assets whose titles contain 'Backend API'
asset_list = await use_mcp_tool("defectdojo", "list_products", {
    "name": "Backend API",
    "limit": 20
})

Assessment Cycle Index

# Retrieving cycles marked as 'Ongoing' for asset ID 42
cycle_roster = await use_mcp_tool("defectdojo", "list_engagements", {
    "product_id": 42,
    "status": "In Progress"
})

Single Assessment Fetch

# Detailed view of engagement 101
details = await use_mcp_tool("defectdojo", "get_engagement", {
    "engagement_id": 101
})

Assessment Initiation

# Scheduling a new security review for asset 42
creation_ack = await use_mcp_tool("defectdojo", "create_engagement", {
    "product_id": 42,
    "name": "Annual Penetration Test Q3",
    "target_start": "2025-07-01",
    "target_end": "2025-07-14",
    "status": "Scheduled"
})

Assessment Update

# Advancing engagement 101 to active status
status_update = await use_mcp_tool("defectdojo", "update_engagement", {
    "engagement_id": 101,
    "status": "Active",
    "description": "Initial scanning phase commenced."
})

Assessment Finalization

# Concluding assessment 101
closure_confirmation = await use_mcp_tool("defectdojo", "close_engagement", {
    "engagement_id": 101
})

Development Prerequisites

Environment Setup

1. Clone the source repository.
2. It is strongly advised to utilize an isolated virtual environment: bash python -m venv .venv source .venv/bin/activate # Use `.venv\Scripts\activate` on Windows systems
3. Install necessary packages, including tools for development: bash pip install -e ".[dev]"

License Information

This software is distributed under the MIT License agreement; consult the LICENSE file for comprehensive terms.

Collaboration Guidelines

Contributions are highly valued! If you identify a fault or require a new capability, please initiate a discussion by opening an issue ticket. For contributions involving code modifications, please create an issue beforehand to align on the proposed scope.