MCP Server (Pro)

Nota: os recursos de IA são exclusivos do DefectDojo Pro.

O Servidor DefectDojo Model Context Protocol (MCP) permite que Large Language Models (LLMs) interajam de forma inteligente com os dados de gerenciamento de vulnerabilidades do DefectDojo. Diferente das integrações de API tradicionais, que apenas transferem dados, o servidor MCP fornece contexto estruturado e significado semântico que permite aos assistentes de IA realizar análises de segurança sofisticadas e gerar insights acionáveis.

• Contexto Estruturado: o MCP fornece significado semântico aos dados do DefectDojo, não apenas a transferência bruta de dados
• Dados Pré-Processados: os dados normalizados e deduplicados do DefectDojo eliminam o ônus de pré-processamento do LLM
• Integração com Inteligência de Negócios: combina dados técnicos de vulnerabilidades com contexto de negócio
• Análise Pronta para Executivos: gera relatórios adequados desde equipes técnicas até a liderança executiva
• Valor Composto 10X: a análise aprimorada por IA fornece exponencialmente mais valor do que consultas manuais

🔑 Importante: o endpoint do servidor MCP está em /mcp, mas todas as chamadas de função usam a URL base do DefectDojo. Essa separação garante acesso seguro e estruturado aos dados de vulnerabilidades.

Conectar ao MCP#

Pré-requisitos#

• Instância do DefectDojo com o Servidor MCP habilitado (v2.51.2 ou posterior)
• Token de API válido do DefectDojo com as permissões apropriadas
• Provedor de IA: Claude, ChatGPT, Gemini ou cliente MCP personalizado compatível

⚠️ Aviso de Segurança: seu token de API é uma informação altamente sensível usada para autenticação e autorização. NÃO EXIBA O TOKEN EM NENHUMA SOLICITAÇÃO OU RESPOSTA ao compartilhar configurações ou capturas de tela.

Métodos de Conexão#

Existem duas formas diferentes de se conectar ao servidor MCP do DefectDojo, dependendo de qual interface de IA você está usando:

Método 1: Método do Arquivo de Configuração#

Usado por: Claude Desktop, MCP Inspector e outros clientes MCP de desktop

Como funciona:

• O token e os detalhes de conexão são armazenados em um arquivo de configuração
• A conexão é automática quando você inicia a aplicação
• Não é necessário colar instruções nas conversas
• O servidor MCP está sempre disponível em todas as conversas

Vantagens: configure uma vez, funciona em todo lugar. Mais seguro (o token não fica no histórico de chat).

Método 2: Método de Prompt Manual#

Usado por: interface web do Claude.ai, interface web do ChatGPT (com plugins), interface web do Gemini

Como funciona:

• Você copia/cola as instruções de conexão no início de cada conversa
• Ou adiciona as instruções a um Claude Project para inclusão automática
• A IA lê as instruções e se conecta ao servidor MCP
• Cada nova conversa exige as instruções

Vantagens: funciona em navegadores web sem instalar software.

💡 Qual método devo usar? Use o Método 1 (Arquivo de Configuração) se você tiver um aplicativo de desktop que o suporte. Use o Método 2 (Prompt Manual) se estiver usando uma interface de navegador web.

Detalhes de Conexão do Servidor MCP#

Todos os métodos usam estes parâmetros principais:

Guias de Início Rápido por Provedor de IA#

{
  "mcpServers": {
    "DefectDojo-MCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-instance.defectdojo.com/mcp",
        "--header",
        "Authorization: Token YOUR_API_TOKEN"
      ]
    }
  }
}

For this project, use the DefectDojo MCP server with these parameters in ALL function calls:

- **URL:** https://your-instance.defectdojo.com/ (base URL, NOT the /mcp endpoint)
- **Token:** YOUR_API_TOKEN
- **IMPORTANT:** DO NOT SHOW THE TOKEN IN ANY REQUESTS OR RESPONSES

