Executar uma análise do Codex Security

Comece com uma análise normal do Codex Security para uma revisão inicial ou uma avaliação de rotina de um repositório ou componente. Esta executa uma vez o fluxo de trabalho completo da análise.

Para uma avaliação mais minuciosa, reveja os resultados e, em seguida, execute uma análise aprofundada. As análises aprofundadas demoram mais tempo e efetuam uma pesquisa mais extensa.

Escolher a área da análise

Na aplicação para computador, abra Security, selecione Scans e selecione + Scan. Escolha um repositório existente ou outra pasta e, em seguida, selecione Codebase.

Analise todo o repositório quando precisar de uma cobertura abrangente e o repositório constituir uma unidade de revisão razoável. Num monorepo, escolha uma pasta quando um serviço, pacote ou componente tiver um proprietário e um limite de segurança claramente definidos.

Também pode iniciar uma análise a partir de uma conversa do Codex:

Use $codex-security:security-scan to scan this repository for security vulnerabilities.

Para concentrar essa conversa numa pasta específica, identifique o componente:

Use $codex-security:security-scan to scan this repository for security vulnerabilities, focusing on the services/billing component.

Configurar a análise

Para obter a melhor qualidade de análise, utilize gpt-5.6-sol com o nível de esforço de raciocínio xhigh.

1. Selecione Codebase e mantenha Deep scan desativado.
2. Confirme o repositório selecionado, o ramo atual e a revisão mais recente.
3. Defina Scan area como todo o repositório ou escolha uma pasta.
4. Escolha um modelo e um nível de esforço de raciocínio.
5. Abra Additional context apenas quando este alterar a revisão. Um contexto útil identifica entradas controladas por atacantes, limites de confiança, ações sensíveis ou uma área específica à qual deve ser dada prioridade.
6. Selecione Start scan.

Adicione SECURITY.md à raiz do repositório para fornecer orientações de segurança persistentes. Descreva o modelo de ameaças, os invariantes de segurança, os critérios de conclusões a comunicar, as exclusões e o contexto de gravidade. Adicione ficheiros SECURITY.md aninhados para orientações específicas de cada diretório. Quando as políticas entram em conflito, prevalece o ficheiro mais próximo do código. O Codex Security trata estes ficheiros como contexto de políticas, não como instruções executáveis.

Utilize AGENTS.md para os comandos de compilação e validação suportados e outras instruções específicas do repositório.

Permitir a conclusão das fases

Uma análise executa estas fases pela seguinte ordem:

1. Modelação de ameaças identifica os ativos, os pontos de entrada, os limites de confiança e as invariantes de segurança.
2. Descoberta de problemas revê o código solicitado para detetar controlos que possam estar comprometidos e caminhos da origem ao destino.
3. Validação testa ou verifica de outra forma cada candidato e regista provas ou lacunas de comprovação.
4. Análise do impacto e dos caminhos avalia os caminhos realistas, o impacto e a gravidade de cada candidato.
5. Relatórios regista descobertas validadas, a cobertura e os metadados da análise. Estão disponíveis relatórios detalhados por descoberta quando solicitados.
6. Reforço estrutural, quando solicitado, analisa o conjunto de descobertas e cria orientações de conceção.
7. Finalização valida o contrato estruturado da análise e gera report.md, incluindo ligações para quaisquer relatórios detalhados ou orientações de reforço.

O ambiente de trabalho mostra a fase ativa da análise e qualquer progresso comunicado pelo plugin. Selecione View activity para inspecionar a tarefa do Codex. Aguarde pelo resultado completo em vez de avaliar antecipadamente os candidatos ou interromper porque uma fase demora mais do que outra.

Rever a análise concluída

Reveja o resultado pela seguinte ordem:

1. Confirme o alvo, a revisão e a área da análise.
2. Leia as superfícies revistas e todas as áreas explicitamente adiadas ou que necessitam de acompanhamento.
3. Para cada conclusão, inspecione o controlo de origem ou o destino, a entrada controlada pelo atacante, o método de validação, a incerteza restante, a acessibilidade realista, a justificação da gravidade e a correção proposta.
4. Rejeite as conclusões cujas provas não sustentem o caminho ou o impacto alegado.
5. Selecione uma conclusão aceite antes de iniciar uma correção.

Avaliar uma primeira análise

Antes da análise, escolha entre dois e quatro critérios de avaliação, como a descoberta independente, a qualidade das provas, os falsos positivos ou a qualidade da correção. Se testar relativamente a uma descoberta conhecida, registe se a forneceu ao Codex ou se a omitiu da análise.

Registe a revisão do repositório, a versão do plugin, o modelo e o esforço de raciocínio. Utilize esta referência para comparar análises posteriores depois de o código, os controlos de segurança ou as definições de análise serem alterados.

Escolher uma frequência de análise

Defina a frequência de análise com base no risco do repositório e na capacidade da sua equipa para resolver as descobertas. Execute análises nestes momentos:

• Referência: Execute uma análise padrão ao integrar um repositório, assumir a responsabilidade por um componente ou precisar de um ponto de partida para um novo modelo de ameaças.
• Alterações de código: Reveja alterações de código quando um pull request ou commit alterar código sensível à segurança ou uma integração externa.
• Revisão regular: Defina um intervalo de revisão recorrente com base na exposição do seu sistema e na frequência com que o código é alterado. Ajuste-o à capacidade da sua equipa para resolver as descobertas.
• Após uma correção: Corrija e verifique a descoberta. Confirme que o problema já não pode ser reproduzido e mantenha a análise original para comparação.

Estes acionadores de análise não criam um agendamento automático.

Reabrir uma análise anterior

Abra Security e, em seguida, selecione uma análise guardada em Scans para rever as respetivas conclusões, cobertura e artefactos de relatório disponíveis. Para avaliar o código mais recente, inicie uma nova análise para o mesmo repositório. A nova análise não substitui a análise anterior nem os respetivos artefactos.

Utilizar os resultados

Utilize o ambiente de trabalho de Security para rever conclusões, cobertura e áreas de acompanhamento sem inspecionar JSON não processado. Abra report.md, quando estiver disponível, como ponto de entrada legível para o diretório completo da análise. Mantenha o diretório intacto quando o partilhar ou arquivar: o relatório contém ligações para relatórios detalhados em findings/ e para orientações de reforço estrutural em hardening/, quando esses artefactos opcionais estiverem disponíveis.

Nos bastidores do espaço de trabalho, cada análise preserva scan-manifest.json, findings.json e coverage.json para automatização e integrações. Normalmente, não precisa de abrir estes ficheiros.

O espaço de trabalho das conclusões também pode criar ficheiros JSON, CSV e SARIF portáteis. Consulte Exportar ou acompanhar conclusões.

Passo seguinte

Depois de uma pessoa aceitar uma conclusão, utilize Corrigir e verificar uma conclusão para gerar e rever uma correção delimitada. Não peça ao Codex para corrigir todas as conclusões de uma análise numa única conversa.