Saltar para o conteúdo principal

Como Funciona

O escaneamento de PRs do ZeroPath analisa as mudanças de código nos seus pull requests e merge requests, capturando problemas de segurança antes que sejam mesclados. Os escaneamentos são executados automaticamente quando um PR é aberto ou atualizado, e os resultados aparecem diretamente no seu VCS.

Análise Focada no Diff

Apenas os arquivos alterados e o contexto ao redor são analisados — rápido e direcionado. Diffs grandes são tratados sem problemas: o agente de IA pode inspecionar diffs de arquivos específicos por meio de ferramentas em vez de exigir o diff inteiro inline, de modo que até pull requests muito grandes recebem análise completa baseada em agente.

Comparação Diferencial

Escaneia tanto a branch de destino quanto a branch do PR, exibindo apenas as descobertas novas no PR.

Ferramentas de Segurança em Paralelo

SAST, SCA, Secrets e IaC são executados simultaneamente no código alterado. Se a análise de IA atingir o tempo limite ou encontrar um erro, as descobertas das ferramentas concluídas de forma independente (como secrets e SCA) são preservadas.

Validação por IA

Cada descoberta é validada no contexto do diff para minimizar falsos positivos.

Plataformas Suportadas

Todas as quatro plataformas suportam o conjunto completo de recursos de escaneamento de PRs: acionamento automático, relatório de status e comentários inline de revisão de código.
Quer verificar se o seu PR corrige uma vulnerabilidade conhecida? Consulte Verificação de Correção para aprender como referenciar problemas na descrição do seu PR.

O Que É Analisado

O escaneamento de PRs é estritamente focado no diff. Ele não escaneia novamente toda a sua base de código a cada PR.
1

Buscar o Diff

Obtém o diff unificado da API do seu VCS (recorre a git diff se necessário). Quando a branch do PR não compartilha nenhum ancestral comum com a branch de destino (por exemplo, branches órfãs ou históricos com force push), o ZeroPath recorre automaticamente a uma comparação direta de árvores para que o escaneamento ainda possa prosseguir.
2

Identificar Arquivos Alterados

Mapeia cada hunk alterado para seu arquivo e números de linha.
3

Executar Ferramentas de Segurança em Paralelo

Apenas nos arquivos alterados:
  • SAST — análise estática em ambas as branches, de destino e do PR, exibindo apenas descobertas novas. Se a sua organização configurou regras SAST personalizadas em linguagem natural, essas regras também são aplicadas ao código alterado — as mesmas regras que rodam durante escaneamentos completos são aplicadas aos arquivos tocados pelo PR, de modo que violações são capturadas antes do merge.
  • SCA — análise de dependências quando manifests/lockfiles foram alterados (uma pré-triagem por IA pula a etapa se não for relevante)
  • Secrets — escaneia o diff em busca de credenciais hardcoded
  • IaC — verifica arquivos de infraestrutura alterados
4

Filtrar para Regiões Alteradas

Apenas descobertas que se sobrepõem diretamente às linhas efetivamente alteradas no diff são reportadas — não há margem de proximidade, então descobertas próximas mas não relacionadas são excluídas. Arquivos novos são incluídos integralmente; arquivos excluídos são descartados.
5

Validar e Reportar

A validação por IA remove falsos positivos. Quando um problema reportado anteriormente é reavaliado e determinado como falso positivo, ele pode ser resolvido automaticamente. Os resultados são publicados no seu VCS como status de verificação e comentários inline.Quando um PR é atualizado depois que um escaneamento anterior foi pulado (por exemplo, porque o diff anterior não era relevante para segurança), o ZeroPath exclui o escaneamento pulado da linha de base da atualização. Isso garante que a comparação incremental cubra o conjunto completo de mudanças do PR em vez de apenas a atualização mais recente.Descobertas que você confirmou como verdadeiros positivos por meio de investigação nunca são resolvidas automaticamente por escaneamentos de PR. Se uma descoberta confirmada estiver ausente em uma atualização de escaneamento de PR, ela é mantida em vez de marcada como resolvida, garantindo que vulnerabilidades confirmadas permaneçam visíveis até serem explicitamente tratadas.

Status de Verificação e Feedback