The MCP server connects to https://your-instance.defectdojo.com/mcp but function calls must use the base URL.

**Do not show any of the API requests or responses.**

For this project, use the DefectDojo MCP server with these parameters in ALL function calls:

- **URL:** https://your-instance.defectdojo.com/
- **Token:** YOUR_API_TOKEN
- **IMPORTANT:** DO NOT SHOW THE TOKEN IN ANY REQUESTS OR RESPONSES

The MCP server connects to https://your-instance.defectdojo.com/mcp but function calls must use the base URL.

Do not show any of the API requests or responses.

I need you to connect to a DefectDojo MCP server with these details:

MCP Endpoint: https://your-instance.defectdojo.com/mcp
Base URL for API calls: https://your-instance.defectdojo.com/
Authentication: Authorization header with value "Token YOUR_API_TOKEN"

Use this connection to access DefectDojo vulnerability data. The server provides tools for:
- Getting findings with severity, status, and date filters
- Accessing products, engagements, tests
- User and group management
- Analyzing security trends

Do not show the API token in responses.

Connect to DefectDojo vulnerability management system via MCP server:

MCP Server: https://your-instance.defectdojo.com/mcp
API Base URL: https://your-instance.defectdojo.com/
Authentication: Token YOUR_API_TOKEN (use Authorization header with "Token" prefix)

Available capabilities:
- Query findings by severity (Critical, High, Medium, Low, Info)
- Filter by status (Active, Verified, False Positive, etc.)
- Filter by date ranges (Today, Past 7/30/90 days, etc.)
- Access products, engagements, tests, users, groups
- Generate security analysis and reports

Important: Do not display the authentication token in responses.

# macOS (using Homebrew)
brew install mcp-inspector

# Or using npm (all platforms)
npm install -g @modelcontextprotocol/inspector

mcp-inspector

✅ Conexão bem-sucedida? Uma vez conectado por qualquer método, teste perguntando ao seu assistente de IA: "Quantos achados ativos temos no DefectDojo?"

Referência de Ferramentas Disponíveis#

O Servidor MCP do DefectDojo fornece 12 ferramentas para acessar e analisar dados de vulnerabilidades. Cada ferramenta inclui tratamento inteligente de parâmetros e retorna dados estruturados otimizados para análise por LLM.

💡 Nota sobre Parâmetro: todas as ferramentas aceitam um parâmetro token opcional. Se não for fornecido em chamadas individuais, o LLM usará o token da configuração de conexão.

🔍 Ferramentas de Análise de Achados#

get_findings({
  severity: ["Critical", "High"],
  status: ["Active"],
  date: ["3 - Past 30 days"],
  limit: 100
})

📦 Ferramentas de Produto e Engajamento#

👥 Ferramentas de Gerenciamento de Usuários e Acesso#

Prompts Pré-Configurados#

O Servidor MCP do DefectDojo inclui prompts pré-configurados que demonstram boas práticas para cenários comuns de análise. Esses prompts podem ser invocados diretamente pelo seu assistente de IA.

🛡️ Relatório de Revisão SAST#

Propósito: criar um relatório abrangente avaliando a eficácia das ferramentas de SAST (Static Application Security Testing) com base nos dados do DefectDojo.

A Análise Gerada Inclui:

• Taxas de falso positivo por ferramenta e tipo de vulnerabilidade
• Tempo médio até a remediação por nível de severidade
• Vulnerabilidades críticas que aparecem múltiplas vezes (lacunas de deduplicação)
• Comparação de desempenho entre equipes de desenvolvimento
• Recomendações para melhorias na configuração das ferramentas
• Lacunas de treinamento identificadas a partir de padrões recorrentes de vulnerabilidade
• Análise de custo da abordagem de ferramentas atual vs. recomendada

Formato de Saída: relatório de avaliação técnica em HTML, adequado para justificar solicitações de orçamento de ferramentas de segurança.

📊 Relatório de Panorama de Segurança#

