Saltar para o conteúdo principal
O servidor MCP expõe ferramentas que mapeiam para a API REST V2 da ZeroPath. As ferramentas são carregadas do manifesto MCP da ZeroPath na inicialização, então seu assistente de IA sempre tem acesso às capacidades atuais.

Automações do Assistente

O MCP local com token de API permite gerenciar agendamentos e gatilhos e ativar playbooks, com Manage Agent. O MCP remoto permite listar, executar e excluir agendamentos existentes, mas não criar/editar automações nem ativar playbooks. Configurações globais e instruções do Assistente ficam no painel ou na API administrativa. agent.getJob retorna o status, o resumo e as mensagens visíveis de uma execução, respeitando o acesso atual. Consulte o fluxo completo da API.

Issues

12 ferramentas — listar, triar, investigar, atualizar status, severidade e notas, regenerar patches

Scans

3 ferramentas — listar histórico de scans, obter detalhes de um scan, reescanear PRs

Repositórios

1 ferramenta — listar repositórios com filtragem

Inspeção de Código

3 ferramentas — buscar, ler e listar arquivos em repositórios conectados

Regras

5 ferramentas — CRUD completo para regras de segurança personalizadas

Security Compass

11 ferramentas: gerenciar mapeamentos de projeto do SD Elements e seu mapeamento de status de tarefa, sincronizar regras, enviar o último scan, ler a auditoria de cobertura e consultar issues vinculadas

Escopo de Organização

Toda ferramenta aceita organizationId. O servidor MCP lida com isso automaticamente:
  • Se ZEROPATH_ORG_ID estiver definido, o servidor o injeta em cada requisição — você nunca precisa passá-lo manualmente.
  • Se ZEROPATH_ORG_ID não estiver definido, você deve passar organizationId explicitamente. A maioria das ferramentas o exige no nível da API; algumas (como issues.list) conseguem resolver o contexto da organização a partir da sua sessão de autenticação.
Defina ZEROPATH_ORG_ID durante a instalação para evitar passar organizationId em cada chamada.

Ferramentas de Issues

issues.list

Liste e filtre issues de segurança. Usa paginação baseada em offset via offset e limit.

issues.archive

Arquive issues para removê-las das visualizações ativas.

issues.unarchive

Restaure issues arquivadas de volta às visualizações ativas.

issues.markFalsePositive

Marque issues como falsos positivos. Remove-as da revisão ativa.

issues.markTruePositive

Confirme issues como verdadeiros positivos.

issues.updateStatus

Atualize o status de fluxo de trabalho de uma ou mais issues.
O nome do campo é issueStatus, não status. Usar o nome de campo errado causará um erro de validação.

issues.updateSeverity

Atualize a severidade bruta de 0 a 10 de uma única issue. A classificação exibida em uma issue é o score composto do ZeroPath (severidade x confiança, 0-100), portanto esta ferramenta move a classificação apenas para um achado que um agente do scanner avaliou. Um achado sem confiança registrada é pontuado apenas pela severidade e permanece na faixa Informational qualquer que seja a severidade definida — use issues.updateSeverityRating para mover um desses.
Esta ferramenta recebe um único issueId (string), não issueIds (array). O campo severity é um número entre 0 e 10, não um enum de string.

issues.updateSeverityRating

Altere a classificação de severidade exibida de uma única issue. Informe issueId e rating como critical, high, medium, low ou info; inclua reason opcionalmente. Use a organização configurada na sessão MCP ou informe organizationId explicitamente. A resposta é { "ok": true }. Esta ferramenta ajusta a severidade para atingir a faixa solicitada do ZeroPath score. Uma confiança baixa pode impedir a elevação para uma faixa superior; reduções sempre são aplicadas.

issues.requestInvestigation

