Connection Doctor

DefectDojo connection doctor

This plugin requires DefectDojo Pro. It does not support DefectDojo open source and will refuse to run against it.

Why this skill exists

Connection failures in this integration have five distinct causes that produce similar looking symptoms, and guessing between them wastes the user's time:

1. Nothing is configured yet.
2. The instance is DefectDojo open source, which this plugin does not support.
3. The API token is wrong, revoked, or expired. DefectDojo tokens can expire.
4. The MCP server is disabled on the instance, so REST works but tools are missing.
5. The user's DefectDojo role does not permit the action, so everything works except one call.

Probe in order and stop at the first failure. Do not skip ahead: a missing tool is a symptom of causes 1, 2 and 4 alike, and only the ordered probes separate them.

Procedure

Step 1: Establish what is configured

dd-api config

This prints the instance URL and where the credential came from. It never prints the token. If it exits 3, nothing is configured: go to Step 6.

Step 2: Verify credentials and edition together

dd-api whoami

Interpret the exit code. Do not interpret the text of an error you have not read.

Step 3: Check the MCP server itself

REST working does not mean the MCP tools are available. They are separately gated on the instance.

Check whether MCP tools are present in this session. The DefectDojo tools are named mcp__defectdojo__*, for example mcp__defectdojo__get_products. Try one small call, such as get_products with limit 1.

If REST succeeded but the MCP tools are missing or erroring:

• The MCP server may be disabled on the instance. A DefectDojo administrator enables it under the AI settings in the Pro UI. It is a live toggle and needs no restart. Self-hosted deployments also need MCP_ENABLED set at deploy time.
• The session may predate the configuration. MCP servers connect at session start, so tell the user to start a new session after any credential change.
• Report dd-api feature-flags output only if the user is debugging a specific feature, not as routine noise.

Step 4: Edition failures

Exit code 5 means the Pro-only API surface is absent. State plainly that the plugin requires DefectDojo Pro and does not work with DefectDojo open source. Do not offer a workaround, a reduced mode, or a way to bypass the check. There is none by design.

Before concluding, confirm two things that produce the same symptom:

• The URL points at the DefectDojo application root, with no trailing path and no /api/v2 suffix. https://example.cloud.defectdojo.com is right, https://example.cloud.defectdojo.com/api/v2/ is not.
• A proxy or SSO gateway is not intercepting the request and returning its own
  404. If the user can load the DefectDojo UI in a browser but the probe 404s, suspect the gateway.

If the user wants Pro, point them at a two-week SaaS trial at defectdojo.com.

Step 5: Token failures

Exit code 4 covers two different problems. Read the message.

• 401 rejected: the token is wrong, revoked, or expired. DefectDojo tokens can expire, and the failure appears mid-session with no warning. The user generates a fresh API v2 key from their DefectDojo user profile, then updates it through /plugin by configuring defectdojo-connect, then starts a new session. Never retry the same token, and never suggest pasting the token into the chat.
• 403 forbidden: the token is valid but the user's role does not allow that operation on that object. Name the object and the operation, and say which role level is needed. Suggest performing it as a user who has the role rather than escalating the token.

Step 6: First-time setup

Tell the user exactly this sequence:

1. In DefectDojo, open your user profile and create an API v2 key.
2. In Claude Code, run /plugin, choose defectdojo-connect, and configure it. Enter the instance URL, for example https://yourcompany.cloud.defectdojo.com, with no trailing slash and no path. Paste the API key when prompted. It is stored in the operating system keychain.
3. Start a new session so the MCP server connects and the credentials load.
4. Run this doctor again to confirm.

For CI or for users who will not keep a credential on disk, both values can come from the environment instead: DD_BASE_URL and DD_API_TOKEN.

Rules

• Never ask the user to paste their API token into the conversation, and never echo one if they do. If a token appears in the transcript, tell them to revoke it and issue a new one.
• Never suggest editing ~/.defectdojo/claude-code.json by hand. It is written from plugin settings at session start and hand edits are overwritten.
• Never propose bypassing the Pro edition check.
• Report what each probe actually returned. Do not assert that something is fixed until a probe confirms it.

Reference

references/troubleshooting.md covers proxies, self-hosted nginx, self-signed certificates, and the difference between the deploy-time and runtime MCP toggles. Read it when the fast path above does not resolve the failure.