DefectDojo Intelligence MCP Server

Ein rechteerhaltender Model Context Protocol-Server auf Basis der REST-API v2 von DefectDojo OSS v2.58.4. Er erreicht 1:1-Funktionsparität mit dem offiziellen, in DefectDojo Pro integrierten MCP-Server (12 Lese-Tools + ein Security-Landscape-Prompt) und ergänzt ein deterministisches Analytics-/Reporting-Superset — umgesetzt als externer Adapter, da der integrierte Pro-MCP die Pro-Edition sowie Instanz-Version v2.51.2+ voraussetzt und auf einem OSS-2.58.4-Host nicht verfügbar ist.

Jeder Aufruf verwendet den eigenen DefectDojo-API-Token des Aufrufers, sodass DefectDojo über die Sichtbarkeit entscheidet. Der Token wird nur im Speicher gehalten, nie protokolliert und nie an das LLM gesendet.

• Status: Phasen 0–4 abgeschlossen, gehärtet und dockerisiert. 140 Tests, ruff-sauber.

• Bereitstellung: siehe deploy/DEPLOY.md für das dockerisierte Setup unter https://dojo.example.com/mcp/. Hinweis: Dieses Deployment aktiviert die Schreib- und DB-History-Toolgrupen (siehe Sicherhesmodell und DEPLOY.md). Spezifikation: PRD.md.

Tools

26 Tools — 20 standardmäßig aktviert (14 Lese + 6 Analytik/Berichte), 6 standardmäßig deaktviert. Plus 1 MCP-Prompt-rimitiv.

Die Analytik-Tools berechnen deterministisch serverseitig (kein LLM, keine erfundenen Daten — jede Kennzahl geht auf eine Findings-API-Abfrage zurück) und liefern typisierte, strukturierte Ausgaben. SLA nutzt DefectDojos eigenen outside_of_sla-Filter; die Priorisierung verwendet echte KEV/EPSS/SLA-Signale.

Related MCP server: mcp-vulbox-agent

Funktionsparität mit Pro

Security-Modell

• Token: Authorization: Token <token> (nicht Bearer). HTTP liest ihn pro Anfrage aus dem eingehenden Header (dem eigenen Token des Aufrufers); std test liest DD_API_TOKEN. Bei streamable-http ist der Environmentab-Fallback deaktiviert — eine how: Anfrage ohne oder mit fehlerhaftem Authorization-Header wird abgelehnt und niemals stillschweigend mit dem Env-Token des Servers ausgeführt.

• Token-Isolation beim gepoolten Betrieb: Der gemeinsame Verbindungspool verwendet einen No-Store-Cookie-Jar, sodass ein upstream Set-Cookie niemals über Tokens verschiedener Aufrufer hinweg wiederverspielt wird. Die Authentifizierung ist only per-request.

• Validierung: Der Token wird nur einmal pro TTL validiert (Cache per 128-Bit-Fingerprint, niemals der Token; Cache begrenzt) validiert.

• Redaktion: Wird zentral für jede Tool-Ausgabe angewendet, wenn redact_secrets/treat_finding_text_as_untrusted gesetzt ist — Geheimnisse werden entfernt (einschließlich URL- eingebetteter Anmeldedaten), PII entfernt bei omit_user_pii, Freitext gekürzt auf max_evidence_chars.

• Fehler: Fehlschläge (401/403/404/Timeout/…) erscheinen als MCP-Tool-Fehler (isError), nicht als Erfolgs-Payloads — der Client kann eine Ablehnung nicht mit Daten verwechseln.

• Schreibzugriffe: standardmäßig aus; wenn aktiviert, verlangt jeder physik eine nicht-leere Reason + explizites confirm=true (sonst ein No-Pro. -op-Preview) plus Vorher-/Nachher-State-Hash-Audit. Nur API — nie direkte DB-Schreibung.

• DB-Verlauf: standardmäßig aus; jedes Tool autorisiert das Objekt per REST zuerst, dann liest es eine Allowlist-Lese-Viewliste (nie willkürliches SQL).

• Transport: streamable-http erhält explizite TransportSecuritySettings (DNS-Rebinding-/Origin-Schutz) aus mcp.allowed_hosts/allowed_origins; Loopback ist für Healthchecks immer erlaubt.

• Veraltete Endpunkte (credentials, credential_mappings, stub_findings) sind blockiert; eine disallowed-tool-Allowlist wir bei der Registrierung geprüft.

• Audit: ein strukturiertes JSON-Event pro Tool-Aufruf an stderr (stdout ist der MCP-Stream).

Härtung

Begrenztes Retry/Backoff für transient-al GET-Fehler (429/502/503/504/timeout; beachtet Retry-After inkl. HTTP-date-Form; niemals Writes oder 4xx wiederholt) · processübergreifendes Semaphore · shared gepoolter httpx-Client (per-request-Auth, geschlossen beim Lifecycle) · rollen- TTL-Cache per Token. Siehe tests/test_hardening.py.

Produktionsbereitstellung (dockerisiert, /mcp/)

Vollständige Anleitung: deploy/DEPLOY.md. Kurzgefasst:

