- Guia de revisão de código do Agents Please: Use um processo repetível para revisões de pull requests assistidas por IA.
- Primeira prioridade: Confirme o escopo, as permissões, os segredos e a revisão exata sob análise.
- Melhor fluxo de trabalho: Faça uma varredura ampla, rastreie fluxos de dados arriscados e valide as descobertas manualmente.
- Principal alerta: Trate as descobertas geradas como hipóteses até que um desenvolvedor as reproduza.
- Verificação final: Exija testes, revisão do patch e cobertura de regressão antes da aprovação.
Guia de revisão de código do Agents Please: escopo e segurança
O guia de revisão de código do Agents Please foi criado para equipes que usam um agente de IA para inspecionar pull requests, repositórios ou amostras de código isoladas. O objetivo não é substituir os revisores. É tornar a preparação da revisão mais rápida, destacar caminhos sensíveis à segurança e fornecer aos engenheiros uma lista mais clara de questões para investigar.
Comece com um limite de revisão restrito. Identifique a branch, o commit, os arquivos alterados, as linguagens de programação, os comandos de teste e os diretórios aos quais o agente poderá acessar. Um escopo limitado facilita a auditoria dos resultados e reduz a chance de que código legado não relacionado sobrecarregue a revisão.
Nunca forneça credenciais de produção, chaves privadas, registros de clientes ou acesso irrestrito ao shell apenas para melhorar a cobertura da revisão. Use um checkout descartável, tokens com o menor privilégio possível e fixtures sanitizadas sempre que possível.
Limites da revisão
| Item da revisão | Decisão recomendada | Por que isso importa |
|---|---|---|
| Commit ou pull request | Registre uma revisão exata | Evita que as descobertas mudem conforme o código é alterado |
| Escopo de arquivos | Inclua os arquivos alterados e suas dependências diretas | Equilibra o contexto com uma saída gerenciável |
| Segredos | Remova, revogue ou mascare-os | Limita a exposição acidental |
| Ferramentas | Permita primeiro pesquisas somente leitura | Reduz modificações não intencionais |
| Comandos de teste | Aprove apenas comandos seguros e determinísticos | Evita scripts destrutivos e efeitos colaterais de rede |
O que uma revisão útil deve responder
Uma revisão sólida assistida por IA deve ajudar a responder a cinco perguntas:
- O que mudou e qual comportamento foi afetado?
- Onde uma entrada não confiável entra no sistema?
- Quais funções, serviços ou permissões recebem essa entrada?
- Que evidências sustentam cada problema relatado?
- Que teste ou patch reduziria o risco?
Um relatório que apenas lista preocupações genéricas é menos útil do que um relatório mais curto com caminhos de arquivos, símbolos afetados, raciocínio sobre o fluxo de dados e uma etapa prática de verificação.
Escopo
- Commit exato
- Arquivos alterados
- Dependências relacionadas
- Exclusões da revisão
Segurança
- Tratamento de segredos
- Limites de permissão
- Fronteiras de entrada
- Chamadas externas
Evidências
- Arquivo e linha
- Caminho de reprodução
- Nível de confiança
- Premissas
Resolução
- Patch sugerido
- Teste de regressão
- Responsável
- Status da verificação
Prepare uma revisão assistida por IA
A preparação determina se um agente produzirá uma análise acionável ou uma coleção ruidosa de suposições. Antes de começar, escreva um breve resumo da revisão em linguagem simples. Inclua o objetivo da funcionalidade, as fronteiras de confiança esperadas, as operações sensíveis conhecidas e as áreas que não devem ser modificadas.
Para um serviço web, o resumo pode identificar autenticação, autorização, uploads de arquivos, tarefas em segundo plano, requisições a terceiros, gravações no banco de dados e integrações com modelos ou prompts. Para uma biblioteca, ele pode enfatizar parsers inseguros, serialização, alterações de dependências e compatibilidade da API pública.
Peça ao agente para explicar como a entrada percorre o caminho entre a origem e o destino. Isso geralmente é mais valioso do que pedir que ele “encontre todos os bugs”, porque a instrução mais específica produz evidências que um revisor pode contestar.
Modelo de resumo da revisão
| Seção do resumo | Exemplo de conteúdo | Benefício para a revisão |
|---|---|---|
| Objetivo da funcionalidade | Adiciona alertas de webhook configuráveis pelo usuário | Define o comportamento pretendido |
| Fronteiras de confiança | As configurações do usuário chegam a um cliente HTTP de saída | Destaca um possível risco de SSRF |
| Ativos sensíveis | Tokens, dados de tenants, metadados internos | Estabelece o impacto |
| Verificações necessárias | Autorização, validação de URL, tratamento de erros | Cria uma checklist focada |
| Verificação | Testes unitários e requisições de rede simuladas | Define os critérios de conclusão |
Um conjunto prático de instruções
Use instruções que separem descoberta, raciocínio e relatório:
- Mapeie o código alterado e seus chamadores diretos.
- Identifique entradas externas, dados sensíveis, operações privilegiadas e requisições de rede.
- Rastreie valores suspeitos durante validação, transformação, armazenamento e saída.
- Relate apenas problemas sustentados por evidências no código.
- Diferencie defeitos confirmados, preocupações plausíveis e dúvidas para o autor.
- Sugira testes sem aplicar alterações, a menos que isso seja explicitamente autorizado.
Essa estrutura também ajuda a evitar uma falha comum: o agente percebe um padrão perigoso, mas não verifica se um validador, controle do framework ou permissão anterior já impede a exploração.
Congele o alvo da revisão
Registre o repositório, a branch, o hash do commit e a lista de arquivos alterados. Se o pull request mudar durante a análise, reinicie o processo ou marque claramente a nova revisão.
Descreva o modelo de confiança
Identifique usuários anônimos, usuários autenticados, administradores, contas de serviço, workers em segundo plano e sistemas de terceiros. Informe quais funções podem acessar cada operação afetada.
Defina os destinos de alto risco
Destaque consultas ao banco de dados, parsers de arquivos, renderização de templates, requisições de saída, comandos do shell, desserialização, uso de credenciais e verificações de permissão.
Solicite descobertas baseadas em evidências
Exija um caminho, símbolo ou intervalo de linhas, origem da entrada, operação perigosa, impacto, nível de confiança e um método de verificação sugerido para cada descoberta.
Revise a saída manualmente
Reproduza as alegações importantes, inspecione o código próximo, verifique os controles existentes e decida se o problema é válido, mitigado ou incorreto.
Priorize as descobertas e rastreie o fluxo de dados
A revisão de código com IA se torna mais eficaz quando as descobertas são classificadas por explorabilidade e impacto, e não pelo quão alarmante sua redação parece. Um comentário ausente e uma requisição controlada pelo usuário no lado do servidor não devem receber a mesma atenção.
Comece pelos caminhos que conectam entradas não confiáveis a comportamentos privilegiados ou visíveis externamente. Exemplos comuns incluem parâmetros de requisição chegando a consultas de banco de dados, conteúdo enviado chegando a parsers, URLs configuráveis chegando a clientes HTTP ou texto do usuário sendo inserido em instruções para outro modelo.
Um problema de alta confiança pode ter impacto limitado, enquanto um problema grave pode permanecer não confirmado até que o ambiente seja compreendido. Acompanhe a confiança e o impacto separadamente no relatório.
Classificação das descobertas
| Tipo de descoberta | Padrão de evidência | Ação do revisor |
|---|---|---|
| Defeito confirmado | Caminho claro e controle ausente | Reproduzir, corrigir e adicionar cobertura de regressão |
| Preocupação provável | Padrão forte, mas contexto incompleto | Inspecionar dependências e a lógica ao redor |
| Questão de design | O comportamento pode ser intencional | Pedir ao responsável que esclareça o modelo de confiança |
| Falso positivo | Um controle existente bloqueia o caminho | Documentar o controle e encerrar a descoberta |
| Informativo | Problema de manutenibilidade ou reforço de segurança | Programar de acordo com as prioridades da equipe |
Matriz de triagem de riscos
| Impacto | Confiança | Prioridade |
|---|---|---|
| Alto | Alta | Investigação imediata |
| Alto | Média | Validar antes do merge |
| Médio | Alta | Corrigir na alteração atual quando for prático |
| Médio | Baixa | Solicitar mais contexto |
| Baixo | Qualquer | Agrupar com o trabalho de manutenção |
Ao revisar uma suposta vulnerabilidade, peça ao agente que mostre a cadeia completa:
- Origem: Onde o valor se origina?
- Transformação: Ele é decodificado, analisado, concatenado ou normalizado?
- Controle: Que validação, autorização, codificação ou allowlist se aplica?
- Destino: Qual operação usa o valor?
- Impacto: O que um invasor ou usuário com comportamento inesperado poderia causar?
- Verificação: Que teste seguro demonstra a alegação?
Por exemplo, uma requisição de saída não é automaticamente um problema de falsificação de requisição do lado do servidor. O revisor deve estabelecer se um invasor pode influenciar o destino, se endereços privados ou de metadados estão acessíveis, se os redirecionamentos são controlados e se a aplicação possui uma política de destinos aprovados.
Da mesma forma, uma string inserida em um prompt não é automaticamente uma injeção de prompt bem-sucedida. A revisão deve identificar a fronteira do modelo, a autoridade da saída gerada, as ferramentas disponíveis e se o conteúdo não confiável está claramente separado das instruções do sistema.
Revise padrões sensíveis à segurança
Uma revisão focada deve examinar padrões que frequentemente geram defeitos sem presumir que toda ocorrência seja explorável. As categorias a seguir são pontos de partida úteis para um fluxo de trabalho do Agents Please.
Use valores inofensivos de prova de conceito e redija tokens, dados pessoais, nomes de host internos e comandos destrutivos. Um relatório de revisão deve demonstrar o risco sem se transformar em uma receita de ataque.
| Padrão | Perguntas a fazer | Sinal de revisão mais seguro |
|---|---|---|
| Requisição HTTP de saída | Os usuários podem controlar o esquema, host, porta ou redirecionamentos? | Destinos validados e acesso de rede restrito |
| Consulta ao banco de dados | A entrada é vinculada como dado ou concatenada ao texto da consulta? | Consultas parametrizadas e permissões restritas |
| Upload de arquivo | O tipo, tamanho, nome e local de armazenamento são limitados? | Nomes aleatórios, armazenamento isolado e análise segura |
| Saída de template ou HTML | O conteúdo não confiável é codificado para o contexto de saída? | Escape com reconhecimento de contexto e renderização segura |
| Verificação de autorização | O acesso é verificado no servidor para cada objeto? | Política centralizada e validação de propriedade |
| Construção de prompt | Um texto não confiável pode ultrapassar os limites da tarefa? | Conteúdo delimitado, ferramentas restritas e validação da saída |
| Desserialização | Dados controlados por um invasor podem selecionar classes ou comportamentos? | Formatos seguros e esquemas explícitos |
| Contexto de tenant ou conta | Um chamador pode escolher diretamente outro escopo? | Contexto derivado do servidor e verificações de autorização |
Padrões para revisão de patches
Uma correção proposta deve tratar a causa, em vez de apenas esconder o sintoma relatado. Verifique se ela:
- Valida a entrada na fronteira de confiança correta.
- Preserva o comportamento esperado para usuários legítimos.
- Aplica autorização a todos os caminhos de código relevantes.
- Trata falhas sem vazar detalhes sensíveis.
- Inclui um teste de regressão que falharia sem a correção.
- Evita introduzir um segundo bypass por endpoints alternativos ou tarefas em segundo plano.
Controles de entrada
Valide formato, tamanho, codificação e valores permitidos antes de operações perigosas.
Controles de acesso
Derive a identidade e o escopo a partir de um contexto confiável do servidor e, em seguida, aplique permissões no nível do objeto.
Controles de saída
Codifique, filtre, restrinja ou revise os dados antes de retorná-los aos usuários, interpretadores ou serviços externos.
Conclua a revisão e acompanhe as correções
A revisão não termina quando o agente produz um relatório. Ela termina quando a equipe decide quais descobertas são válidas, atribui responsáveis, aplica as correções adequadas e verifica se a alteração funciona com segurança.
Mantenha as descobertas aceitas separadas das questões não resolvidas. Isso evita que um relatório longo esconda a pequena quantidade de problemas que bloqueiam o lançamento. Também cria um histórico útil para futuros revisores que possam encontrar o mesmo caminho de código.
Aprove somente depois que as descobertas importantes tiverem uma disposição: corrigidas, mitigadas, aceitas com um responsável ou encerradas com evidências documentadas. “O agente disse que é seguro” não é uma disposição suficiente.
Tabela de conclusão da revisão
| Etapa | Evidência necessária | Sinal de conclusão |
|---|---|---|
| Descoberta | Escopo e mapa dos arquivos alterados | O revisor entende a alteração |
| Análise | Descobertas com caminhos e raciocínio | As alegações podem ser contestadas |
| Triagem | Rótulos de impacto e confiança | As prioridades estão claras |
| Correção | Patch e teste de regressão | A causa raiz foi tratada |
| Verificação | Testes, verificações manuais ou reprodução segura | A correção funciona conforme o esperado |
| Encerramento | Responsável, status e justificativa | O registro da revisão é auditável |
Checklist de conclusão da revisão de código:
- Confirme o commit exato e o escopo da revisão
- Remova segredos e restrinja as permissões do agente
- Rastreie entradas não confiáveis até operações sensíveis
- Classifique as descobertas por impacto e confiança
- Verifique as correções com testes ou reprodução segura
- Registre os riscos aceitos e o trabalho de acompanhamento pendente
Um relatório final útil é conciso, mas específico. Para cada problema aceito, inclua o componente afetado, o risco, as evidências, a correção recomendada, o responsável e o status da verificação. Para cada problema rejeitado, registre o controle ou a premissa que o tornou inválido. Isso reduz investigações repetidas durante pull requests posteriores.
Se o mesmo falso positivo aparecer com frequência, melhore as instruções da revisão ou adicione orientações ao repositório. Se o mesmo defeito real aparecer repetidamente, invista em um helper compartilhado, um controle do framework, uma regra de lint, um fixture de teste ou uma alteração arquitetural, em vez de depender de detecção manual repetida.
Salve exemplos curtos de descobertas aceitas, descobertas rejeitadas e correções preferidas. Com o tempo, esses exemplos tornam as instruções futuras para o agente mais precisas e ajudam os revisores humanos a calibrar seu julgamento.
FAQ: fluxos de trabalho de revisão de código do Agents Please
Q: Qual é a maneira mais segura de iniciar um fluxo de trabalho do guia de revisão de código do Agents Please?
Comece com um checkout descartável, um commit exato, ferramentas somente leitura, dados sanitizados e um escopo restrito de arquivos. Peça ao agente para mapear a alteração antes de solicitar descobertas de segurança.
Q: Uma vulnerabilidade gerada por IA deve bloquear um pull request imediatamente?
Não por si só. Trate o relatório como uma hipótese e verifique o fluxo completo de dados, os controles existentes, a explorabilidade e o comportamento esperado. Bloqueie somente depois que um revisor qualificado confirmar o risco ou que a equipe adote uma política documentada.
Q: Como as preocupações com injeção de prompt devem ser revisadas?
Identifique qual conteúdo não é confiável, onde ele entra no prompt, que autoridade o modelo possui, quais ferramentas ou ações estão disponíveis e como as saídas são validadas. O risco depende da fronteira completa do sistema, não apenas da interpolação de strings.
Q: O que torna uma descoberta de revisão de código acionável?
Uma descoberta acionável identifica o arquivo ou símbolo afetado, explica o caminho da entrada ao destino, descreve um impacto realista, informa o nível de confiança, propõe uma correção direcionada e inclui um método seguro de verificação.
Use a IA para ampliar a cobertura da revisão e organizar as evidências, mas mantenha o controle do escopo, as decisões de risco e a aprovação final com engenheiros humanos responsáveis.