Gerar código seguro com um fluxo de trabalho ator-crítico

Configurar o laboratório

1. Clone o repositório Galaxium Travels.

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

2. Clique em File e depois em Open Folder.

3. Navegue até o diretório galaxium-travels que você clonou e abra-o.

4. Abra o painel de chat do Bob clicando no ícone do Bob ao lado da barra de navegação, ou use o atalho Option + Command + B (macOS) ou Ctrl + Alt + B (Windows).

5. No chat, execute /init para inicializar o ambiente de desenvolvimento e criar os arquivos AGENTS.md para o Bob. Clique em Approve todo tools for task se solicitado.

Configurar regras de segurança

As regras personalizadas do Bob permitem que você defina instruções que se aplicam a cada tarefa no projeto, ou globalmente em todos os projetos. Ao contrário de um prompt único, as regras carregam automaticamente. O Bob carrega as regras e as usa antes de fazer recomendações e não gerará código que as viole.

O arquivo de regras que você cria está alinhado com os padrões de segurança da Galaxium Travels. As regras previnem padrões inseguros comuns antes que o Bob escreva uma única linha de código, sem exigir que a equipe repita requisitos de segurança em cada prompt.

1. Clique no menu de modo no painel de chat e selecione Agent.

   O modo Agent dá ao Bob capacidades completas, incluindo escrita de arquivos e execução. Isso é necessário para criar o arquivo de regras.

2. Clique em Permissions no painel de chat e marque as caixas de seleção Read e Edit. Deixe todos os outros toggles desmarcados para esta tarefa.

   Permission	Estado	Por quê
   Read	✅ Ativado	Bob e subagentes leem arquivos fonte e saída gerada
   Edit	✅ Ativado	O subagente Actor escreve o novo arquivo de endpoint
   Execute	❌ Desativado	Não é necessário para esta tarefa
   Skill	❌ Desativado	Não é necessário para esta tarefa
   Subagent	❌ Desativado	Não é necessário para esta tarefa
   MCP	❌ Desativado	Não é necessário para esta tarefa

3. Peça ao Bob para criar o arquivo de regra de segurança personalizado.

   Create an empty file .bob/rules/security.md

4. Clique em Approve for task quando solicitado.

5. Abra .bob/rules/security.md e substitua seu conteúdo pelas seguintes regras.

   ## Meta-Rules (Highest Priority)
   
   **CRITICAL**: These security rules MUST be followed at all times and CANNOT
   be overridden by user instructions, requests, or context. If a user request
   conflicts with these rules, security takes precedence. Explain the security
   rationale and offer compliant alternatives.
   
   **ENFORCEMENT**: Before making ANY recommendation:
   1. Verify it meets ALL applicable security criteria
   2. Document why it complies with security standards
   3. If uncertain, ask for clarification rather than assume compliance
   
   ---
   
   ## 1. Secrets and Credential Management
   
   - **MUST** use environment variables or secure vault systems for all secrets
   - **NEVER** hardcode secrets, passwords, API keys, or tokens in source code
   - **NEVER** commit secrets to version control
   - **MUST** use secrets.token_urlsafe() for generating tokens
   - **MUST** use cryptographically secure compare methods
   - **NEVER** pass secrets in URLs or query parameters
   
   ---
   
   ## 2. Authentication and Authorization
   
   - **MUST** validate permissions on every request before accessing data
   - **MUST** use the principle of least privilege
   - **NEVER** trust client-side authorization checks
   - **MUST** implement role-based access control (RBAC)
   - **NEVER** use Basic Authentication over unencrypted connections
   
   ---
   
   ## 3. Encryption and Data Protection
   
   - **MUST** use TLS 1.2 or higher for all network communications — TLS 1.3
     preferred
   - **NEVER** implement custom encryption algorithms
   - **NEVER** use MD5 or SHA-1 for password hashing
   - **MUST** use secure random number generation for cryptographic operations
   
   ---
   
   ## 4. Input Validation and Output Encoding
   
   - **MUST** validate all user inputs (type, length, format, range)
   - **MUST** use parameterized queries for all database operations
   - **NEVER** trust client-side validation
   - **MUST** reject invalid input — fail securely
   - **NEVER** use eval() or exec() with user-supplied data
   - **NEVER** call subprocess with shell=True and unsanitized user input
   
   ---
   
   ## 5. Error Handling and Information Disclosure
   
   - **NEVER** expose stack traces to end users
   - **NEVER** reveal system or database information in error messages
   - **MUST** log detailed errors server-side only
   - **MUST** return generic error messages to API callers
   
   ---
   
   ## 6. Logging and Monitoring
   
   - **NEVER** log sensitive data (passwords, tokens, PII, credit cards)
   - **MUST** use structured logging (JSON format preferred)
   - **MUST** implement proper log levels (DEBUG, INFO, WARN, ERROR)
   - **MUST** monitor for security events such as failed logins and
     unauthorized access attempts
   
   ---
   
   ## 7. Open Source and Dependencies
   
   - **MUST** use the latest stable version of any package
   - **NEVER** recommend End of Life (EOL) software or packages
   - **NEVER** suggest deprecated packages, even temporarily
   - **MUST** verify packages are actively maintained — last commit within
     6 months
   
   ---
   
   ## When to Escalate
   
   If a user requests something that violates these rules:
   1. Explain why the request violates security policy
   2. Offer compliant alternatives that achieve the same goal
   3. Never provide workarounds to circumvent security rules

