list_engagements
Retrieve and filter engagements in DefectDojo with pagination options to manage vulnerability assessment workflows efficiently.
Instructions
List engagements with optional filtering and pagination support
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| name | No | ||
| offset | No | ||
| product_id | No | ||
| status | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/defectdojo/engagements_tools.py:6-42 (handler)The handler function that implements the tool logic: fetches engagements from DefectDojo API with filters for product, status, name, pagination; includes validation and error handling.
async def list_engagements(product_id: Optional[int] = None, status: Optional[str] = None, name: Optional[str] = None, limit: int = 20, offset: int = 0) -> Dict[str, Any]: """List engagements with optional filtering and pagination. Args: product_id: Optional product ID filter status: Optional status filter (e.g., 'Not Started', 'In Progress', 'Completed') name: Optional name filter (partial match) limit: Maximum number of engagements to return per page (default: 20) offset: Number of records to skip (default: 0) Returns: Dictionary with status, data/error, and pagination metadata """ filters = {"limit": limit} if product_id: filters["product"] = product_id if status: # Validate against known API statuses if necessary valid_statuses = ["Not Started", "Blocked", "Cancelled", "Completed", "In Progress", "On Hold", "Waiting for Resource"] if status not in valid_statuses: return {"status": "error", "error": f"Invalid status filter '{status}'. Must be one of: {', '.join(valid_statuses)}"} filters["status"] = status if name: filters["name"] = name # Or name__icontains if supported if offset: filters["offset"] = offset client = get_client() result = await client.get_engagements(filters) if "error" in result: return {"status": "error", "error": result["error"], "details": result.get("details", "")} return {"status": "success", "data": result} - src/defectdojo/tools.py:64-68 (registration)Registers the 'list_engagements' tool with the FastMCP instance, specifying name and description, binding it to the handler function.
mcp.tool( name="list_engagements", description="List engagements with optional filtering and pagination support" )(list_engagements)