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..bd21725556d --- /dev/null +++ b/docs/content/metrics_reports/ai/claude_code_plugin.md @@ -0,0 +1,155 @@ +--- +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 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. 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