Saltar para o conteúdo principal

Como Funciona

Mencione o bot do ZeroPath em um comentário de pull request ou merge request. O bot processa o comando e informa o resultado na mesma conversa.
1

Mencione o bot

Comece o seu comentário com @ZeroPath (o alias legado @zeropath-ai também funciona), ou @<your-bot-username> (o nome de usuário exato configurado para o seu GitHub App ou integração do GitLab). Nomes de usuário de bot específicos de ambiente só correspondem àquela integração exata.
2

Digite um comando

Use um dos comandos estruturados abaixo, ou faça uma pergunta em linguagem natural. Alvos como issue 2 são comparados com os problemas que o ZeroPath reportou neste PR.
3

Leia a resposta

Para perguntas ao Assistente, o bot atualiza a confirmação com a resposta quando ela estiver pronta. Comandos estruturados informam o resultado da ação. A confirmação indica que o bot recebeu o comentário. Aguarde o resultado antes de enviar o pedido novamente.
Os comandos do bot são suportados no GitHub, GitLab e Azure DevOps. O suporte ao Bitbucket Cloud e Data Center está disponível nas versões que incluem ZP-7560. Instalações on-premises precisam de uma distribuição publicada com essa atualização.
No Bitbucket, publique um comentário novo, sem edição, começando com @ZeroPath ou @zeropath-ai. Exemplos: explain issue 1, fp issue 1 because ..., rescan e rescan force. Explicações exigem o Assistente habilitado e substituem a resposta inicial quando ficam prontas. Comentários editados ou excluídos não executam comandos. Com controle de acesso habilitado, vincule a conta de colaborador Bitbucket à identidade ZeroPath da instância correta e conceda as permissões necessárias. Respostas a achados usam a partição do achado; comentários gerais usam o scan de PR mais recente da conexão. Modificação de branches e bypass de checks não são suportados. Após atualizar o Data Center, execute Add all accessible Bitbucket repositories para incluir pr:comment:added nos webhooks existentes.
Um @ZeroPath sozinho, sem comando, faz o bot responder com uma dica: I'm here. Try: @ZeroPath fp issue 2 because …

Referência de Comandos

A maioria das categorias aceita a mesma sintaxe de alvo (consulte Alvos) e muitas aceitam um sufixo opcional because <reason> (consulte O Modificador because para saber quais comandos persistem o motivo).

Status de Triagem

Marque o veredito de corretude de uma descoberta. Esses comandos alteram o estado de triagem do problema e disparam uma notificação vulnerability status changed pelos seus canais configurados.

Status de Fluxo de Trabalho

Mova uma descoberta pelo fluxo de revisão da sua equipe. Esses comandos não alteram o veredito de corretude — use o Status de Triagem para isso. fixed in registra o commit como o motivo da resolução, mas somente depois que o bot verifica que o commit é um dos commits deste PR. Ele aceita um SHA de commit (de 7 a 40 caracteres hexadecimais), um SHA entre crases ou um link para o commit. Sem um <target>, aplica-se à descoberta em cujo fio você está respondendo. Se o commit não está no PR, corresponde a mais de um commit, ou o PR tem mais commits do que o bot consegue verificar, o bot informa isso e não altera nada.
fixed in (o comando acima e a resposta sem menção) e a resposta Accepted risk sem menção estão disponíveis enquanto a configuração de resolução por resposta a descobertas do bot de PR estiver ativada. A configuração vem ativada por padrão e é gerenciada pela ZeroPath. Em implantações hospedadas pela ZeroPath, a ZeroPath pode desativá-la, e o bot passa então a tratar essas mensagens como qualquer outra mensagem. O chart self-hosted não expõe a configuração nesta versão, então instalações self-hosted sempre a mantêm ativada.

Atribuição

Atribua o ticket do Jira ou do Linear vinculado a uma descoberta a um colega de equipe. Requer que a descoberta tenha um issue associado no Jira/Linear (consulte Jira ou Linear). Se um alvo não tiver ticket vinculado no Jira/Linear, o bot reporta assignment isn't possible (no linked Jira/Linear ticket) para aquele problema e continua com os demais.

Patches de Correção Automática

Acione o pipeline de geração de patches do ZeroPath para uma descoberta específica. Consulte Auto-Fix para o recurso completo.

Alterações em PRs de Patch no GitHub

No GitHub, quando o ZeroPath abre um PR de patch de correção automática, os revisores podem solicitar mudanças de código adicionais diretamente da conversa do PR. Comece um novo comentário no PR com @ZeroPath e descreva a mudança que você quer.
PR comment
Para essas solicitações, o ZeroPath:
  1. Verifica que o PR é um PR de patch do GitHub criado pelo ZeroPath.
  2. Verifica que a branch head atual do PR é a mesma branch de patch que o ZeroPath criou.
  3. Aplica apenas a mudança solicitada.
  4. Faz commit da mudança na branch existente do PR.
  5. Responde com um resumo e a referência do commit.
