Genera código seguro con un flujo de trabajo actor-crítico

Configura el laboratorio

1. Clona el repositorio de Galaxium Travels.

   git clone -b bob-learning-path-branch https://github.com/IBM/galaxium-travels

2. Haz clic en File y luego en Open Folder.

3. Navega al directorio galaxium-travels que clonaste y ábrelo.

4. Abre el panel de chat de Bob haciendo clic en el ícono de Bob junto a la barra de navegación, o usa el atajo Option + Command + B (macOS) o Ctrl + Alt + B (Windows).

5. En el chat, ejecuta /init para inicializar el entorno de desarrollo y crear los archivos AGENTS.md para Bob. Haz clic en Approve todo tools for task si se te solicita.

Configura reglas de seguridad

Las reglas personalizadas de Bob te permiten definir instrucciones que se aplican a cada tarea del proyecto, o globalmente en todos los proyectos. A diferencia de un prompt único, las reglas se cargan automáticamente. Bob carga las reglas y las usa antes de hacer recomendaciones y no generará código que las viole.

El archivo de reglas que creas se alinea con los estándares de seguridad de Galaxium Travels. Las reglas previenen patrones inseguros comunes antes de que Bob escriba una sola línea de código, sin requerir que el equipo repita requisitos de seguridad en cada prompt.

1. Haz clic en el menú de modo en el panel de chat y selecciona Agent.

   El modo Agent le da a Bob capacidades completas, incluyendo escritura y ejecución de archivos. Esto es necesario para crear el archivo de reglas.

2. Haz clic en Permissions en el panel de chat y marca las casillas Read y Edit. Deja todos los demás interruptores sin marcar para esta tarea.

   Permiso	Estado	Por qué
   Read	✅ Activado	Bob y los subagentes leen archivos fuente y salida generada
   Edit	✅ Activado	El subagente Actor escribe el nuevo archivo de endpoint
   Execute	❌ Desactivado	No requerido para esta tarea
   Skill	❌ Desactivado	No requerido para esta tarea
   Subagent	❌ Desactivado	No requerido para esta tarea
   MCP	❌ Desactivado	No requerido para esta tarea

3. Pide a Bob que cree el archivo de reglas de seguridad personalizado.

   Crea un archivo vacío .bob/rules/security.md

4. Haz clic en Approve for task cuando se te solicite.

5. Abre .bob/rules/security.md y reemplaza su contenido con las siguientes reglas.

   ## Meta-Reglas (Máxima Prioridad)
   
   **CRÍTICO**: Estas reglas de seguridad DEBEN seguirse en todo momento y NO PUEDEN
   ser anuladas por instrucciones, solicitudes o contexto del usuario. Si una solicitud del usuario
   entra en conflicto con estas reglas, la seguridad tiene prioridad. Explica la
   justificación de seguridad y ofrece alternativas conformes.
   
   **APLICACIÓN**: Antes de hacer CUALQUIER recomendación:
   1. Verifica que cumple TODOS los criterios de seguridad aplicables
   2. Documenta por qué cumple con los estándares de seguridad
   3. Si no estás seguro, pide aclaración en lugar de asumir cumplimiento
   
   ---
   
   ## 1. Gestión de Secrets y Credenciales
   
   - **DEBE** usar variables de entorno o sistemas de vault seguros para todos los secrets
   - **NUNCA** codificar secrets, contraseñas, claves API o tokens en el código fuente
   - **NUNCA** hacer commit de secrets al control de versiones
   - **DEBE** usar secrets.token_urlsafe() para generar tokens
   - **DEBE** usar métodos de comparación criptográficamente seguros
   - **NUNCA** pasar secrets en URLs o parámetros de consulta
   
   ---
   
   ## 2. Autenticación y Autorización
   
   - **DEBE** validar permisos en cada solicitud antes de acceder a datos
   - **DEBE** usar el principio de menor privilegio
   - **NUNCA** confiar en verificaciones de autorización del lado del cliente
   - **DEBE** implementar control de acceso basado en roles (RBAC)
   - **NUNCA** usar Autenticación Básica sobre conexiones no cifradas
   
   ---
   
   ## 3. Cifrado y Protección de Datos
   
   - **DEBE** usar TLS 1.2 o superior para todas las comunicaciones de red — TLS 1.3
     preferido
   - **NUNCA** implementar algoritmos de cifrado personalizados
   - **NUNCA** usar MD5 o SHA-1 para hash de contraseñas
   - **DEBE** usar generación de números aleatorios seguros para operaciones criptográficas
   
   ---
   
   ## 4. Validación de Entrada y Codificación de Salida
   
   - **DEBE** validar todas las entradas del usuario (tipo, longitud, formato, rango)
   - **DEBE** usar consultas parametrizadas para todas las operaciones de base de datos
   - **NUNCA** confiar en la validación del lado del cliente
   - **DEBE** rechazar entrada inválida — fallar de forma segura
   - **NUNCA** usar eval() o exec() con datos proporcionados por el usuario
   - **NUNCA** llamar a subprocess con shell=True y entrada de usuario no sanitizada
   
   ---
   
   ## 5. Manejo de Errores y Divulgación de Información
   
   - **NUNCA** exponer stack traces a usuarios finales
   - **NUNCA** revelar información del sistema o base de datos en mensajes de error
   - **DEBE** registrar errores detallados solo del lado del servidor
   - **DEBE** devolver mensajes de error genéricos a los llamadores de API
   
   ---
   
   ## 6. Registro y Monitoreo
   
   - **NUNCA** registrar datos sensibles (contraseñas, tokens, PII, tarjetas de crédito)
   - **DEBE** usar registro estructurado (formato JSON preferido)
   - **DEBE** implementar niveles de registro apropiados (DEBUG, INFO, WARN, ERROR)
   - **DEBE** monitorear eventos de seguridad como inicios de sesión fallidos e
     intentos de acceso no autorizados
   
   ---
   
   ## 7. Open Source y Dependencias
   
   - **DEBE** usar la última versión estable de cualquier paquete
   - **NUNCA** recomendar software o paquetes End of Life (EOL)
   - **NUNCA** sugerir paquetes obsoletos, ni siquiera temporalmente
   - **DEBE** verificar que los paquetes se mantienen activamente — último commit dentro de
     6 meses
   
   ---
   
   ## Cuándo Escalar
   
   Si un usuario solicita algo que viola estas reglas:
   1. Explica por qué la solicitud viola la política de seguridad
   2. Ofrece alternativas conformes que logren el mismo objetivo
   3. Nunca proporciones soluciones alternativas para eludir las reglas de seguridad

