From d42dc4aa87e95c21dd55d37e6b86c7c00d0ff249 Mon Sep 17 00:00:00 2001 From: devGregA Date: Sun, 16 Aug 2026 11:45:57 -0600 Subject: [PATCH 1/2] docs(ai): add the Claude Code plugin page and correct the MCP tool count Two gaps on the AI docs. The MCP Server page said the server provides 12 tools. It provides 14: the reference was missing finding_summary and risk_summary, both of which have been in the server for some time. Counting the documented blocks now gives 14 and matches the tool registrations. The two new entries follow the existing format and note when a summary call is preferable to paging through findings. There was also no Claude Code guidance anywhere in the docs. The only configuration example was the Claude Desktop config file, which is the wrong shape for Claude Code users, so they were left to work it out. The new page covers the two-command install, prerequisites, what each plugin does, how the MCP and REST channels are wired, CI usage with a service account, and a troubleshooting table. The pages cross-link both ways: the MCP page now points Claude Code users at the plugin rather than the hand-rolled config, and the plugin page points back for administrator setup and for chat assistants such as Claude Desktop. Both pages are audience: pro. The plugin requires DefectDojo Pro and the page states that it refuses to run against open source rather than partially working. Co-Authored-By: Claude Fable 5 --- .../metrics_reports/ai/claude_code_plugin.md | 148 ++++++++++++++++++ .../metrics_reports/ai/mcp_server_pro.md | 66 +++++++- 2 files changed, 213 insertions(+), 1 deletion(-) create mode 100644 docs/content/metrics_reports/ai/claude_code_plugin.md diff --git a/docs/content/metrics_reports/ai/claude_code_plugin.md b/docs/content/metrics_reports/ai/claude_code_plugin.md new file mode 100644 index 00000000000..0f35aa7ed2e --- /dev/null +++ b/docs/content/metrics_reports/ai/claude_code_plugin.md @@ -0,0 +1,148 @@ +--- +title: "Claude Code Plugin" +description: "Query, triage, import and report on DefectDojo Pro data from Claude Code" +draft: false +audience: pro +weight: 24 +--- + +Note: AI features are a DefectDojo Pro-only feature. + +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. + +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 +specifically for Claude Code, the command-line coding agent. + +## Install + +``` +/plugin marketplace add DefectDojo/agent-skills +/plugin install defectdojo@defectdojo +``` + +When you enable the plugin it asks for two things: + +- **Instance URL**, for example `https://yourcompany.cloud.defectdojo.com`, with + no trailing slash and no path. +- **API v2 key**, which you create from your user profile in DefectDojo. + +The key is stored in your operating system keychain. Start a new session +afterwards so the MCP server connects. + +Then ask for something: + +> What are the top 10 findings we should fix first? + +## Prerequisites + +- DefectDojo Pro v2.51.2 or later, with the MCP server enabled. See + [MCP Server](../mcp_server_pro/) for how an administrator turns it on. +- Claude Code 2.1.143 or later, so that installing the umbrella plugin enables + its components automatically. +- macOS or Linux, including WSL. Native Windows is not supported yet. + +The plugin requires DefectDojo Pro and refuses to run against DefectDojo open +source. It verifies the edition on first contact and stops with an explanatory +message rather than partially working. + +## What you can ask for + +Installing `defectdojo` installs the full set. You can also install any single +plugin; each one pulls in the connection plugin automatically. + +| Plugin | Skills | Ask it for | +| --- | --- | --- | +| `defectdojo-connect` | `connection-doctor` | "Is DefectDojo connected?", or any 401, 403 or missing-tool problem | +| `defectdojo-triage` | `findings-query`, `triage-findings` | "How many criticals are open?", "Mark these false positive", "Give me a brief" | +| `defectdojo-import` | `import-scans`, `wire-ci-import` | "Get this Semgrep output into Dojo", "Push our scans from CI" | +| `defectdojo-report` | `security-report` | "Build the quarterly report for the board" | + +### Asking questions + +Questions are answered from your live data, and counts always state what they +counted: + +> How many critical findings are open in the payments app? +> +> What changed this week? +> +> Which products have the worst backlog? + +For anything phrased as "top", "worst" or "what should we fix first", the plugin +ranks by DefectDojo's own priority, which weighs exploitability, threat +intelligence, reachability, business context and many more signals, rather than +by severity alone. + +### Triaging findings + +The triage skill changes finding state: close, verify, mark false positive, mark +out of scope, risk accept, add notes and tags, and merge duplicates. + +It always shows you a table of proposed changes and waits for you to confirm +before writing anything, and it records a note on every change so the reason +survives for the next person who looks. + +### Importing scans + +> Get this semgrep.json into Dojo under the payments product. + +The import skill identifies the scan type, chooses import or reimport correctly, +creates the product and engagement if you ask it to, and waits for background +processing to finish before reporting results. It can also add scan upload to +your CI pipeline, using a service account rather than a personal token. + +## How it connects + +You enter credentials once, and two channels derive from that single entry. + +**MCP** connects Claude Code to the MCP server built into your instance at +`https://your-instance/mcp`. That provides the read tools, which appear as +`mcp__defectdojo__*`. + +**REST** covers everything the read tools do not: status changes, notes, imports +and reporting. The plugin bundles a single command that handles the auth header, +error translation and background-import polling. + +Your token is never shown to the model, and never appears on a command line. +Every action runs as you, under your existing DefectDojo permissions: the plugin +cannot do anything in DefectDojo that you cannot do yourself. + +### Using it in CI + +Rather than configuring the plugin, set two environment variables: + +``` +DD_BASE_URL=https://your-instance.example.com +DD_API_TOKEN= +``` + +Use a dedicated service account rather than a personal token. Personal tokens +expire and carry one person's permissions, which is the usual reason a pipeline +that worked for months suddenly stops. + +## Troubleshooting + +Ask the plugin first: + +> Is my DefectDojo connection working? + +The connection doctor probes each layer in order and tells you which one failed +and what to do about it. The most common causes: + +| Symptom | Cause | +| --- | --- | +| Tools missing, but other calls work | The MCP server is disabled on the instance, or the session started before you configured the plugin. Start a new session. | +| Everything returns 401 | The API token expired. DefectDojo tokens can expire. Create a new one, update it through `/plugin`, and start a new session. | +| One operation returns 403 | Your DefectDojo role does not permit that action on that object. | +| The plugin says the instance is not Pro | The URL includes a path, a proxy is returning its own 404, or the instance is DefectDojo open source, which is not supported. | + +## Source and support + +The plugin is open source at +[github.com/DefectDojo/agent-skills](https://github.com/DefectDojo/agent-skills). +Report problems as issues there. diff --git a/docs/content/metrics_reports/ai/mcp_server_pro.md b/docs/content/metrics_reports/ai/mcp_server_pro.md index bb036f246f9..a0dd73b9f22 100644 --- a/docs/content/metrics_reports/ai/mcp_server_pro.md +++ b/docs/content/metrics_reports/ai/mcp_server_pro.md @@ -72,6 +72,11 @@ All methods use these core parameters: ## Quick Start Guides by AI Provider +> **💡 Using Claude Code?** Do not configure it by hand. The +> [Claude Code Plugin](../claude_code_plugin/) wires up this MCP server for you +> in two commands, and adds the write operations these read-only tools do not +> cover, such as changing finding status and importing scans. +