cd deploy
# Optional: set DOJO_NETWORK / DD_URL / DD_MCP_REPORTING_DB_DSN in a deploy/.env
# (docker compose reads ${...} env defaults; there is no committed .env template —
#  config lives in deploy/config.prod.yaml, bind-mounted at /app/config.yaml).
docker compose up -d --build
curl -s http://127.0.0.1:9900/healthz   # -> {"status":"ok","transport":"streamable-http"}

Dann fügen Sie den Block location ~ ^/(mcp|sse|messages) aus deploy/nginx-mcp.conf in die Host-Nginx ein und laden neu. Clients verbinden sich mit eigenem Authorization: Token <token> über mcp-remote zu https://dojo.example.com/mcp/. Der Container bindet innerhalb 0.0.0.0:9000 und macht ihn auf dem Host nur als 127.0.0.1:9900 verfügbar; DefectDojo wird intern über http://nginx:8080 erreicht. Die Prod-Konfiguration aktiviert die Schreib- und DB-History-Toolgruppen (enable_write_tools / enable_db_tools); Schreibzugriffe bleiben bestätigungspflichtig, und die DB-Tools autorisieren über die Rest-API zuerst — siehe DEPLOY.md.

Lokale Entwicklung

Phase 0 — Zuerst überprüfen: das Live-Schema

DD_URL=https://dojo.internal DD_API_TOKEN=xxxx ./scripts/check_schema.sh

Bestätigt, dass die benötigten Collection-Endpunkte existieren, und markiert veraltete. Die DRF-Filter-Lookups in src/defectdojo_mcp/tools/* sind gegen die DefectDojo-2.58.4-Quelle verifiziert — hier gegen Ihr Live-Schema erneut bestätigen.

Installation & Ausführen

pip install -e ".[dev]"
cp config.example.yaml config.yaml          # edit base_url
# stdio reads the token from the DD_API_TOKEN env var (and DD_URL) directly — no .env file.

# stdio (single user / desktop client)
DD_URL=https://dojo.internal DD_API_TOKEN=xxxx DD_MCP_CONFIG=config.yaml defectdojo-mcp

# streamable-http (multi-user; token per-request). Set mcp.allowed_hosts for a 0.0.0.0 bind.
DD_MCP_TRANSPORT=streamable-http DD_MCP_HOST=0.0.0.0 DD_MCP_PORT=9000 defectdojo-mcp
# endpoint: http://<host>:9000/mcp   health: http://<host>:9000/healthz

Claude Desktop (stdio)

{
  "mcpServers": {
    "defectdojo": {
      "command": "defectdojo-mcp",
      "env": {
        "DD_URL": "https://dojo.internal",
        "DD_API_TOKEN": "your-token",
        "DD_MCP_CONFIG": "/path/to/config.yaml"
      }
    }
  }
}

Testen

pytest          # 140 tests: redaction/sanitize, params, paging, auth+validator, context,
                # server gating, intelligence scoring, source resolution, writes, history,
                # hardening (retry/pool/semaphore/cache)
ruff check .

Konfiguration

Wichtige Schrauben in config.yaml (siehe config.example.yaml / deploy/config.prod.yaml):

• mcp.transport (stdio | streamable-http), mcp.host/mcp.port

• mcp.enable_write_tools, mcp.enable_db_tools — steuern die standardmäßig ausgeschalteten Gruppen

• mcp.enable_dns_rebinding_protection, mcp.allowed_hosts, mcp.allowed_origins

• security.redact_secrets, security.omit_user_pii, security.require_confirmation_for_writes

• limits.max_concurrent_api_calls, limits.max_retries, limits.max_evidence_chars, limits.roles_cache_ttl_seconds

• database.enabled, database.dsn_env, database.allowed_views (Phase 3 Reporting-DB)

Findbarkeit & Erweiterbarkeit

Jedes Tool trägt ToolAnnotations (readOnlyHint/idempotentHint/title; Schreibzugriffe sind nicht read-only); Enum-Parameter veröffentlichen Enums; Listen-Tools deklarieren ein typisiertes Page-Ausgabeschema; eorskutes veröffentlicht instructions; das Prompt hat Titel und dokumentierte Argumente. Tools registrieren sich über ein (module, predicate)-Register in server.py (ein Gate für optionale Gruppen); ServerContext.execute() / execute_db_gated() / execute_write() sind die Nadelöre für Token‑Validierung, die zentrale Egress‑Transformation, das Audit und das Fehler‑Mapping.

Lizenz

Nur GNU Affero General Public License v3.0 (AGPL-3.0-only). Vollständiger Text in LICENSE.

Copyright (C) 2026 Zeeshan Sultan.

Sicherheit

Bitte melden Sie Sicherheitsprobleme privat — siehe SECURITY.md. Eröffnen Sie für ein Sicherheitsproblem kein öffentliches Issue.

Verwandtes

Parallel zu ShadowDSO entstanden, einer Out-of-Band-Sicherheits-Scanning-Plattform, die DefectDojo als System of Record verwendet. Dieser Server ist eigenständig und unabhängig davon.