Cómo leer un informe de CodeAuditAgent y actuar sobre él

Un informe de seguridad solo sirve si se convierte en correcciones fusionadas. Los informes de CodeAuditAgent están diseñados en torno a eso: cada hallazgo es lo bastante concreto como para verificarlo rápido y viene con un parche que puedes adaptar. Esta guía explica cada parte de un informe, cómo triarlo cuando no tienes un ingeniero de seguridad dedicado y cómo confirmar que tus correcciones funcionaron.

Qué se audita

Una auditoría se ejecuta sobre un repositorio público de GitHub o sobre un fragmento de código que pegues. Para los repositorios, CodeAuditAgent lee la rama por defecto. Los repositorios privados no se pueden auditar por URL, y todavía no hay comentarios en pull requests; los resultados viven en el panel y en las exportaciones.

Cuánto se lee de un repositorio depende de tu plan. El plan Gratis cubre 1 repositorio, 3 auditorías al mes y hasta 20 archivos por auditoría. Starter, por 49 $ al mes, cubre 5 repositorios, 50 auditorías y 40 archivos por auditoría. Pro, por 199 $ al mes, cubre repositorios ilimitados, 500 auditorías y 80 archivos por auditoría. Los archivos individuales de más de 60 KB se omiten. Los contadores mensuales de auditorías se reinician al principio de cada mes natural (UTC). Un fragmento pegado es además una forma rápida de revisar un archivo que te preocupa antes de auditar el repositorio entero.

Cuando quedan archivos fuera por estos límites, el informe se marca como instantánea parcial. Toma esa etiqueta en serio. Un informe parcial limpio significa que los archivos que se leyeron parecen limpios, no que el repositorio lo esté. Si se omitió justo el código que más te importa, audítalo como fragmento pegado o con un plan que cubra más archivos.

La puntuación de riesgo

En la parte superior de cada informe hay una puntuación de riesgo de 0 a 100; la exportación en Markdown indica además la severidad global junto a ella. Más alta significa más riesgo. Es un resumen de los hallazgos de esa auditoría, útil para dos cosas: decidir con qué urgencia mirar un repositorio y seguir si va mejorando con el tiempo.

No leas demasiado en las pequeñas diferencias entre repositorios sin relación. Una puntuación es siempre relativa a lo que se auditó, y una instantánea parcial ve menos código. Comparar el mismo repositorio antes y después de las correcciones es donde el número tiene más significado.

Severidad y confianza

Cada hallazgo tiene una severidad y una confianza. Responden a preguntas distintas: la severidad es lo malo que sería si el hallazgo es real, y la confianza es lo seguro que está el revisor de que lo sea.

• Crítica: directamente explotable y con impacto grave, como una inyección en un endpoint público, un bypass de autenticación o credenciales de producción expuestas.
• Alta: una vulnerabilidad real que necesita alguna precondición, o que tiene un impacto significativo pero limitado.
• Media: una debilidad que importa combinada con otros bugs, o que tiene un impacto moderado.
• Baja: problemas de endurecimiento y huecos de defensa en profundidad.
• Informativa: observaciones que conviene conocer pero que no son vulnerabilidades por sí solas.

La confianza es alta, media o baja. Un hallazgo de confianza alta tiene evidencia clara en el código que se leyó. Un hallazgo de confianza baja suele depender de algo que la auditoría no pudo ver, como un middleware en otro archivo, una política de base de datos o un valor de configuración fijado en el despliegue. Confianza baja no significa ignorarlo; significa que una persona debería revisar el contexto que falta antes de corregir.

Anatomía de un hallazgo

Todos los hallazgos siguen la misma estructura, así que puedes verificarlos en un orden constante.

• Título y CWE: la clase de debilidad, como CWE-639 para un bypass de autorización mediante una clave controlada por el usuario. El CWE te dice qué tipo de corrección esperar.
• Ubicación: el archivo y la línea, para que puedas abrir el código directamente.
• Evidencia: el código relevante citado del archivo. Comprueba que la cita coincide con tu código actual; si la línea ya ha cambiado, el hallazgo puede estar obsoleto.
• Escenario de explotación: cómo usaría realmente un atacante la debilidad, paso a paso. Es la forma más rápida de juzgar si es real en tu contexto.
• Parche de remediación: un cambio propuesto en el estilo del código que lo rodea.

Trata el parche como un buen punto de partida, no como un commit listo para fusionar. Está escrito a partir del código que la auditoría leyó, así que puede no conocer tus funciones helper, tus convenciones de ORM o algún llamador en otro punto de la base de código. Un parche típico es pequeño y concreto:

--- a/app/api/invoices/[id]/route.ts
+++ b/app/api/invoices/[id]/route.ts
@@
-  const invoice = await db.invoice.findUnique({ where: { id } });
+  const invoice = await db.invoice.findFirst({
+    where: { id, userId: session.user.id },
+  });
   if (!invoice) return Response.json({ error: 'not_found' }, { status: 404 });

Observaciones positivas y próximos pasos

Los informes también enumeran lo que está bien hecho: consultas parametrizadas usadas de forma consistente, secretos cargados desde el entorno, una configuración estricta de cookies. Merece la pena leerlas. Te dicen qué patrones conservar y copiar al código nuevo, y son útiles al explicarle a otra persona el estado de una base de código.

La sección de próximos pasos recomendados convierte los hallazgos en un plan ordenado. A menudo agrupa hallazgos relacionados, por ejemplo varias comprobaciones de propiedad ausentes que se corrigen mejor con un helper compartido que con cinco parches separados.

Un flujo de triaje para equipos pequeños

Sin un ingeniero de seguridad, el riesgo no es ignorar un informe; es pasarse un día con hallazgos bajos mientras uno crítico espera. Un orden sencillo funciona bien:

• Lee primero todos los hallazgos críticos y altos. Para cada uno, lee el escenario de explotación y decide: real, no real, o necesita contexto.
• Corrige el mismo día los hallazgos críticos reales. Si una corrección necesita tiempo, añade una mitigación temporal como desactivar el endpoint o endurecer una comprobación.
• Para los hallazgos que necesitan contexto, revisa la pieza que falta: ¿hay un middleware, una política a nivel de fila o una configuración que ya lo impide? Anota la respuesta.
• Planifica los hallazgos altos en el sprint actual, los medios en el backlog, y agrupa los bajos e informativos en una pasada de endurecimiento.
• Cuando un hallazgo no sea real, deja constancia de por qué. Esa nota ahorra a la siguiente persona tener que investigarlo otra vez.

Asigna cada hallazgo a un único responsable. Los hallazgos compartidos por todo el equipo tienden a no ser de nadie.

El explorador de hallazgos y las exportaciones

Una vez que tienes varias auditorías, el explorador de hallazgos es más cómodo que los informes individuales. Lista los hallazgos de todas las auditorías y los filtra por severidad, CWE y repositorio. Filtrar por CWE es especialmente útil: si la misma debilidad aparece en tres repositorios, suele apuntar a un patrón compartido o a un helper que falta, y corregir el patrón sale más barato que corregir cada caso.

Los hallazgos se pueden exportar a CSV desde el explorador, lo que viene bien para importarlos a un gestor de incidencias o a una hoja de cálculo. Los informes individuales se pueden exportar en Markdown, que queda bien en la descripción de un pull request, en un wiki interno o en un mensaje a un contratista que va a hacer la corrección.

Vuelve a auditar para confirmar la corrección

Una corrección no está hecha hasta que la has comprobado. Después de fusionar, ejecuta una auditoría nueva sobre el mismo repositorio. Cada informe se puede comparar con la auditoría anterior, así que puedes ver qué hallazgos han desaparecido, cuáles siguen y si ha aparecido algo nuevo. La puntuación de riesgo debería bajar cuando se corrigen problemas reales; si no baja, mira la comparación para ver por qué.

Mantén la comparación justa. Si la primera auditoría fue una instantánea parcial y la segunda leyó archivos distintos, la diferencia refleja tanto la cobertura como las correcciones. Las auditorías salen de tu cuota mensual, así que normalmente compensa agrupar varias correcciones antes de reauditar en lugar de relanzarla tras cada commit.

Qué no cubre un informe

Conocer los límites ayuda a rellenar los huecos. Las auditorías leen tu código fuente; no escanean las dependencias en busca de versiones vulnerables conocidas, así que mantén también en marcha un escáner de dependencias como el que trae tu gestor de paquetes o GitHub. Las auditorías no ven la configuración de despliegue, la infraestructura fuera del repositorio ni los archivos que se omitieron. Y como cualquier revisor, humano o de IA, la auditoría puede equivocarse: la evidencia y los niveles de confianza están ahí para que puedas comprobarla rápido en lugar de creerla sin más.

Usado así, un informe se convierte en una lista corta y priorizada de cambios con evidencia adjunta. Corrige los críticos, comprueba los dudosos, vuelve a auditar y observa cómo se mueve la puntuación.