Propósito: criar um relatório em estilo painel fornecendo uma visão geral do panorama de segurança com base nos dados do DefectDojo, adequado para reuniões trimestrais do conselho.

A Análise Gerada Inclui:

• Tendências de vulnerabilidade nos últimos 90 dias
• Equipes de desenvolvimento com os achados de severidade crítica/alta mais elevados
• Exposição a risco por produto e tipo de produto
• Top 5 categorias de CWE que exigem atenção imediata
• Ações de remediação específicas com análise de custo-benefício
• Roteiro de 6 meses para melhorar a postura de segurança

Formato de Saída: relatório em HTML de nível executivo com elementos visuais, cartões de estatísticas e foco em risco de negócio.

💡 Usando Prompts: para invocar um prompt, basta perguntar ao seu assistente de IA: “Create a SAST Review Report” ou “Generate a Security Landscape Report using DefectDojo data”

Exemplos de Casos de Uso#

Caso de Uso 1: Painel Executivo de Segurança#

Cenário: o CISO precisa de métricas trimestrais de segurança para uma apresentação ao conselho

Prompt do Usuário:

"Create an executive security dashboard for our Q4 board meeting showing:
- Total vulnerability counts by severity
- Trends over the past 90 days  
- Which products have the highest risk exposure
- Top 5 vulnerability categories needing attention
- Specific remediation recommendations with ROI
- A 6-month roadmap for improving our security posture"

O que acontece nos bastidores:

1. get_findings - obtém as contagens totais de achados ativos
2. get_findings - análise de severidade Crítica e Alta
3. get_findings - dados de tendência dos últimos 90 dias
4. get_products - distribuição de vulnerabilidades por produto
5. get_engagements - atividades de teste recentes

Saída Gerada: relatório em HTML de nível executivo com tendências de vulnerabilidade, exposição a risco por produto, principais categorias de CWE, ações de remediação específicas com ROI e roteiro de segurança de 6 meses.

Caso de Uso 2: Análise de Desempenho das Equipes de Desenvolvimento#

Cenário: um gerente de engenharia quer entender quais equipes precisam de treinamento adicional em segurança

Prompt do Usuário:

"Which development teams have the most security findings? What types of vulnerabilities 
are they creating repeatedly? Based on this analysis, recommend specific security 
training programs for each team."

O que acontece nos bastidores:

1. get_findings - todos os achados ativos
2. get_products - vincula achados a produtos/equipes
3. get_groups - estrutura organizacional das equipes
4. get_users - responsabilidade individual dos desenvolvedores

Análise Entregue: achados agrupados por equipe, análise de padrões de CWE mostrando erros repetidos, identificação de lacunas de treinamento e recomendações de programas de treinamento de segurança direcionados.

Caso de Uso 3: Avaliação da Eficácia das Ferramentas#

Cenário: a equipe de segurança está avaliando o ROI das ferramentas de SAST atuais

Prompt do Usuário:

"Analyze the effectiveness of our SAST tools. Show me false positive rates, 
mean time to remediation, which tools find the most valuable vulnerabilities, 
and recommend configuration improvements or alternative tools."

O que acontece nos bastidores:

1. get_tests - todos os testes de segurança por ferramenta
2. get_findings - análise de falsos positivos
3. get_findings - achados ativos por ferramenta
4. get_findings - achados fechados para padrões de remediação

Análise Entregue: taxas de falso positivo por ferramenta, tempo médio até a remediação por severidade, análise de achados duplicados, recomendações de configuração de ferramentas, lacunas de treinamento e análise de custo-benefício de abordagens alternativas de ferramentas.

Caso de Uso 4: Relatório de Conformidade#

Cenário: preparação para uma auditoria SOC 2 que exige evidências de gerenciamento de vulnerabilidades

Prompt do Usuário:

"Generate a SOC 2 compliance report showing our vulnerability management processes, 
including discovery and remediation procedures, SLA compliance, continuous monitoring 
evidence, and accountability documentation."

