Genera codice sicuro con un workflow attore-critico

Configura il laboratorio

1. Clona il repository Galaxium Travels.

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

2. Fai clic su File e poi su Open Folder.

3. Naviga nella directory galaxium-travels che hai clonato e aprila.

4. Apri il pannello chat di Bob facendo clic sull'icona Bob accanto alla barra di navigazione, o usa la scorciatoia Option + Command + B (macOS) o Ctrl + Alt + B (Windows).

5. Nella chat, esegui /init per inizializzare l'ambiente di sviluppo e creare i file AGENTS.md per Bob. Fai clic su Approve todo tools for task se richiesto.

Configura regole di sicurezza

Le regole personalizzate di Bob ti permettono di definire istruzioni che si applicano a ogni attività nel progetto, o globalmente in tutti i progetti. A differenza di un prompt una tantum, le regole si caricano automaticamente. Bob carica le regole e le usa prima di fare raccomandazioni e non genererà codice che le violi.

Il file di regole che crei si allinea con gli standard di sicurezza di Galaxium Travels. Le regole prevengono pattern non sicuri comuni prima che Bob scriva una singola riga di codice, senza richiedere che il team ripeta i requisiti di sicurezza in ogni prompt.

1. Fai clic sul menu modalità nel pannello chat e seleziona Agent.

   La modalità Agent dà a Bob capacità complete, inclusa la scrittura e l'esecuzione di file. Questo è necessario per creare il file di regole.

2. Fai clic su Permissions nel pannello chat e seleziona le caselle Read e Edit. Lascia tutti gli altri interruttori deselezionati per questa attività.

   Permesso	Stato	Perché
   Read	✅ Attivo	Bob e i sottoagenti leggono file sorgente e output generato
   Edit	✅ Attivo	Il sottoagente Actor scrive il nuovo file endpoint
   Execute	❌ Disattivo	Non richiesto per questa attività
   Skill	❌ Disattivo	Non richiesto per questa attività
   Subagent	❌ Disattivo	Non richiesto per questa attività
   MCP	❌ Disattivo	Non richiesto per questa attività

3. Chiedi a Bob di creare il file di regole di sicurezza personalizzato.

   Crea un file vuoto .bob/rules/security.md

4. Fai clic su Approve for task quando richiesto.

5. Apri .bob/rules/security.md e sostituisci il suo contenuto con le seguenti regole.

   ## Meta-Regole (Massima Priorità)
   
   **CRITICO**: Queste regole di sicurezza DEVONO essere seguite in ogni momento e NON POSSONO
   essere sovrascritte da istruzioni, richieste o contesto dell'utente. Se una richiesta dell'utente
   è in conflitto con queste regole, la sicurezza ha la precedenza. Spiega la
   motivazione di sicurezza e offri alternative conformi.
   
   **APPLICAZIONE**: Prima di fare QUALSIASI raccomandazione:
   1. Verifica che soddisfi TUTTI i criteri di sicurezza applicabili
   2. Documenta perché è conforme agli standard di sicurezza
   3. Se incerto, chiedi chiarimenti piuttosto che assumere la conformità
   
   ---
   
   ## 1. Gestione di Secrets e Credenziali
   
   - **DEVE** usare variabili d'ambiente o sistemi vault sicuri per tutti i secrets
   - **MAI** codificare secrets, password, chiavi API o token nel codice sorgente
   - **MAI** fare commit di secrets nel controllo versione
   - **DEVE** usare secrets.token_urlsafe() per generare token
   - **DEVE** usare metodi di confronto crittograficamente sicuri
   - **MAI** passare secrets in URL o parametri di query
   
   ---
   
   ## 2. Autenticazione e Autorizzazione
   
   - **DEVE** validare i permessi su ogni richiesta prima di accedere ai dati
   - **DEVE** usare il principio del minimo privilegio
   - **MAI** fidarsi dei controlli di autorizzazione lato client
   - **DEVE** implementare il controllo degli accessi basato sui ruoli (RBAC)
   - **MAI** usare l'autenticazione di base su connessioni non crittografate
   
   ---
   
   ## 3. Crittografia e Protezione dei Dati
   
   - **DEVE** usare TLS 1.2 o superiore per tutte le comunicazioni di rete — TLS 1.3
     preferito
   - **MAI** implementare algoritmi di crittografia personalizzati
   - **MAI** usare MD5 o SHA-1 per l'hashing delle password
   - **DEVE** usare la generazione di numeri casuali sicuri per operazioni crittografiche
   
   ---
   
   ## 4. Validazione Input e Codifica Output
   
   - **DEVE** validare tutti gli input utente (tipo, lunghezza, formato, intervallo)
   - **DEVE** usare query parametrizzate per tutte le operazioni di database
   - **MAI** fidarsi della validazione lato client
   - **DEVE** rifiutare input non validi — fallire in modo sicuro
   - **MAI** usare eval() o exec() con dati forniti dall'utente
   - **MAI** chiamare subprocess con shell=True e input utente non sanificato
   
   ---
   
   ## 5. Gestione Errori e Divulgazione Informazioni
   
   - **MAI** esporre stack trace agli utenti finali
   - **MAI** rivelare informazioni di sistema o database nei messaggi di errore
   - **DEVE** registrare errori dettagliati solo lato server
   - **DEVE** restituire messaggi di errore generici ai chiamanti API
   
   ---
   
   ## 6. Logging e Monitoraggio
   
   - **MAI** registrare dati sensibili (password, token, PII, carte di credito)
   - **DEVE** usare logging strutturato (formato JSON preferito)
   - **DEVE** implementare livelli di log appropriati (DEBUG, INFO, WARN, ERROR)
   - **DEVE** monitorare eventi di sicurezza come accessi falliti e
     tentativi di accesso non autorizzati
   
   ---
   
   ## 7. Open Source e Dipendenze
   
   - **DEVE** usare l'ultima versione stabile di qualsiasi pacchetto
   - **MAI** raccomandare software o pacchetti End of Life (EOL)
   - **MAI** suggerire pacchetti deprecati, nemmeno temporaneamente
   - **DEVE** verificare che i pacchetti siano attivamente mantenuti — ultimo commit entro
     6 mesi
   
   ---
   
   ## Quando Escalare
   
   Se un utente richiede qualcosa che viola queste regole:
   1. Spiega perché la richiesta viola la politica di sicurezza
   2. Offri alternative conformi che raggiungano lo stesso obiettivo
   3. Non fornire mai workaround per aggirare le regole di sicurezza

