Auditorias de Código

As auditorias de código são experimentais.

Uma auditoria de código é uma revisão de segurança de um projeto executada pelo seu agente de programação local. Clique com o botão direito em um projeto na barra lateral, escolha "Experimental" → "Auditoria de código" e, em seguida, "Nova auditoria". Em "Assistente local", escolha "Codex" ou "Claude"; depois escolha um "Modelo", um "Esforço de raciocínio" e o "Escopo" e clique em "Iniciar auditoria". A página do relatório mostra a fase atual da varredura. "Sessão do assistente" mostra as chamadas de ferramentas originais do agente, a análise e as solicitações de permissão pendentes; responda às solicitações ali para que a auditoria continue. O relatório aparece quando o Codex Security sela os resultados.

A auditoria é executada na máquina que hospeda o projeto e usa a CLI instalada do agente selecionado, com o login, a configuração e o tratamento de permissões que ela já tem ("Usa o login e a configuração do assistente local. Não é necessário configurar outra API de modelos."). O VelaTerm adiciona um servidor MCP do Codex Security somente para a sessão de auditoria; seus outros servidores MCP continuam como estão, e o próprio VelaTerm não chama nenhuma API de modelos. A CLI precisa estar instalada, com o login feito e dentro dos limites da conta. A configuração da própria CLI pode selecionar um provedor de modelos; o VelaTerm não a altera.

O item "Auditoria de código" também aparece para coleções. Uma coleção sem pasta raiz não pode ser auditada.

Modelos e esforço de raciocínio

A lista de modelos é a mesma que a caixa de diálogo de nova sessão usa para esse agente e leva em conta os argumentos de inicialização padrão do agente; assim, a lista corresponde à forma como a auditoria será executada. "Modelo padrão" mantém a escolha do próprio agente. "Esforço de raciocínio" fica disponível quando você escolhe um modelo que oferece níveis de esforço; "Automático" mantém a escolha do próprio agente. Se a lista não puder ser carregada, aparece um botão para tentar novamente. O backend verifica as combinações escolhidas explicitamente, e a auditoria salva os valores selecionados para o histórico e para execuções posteriores. O fato de um modelo aparecer na lista não significa que sua conta possa usá-lo. Falhas do provedor, incluindo limites de uso esgotados, encerram a auditoria como falha.

As novas auditorias pedem a análise no idioma da interface. Campos de protocolo, caminhos, identificadores e evidências citadas do código-fonte permanecem inalterados.

Integração com o Codex Security

O VelaTerm inclui a versão pública @openai/codex-security@0.1.26, sob licença Apache-2.0, cujo manifesto de plugin está na versão 0.1.95; a página de nova auditoria mostra as duas versões. As habilidades, referências, esquemas, scripts, ambiente de execução e licença originais estão incluídos, e UPSTREAM.json registra a origem do pacote, o valor de integridade e os hashes dos arquivos.

Cada nova auditoria registra uma varredura real no workbench do Codex Security. O agente lê a habilidade de entrada incluída e usa as ferramentas MCP e o formato de resultado originais. Os registros do fluxo em lote anterior, implementado de forma independente, continuam legíveis e recebem o rótulo "Auditoria anterior · Este registro não utilizou o processo do Codex Security."

Os dois agentes usam o mesmo fluxo do Codex Security. O SDK público em TypeScript controla o ambiente de execução do Codex e não oferece um executor para o Claude Code; por isso, o VelaTerm faz a integração pelo servidor MCP e pelo workbench local do Codex Security. O suporte ao Claude Code é uma adaptação do VelaTerm, e não uma declaração de suporte oficial ao Claude por parte do projeto original.

O ambiente de execução precisa do Node.js no PATH, em uma versão compatível com o pacote original, e do Python 3.10 ou posterior; o Python 3.10 também precisa do pacote tomli, que no Python 3.11 e posteriores é substituído pelo tomllib integrado. O VelaTerm verifica os recursos incluídos e os descompacta no próprio diretório de dados. Ele não os instala na sua configuração do Codex ou do Claude.

Escopo e fluxo de trabalho

