Guardrail di produzione per agenti AI: autonomia sicura

I guardrail di produzione per agenti AI devono resistere a qualcosa di più di un prompt formulato con gentilezza. Un coding agent autonomo può interpretare male una destinazione, ripetere un’operazione, esporre una credenziale nella propria spiegazione o continuare dopo una risposta ambigua. La sicurezza in produzione deve quindi essere presente nell’interfaccia eseguibile, nel modello di autorizzazione e nell’audit trail, non solo nelle istruzioni.

Dockup combina le indicazioni comportamentali della skill di Claude Code e Codex con l’enforcement a livello CLI: i secret vengono mascherati, le operazioni distruttive richiedono --yes, gli errori restituiscono codici stabili, i deployment possono attendere uno stato terminale e le mutazioni compaiono nell’audit log.

Perché i guardrail devono essere applicati sotto il livello del prompt?

Un prompt è una policy utile, ma non costituisce un confine di sicurezza. Il contesto dell’agente può essere troncato, le istruzioni possono entrare in conflitto e il modello può scegliere un’interpretazione errata. Lo strumento sottostante dovrebbe rendere il comportamento non sicuro difficile o impossibile.

Consideriamo una richiesta di eliminazione. In un design debole, il comando esegue immediatamente l’eliminazione e si affida all’agente perché si ricordi di chiedere conferma. In un design più solido, l’operazione viene rifiutata a meno che non sia presente un flag di conferma separato.

Dockup usa il pattern più solido:

dockup up production/api --prune --json

Senza una conferma esplicita, la pulizia distruttiva viene rifiutata e il JSON include code:"needs_confirm". Non viene eseguito alcun prune. L’agente deve mostrare il risultato a una persona, ricevere l’approvazione e poi eseguire nuovamente il comando in modo deliberato:

dockup up production/api --prune --yes --json

Si tratta di defense in depth. La skill di Dockup indica all’agente di fermarsi, mentre la CLI impedisce l’esecuzione accidentale anche se l’istruzione viene ignorata.

In che modo il mascheramento dei secret protegge gli agenti autonomi?

Gli agenti spesso includono l’output dei comandi nel proprio ragionamento o nella risposta finale. Se un’operazione di lettura restituisce un token di produzione, il secret può finire nella cronologia della chat, nei log, nella telemetria, negli screenshot o nelle note di un incidente copiate altrove.

Un’interfaccia di configurazione sicura separa i metadati dei secret dai relativi valori. Dockup restituisce le chiavi delle variabili d’ambiente e l’indicatore isSecret, mentre i valori dei secret memorizzati sono null o mascherati.

dockup env list -s production/api --json

L’agente può impostare un secret senza recuperarlo in seguito:

dockup env set API_KEY="$API_KEY" \
  --secret \
  -s production/api \
  --json

Il mascheramento dei secret non elimina la necessità di gestire con attenzione il processo. Il valore originale esiste ancora nell’ambiente della shell durante l’operazione di impostazione. Evita set -x, non fare echo della variabile e non creare stringhe di comando che vengano acquisite da un logging dettagliato.

Le password dei database, le API key, i token dei registry, le credenziali SSH e le credenziali Windows RDP dovrebbero essere trattati come output monouso o soggetti a restrizioni. Un agente dovrebbe archiviarli in un secret manager approvato oppure passarli direttamente al processo successivo senza riprodurli in forma testuale.

L’approccio più ampio a livello applicativo è descritto nelle best practice di sicurezza.

Come dovrebbe funzionare l’approvazione delle azioni distruttive?

Non tutte le mutazioni richiedono lo stesso livello di formalità. Un modello di autonomia utile separa le operazioni in base alla reversibilità e al blast radius:

Livello	Esempio	Comportamento predefinito dell’agente
Sola lettura	Elencare i servizi, leggere lo stato, visualizzare i log	Eseguire e riepilogare
Scrittura reversibile	Impostare una variabile, avviare un deployment	Eseguire entro l’ambito approvato
Recovery operativo	Riavviare, ripetere un deployment precedente	Eseguire se il runbook lo consente; riportare le evidenze
Distruttiva	Distruggere un servizio, eliminare un database, abbandonare un progetto	Fermarsi e richiedere un’approvazione esplicita
Ampiamente distruttiva	Applicare --prune, trasferire la proprietà	Richiedere una conferma umana specifica per la destinazione