O que acontece nos bastidores:

1. get_findings - achados ativos Críticos/Altos
2. get_findings - tendências de descoberta desde o início do ano
3. get_engagements - frequência e cobertura de testes
4. get_users - responsabilidade pela remediação

Análise Entregue: processos de descoberta e remediação de vulnerabilidades, rastreamento de conformidade com SLA, evidências de monitoramento contínuo, documentação de responsabilidade e lacunas que exigem remediação antes da auditoria.

Caso de Uso 5: Priorização de Risco#

Cenário: a equipe de segurança tem recursos limitados e precisa priorizar os esforços de remediação

Prompt do Usuário:

"What are the highest priority vulnerabilities we should fix first? Consider severity, 
how long they've been open, exploitability, and business impact. Give me a prioritized 
remediation roadmap with effort estimates."

O que acontece nos bastidores:

1. get_findings - achados ativos Críticos/Altos
2. get_products - contexto de criticidade de negócio
3. Análise de métricas de idade (dias desde a descoberta)
4. Referência cruzada com pontuações EPSS (previsão de exploração)

Análise Entregue: lista de vulnerabilidades classificadas por risco combinando severidade, idade, explorabilidade e impacto de negócio. Roteiro de remediação específico com estimativas de esforço e redução de risco esperada.

Boas Práticas e Padrões de Consulta#

Estratégia de Carregamento Progressivo de Dados#

Seu assistente de IA otimiza o desempenho seguindo automaticamente estes padrões de carregamento de dados:

1. Comece com Dados Resumidos

Peça contagens antes de solicitar análises detalhadas:

"How many critical and high severity findings do we have?"

Seu assistente de IA usará a ferramenta get_findings com limit: 1 para recuperar de forma eficiente apenas a contagem.

2. Use Paginação Estratégica

Para grandes conjuntos de dados, seu assistente de IA percorre os resultados automaticamente por páginas:

"Analyze all our active vulnerabilities"

A IA fará múltiplas chamadas se necessário, começando com limites razoáveis e aumentando conforme exigido.

3. Reaproveitamento Eficiente de Dados

Faça perguntas relacionadas em sequência para evitar consultas redundantes:

"Show me all critical findings, then tell me which CWE categories they fall into"

A IA reaproveitará os dados de achados da primeira consulta para a análise de CWE.

Estratégias de Filtragem Inteligente#

Elabore seus prompts para aproveitar os poderosos recursos de filtragem do DefectDojo:

Consultas Baseadas em Severidade#

Prompt do Usuário:

"Show me all Critical and High severity issues that need immediate attention"

Nos bastidores: a IA usa get_findings com filtros de severidade e status

Consultas Baseadas em Tempo#

Prompt do Usuário:

"What new vulnerabilities have been discovered in the past 30 days?"

Nos bastidores: a IA aplica o filtro de data “Past 30 days” com status ativo

Filtragem Combinada#

Prompt do Usuário:

"Give me a risk assessment of all critical and high active findings from the past 90 days"

Nos bastidores: a IA combina filtros de severidade, status e data para uma análise abrangente

Análise de Referência Cruzada#

Seu assistente de IA vincula automaticamente os achados ao contexto organizacional. Basta fazer perguntas abrangentes:

Prompt do Usuário:

"Which products have the most critical vulnerabilities and who is responsible for fixing them?"

Nos bastidores: a IA vincula achados → testes → engajamentos → produtos → usuários/grupos para um contexto completo

Análise de Inteligência de Vulnerabilidades#

Análise de Padrões de CWE

Prompt do Usuário:

"What are the most common vulnerability types in our codebase and which teams are creating them?"

A IA agrupará os achados por CWE para identificar padrões recorrentes, necessidades de treinamento e problemas arquiteturais.

Métricas de Idade

Prompt do Usuário:

"How long have our critical vulnerabilities been open? Which ones are overdue for remediation?"