Os resultados são reportados por meio de vários canais:
Um status de verificação de aprovação/reprovação é publicado no seu PR. Isso se integra às regras de proteção de branch para que você possa exigir que as verificações do ZeroPath passem antes do merge.Para organizações que usam faturamento baseado em créditos, um escaneamento de PR pode ser pulado se a organização não tiver créditos suficientes. Quando isso ocorre, a verificação é marcada como falha com uma mensagem indicando o motivo e (se habilitado) um comentário é publicado no PR explicando por que o escaneamento não foi executado. Entre em contato com o administrador da sua organização para adicionar mais créditos.Quando você faz a triagem de um problema (por exemplo, marcando-o como falso positivo ou resolvido) em um PR que foi atualizado e reescaneado, o ZeroPath atualiza o status de verificação no commit head atual do PR, e não no escaneamento em que o problema foi originalmente detectado. Isso garante que as ações de triagem se reflitam imediatamente na verificação de proteção de branch que a sua equipe vê, mesmo depois que commits subsequentes foram enviados ao PR.

Bloqueando Pull Requests

O nome padrão da verificação do ZeroPath é ZeroPath Security Scan. Se a sua organização usa uma integração personalizada ou white-label, exija o nome exato da verificação que aparece em um PR de teste.

GitHub

Use as regras de proteção de branch do GitHub para exigir a verificação do ZeroPath antes do merge.
1

Crie um check run do ZeroPath

Habilite o escaneamento de PRs e Check status posting no ZeroPath, depois abra ou atualize um pull request de teste para que o GitHub tenha visto a verificação ZeroPath Security Scan pelo menos uma vez.
2

Abra a proteção de branch

No GitHub, acesse Settings > Branches do seu repositório, depois adicione ou edite a regra de proteção de branch para a branch que você deseja proteger, como main.
3

Exija a verificação do ZeroPath

Selecione Require status checks to pass before merging, procure por ZeroPath Security Scan e selecione-o. Se o GitHub pedir a origem esperada, escolha o GitHub App do ZeroPath em vez de “any source”.
4

Salve e teste

Salve a regra, envie um commit ao PR de teste e confirme que o GitHub bloqueia o merge até que a verificação do ZeroPath reporte sucesso.

Documentação de proteção de branch do GitHub

Veja os passos oficiais do GitHub para exigir status checks em uma regra de proteção de branch.

GitLab

Use as merge checks do GitLab para exigir que o pipeline que contém o status do ZeroPath seja bem-sucedido antes do merge.
1

Crie um status do ZeroPath

Habilite o escaneamento de PRs e Check status posting no ZeroPath, depois abra ou atualize um merge request de teste para que o GitLab mostre ZeroPath Security Scan no pipeline ou na área de status do merge request.
2

Abra as configurações de merge request

No GitLab, acesse o projeto e selecione Settings > Merge requests.
3

Exija pipelines bem-sucedidos

Em Merge checks, selecione Pipelines must succeed e salve suas alterações. O GitLab vai bloquear o merge até que o pipeline relevante, incluindo o status do ZeroPath, seja bem-sucedido.
4

Verifique o pipeline com gate

Envie um commit ao merge request de teste e confirme que o status ZeroPath Security Scan aparece no pipeline que o GitLab avalia para o merge request. Se você executa pipelines tanto de branch quanto de merge request, certifique-se de que o status do ZeroPath está anexado ao pipeline de merge request que o GitLab usa para o gate de merge.

Documentação de pipeline bem-sucedido do GitLab

Veja os passos oficiais do GitLab para exigir um pipeline bem-sucedido antes do merge.

Documentação de commit status externo do GitLab

Veja como o GitLab representa status de sistemas externos dentro de pipelines.

Bitbucket

Use as merge checks do Bitbucket para exigir build statuses bem-sucedidos antes do merge.
1

Crie um build status do ZeroPath

Habilite o escaneamento de PRs e Check status posting no ZeroPath, depois abra ou atualize um pull request de teste para que o Bitbucket mostre o build status ZeroPath Security Scan no commit mais recente.
2

Abra as restrições de branch ou merge checks

No Bitbucket Cloud, abra as configurações do repositório e acesse Branch restrictions em Workflow. No Bitbucket Data Center, abra Repository settings > Merge checks ou Repository settings > Required builds.
3

Exija builds bem-sucedidos

No Bitbucket Cloud, adicione uma restrição de branch para a branch protegida e habilite Minimum number of successful builds for the last commit with no failed builds. Defina o mínimo como pelo menos 1.
4

Aplique a merge check no Bitbucket Cloud

No Bitbucket Cloud Premium, habilite Prevent a merge with unresolved merge checks para que o requisito de build bem-sucedido bloqueie o merge. Sem essa configuração, o Bitbucket avisa os usuários sobre merge checks não resolvidas, mas ainda pode permitir o merge.
5

