From e371684655c520a858a75e35693ab37417f04e76 Mon Sep 17 00:00:00 2001 From: Matt Tesauro Date: Wed, 23 Sep 2026 21:08:52 -0500 Subject: [PATCH 1/3] Add docs on MCP Report Generation --- .../metrics_reports/ai/claude_code_plugin.md | 4 +- .../metrics_reports/ai/mcp_server_pro.md | 130 +++++++++++++++++- 2 files changed, 129 insertions(+), 5 deletions(-) diff --git a/docs/content/metrics_reports/ai/claude_code_plugin.md b/docs/content/metrics_reports/ai/claude_code_plugin.md index bd21725556d..80ae8fb807a 100644 --- a/docs/content/metrics_reports/ai/claude_code_plugin.md +++ b/docs/content/metrics_reports/ai/claude_code_plugin.md @@ -11,8 +11,8 @@ weight: 24 The DefectDojo plugin for Claude Code brings your vulnerability data into the terminal where your team already works. Your Pro instance already speaks MCP; the plugin teaches a coding agent what to do with it, and adds the operations -the read-only [MCP Server](../mcp_server_pro/) does not cover, such as changing -finding status and importing scans. +the [MCP Server](../mcp_server_pro/)'s read-only `core` toolset does not cover, +such as changing finding status and importing scans. If you want to connect a chat assistant such as Claude Desktop or claude.ai to DefectDojo, use the [MCP Server](../mcp_server_pro/) page instead. This page is diff --git a/docs/content/metrics_reports/ai/mcp_server_pro.md b/docs/content/metrics_reports/ai/mcp_server_pro.md index 1362a2441ee..8275719ce0e 100644 --- a/docs/content/metrics_reports/ai/mcp_server_pro.md +++ b/docs/content/metrics_reports/ai/mcp_server_pro.md @@ -93,7 +93,8 @@ Toolsets are enabled under **Settings → Feature Flags**, nested below the **MC | Toolset | Feature Flag | Also requires | |---------|--------------|---------------| | `core` | none — always on with the MCP Server | — | -| `hierarchy` | **MCP: Asset Hierarchy** | the **Asset Hierarchy** feature | +| `hierarchy` | **MCP: Asset Hierarchy** | the **Asset Hierarchy** feature — see [Asset Hierarchy Toolset](#asset-hierarchy-toolset) | +| `reporting` | **MCP: Reporting** | the **Reporting** feature (the Report Builder) — see [Reporting Toolset](#reporting-toolset) | More toolsets appear in the Feature Flags menu as they are released. A toolset's flag only controls what the MCP Server offers: it does not change the REST API, and every tool call still runs with the permissions of the API token that connects. @@ -105,6 +106,8 @@ Add a `toolsets` query parameter to the MCP endpoint URL. Names are comma-separa |--------------|---------------| | `https://[YOUR-INSTANCE].defectdojo.com/mcp` | `core` only. Unchanged from earlier releases. | | `https://[YOUR-INSTANCE].defectdojo.com/mcp?toolsets=hierarchy` | `core` plus the Asset Hierarchy toolset. | +| `https://[YOUR-INSTANCE].defectdojo.com/mcp?toolsets=reporting` | `core` plus the Reporting toolset. | +| `https://[YOUR-INSTANCE].defectdojo.com/mcp?toolsets=hierarchy,reporting` | `core` plus both named toolsets. | | `https://[YOUR-INSTANCE].defectdojo.com/mcp?toolsets=all` | `core` plus every toolset enabled on the instance. Requires the `Authorization` header to be sent when connecting, because the server reads the instance's Feature Flags with your token to resolve `all`. | Any selection with a `toolsets` parameter also offers `get_instance_info`, a tool that reports the DefectDojo Pro version, which toolsets are enabled (`mcp_toolsets_enabled`), each Feature Flag's state, and whether the instance names its objects **Assets / Organizations** or **Products / Product Types**. Ask your assistant to call it when you are unsure which toolsets an instance provides. @@ -811,6 +814,123 @@ finding_summary({ --- +## Asset Hierarchy Toolset + +The `hierarchy` toolset (`?toolsets=hierarchy`) lets an assistant explore and maintain the Organization/Asset hierarchy: which Organizations exist, which Assets sit under which parents, where findings roll up, and where the structure has gaps. It adds 12 tools (7 read, 5 write), 1 resource and 2 prompts on top of `core`. + +It is available when an administrator has enabled **MCP: Asset Hierarchy** under **Settings → Feature Flags** (which itself requires the **Asset Hierarchy** feature). Instances that still use the classic **Product Type / Product** wording see the same tools; the tool and argument names always say `organization` and `asset`, and `get_instance_info` reports which words the instance shows its users. + +> **⚠️ Write tools change DefectDojo immediately.** This toolset contains the MCP Server's first write tools. Each one performs exactly one DefectDojo REST write with your API token: DefectDojo's own permission checks and validation apply, and the MCP Server adds no preview, dry run, approval step or undo. The bundled workflow guide instructs the assistant to explore first, summarise what it found, and ask for your confirmation before any change. If your token can re-parent or create Assets in the REST API, the assistant can too. + +Every hierarchy tool accepts the optional `token` parameter, and every list tool pages with `limit` (1–100, default 25) and `offset`. + +### 🌳 Hierarchy Read Tools + +| Tool | What it returns | Key parameters | +|------|-----------------|----------------| +| `get_organizations` | Organizations, including their nesting under a parent Organization. | `name` (exact), `org_type` (`team`, `business_app`, `compliance_scope`, `portfolio`, `custom`), `parent_id` | +| `get_organization_memberships` | Which Assets belong to an Organization, or which Organizations an Asset is in. `is_primary` marks the Asset's owning Organization. | `organization_id` and/or `asset_id` (at least one) | +| `get_asset_placement` | One Asset's Organization, parent Asset, tags and all of its memberships in a single call. | `asset_id` | +| `get_organization_type_roles` | Roles a user or group holds across every Organization of one type. Empty when the instance does not use type roles. | `org_type`, `role`, `user`, `group` | +| `get_hierarchy_tree` | The parent/child tree around one Asset: `root`, `nodes`, `edges`, and the IDs of nodes that were cut off. | `root_id`, `direction` (`down` default, `up`, `both`), `depth` (1–10, default 3), `nodes_per_level` | +| `get_structure_summary` | Health overview of the whole hierarchy: totals, orphan Assets (no parent and no children), duplicate names, and Organizations without Assets, each with capped examples. | `section` (`all`, `orphans`, `duplicates`, `organizations`), `limit` | +| `get_node_stats` | Finding roll-up for one Asset and its subtree: direct and indirect finding counts, descendant count, per-severity breakdown. | `asset_id` | + +An Asset the token cannot see is reported as `not_found`. Trees are capped by `depth` and `nodes_per_level`; a node flagged `has_more_children` needs another `get_hierarchy_tree` call with that node as `root_id`. + +### ✏️ Hierarchy Write Tools + +| Tool | What it does in DefectDojo | Key parameters | +|------|----------------------------|----------------| +| `set_asset_parent` | Sets or clears the parent of 1–25 Assets, one update per Asset. `parent_id: null` detaches an Asset while it keeps its own children. | `asset_ids`, `parent_id` | +| `remove_asset_parent` | Detaches one Asset from its parent and decides what happens to the Asset's children: `false` moves them under the former parent (closes the gap), `true` makes each child a root Asset (scatters them). | `asset_id`, `orphan_child_children` (required) | +| `create_organization` | Creates an Organization, optionally nested under `parent_id` and typed with `org_type`. | `name`, `description`, `org_type`, `parent_id` | +| `create_asset` | Creates an Asset in an Organization, optionally under a parent Asset and with tags. DefectDojo requires `description`. | `name`, `description`, `organization_id`, `parent_id`, `tags` | +| `manage_organization_membership` | Adds an Asset to an additional Organization (`action=add`; the instance must allow non-exclusive memberships) or removes such a membership (`action=remove`). A primary membership cannot be removed. | `action`, `asset_id`, `organization_id`, `membership_id` | + +Every write tool answers with the same result envelope so the assistant can tell you exactly what happened: + +| `outcome` | Meaning | +|-----------|---------| +| `committed` | DefectDojo accepted the change (`status_code` 200/201/204, plus `object_id` and `url` where a row was created). | +| `rejected` | DefectDojo refused it. `status_code` and `field_errors` carry DefectDojo's own answer (for example a 400 validation error, 403 permission denied, or 404 unknown ID). | +| `partial` | Only for `set_asset_parent`: some Assets were updated and others rejected. Nothing is rolled back; `results` lists the outcome per Asset. | +| `unknown` | The request left the MCP Server without a trustworthy answer (timeout or an upstream error). Check DefectDojo before retrying; the MCP Server never retries on its own. | + +Re-parenting an Asset or moving it between Organizations can change who can see it and its findings, because DefectDojo grants visibility through Organizations and through parent Assets. Ask the assistant to state the new audience before it applies such a change. + +### Hierarchy Resource and Prompts + +- **`mcp://resource/hierarchy/workflow-guide.md`** (Markdown) — the working method the assistant is expected to follow: learn the instance's vocabulary with `get_instance_info`, explore with the bounded read tools, summarise with IDs, propose, and change only after confirmation. +- **`explore_hierarchy`** prompt — takes `organization_name_or_id`; explores that Organization's Asset hierarchy and reports what is there before proposing any change. +- **`hierarchy_cleanup_review`** prompt — no arguments; reviews the whole hierarchy for orphan Assets, duplicate names and empty Organizations and proposes cleanup steps without applying them. + +### Example requests + +- "Run the hierarchy cleanup review and show me the orphaned Assets." +- "Explore the `Payments` Organization and draw the Asset tree three levels deep." +- "How many critical findings roll up to the `checkout-api` Asset and its children?" +- "Move `checkout-web` and `checkout-mobile` under `checkout-api`. Tell me who gains visibility first, then do it when I confirm." +- "Detach `legacy-gateway` from its parent but keep its children attached to the old parent." + +--- + +## Reporting Toolset + +The `reporting` toolset (`?toolsets=reporting`) lets an assistant work with the Pro [Report Builder](../../reports/report-builder/): read the themes, blocks and templates that already exist, design and create new ones, run a template, and hand you the download link once DefectDojo has rendered the file. It adds 17 tools (6 read, 11 write), 3 resources and 3 prompts on top of `core`. + +It is available when an administrator has enabled **MCP: Reporting** under **Settings → Feature Flags** (which itself requires the **Reporting** feature). The toolset covers the Report Builder only; the classic report engine and its migration endpoints are not exposed. If you would rather drive the Report Builder with an LLM through the REST API and a generated script, see [Building Reports with an LLM](../../reports/report-builder-llm/); the MCP toolset does the same job without any code leaving the chat. + +> **⚠️ Write tools change DefectDojo immediately.** As with the hierarchy toolset, each write tool performs exactly one DefectDojo REST write with your API token and relays DefectDojo's answer. DefectDojo's permission checks apply — an organization member with the Writer role can run reports but not change report definitions, exactly as in the UI — and the MCP Server adds no preview, approval step or undo. The bundled workflow guide instructs the assistant to look up what exists, propose the design, and ask for your confirmation before any write. + +Every reporting tool accepts the optional `token` parameter, and every list tool pages with `limit` (1–100, default 25) and `offset`. + +### 📄 Reporting Read Tools + +| Tool | What it returns | Key parameters | +|------|-----------------|----------------| +| `get_report_catalog` | Themes, blocks and templates in one call, each as a bounded page projected to `id`, `name`, kind, `block_count`/`filter_count` and `updated`. Names are not unique, so the assistant checks here before creating anything. | `section` (`all` default, `themes`, `blocks`, `templates`), per-collection `*_limit` and `*_offset` | +| `get_report_template` | One template. `summary` gives identity, theme and `block_count`; `blocks` adds the ordered block list; `full` returns the complete template as DefectDojo serializes it. | `template_id`, `include` (`summary` default, `blocks`, `full`) | +| `get_report_block` | One block with its single configuration (`tabular`, `detail`, `chart`, `stock` or `widget`) and its filter entries. | `block_id` | +| `get_report_field_options` | The field paths a tabular or detail block may show and the values it may sort by, per model, as this instance exposes them. | `model_choice` (optional) | +| `get_generated_reports` | Report runs, newest first: `status`, `file_format`, who requested it and when, `error_message` for a failed run, and `download_url` once a run is `completed`. | `template_id`, `status` (`pending`, `processing`, `completed`, `failed`), `file_format`, `requested_by`, `requested_after` | +| `get_generated_report` | One run by id — the tool the assistant polls after `generate_report`. | `report_id` | + +### ✏️ Reporting Write Tools + +| Tool | What it does in DefectDojo | Key parameters | +|------|----------------------------|----------------| +| `create_report_theme` / `update_report_theme` / `delete_report_theme` | Creates, changes or deletes a theme: five `#rrggbb` colours, `base_font_size` (8–16), `footer_text`, `show_page_numbers`. Only `name` is required on create. Templates that used a deleted theme render with default styling. | `theme_id`, `name`, colour fields | +| `create_report_block` / `update_report_block` / `delete_report_block` | Creates, changes or deletes a block — the reusable unit templates are built from. `block_type` and its matching configuration are required on create: `tabular`/`detail` (`model_choice`, `fields`, `ordering`), `chart` (`chart_key`, `model_choice`, optional `date_range` in days) or `stock` (cover page, table of contents, page break, text block). `block_type` and a configuration's `model_choice` cannot change after creation. Image stock blocks and `widget` blocks are created in the Pro UI. | `block_id`, `name`, `block_type`, one `*_configuration`, `filter_entries` | +| `create_report_template` / `update_report_template` / `delete_report_template` | Creates, changes or deletes a template: a name, optional `theme_id`, and the ordered blocks as `template_blocks_write` `[{block_id, order}]`. On update that list **replaces** the whole block list, so the assistant reads the template first and sends every block that stays. Deleting a template does not delete its blocks, its theme or reports already generated from it. | `template_id`, `name`, `theme_id`, `template_blocks_write` | +| `duplicate_report_template` | Copies a template, including its theme and block list, as ` (Copy)`. | `template_id` | +| `generate_report` | Starts one report run and returns at once with `job_id` and `status` (normally `pending`). Every call is a new run. | `template_id`, `file_format` (`pdf` or `html`), `name`, `runtime_filters` | + +Write tools answer with the same `outcome` envelope for the [Asset Hierarchy Toolset](#asset-hierarchy-toolset) (`committed`, `rejected`, `unknown`); `generate_report` additionally carries the new run's `status`. + +#### Reports are generated asynchronously + +DefectDojo renders reports in a background worker, so `generate_report` does not return a file. The assistant is told to call `get_generated_report` with the returned `job_id` every 10–30 seconds (for up to about 10 minutes) until `status` is `completed` or `failed`. A completed run carries `download_url`, a path on your DefectDojo instance (`/api/v2/generated_reports//download/`) that you open with your own DefectDojo credentials; a failed run carries `error_message`. No reporting tool returns the report's content, and there is no scheduling tool — recurring reports are set up in the DefectDojo Pro UI. + +### Reporting Resources and Prompts + +- **`mcp://resource/reporting/builder-schema.json`** (JSON) — the structure and allowed values of themes, blocks, templates and runs as the write tools accept them. +- **`mcp://resource/reporting/chart-catalog.json`** (JSON) — every `chart_key` a chart block may use, its label, the `model_choice` it requires, and whether it is a time series. +- **`mcp://resource/reporting/workflow-guide.md`** (Markdown) — the working method: look up before creating, build theme → blocks → template, generate, poll, then hand over the download link. +- **`build_report_template`** prompt — takes `audience`, `scope_description` and an optional `file_format`; reads the resources and the catalog, proposes a theme, block list and template for that audience, and creates them in dependency order after you approve. +- **`run_report`** prompt — takes `template_name_or_id` plus optional `timeframe` and `file_format`; resolves the template by exact name or id, summarises what it contains, generates it, polls to completion and returns the download link or the error. +- **`check_report_run`** prompt — takes `template_name_or_id`; lists that template's recent runs with status, requester and download links without starting a new run. + +### Example requests + +- "Show me the report templates we already have and what blocks each one uses." +- "Build a monthly executive PDF for the `Payments` Organization: cover page, severity-over-time chart, and a table of open Critical and High findings. Propose it first." +- "Run the `Quarterly Compliance` template as HTML and give me the link when it's done." +- "Did last night's `SOC 2 Evidence` report finish? If it failed, tell me why." +- "Duplicate `Executive Summary`, rename the copy `Executive Summary — EMEA`, and add the `Assets by Region` block at the end." + +--- + ## Reference Resources The `core` toolset publishes 6 read-only JSON resources (MIME type `application/json`). They are reference material bundled with the MCP Server, not data from your DefectDojo instance, and are available without any tool call so an assistant can map findings to a standard or explain a regulatory obligation while it reports. @@ -826,6 +946,8 @@ The `core` toolset publishes 6 read-only JSON resources (MIME type `application/ Ask your assistant to read a resource by URI (for example, "read `mcp://resource/cwe_to_owasp_2025_mapping.json` and group our open findings by OWASP category") when a report should cite a standard. +Add-on toolsets publish their own resources alongside these: the `hierarchy` toolset adds `mcp://resource/hierarchy/workflow-guide.md` (see [Asset Hierarchy Toolset](#asset-hierarchy-toolset)) and the `reporting` toolset adds three under `mcp://resource/reporting/` (see [Reporting Toolset](#reporting-toolset)). + --- ## Pre-Configured Prompts @@ -865,6 +987,8 @@ The DefectDojo MCP Server includes pre-configured prompts that demonstrate best > **💡 Using Prompts:** To invoke a prompt, simply ask your AI assistant: "Create a SAST Review Report" or "Generate a Security Landscape Report using DefectDojo data" +The `hierarchy` toolset adds two more prompts, `explore_hierarchy` and `hierarchy_cleanup_review`, described under [Asset Hierarchy Toolset](#asset-hierarchy-toolset); the `reporting` toolset adds `build_report_template`, `run_report` and `check_report_run`, described under [Reporting Toolset](#reporting-toolset). Unlike the two `core` prompts, most of these take arguments, which your client asks for when you invoke them. + --- ## Use Case Examples @@ -1163,11 +1287,11 @@ Verify these items when experiencing connection issues: #### ❌ "toolset 'hierarchy' is not enabled on this DefectDojo Pro instance" -**Cause:** The connection URL asks for a toolset whose Feature Flag is off, or the MCP Server itself is disabled. +**Cause:** The connection URL asks for a toolset whose Feature Flag is off, or the MCP Server itself is disabled. The same message names `reporting` when that toolset's flag is off. **Solutions:** -1. Ask a superuser to open **Settings → Feature Flags**, confirm **MCP Server** is on, and enable the toolset's flag (for `hierarchy`, **MCP: Asset Hierarchy**, which also needs the **Asset Hierarchy** feature) +1. Ask a superuser to open **Settings → Feature Flags**, confirm **MCP Server** is on, and enable the toolset's flag (for `hierarchy`, **MCP: Asset Hierarchy**, which also needs the **Asset Hierarchy** feature; for `reporting`, **MCP: Reporting**, which also needs the **Reporting** feature) 2. Or remove the toolset from the `toolsets` parameter and reconnect 3. Ask your assistant to call `get_instance_info` to see which toolsets the instance has enabled From 6c0d3058d33f1390525cf5ab434cb7ec3fba2ca2 Mon Sep 17 00:00:00 2001 From: Matt Tesauro Date: Thu, 24 Sep 2026 19:49:13 -0500 Subject: [PATCH 2/3] Update MCP docs for Multi-MCP Report Builder --- .../metrics_reports/ai/mcp_server_pro.md | 33 ++++- .../reports/PRO__report_builder_api.md | 113 +++++++++++++++++- 2 files changed, 137 insertions(+), 9 deletions(-) diff --git a/docs/content/metrics_reports/ai/mcp_server_pro.md b/docs/content/metrics_reports/ai/mcp_server_pro.md index 8275719ce0e..325538747e8 100644 --- a/docs/content/metrics_reports/ai/mcp_server_pro.md +++ b/docs/content/metrics_reports/ai/mcp_server_pro.md @@ -877,7 +877,7 @@ Re-parenting an Asset or moving it between Organizations can change who can see ## Reporting Toolset -The `reporting` toolset (`?toolsets=reporting`) lets an assistant work with the Pro [Report Builder](../../reports/report-builder/): read the themes, blocks and templates that already exist, design and create new ones, run a template, and hand you the download link once DefectDojo has rendered the file. It adds 17 tools (6 read, 11 write), 3 resources and 3 prompts on top of `core`. +The `reporting` toolset (`?toolsets=reporting`) lets an assistant work with the Pro [Report Builder](../../reports/report-builder/): read the themes, blocks and templates that already exist, design and create new ones, run a template once or on a recurring schedule, and hand you the download link once DefectDojo has rendered the file. It adds 22 tools (8 read, 14 write), 3 resources and 3 prompts on top of `core`. It is available when an administrator has enabled **MCP: Reporting** under **Settings → Feature Flags** (which itself requires the **Reporting** feature). The toolset covers the Report Builder only; the classic report engine and its migration endpoints are not exposed. If you would rather drive the Report Builder with an LLM through the REST API and a generated script, see [Building Reports with an LLM](../../reports/report-builder-llm/); the MCP toolset does the same job without any code leaving the chat. @@ -893,8 +893,10 @@ Every reporting tool accepts the optional `token` parameter, and every list tool | `get_report_template` | One template. `summary` gives identity, theme and `block_count`; `blocks` adds the ordered block list; `full` returns the complete template as DefectDojo serializes it. | `template_id`, `include` (`summary` default, `blocks`, `full`) | | `get_report_block` | One block with its single configuration (`tabular`, `detail`, `chart`, `stock` or `widget`) and its filter entries. | `block_id` | | `get_report_field_options` | The field paths a tabular or detail block may show and the values it may sort by, per model, as this instance exposes them. | `model_choice` (optional) | -| `get_generated_reports` | Report runs, newest first: `status`, `file_format`, who requested it and when, `error_message` for a failed run, and `download_url` once a run is `completed`. | `template_id`, `status` (`pending`, `processing`, `completed`, `failed`), `file_format`, `requested_by`, `requested_after` | +| `get_generated_reports` | Report runs, newest first: `status`, `file_format`, who requested it and when, `error_message` for a failed run, and `download_url` once a run is `completed`. | `template_id`, `status` (`pending`, `processing`, `completed`, `failed`), `file_format`, `requested_by`, `requested_after` (`YYYY-MM-DD`) | | `get_generated_report` | One run by id — the tool the assistant polls after `generate_report`. | `report_id` | +| `get_report_content` | The plain-text rendition of a completed `pdf` or `html` report, so the assistant can summarise what the report says without downloading the file. Returns `content`, `truncated`, `total_bytes` and `returned_bytes`; `content` is `null` for other formats and for reports generated before your instance started writing text renditions. Available from DefectDojo Pro 3.3.300. | `report_id`, `max_bytes` (1–262144, default 65536) | +| `get_report_schedules` | Report schedules — standing requests that generate a report from a template on a cron cadence — newest first, or one by id. Each carries its `template`, `file_format`, `runtime_filters`, `created_by`, and a `schedule` object from DefectDojo's scheduling service: `enabled`, `trigger_expression` (UTC cron), `trigger_expression_readable`, `next_run`, `last_run` and the `status` of the last run. Available from DefectDojo Pro 3.3.300. | `schedule_id`, `template_id`, `created_by`, `file_format` | ### ✏️ Reporting Write Tools @@ -905,20 +907,36 @@ Every reporting tool accepts the optional `token` parameter, and every list tool | `create_report_template` / `update_report_template` / `delete_report_template` | Creates, changes or deletes a template: a name, optional `theme_id`, and the ordered blocks as `template_blocks_write` `[{block_id, order}]`. On update that list **replaces** the whole block list, so the assistant reads the template first and sends every block that stays. Deleting a template does not delete its blocks, its theme or reports already generated from it. | `template_id`, `name`, `theme_id`, `template_blocks_write` | | `duplicate_report_template` | Copies a template, including its theme and block list, as ` (Copy)`. | `template_id` | | `generate_report` | Starts one report run and returns at once with `job_id` and `status` (normally `pending`). Every call is a new run. | `template_id`, `file_format` (`pdf` or `html`), `name`, `runtime_filters` | +| `schedule_report` | Creates a standing schedule that generates a report from a template on a cron cadence. Returns at once with the schedule id, `status: enabled` and the next run time; nothing is generated until the first tick. Every call creates another schedule, so the assistant lists existing ones first. | `template_id`, `file_format` (`pdf` or `html`), `cron`, `name`, `runtime_filters` | +| `update_report_schedule` | Pauses or resumes a schedule (`enabled`), moves it to a new cadence (`cron`), or changes its `name`, `file_format` or `runtime_filters`. Fields not supplied keep their value. | `schedule_id` plus at least one of `enabled`, `cron`, `name`, `file_format`, `runtime_filters` | +| `delete_report_schedule` | Deletes a schedule. No further reports are generated from it; the reports it already produced are kept. | `schedule_id` | -Write tools answer with the same `outcome` envelope for the [Asset Hierarchy Toolset](#asset-hierarchy-toolset) (`committed`, `rejected`, `unknown`); `generate_report` additionally carries the new run's `status`. +Write tools answer with the same `outcome` envelope for the [Asset Hierarchy Toolset](#asset-hierarchy-toolset) (`committed`, `rejected`, `unknown`); `generate_report` additionally carries the new run's `status`, and `schedule_report`/`update_report_schedule` carry the schedule's real state as `status` (`enabled` or `disabled`). #### Reports are generated asynchronously -DefectDojo renders reports in a background worker, so `generate_report` does not return a file. The assistant is told to call `get_generated_report` with the returned `job_id` every 10–30 seconds (for up to about 10 minutes) until `status` is `completed` or `failed`. A completed run carries `download_url`, a path on your DefectDojo instance (`/api/v2/generated_reports//download/`) that you open with your own DefectDojo credentials; a failed run carries `error_message`. No reporting tool returns the report's content, and there is no scheduling tool — recurring reports are set up in the DefectDojo Pro UI. +DefectDojo renders reports in a background worker, so `generate_report` does not return a file. The assistant is told to call `get_generated_report` with the returned `job_id` every 10–30 seconds (for up to about 10 minutes) until `status` is `completed` or `failed`. A completed run carries `download_url`, a path on your DefectDojo instance (`/api/v2/generated_reports//download/`) that you open with your own DefectDojo credentials; a failed run carries `error_message`. The MCP Server never proxies the file itself. To read what a completed `pdf` or `html` report says, the assistant calls `get_report_content`, which returns the bounded plain-text rendition DefectDojo writes next to the file (the same text as `/api/v2/generated_reports//content/`, described in [Automating Reports with the API](../../reports/report-builder-api/#step-3-run-the-report-and-download-the-result); capped at 256 KiB upstream and sliced by `max_bytes`). Calling it before the run has completed returns a not-found error that tells the assistant to keep polling `get_generated_report`. + +#### Recurring reports + +`schedule_report` creates a report schedule through `/api/v2/report_schedules/` (see [Automating Reports with the API](../../reports/report-builder-api/#step-4-run-a-report-on-a-schedule); DefectDojo Pro 3.3.300 or later). A few rules are worth knowing before you ask for one: + +- **The cadence is a five-field cron expression in UTC**, at most once an hour: the minute field must be a single value, so `0 6 * * 1` (06:00 UTC every Monday) is accepted and `*/15 * * * *` is rejected. The assistant translates "every weekday at 8" into cron for you; the response carries `trigger_expression_readable` and the `next_run` time so you can check its reading. +- **Each run is generated as the schedule's creator** — the user whose token created it — with that user's visibility, and appears in `get_generated_reports` as an ordinary run requested by that user. +- **A new schedule is always enabled.** To prepare one without running it yet, create it and then pause it with `update_report_schedule` and `enabled: false`; a paused schedule keeps its cadence until you resume it with `enabled: true`. +- **Changing the cadence resumes a paused schedule**, even when `enabled: false` is sent in the same call, because DefectDojo re-registers the schedule with its scheduling service. The assistant is told to send the new `cron` first and pause again in a second call; the `status` in every response is the schedule's real state, so check it. +- **Who may change a schedule.** Any organization member who can run the template can schedule it, but only the schedule's creator or a report administrator may update or delete it; anyone else receives a permission error. +- **Deleting a schedule keeps its reports.** `delete_report_schedule` stops future runs; reports already generated stay in `get_generated_reports` until they are deleted. + +Report schedules have no page of their own in the DefectDojo Pro UI yet, so the MCP Server returns no `url` for one; `get_report_schedules` is the way to review them. ### Reporting Resources and Prompts - **`mcp://resource/reporting/builder-schema.json`** (JSON) — the structure and allowed values of themes, blocks, templates and runs as the write tools accept them. - **`mcp://resource/reporting/chart-catalog.json`** (JSON) — every `chart_key` a chart block may use, its label, the `model_choice` it requires, and whether it is a time series. -- **`mcp://resource/reporting/workflow-guide.md`** (Markdown) — the working method: look up before creating, build theme → blocks → template, generate, poll, then hand over the download link. +- **`mcp://resource/reporting/workflow-guide.md`** (Markdown) — the working method: look up before creating, build theme → blocks → template, generate, poll, read the text rendition with `get_report_content` when a summary is wanted, then hand over the download link; plus how to create, pause, move and delete a report schedule. - **`build_report_template`** prompt — takes `audience`, `scope_description` and an optional `file_format`; reads the resources and the catalog, proposes a theme, block list and template for that audience, and creates them in dependency order after you approve. -- **`run_report`** prompt — takes `template_name_or_id` plus optional `timeframe` and `file_format`; resolves the template by exact name or id, summarises what it contains, generates it, polls to completion and returns the download link or the error. +- **`run_report`** prompt — takes `template_name_or_id` plus optional `timeframe` and `file_format`; resolves the template by exact name or id, summarises what it contains, generates it, polls to completion, offers a summary of the text rendition, and returns the download link or the error. - **`check_report_run`** prompt — takes `template_name_or_id`; lists that template's recent runs with status, requester and download links without starting a new run. ### Example requests @@ -927,7 +945,10 @@ DefectDojo renders reports in a background worker, so `generate_report` does not - "Build a monthly executive PDF for the `Payments` Organization: cover page, severity-over-time chart, and a table of open Critical and High findings. Propose it first." - "Run the `Quarterly Compliance` template as HTML and give me the link when it's done." - "Did last night's `SOC 2 Evidence` report finish? If it failed, tell me why." +- "Summarise the key numbers in the latest `Executive Summary` PDF." - "Duplicate `Executive Summary`, rename the copy `Executive Summary — EMEA`, and add the `Assets by Region` block at the end." +- "Generate the `Executive Summary` as PDF every Monday at 06:00 UTC. Which schedules already exist for that template?" +- "Pause the weekly `SOC 2 Evidence` schedule until further notice." --- diff --git a/docs/content/metrics_reports/reports/PRO__report_builder_api.md b/docs/content/metrics_reports/reports/PRO__report_builder_api.md index 82b5b3fc7e1..fbd7a910dea 100644 --- a/docs/content/metrics_reports/reports/PRO__report_builder_api.md +++ b/docs/content/metrics_reports/reports/PRO__report_builder_api.md @@ -8,7 +8,7 @@ slug: report-builder-api --- Note: The Report Builder REST API (report themes, blocks, templates, and generated reports) is a DefectDojo Pro feature, currently in beta. -The Report Builder REST API lets you automate the same Themes, Blocks, and Templates you assemble by hand in the [Report Builder UI](../report-builder/) — and it goes one step further by letting you **run** a template and **download** the finished PDF or HTML. This guide walks the full lifecycle: authenticate, discover the field and filter vocabulary, create the building blocks, then generate and retrieve a report. +The Report Builder REST API lets you automate the same Themes, Blocks, and Templates you assemble by hand in the [Report Builder UI](../report-builder/) — and it goes one step further by letting you **run** a template, **download** the finished PDF or HTML, or **read** its plain-text rendition. This guide walks the full lifecycle: authenticate, discover the field and filter vocabulary, create the building blocks, then generate and retrieve a report. > **Looking for a quick findings export instead?** If you only need a flat list of findings as JSON, HTML, CSV, or Excel — with no themes, blocks, or templates to set up — use the simpler `generate_report/` endpoint documented in [Generating Reports](/automation/api/api-v2-docs/#generating-reports). The Report Builder API described on this page is for building designed, multi\-section reports. @@ -51,14 +51,15 @@ List endpoints are paginated with `limit` and `offset` query parameters. ## The reporting API at a glance -Four resources make up the Report Builder API. Each supports the standard list (`GET`), create (`POST`), retrieve (`GET {id}/`), update (`PATCH {id}/`), and delete (`DELETE {id}/`) operations, plus a handful of custom actions. +Five resources make up the Report Builder API. Each supports the standard list (`GET`), create (`POST`), retrieve (`GET {id}/`), update (`PATCH {id}/`), and delete (`DELETE {id}/`) operations, plus a handful of custom actions. | Resource | Path | What it is | Custom actions | |----------|------|------------|----------------| | Themes | `/report_themes/` | Colors, fonts, header/footer images, page numbers | — | | Blocks | `/report_blocks/` | A single piece of content: a cover page, a table, or a detail section | `field_options/`, `preview/`, `{id}/preview/`, `{id}/duplicate/` | | Templates | `/report_templates/` | An ordered list of blocks plus a theme | `{id}/duplicate/` | -| Generated reports | `/generated_reports/` | A run of a template that produces a downloadable file | `{id}/download/` | +| Generated reports | `/generated_reports/` | A run of a template that produces a downloadable file | `{id}/download/`, `{id}/content/` | +| Report schedules | `/report_schedules/` | A standing request that runs a template on a cron cadence | — | Two more endpoints help you discover the vocabulary you need: @@ -378,6 +379,112 @@ curl -s -L \ -o report.pdf ``` +**Read the report as plain text (optional).** A `pdf` or `html` report also gets a plain-text rendition when it is generated, so automation (or an AI assistant) can read what a report says without downloading and parsing the file. The `content/` endpoint returns a bounded slice of that text as JSON: + +```bash +curl -s \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/generated_reports/7/content/?max_bytes=65536" +``` + +```json +{ + "id": 7, + "status": "completed", + "file_format": "pdf", + "content_type": "text/plain", + "truncated": false, + "total_bytes": 4213, + "returned_bytes": 4213, + "content": "Quarterly Findings Report\nSeverity\tTitle\tAsset\nCritical\tSQL injection in the login form\tCustomer Portal\n..." +} +``` + +A few rules keep this endpoint cheap to call, whatever the size of the underlying report: + +- The text is produced once, by the generation worker, from the rendered HTML — table rows come back as tab-separated lines, and headings and paragraphs as their own lines. It is capped at 256 KiB; a longer report is cut there and reported with `"truncated": true`. +- `max_bytes` (default `65536`) limits how much of that text one call returns. Values above 256 KiB are clamped to it; `0`, a negative number or a non-integer returns `400`. `total_bytes` is the size of the whole rendition, `returned_bytes` what this response holds, and `truncated` is `true` whenever `content` is not the complete report text. +- Like `download/`, the endpoint responds `404` until the run is `completed`. +- `csv`, `xlsx` and `json` runs have no text rendition — their rows are already machine-readable through `download/` — so `content/` answers `200` with `"content": null` for them. + +## Step 4: Run a report on a schedule + +A report schedule is a standing version of the request in Step 3: the template, format and runtime filters to run, plus a cron cadence. DefectDojo's scheduling service generates a new report on every tick, and each one appears in `/generated_reports/` as an ordinary run, so the polling, download and `content/` calls above work unchanged. Report schedules are available from DefectDojo Pro 3.3.300. + +**Create a schedule.** POST the same `template_id`, `file_format` and optional `name` / `runtime_filters` you would send to `/generated_reports/`, plus a nested `schedule` object carrying the cadence: + +```bash +curl -s -X POST \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + -H "Content-Type: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/report_schedules/" \ + -d '{ + "template_id": 5, + "file_format": "pdf", + "name": "Weekly executive summary", + "schedule": {"trigger_expression": "0 6 * * 1"} + }' +``` + +`schedule.trigger_expression` is a five-field cron expression (minute, hour, day of month, month, day of week) evaluated in **UTC**. A schedule may run at most once an hour: the minute field must be a single value, so `0 6 * * 1` (06:00 UTC every Monday) is accepted and `*/15 * * * *` is refused with `400` under `trigger_expression`. Any of the five `file_format` values is allowed. + +The response is the schedule with the scheduling service's view of it nested as `schedule`: + +```json +{ + "id": 3, + "name": "Weekly executive summary", + "template": { + "id": 5, + "name": "Executive Summary", + "description": "", + "created_by": "reporting-bot", + "created": "2026-09-23T03:15:56Z", + "updated": "2026-09-23T03:15:56Z", + "block_count": 4 + }, + "file_format": "pdf", + "runtime_filters": {}, + "created_by": "reporting-bot", + "created": "2026-09-24T07:10:29Z", + "updated": "2026-09-24T07:10:29Z", + "schedule": { + "enabled": true, + "status": "S", + "trigger_expression": "0 6 * * 1", + "trigger_expression_readable": "At 06:00 AM, only on Monday", + "last_run": null, + "next_run": "2026-09-28T06:00:00Z" + } +} +``` + +A few things to know about how schedules behave: + +- **Every run is generated as the schedule's creator.** `created_by` is the user whose token created the schedule, each run is requested by that user with that user's visibility, and `created_by` never changes — a PATCH by someone else does not move the schedule to them. +- **A new schedule is always enabled.** To create one without running it yet, create it and then pause it (below). +- **Registering a new cadence resumes the schedule**, even if the same PATCH also sends `"enabled": false`. To move a paused schedule and keep it paused, PATCH the cadence first and pause it in a second call. The `schedule.enabled` value in every response is the schedule's real state. +- **Creating and registering are one transaction.** If the scheduling service cannot register the cadence, the request answers `503` and no schedule row is kept. + +**List, filter and read back.** `GET /report_schedules/` lists the schedules the caller may see, newest first; filter with `template`, `created_by`, `file_format` or `id`, and retrieve one with `GET /report_schedules/{id}/`. To see the reports a schedule has produced, list `/generated_reports/` with the same `template` and the creator as `requested_by`. + +**Pause, resume or change a schedule.** PATCH the report-side fields (`name`, `file_format`, `runtime_filters`) or a `schedule` object. `schedule` may carry only `enabled` to pause or resume without touching the cadence: + +```bash +curl -s -X PATCH \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + -H "Content-Type: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/report_schedules/3/" \ + -d '{"schedule": {"enabled": false}}' +``` + +**Delete a schedule.** `DELETE /report_schedules/{id}/` answers `204` and stops future runs; the reports it already generated stay in `/generated_reports/`. + +Any organization member who may run a template may schedule it. Updating or deleting a schedule is limited to its creator and to users with the global permission to delete generated reports; anyone else receives `403`. As with every other Report Builder endpoint, the routes require the **Reporting** feature and answer `403` with `"code": "feature_disabled"` when it is off. + ## Putting it together: a full lifecycle script The script below runs the entire flow using only the Python 3 standard library — no `requests`, no third-party packages. It reads the token from `DD_IMPORTER_DOJO_API_TOKEN`, creates a theme, three blocks, and a template, kicks off a report, polls with backoff until it completes or fails, downloads the result, and writes the created IDs to `created.json`. From 5a59f54a7691ae0781beeaa09a08aa1489b69d97 Mon Sep 17 00:00:00 2001 From: Matt Tesauro Date: Fri, 25 Sep 2026 17:08:55 -0500 Subject: [PATCH 3/3] Update docs for MCP Dashboard addition --- .../metrics_reports/ai/mcp_server_pro.md | 84 +++++++++++++++++++ .../dashboards/PRO__custom_dashboards.md | 1 + .../dashboards/PRO__custom_dashboards_api.md | 1 + .../dashboards/PRO__custom_dashboards_llm.md | 1 + 4 files changed, 87 insertions(+) diff --git a/docs/content/metrics_reports/ai/mcp_server_pro.md b/docs/content/metrics_reports/ai/mcp_server_pro.md index 325538747e8..9ba805b61ef 100644 --- a/docs/content/metrics_reports/ai/mcp_server_pro.md +++ b/docs/content/metrics_reports/ai/mcp_server_pro.md @@ -95,6 +95,10 @@ Toolsets are enabled under **Settings → Feature Flags**, nested below the **MC | `core` | none — always on with the MCP Server | — | | `hierarchy` | **MCP: Asset Hierarchy** | the **Asset Hierarchy** feature — see [Asset Hierarchy Toolset](#asset-hierarchy-toolset) | | `reporting` | **MCP: Reporting** | the **Reporting** feature (the Report Builder) — see [Reporting Toolset](#reporting-toolset) | +<<<<<<< Updated upstream +======= +| `dashboards` | **MCP: Dashboards 2.0** | the **Dashboards 2.0** feature ([Customizable Dashboards](../../dashboards/custom-dashboards/)) — see [Dashboards Toolset](#dashboards-toolset) | +>>>>>>> Stashed changes More toolsets appear in the Feature Flags menu as they are released. A toolset's flag only controls what the MCP Server offers: it does not change the REST API, and every tool call still runs with the permissions of the API token that connects. @@ -107,7 +111,12 @@ Add a `toolsets` query parameter to the MCP endpoint URL. Names are comma-separa | `https://[YOUR-INSTANCE].defectdojo.com/mcp` | `core` only. Unchanged from earlier releases. | | `https://[YOUR-INSTANCE].defectdojo.com/mcp?toolsets=hierarchy` | `core` plus the Asset Hierarchy toolset. | | `https://[YOUR-INSTANCE].defectdojo.com/mcp?toolsets=reporting` | `core` plus the Reporting toolset. | +<<<<<<< Updated upstream | `https://[YOUR-INSTANCE].defectdojo.com/mcp?toolsets=hierarchy,reporting` | `core` plus both named toolsets. | +======= +| `https://[YOUR-INSTANCE].defectdojo.com/mcp?toolsets=dashboards` | `core` plus the Dashboards toolset. | +| `https://[YOUR-INSTANCE].defectdojo.com/mcp?toolsets=hierarchy,reporting,dashboards` | `core` plus every named toolset. | +>>>>>>> Stashed changes | `https://[YOUR-INSTANCE].defectdojo.com/mcp?toolsets=all` | `core` plus every toolset enabled on the instance. Requires the `Authorization` header to be sent when connecting, because the server reads the instance's Feature Flags with your token to resolve `all`. | Any selection with a `toolsets` parameter also offers `get_instance_info`, a tool that reports the DefectDojo Pro version, which toolsets are enabled (`mcp_toolsets_enabled`), each Feature Flag's state, and whether the instance names its objects **Assets / Organizations** or **Products / Product Types**. Ask your assistant to call it when you are unsure which toolsets an instance provides. @@ -952,6 +961,65 @@ Report schedules have no page of their own in the DefectDojo Pro UI yet, so the --- +<<<<<<< Updated upstream +======= +## Dashboards Toolset + +The `dashboards` toolset (`?toolsets=dashboards`) lets an assistant work with [Customizable Dashboards](../../dashboards/custom-dashboards/): list the dashboards you can see, read what is on one, render a widget's current numbers, explain why a widget shows what it shows, and design, create, edit, clone, share and delete dashboards for you. It adds 11 tools (6 read, 5 write), 2 resources and 2 prompts on top of `core`. + +It is available when an administrator has enabled **MCP: Dashboards 2.0** under **Settings → Feature Flags** (which itself requires the **Dashboards 2.0** feature, described in [Enabling Customizable Dashboards](../../dashboards/custom-dashboards/#enabling-customizable-dashboards)). It requires DefectDojo Pro 3.3.300 or later, the release that made the dashboards endpoints available to API tokens under `/api/v2/dashboards/`. If you would rather drive dashboards with an LLM through the REST API and a generated script, see [Building Dashboards with an LLM](../../dashboards/custom-dashboards-llm/); the MCP toolset does the same job without any code leaving the chat. + +> **⚠️ Write tools change DefectDojo immediately.** As with the hierarchy and reporting toolsets, each write tool performs one DefectDojo REST write with your API token and relays DefectDojo's answer. DefectDojo's permission checks apply — sharing a dashboard needs the same permission as in the UI, and an instance whose administrator has locked dashboards to the designated defaults refuses edits the same way — and the MCP Server adds no preview, approval step or undo. The bundled workflow guide instructs the assistant to read the widget catalog, propose the dashboard, and ask for your confirmation before any write, and never to share a dashboard unless you ask. + +Every dashboards tool accepts the optional `token` parameter, and every list tool pages with `limit` (1–100, default 25) and `offset`. + +### 📊 Dashboards Read Tools + +| Tool | What it returns | Key parameters | +|------|-----------------|----------------| +| `get_dashboards` | The dashboards visible to your token, one page at a time. Each row carries `id`, `name`, `is_shared`, `is_default`, `is_owned`, `is_catalog`, `can_edit`, `can_manage`, `category`, `widget_count`, `updated_at` and a `url`. | `scope` (`all` default, `mine`, `shared`) | +| `get_dashboard` | One dashboard. `summary` (default) gives identity, sharing/ownership/default flags, `widget_count` and `settings`; `widgets` adds each widget's `id`, `type`, `title`, `refresh_interval` and grid `position` without its configuration; `full` returns the complete layout document as DefectDojo serializes it, the form `update_dashboard`'s whole-document mode expects back. Never renders data. | `dashboard_id`, `include` (`summary` default, `widgets`, `full`) | +| `get_widget_catalog` | Every widget type the instance knows (48 in 3.3.300): `type`, `label`, `category`, `description`, `config_example`, what it `requires` (feature flags, licensed features, permissions), `renderable`, `available` (true only when every feature flag the type needs is on) and `accepts_filters`. The assistant checks here before proposing a widget. | `category` (`numbers`, `charts`, `lists`, `static`) | +| `get_widget_data` | Renders one widget with the same request the UI sends — either a widget saved on a dashboard (`dashboard_id` + `widget_id`) or an unsaved one (`widget_type` + `config`) — and returns its `data`, capped by `row_limit` and `series_limit` with a `truncation` note saying what was dropped. Static types (`table`, `favorites`, `section_break`, `markdown`, `quick_actions`) have no data. | `dashboard_id` + `widget_id`, or `widget_type` + `config`; `row_limit`, `series_limit` (1–100, default 25) | +| `diagnose_widget` | Renders the widget as configured and once more with no filters, then reports `applied_filters`, both summaries, `ignored_filter_keys` (filter keys DefectDojo does not recognise for the widget's model — usually a misspelling) and `suggestions`. Only widget types that take filters can be diagnosed. | the same selectors as `get_widget_data` | +| `get_exec_pack_schedules` | Your own executive posture pack e-mail schedules, oldest first: `name`, `enabled`, `cadence`, `weekday`, `day_of_month`, `hour_utc`, `window_days`, `file_format`, `last_run_at`, `last_report_id`. Read-only; schedules are created in the DefectDojo Pro UI and also require the Reporting feature and permission to generate reports. | — | + +A dashboard's `url` is the Dashboards page (`/ui/dashboard-v2`); DefectDojo Pro has no per-dashboard link, so pick the dashboard by name from the page's dropdown. Every render is bounded: a wide widget is trimmed to the caps and the `truncation` field says so, so the assistant reports what it saw rather than guessing at the rest. + +### ✏️ Dashboards Write Tools + +| Tool | What it does in DefectDojo | Key parameters | +|------|----------------------------|----------------| +| `create_dashboard` | Creates a dashboard from 1–50 widgets, each with a catalog `type`, `title`, `config` and `refresh_interval`. An optional `layout` places widgets on the 12-column grid; widgets without an entry are placed two per row below the others. Personal unless `is_shared` is true. DefectDojo validates every widget configuration and answers a 400 with `field_errors` when one is wrong. | `name`, `widgets`, `layout`, `settings`, `is_shared` | +| `update_dashboard` | Changes a dashboard with one update. Whole-document mode replaces exactly the fields you send (`name`, `widgets` together with `layout`, `settings`, `is_shared`). `ops` mode takes 1–25 ordered operations — `add_widget`, `update_widget`, `remove_widget`, `move_widget`, `retitle_widget`, `rename` — which the assistant applies to the current document before saving, so a single widget can be changed without restating the rest. A concurrent edit in the UI between the read and the save is overwritten. | `dashboard_id`, then either the document fields or `ops` | +| `clone_dashboard` | Copies a shared or catalog dashboard into your own, with fresh widget ids and never shared, as `name` or `Copy of `. | `dashboard_id`, `name` | +| `manage_dashboard_sharing` | One action per call: `share` or `unshare` a dashboard, `set_my_default`, `set_shared_default` (the dashboard everyone lands on) or `clear_shared_default`. | `action`, `dashboard_id` | +| `delete_dashboard` | Deletes a dashboard after reading its name, so the answer says which one went (`Deleted dashboard "" (id N)`). DefectDojo refuses the starter template and dashboards you cannot manage. Cannot be undone. | `dashboard_id` | + +Write tools answer with the same `outcome` envelope as the [Asset Hierarchy Toolset](#asset-hierarchy-toolset) (`committed`, `rejected`, `unknown`). A `rejected` outcome carries DefectDojo's `status_code` and `field_errors`, so a misconfigured widget is reported field by field rather than silently dropped. After creating or changing a dashboard, the assistant is told to render every non-static widget once with `get_widget_data` and to report any that answer with a rejection, a disabled feature or a permission error. + +Sharing a dashboard or changing the shared default changes what every user of the instance sees. The workflow guide and the `build_dashboard` prompt only do either when you explicitly ask. + +### Dashboards Resources and Prompts + +- **`mcp://resource/dashboards/widget-schema.json`** (JSON) — every widget type with the configuration keys, allowed values and ranges DefectDojo accepts, plus the rules for the widget envelope, grid positions and dashboard settings. The assistant reads a type's entry before writing its configuration. +- **`mcp://resource/dashboards/workflow-guide.md`** (Markdown) — the working method: discover the catalog, resolve dashboards by name, propose a small layout, confirm, create, render-check every widget, diagnose an empty one, and share only on request. +- **`summarize_dashboard`** prompt — takes an optional `dashboard_name_or_id` (your default dashboard when blank); reads the dashboard, renders up to six of its widgets and summarises what they currently show, within a bounded number of calls. +- **`build_dashboard`** prompt — takes `audience` and `focus`; reads the catalog and the widget schema, learns the instance's Organization/Asset wording, proposes a dashboard of four to eight widgets for that audience with every filter spelled out, creates it after you approve, render-checks each widget (diagnosing and fixing an empty one only after telling you), and hands you the URL. It mentions sharing but never shares unless you ask. + +### Example requests + +- "Which dashboards can I see, and which one is my default?" +- "Summarise my `Executive Overview` dashboard — what are the numbers right now?" +- "Why does the `Open Criticals — Payments` widget show zero? Diagnose it." +- "Build a dashboard for the AppSec team focused on remediation velocity. Propose it first." +- "Add a `Findings by severity` chart filtered to the `Payments` Organization to my `Triage` dashboard, top right." +- "Clone the shared `Security Posture` dashboard so I can edit my own copy." +- "Which posture pack e-mails do I have scheduled?" + +--- + +>>>>>>> Stashed changes ## Reference Resources The `core` toolset publishes 6 read-only JSON resources (MIME type `application/json`). They are reference material bundled with the MCP Server, not data from your DefectDojo instance, and are available without any tool call so an assistant can map findings to a standard or explain a regulatory obligation while it reports. @@ -967,7 +1035,11 @@ The `core` toolset publishes 6 read-only JSON resources (MIME type `application/ Ask your assistant to read a resource by URI (for example, "read `mcp://resource/cwe_to_owasp_2025_mapping.json` and group our open findings by OWASP category") when a report should cite a standard. +<<<<<<< Updated upstream Add-on toolsets publish their own resources alongside these: the `hierarchy` toolset adds `mcp://resource/hierarchy/workflow-guide.md` (see [Asset Hierarchy Toolset](#asset-hierarchy-toolset)) and the `reporting` toolset adds three under `mcp://resource/reporting/` (see [Reporting Toolset](#reporting-toolset)). +======= +Add-on toolsets publish their own resources alongside these: the `hierarchy` toolset adds `mcp://resource/hierarchy/workflow-guide.md` (see [Asset Hierarchy Toolset](#asset-hierarchy-toolset)), the `reporting` toolset adds three under `mcp://resource/reporting/` (see [Reporting Toolset](#reporting-toolset)), and the `dashboards` toolset adds `mcp://resource/dashboards/widget-schema.json` and `mcp://resource/dashboards/workflow-guide.md` (see [Dashboards Toolset](#dashboards-toolset)). +>>>>>>> Stashed changes --- @@ -1008,7 +1080,11 @@ The DefectDojo MCP Server includes pre-configured prompts that demonstrate best > **💡 Using Prompts:** To invoke a prompt, simply ask your AI assistant: "Create a SAST Review Report" or "Generate a Security Landscape Report using DefectDojo data" +<<<<<<< Updated upstream The `hierarchy` toolset adds two more prompts, `explore_hierarchy` and `hierarchy_cleanup_review`, described under [Asset Hierarchy Toolset](#asset-hierarchy-toolset); the `reporting` toolset adds `build_report_template`, `run_report` and `check_report_run`, described under [Reporting Toolset](#reporting-toolset). Unlike the two `core` prompts, most of these take arguments, which your client asks for when you invoke them. +======= +The `hierarchy` toolset adds two more prompts, `explore_hierarchy` and `hierarchy_cleanup_review`, described under [Asset Hierarchy Toolset](#asset-hierarchy-toolset); the `reporting` toolset adds `build_report_template`, `run_report` and `check_report_run`, described under [Reporting Toolset](#reporting-toolset); and the `dashboards` toolset adds `summarize_dashboard` and `build_dashboard`, described under [Dashboards Toolset](#dashboards-toolset). Unlike the two `core` prompts, most of these take arguments, which your client asks for when you invoke them. +>>>>>>> Stashed changes --- @@ -1308,11 +1384,19 @@ Verify these items when experiencing connection issues: #### ❌ "toolset 'hierarchy' is not enabled on this DefectDojo Pro instance" +<<<<<<< Updated upstream **Cause:** The connection URL asks for a toolset whose Feature Flag is off, or the MCP Server itself is disabled. The same message names `reporting` when that toolset's flag is off. **Solutions:** 1. Ask a superuser to open **Settings → Feature Flags**, confirm **MCP Server** is on, and enable the toolset's flag (for `hierarchy`, **MCP: Asset Hierarchy**, which also needs the **Asset Hierarchy** feature; for `reporting`, **MCP: Reporting**, which also needs the **Reporting** feature) +======= +**Cause:** The connection URL asks for a toolset whose Feature Flag is off, or the MCP Server itself is disabled. The same message names `reporting` or `dashboards` when that toolset's flag is off. + +**Solutions:** + +1. Ask a superuser to open **Settings → Feature Flags**, confirm **MCP Server** is on, and enable the toolset's flag (for `hierarchy`, **MCP: Asset Hierarchy**, which also needs the **Asset Hierarchy** feature; for `reporting`, **MCP: Reporting**, which also needs the **Reporting** feature; for `dashboards`, **MCP: Dashboards 2.0**, which also needs the **Dashboards 2.0** feature) +>>>>>>> Stashed changes 2. Or remove the toolset from the `toolsets` parameter and reconnect 3. Ask your assistant to call `get_instance_info` to see which toolsets the instance has enabled diff --git a/docs/content/metrics_reports/dashboards/PRO__custom_dashboards.md b/docs/content/metrics_reports/dashboards/PRO__custom_dashboards.md index aeaec88bd4e..ca958556e34 100644 --- a/docs/content/metrics_reports/dashboards/PRO__custom_dashboards.md +++ b/docs/content/metrics_reports/dashboards/PRO__custom_dashboards.md @@ -216,3 +216,4 @@ Notes, shortcuts, and structure. - **[Automating Dashboards with the API](../custom-dashboards-api/)** — discover the widget catalog, create and update layouts, and render widget data over the REST API, with a complete script. - **[Building Dashboards with an LLM](../custom-dashboards-llm/)** — let an LLM design and build dashboards for you (the dashboards API was built with AI agents in mind). +- **[MCP Server — Dashboards Toolset](../../ai/mcp_server_pro/#dashboards-toolset)** — connect an AI assistant to the MCP Server with `?toolsets=dashboards` to summarise, diagnose, build and share dashboards from the chat, with no script. diff --git a/docs/content/metrics_reports/dashboards/PRO__custom_dashboards_api.md b/docs/content/metrics_reports/dashboards/PRO__custom_dashboards_api.md index d58c40147c8..99991ec3407 100644 --- a/docs/content/metrics_reports/dashboards/PRO__custom_dashboards_api.md +++ b/docs/content/metrics_reports/dashboards/PRO__custom_dashboards_api.md @@ -494,3 +494,4 @@ curl -s -X POST \ - Build and arrange the same layouts interactively in the [Customizable Dashboards UI](../custom-dashboards/). - Let an LLM design and build dashboards for you with the [Dashboards LLM integration](../custom-dashboards-llm/). +- Use the same endpoints through an AI assistant connected to the [MCP Server's Dashboards Toolset](../../ai/mcp_server_pro/#dashboards-toolset). diff --git a/docs/content/metrics_reports/dashboards/PRO__custom_dashboards_llm.md b/docs/content/metrics_reports/dashboards/PRO__custom_dashboards_llm.md index f274f57cb1b..6c75f967a9e 100644 --- a/docs/content/metrics_reports/dashboards/PRO__custom_dashboards_llm.md +++ b/docs/content/metrics_reports/dashboards/PRO__custom_dashboards_llm.md @@ -191,3 +191,4 @@ A well-behaved model will: - See the [Dashboards API guide](../custom-dashboards-api/) for the raw resources, request shapes, and the full widget-data action reference. - Build and arrange dashboards by hand in the [Customizable Dashboards UI](../custom-dashboards/). +- Prefer no script at all? The [MCP Server's Dashboards Toolset](../../ai/mcp_server_pro/#dashboards-toolset) gives an MCP-capable assistant the same discovery, build, render-check and sharing steps as tools, with your API token sent by the client rather than pasted into the chat.