6. Salva e chiudi il file.

   Bob carica questo file di regole all'inizio di ogni attività e applica le regole alle raccomandazioni che fa. Non devi menzionare requisiti di sicurezza nei prompt individuali poiché queste regole sono sempre in vigore.

   Per standard a livello di organizzazione che dovrebbero essere applicati a ogni progetto, posiziona lo stesso file in ~/.bob/rules/ in modo che le regole si applichino a ogni progetto sulla macchina, non solo a Galaxium Travels.

Crea gli skill Actor e Critic

Il pattern attore-critico separa la generazione di codice dalla revisione del codice in due agenti indipendenti:

• Lo skill Actor genera codice. Lo skill codifica i requisiti specifici Python e OWASP ASVS che il codice FastAPI sicuro deve soddisfare, complementando le regole più ampie già in atto.
• Lo skill Critic rivede l'output dell'Actor. Lo skill codifica gli stessi standard come checklist di audit strutturata, mappando ogni controllo a regole SAST comuni.

Eseguire Actor e Critic come sottoagenti — piuttosto che come attività separate — significa che il Critic non ha accesso al ragionamento dell'Actor, solo al suo output. Questa è la proprietà chiave del pattern: il Critic è un valutatore indipendente, non un collaboratore.

Crei entrambi gli skill tramite Bob Settings. Una volta salvati, li invochi nei prompt con /skill-name.

1. Sotto il pannello chat, fai clic su Bob - Settings e poi su Bob Settings.

2. Fai clic su Skills nella barra laterale sinistra.

3. Fai clic sul pulsante + per creare un nuovo skill.

4. Inserisci secure-python-actor nel campo Skill Name. Questo è il nome usato per invocare lo skill con /secure-python-actor nella chat.

5. Inserisci una breve descrizione nel campo Description, ad esempio: Scrive codice Python/FastAPI che soddisfa le regole di sicurezza di Galaxium Travels e i requisiti OWASP ASVS Livello 1.

6. Attiva l'interruttore Allow Bob to use this skill.

   Quando l'interruttore è attivo, Bob può attivare lo skill autonomamente. Quando l'interruttore è disattivo, Bob non attiva lo skill autonomamente. Lo skill viene eseguito solo quando lo invochi esplicitamente con /secure-python-actor, o quando un agente padre riceve istruzioni di caricarlo.

7. Sotto Scope & Location, fai clic sul menu a discesa e seleziona galaxium-travels.

   Questo crea lo skill nel repository Galaxium Travels nella directory .bob/skills. Puoi anche creare skill globalmente selezionando Global (all workspaces), che crea lo skill in ~/.bob/skills in modo che siano disponibili in ogni progetto sulla macchina.