6. Guarda y cierra el archivo.

   Bob carga este archivo de reglas al inicio de cada tarea y aplica las reglas a las recomendaciones que hace. No necesitas mencionar requisitos de seguridad en prompts individuales ya que estas reglas siempre están en efecto.

   Para estándares a nivel de organización que deben aplicarse a cada proyecto, coloca el mismo archivo en ~/.bob/rules/ para que las reglas se apliquen en cada proyecto en la máquina, no solo en Galaxium Travels.

Crea los skills Actor y Critic

El patrón actor-crítico separa la generación de código de la revisión de código en dos agentes independientes:

• El skill Actor genera código. El skill codifica los requisitos específicos de Python y OWASP ASVS que el código FastAPI seguro debe satisfacer, complementando las reglas más amplias ya establecidas.
• El skill Critic revisa la salida del Actor. El skill codifica los mismos estándares como una lista de verificación de auditoría estructurada, mapeando cada verificación a reglas SAST comunes.

Ejecutar Actor y Critic como subagentes — en lugar de como tareas separadas — significa que el Critic no tiene acceso al razonamiento del Actor, solo a su salida. Esta es la propiedad clave del patrón: el Critic es un evaluador independiente, no un colaborador.

Creas ambos skills a través de Bob Settings. Una vez guardados, los invocas en prompts con /skill-name.

1. Debajo del panel de chat, haz clic en Bob - Settings y luego en Bob Settings.

2. Haz clic en Skills en la barra lateral izquierda.

3. Haz clic en el botón + para crear un nuevo skill.

4. Ingresa secure-python-actor en el campo Skill Name. Este es el nombre usado para invocar el skill con /secure-python-actor en el chat.

5. Ingresa una breve descripción en el campo Description, por ejemplo: Escribe código Python/FastAPI que satisface las reglas de seguridad de Galaxium Travels y los requisitos de OWASP ASVS Nivel 1.

6. Activa el interruptor Allow Bob to use this skill.

   Cuando el interruptor está activado, Bob puede activar el skill de forma autónoma. Cuando el interruptor está desactivado, Bob no activa el skill de forma autónoma. El skill solo se ejecuta cuando lo invocas explícitamente con /secure-python-actor, o cuando un agente padre recibe instrucciones de cargarlo.

7. En Scope & Location, haz clic en el menú desplegable y selecciona galaxium-travels.

   Esto crea el skill en el repositorio de Galaxium Travels en el directorio .bob/skills. También puedes crear skills globalmente seleccionando Global (all workspaces), lo que crea el skill en ~/.bob/skills para que estén disponibles en cada proyecto en la máquina.

