DefectDojo MCP Bridge Server

This repository hosts an implementation of the Model Context Protocol (MCP) server specification, designed to interface directly with the DefectDojo application programming interface (API). It serves as a standardized gateway allowing artificial intelligence agents and other MCP-compliant clients to manage security data within their DefectDojo instance.

Core Capabilities

This MCP service exposes functional endpoints for manipulating primary DefectDojo artifacts:

• Vulnerability Findings: Retrieve records, execute targeted searches, instantiate new findings, modify existing finding states (e.g., Active, Mitigated), and append supplementary commentary.
• Product Assets: Query the catalog of managed security products.
• Security Engagements: List existing engagements, fetch granular details for specific engagements, provision new engagements, alter their attributes, and finalize (close) ongoing efforts.

Deployment and Execution

Two primary methods exist for launching this server component:

Using uvx (Preferred Method)

uvx streamlines execution by creating ephemeral Python environments and handling all dependency resolution automatically.

bash uvx defectdojo-mcp

Using Local Python Installation (pip)

Install the package into your active Python environment via pip.

bash

If installing from local source code directory

pip install .

If the package is available on the Python Package Index

pip install defectdojo-mcp

After installation via pip, invoke the server like this:

bash defectdojo-mcp

Configuration Parameters

The server necessitates specific environmental variables to establish a secure link to the target DefectDojo environment:

• DEFECTDOJO_API_TOKEN (Mandatory): The authentication credential (API Key) for the DefectDojo instance.
• DEFECTDOJO_API_BASE (Mandatory): The root uniform resource locator (URL) pointing to the DefectDojo deployment (e.g., https://app.securecorp.com/api/v2/).

These values must be supplied within your MCP client's configuration structure. For example, when launching via uvx:

{ "mcpServers": { "defectdojo": { "command": "uvx", "args": ["defectdojo-mcp"], "env": { "DEFECTDOJO_API_TOKEN": "YOUR_API_TOKEN_HERE", "DEFECTDOJO_API_BASE": "https://your-defectdojo-instance.com" } } } }

If installed via pip, the configuration snippet is adjusted as follows:

{ "mcpServers": { "defectdojo": { "command": "defectdojo-mcp", "args": [], "env": { "DEFECTDOJO_API_TOKEN": "YOUR_API_TOKEN_HERE", "DEFECTDOJO_API_BASE": "https://your-defectdojo-instance.com" } } } }

Exposed Toolset

The following atomic functions are accessible through the MCP interface:

• get_findings: Retrieve security findings, supporting filtering by product designation, current status, and severity level, alongside standard pagination controls (limit, offset).
• search_findings: Execute full-text queries against findings, incorporating optional scoping filters and pagination.
• update_finding_status: Modify the workflow state of a discrete finding (e.g., promoting it to 'Verified' or flagging as 'False Positive').
• add_finding_note: Append supplementary textual annotations to a specified finding record.
• create_finding: Register a novel vulnerability report within an existing test context.
• list_products: Enumerate registered products, with options to filter results by name or product type.
• list_engagements: Obtain a roster of security engagements, filterable by associated product identifier, current status, or engagement name.
• get_engagement: Fetch the complete metadata for a single engagement, identified by its unique ID.
• create_engagement: Schedule a new security review activity linked to a specific product.
• update_engagement: Adjust the parameters or status of a previously defined engagement.
• close_engagement: Officially mark a specific engagement cycle as concluded.

(Consult the underlying source code or official documentation for comprehensive usage parameters for each tool function)

Operational Walkthroughs

(These examples demonstrate invocation using an MCP client context with the use_mcp_tool asynchronous method)

Fetching Findings

python

Retrieve the first 10 findings that are currently 'Active' and rated 'High'

report = await use_mcp_tool("defectdojo", "get_findings", { "status": "Active", "severity": "High", "limit": 10 })

Searching Findings

python

Search for any finding titles or descriptions containing 'SQL Injection'

search_results = await use_mcp_tool("defectdojo", "search_findings", { "query": "SQL Injection" })

Changing Finding State

python

Transition finding ID 123 to the 'Verified' status

status_update = await use_mcp_tool("defectdojo", "update_finding_status", { "finding_id": 123, "status": "Verified" })

Annotating a Finding

python

Append an internal note to finding 123

note_added = await use_mcp_tool("defectdojo", "add_finding_note", { "finding_id": 123, "note": "Verification team confirmed exploitability on the staging environment." })

Registering a New Finding

python

Log a new Cross-Site Scripting (XSS) vulnerability

new_record = await use_mcp_tool("defectdojo", "create_finding", { "title": "Reflected XSS in Search Interface", "test_id": 55, "severity": "Medium", "description": "Input parameter 'q' lacks output encoding, permitting script execution.", "cwe": 79 })

Listing Products

python

List up to 10 products whose names contain 'Web Application'

product_list = await use_mcp_tool("defectdojo", "list_products", { "name": "Web Application", "limit": 10 })

Retrieving Engagements

python

List all engagements for Product ID 42 that are currently 'In Progress'

engagement_list = await use_mcp_tool("defectdojo", "list_engagements", { "product_id": 42, "status": "In Progress" })

Fetching Specific Engagement Details

python

Get all data for engagement with ID 101

details = await use_mcp_tool("defectdojo", "get_engagement", { "engagement_id": 101 })

Provisioning an Engagement

python

Schedule a new Q2 2025 security review for Product 42

new_engagement = await use_mcp_tool("defectdojo", "create_engagement", { "product_id": 42, "name": "Q2 Penetration Test 2025", "target_start": "2025-04-01", "target_end": "2025-04-15", "status": "Not Started" })

Modifying an Engagement

python

Update engagement 101 to show work has commenced

status_change = await use_mcp_tool("defectdojo", "update_engagement", { "engagement_id": 101, "status": "In Progress", "description": "Initial scoping phase completed." })

Finalizing an Engagement

python

Mark engagement 101 as formally finished

completion = await use_mcp_tool("defectdojo", "close_engagement", { "engagement_id": 101 })

Development Setup

Initialization

1. Clone the source repository.

2. It is highly advised to isolate dependencies within a virtual environment: bash python -m venv .venv source .venv/bin/activate # Use .venv\Scripts\activate on Windows systems

3. Install all necessary libraries, including testing and linting tools: bash pip install -e ".[dev]"

Licensing

This software is released under the terms specified in the LICENSE file.

Community Contribution

We welcome contributions! Please submit a detailed issue for any defects discovered or feature suggestions. For substantive code contributions, open a discussion thread (issue) first to align on the intended implementation strategy.