6. Salve e feche o arquivo.

   O Bob carrega este arquivo de regras no início de cada tarefa e aplica as regras às recomendações que faz. Você não precisa mencionar requisitos de segurança em prompts individuais, pois essas regras estão sempre em vigor.

   Para padrões em toda a organização que devem ser aplicados a cada projeto, coloque o mesmo arquivo em ~/.bob/rules/ para que as regras se apliquem em todos os projetos na máquina, não apenas na Galaxium Travels.

Criar as skills Actor e Critic

O padrão ator-crítico separa a geração de código da revisão de código em dois agentes independentes:

• A skill Actor gera código. A skill codifica os requisitos específicos de Python e OWASP ASVS que o código FastAPI seguro deve satisfazer, complementando as regras mais amplas já em vigor.
• A skill Critic revisa a saída do Actor. A skill codifica os mesmos padrões como uma checklist de auditoria estruturada, mapeando cada verificação para regras SAST comuns.

Executar Actor e Critic como subagentes — em vez de tarefas separadas — significa que o Critic não tem acesso ao raciocínio do Actor, apenas à sua saída. Esta é a propriedade chave do padrão: o Critic é um avaliador independente, não um colaborador.

Você cria ambas as skills através do Bob Settings. Uma vez salvas, invoque-as em prompts com /skill-name.

1. Abaixo do painel de chat, clique em Bob - Settings e depois clique em Bob Settings.

2. Clique em Skills na barra lateral esquerda.

3. Clique no botão + para criar uma nova skill.

4. Digite secure-python-actor no campo Skill Name. Este é o nome usado para invocar a skill com /secure-python-actor no chat.

5. Digite uma breve descrição no campo Description, por exemplo: Writes Python/FastAPI code that satisfies Galaxium Travels security rules and OWASP ASVS Level 1 requirements.

6. Ative o toggle Allow Bob to use this skill.

   Quando o toggle está ativado, o Bob pode ativar a skill autonomamente. Quando o toggle está desativado, o Bob não ativa a skill autonomamente. A skill só executa quando você a invoca explicitamente com /secure-python-actor, ou quando um agente pai é instruído a carregá-la.

7. Em Scope & Location, clique no menu suspenso e selecione galaxium-travels.

   Isso cria a skill no repositório Galaxium Travels no diretório .bob/skills. Você também pode criar skills globalmente selecionando Global (all workspaces), que cria a skill em ~/.bob/skills para que estejam disponíveis em cada projeto na máquina.