L’approvazione esplicita dovrebbe includere la destinazione esatta e la conseguenza dell’azione. “Sì, procedi” è meno chiaro di “Elimina staging/old-api e le risorse di servizio associate”. L’agente non dovrebbe riutilizzare un’approvazione concessa per un comando o una destinazione diversi.

La configurazione come codice di Dockup è additiva per impostazione predefinita. dockup up non rimuove le variabili d’ambiente o i domini assenti dal manifest. L’eliminazione richiede il flag esplicito --prune:

dockup plan production/api --json
dockup up production/api --prune --json

Il plan è in sola lettura e dovrebbe essere esaminato prima. Anche con --prune, secret, servizi, database e volumi sono protetti da questo percorso di pulizia del manifest. Consulta configurazione come codice con dockup.yaml per il workflow completo.

In che modo gli errori strutturati mantengono limitata l’autonomia?

Un agente ha bisogno di un insieme finito di percorsi sicuri. I messaggi in forma libera sono utili alle persone, ma i codici di errore stabili rendono deterministica la prima risposta.

Codice	Risposta corretta
not_logged_in	Fermarsi e ottenere una credenziale valida
not_linked	Risolvere la destinazione o passarla esplicitamente
no_target	Eseguire la service discovery; non inventare mai uno slug
needs_confirm	Chiedere l’approvazione di una persona
deploy_trigger_failed	Segnalare perché non è stato possibile avviare l’operazione
deploy_failed	Esaminare i build log
deploy_timeout	Segnalare l’incertezza relativa a uno stato non terminale

Un deployment dovrebbe attendere uno stato terminale:

dockup deploy production/api --wait --json

Il timeout predefinito è di 900 secondi. L’uscita 0 dimostra che il deployment ha raggiunto lo stato di successo. Un’uscita diversa da zero impedisce all’agente di proseguire con modifiche al dominio, migrazioni o annunci come se la produzione fosse pronta.

Questo design è analizzato in AI agent CLI design. Il principio è semplice: lo strumento deve rendere esplicito ogni risultato ambiguo.

Cosa dovrebbe registrare un audit log?

L’autonomia senza attribuzione è debito operativo. Un audit trail di produzione dovrebbe indicare chi ha eseguito l’azione, quale interfaccia ha utilizzato, quale destinazione è cambiata, se si è trattato di una lettura o di una scrittura, quando è avvenuta l’azione e se ha avuto successo.

Dockup registra le azioni eseguite tramite CLI, UI e API. Gli operatori possono esaminare le mutazioni recenti:

dockup audit --writes --json
dockup audit --number 30 --json
dockup audit --search domains --json

Il report dell’agente dovrebbe integrare il record della piattaforma. Includi:

1. La destinazione project/service risolta.
2. La categoria del comando, senza i valori dei secret.
3. Gli ID di deployment o delle risorse restituiti dalla piattaforma.
4. Il codice di uscita e lo stato strutturato.
5. Le evidenze raccolte dopo la mutazione.
6. Qualsiasi approvazione ricevuta per attività distruttive.
7. Le incertezze residue o le attività successive.

Gli audit log non servono soltanto ad attribuire colpe dopo un incidente. Permettono a un secondo agente o a un operatore umano di ricostruire lo stato senza ripetere comandi rischiosi.

Come possono i team aumentare l’autonomia degli agenti in sicurezza?

Inizia con l’accesso in lettura e un solo servizio a basso rischio. Estendi l’accesso soltanto quando l’agente dimostra di saper individuare correttamente le destinazioni, gestire i secret in modo sicuro, diramare correttamente in caso di errore e produrre report adeguati.

Una progressione pratica è la seguente:

Fase 1: Osservazione

Consenti l’elenco dei servizi, la lettura dello stato, della cronologia dei deployment, dei build log, dei runtime log, dell’uptime, dell’utilizzo e dei risultati delle security scan. Confronta il riepilogo dell’agente con il JSON grezzo.

Fase 2: Deployment verso una destinazione fissa

Consenti il deployment di un solo servizio con --wait. Richiedi un health check e un report strutturato di completamento. Non concedere l’eliminazione o la gestione dei permessi del team.

Fase 3: Gestione della configurazione reversibile

Consenti l’aggiornamento di variabili secret e non secret, la configurazione degli health check e l’impostazione di custom domain nell’ambito di un runbook revisionato. Richiedi un nuovo deployment dopo le modifiche all’ambiente.