Solicite uma investigação sob demanda de um achado usando modelos de IA maiores para uma validação de maior confiança.
REST vs MCP: A API HTTP pública expõe um único procedimento, POST /api/v2/issues/requestInvestigation, com um array issueIds (um ou mais IDs). Essa rota usa o mesmo caminho de backend que a ferramenta MCP issues.requestBulkInvestigation. Esta ferramenta MCP issues.requestInvestigation chama a mutação tRPC de issue única — não existe um endpoint REST POST …/{id}/investigate correspondente.
Se já houver uma investigação em andamento para a issue, a resposta retorna a investigação existente com "status": "already_pending" em vez de criar uma duplicata. Uma reinvestigação pode fechar achados: um veredito definitivo de não explorável ou corrigido fecha a issue e o ticket vinculado. Por isso ela exige permissão para fechar achados (Close Issues, ISSUE_EDIT_CLOSE) no repositório da issue. Sem ela, a solicitação falha com FORBIDDEN (HTTP 403) e a mensagem “Re-investigation can close findings, so it needs permission to close findings.” A verificação vale para a pessoa em nome de quem a sessão MCP age. Administradores da organização não são recusados, nem as automações que rodam por conta própria (gatilhos de eventos e tarefas agendadas). Uma execução iniciada por uma pessoa, como ativar um playbook ou executar manualmente uma tarefa agendada, é verificada contra essa pessoa.

issues.requestBulkInvestigation

Solicite investigações para várias issues de uma vez.
Mapeamento REST: POST /api/v2/issues/requestInvestigation com { issueIds, context?, organizationId? }. Esta é a superfície HTTP para investigações em lote; não é o mesmo nome de ferramenta MCP que issues.requestInvestigation (ferramenta tRPC de issue única acima).
Issues que já têm uma investigação pendente ou em andamento são ignoradas. Issues que não pertencem à sua organização são contabilizadas como não autorizadas. Assim como issues.requestInvestigation, esta ferramenta exige permissão para fechar achados (ISSUE_EDIT_CLOSE) no repositório de cada issue solicitada que você pode ver. Se uma delas estiver em um repositório onde você não tem essa permissão, toda a solicitação falha com FORBIDDEN (HTTP 403) e nada é enfileirado. Issues que você não pode ver não fazem parte desta verificação: continuam contabilizadas como não autorizadas.

issues.getInvestigationStatus

Obtenha o resultado de investigação mais recente de uma issue.
Retorna null se nenhuma investigação tiver sido solicitada para a issue. O campo status pode ser PENDING, PROCESSING, COMPLETED ou FAILED.

issues.regeneratePatch

Solicite a geração de um novo patch para uma issue. Use isto quando o patch gerado automaticamente estiver desatualizado, não se aplicar de forma limpa, ou quando você quiser uma nova tentativa depois que o código afetado mudou.

issues.updateNotes

Atualize as notas internas de uma issue. Notas são anotações de texto livre visíveis para sua equipe na página de detalhes da issue e são úteis para registrar contexto de triagem, descobertas de investigação ou planos de remediação.

Ferramentas de Scan

scans.list

Liste scans com paginação baseada em cursor. Passe o nextCursor de uma resposta anterior para avançar na paginação.

scans.get

Obtenha os detalhes de um scan específico.

scans.rescanPR

Dispare um novo scan de um pull request ou merge request. Passe o ID de um scan de PR anterior e a plataforma buscará o pull request novamente e criará novo(s) scan(s). Suporta PRs do GitHub e MRs do GitLab.
O campo outcome indica o que aconteceu:

Ferramentas de Repositório

repositories.list

Liste repositórios com paginação baseada em cursor (cursor em string).

Ferramentas de Inspeção de Código

Estas ferramentas permitem navegar e buscar código-fonte diretamente em repositórios GitHub e GitLab conectados, sem precisar cloná-los. Busque código dentro de um repositório.

code.read

Leia o conteúdo de um arquivo em um repositório.
As respostas são limitadas a 1.000 linhas e 200 KB. As flags truncatedByLineRange e truncatedByByteLimit indicam se a resposta foi truncada.

code.listFiles

Liste arquivos e diretórios dentro de um caminho do repositório.
A inspeção de código atualmente é suportada para repositórios GitHub e GitLab. Bitbucket, Git genérico e repositórios enviados por upload ainda não são suportados.

Ferramentas de Regras

rules.list