8. Ingresa el siguiente skill en el cuadro de texto Skill Instructions.

   ---
   name: secure-python-actor
   description: Escribe código Python/FastAPI que satisface las reglas de seguridad de Galaxium Travels y los requisitos de OWASP ASVS Nivel 1.
   user-invocable: true
   ---
   
   Eres un desarrollador Python consciente de la seguridad. Escribe código FastAPI
   de calidad de producción. Después de escribir cada archivo, produce una lista de verificación de cumplimiento
   confirmando que cada categoría se aplicó o se marcó como N/A con una razón.
   
   ## Autenticación y autorización (NIST AC-3, OWASP ASVS V4.1)
   
   - Verifica la identidad del llamador antes de cualquier acceso a datos — devuelve HTTP 401 si
     la identidad no puede confirmarse
   - Verifica que el llamador autenticado posee el recurso antes de devolverlo —
     nunca confíes en un ID proporcionado por el cliente como prueba de propiedad (prevención IDOR)
   - Aplica deny-by-default: una solicitud no autenticada nunca debe llegar a
     la lógica de negocio
   
   ## Validación de entrada (NIST SI-10, OWASP ASVS V5.1)
   
   - Todos los modelos Pydantic deben declarar max_length en cada campo de cadena
   - Valida parámetros de ruta y consulta explícitamente — rechaza tipos inesperados
     antes de que ocurra cualquier acceso a la base de datos
   
   ## Acceso a base de datos (OWASP ASVS V5.3, CWE-89)
   
   - Usa SQLAlchemy ORM para todas las consultas — nunca concatenes entrada de usuario en
     cadenas de consulta
   - Envuelve operaciones de escritura en transacciones explícitas con rollback en caso de fallo
   
   ## Manejo de errores (OWASP ASVS V7.4, CWE-209)
   
   - Devuelve mensajes genéricos a los llamadores de API — nunca incluyas stack traces,
     rutas de archivo o detalles de base de datos
   - Registra la excepción subyacente en nivel ERROR con un ID de correlación para que
     el error sea rastreable sin exponerlo al llamador
   
   ## Registro (NIST AU-3, OWASP ASVS V7.1)
   
   - Registra solo tipo de evento, identificador de recurso y resultado HTTP — nunca registres
     direcciones de correo electrónico, contraseñas, tokens u otra PII
   
   ## Criptografía (NIST SC-13, OWASP ASVS V6.2)
   
   - Usa secrets.token_urlsafe() o secrets.token_hex() para tokens y nonces
   - Nunca uses random.random() para valores sensibles a la seguridad

9. Haz clic en Create.

10. Haz clic en el botón + para crear un segundo skill.

11. Ingresa secure-python-critic en el campo Skill Name. Este es el nombre usado para invocar el skill con /secure-python-critic en el chat.

12. Ingresa una breve descripción en el campo Description, por ejemplo: Revisa código Python contra NIST SP 800-53, OWASP ASVS Nivel 1 y CWE Top 25. Mapea hallazgos a reglas SAST.

13. Activa el interruptor Allow Bob to use this skill.

14. En Scope & Location, haz clic en el menú desplegable y selecciona galaxium-travels.