Exija o build do ZeroPath no Data Center

No Bitbucket Data Center, habilite Minimum successful builds ou adicione uma regra de Required builds para a chave de build do ZeroPath se a sua instância suportar required builds.
6

Salve e teste

Envie um commit ao PR de teste e confirme que o Bitbucket bloqueia o merge até que o commit mais recente tenha um build status bem-sucedido do ZeroPath.

Documentação de merge check do Bitbucket Cloud

Veja os passos oficiais do Bitbucket Cloud para exigir builds bem-sucedidos antes do merge.

Documentação de merge check do Bitbucket Data Center

Veja a documentação oficial de merge checks e required builds do Bitbucket Data Center.

Azure DevOps Services

Use as branch policies do Azure Repos para exigir o status do ZeroPath antes de concluir um pull request.
1

Crie um status do ZeroPath

Habilite o escaneamento de PRs e Check status posting no ZeroPath, depois abra ou atualize um pull request de teste para que o Azure DevOps Services receba o status ZeroPath Security Scan.
2

Abra as branch policies

No Azure DevOps Services, abra a página Repos > Branches do repositório, selecione a branch de destino e abra Branch policies.
3

Exija o status do ZeroPath

Adicione uma status policy para o contexto de status do ZeroPath usado no seu ambiente. Configure-a como obrigatória se a branch deve bloquear merges até que o escaneamento passe.
4

Salve e teste

Envie um commit ao pull request de teste e confirme que o Azure DevOps bloqueia a conclusão até que o status do ZeroPath reporte sucesso.
Escaneamentos de PR no Azure DevOps exigem uma conexão do Azure DevOps Services no ZeroPath. Consulte o guia de integração do Azure DevOps para a configuração de OAuth e PAT.

Comandos do Bot

Você pode controlar o ZeroPath diretamente do seu PR ou merge request mencionando o bot em um comentário — fazer triagem de descobertas, atribuir tickets, gerar patches, reescanear, fazer bypass de verificações ou fazer perguntas em linguagem natural. O bot confirma o recebimento imediatamente e atualiza o mesmo comentário no lugar quando a ação é concluída. Quando o trabalho termina, o ZeroPath também publica uma resposta de acompanhamento no mesmo fio com um resumo do resultado (ou uma mensagem de erro se o trabalho falhou), de modo que o desfecho fica visível inline sem precisar navegar até o dashboard. Alguns exemplos comuns:
PR comment
O comando rescan force ignora o cache e executa um escaneamento completo em vez de uma atualização incremental, mesmo que um escaneamento para o commit atual já exista. Isso é útil quando você quer reanalisar o PR inteiro do zero em vez de construir sobre resultados anteriores. O comando bypass sobrepõe uma verificação de PR do ZeroPath que está falhando para que ela não bloqueie mais o merge. No GitHub, o bot orienta você a usar o botão Bypass Check no check run, na aba de checks do PR. No Azure DevOps, o bot executa o bypass diretamente, marcando os escaneamentos do PR como bypassed e publicando um status succeeded, liberando o gate de merge da branch policy. O comando bypass exige a permissão Bypass PR Check. Quando um comando inclui um alvo explícito (como issue 2), esse alvo sempre tem prioridade — mesmo que o comando seja publicado como resposta sob o fio de comentários de outra descoberta. O contexto do fio é usado como fallback apenas quando nenhum alvo está escrito no texto do comando. Por exemplo, @ZeroPath fp issue 2 publicado como resposta sob o fio do issue 5 vai agir sobre o issue 2, não sobre o issue 5. Para a referência completa de comandos — cada palavra-chave, alias, forma de alvo, o modificador because, requisitos de RBAC e suporte de plataformas — consulte Comandos do Bot. Quando você altera o status de um problema por meio de um comando do bot, uma notificação de vulnerability status changed é enviada pelos seus canais de notificação configurados. A notificação inclui o status anterior, o novo status e quem fez a mudança, para que a sua equipe tenha visibilidade total das decisões de triagem feitas a partir de comentários de PR.
Os comandos do bot são suportados no GitHub, GitLab e Azure DevOps. O Bitbucket suporta escaneamento de PRs, mas ainda não comandos do bot. No Azure DevOps, você pode usar comandos como @zeropath rescan, @zeropath bypass e outros comandos de triagem diretamente dos comentários do PR. Use @ZeroPath como alias universal, ou substitua-o pelo nome de usuário do bot configurado no seu ambiente.
Comentários que parecem conter conteúdo de prompt injection são bloqueados automaticamente. Se você receber uma mensagem de rejeição, reformule a sua pergunta como uma consulta direta sobre o problema reportado.
Os comandos do bot devem vir de uma conta humana. Comentários de contas de bot (incluindo outros GitHub Apps) são ignorados automaticamente para evitar loops de feedback e garantir que cada comando seja atribuível a um usuário real.
Quando o bot responde perguntas sobre descobertas de secrets, o valor bruto do secret é automaticamente mascarado na resposta. O assistente recebe e publica apenas a forma redigida, de modo que credenciais em texto claro nunca são ecoadas de volta nos comentários do seu pull request.
Quando a sua organização tem o controle de acesso habilitado, os comandos do bot exigem que a sua conta no VCS esteja vinculada a um usuário do ZeroPath. No GitHub, você pode vincular a sua conta definindo o seu e-mail público do GitHub (Settings → Public profile) para corresponder ao e-mail da sua conta do ZeroPath e, em seguida, comentando em um PR. O vínculo é salvo permanentemente, então você pode voltar o e-mail para privado depois. No GitLab, entre em contato com o admin da sua organização para vincular a sua conta. Quando o controle de acesso está desabilitado, qualquer pessoa com acesso a comentários no PR pode usar os comandos do bot e o assistente de IA sem vincular uma conta.
Se o PR referenciar vulnerabilidades específicas usando tags ZP-ID ou URLs de issues do dashboard (consulte Verificação de Correção), retriage executa novamente a verificação de correção contra o código mais recente do PR em vez do fluxo padrão de investigação. Isso verifica se as mudanças atuais do PR realmente resolvem os problemas referenciados. Se uma verificação de correção já estiver em andamento para o PR, o bot avisará você em vez de criar uma duplicata.