Mudanças diretas na branch de PRs de patch são atualmente exclusivas do GitHub. Os comandos do bot no GitLab continuam suportando triagem, atribuição, geração de patches, reescaneamentos, retriagem e perguntas em linguagem natural, mas não commits de acompanhamento diretos em uma branch de PR de patch existente.
O ZeroPath se recusa a fazer push quando a branch do PR não pode ser verificada como uma branch de patch criada pelo ZeroPath, a branch se moveu enquanto o bot estava trabalhando, o PR vem de um fork, ou a solicitação é insegura, ambígua, impossível ou faria mudanças não relacionadas.

Operações de Escaneamento

Quando o bot não consegue executar um reescaneamento, ele explica o motivo com uma destas mensagens: A scan for the current commit already exists. Use \rescan force` to bypass the cache., Cannot rescan a closed pull request.`, ou um motivo específico do serviço.

Exceções à Verificação Supply Chain Intel

Consulte a verificação Supply Chain Intel para ver a configuração e os lockfiles compatíveis. No GitHub, peça uma exceção à verificação ZeroPath Supply Chain Intel para uma versão de pacote que ela sinalizou neste pull request. A verificação Supply Chain Intel não tem bypass; uma exceção é o caminho. because <text> funciona no lugar de reason: <text>, e o motivo é obrigatório. O comando cobre as ocorrências Block e Warn que a verificação Supply Chain Intel mais recente do head atual do PR registrou nessa versão. A sua conta do GitHub precisa estar vinculada a um usuário do ZeroPath. Dependendo das configurações de exceção das regras e do seu papel, o bot cria a exceção, diz até quando ela vale e reavalia a verificação, ou a solicita e nomeia os aprovadores; a verificação é executada de novo quando um deles aprova. Uma regra que não permite exceções é nomeada na resposta. No GitLab, no Bitbucket e no Azure DevOps, o bot responde que @ZeroPath allow ainda não está disponível nesse host de código.

Re-Triagem (Investigação Mais Profunda)

Execute novamente a validação por IA nas descobertas usando uma investigação mais minuciosa do que a do escaneamento de PR padrão. Quando a descrição do PR referencia vulnerabilidades por tag ZP-ID ou URL do dashboard (consulte Verificação de Correção), retriage executa a verificação de correção em vez disso. A resposta do retriage, publicada no lugar do comentário de confirmação, lista cada problema com um veredito (Confirmed ou Disconfirmed), uma avaliação de segurança e um link para o problema no dashboard do ZeroPath.

Perguntas em Linguagem Natural