Fase 4: Esecuzione di azioni di recovery

Consenti il riavvio o il rollback solo quando l’agente seleziona l’ID esatto di un deployment noto e conserva le evidenze dell’errore.

Fase 5: Attività distruttive soggette ad approvazione

Mantieni i flag distruttivi dietro un’approvazione umana esplicita, anche quando la credenziale li consente tecnicamente. Usa API key con ambito limitato quando possibile ed esamina regolarmente l’audit trail.

L’installazione della skill dell’agente rafforza questi comportamenti:

npm install -g dockup-cli
dockup skill install
dockup skill status --json

La documentazione di riferimento della Dockup CLI descrive il comportamento applicato dei comandi. L’agente dovrebbe verificare lo schema locale invece di affidarsi a un esempio ricordato.

Checklist per la revisione dei guardrail

Prima di concedere l’accesso alla produzione, rispondi a ogni domanda:

• L’agente può individuare le destinazioni esatte senza fare supposizioni?
• I valori dei secret sono mascherati in tutti i percorsi di lettura?
• Ogni mutazione fallita restituisce un valore diverso da zero?
• Le operazioni lunghe possono attendere uno stato terminale?
• Le azioni distruttive vengono bloccate senza una conferma esplicita?
• Le credenziali sono soggette ad ambito limitato e fornite al di fuori dei prompt?
• Ogni mutazione può essere trovata in un audit log?
• Esiste una procedura di rollback o recovery testata?
• Le versioni della skill e dell’eseguibile possono divergere?
• Il report finale distingue i fatti dalle incertezze?

Una risposta “no” indica un’attività di design, non un problema di scrittura del prompt. L’autonomia in produzione dovrebbe crescere solo insieme alle garanzie sottostanti.

Testa i guardrail come casi di errore

Una revisione è incompleta finché il team non attiva deliberatamente i limiti. Esegui un deployment con un token non valido, richiedi una destinazione sconosciuta, lascia fallire una build di test, imposta un timeout molto breve e prova un comando distruttivo senza conferma. Ogni caso dovrebbe produrre un’uscita diversa da zero, un codice stabile, nessuna fuga di secret e nessuna mutazione non prevista.

Questi test trasformano i guardrail di produzione per agenti AI in garanzie osservabili. Ripetili dopo gli aggiornamenti della CLI o delle policy, proprio come ripeteresti i test di autenticazione e autorizzazione di un’applicazione. Un guardrail che esiste solo in una presentazione non proteggerà un rilascio non supervisionato.

Porta il workflow in produzione

Installa la skill, esamina le relative istruzioni e testa ogni guardrail, incluso un comando distruttivo bloccato, prima di emettere un token di produzione.

npm install -g dockup-cli
dockup skill install

Il primo comando installa la CLI. Il secondo installa la skill di Dockup corrispondente per Claude Code e Codex. Inizia gratuitamente su app.dockup.ai.

FAQ

Le istruzioni nel prompt sono sufficienti per mantenere un agente AI sicuro in produzione?

No. I prompt aiutano a guidare il comportamento, ma i controlli critici come il mascheramento dei secret, la conferma, l’autorizzazione, i codici di uscita e l’audit logging devono essere applicati dallo strumento e dalla piattaforma.

In che modo Dockup blocca le operazioni distruttive?

I comandi distruttivi rifiutano l’esecuzione senza il flag esplicito --yes e restituiscono il codice strutturato needs_confirm, consentendo all’agente di fermarsi e chiedere conferma a una persona.

Un agente AI può leggere i valori dei secret nelle variabili d’ambiente da Dockup?

I valori dei secret memorizzati sono mascherati nell’output. L’agente può vedere la chiave e l’indicatore del secret e può sostituire il valore, ma non riceve il secret memorizzato.

Perché i codici di errore strutturati sono importanti per l’autonomia?

Vincolano l’agente a percorsi di recovery noti, come richiedere l’autenticazione, individuare la destinazione esatta, leggere i build log o chiedere conferma.

Come dovrebbe iniziare un team a concedere l’accesso alla produzione?

Inizia con operazioni in sola lettura, poi consenti il deployment verso una sola destinazione a basso rischio ed estendi l’accesso alla configurazione e al recovery reversibili solo dopo che l’agente ha dimostrato di riportare con costanza evidenze verificabili.