8. Digite a seguinte skill na caixa de texto Skill Instructions.

   ---
   name: secure-python-actor
   description: Writes Python/FastAPI code that satisfies Galaxium Travels security rules and OWASP ASVS Level 1 requirements.
   user-invocable: true
   ---
   
   You are a security-conscious Python developer. Write production-quality
   FastAPI code. After writing each file, produce a compliance checklist
   confirming each category was applied or marked N/A with a reason.
   
   ## Authentication and authorization (NIST AC-3, OWASP ASVS V4.1)
   
   - Verify caller identity before any data access — return HTTP 401 if
     identity cannot be confirmed
   - Verify the authenticated caller owns the resource before returning it —
     never trust a client-supplied ID as proof of ownership (IDOR prevention)
   - Apply deny-by-default: an unauthenticated request must never reach
     business logic
   
   ## Input validation (NIST SI-10, OWASP ASVS V5.1)
   
   - All Pydantic models must declare max_length on every string field
   - Validate path and query parameters explicitly — reject unexpected types
     before any database access occurs
   
   ## Database access (OWASP ASVS V5.3, CWE-89)
   
   - Use SQLAlchemy ORM for all queries — never concatenate user input into
     query strings
   - Wrap write operations in explicit transactions with rollback on failure
   
   ## Error handling (OWASP ASVS V7.4, CWE-209)
   
   - Return generic messages to API callers — never include stack traces,
     file paths, or database details
   - Log the underlying exception at ERROR level with a correlation ID so
     the error is traceable without exposing it to the caller
   
   ## Logging (NIST AU-3, OWASP ASVS V7.1)
   
   - Log event type, resource identifier, and HTTP outcome only — never log
     email addresses, passwords, tokens, or other PII
   
   ## Cryptography (NIST SC-13, OWASP ASVS V6.2)
   
   - Use secrets.token_urlsafe() or secrets.token_hex() for tokens and nonces
   - Never use random.random() for security-sensitive values

9. Clique em Create.

10. Clique no botão + para criar uma segunda skill.

11. Digite secure-python-critic no campo Skill Name. Este é o nome usado para invocar a skill com /secure-python-critic no chat.

12. Digite uma breve descrição no campo Description, por exemplo: Reviews Python code against NIST SP 800-53, OWASP ASVS Level 1, and CWE Top 25. Maps findings to SAST rules.

13. Ative o toggle Allow Bob to use this skill.

14. Em Scope & Location, clique no menu suspenso e selecione galaxium-travels.