Qualquer coisa que não corresponda a um comando estruturado ou a uma solicitação de mudança em PR de patch do GitHub é tratada como uma pergunta ao bot. No GitHub, o bot responde com uma resposta gerada por IA no mesmo fio de comentários, publicando um placeholder Thinking... e editando-o no lugar com a resposta completa quando estiver pronta.
PR comment
O que o bot faz com uma mensagem que não é um comando estruturado depende de o Assistant do ZeroPath estar habilitado para a sua organização. Um administrador da organização pode habilitar o Assistant.Assistant habilitado: uma mensagem não reconhecida recebe uma resposta do Assistant. Mensagens em formato de pergunta (aquelas classificadas como perguntas pelo LLM) recebem uma resposta de IA em formato livre tanto no GitHub quanto no GitLab. As plataformas divergem apenas quando o classificador não consegue reconhecer a mensagem de forma alguma: o GitLab retorna uma resposta estática listando os exemplos de comandos suportados (I couldn't understand that command. Examples: ...), enquanto o GitHub recorre a uma resposta de Assistant em formato livre. Se você está no GitLab e o bot responde com a lista estática de comandos, reformule como uma pergunta clara ou use um dos comandos estruturados acima.Assistant desabilitado: o bot não tem com o que responder. Ele publica a lista de comandos suportados uma vez por fio e permanece em silêncio nesse fio depois disso. No GitHub a lista inclui @ZeroPath allow, que os outros hosts de código não executam. O reconhecimento do bot no seu comentário continua mostrando que ele o recebeu: uma reação de olhos no GitHub e no GitLab, um like no Azure DevOps. O Bitbucket não tem reconhecimento.Comandos estruturados como @ZeroPath fp issue 2 because … funcionam nos dois casos.
Comentários que parecem tentativas de prompt injection são bloqueados automaticamente. Se você receber uma mensagem de rejeição, reformule a pergunta como uma consulta direta sobre uma descoberta específica reportada.

Respondendo a uma Descoberta sem Mencionar o Bot

No GitHub e no Azure DevOps, duas respostas sob o comentário de uma descoberta são reconhecidas sem @ZeroPath. A resposta precisa começar com essas palavras e aplica-se à descoberta em cujo fio você está respondendo.
PR reply under a finding
O bot responde com a mesma confirmação do comando correspondente, seguida de I recorded this from your reply in this thread. To undo it, reopen the issue in ZeroPath. Nada é registrado em silêncio. Para reverter, reabra a descoberta: responda @ZeroPath in-progress ou @ZeroPath status pending_review no fio dela, ou reabra o problema no ZeroPath.
  • Qualquer outra coisa que você escrever sob uma descoberta é tratada como uma pergunta, como descrito em Perguntas em Linguagem Natural. Accepted risk assessment is wrong e Not fixed in abc1234 não são reconhecidas como essas respostas.
  • O texto depois do commit ou depois de Accepted risk nunca muda qual descoberta é afetada. Para agir em outra descoberta, use um comando com um alvo.
  • Só conta o fio iniciado pelo comentário do ZeroPath para uma descoberta. Em qualquer outro fio, como o fio de resumo do Azure DevOps que tem links para todas as descobertas, essas respostas são tratadas como perguntas e não alteram nada.
  • Valem as mesmas permissões dos comandos: Mark Issues as Open para Fixed in e Archive Issues para Accepted risk. Com controle de acesso habilitado, a sua conta precisa estar vinculada a uma identidade do ZeroPath.
  • Essas respostas são tratadas mesmo quando o Assistant do ZeroPath não está habilitado para a sua organização.
  • Se a descoberta não é mais reportada pelo escaneamento mais recente do PR, o bot informa isso e não altera nada.
  • Um motivo com mais de 2000 caracteres não é registrado; o bot avisa e você pode publicar um mais curto.
  • Ambas as respostas, assim como fixed in, estão disponíveis enquanto a configuração de resolução por resposta a descobertas do bot de PR estiver ativada (o padrão); consulte a nota em Status de Fluxo de Trabalho. Com ela desativada, elas vão para o Assistant como antes.

Alvos

Um alvo especifica a qual(is) problema(s) o comando se aplica. O parser aceita: A forma implícita é o caminho mais fácil: abra um comentário inline de descoberta, responda a ele com @ZeroPath fp because not reachable from input, e o bot aplica o comando àquela descoberta sem que você precise nomear um número de problema. Cada comentário inline de descoberta inclui um rodapé de dicas rápidas com exemplos de comandos de resposta, para que você veja a sintaxe sem sair do seu PR. Um retriage sozinho, sem alvo, assume por padrão todos os problemas deste PR.
Use vírgulas, não a palavra and, para separar vários números de problemas. O parser só reconhece listas separadas por vírgula — issues 1 and 4 silenciosamente atinge apenas o problema #1, descartando and 4. Sempre escreva issues 1, 4.

O Modificador because

Todo comando de triagem, de status de fluxo de trabalho e de retriagem aceita um sufixo opcional because <reason>. O texto após because é capturado pelo parser como o motivo do usuário para a ação.
PR comment
Como o motivo é usado depende do comando:

Exemplos Práticos

Permissões

Quando o controle de acesso está habilitado para a sua organização, o bot verifica que o usuário do GitHub ou do GitLab que publicou o comentário está vinculado a uma identidade do ZeroPath, e que o usuário vinculado tem a permissão de repositório adequada para a ação. As permissões abaixo usam os nomes de exibição exatos da página de configurações de Teams, para que um admin possa encontrar cada uma como uma checkbox na UI de permissões de equipe.
Essas são permissões distintas. Um usuário com Mark as False Positive mas sem Archive Issues pode executar fp, mas terá accepted-risk negado, ainda que ambas sejam ações de “triagem” no uso casual. Da mesma forma, non-exploitable é controlado por Mark as True Positive, não por False Positive — ambos os comandos afirmam uma classificação de vulnerabilidade, então compartilham a permissão de True Positive.
Se um usuário não tiver a permissão necessária, o bot responde com Permission denied (missing <PERMISSION_CONSTANT>). Por exemplo, ISSUE_EDIT_OPEN corresponde a Mark Issues as Open, PATCH_CREATE corresponde a Generate Patches e PATCH_ISSUE corresponde a Create Pull Requests. Se o autor do comentário não tiver uma identidade do ZeroPath vinculada no GitHub, o bot responde:
I can’t verify your ZeroPath identity for this organization. Your GitHub account isn’t linked to a ZeroPath user yet. To link it, set your GitHub public email (Settings > Public profile) to match your ZeroPath account email, then comment again. The link is saved on our side, so you can switch the email back to private afterward. This should fix the issue most of the time.
No GitLab, o bot responde:
I can’t verify your ZeroPath identity for this organization (no linked ZeroPath user). Please contact your org admin to link your account.
Consulte Equipes e Permissões para saber como vincular usuários do VCS e configurar RBAC.

Suporte de Plataformas

As exceções à verificação Supply Chain Intel (@ZeroPath allow) existem apenas no GitHub.

Solução de Problemas

O bot responde “I couldn’t understand that command.” O parser não reconheceu nem uma palavra-chave explícita nem uma pergunta. Use um dos exemplos práticos como modelo, ou cole uma URL do dashboard como alvo. O bot responde “I didn’t run that command. …” O comando foi reconhecido, mas uma de suas partes é inválida, então o bot não executou nada dele. A resposta indica qual parte. A causa mais comum é um motivo após because com mais de 2000 caracteres (no retriage, o contexto após because pode ter até 20000 caracteres). As outras causas são um responsável (assignee) que não é um endereço de e-mail nem um @handle de até 100 caracteres, e um link ou ID de problema que não é um ID de problema válido do ZeroPath. Corrija essa parte e publique o comando novamente. O bot responde “I didn’t record a fix: …” O bot confere toda afirmação de fixed in com os commits do pull request e não registra nada quando não consegue confirmar o commit. A resposta diz o motivo: o commit não está neste PR, o SHA corresponde a mais de um commit (use um SHA mais longo), ou o PR tem mais commits do que o bot consegue verificar (use @ZeroPath closed because fixed in <sha>). Quando o bot não consegue carregar os commits do PR de forma alguma, ele responde com a mensagem genérica de erro interno; tente novamente em alguns minutos. O bot publicou a lista de comandos uma vez e depois parou de responder O Assistant está desabilitado para a sua organização, então o bot não consegue responder mensagens em formato livre. Ele publica a lista de comandos uma vez por fio (“The ZeroPath Assistant isn’t enabled for this organization…”; no GitHub ela inclui @ZeroPath allow) e permanece em silêncio nesse fio depois disso. O reconhecimento do bot no seu comentário continua mostrando que ele recebeu a sua mensagem: uma reação de olhos no GitHub e no GitLab, um like no Azure DevOps. O Bitbucket não tem reconhecimento. Comandos estruturados como @ZeroPath fp issue 2 because … continuam funcionando. Para receber respostas a perguntas em formato livre, peça a um administrador da organização para habilitar o Assistant. O bot responde “No matching issues found for that target.” O número de problema que você usou não corresponde a uma descoberta que o ZeroPath reportou neste PR. Verifique o comentário de resumo do PR para ver a lista de problemas reportados, ou use all issues in this pr. O bot responde “I can’t verify your ZeroPath identity…” A sua conta no VCS não está vinculada a um usuário do ZeroPath. No GitHub, a correção mais rápida é definir o seu e-mail público do GitHub (Settings > Public profile) para corresponder ao e-mail da sua conta do ZeroPath e então comentar novamente — o ZeroPath vinculará automaticamente as contas via correlação de e-mail. Você pode voltar o e-mail para privado depois; o vínculo persiste. No GitLab, o fallback de correlação de e-mail ainda não está implementado, então entre em contato com o admin da sua organização para vincular as contas em Teams, ou execute a ação a partir do dashboard do ZeroPath. assign reporta “no linked Jira/Linear ticket” A descoberta alvo ainda não foi enviada ao Jira ou ao Linear. Configure a integração do Jira ou do Linear com auto-ticketing, ou crie o ticket a partir do dashboard primeiro. O bot rejeitou meu comentário como conteúdo de prompt injection Reformule como uma pergunta direta sobre uma descoberta específica reportada, sem instruções formatadas como comandos de bot embutidas nela. O bot se recusou a modificar um PR de patch do GitHub O bot só faz commits diretamente em branches de PR que o ZeroPath criou para PRs de patch. Ele se recusa quando não consegue verificar a branch, o PR vem de um fork, a branch se moveu enquanto a solicitação estava sendo preparada, ou a mudança solicitada é insegura, ambígua, impossível, não relacionada ao patch ou não produz mudanças em arquivos.
Consulte Escaneamento de PRs para o recurso ao redor (status de verificação, comentários inline, comentários de resumo) e Auto-Fix para o que generate patch e approve patch realmente produzem.