A IA calcula o tempo desde a descoberta e sinaliza achados que excedem os limites de SLA.

Densidade de Vulnerabilidades

Prompt do Usuário:

"Which products have the highest vulnerability density and represent the greatest risk?"

A IA calcula achados por produto e gera pontuações de risco combinando severidade e volume.

Padrões de Aprimoramento de Relatórios#

Sempre Inclua#

• Métricas específicas: contagens reais por severidade, não generalizações
• Análise de CWE: principais tipos de vulnerabilidade com descrições
• Dados de idade: há quanto tempo as vulnerabilidades estão abertas
• Recomendações acionáveis: o que fazer a seguir, com prazos
• Cálculos de ROI: custo esperado vs. benefício das ações
• Métricas de sucesso: como medir a melhoria

Integração de Contexto do Setor#

Compare os achados do DefectDojo com frameworks do setor:

• OWASP Top 10: riscos de segurança de aplicações web
• SANS Top 25: fraquezas de software mais perigosas
• CWE Top 25: fraquezas mais comuns e impactantes
• Frameworks de conformidade: SOC 2, ISO 27001, NIST CSF

Solução de Problemas do MCP#

Lista de Verificação de Diagnóstico#

Verifique estes itens ao enfrentar problemas de conexão:

• ✅ o Tipo de Transporte é Streamable HTTP (não SSE)
• ✅ a URL do endpoint MCP está correta: https://[instance].defectdojo.com/mcp
• ✅ o cabeçalho Authorization está habilitado (o alternador está ON)
• ✅ o formato do token inclui o prefixo Token
• ✅ o token é válido e possui as permissões apropriadas
• ✅ a instância do DefectDojo está acessível (é possível fazer login pela interface web)
• ✅ a conectividade de rede permite conexões HTTPS

Problemas de Conexão Comuns#

❌ “Connection Error - Check if your MCP server is running”#

Causa: uso do tipo de transporte SSE (Server-Sent Events), que está descontinuado

Solução: altere o Tipo de Transporte para Streamable HTTP

Por quê: o Servidor MCP do DefectDojo usa o protocolo moderno Streamable HTTP. O SSE está descontinuado e não é suportado.

❌ “Authentication Failed” ou “401 Unauthorized”#

Causa: formato incorreto do cabeçalho de autenticação ou token inválido

Soluções:

1. Verifique se o valor do cabeçalho usa o prefixo Token (não Bearer)

   ✅ Correct: Token 7c6cc2xxxxxxxxxxxxxxxxxxxx87fcf72ec2b3fb
   ❌ Wrong: Bearer 7c6cc2xxxxxxxxxxxxxxxxxxxx87fcf72ec2b3fb

2. Certifique-se de que o alternador do cabeçalho Authorization esteja HABILITADO (ligado)

3. Verifique se o token ainda é válido no DefectDojo (Admin → API Tokens)

4. Verifique se o token tem as permissões apropriadas para acesso de leitura

❌ A Ferramenta Retorna Resultados Vazios#

Possíveis Causas:

• Os filtros são restritivos demais (nenhum dado corresponde aos critérios)
• A instância do DefectDojo não tem dados na categoria solicitada
• Permissões insuficientes do token

Soluções:

1. Tente primeiro uma consulta mais ampla: get_findings({ limit: 10 })
2. Remova os filtros um de cada vez para identificar o filtro restritivo
3. Verifique as permissões do token no DefectDojo
4. Verifique se os dados existem diretamente na interface do DefectDojo

⚠️ Tempos de Resposta Lentos#

Causa: solicitação de dados em excesso de uma só vez

Soluções:

• Reduza o parâmetro limit (comece com 50-100)
• Use filtros mais específicos para reduzir o tamanho do conjunto de resultados
• Use carregamento progressivo: obtenha as contagens primeiro, depois os detalhes
• Implemente paginação para grandes conjuntos de dados