• Repositório inteiro executa a varredura Standard do Codex Security com base em um instantâneo fixo do alvo e na política de segurança do repositório.
• Diretório ou arquivo executa a varredura Standard com um "Caminho relativo" exato. Outros arquivos de código-fonte podem ser lidos para entender uma cadeia de chamadas, sem que isso signifique que essas áreas receberam uma auditoria completa.
• Alterações na árvore de trabalho executa a habilidade de diff do Codex Security em um conjunto fixo de alterações do Git. Ela inclui as alterações preparadas, não preparadas e não rastreadas que o resolvedor de alvos original aceita e mantém as evidências da versão de referência para os arquivos excluídos.

A varredura Standard lê skills/security-scan/SKILL.md e references/core-scan.md. Ela realiza verificações preliminares, análise independente da linha de base e da arquitetura, investigações ancoradas no código-fonte, pontos de controle dos possíveis achados, revisão de contraevidências, validação e conciliação da cobertura. Workers independentes são usados quando o agente oferece suporte a eles; caso contrário, vale a alternativa sequencial do Codex Security, e as limitações dela precisam ser informadas. Uma configuração de capacidade de workers, por si só, não comprova que workers independentes foram executados.

As auditorias da árvore de trabalho leem skills/security-diff-scan/SKILL.md. Elas fixam o alvo, constroem o modelo de ameaças, preparam e enumeram os itens de revisão, encontram possíveis achados, validam esses achados, analisam os caminhos de ataque e enviam o rascunho do resultado para conclusão. Revisar apenas o conteúdo atual dos arquivos alterados não substitui esse fluxo.

O workbench do Codex Security aceita apenas diretórios como escopo. Para que a seleção de arquivos continue funcionando, o ambiente de execução instalado aplica dois patches pontuais, cujos hashes ficam registrados: um arquivo existente é aceito como escopo e conta como um item do instantâneo. Os originais incluídos não são alterados, e o ADAPTER.json instalado registra tanto os hashes originais quanto os adaptados. Selecionar um arquivo nunca se transforma em uma varredura do diretório inteiro dele.

As instruções da auditoria proíbem edições no código-fonte, correções, publicação e alterações na configuração do agente. As permissões de ferramentas do próprio agente continuam valendo. Essas instruções não são um sandbox do sistema operacional. A validação precisa informar o que foi de fato verificado, e um achado estático não significa que uma exploração foi reproduzida ("Apenas revisão estática. A cobertura declarada não garante que todas as vulnerabilidades foram encontradas. Não são executadas explorações dinâmicas.").

Relatórios, cobertura e cancelamento

Os resultados oficiais são os arquivos scan-manifest.json, findings.json e coverage.json do Codex Security. O finalizador do Codex Security os valida e sela e, em seguida, gera o relatório legível. O VelaTerm importa esses arquivos e verifica a localização e as linhas exatas do código-fonte de cada achado, tratando as quebras de linha LF e CRLF como equivalentes. Uma estrutura válida e linhas de código-fonte correspondentes não comprovam, por si sós, que um achado pode ser explorado. Se as evidências do código-fonte não corresponderem, a auditoria permanece como "Falhou" e os achados dela não são aceitos como validados. O relatório selado do Codex Security continua disponível, e as exportações em Markdown mostram primeiro a falha de validação, sem reescrever o relatório.

Antes da selagem, o VelaTerm verifica os caminhos, os intervalos de linhas e os trechos do rascunho com o mesmo verificador usado na importação. Se as evidências não corresponderem, a varredura permanece sem selo e o agente é informado sobre quais locais precisa corrigir. Em seguida, a ferramenta de conclusão do Codex Security gera e sela o relatório. Essa verificação nunca reescreve trechos, remove achados nem altera resultados selados. A importação repete a verificação; assim, alterações posteriores no código-fonte não podem transformar silenciosamente evidências inválidas em um resultado bem-sucedido.

A cobertura vem dos registros de revisão e das decisões do Codex Security, e não do número de arquivos que o agente afirma ter lido. Possíveis achados não resolvidos, trabalho adiado, exclusões e avisos de conclusão continuam visíveis. Uma varredura selada com cobertura incompleta aparece como "Cobertura parcial". Mesmo uma cobertura completa não garante que todas as vulnerabilidades foram encontradas.

