Auditorías de código

Las auditorías de código son experimentales.

Una auditoría de código es una revisión de seguridad de un proyecto que se ejecuta mediante su agente de programación local. Haga clic con el botón derecho en un proyecto de la barra lateral, elija «Experimental» → «Auditoría de código» y, después, «Nueva auditoría». En «Asistente local», elija «Codex» o «Claude»; a continuación, elija un «Modelo», un «Esfuerzo de razonamiento» y el «Alcance», y haga clic en «Iniciar auditoría». La página del informe muestra la fase actual del análisis. «Sesión del asistente» muestra las llamadas a herramientas originales del agente, su análisis y las solicitudes de permiso pendientes; responda allí a las solicitudes para que la auditoría continúe. El informe aparece cuando Codex Security sella sus resultados.

La auditoría se ejecuta en la máquina que aloja el proyecto y usa la CLI instalada del agente seleccionado, con su inicio de sesión, su configuración y su gestión de permisos existentes («Utiliza el inicio de sesión y la configuración del asistente local. No requiere configurar una API de modelos adicional»). VelaTerm añade un servidor MCP de Codex Security solo para la sesión de auditoría; sus demás servidores MCP no se modifican, y VelaTerm no llama por sí mismo a ninguna API de modelos. La CLI debe estar instalada, tener la sesión iniciada y no haber superado los límites de su cuenta. La configuración propia de la CLI puede seleccionar un proveedor de modelos; VelaTerm no la modifica.

El elemento «Auditoría de código» también aparece en las colecciones. Una colección sin carpeta raíz no se puede auditar.

Modelos y esfuerzo de razonamiento

La lista de modelos es la misma que usa el cuadro de diálogo de nueva sesión para ese agente y tiene en cuenta los argumentos de inicio predeterminados del agente, de modo que coincide con la forma en que se ejecutará la auditoría. «Modelo predeterminado» mantiene la elección propia del agente. «Esfuerzo de razonamiento» pasa a estar disponible al elegir un modelo que ofrece niveles de esfuerzo; «Automático» mantiene la elección propia del agente. Si la lista no se puede cargar, aparece un botón para reintentarlo. El servidor comprueba las combinaciones explícitas, y la auditoría guarda los valores seleccionados para su historial y para ejecuciones posteriores. Que un modelo aparezca en la lista no significa que su cuenta pueda usarlo. Los errores del proveedor, incluido el agotamiento de los límites de uso, hacen que la auditoría termine como fallida.

Las auditorías nuevas solicitan el análisis en el idioma de la interfaz. Los campos del protocolo, las rutas, los identificadores y los fragmentos de código fuente citados como evidencia se dejan sin cambios.

Integración con Codex Security

VelaTerm incluye la versión pública @openai/codex-security@0.1.26, distribuida con licencia Apache-2.0, cuyo manifiesto de complemento corresponde a la versión 0.1.95; la página de nueva auditoría muestra ambas versiones. Se incluyen las habilidades, las referencias, los esquemas, los scripts, el entorno de ejecución y la licencia originales, y UPSTREAM.json registra el origen del paquete, el valor de integridad y los hashes de los archivos.

Cada auditoría nueva registra un análisis real en el entorno de trabajo (workbench) original de Codex Security. El agente lee la habilidad de entrada incluida y usa las herramientas MCP y el formato de resultados originales. Los registros del flujo de trabajo por lotes anterior, que se implementó de forma independiente, se pueden seguir leyendo y llevan la etiqueta «Auditoría anterior · Este registro no utilizó el proceso de Codex Security».

Ambos agentes usan el mismo flujo de trabajo original. El SDK público de TypeScript controla el entorno de ejecución de Codex y no ofrece un ejecutor para Claude Code, por lo que VelaTerm se integra mediante el servidor MCP y el workbench local originales. La compatibilidad con Claude Code la aporta un adaptador de VelaTerm; el proyecto original no afirma ofrecer compatibilidad oficial con Claude.

El entorno de ejecución necesita Node.js en el PATH, en una versión compatible con el paquete original, y Python 3.10 o posterior; Python 3.10 necesita además el paquete tomli, que en Python 3.11 y posteriores se sustituye por el módulo integrado tomllib. VelaTerm comprueba los recursos incluidos y los descomprime en su directorio de datos. No los instala en su configuración de Codex o de Claude.

Alcance y flujo de trabajo