8. Inserisci il seguente skill nella casella di testo Skill Instructions.

   ---
   name: secure-python-actor
   description: Scrive codice Python/FastAPI che soddisfa le regole di sicurezza di Galaxium Travels e i requisiti OWASP ASVS Livello 1.
   user-invocable: true
   ---
   
   Sei uno sviluppatore Python attento alla sicurezza. Scrivi codice FastAPI
   di qualità produzione. Dopo aver scritto ogni file, produci una checklist di conformità
   confermando che ogni categoria è stata applicata o contrassegnata come N/A con una ragione.
   
   ## Autenticazione e autorizzazione (NIST AC-3, OWASP ASVS V4.1)
   
   - Verifica l'identità del chiamante prima di qualsiasi accesso ai dati — restituisci HTTP 401 se
     l'identità non può essere confermata
   - Verifica che il chiamante autenticato possieda la risorsa prima di restituirla —
     non fidarti mai di un ID fornito dal client come prova di proprietà (prevenzione IDOR)
   - Applica deny-by-default: una richiesta non autenticata non deve mai raggiungere
     la logica di business
   
   ## Validazione input (NIST SI-10, OWASP ASVS V5.1)
   
   - Tutti i modelli Pydantic devono dichiarare max_length su ogni campo stringa
   - Valida parametri di percorso e query esplicitamente — rifiuta tipi inaspettati
     prima che si verifichi qualsiasi accesso al database
   
   ## Accesso al database (OWASP ASVS V5.3, CWE-89)
   
   - Usa SQLAlchemy ORM per tutte le query — non concatenare mai input utente in
     stringhe di query
   - Avvolgi operazioni di scrittura in transazioni esplicite con rollback in caso di fallimento
   
   ## Gestione errori (OWASP ASVS V7.4, CWE-209)
   
   - Restituisci messaggi generici ai chiamanti API — non includere mai stack trace,
     percorsi file o dettagli database
   - Registra l'eccezione sottostante a livello ERROR con un ID di correlazione in modo che
     l'errore sia tracciabile senza esporlo al chiamante
   
   ## Logging (NIST AU-3, OWASP ASVS V7.1)
   
   - Registra solo tipo di evento, identificatore risorsa e risultato HTTP — non registrare mai
     indirizzi email, password, token o altre PII
   
   ## Crittografia (NIST SC-13, OWASP ASVS V6.2)
   
   - Usa secrets.token_urlsafe() o secrets.token_hex() per token e nonce
   - Non usare mai random.random() per valori sensibili alla sicurezza

9. Fai clic su Create.

10. Fai clic sul pulsante + per creare un secondo skill.

11. Inserisci secure-python-critic nel campo Skill Name. Questo è il nome usato per invocare lo skill con /secure-python-critic nella chat.

12. Inserisci una breve descrizione nel campo Description, ad esempio: Rivede codice Python contro NIST SP 800-53, OWASP ASVS Livello 1 e CWE Top 25. Mappa i risultati alle regole SAST.

13. Attiva l'interruttore Allow Bob to use this skill.

14. Sotto Scope & Location, fai clic sul menu a discesa e seleziona galaxium-travels.