🖥️ Claude Desktop (Method 1: Configuration File)

 @@ -302,7 +307,7 @@ Once connected, you can explore: ## Available Tools Reference -The DefectDojo MCP Server provides 12 tools for accessing and analyzing vulnerability data. Each tool includes intelligent parameter handling and returns structured data optimized for LLM analysis. +The DefectDojo MCP Server provides 14 tools for accessing and analyzing vulnerability data. Each tool includes intelligent parameter handling and returns structured data optimized for LLM analysis. > **💡 Parameter Note:** All tools accept an optional `token` parameter. If not provided in individual calls, the LLM will use the token from the connection configuration. @@ -384,6 +389,65 @@ get_findings({
+
+

finding_summary

 + +**Description:** Retrieve aggregate finding metrics in a single call, rather than fetching findings and counting them. Returns counts by severity, average priority and risk score, average finding age, and the most common CWEs. + +**Parameters:** + +**product_id** (Optional) +- **Type:** Number +- **Minimum:** 1 +- **Usage:** Scope the summary to a single product. + +**engagement_id** (Optional) +- **Type:** Number +- **Minimum:** 1 +- **Usage:** Scope the summary to a single engagement. + +**date** (Optional) +- **Type:** Array with single string value +- **Values:** `0 - Any date`, `1 - Today`, `2 - Past 7 days`, `3 - Past 30 days`, `4 - Past 90 days`, `5 - Current month`, `6 - Current year`, `7 - Past year` +- **Example:** `["3 - Past 30 days"]` +- **Usage:** Restrict the summary to findings discovered in the period. + +> **💡 Best Practice:** Use this instead of `get_findings` whenever the question is "how many" or "what is the spread". One summary call replaces paging through findings and counting them, and the counts stay correct beyond the 100-record page limit. + +**Example Query:** + +**User asks:** "Give me a severity breakdown for the payments product over the last quarter" + +**LLM calls:** +``` +finding_summary({ + product_id: 42, + date: ["4 - Past 90 days"] +}) +``` + +