• Todo el repositorio ejecuta el análisis Standard original sobre una instantánea fija del objetivo y la política de seguridad del repositorio.
• Directorio o archivo ejecuta Standard con una «Ruta relativa» exacta. Se pueden leer otros archivos de código fuente para entender una cadena de llamadas, sin afirmar que esas áreas hayan recibido una auditoría completa.
• Cambios del árbol de trabajo ejecuta la habilidad original de análisis de diferencias sobre un conjunto fijo de cambios de Git. Incluye los cambios preparados, sin preparar y sin seguimiento que admite el resolvedor de objetivos original, y conserva la evidencia de la versión base de los archivos eliminados.

Standard lee skills/security-scan/SKILL.md y references/core-scan.md. Realiza comprobaciones previas, análisis independientes de la línea base y de la arquitectura, investigaciones ancladas en el código fuente, puntos de control de candidatos, revisión de contraevidencias, validación y conciliación de la cobertura. Se usan procesos trabajadores independientes cuando el agente los admite; en caso contrario, se aplica la alternativa secuencial original, cuyas limitaciones deben declararse. Un ajuste de capacidad de procesos trabajadores no demuestra por sí solo que se hayan ejecutado procesos trabajadores independientes.

Las auditorías del árbol de trabajo leen skills/security-diff-scan/SKILL.md. Fijan el objetivo, construyen el modelo de amenazas, preparan y enumeran los elementos que se van a revisar, buscan candidatos, los validan, analizan las rutas de ataque y envían el borrador de resultados para su finalización. Revisar solo el contenido actual de los archivos modificados no sustituye a este flujo.

El workbench original solo acepta directorios como alcance. Para que la selección de archivos siga funcionando, el entorno de ejecución instalado aplica dos parches acotados cuyos hashes quedan registrados: se admite un archivo existente como alcance y cuenta como una entrada de la instantánea. Los originales incluidos no se modifican, y el ADAPTER.json instalado registra tanto los hashes originales como los adaptados. Seleccionar un archivo nunca se convierte en un análisis de todo su directorio.

Las instrucciones de la auditoría prohíben editar el código fuente, aplicar correcciones, publicar resultados y modificar la configuración del agente. Los permisos de herramientas propios del agente siguen vigentes. Estas instrucciones no constituyen un entorno aislado del sistema operativo. La validación debe indicar qué se comprobó realmente, y un hallazgo estático no significa que se haya reproducido una explotación («Solo revisión estática. La cobertura declarada no garantiza que se hayan detectado todas las vulnerabilidades. No se ejecutan pruebas de explotación dinámica»).

Informes, cobertura y cancelación

Los resultados de referencia son los archivos originales scan-manifest.json, findings.json y coverage.json. El finalizador original los valida y los sella, y después genera el informe legible. VelaTerm importa estos archivos y comprueba la ubicación y las líneas exactas de código fuente de cada hallazgo, y trata como equivalentes los finales de línea LF y CRLF. Una estructura válida y unas líneas de código coincidentes no demuestran por sí solas que un hallazgo sea explotable. Si la evidencia del código fuente no coincide, la auditoría permanece como «Fallida» y sus hallazgos no se aceptan como validados. El informe original sellado sigue disponible, y las exportaciones en Markdown muestran primero el error de validación sin reescribir el informe.

Antes del sellado, VelaTerm comprueba las rutas, los intervalos de líneas y los fragmentos del borrador con el mismo verificador que se usa durante la importación. Si la evidencia no coincide, el análisis queda sin sellar y se indica al agente qué ubicaciones debe corregir. A continuación, la herramienta de finalización de Codex Security genera y sella el informe. Esta comprobación nunca reescribe fragmentos, elimina hallazgos ni modifica resultados sellados. La importación repite la comprobación, de modo que los cambios posteriores en el código fuente no pueden convertir sin que se advierta una evidencia no válida en un resultado correcto.

La cobertura procede de los registros y las decisiones de revisión originales, no del número de archivos que el agente afirma haber leído. Los candidatos sin resolver, el trabajo aplazado, las exclusiones y las advertencias de finalización siguen visibles. Un análisis sellado con cobertura incompleta se muestra como «Cobertura parcial». Ni siquiera una cobertura completa garantiza que se hayan encontrado todas las vulnerabilidades.