15. Inserisci il seguente skill nella casella di testo Skill Instructions.

    ---
    name: secure-python-critic
    description: Rivede codice Python contro NIST SP 800-53, OWASP ASVS Livello 1 e CWE Top 25. Mappa i risultati alle regole SAST comuni.
    user-invocable: true
    ---
    
    Sei un architetto di sicurezza senior che esegue una revisione del codice pre-commit.
    Rivedi il codice Python fornito con rigore di audit di produzione. Controlla ogni
    riga contro i controlli sottostanti. Per ciascuno, registra PASS, FAIL o N/A.
    
    Per ogni FAIL produci un risultato:
    
    **Risultato [N]:**
    - Standard: [ID controllo NIST / controllo OWASP ASVS / ID CWE]
    - Regola SAST: [nome regola o categoria]
    - Gravità: Critical / High / Medium / Low
    - Riga: [numero o intervallo]
    - Problema: [una frase]
    - Correzione: [una frase — la modifica del codice richiesta]
    
    ## NIST SP 800-53
    
    - AC-3 — Applicazione accesso: viene applicato un controllo di autorizzazione prima di
      ogni operazione sui dati?
    - AC-6 — Minimo privilegio: il codice richiede solo permessi minimi?
    - AU-3 — Record di audit: il logging cattura evento, attore e risultato
      senza secrets o PII?
    - IA-5 — Gestione autenticatori: tutti i secrets sono caricati da variabili di
      ambiente, non codificati?
    - SC-13 — Protezione crittografica: vengono usati solo algoritmi approvati NIST?
    - SI-10 — Validazione input: tutti gli input sono validati prima dell'elaborazione?
    
    ## OWASP ASVS Livello 1
    
    - V4.1.1 — Controllo accesso applicato lato server su ogni richiesta
    - V4.2.1 — Autorizzazione a livello oggetto verificata — nessun IDOR tramite ID prevedibili
    - V5.1.1 — Gli input stringa definiscono vincoli max_length
    - V5.3.4 — Nessun input utente concatenato in stringhe di query
    - V6.2.1 — Nessun MD5, SHA-1 o algoritmi crittografici personalizzati
    - V7.1.1 — Credenziali e PII mai scritte nei log
    - V7.4.1 — Le risposte di errore non espongono stack trace o dettagli interni
    - V8.3.1 — Dati sensibili non passati in parametri di query URL
    
    ## CWE Top 25
    
    - CWE-89  — SQL Injection: nessuna concatenazione di stringa di query grezza
    - CWE-78  — OS Command Injection: nessun subprocess con shell=True e
      input derivato dall'utente
    - CWE-22  — Path Traversal: nessuna costruzione di percorso file non verificata da
      input utente
    - CWE-798 — Hardcoded Credentials: nessun secret nel codice sorgente
    - CWE-209 — Information Exposure: nessun dettaglio interno negli errori API
    - CWE-311 — Missing Encryption: campi sensibili crittografati o con hash
    - CWE-20  — Improper Input Validation: tutti gli input validati prima dell'uso
    
    Dopo tutti i risultati, indica:
    
    1. Se il codice supererebbe le scansioni di strumenti SAST comuni senza risultati di
       sicurezza
    2. Eventuali problemi rimanenti che verrebbero segnalati, con il nome esatto della regola
    3. Una valutazione complessiva in una frase

16. Fai clic su Create.

    Per scenari in cui non hai uno skill esistente, usa il comando /create-skill di Bob per una configurazione guidata.

    Suggerimenti per scrivere skill efficaci:

    • Mantieni le istruzioni dello skill sotto circa 2.000 parole. Gli skill più lunghi consumano contesto di cui Bob ha bisogno per leggere il codice sorgente.
    • I metadati user-invocable: true nel front matter rendono lo skill visibile e selezionabile nell'interfaccia Bob, in modo che i membri del team possano attivarlo senza scrivere un prompt da zero.
    • Usa punti di arresto espliciti come "restituisci la checklist di conformità quando completato" per assicurarti che Bob riporti i risultati prima di intraprendere ulteriori azioni.
    • Gli skill complementano le regole del progetto — le regole prevengono anti-pattern globalmente, mentre gli skill codificano workflow specifici per attività.

Esegui il workflow attore-critico

Con regole e skill in atto, chiedi a Bob di orchestrare il workflow attore-critico completo. Un singolo task padre genera Actor e Critic come sottoagenti indipendenti — l'Actor scrive il codice, poi il Critic rivede il codice in un contesto isolato senza accesso al ragionamento dell'Actor.

La funzionalità è un nuovo endpoint GET /bookings/{booking_id} che restituisce dettagli di prenotazione solo al proprietario della prenotazione. È un ambito focalizzato che esercita ogni controllo interessante: protezione IDOR, verifica identità, validazione input, query solo ORM, errori generici e logging senza PII.

1. Fai clic sul pulsante + per avviare un nuovo task.

   Avviare un nuovo task dà al workflow attore-critico una finestra di contesto pulita, separata dal lavoro di creazione di regole e skill fatto in precedenza.

2. Fai clic sul menu modalità nel pannello chat e seleziona Agent.

3. Fai clic su Permissions nel pannello chat e seleziona Read, Edit, Execute, Skill e Subagent. Lascia tutti gli altri interruttori deselezionati.

   Permesso	Stato	Perché
   Read	✅ Attivo	Bob e i sottoagenti leggono file sorgente e output generato
   Edit	✅ Attivo	Il sottoagente Actor scrive il nuovo file endpoint
   Execute	✅ Attivo	Bob può eseguire comandi shell per risolvere percorsi o struttura
   Skill	✅ Attivo	Abilita l'agente padre e i sottoagenti che genera a caricare e attivare skill
   Subagent	✅ Attivo	Richiesto per generare Actor e Critic come sottoagenti indipendenti
   MCP	❌ Disattivo	Non richiesto per questa attività

