create_engagement

Initiate a new engagement in DefectDojo by defining product details, target timelines, and status to manage vulnerability assessments effectively.

Instructions

Create a new engagement

Input Schema

TableJSON Schema

Name	Required	Description	Default
`branch_tag`	No
`build_id`	No
`commit_hash`	No
`deduplication_on_engagement`	No
`description`	No
`engagement_type`	No
`lead_id`	No
`name`	Yes
`product_id`	Yes
`status`	Yes
`tags`	No
`target_end`	Yes
`target_start`	Yes
`version`	No

Implementation Reference

src/defectdojo/engagements_tools.py:63-121 (handler)

The primary handler function for the 'create_engagement' MCP tool. It validates input parameters, constructs the API payload, calls the DefectDojo client to create the engagement, and returns a structured success/error response.

async def create_engagement(product_id: int, name: str, target_start: str, target_end: str, status: str, lead_id: int = None, description: str = None, version: str = None, build_id: str = None, commit_hash: str = None, branch_tag: str = None, engagement_type: str = None, deduplication_on_engagement: bool = None, tags: list = None):
    """
    Creates a new engagement in DefectDojo.

    Args:
        product_id: ID of the product.
        name: Name of the engagement.
        target_start: Start date (YYYY-MM-DD).
        target_end: End date (YYYY-MM-DD).
        status: Engagement status ('Not Started', 'Blocked', 'Cancelled', 'Completed', 'In Progress', 'On Hold', 'Waiting for Resource').
        lead_id: Optional ID of the engagement lead (user ID).
        description: Optional engagement description.
        version: Optional product version tested.
        build_id: Optional build ID.
        commit_hash: Optional commit hash.
        branch_tag: Optional branch or tag.
        engagement_type: Optional engagement type ('Interactive' or 'CI/CD').
        deduplication_on_engagement: Optional flag to enable deduplication within this engagement.
        tags: Optional list of tags.

    Returns:
        JSON response from the API.
    """
    # endpoint = "/api/v2/engagements/" # Endpoint handled by client method
    valid_statuses = ["Not Started", "Blocked", "Cancelled", "Completed", "In Progress", "On Hold", "Waiting for Resource"]
    if status not in valid_statuses:
        # Use raise ValueError for internal validation errors
        raise ValueError(f"Invalid status '{status}'. Must be one of: {', '.join(valid_statuses)}")

    # Validate engagement_type if provided
    if engagement_type and engagement_type not in ["Interactive", "CI/CD"]:
         raise ValueError(f"Invalid engagement_type '{engagement_type}'. Must be 'Interactive' or 'CI/CD'.")

    data = {
        "product": product_id,
        "name": name,
        "target_start": target_start,
        "target_end": target_end,
        "status": status, # Use API expected casing directly
    }
    # Add optional fields cleanly
    if lead_id is not None: data["lead"] = lead_id
    if description is not None: data["description"] = description
    if version is not None: data["version"] = version
    if build_id is not None: data["build_id"] = build_id
    if commit_hash is not None: data["commit_hash"] = commit_hash
    if branch_tag is not None: data["branch_tag"] = branch_tag
    if engagement_type is not None: data["engagement_type"] = engagement_type
    if deduplication_on_engagement is not None: data["deduplication_on_engagement"] = deduplication_on_engagement
    if tags is not None: data["tags"] = tags # Assumes API accepts list directly

    client = get_client()
    result = await client.create_engagement(data)

    # Return structured response
    if "error" in result:
        return {"status": "error", "error": result["error"], "details": result.get("details", "")}

    return {"status": "success", "data": result}

src/defectdojo/tools.py:74-78 (registration)
Main registration of the 'create_engagement' tool using mcp.tool() in the central tools.py registration function. Imports the handler from engagements_tools.py.
```
mcp.tool(
    name="create_engagement",
    description="Create a new engagement in DefectDojo"
    # Schema inferred from type hints and docstring
)(create_engagement)
```

src/defectdojo/engagements_tools.py:227-233 (registration)

Modular registration function in engagements_tools.py that registers the 'create_engagement' tool (along with related engagement tools). This may be called internally or for testing.

def register_tools(mcp):
    """Register engagement-related tools with the MCP server instance."""
    mcp.tool(name="list_engagements", description="List engagements with optional filtering and pagination support")(list_engagements)
    mcp.tool(name="get_engagement", description="Get a specific engagement by ID")(get_engagement)
    mcp.tool(name="create_engagement", description="Create a new engagement")(create_engagement)
    mcp.tool(name="update_engagement", description="Update an existing engagement")(update_engagement)
    mcp.tool(name="close_engagement", description="Close an engagement")(close_engagement)

src/defectdojo/client.py:78-80 (helper)

Helper method in DefectDojoClient that performs the actual HTTP POST request to create an engagement. Called by the tool handler.

async def create_engagement(self, data: Dict[str, Any]) -> Dict[str, Any]:
    """Create a new engagement."""
    return await self._request("POST", "/api/v2/engagements/", json=data)

DefectDojo MCP Server