Liste regras de segurança personalizadas, das mais recentes para as mais antigas. Usa paginação baseada em cursor (cursor do tipo string): passe o nextCursor de uma resposta anterior para obter as regras após a última que ela retornou. Regras criadas ou excluídas entre as requisições de página nunca fazem uma página seguinte repetir ou pular uma regra; recomece sem cursor para ver as regras criadas depois da primeira página.

rules.get

Obtenha os detalhes de uma regra específica, incluindo os nomes dos repositórios associados.

rules.create

Crie uma regra de segurança personalizada.

rules.update

Atualize uma regra existente. Apenas os campos que você incluir serão modificados.

rules.delete

Exclua uma regra personalizada.

Ferramentas do Security Compass

Estas ferramentas permitem gerenciar a integração Security Compass / SD Elements a partir do seu assistente de IA. As operações de credenciais (criar ou excluir a integração, e o parâmetro de token do testConnection) não são expostas pelo MCP de propósito: forneça sua chave de API do SD Elements pelo dashboard do ZeroPath, não por um assistente de IA.

securityCompass.getIntegration

Busca a integração do Security Compass e todos os mapeamentos de projeto de uma organização.

securityCompass.testConnection

Valida as credenciais contra um projeto específico do SD Elements. O parâmetro apiToken não é exposto pelo MCP: a ferramenta usa as credenciais armazenadas quando a URL solicitada corresponde à origem da integração armazenada.

securityCompass.listTaskStatuses

Lista os status de tarefa que existem na instância do SD Elements conectada, retornados em statuses. Cada entrada tem um id, um slug, um name de exibição e um meaning de DONE, TODO ou NA. Use os slugs ao montar um taskStatusMapping; apenas status cujo significado é DONE ou TODO podem ser mapeados. Falha com BAD_REQUEST quando a instância não pode ser alcançada.

securityCompass.addProjectMapping

Vincula um projeto SD Elements a um repositório ZeroPath, inicia a sincronização de regras inicial e, quando a integração está habilitada, envia o último scan completo finalizado do repositório assim que essa sincronização tem sucesso.

securityCompass.updateProjectMapping

Define o mapeamento de status de tarefa de um mapeamento, ou o limpa para que o mapeamento herde o padrão da integração. Uma chave ausente significa “deixar o status da tarefa como está” para aquele resultado, e {} significa apenas a nota de verificação. Todo slug precisa existir na instância com o significado DONE ou TODO; a chamada falha com BAD_REQUEST quando um slug não existe, significa NA, ou a instância não pode ser alcançada para conferir. A mudança vale para o próximo envio; chame pushLatestScan para aplicá-la ao scan atual.

securityCompass.removeProjectMapping

Desvincula um mapeamento de projeto (e limpa as regras geradas quando não restam outros mapeamentos para o repositório).

securityCompass.syncRules

Dispara manualmente uma sincronização de contramedidas para regras em um mapeamento.

securityCompass.pushLatestScan

Enfileira um envio de resultados do último scan completo finalizado do repositório para um mapeamento, sem rodar um novo scan. Use depois de mudar um mapeamento de status de tarefa, ou para um mapeamento criado muito depois do último scan do repositório. Retorna { status: "enqueued", codeScanId }, ou { status: "no_scan" } quando o repositório ainda não tem um scan completo finalizado. A chamada falha com CONFLICT (HTTP 409) enquanto um envio desse scan já está em execução, e com PRECONDITION_FAILED (HTTP 412) quando a integração está desabilitada. Um reenvio de um scan já enviado roda de novo com o mapeamento atual e os achados abertos como estão agora.

securityCompass.getMappingAudit

Recupera o detalhamento de cobertura por contramedida de um mapeamento. Retorna uma entrada por contramedida do SD Elements descrevendo como o ZeroPath a cobre (análise integrada, regra em linguagem natural gerada automaticamente, não suportada ou erro de classificação), enriquecida com fase, prioridade, classificação de risco e contagem de issues vinculadas.

securityCompass.getLinkedIssues

Lista os achados abertos do ZeroPath vinculados a uma contramedida específica do SD Elements.

