- Guía de revisión de código de Agents Please: Usa un proceso repetible para las revisiones de pull requests asistidas por IA.
- Primera prioridad: Confirma el alcance, los permisos, los secretos y la revisión exacta que se está analizando.
- Mejor flujo de trabajo: Examina ampliamente, rastrea los flujos de datos riesgosos y valida manualmente los hallazgos.
- Advertencia principal: Trata los hallazgos generados como hipótesis hasta que un desarrollador los reproduzca.
- Comprobación final: Exige pruebas, revisión del parche y cobertura de regresión antes de aprobar.
Guía de revisión de código de Agents Please: alcance y seguridad
La guía de revisión de código de Agents Please está diseñada para equipos que utilizan un agente de IA para inspeccionar pull requests, repositorios o ejemplos de código aislados. El objetivo no es reemplazar a los revisores. Se trata de acelerar la preparación de las revisiones, detectar rutas sensibles para la seguridad y ofrecer a los ingenieros una lista más clara de preguntas que investigar.
Comienza con un límite de revisión reducido. Identifica la rama, el commit, los archivos modificados, los lenguajes de programación, los comandos de prueba y los directorios a los que el agente puede acceder. Un alcance restringido facilita la auditoría de los resultados y reduce la posibilidad de que el código heredado no relacionado abrume la revisión.
Nunca proporciones credenciales de producción, claves privadas, registros de clientes ni acceso de shell sin restricciones únicamente para mejorar la cobertura de la revisión. Usa un checkout desechable, tokens con privilegios mínimos y datos de prueba sanitizados siempre que sea posible.
Límites de la revisión
| Elemento de revisión | Decisión recomendada | Por qué es importante |
|---|---|---|
| Commit o pull request | Registra una revisión exacta | Evita que los hallazgos cambien a medida que se modifica el código |
| Alcance de archivos | Incluye los archivos modificados y sus dependencias directas | Equilibra el contexto con un resultado manejable |
| Secretos | Elimínalos, revócalos o enmascáralos | Limita la exposición accidental |
| Herramientas | Permite primero búsquedas de solo lectura | Reduce las modificaciones involuntarias |
| Comandos de prueba | Aprueba únicamente comandos seguros y deterministas | Evita scripts destructivos y efectos secundarios de red |
Qué debería responder una revisión útil
Una revisión sólida asistida por IA debería ayudar a responder cinco preguntas:
- ¿Qué cambió y qué comportamiento afecta?
- ¿Dónde entra la entrada no confiable en el sistema?
- ¿Qué funciones, servicios o permisos reciben esa entrada?
- ¿Qué evidencia respalda cada problema reportado?
- ¿Qué prueba o parche reduciría el riesgo?
Un informe que solo enumera preocupaciones genéricas es menos útil que uno más breve que incluya rutas de archivos, símbolos afectados, razonamiento sobre el flujo de datos y un paso práctico de verificación.
Alcance
- Commit exacto
- Archivos modificados
- Dependencias relacionadas
- Exclusiones de la revisión
Seguridad
- Gestión de secretos
- Límites de permisos
- Límites de entrada
- Llamadas externas
Evidencia
- Archivo y línea
- Ruta de reproducción
- Nivel de confianza
- Suposiciones
Resolución
- Parche sugerido
- Prueba de regresión
- Responsable
- Estado de verificación
Prepara una revisión asistida por IA
La preparación determina si un agente produce un análisis práctico o una colección ruidosa de suposiciones. Antes de comenzar, redacta un resumen breve de la revisión en lenguaje sencillo. Incluye el objetivo de la funcionalidad, los límites de confianza esperados, las operaciones sensibles conocidas y las áreas que no deben modificarse.
En un servicio web, el resumen puede identificar la autenticación, la autorización, las cargas de archivos, los trabajos en segundo plano, las solicitudes a terceros, las escrituras en la base de datos y las integraciones con modelos o prompts. En una biblioteca, puede centrarse en analizadores inseguros, serialización, cambios de dependencias y compatibilidad de la API pública.
Pide al agente que explique cómo viaja la entrada desde el origen hasta el destino. Esto suele ser más valioso que pedirle que “encuentre todos los errores”, porque la instrucción más específica produce evidencia que un revisor puede cuestionar.
Plantilla del resumen de revisión
| Sección del resumen | Contenido de ejemplo | Beneficio para la revisión |
|---|---|---|
| Objetivo de la funcionalidad | Añade alertas de webhook configurables por el usuario | Define el comportamiento previsto |
| Límites de confianza | La configuración del usuario llega a un cliente HTTP saliente | Destaca un posible riesgo de SSRF |
| Activos sensibles | Tokens, datos de inquilinos, metadatos internos | Establece el impacto |
| Comprobaciones necesarias | Autorización, validación de URL, gestión de errores | Crea una lista de comprobación enfocada |
| Verificación | Pruebas unitarias y solicitudes de red simuladas | Define los criterios de finalización |
Conjunto práctico de instrucciones
Usa instrucciones que separen el descubrimiento, el razonamiento y la presentación de informes:
- Mapea el código modificado y sus llamadores directos.
- Identifica las entradas externas, los datos sensibles, las operaciones privilegiadas y las solicitudes de red.
- Rastrea los valores sospechosos a través de la validación, la transformación, el almacenamiento y la salida.
- Informa únicamente de problemas respaldados por evidencia del código.
- Distingue entre defectos confirmados, preocupaciones plausibles y preguntas para el autor.
- Sugiere pruebas sin aplicar cambios, a menos que se autorice explícitamente.
Esta estructura también ayuda a prevenir un fallo común: el agente detecta un patrón peligroso, pero no comprueba si un validador, un control del framework o un permiso ascendente ya impide su explotación.
Fija el objetivo de la revisión
Registra el repositorio, la rama, el hash del commit y la lista de archivos modificados. Si el pull request cambia durante el análisis, reinicia el proceso o marca claramente la nueva revisión.
Describe el modelo de confianza
Identifica a los usuarios anónimos, los usuarios autenticados, los administradores, las cuentas de servicio, los trabajadores en segundo plano y los sistemas de terceros. Indica qué roles pueden acceder a cada operación afectada.
Define los destinos de alto riesgo
Destaca las consultas a bases de datos, los analizadores de archivos, el renderizado de plantillas, las solicitudes salientes, los comandos de shell, la deserialización, el uso de credenciales y las comprobaciones de permisos.
Solicita hallazgos basados en evidencia
Exige una ruta, un símbolo o rango de líneas, el origen de la entrada, la operación peligrosa, el impacto, la confianza y un método de verificación sugerido para cada hallazgo.
Revisa manualmente el resultado
Reproduce las afirmaciones importantes, inspecciona el código cercano, comprueba los controles existentes y decide si el problema es válido, está mitigado o es incorrecto.
Prioriza los hallazgos y rastrea el flujo de datos
La revisión de código con IA es más eficaz cuando los hallazgos se clasifican por explotabilidad e impacto, en lugar de por lo alarmante que suene su redacción. Un comentario ausente y una solicitud del lado del servidor controlada por el usuario no deberían recibir la misma atención.
Comienza por las rutas que conectan entradas no confiables con comportamientos privilegiados o visibles externamente. Algunos ejemplos habituales son los parámetros de solicitud que llegan a consultas de bases de datos, el contenido cargado que llega a analizadores, las URL configurables que llegan a clientes HTTP o el texto del usuario que se inserta en las instrucciones destinadas a otro modelo.
Un problema con alta confianza puede tener un impacto limitado, mientras que un problema grave puede permanecer sin confirmar hasta comprender el entorno. Registra por separado la confianza y el impacto en el informe.
Clasificación de hallazgos
| Tipo de hallazgo | Estándar de evidencia | Acción del revisor |
|---|---|---|
| Defecto confirmado | Ruta clara y control ausente | Reproducir, corregir y añadir cobertura de regresión |
| Preocupación probable | Patrón sólido, pero contexto incompleto | Inspeccionar las dependencias y la lógica circundante |
| Pregunta de diseño | El comportamiento puede ser intencionado | Pedir al responsable que aclare el modelo de confianza |
| Falso positivo | Un control existente bloquea la ruta | Documentar el control y cerrar el hallazgo |
| Informativo | Problema de mantenibilidad o refuerzo de seguridad | Programarlo según las prioridades del equipo |
Matriz de triaje de riesgos
| Impacto | Confianza | Prioridad |
|---|---|---|
| Alto | Alta | Investigación inmediata |
| Alto | Media | Validar antes de fusionar |
| Medio | Alta | Corregir en el cambio actual cuando sea práctico |
| Medio | Baja | Solicitar más contexto |
| Bajo | Cualquiera | Agrupar con el trabajo de mantenimiento |
Al revisar una vulnerabilidad sospechosa, pide al agente que muestre la cadena completa:
- Origen: ¿De dónde procede el valor?
- Transformación: ¿Se decodifica, analiza, concatena o normaliza?
- Control: ¿Qué validación, autorización, codificación o lista de permitidos se aplica?
- Destino: ¿Qué operación utiliza el valor?
- Impacto: ¿Qué podría provocar un atacante o un usuario que cause un funcionamiento incorrecto?
- Verificación: ¿Qué prueba segura demuestra la afirmación?
Por ejemplo, una solicitud saliente no es automáticamente un problema de falsificación de solicitudes del lado del servidor. El revisor debe establecer si un atacante puede influir en el destino, si se puede acceder a direcciones privadas o de metadatos, si las redirecciones están controladas y si la aplicación cuenta con una política de destinos aprobados.
Del mismo modo, una cadena insertada en un prompt no constituye automáticamente una inyección de prompts exitosa. La revisión debe identificar el límite del modelo, la autoridad de la salida generada, las herramientas disponibles y si el contenido no confiable está claramente separado de las instrucciones del sistema.
Revisa patrones sensibles para la seguridad
Una revisión enfocada debe examinar patrones que suelen crear defectos sin asumir que cada coincidencia es explotable. Las siguientes categorías son puntos de partida útiles para un flujo de trabajo de Agents Please.
Usa valores de prueba de concepto inofensivos y redacta los tokens, los datos personales, los nombres de host internos y los comandos destructivos. Un informe de revisión debe demostrar el riesgo sin convertirse en una guía de ataque.
| Patrón | Preguntas que debes hacer | Indicador de revisión más seguro |
|---|---|---|
| Solicitud HTTP saliente | ¿Pueden los usuarios controlar el esquema, el host, el puerto o las redirecciones? | Destinos validados y acceso de red restringido |
| Consulta a la base de datos | ¿La entrada se vincula como dato o se une al texto de la consulta? | Consultas parametrizadas y permisos limitados |
| Carga de archivos | ¿Están restringidos el tipo, el tamaño, el nombre y la ubicación de almacenamiento? | Nombres aleatorios, almacenamiento aislado y análisis seguro |
| Salida de plantilla o HTML | ¿El contenido no confiable está codificado para su contexto de salida? | Escape consciente del contexto y renderizado seguro |
| Comprobación de autorización | ¿Se comprueba el acceso en el servidor para cada objeto? | Política centralizada y validación de propiedad |
| Construcción de prompts | ¿Puede el texto no confiable anular los límites de la tarea? | Contenido delimitado, herramientas restringidas y validación de salida |
| Deserialización | ¿Pueden los datos controlados por un atacante seleccionar clases o comportamientos? | Formatos seguros y esquemas explícitos |
| Contexto del inquilino o de la cuenta | ¿Puede un llamador elegir directamente otro ámbito? | Contexto derivado del servidor y comprobaciones de autorización |
Estándares para revisar parches
Una corrección propuesta debe abordar la causa en lugar de ocultar únicamente el síntoma reportado. Comprueba si:
- Valida la entrada en el límite de confianza correcto.
- Conserva el comportamiento esperado para los usuarios legítimos.
- Aplica la autorización a todas las rutas de código relevantes.
- Gestiona los fallos sin filtrar detalles sensibles.
- Incluye una prueba de regresión que fallaría sin la corrección.
- Evita introducir un segundo bypass mediante endpoints alternativos o trabajos en segundo plano.
Controles de entrada
Valida el formato, la longitud, la codificación y los valores permitidos antes de realizar operaciones peligrosas.
Controles de acceso
Deriva la identidad y el ámbito del contexto confiable del servidor y, después, aplica permisos a nivel de objeto.
Controles de salida
Codifica, filtra, restringe o revisa los datos antes de devolverlos a los usuarios, intérpretes o servicios externos.
Finaliza la revisión y realiza el seguimiento de las correcciones
La revisión no termina cuando el agente produce un informe. Termina cuando el equipo ha decidido qué hallazgos son válidos, ha asignado responsables, ha aplicado las correcciones adecuadas y ha verificado que el cambio funciona de forma segura.
Mantén separados los hallazgos aceptados de las preguntas sin resolver. Esto evita que un informe extenso oculte el pequeño número de problemas que bloquean el lanzamiento. También crea un historial útil para futuros revisores que puedan encontrarse con la misma ruta de código.
Aprueba únicamente después de que los hallazgos importantes tengan una resolución: corregidos, mitigados, aceptados con un responsable o cerrados con evidencia documentada. “El agente dice que es seguro” no es una resolución suficiente.
Tabla de finalización de la revisión
| Etapa | Evidencia necesaria | Indicador de finalización |
|---|---|---|
| Descubrimiento | Alcance y mapa de archivos modificados | El revisor comprende el cambio |
| Análisis | Hallazgos con rutas y razonamiento | Las afirmaciones pueden cuestionarse |
| Triaje | Etiquetas de impacto y confianza | Las prioridades están claras |
| Corrección | Parche y prueba de regresión | Se aborda la causa raíz |
| Verificación | Pruebas, comprobaciones manuales o reproducción segura | La corrección funciona según lo previsto |
| Cierre | Responsable, estado y justificación | El registro de revisión es auditable |
Lista de comprobación para completar la revisión de código:
- Confirma el commit exacto y el alcance de la revisión
- Elimina los secretos y restringe los permisos del agente
- Rastrea la entrada no confiable hasta las operaciones sensibles
- Clasifica los hallazgos por impacto y confianza
- Verifica las correcciones con pruebas o una reproducción segura
- Registra los riesgos aceptados y el trabajo de seguimiento pendiente
Un informe final útil es conciso, pero específico. Para cada problema aceptado, incluye el componente afectado, el riesgo, la evidencia, la corrección recomendada, el responsable y el estado de verificación. Para cada problema rechazado, registra el control o la suposición que lo hizo inválido. Esto reduce las investigaciones repetidas durante pull requests posteriores.
Si el mismo falso positivo aparece con frecuencia, mejora las instrucciones de revisión o añade orientación al repositorio. Si el mismo defecto real aparece repetidamente, invierte en un helper compartido, un control del framework, una regla de lint, un fixture de pruebas o un cambio arquitectónico en lugar de depender de la detección manual repetida.
Guarda ejemplos breves de hallazgos aceptados, hallazgos rechazados y correcciones preferidas. Con el tiempo, estos ejemplos harán que las instrucciones para futuros agentes sean más precisas y ayudarán a los revisores humanos a calibrar su criterio.
Preguntas frecuentes: flujos de trabajo de revisión de código de Agents Please
Q: ¿Cuál es la forma más segura de iniciar un flujo de trabajo de la guía de revisión de código de Agents Please?
Comienza con un checkout desechable, un commit exacto, herramientas de solo lectura, datos sanitizados y un alcance de archivos reducido. Pide al agente que mapee el cambio antes de solicitar hallazgos de seguridad.
Q: ¿Una vulnerabilidad generada por IA debería bloquear inmediatamente un pull request?
No por sí sola. Trata el informe como una hipótesis y, después, comprueba el flujo de datos completo, los controles existentes, la explotabilidad y el comportamiento esperado. Bloquea únicamente después de que un revisor cualificado confirme el riesgo o de que el equipo adopte una política documentada.
Q: ¿Cómo deben revisarse las preocupaciones relacionadas con la inyección de prompts?
Identifica qué contenido no es confiable, dónde entra en el prompt, qué autoridad tiene el modelo, qué herramientas o acciones están disponibles y cómo se validan las salidas. El riesgo depende del límite completo del sistema, no solo de la interpolación de cadenas.
Q: ¿Qué hace que un hallazgo de revisión de código sea práctico?
Un hallazgo práctico identifica el archivo o símbolo afectado, explica la ruta desde la entrada hasta el destino, describe un impacto realista, indica la confianza, propone una corrección específica e incluye un método de verificación seguro.
Usa la IA para ampliar la cobertura de las revisiones y organizar la evidencia, pero mantén el control del alcance, las decisiones de riesgo y la aprobación final en manos de ingenieros humanos responsables.