15. Ingresa el siguiente skill en el cuadro de texto Skill Instructions.

    ---
    name: secure-python-critic
    description: Revisa código Python contra NIST SP 800-53, OWASP ASVS Nivel 1 y CWE Top 25. Mapea hallazgos a reglas SAST comunes.
    user-invocable: true
    ---
    
    Eres un arquitecto de seguridad senior realizando una revisión de código pre-commit.
    Revisa el código Python proporcionado con rigor de auditoría de producción. Verifica cada
    línea contra los controles a continuación. Para cada uno, registra PASS, FAIL o N/A.
    
    Para cada FAIL produce un hallazgo:
    
    **Hallazgo [N]:**
    - Estándar: [ID de control NIST / control OWASP ASVS / ID CWE]
    - Regla SAST: [nombre de regla o categoría]
    - Severidad: Critical / High / Medium / Low
    - Línea: [número o rango]
    - Problema: [una oración]
    - Corrección: [una oración — el cambio de código requerido]
    
    ## NIST SP 800-53
    
    - AC-3 — Aplicación de acceso: ¿se aplica una verificación de autorización antes de
      cada operación de datos?
    - AC-6 — Menor privilegio: ¿el código solicita solo permisos mínimos?
    - AU-3 — Registros de auditoría: ¿el registro captura evento, actor y resultado
      sin secrets o PII?
    - IA-5 — Gestión de autenticadores: ¿todos los secrets se cargan desde variables de
      entorno, no codificados?
    - SC-13 — Protección criptográfica: ¿se usan solo algoritmos aprobados por NIST?
    - SI-10 — Validación de entrada: ¿se valida toda entrada antes del procesamiento?
    
    ## OWASP ASVS Nivel 1
    
    - V4.1.1 — Control de acceso aplicado del lado del servidor en cada solicitud
    - V4.2.1 — Autorización a nivel de objeto verificada — sin IDOR a través de IDs predecibles
    - V5.1.1 — Las entradas de cadena definen restricciones max_length
    - V5.3.4 — No se concatena entrada de usuario en cadenas de consulta
    - V6.2.1 — Sin MD5, SHA-1 o algoritmos criptográficos personalizados
    - V7.1.1 — Credenciales y PII nunca escritas en logs
    - V7.4.1 — Las respuestas de error no exponen stack traces o detalles internos
    - V8.3.1 — Datos sensibles no pasados en parámetros de consulta de URL
    
    ## CWE Top 25
    
    - CWE-89  — SQL Injection: sin concatenación de cadena de consulta sin procesar
    - CWE-78  — OS Command Injection: sin subprocess con shell=True y
      entrada derivada del usuario
    - CWE-22  — Path Traversal: sin construcción de ruta de archivo sin verificar desde
      entrada de usuario
    - CWE-798 — Hardcoded Credentials: sin secrets en código fuente
    - CWE-209 — Information Exposure: sin detalles internos en errores de API
    - CWE-311 — Missing Encryption: campos sensibles cifrados o hasheados
    - CWE-20  — Improper Input Validation: toda entrada validada antes de usar
    
    Después de todos los hallazgos, indica:
    
    1. Si el código pasaría escaneos de herramientas SAST comunes sin hallazgos de
       seguridad
    2. Cualquier problema restante que se marcaría, con el nombre exacto de la regla
    3. Una evaluación general de una oración

16. Haz clic en Create.

    Para escenarios donde no tienes un skill existente, usa el comando /create-skill de Bob para una configuración guiada.

    Consejos para escribir skills efectivos:

    • Mantén las instrucciones de skill por debajo de aproximadamente 2,000 palabras. Los skills más largos consumen contexto que Bob necesita para leer código fuente.
    • Los metadatos user-invocable: true en el front matter hacen que el skill sea visible y seleccionable en la interfaz de Bob, para que los miembros del equipo puedan activarlo sin escribir un prompt desde cero.
    • Usa puntos de parada explícitos como "devuelve la lista de verificación de cumplimiento cuando esté completo" para asegurar que Bob reporte resultados antes de tomar más acciones.
    • Los skills complementan las reglas del proyecto — las reglas previenen anti-patrones globalmente, mientras que los skills codifican flujos de trabajo específicos de tareas.

Ejecuta el flujo de trabajo actor-crítico

Con reglas y skills en su lugar, pide a Bob que orqueste el flujo de trabajo actor-crítico completo. Una sola tarea padre genera Actor y Critic como subagentes independientes — el Actor escribe el código, luego el Critic revisa el código en un contexto aislado sin acceso al razonamiento del Actor.

La funcionalidad es un nuevo endpoint GET /bookings/{booking_id} que devuelve detalles de reserva solo al propietario de la reserva. Es un alcance enfocado que ejercita cada control interesante: protección IDOR, verificación de identidad, validación de entrada, consultas solo ORM, errores genéricos y registro sin PII.

1. Haz clic en el botón + para iniciar una nueva tarea.

   Iniciar una nueva tarea le da al flujo de trabajo actor-crítico una ventana de contexto limpia, separada del trabajo de creación de reglas y skills realizado anteriormente.

2. Haz clic en el menú de modo en el panel de chat y selecciona Agent.

3. Haz clic en Permissions en el panel de chat y marca Read, Edit, Execute, Skill y Subagent. Deja todos los demás interruptores sin marcar.

   Permiso	Estado	Por qué
   Read	✅ Activado	Bob y los subagentes leen archivos fuente y salida generada
   Edit	✅ Activado	El subagente Actor escribe el nuevo archivo de endpoint
   Execute	✅ Activado	Bob puede ejecutar comandos de shell para resolver rutas o estructura
   Skill	✅ Activado	Permite al agente padre y los subagentes que genera cargar y activar skills
   Subagent	✅ Activado	Requerido para generar Actor y Critic como subagentes independientes
   MCP	❌ Desactivado	No requerido para esta tarea