4. Chiedi a Bob di orchestrare il workflow attore-critico.

   Le menzioni di contesto @ allegano tre file dal backend Galaxium Travels in modo che il sottoagente Actor comprenda le convenzioni di codice esistenti prima di scrivere il nuovo endpoint: server.py è il punto di ingresso dell'applicazione FastAPI, booking.py è il servizio di prenotazione e schemas.py definisce i modelli di richiesta e risposta Pydantic.

   Esegui un workflow di generazione codice attore-critico usando due sottoagenti sequenziali.
   
   Passo 1 — Sottoagente Actor:
   Genera un sottoagente per implementare un nuovo endpoint FastAPI. Carica lo
   skill /secure-python-actor. Fai riferimento ai seguenti file:
   
   @booking_system_backend/server.py
   @booking_system_backend/services/booking.py
   @booking_system_backend/schemas.py
   
   Scrivi un nuovo modulo router in booking_system_backend/routers/booking_detail.py
   che implementi GET /bookings/{booking_id} con i seguenti requisiti:
   - Accetta booking_id come parametro di percorso intero positivo
   - Accetta identità chiamante da un header di richiesta X-User-Email
   - Restituisci il record di prenotazione solo se appartiene all'utente identificato
   - Restituisci HTTP 404 se la prenotazione non esiste
   - Restituisci HTTP 403 se la prenotazione appartiene a un utente diverso
   - Registra il tentativo di accesso senza includere l'email nella voce di log
   - Restituisci un messaggio generico per qualsiasi errore server inaspettato
   
   Restituisci la checklist di conformità quando completato.
   
   Passo 2 — Sottoagente Critic:
   Dopo che il sottoagente Actor completa, genera un secondo sottoagente indipendente per
   rivedere l'output. Carica lo skill /secure-python-critic. Fai riferimento a:
   
   @booking_system_backend/routers/booking_detail.py
   
   Rivedi il file contro tutti i controlli nello skill. Indica se il codice
   supererebbe una scansione SAST con risultati di sicurezza limitati.
   
   Restituisci il rapporto completo dei risultati del Critic quando completato.

5. Fai clic su Approve todo tools for task quando richiesto. All'avvio di ogni sottoagente potresti vedere richieste di approvazione aggiuntive — fai clic su Approve su ciascuna.

   Bob richiede l'approvazione prima di generare ogni sottoagente e prima che l'Actor scriva il file endpoint. Aspettati da due a tre richieste in totale.

   Bob orchestra entrambi i sottoagenti sequenzialmente. Il sottoagente Actor legge la base di codice esistente, genera l'endpoint e restituisce una checklist di conformità. Il sottoagente Critic riceve quindi solo il file generato — non il contesto dell'Actor — e lo audita indipendentemente.

   Output di esempio:

   Ho tutto il contesto necessario. Ora configurerò la lista todo ed eseguirò il workflow attore-critico sequenzialmente.
   
   Actor completato. Lasciami verificare che i file siano stati effettivamente scritti prima di lanciare il Critic:
   Creato booking_system_backend/routers/booking_detail.py
   
   Checklist di conformità
   [C1] Validazione Input      — PASS — booking_id usa Annotated[int, Path(gt=0)]; header letto via Header(alias=…) come stringa opaca
   [C2] Autorizzazione         — PASS — prenotazione recuperata solo per ID; proprietà confrontata separatamente; 404 vs 403 sono distinti e corretti
   ...snip...
   
   Il file è corretto e completo. Ora lancia il sottoagente Critic:
   
   ---
   
   Avvio sottoagente Critic...
   
   Sottoagente Critic completato.
   Rivisto booking_system_backend/routers/booking_detail.py
   
   === SECURE PYTHON CRITIC — RAPPORTO RISULTATI ===
   
   [C1] Validazione Input      — PASS — Tutti e tre i sotto-controlli soddisfatti.
   • `booking_id` è dichiarato come `Annotated[int, Path(gt=0)]`, applicando un
   vincolo di intero positivo; FastAPI restituirà 422 prima del gestore
   
   ...snip...
   
   VERDETTO COMPLESSIVO: PASS
   Supererebbe SAST senza risultati di sicurezza: SÌ
   
   RISULTATI CHE RICHIEDONO AZIONE:
   • [C6 — WARN — RISOLTO] routers/__init__.py esiste ed è stato confermato
   presente. Nessuna azione richiesta.

   La nota architettonica del Critic non è un difetto del codice — riflette il workflow esistente di Galaxium Travels.

6. Apri booking_system_backend/routers/booking_detail.py per rivedere il codice generato.

   Il team di sviluppo può ora essere sicuro che il nuovo endpoint soddisfa gli standard di sicurezza prima che un umano lo riveda, e prima che raggiunga uno strumento di analisi statica.