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

O ZeroPath analisa os arquivos alterados e consulta o código relacionado para obter contexto. Pull requests grandes estão sujeitos aos limites de escaneamento.

Comparação Diferencial

O ZeroPath compara o PR com o branch de destino. Quando confirma que uma movimentação de código deixou um achado existente inalterado, ele o omite dos resultados do 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.
GitLab: Scans automáticos de MRs exigem a entrega de um webhook e um pipeline para o commit escaneado. O acesso Reporter precisa de um webhook de projeto configurado manualmente, um pipeline existente e Check status posting desabilitado. A publicação de status exige Developer ou Maintainer; Maintainer também permite configurar webhooks de projeto automaticamente. Veja o guia de integração com GitLab para a seleção de pipelines e os requisitos completos de acesso.
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.
Para aplicar políticas de risco de dependências no GitHub, consulte a verificação Supply Chain Intel. Para revisar a configuração dos pipelines e os controles de merge, consulte Segurança de CI/CD. Para revisar sinais de autoria com IA em pull requests, consulte Code Governance.

Primeira conexão com o GitHub

Na primeira conexão da organização com o GitHub, o ZeroPath pode analisar PRs abertos e atualizados recentemente, assim que o escaneamento de PRs estiver habilitado. São elegíveis os repositórios conectados pelo GitHub App nas primeiras 24 horas. O ZeroPath analisa os PRs atualizados nas últimas 24 horas, começando pelos mais recentes, até 10 por repositório e 50 por organização. Consulte os achados no ZeroPath. Quando a publicação de checks está habilitada, o escaneamento inicial contribui com um resultado neutro para o check do GitHub. Ele pode publicar um resumo de achados se essa opção estiver habilitada. Comentários inline e resumos sem achados ficam para os escaneamentos regulares.

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. Quando há contexto da aplicação, o ZeroPath o usa para entender as mudanças nos arquivos relevantes. As descrições geradas pelo ZeroPath ajudam a explicar a aplicação. Suas regras configuradas definem as políticas que o scan verifica.
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 — compara o código alterado com o branch de destino e valida os achados com as evidências disponíveis. O ZeroPath confirma violações de regras personalizadas em linguagem natural com base no texto da própria regra, inclusive para requisitos internos sem um meio de exploração.
  • SCA — analisa alterações de dependências em manifests e lockfiles quando são relevantes para o PR. Para dependências privadas, consulte Registros privados (em inglês).
  • 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.O ZeroPath usa análises concluídas como base para atualizações incrementais. Depois de uma análise ignorada ou incompleta, o ZeroPath analisa todo o diff do PR quando não há uma revisão anterior adequada.Quando uma atualização concluída deixa de detectar um achado de SAST confirmado no mesmo PR, o ZeroPath pode verificar a correção automaticamente. O achado permanece aberto até o ZeroPath confirmar uma correção no código ou alguém resolvê-lo.

Status de Verificação e Feedback

Os resultados são reportados por meio de vários canais:
Quando a publicação de checks está habilitada, o ZeroPath informa o resultado no PR. Use as regras de proteção de branch da sua plataforma para exigir o check 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.

Checks compartilhados no GitHub

Quando vários escaneamentos do ZeroPath contribuem para o mesmo check em um commit, como em partições de um monorepo, o check fica em andamento até a conclusão dos escaneamentos vinculados. Um achado confirmado que atingiu o limiar de falha mantém o check reprovado mesmo que os outros escaneamentos passem. Se um escaneamento anterior encontrou achados bloqueantes, eles continuam valendo quando um novo escaneamento do mesmo commit é cancelado, atinge o tempo limite ou termina com erro.

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, adicione uma regra de Required builds para a chave de build ZeroPath Security Scan ou habilite Minimum successful builds. Um scan ignorado, com falha ou que excede o tempo limite publica um build Cancelled (Failed no Data Center anterior à 8.0, que não tem o estado Cancelled). Esse não é um build bem-sucedido, então uma regra de Required builds mantém o merge bloqueado até que um scan do commit mais recente chegue a um veredito. Isso inclui pull requests que não alteram arquivos dentro das partições de diretório configuradas, que são ignorados. O ZeroPath publica build statuses pela API de build status do repositório, que exige o Bitbucket Data Center 7.4 ou mais recente.
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.

Revisões de segurança incompletas ou ignoradas

  • Se apenas parte da revisão for concluída, o check ainda pode publicar um resultado com base nos achados que conseguiu avaliar. Achados anteriores podem ficar em aberto até que um scan posterior verifique o status deles. Execute o scan novamente se precisar de uma nova revisão da alteração.
  • Security review skipped por limite de tamanho indica que a revisão do PR terminou sem um parecer de segurança. Divida a alteração em PRs menores para que sejam analisados.

Comandos do Bot

Mencione o bot em um comentário do PR ou merge request para fazer a triagem de achados, solicitar um patch, executar um novo scan ou fazer uma pergunta ao Assistente. Nas plataformas compatíveis, o bot confirma o recebimento e publica o resultado quando concluir. Respostas como Fixed in <sha> e Accepted risk: <reason> também podem funcionar sem menção na conversa do próprio achado. Consulte a referência de comandos para ver as plataformas e permissões. 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 estão disponíveis no GitHub, GitLab e Azure DevOps. O Bitbucket Cloud e Data Center aceitam um subconjunto de comandos. Consulte a tabela de plataformas para ver os comandos disponíveis e os requisitos de versão.
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 Merge queues (leitura ou escrita) 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

Abra o repositório, selecione Settings → Pull requests e ative Pull Request Scanning.
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.