Modos de localização do CodeMender

O CodeMender oferece três modos de verificação distintos usando o comando cm find. Cada modo é projetado para uma etapa específica do ciclo de vida de desenvolvimento de software, equilibrando velocidade, escopo e profundidade.

Comparar modos de localização

A tabela a seguir compara os três modos de verificação cm find:

Modo Comando Escopo de destino Tempo de execução típico Ideal para
Verificação padrão cm find PATH Diretório especificado Tempo de execução moderado Descoberta de desenvolvedores locais, verificações rápidas, análises exploratórias
Verificação de diferenças cm find PATH --diff[=REF] Arquivos modificados e arquivos dependentes (como chamadores e chamados) Tempo de execução rápido Pipelines de CI/CD de solicitação de pull (GitHub Actions, Cloud Build), hooks de pré-commit
Verificação avançada cm find PATH --deep Repositório inteiro Tempo de execução mais longo Auditorias programadas, preparação para lançamento, certificações de compliance (SOC 2, ISO)

Verificação padrão (padrão)

Uma verificação padrão é o modo padrão quando você executa cm find sem fornecer flags de verificação adicionais. Ele executa uma verificação autônoma de sessão única do diretório de destino especificado. Durante a verificação, o CodeMender descobre arquivos de origem, prioriza com base em padrões de vulnerabilidade, realiza uma análise de segurança inicial e informa possíveis vulnerabilidades agrupadas por gravidade e tipo.

Os exemplos a seguir mostram como executar uma verificação padrão em um diretório de destino:

# Scan a directory using the default model
cm find ./src

# Scan with a specific Gemini model
cm find ./src --model gemini-3.8-flash

Pontos fortes

Uma verificação padrão funciona sem configuração e sem flags ou parâmetros extras. Ele equilibra velocidade e cobertura com um tempo de execução moderado e usa o mínimo de tokens e computação, o que o torna econômico para o desenvolvimento diário.

Vantagens, desvantagens e limitações

Uma verificação padrão tem recall menor em grandes bases de código e pode não analisar todos os arquivos em repositórios empresariais grandes e com vários pacotes porque opera em um único contexto de sessão. Ele também se concentra principalmente em padrões locais em arquivos individuais, o que limita a análise entre pacotes e pode perder vulnerabilidades que abrangem pacotes distantes.

Quando usar

Use uma verificação padrão nos seguintes cenários:

  • Execute uma verificação na sua máquina local antes de confirmar as mudanças para receber feedback rápido durante o desenvolvimento local.
  • Inspecione um repositório recém-clonado ou um projeto pequeno para uma avaliação inicial da postura de segurança.
  • Inspecione um submódulo ou subdiretório específico ao investigar um possível problema.

Verificação de diferenças

Uma verificação de diff realiza a análise de diff do Git para fluxos de trabalho de solicitação de envio e pipelines de CI/CD inspecionando arquivos modificados e adicionados, com foco nos intervalos de linha exatos (diff hunks) que foram alterados. Além de inspecionar as linhas alteradas, ele realiza uma análise de impacto para descobrir arquivos não modificados no repositório que chamam, importam ou dependem das funções e símbolos modificados. Isso ajuda a garantir que as mudanças que alteram contratos ou assinaturas de função em um arquivo não introduzam vulnerabilidades em arquivos dependentes.

Durante a verificação, o CodeMender isola automaticamente as vulnerabilidades preexistentes no código intocado para que problemas legados não causem falha na verificação nem bloqueiem a solicitação de envio. Em seguida, ele avalia os resultados em relação à sua política de --fail-on e gera resultados em formato de tabela, JSON ou SARIF v2.1.0.

Os exemplos a seguir mostram como executar uma verificação de diff em relação a mudanças na cópia de trabalho, mudanças preparadas ou uma ramificação de destino:

# Scan working copy changes versus HEAD
cm find . --diff

# Scan staged changes only (pre-commit)
cm find . --diff --staged

# Scan a pull request branch against the main branch in CI/CD
cm find . --diff=origin/main --format=sarif --output=results.sarif \
    --fail-on=CRITICAL,HIGH

Para configurações de pipeline de ponta a ponta, consulte Integrar com CI/CD.

Pontos fortes

Uma verificação de diff é rápida e determinista, geralmente terminando em menos de 2 minutos para manter os tempos de execução do pipeline de CI/CD curtos. Ao contrário dos verificadores de diff que inspecionam apenas linhas alteradas, o --diff inspeciona as relações entre chamador e chamado para detectar regressões de segurança e violações de contrato entre arquivos. Como ele suprime descobertas em código não modificado, a verificação só bloqueia solicitações de pull em problemas introduzidos ou afetados pelas mudanças, evitando relatórios ruidosos e falhas de build desnecessárias. Uma verificação de diff também emite SARIF v2.1.0 para integração direta em anotações da verificação de código do GitHub e painéis do Cloud Build.

Vantagens, desvantagens e limitações

Uma verificação de diff analisa apenas o código na área afetada da solicitação de envio e não encontra vulnerabilidades preexistentes em partes intocadas do repositório. Ele também exige um repositório Git com acesso à referência da base de destino.

Quando usar