Quando o agente encerra um turno e a varredura ainda tem trabalho pendente, o VelaTerm continua a mesma sessão e a mesma varredura, mantendo os achados existentes e os resultados dos workers. As solicitações de permissão continuam pendentes ("Permissão ou entrada necessária"), e um cancelamento ou um erro do provedor interrompe a continuação automática. Se três turnos seguidos terminarem sem nenhuma mudança no progresso da revisão, nos achados ou na cobertura do Codex Security, a auditoria é interrompida com um erro de varredura incompleta e mantém os pontos de controle.

A aba "Relatório" mostra os achados mantidos, as evidências do código-fonte e os limites da cobertura. Cada achado tem uma URL própria e mostra o caminho de ataque, como foi validado e a conclusão (quando fornecida), as recomendações de correção e os trechos de código-fonte informados; confira o status da auditoria antes de tratar esses trechos como verificados. A aba "Arquivos do relatório" guarda o relatório completo gerado pelo Codex Security e o ID da varredura. Uma varredura em andamento mostra as versões do pacote e do plugin do Codex Security, a fase e o progresso reais e os avisos; enquanto não existe um relatório selado, são exibidas informações de progresso e dos pontos de controle, em vez de uma avaliação vazia. Na "Sessão do assistente", a caixa de mensagem normal e a reversão ficam desativadas para que um turno sem relação com a auditoria não a substitua; as solicitações de permissão continuam utilizáveis.

"Cancelar" interrompe a varredura do Codex Security e o agente. Os pontos de controle salvos continuam disponíveis quando o workbench do Codex Security consegue selá-los e mantêm o status de cancelado ou de falha. Resultados que chegam depois não reativam uma auditoria cancelada. Após uma reinicialização, o VelaTerm concilia o estado do Codex Security: um resultado concluído e selado pode ser importado, e uma execução não concluída é marcada como "Interrompida", com os arquivos mantidos sempre distinguíveis de um resultado concluído.

"Iniciar auditoria" em um registro existente cria uma nova varredura do alvo atual com o agente e as seleções salvos. Isso não retoma um turno interrompido do modelo nem reutiliza um veredito antigo.

O histórico de auditorias, o formulário de nova auditoria, os detalhes do relatório e a sessão do agente têm URLs próprias; assim, podem ser abertos diretamente, atualizados e percorridos com os botões voltar e avançar do navegador. Em telas estreitas, o histórico e os detalhes aparecem em visualizações separadas.

Exportações e limitações

"Exportar relatório" oferece Markdown e JSON. As exportações em Markdown contêm o relatório do Codex Security, quando ele existe; caso contrário, indicam claramente que são o registro de uma varredura incompleta. As exportações em JSON mantêm todos os dados importados junto com os metadados do próprio VelaTerm. A pasta da varredura do Codex Security também guarda o SARIF gerado e outros arquivos. As exportações podem conter trechos do código-fonte e detalhes de vulnerabilidades; por isso, compartilhe-as com cuidado.

Esta interface oferece auditorias Standard e de diff da árvore de trabalho. Outras habilidades incluídas, como varreduras profundas, correção, verificação de correções e acompanhamento de issues externos, são mantidas como recursos do Codex Security, mas não estão disponíveis como ações separadas. Uma auditoria não aplica correções, não publica achados, não cria issues nem abre pull requests.

Diagnóstico

O backend registra o ciclo de vida da auditoria e as informações de fase do Codex Security em runtime-*.log, no diretório de logs do aplicativo. VLX_LOG_DIR define o local compartilhado; quando não está definida, VLX_SECURITY_LOG_DIR define o local dos eventos de auditoria. VLX_SECURITY_LOG_LEVEL=error os limita a falhas, e off os desativa. Prompts e respostas são descritos pelo tamanho e pelo hash SHA-256; o código-fonte completo, as credenciais e as respostas completas da IA não são copiados para o log, e as mensagens brutas do provedor não são guardadas. Nomes de modelos personalizados são substituídos por identificadores anônimos válidos apenas no processo atual. As contagens de tokens, quando disponíveis, representam o uso acumulado da sessão. A conversa do agente mantém o registro normal.

Em uma auditoria com falha, leia a explicação do provedor no relatório ou abra "Sessão do assistente". Resolva problemas de login, de ambiente de execução, de permissão ou de limite da conta antes de iniciar outra auditoria. Um servidor MCP conectado mostra apenas que as ferramentas estão disponíveis; isso não indica que o modelo concluiu a varredura.

Referências do Codex Security: visão geral da CLI, referência da CLI, código-fonte público.