Guard SAST Analyzer para Visual Studio Code
Extensión para proyectos Python/Flask y JavaScript/Express. Entrada TypeScript compilada y módulos JavaScript reutilizados, sin dependencias npm de runtime. Usa el backend existente y sus 27 controles; no duplica reglas ni scoring.
Proyecto académico independiente. No es un producto oficial, afiliado ni respaldado por OWASP.
Requisito del servicio
El análisis SAST se ejecuta en el backend Guard configurado; esta extensión no incorpora un motor local y no necesita Copilot para enviar un análisis. El servicio público de Render aún no tiene desplegada la versión que incorpora la vinculación de cuentas y tokens personales. Su comprobación de salud responde con los 27 controles, pero la vinculación desde VS Code devuelve 404. Hasta actualizar ese servicio, no se puede completar el flujo remoto autenticado ni verificar en Render el historial por usuario. No envíes proyectos privados a ese servicio durante este estado.
La integración opcional con Copilot sirve para interpretar hallazgos y preparar correcciones bajo autorización. Requiere Copilot/modelo compatible; sus archivos de agente y Skill no sustituyen ni ejecutan el análisis SAST.
Instalar, compilar y depurar
Desde la raíz del repositorio, con Node.js 24 y Python 3.12/dependencias del backend disponibles:
npm ci --ignore-scripts --prefix vscode-extension
npm run compile --prefix vscode-extension
npm test --prefix vscode-extension
Abre vscode-extension/ en VS Code y pulsa F5. La tarea previa compila y el mapa de fuentes permite depurar la entrada TypeScript. En el host abre únicamente una carpeta propia y confiable. La extensión rechaza el análisis en modo restringido; la decisión de confianza corresponde a la persona.
Para un servidor de demostración aislado, en otra terminal de la raíz:
$env:DATABASE_URL = 'sqlite:///' + ((Join-Path $env:TEMP 'owasp-guard-u209-demo.sqlite') -replace '\\','/')
$env:OWASP_GUARD_API_KEY = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
$env:OWASP_GUARD_SECRET_KEY = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
python -m flask --app app:create_app run --host 127.0.0.1 --port 5000
Las claves se generan para cada sesión, no están incorporadas al código ni deben guardarse en archivos o logs. Introduce personalmente el valor de OWASP_GUARD_API_KEY en SecretStorage para esa demostración. La base es SQLite temporal; no emplees credenciales ni la URL de PostgreSQL de producción.
Demostración del flujo integrado
- Abre una carpeta propia con un
app.py de prueba y un .env sintético. Configura http://127.0.0.1:5000 con Guard SAST Analyzer: Configurar servidor y ejecuta Guard SAST Analyzer: Comprobar servidor.
- Configura el host HTTPS autorizado con Guard SAST Analyzer: Configurar servidor. En la web, inicia sesión y abre Vincular VS Code; crea un token individual, limitado y revocable. Pégalo con Guard SAST Analyzer: Vincular cuenta. El token vence en 90 días, se muestra una sola vez y se guarda en SecretStorage, sin escribirlo en settings ni logs. Cada cuenta puede tener cinco tokens activos y hasta diez operaciones de administración por hora.
- Ejecuta Guard SAST Analyzer: Analizar proyecto. Revisa URL completa, cantidad y tamaño del ZIP. Cancelar impide todas las solicitudes del análisis. Solo Enviar para análisis permite consultar salud y transmitir el ZIP.
- Revisa Problems, la salida Guard SAST Analyzer, Guard SAST Analyzer: Mostrar hallazgos del último análisis y Guard SAST Analyzer: Mostrar resumen de controles. Se conservan archivo/línea, severidad, categoría, control y recomendación de la API. Los estados inciertos y no aplicables se muestran por separado; no se infiere aprobación.
- Usa Guard SAST Analyzer: Copiar resultados JSON y revisa ese contenido antes de compartirlo con un modelo autorizado. En Chat selecciona Guard SAST Analyzer Assistant y pide:
Usa /guard-sast-quality para revisar este reporte real; contrasta OG-05.1 con app.py, explica la corrección y propón su prueba. No edites ni ejecutes nada todavía. Adjunta solo el reporte y código de prueba autorizados.
- El agente debe pedir autorización antes de editar/ejecutar pruebas. Tras autorizar un cambio concreto, comprueba las pruebas y repite el análisis con otro consentimiento. Conserva ambos reportes. El agente no inicia transmisiones automáticamente.
El Skill canónico se mantiene en .agents/skills/guard-sast-quality/SKILL.md, ruta nativa de Codex y Copilot. El antiguo owasp-guard-review es solo un alias compatible. El agente se mantiene en .github/agents/guard-sast-analyzer.agent.md con nombre Guard SAST Analyzer Assistant. La compilación copia ambas fuentes al paquete: chatSkills y chatAgents son contribuciones reales de VS Code. No hay procedimientos duplicados que mantener. Para descubrimiento en Codex, abre una nueva sesión del repositorio después de crear el Skill.
La invocación del agente requiere Copilot/modelo habilitado por la persona. Tener archivos válidos o ver el perfil no acredita una respuesta de IA. No transfieras el repositorio privado completo para esta demostración.
Contratos reales y privacidad
GET /api/v1/health: disponibilidad y registro de 27 controles, sin token ni fuentes.
POST /api/v1/scan: ZIP multipart file, Bearer desde SecretStorage. La respuesta añade controls a los campos existentes sin cambiar scoring. El límite individual es 20 análisis por hora por defecto y se configura con OWASP_GUARD_API_SCAN_LIMIT_PER_HOUR.
GET /api/v1/runs/<id> y GET /api/v1/runs: reportes del propietario, requieren token personal. El backend guarda solo un hash; el token caduca a los 90 días y puede revocarse desde la cuenta. Nunca se debe entregar la clave maestra del backend a usuarios externos.
- ZIP en memoria; excluye
.git, dependencias, caches, .reports, .terraform, .env*, credenciales/claves y contenido con posibles secretos. Los archivos excluidos no quedan evaluados: los filtros no son una garantía de ausencia de secretos.
- Rechaza enlaces que resuelven fuera de la carpeta y aplica límites de archivos, rutas y tamaño antes del envío. HTTPS remoto; HTTP solo loopback. No sigue redirecciones. Salud tiene timeout de 5 s y peticiones autenticadas de 120 s.
- El contenido analizado nunca se ejecuta, importa ni instala. Los errores de API se traducen sin reproducir cuerpos que pudieran contener credenciales.
Licencia
Esta versión no especifica una licencia de software ni incluye un archivo LICENSE. Antes de publicar o redistribuir, los responsables del proyecto deben aprobar la licencia y agregar su texto y el identificador correspondiente al manifiesto.
Paquete instalable y prueba en host real
npx --yes @vscode/vsce@4.1.1 package --no-dependencies --allow-missing-repository --skip-license --out ../.reports/u209/guard-sast-analyzer-0.2.0.vsix
El comando anterior se ejecuta desde vscode-extension/. No publica en Marketplace y no asigna una licencia inexistente. Instalar localmente con code --install-extension .reports/u209/guard-sast-analyzer-0.2.0.vsix desde la raíz, o Extensions: Install from VSIX.
$env:OWASP_GUARD_TEST_API_KEY = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
npm run test:host --prefix vscode-extension
El arnés crea una carpeta sintética, API local y SQLite aisladas y abre VS Code con un driver de prueba no incluido en el VSIX. La persona debe confiar solo en esa carpeta, introducir el valor efímero de OWASP_GUARD_TEST_API_KEY y aceptar el diálogo. La prueba consulta la colección real de Problems y compara OG-05.1/archivo/línea con la API; cada ejecución guarda evidencia en una carpeta nueva de .reports/u209/host/sessions/, anunciada como HOST_TEST_EVIDENCE, sin sobrescribir pruebas anteriores. Espera hasta 15 minutos y nunca aprueba una interacción incompleta. En equipos donde una ventana lanzada desde shell no sea visible, abrir VS Code normalmente y ejecutar con OWASP_GUARD_HOST_USE_CURRENT_PROFILE=true; no modifica ajustes globales del servidor, y limpia la clave efímera al terminar correctamente.
Regresión SQL portable desde la raíz: python -m pytest -q tests/unit/test_u209_sql_regression.py. Usa el mismo fixture seguro que el E2E de la extensión; lee su AST sin importar ni ejecutar el proyecto y ejecuta únicamente la consulta conocida sobre SQLite en memoria.
Evidencia y límites de esta fase
La prueba Node E2E usa Flask y SAST reales con diálogos VS Code sustituidos por un doble de prueba. Conserva reportes reales antes/después al fijar OWASP_GUARD_TEST_EVIDENCE a una carpeta de salida. La parametrización literal verificada lleva OG-05.1 de NO_CUMPLE a CUMPLE; el proyecto posterior sigue REQUIERE_REVISION, sin aprobación global de seguridad.
El host real VS Code 1.146.0 verificó 11 comandos, 27 controles, el consentimiento y la exclusión de .env. Problems mostró tres diagnósticos antes y dos después: OG-05.1 pasó de NO_CUMPLE a CUMPLE, sin diagnóstico SQL residual. Se corrigió una incompatibilidad de mayúsculas de unidad entre las URI /C:/ y /c:/ de Windows, manteniendo el rechazo de rutas externas y otros proveedores.
Copilot descubrió Guard SAST Analyzer Assistant e invocó realmente guard-sast-quality. El agente revisó el reporte, solicitó autorización y después editó solo el app.py propio de prueba. Comparó los reportes posteriores sin declarar seguridad global. Codex ejecutó fuera de Copilot cinco regresiones SQL sobre SQLite en memoria; no se importó ni ejecutó app.py. No se ensayó la ejecución de pruebas mediante la herramienta execute de Copilot. Evidencias locales en .reports/u209/host/ y detalle en PROGRESS_UNIDAD_II.md.
Se detectó un posible falso positivo del motor al parametrizar mediante una variable SQL intermedia: el reporte conservó NO_CUMPLE. Se conserva ese resultado para revisión; no se alteró la regla para esta fase. La clave ficticia de la prueba manual permanece exclusivamente en SecretStorage del perfil utilizado; al terminar la demostración, la persona puede ejecutar Guard SAST Analyzer: Eliminar token personal. Nunca usar una credencial real para esta muestra.
Referencias oficiales: contribuciones VS Code, Agent Skills, agentes personalizados.