Use uma verificação de diff nos seguintes cenários:

  • Execute verificações automatizadas em todas as solicitação de envio em pipelines de CI/CD, como GitHub Actions, Cloud Build, GitLab CI ou Jenkins.
  • Verifique se as mudanças locais estão limpas nos hooks pre-commit ou pre-push antes de enviar o código para o repositório remoto.
  • Valide se as fusões entre ramificações de lançamento não introduzem regressões.

Verificação avançada

Uma verificação completa é um modo exaustivo projetado para auditorias de segurança abrangentes em todo o repositório. Ele audita arquivos de origem em todo o repositório simultaneamente usando workers paralelos (configurados com --deep-workers, que tem como padrão 8 e oferece suporte a um intervalo de 1 a 16). À medida que descobre possíveis descobertas, ele as valida e confirma em relação ao contexto de código ao redor para filtrar falsos positivos antes de gerar relatórios de resultados.

Os exemplos a seguir demonstram como executar uma verificação completa em um repositório:

# Run an exhaustive deep scan across the entire repository
cm find . --deep

# Tune concurrency and use the cyber-specialized security model
cm find . --deep --deep-workers=8 --model=gemini-3.8-flash-cyber

Pontos fortes

Uma verificação completa oferece alta capacidade de recall e descoberta abrangente de vulnerabilidades em grandes bases de código corporativas, superando as verificações de sessão única e usando a verificação automatizada para manter alta precisão. Ele é compatível com vários idiomas e é independente de plataforma, funcionando em todos os idiomas aceitos pelo Gemini sem exigir compiladores, configurações de build ou arquivos de gramática específicos de cada idioma. Ele também otimiza o uso de recursos ao concentrar a análise no código de produção e minimizar o consumo de computação e tokens em arquivos que não são de produção.

Vantagens, desvantagens e limitações

Não use uma verificação completa como uma verificação síncrona que bloqueia solicitações de envio. As verificações detalhadas fazem uma análise completa em todo o repositório. Por isso, eles exigem um tempo de execução mais longo e um gasto de token maior do que as verificações padrão ou de diferenças.

Quando usar

Use uma verificação completa nos seguintes cenários:

  • Execute auditorias de segurança programadas diariamente ou semanalmente em todos os repositórios de produção.
  • Faça uma auditoria de segurança completa antes de lançamentos de versões principais ou implantações de produção.
  • Gerar evidências de auditoria para revisões de conformidade e certificação da SOC 2, ISO 27001, FedRAMP ou PCI-DSS.
  • Estabeleça um valor de referência de segurança inicial ao integrar uma nova base de código ao CodeMender.

Escolher um modo de pesquisa

Use a tabela de referência a seguir para selecionar o modo de verificação adequado ao seu fluxo de trabalho:

Fluxo de trabalho ou ambiente Caso de uso e meta Modo recomendado Exemplo de comando
Terminal local Descoberta rápida ou verificação de confiança em um módulo específico Verificação padrão cm find ./src
Terminal local Verificação de pré-commit em mudanças preparadas antes do push Verificação de diferenças cm find . --diff --staged
Pipeline de CI/CD Controle automatizado de solicitação de envio em código e chamadores alterados Verificação de diferenças cm find . --diff=origin/main --fail-on=CRITICAL,HIGH
Pipeline ou auditoria programada Auditorias noturnas, gates de pré-lançamento, compliance com SOC 2 Verificação avançada cm find . --deep --deep-workers=8

Referência de flags de comando por modo

As tabelas a seguir descrevem as flags de linha de comando aceitas por cada modo de verificação.

Flags comuns (todos os modos)

As flags a seguir se aplicam a todos os modos de verificação do cm find:

Sinalização padrão Descrição
-c, --context TEXT "" Contexto adicional para orientar o agente de verificação, como observações sobre arquitetura.
--model MODEL_NAME gemini-3.8-flash Modelo do Gemini a ser usado (gemini-3.8-flash, gemini-3.8-flash-cyber).
-y, --yes false Pula todos os prompts de confirmação interativos.
--unrestricted false Desative o sandbox do sistema de arquivos.

Flags de verificação de diferenças

As flags a seguir configuram verificações de cm find --diff:

Sinalização padrão Descrição
--diff[=REF] Desativado Ative o modo de diff em relação à referência de destino, como origin/main ou HEAD~1. Sem REF, compara com HEAD. Não pode ser usado com --deep.
--staged Desativado Limita a diferença ao índice em estágio (git diff --cached). Requer --diff.
--diff-depth DEPTH 1 Profundidade de travessia para análise de impacto (1 a 3, padrão: 1-hop).
--diff-workers COUNT 4 Número de workers simultâneos para jobs de auditoria de solicitação de envio (1 a 16).
--diff-max-neighbors COUNT 10 Número máximo de arquivos de autor da chamada ou recebedor da chamada dependentes a serem inspecionados.
--fail-on SEVERITIES CRITICAL,HIGH Gravidades separadas por vírgulas que fazem cm find sair com o código 1.
--fail-on-truncation Desativado Saia com o código 1 se a descoberta de vizinhos exceder o limite.
--format FORMAT table Formato da saída: table, json ou sarif.
--output FILE Saída padrão Grava o relatório em um arquivo em vez da saída padrão.

Flags de verificação avançada

As flags a seguir configuram verificações de cm find --deep:

Sinalização padrão Descrição
--deep false Ative a verificação detalhada exaustiva em todo o repositório. Não pode ser usado com --diff.
--deep-workers COUNT 8 Número de workers simultâneos para verificação completa (de 1 a 16).