Cuando el agente termina un turno mientras el análisis aún tiene trabajo pendiente, VelaTerm continúa la misma sesión y el mismo análisis, y conserva los hallazgos y los resultados de los procesos trabajadores existentes. Las solicitudes de permiso siguen pendientes («Se requiere permiso o información»), y una cancelación o un error del proveedor detiene la continuación automática. Si tres turnos seguidos terminan sin ningún cambio en el progreso de la revisión original, en los hallazgos o en la cobertura, la auditoría se detiene con un error de análisis incompleto y conserva sus puntos de control.

La pestaña «Informe» muestra los hallazgos conservados, la evidencia del código fuente y los límites de la cobertura. Cada hallazgo tiene su propia URL y muestra su ruta de ataque, cómo se validó y la conclusión (cuando se proporciona), las recomendaciones de corrección y los fragmentos de código fuente indicados; compruebe el estado de la auditoría antes de dar por verificados estos fragmentos. La pestaña «Archivos del informe» conserva el informe completo generado por el proyecto original y el ID del análisis. Un análisis en curso muestra las versiones del paquete y del complemento originales, la fase y el progreso reales y las advertencias; mientras no exista un informe sellado, se muestran el progreso y la información de los puntos de control en lugar de una evaluación vacía. En la «Sesión del asistente», el cuadro de mensajes habitual y el retroceso están desactivados para que un turno ajeno no pueda sustituir a la auditoría; las solicitudes de permiso siguen disponibles.

«Cancelar» detiene el análisis original y el agente. Los puntos de control guardados siguen disponibles si el workbench original puede sellarlos, y conservan su estado de cancelado o fallido. Los resultados que llegan tarde no pueden reactivar una auditoría cancelada. Tras un reinicio, VelaTerm concilia el estado original: un resultado completo y sellado se puede importar, y una ejecución sin terminar se marca como «Interrumpida»; sus archivos conservados se siguen distinguiendo de un resultado completo.

«Iniciar auditoría» en un registro existente crea un nuevo análisis del objetivo actual con el agente y las selecciones guardados. No reanuda un turno del modelo que se haya detenido ni reutiliza un veredicto anterior.

El historial de auditorías, el formulario de nueva auditoría, los detalles del informe y la sesión del agente tienen cada uno su propia URL, por lo que se pueden abrir directamente, actualizar y recorrer con los botones Atrás y Adelante del navegador. En pantallas estrechas, el historial y los detalles se muestran como vistas separadas.

Exportaciones y limitaciones

«Exportar informe» ofrece Markdown y JSON. Las exportaciones en Markdown contienen el informe original cuando existe; en caso contrario, se identifican claramente como el registro de un análisis incompleto. Las exportaciones en JSON conservan todos los datos importados junto con los metadatos propios de VelaTerm. La carpeta del análisis original conserva además el archivo SARIF generado y otros archivos. Las exportaciones pueden contener fragmentos de código fuente y detalles de vulnerabilidades, así que compártalas con precaución.

Esta interfaz ofrece auditorías Standard y auditorías de diferencias del árbol de trabajo. Otras habilidades incluidas, como los análisis en profundidad, la corrección, la verificación de correcciones y el seguimiento de incidencias externas, se conservan como recursos originales, pero no están disponibles como acciones independientes. Una auditoría no aplica correcciones, no publica hallazgos, no crea incidencias ni abre solicitudes de incorporación de cambios (pull requests).

Diagnóstico

El servidor registra el ciclo de vida de la auditoría y la información de las fases originales en runtime-*.log, en el directorio de registros de la aplicación. VLX_LOG_DIR establece la ubicación común; cuando no está definida, VLX_SECURITY_LOG_DIR establece la ubicación de los eventos de auditoría. VLX_SECURITY_LOG_LEVEL=error los limita a los errores, y off los desactiva. Las instrucciones y las respuestas se describen mediante su tamaño y su resumen SHA-256; el código fuente completo, las credenciales y las respuestas completas de la IA no se copian en el registro, y los mensajes sin procesar del proveedor no se conservan. Los nombres de modelos personalizados se sustituyen por identificadores anónimos válidos solo en el proceso actual. Los recuentos de tokens, cuando están disponibles, corresponden al uso acumulado de la sesión. La conversación del agente mantiene su registro habitual.

Si una auditoría falla, lea la explicación del proveedor en el informe o abra «Sesión del asistente». Resuelva los problemas de inicio de sesión, de entorno de ejecución, de permisos o de límites de la cuenta antes de iniciar otra auditoría. Un servidor MCP conectado solo indica que las herramientas están disponibles; no indica que el modelo haya completado el análisis.

Referencias del proyecto original: descripción general de la CLI, referencia de la CLI, código fuente público.