securityCompass.getSyncHistory

Recupera os eventos recentes do log de auditoria do Security Compass de uma organização, do mais novo para o mais antigo: sincronizações de regras, envios de achados, solicitações de envio sob demanda, adições de mapeamento, mudanças de mapeamento de status de tarefa e remoções, mudanças na integração e testes de conexão.
Gerenciar mapeamentos, disparar sincronizações e enviar resultados (addProjectMapping, updateProjectMapping, removeProjectMapping, syncRules, pushLatestScan) exige o papel de admin. As operações de leitura (getIntegration, getMappingAudit, getLinkedIssues, getSyncHistory) estão disponíveis a todos os membros da organização. listTaskStatuses também exige o papel de admin, porque chama o SD Elements com o token armazenado em nome de quem faz a chamada. Veja Security Compass / SD Elements para o fluxo completo e Mapeamento de status de tarefa para o que um mapeamento faz no SD Elements.

Fluxos de Trabalho Comuns

  1. Liste as issues pendentes — chame issues.list com statuses: ["PENDING_REVIEW"] ordenado por score decrescente.
  2. Revise cada issue — peça ao seu assistente de IA para resumir a vulnerabilidade e o código afetado.
  3. Classifique — use issues.markTruePositive ou issues.markFalsePositive com um motivo.
  4. Atualize o status — mova as issues confirmadas para REVIEWING ou PATCHING com issues.updateStatus.
  5. Ajuste a severidade — se a classificação atribuída automaticamente não corresponder à sua avaliação, use issues.updateSeverityRating com um rótulo de faixa (critical, high, medium, low, info). Use issues.updateSeverity apenas quando quiser definir especificamente o número bruto de 0 a 10: ele não move a classificação exibida de um achado para o qual o scanner nunca registrou uma confiança, o que é a maior parte da fila PENDING_REVIEW.
  1. Liste as regras existentes — chame rules.list para ver o que já está configurado.
  2. Crie uma regra — use rules.create com uma descrição em linguagem natural. O scanner da ZeroPath fará a correspondência desse padrão em scans futuros.
  3. Defina o escopo — use repositoryIds para limitar a regra a repositórios específicos, globPattern para limitar a tipos de arquivo específicos e sourceTypes para direcionar pontos de entrada específicos.
  4. Adicione tags — use tagIds para associar a regra a tags para fins de organização.
  5. Itere — atualize com rules.update conforme você refina o padrão.
  1. Liste os scans recentes — chame scans.list para ver o histórico de scans. Filtre com scanTypes: ["FullScan"] para scans agendados ou ["PrScan"] para scans de PR.
  2. Obtenha os detalhes do scan — use scans.get com um scanId específico para ver status, branch e contagens de issues.
  3. Aprofunde-se nos achados — chame issues.list com um filtro de scanId para ver apenas as issues daquele scan.

Tratamento de Erros

Chamadas de ferramenta que falham retornam erros estruturados:
Retornado quando a validação da entrada falha. Verifique o array data.issues para detalhes por campo.
Verifique se ZEROPATH_TOKEN_ID e ZEROPATH_TOKEN_SECRET estão corretos e se a chave de API está ativa.
A chave de API não tem as permissões necessárias para esta operação. Verifique o papel da sua chave em ZeroPath Settings.
O ID especificado (issue, scan, regra ou repositório) não foi encontrado. Verifique se o ID está correto e pertence à sua organização.

Dicas

  • Pagine — sempre pagine conjuntos grandes de resultados. Use offset/limit para issues, cursor/limit para scans, repositórios e regras.
  • Filtre cedo — use filtros de status, severidade e repositório para reduzir o tamanho da resposta.
  • Atualize em lote — passe múltiplos IDs em uma única chamada ao arquivar, marcar ou atualizar status.
  • Inclua motivos — adicione um reason ao arquivar, marcar falsos/verdadeiros positivos ou mudar status, para fins de trilha de auditoria.
  • Defina o contexto da organização — configure ZEROPATH_ORG_ID durante a instalação para que o servidor injete organizationId automaticamente em cada requisição.