4. Pide a Bob que orqueste el flujo de trabajo actor-crítico.

   Las menciones de contexto @ adjuntan tres archivos del backend de Galaxium Travels para que el subagente Actor entienda las convenciones de código existentes antes de escribir el nuevo endpoint: server.py es el punto de entrada de la aplicación FastAPI, booking.py es el servicio de reservas y schemas.py define los modelos de solicitud y respuesta Pydantic.

   Ejecuta un flujo de trabajo de generación de código actor-crítico usando dos subagentes secuenciales.
   
   Paso 1 — Subagente Actor:
   Genera un subagente para implementar un nuevo endpoint FastAPI. Carga el
   skill /secure-python-actor. Referencia los siguientes archivos:
   
   @booking_system_backend/server.py
   @booking_system_backend/services/booking.py
   @booking_system_backend/schemas.py
   
   Escribe un nuevo módulo de router en booking_system_backend/routers/booking_detail.py
   que implemente GET /bookings/{booking_id} con los siguientes requisitos:
   - Acepta booking_id como parámetro de ruta entero positivo
   - Acepta identidad del llamador desde un encabezado de solicitud X-User-Email
   - Devuelve el registro de reserva solo si pertenece al usuario identificado
   - Devuelve HTTP 404 si la reserva no existe
   - Devuelve HTTP 403 si la reserva pertenece a un usuario diferente
   - Registra el intento de acceso sin incluir el correo electrónico en la entrada de registro
   - Devuelve un mensaje genérico para cualquier error de servidor inesperado
   
   Devuelve la lista de verificación de cumplimiento cuando esté completo.
   
   Paso 2 — Subagente Critic:
   Después de que el subagente Actor complete, genera un segundo subagente independiente para
   revisar la salida. Carga el skill /secure-python-critic. Referencia:
   
   @booking_system_backend/routers/booking_detail.py
   
   Revisa el archivo contra todos los controles en el skill. Indica si el código
   pasaría un escaneo SAST con hallazgos de seguridad limitados.
   
   Devuelve el informe completo de hallazgos del Critic cuando esté completo.

5. Haz clic en Approve todo tools for task cuando se te solicite. A medida que cada subagente inicia, puedes ver solicitudes de aprobación adicionales — haz clic en Approve en cada una.

   Bob solicita aprobación antes de generar cada subagente y antes de que el Actor escriba el archivo de endpoint. Espera de dos a tres solicitudes en total.

   Bob orquesta ambos subagentes secuencialmente. El subagente Actor lee la base de código existente, genera el endpoint y devuelve una lista de verificación de cumplimiento. El subagente Critic luego recibe solo el archivo generado — no el contexto del Actor — y lo audita independientemente.

   Salida de ejemplo:

   Tengo todo el contexto necesario. Ahora configuraré la lista de tareas y ejecutaré el flujo de trabajo actor-crítico secuencialmente.
   
   Actor terminado. Déjame verificar que los archivos se escribieron realmente antes de lanzar el Critic:
   Creado booking_system_backend/routers/booking_detail.py
   
   Lista de verificación de cumplimiento
   [C1] Validación de Entrada      — PASS — booking_id usa Annotated[int, Path(gt=0)]; encabezado leído via Header(alias=…) como cadena opaca
   [C2] Autorización         — PASS — reserva obtenida solo por ID; propiedad comparada por separado; 404 vs 403 son distintos y correctos
   ...snip...
   
   El archivo es correcto y completo. Ahora lanza el subagente Critic:
   
   ---
   
   Iniciando subagente Critic...
   
   Subagente Critic completo.
   Revisado booking_system_backend/routers/booking_detail.py
   
   === SECURE PYTHON CRITIC — INFORME DE HALLAZGOS ===
   
   [C1] Validación de Entrada      — PASS — Los tres sub-controles satisfechos.
   • `booking_id` se declara como `Annotated[int, Path(gt=0)]`, aplicando una
   restricción de entero positivo; FastAPI devolverá 422 antes del manejador
   
   ...snip...
   
   VEREDICTO GENERAL: PASS
   Pasaría SAST sin hallazgos de seguridad: SÍ
   
   HALLAZGOS QUE REQUIEREN ACCIÓN:
   • [C6 — WARN — RESUELTO] routers/__init__.py existe y fue confirmado
   presente. No se requiere acción.

   La nota arquitectónica del Critic no es un defecto de código — refleja el flujo de trabajo existente de Galaxium Travels.

6. Abre booking_system_backend/routers/booking_detail.py para revisar el código generado.

   El equipo de desarrollo ahora puede estar seguro de que el nuevo endpoint satisface los estándares de seguridad antes de que un humano lo revise, y antes de que llegue a una herramienta de análisis estático.