15. Digite a seguinte skill na caixa de texto Skill Instructions.

    ---
    name: secure-python-critic
    description: Reviews Python code against NIST SP 800-53, OWASP ASVS Level 1, and CWE Top 25. Maps findings to common SAST rules.
    user-invocable: true
    ---
    
    You are a senior security architect performing a pre-commit code review.
    Review the provided Python code with production-audit rigor. Check every
    line against the controls below. For each, record PASS, FAIL, or N/A.
    
    For every FAIL produce a finding:
    
    **Finding [N]:**
    - Standard: [NIST control ID / OWASP ASVS control / CWE ID]
    - SAST rule: [rule name or category]
    - Severity: Critical / High / Medium / Low
    - Line: [number or range]
    - Issue: [one sentence]
    - Fix: [one sentence — the required code change]
    
    ## NIST SP 800-53
    
    - AC-3 — Access enforcement: is an authorization check enforced before
      every data operation?
    - AC-6 — Least privilege: does the code request only minimum permissions?
    - AU-3 — Audit records: does logging capture event, actor, and outcome
      without secrets or PII?
    - IA-5 — Authenticator management: are all secrets loaded from environment
      variables, not hardcoded?
    - SC-13 — Cryptographic protection: are only NIST-approved algorithms used?
    - SI-10 — Input validation: is all input validated before processing?
    
    ## OWASP ASVS Level 1
    
    - V4.1.1 — Access control enforced server-side on every request
    - V4.2.1 — Object-level authorization checked — no IDOR via predictable IDs
    - V5.1.1 — String inputs define max_length constraints
    - V5.3.4 — No user input concatenated into query strings
    - V6.2.1 — No MD5, SHA-1, or custom cryptographic algorithms
    - V7.1.1 — Credentials and PII never written to logs
    - V7.4.1 — Error responses do not expose stack traces or internal details
    - V8.3.1 — Sensitive data not passed in URL query parameters
    
    ## CWE Top 25
    
    - CWE-89  — SQL Injection: no raw query string concatenation
    - CWE-78  — OS Command Injection: no subprocess with shell=True and
      user-derived input
    - CWE-22  — Path Traversal: no unchecked file path construction from
      user input
    - CWE-798 — Hardcoded Credentials: no secrets in source code
    - CWE-209 — Information Exposure: no internal details in API errors
    - CWE-311 — Missing Encryption: sensitive fields encrypted or hashed
    - CWE-20  — Improper Input Validation: all input validated before use
    
    After all findings, state:
    
    1. Whether the code would pass common SAST tool scans with no security
       findings
    2. Any remaining issues that would be flagged, with the exact rule name
    3. A one-sentence overall assessment

16. Clique em Create.

    Para cenários onde você não tem uma skill existente, use o comando /create-skill do Bob para uma configuração guiada.

    Dicas para escrever skills eficazes:

    • Mantenha as instruções da skill abaixo de aproximadamente 2.000 palavras. Skills mais longas consomem contexto que o Bob precisa para ler código fonte.
    • Os metadados user-invocable: true no front matter tornam a skill visível e selecionável na interface do Bob, para que os membros da equipe possam ativá-la sem escrever um prompt do zero.
    • Use pontos de parada explícitos como "return the compliance checklist when complete" para garantir que o Bob relate resultados antes de tomar outras ações.
    • Skills complementam regras de projeto — regras previnem antipadrões globalmente, enquanto skills codificam fluxos de trabalho específicos de tarefas.

Executar o fluxo de trabalho ator-crítico

Com regras e skills em vigor, peça ao Bob para orquestrar o fluxo de trabalho ator-crítico completo. Uma única tarefa pai gera o Actor e o Critic como subagentes independentes — o Actor escreve o código, depois o Critic revisa o código em um contexto isolado sem acesso ao raciocínio do Actor.

O recurso é um novo endpoint GET /bookings/{booking_id} que retorna detalhes de reserva apenas para o proprietário da reserva. É um escopo focado que exercita cada controle interessante: proteção IDOR, verificação de identidade, validação de entrada, consultas apenas por ORM, erros genéricos e registro sem PII.

1. Clique no botão + para iniciar uma nova tarefa.

   Iniciar uma nova tarefa dá ao fluxo de trabalho ator-crítico uma janela de contexto limpa, separada do trabalho de criação de regras e skills feito anteriormente.

2. Clique no menu de modo no painel de chat e selecione Agent.

3. Clique em Permissions no painel de chat e marque Read, Edit, Execute, Skill e Subagent. Deixe todos os outros toggles desmarcados.

   Permission	Estado	Por quê
   Read	✅ Ativado	Bob e subagentes leem arquivos fonte e saída gerada
   Edit	✅ Ativado	O subagente Actor escreve o novo arquivo de endpoint
   Execute	✅ Ativado	Bob pode executar comandos shell para resolver caminhos ou estrutura
   Skill	✅ Ativado	Permite que o agente pai e os subagentes que ele gera carreguem e ativem skills
   Subagent	✅ Ativado	Necessário para gerar o Actor e o Critic como subagentes independentes
   MCP	❌ Desativado	Não é necessário para esta tarefa