+ +
+

risk_summary

 + +**Description:** Retrieve the aggregate risk posture for a single product, including average priority, risk score, active finding counts, and business criticality. + +**Parameters:** + +**product_id** (Required) +- **Type:** Number +- **Minimum:** 1 +- **Usage:** The product to summarize. + +**Example Query:** + +**User asks:** "How risky is the payments API right now?" + +**LLM calls:** `risk_summary({ product_id: 42 })` + +
+ --- ### 📦 Product & Engagement Tools From 4b8e2db41b30e15ecc6b6a82fe90f6bffd53a0b4 Mon Sep 17 00:00:00 2001 From: devGregA Date: Mon, 17 Aug 2026 14:42:46 -0600 Subject: [PATCH 2/2] docs(ai): correct the plugin's licensing description The page called the plugin open source. It is source-available: the source is published for inspection, but modification and redistribution are not permitted, and it may only be used against DefectDojo Pro. Says so plainly, gives the reason the source is published at all, and notes that Community Edition is separate and remains open source, so a reader does not infer a change in that direction. Co-Authored-By: Claude Fable 5 --- .../metrics_reports/ai/claude_code_plugin.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/content/metrics_reports/ai/claude_code_plugin.md b/docs/content/metrics_reports/ai/claude_code_plugin.md index 0f35aa7ed2e..bd21725556d 100644 --- a/docs/content/metrics_reports/ai/claude_code_plugin.md +++ b/docs/content/metrics_reports/ai/claude_code_plugin.md @@ -143,6 +143,13 @@ and what to do about it. The most common causes: ## Source and support -The plugin is open source at -[github.com/DefectDojo/agent-skills](https://github.com/DefectDojo/agent-skills). -Report problems as issues there. +The source is published at +[github.com/DefectDojo/agent-skills](https://github.com/DefectDojo/agent-skills) +so you can read exactly what runs against your vulnerability data before you run +it. Report problems as issues there. + +The plugin is source-available rather than open source: you may install it, use +it with a DefectDojo Pro instance, and review the source, but not modify or +redistribute it. See the licence in the repository for the exact terms. +DefectDojo Community Edition is separate and remains open source under its own +licence.