Configuração

Todas as configurações de escaneamento de PRs seguem uma cascata de herança Organização → Tag → Repositório. Sobrescritas no nível do repositório têm precedência.

Compatibilidade com Merge Queue do GitHub

Se você usa merge queues do GitHub, o ZeroPath trata eventos de merge-group automaticamente. Quando um pull request entra na merge queue, o GitHub cria um commit de merge temporário e solicita status checks nele. Como o PR já foi escaneado quando foi aberto ou atualizado, o ZeroPath não escaneia novamente o commit de merge. Em vez disso, ele publica uma verificação neutral no head SHA do merge-group, que a merge queue trata como aprovada. Isso garante que a sua merge queue não fique travada esperando por uma verificação do ZeroPath que nunca chegaria. Nenhuma configuração adicional é necessária — se o seu GitHub App tem a permissão de leitura de Merge queues e a assinatura do evento merge_group, a compatibilidade com merge queue funciona sem ajustes. GitHub Apps recém-criados pelo fluxo de configuração do ZeroPath incluem essas permissões automaticamente.
Se você estiver usando um GitHub App existente que foi criado antes de o suporte a merge queue ser adicionado, pode ser necessário aceitar as permissões atualizadas nas configurações do seu GitHub App para habilitar a assinatura do evento merge_group.

Sincronização Automática de Repositórios (GitHub)

O ZeroPath mantém automaticamente os metadados do seu repositório sincronizados quando mudanças acontecem no GitHub. Os seguintes eventos são detectados e tratados em tempo real via webhooks:
Nenhuma ação manual é necessária — essas mudanças se propagam automaticamente desde que o GitHub App do ZeroPath esteja instalado.

Azure DevOps

O ZeroPath também detecta eventos de renomeação e exclusão de repositórios no Azure DevOps via service hooks:

Como o Escaneamento de PRs Difere de Escaneamentos Completos

Guia de Adoção

1

Habilite o Escaneamento de PRs

Ative-o nas configurações de scanner do seu repositório.
2

Instale a Integração com o VCS

Garanta que o seu GitHub App, app do GitHub Enterprise Server, instalação do GitLab, integração do Bitbucket ou conexão do Azure DevOps esteja configurado.
3

Abra um PR

O ZeroPath vai escaneá-lo automaticamente e publicar os resultados.
4

Configure a Proteção de Branch

Adicione a verificação do ZeroPath como status check obrigatório nas regras de proteção de branch do seu VCS.
5

Ajuste os Limites

Ajuste o check failure threshold e o result inclusion threshold para corresponder à tolerância da sua equipe.
6

Revise os Comentários Inline

Trate as descobertas diretamente no seu fluxo de revisão de código.