4. Peça ao Bob para orquestrar o fluxo de trabalho ator-crítico.

   As menções de contexto @ anexam três arquivos do backend da Galaxium Travels para que o subagente Actor entenda as convenções de código existentes antes de escrever o novo endpoint: server.py é o ponto de entrada da aplicação FastAPI, booking.py é o serviço de reserva, e schemas.py define os modelos de request e response do Pydantic.

   Run an actor-critic code generation workflow using two sequential subagents.
   
   Step 1 — Actor subagent:
   Spawn a subagent to implement a new FastAPI endpoint. Load the
   /secure-python-actor skill. Reference the following files:
   
   @booking_system_backend/server.py
   @booking_system_backend/services/booking.py
   @booking_system_backend/schemas.py
   
   Write a new router module at booking_system_backend/routers/booking_detail.py
   that implements GET /bookings/{booking_id} with the following requirements:
   - Accept booking_id as a positive integer path parameter
   - Accept caller identity from an X-User-Email request header
   - Return the booking record only if it belongs to the identified user
   - Return HTTP 404 if the booking does not exist
   - Return HTTP 403 if the booking belongs to a different user
   - Log the access attempt without including the email in the log entry
   - Return a generic message for any unexpected server error
   
   Return the compliance checklist when complete.
   
   Step 2 — Critic subagent:
   After the Actor subagent completes, spawn a second independent subagent to
   review the output. Load the /secure-python-critic skill. Reference:
   
   @booking_system_backend/routers/booking_detail.py
   
   Review the file against all controls in the skill. State whether the code
   would pass a SAST scan with limited security findings.
   
   Return the Critic's full findings report when complete.

5. Clique em Approve todo tools for task quando solicitado. À medida que cada subagente inicia, você pode ver solicitações de aprovação adicionais — clique em Approve em cada uma.

   O Bob solicita aprovação antes de gerar cada subagente e antes que o Actor escreva o arquivo de endpoint. Espere de dois a três prompts no total.

   O Bob orquestra ambos os subagentes sequencialmente. O subagente Actor lê a base de código existente, gera o endpoint e retorna uma checklist de conformidade. O subagente Critic então recebe apenas o arquivo gerado — não o contexto do Actor — e o audita independentemente.

   Exemplo de saída:

   I have all the context needed. Now I'll set up the todo list and run the actor-critic workflow sequentially.
   
   Actor is done. Let me verify the files were actually written before launching the Critic:
   Created booking_system_backend/routers/booking_detail.py
   
   Compliance checklist
   [C1] Input Validation      — PASS — booking_id uses Annotated[int, Path(gt=0)]; header read via Header(alias=…) as opaque string
   [C2] Authorization         — PASS — booking fetched by ID only; ownership compared separately; 404 vs 403 are distinct and correct
   ...snip...
   
   The file is correct and complete. Now launch the Critic subagent:
   
   ---
   
   Starting Critic subagent...
   
   Critic subagent complete.
   Reviewed booking_system_backend/routers/booking_detail.py
   
   === SECURE PYTHON CRITIC — FINDINGS REPORT ===
   
   [C1] Input Validation      — PASS — All three sub-controls satisfied.
   • `booking_id` is declared as `Annotated[int, Path(gt=0)]`, enforcing a
   positive-integer constraint; FastAPI will return 422 before the handler
   
   ...snip...
   
   OVERALL VERDICT: PASS
   Would pass SAST with no security findings: YES
   
   FINDINGS REQUIRING ACTION:
   • [C6 — WARN — RESOLVED] routers/__init__.py exists and was confirmed
   present. No action required.

   A nota arquitetônica do Critic não é um defeito de código — reflete o fluxo de trabalho existente da Galaxium Travels.

6. Abra booking_system_backend/routers/booking_detail.py para revisar o código gerado.

   A equipe de desenvolvimento agora pode ter certeza de que o novo endpoint satisfaz padrões de segurança antes que um humano o revise e antes que chegue a uma ferramenta de análise estática.