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 aceitaorganizationId. O servidor MCP lida com isso automaticamente:
- Se
ZEROPATH_ORG_IDestiver definido, o servidor o injeta em cada requisição — você nunca precisa passá-lo manualmente. - Se
ZEROPATH_ORG_IDnão estiver definido, você deve passarorganizationIdexplicitamente. A maioria das ferramentas o exige no nível da API; algumas (comoissues.list) conseguem resolver o contexto da organização a partir da sua sessão de autenticação.
Ferramentas de Issues
issues.list
Liste e filtre issues de segurança. Usa paginação baseada em offset viaoffset 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.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 — useissues.updateSeverityRating para mover um desses.
issues.updateSeverityRating
Altere a classificação de severidade exibida de uma única issue. InformeissueId
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."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).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.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 onextCursor 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.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.code.search
Busque código dentro de um repositório.code.read
Leia o conteúdo de um arquivo em um repositório.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 onextCursor 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 dotestConnection) 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âmetroapiToken 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 emstatuses. 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
Triar novas issues
Triar novas issues
- Liste as issues pendentes — chame
issues.listcomstatuses: ["PENDING_REVIEW"]ordenado porscoredecrescente. - Revise cada issue — peça ao seu assistente de IA para resumir a vulnerabilidade e o código afetado.
- Classifique — use
issues.markTruePositiveouissues.markFalsePositivecom um motivo. - Atualize o status — mova as issues confirmadas para
REVIEWINGouPATCHINGcomissues.updateStatus. - Ajuste a severidade — se a classificação atribuída automaticamente não corresponder à sua avaliação, use
issues.updateSeverityRatingcom um rótulo de faixa (critical,high,medium,low,info). Useissues.updateSeverityapenas 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 filaPENDING_REVIEW.
Criar regras personalizadas
Criar regras personalizadas
- Liste as regras existentes — chame
rules.listpara ver o que já está configurado. - Crie uma regra — use
rules.createcom uma descrição em linguagem natural. O scanner da ZeroPath fará a correspondência desse padrão em scans futuros. - Defina o escopo — use
repositoryIdspara limitar a regra a repositórios específicos,globPatternpara limitar a tipos de arquivo específicos esourceTypespara direcionar pontos de entrada específicos. - Adicione tags — use
tagIdspara associar a regra a tags para fins de organização. - Itere — atualize com
rules.updateconforme você refina o padrão.
Investigar resultados de scans
Investigar resultados de scans
- Liste os scans recentes — chame
scans.listpara ver o histórico de scans. Filtre comscanTypes: ["FullScan"]para scans agendados ou["PrScan"]para scans de PR. - Obtenha os detalhes do scan — use
scans.getcom umscanIdespecífico para ver status, branch e contagens de issues. - Aprofunde-se nos achados — chame
issues.listcom um filtro descanIdpara ver apenas as issues daquele scan.
Tratamento de Erros
Chamadas de ferramenta que falham retornam erros estruturados:BAD_REQUEST — Entrada inválida
BAD_REQUEST — Entrada inválida
Retornado quando a validação da entrada falha. Verifique o array
data.issues para detalhes por campo.FORBIDDEN — Permissões insuficientes
FORBIDDEN — Permissões insuficientes
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.
NOT_FOUND — O recurso não existe
NOT_FOUND — O recurso não existe
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/limitpara issues,cursor/limitpara 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
reasonao arquivar, marcar falsos/verdadeiros positivos ou mudar status, para fins de trilha de auditoria. - Defina o contexto da organização — configure
ZEROPATH_ORG_IDdurante a instalação para que o servidor injeteorganizationIdautomaticamente em cada requisição.