Sicurezza di Codex in pratica: permessi, sandbox e protezione dai leak di secrets

Nella root del tuo progetto c’è un file .env con la password del database e API key di terze parti. Apri Codex per farti aiutare a rifattorizzare il codice dei test. Nel menu compaiono read-only, workspace-write e danger-full-access. Quale scegli?

Dopo aver scelto workspace-write, Codex chiede l’approvazione per eseguire npm install. Tu approvi. Hai pensato che quello script postinstall poco visibile in package.json potrebbe, proprio in quel passaggio, leggere le variabili d’ambiente o inviare una richiesta a un servizio che non conosci?

Metti Codex in GitHub Actions per automatizzare la PR review. Nel workflow scrivi OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}. Sembra sicuro, perché è nei secrets. Ma hai considerato che gli script di test, le third-party actions e gli install hooks delle dipendenze nello stesso job potrebbero leggere quella key?

Tre confini rispondono direttamente a queste domande: le istruzioni non sono permessi, l’approvazione non è isolamento, la sandbox non è audit. Da qui costruiamo la checklist di permessi minimi per locale, Cloud e CI.

I permessi non si proteggono a parole: capire i tre confini sandbox, approval e permission profile

Molti pensano che scrivere in AGENTS.md una frase come “non leggere il file .env” basti a impedire a Codex di accedere a informazioni sensibili. Non è controllo dei permessi, è una linea guida di progetto. Il vero confine di sicurezza nasce da tre livelli: sandbox limita l’ambito dei spawned commands, approval policy decide quando fermarsi e chiedere conferma, permission profile applica il controllo d’accesso obbligatorio.

La sicurezza di Codex non basta costruirla con un solo livello. sandbox decide a cosa possono accedere git, gestori di pacchetti e test runner come spawned commands. approval policy decide se Codex deve chiederti conferma prima di operazioni critiche. permission profile è il livello di configurazione in cui puoi scrivere davvero "**/*.env" = "deny". I tre livelli insieme formano i permessi effettivi.

Confronto dei modi sandbox: read-only, workspace-write, danger-full-access

modo sandbox	Definizione	Scenario adatto	Rischio
read-only	Consente solo lettura dei file, non scrittura o esecuzione di comandi	Code review, analisi architetturale, generazione documentazione, controlli CI in sola lettura	Non protegge tutti i secrets sul runner; il processo gira comunque sul runner
workspace-write	Consente scrittura nell’active workspace, rete chiusa di default	Sviluppo locale quotidiano, modifica del codice, esecuzione di test	Può leggere di default tutti i file nel workspace, incluso .env; serve un deny glob
danger-full-access	Rimuove i confini di filesystem e rete	isolated CI runner/container, ambiente di test completamente controllato	Può accedere a ~/.ssh, /tmp, variabili d’ambiente e servizi locali; non usarlo come default quotidiano

sandbox limita i spawned commands, non solo le operazioni file integrate di Codex. git, gestori di pacchetti e test runner ereditano lo stesso confine. Anche la piattaforma conta: Linux/WSL2 dipende da bubblewrap o user namespace, macOS dalla sandbox di sistema, Windows dalle capacità sandbox disponibili.

approval policy decide quando fermarsi e chiedere:

approval policy	Definizione	Combinazione comune	Permessi effettivi
on-request	Fa pausa prima dell’operazione e chiede approvazione	workspace-write + on-request per automazione locale	Rischio più basso; scrittura, comandi e richieste di rete sono confermati da una persona
never	Nessuna approvazione interattiva, esecuzione diretta	read-only + never per CI in sola lettura; danger-full-access + never in ambiente controllato	Rischio alto; workspace-write + never senza permission profile è rischioso

Le combinazioni a basso rischio sono read-only + never per CI in sola lettura e workspace-write + on-request per sviluppo locale. La combinazione ad alto rischio è danger-full-access + never, da usare solo in ambienti controllati.

Configurazione permission profile: filesystem deny, network rules

permission profile è controllo d’accesso obbligatorio, non una regola verbale. I permessi filesystem supportano read/write/deny; le regole più specifiche sovrascrivono quelle più ampie e deny ha priorità.

Esempio di deny glob per .env:

{
  "filesystem": {
    "rules": {
      "**/*.env": "deny",
      "**/.env.local": "deny",
      "**/secrets/**": "deny",
      "workspace/**": "write"
    }
  }
}

Con questa configurazione, i file .env restano illeggibili anche in workspace-write, anche se il workspace è scrivibile per default. deny vince e le regole concrete sovrascrivono quelle ampie.

network profile può configurare enabled = true e regole allow/deny per dominio; anche qui deny ha priorità. local/private network ha protezioni di default. Consentire localhost o Docker socket è un’eccezione esplicita. Docker socket è un escape hatch locale: può raggiungere servizi locali, container e reti, quindi va aperto con cautela.

network proxy limita l’accesso di rete dei comandi già abilitati; da solo non concede rete. Un allow globale * è accesso di rete ampio e va trattato con attenzione.

Checklist locale dei permessi minimi: da review read-only a full access

In locale, più permessi non significa meno problemi. Approval può fermare alcune operazioni, ma il vero isolamento viene da sandbox e permission profile. Parti dai permessi più stretti e allargali solo quando il task lo richiede.

Tabella decisionale: quando usare read-only e quando workspace-write

Scenario	modo sandbox	approval policy	permission profile	Rischio
Code review / analisi architetturale	read-only	never	Non necessario	Basso
Sviluppo quotidiano / modifica codice	workspace-write	on-request	deny per .env	Medio-basso
Eseguire test / installare dipendenze	workspace-write	on-request	deny per .env, audit degli script	Medio
CI in sola lettura	read-only	never	Non necessario	Basso
CI con scrittura di file	workspace-write	never	deny, isolated runner	Medio-alto
Serve full access	danger-full-access	never	Solo ambiente controllato	Alto

Passaggi per proteggere .env e file di secrets:

1. Trova il percorso del file di configurazione permission profile usato, seguendo la documentazione Codex Permissions.
2. Aggiungi "**/*.env" = "deny" alle permission filesystem.
3. Verifica che le regole più specifiche sovrascrivano quelle più ampie e che deny abbia priorità.
4. Testa: in modalità workspace-write, un tentativo di leggere .env dovrebbe essere negato.
5. Estendi se serve con "**/.env.local" = "deny" e "**/secrets/**" = "deny".

Non fare affidamento su regole verbali. AGENTS.md guida, ma non applica controllo d’accesso obbligatorio. Codex può seguire la guida, ma può anche leggere per altri motivi. Solo deny nel permission profile è un confine vincolante.

Rischi dell’installazione delle dipendenze: npm postinstall, pip hooks, Docker socket

Installare dipendenze non significa solo scaricare file. postinstall e prepare di npm/pnpm, e gli hooks di pip install, vengono eseguiti automaticamente durante l’installazione. Questi script possono leggere variabili d’ambiente, inviare richieste di rete o modificare file di sistema.

Checklist dei rischi:

• Un postinstall sconosciuto può leggere variabili d’ambiente: anche con deny per .env, postinstall gira nell’ambiente dei spawned commands e può vedere environment variables.
• Può inviare richieste di rete: scaricare binari aggiuntivi, inviare telemetria, connettersi a repository privati.
• Può modificare file di sistema: scrivere configurazione globale, modificare PATH.

Raccomandazioni di audit:

1. Controlla prima script e origine: campo scripts di package.json, setup.py dei pacchetti pip.
2. Usa fonti affidabili: blocca le versioni ed evita upgrade automatici verso versioni sconosciute.
3. Approva in ambiente controllato: in locale usa workspace-write + on-request e guarda cosa Codex vuole installare prima di approvare.

Docker socket è un escape hatch locale. Consentirlo può dare accesso a servizi locali, container e rete. Configuralo solo se serve davvero, non di default.

Confini Cloud: setup vs agent phase, ciclo di vita dei secrets

Una Cloud task non gira in locale, ma in un container isolato ospitato da OpenAI. sandbox può limitare i spawned commands, ma la protezione reale dei secrets viene dal ciclo di vita di Cloud secrets: disponibili nella fase setup, rimossi prima della agent phase. sandbox non è audit; la sicurezza nasce dalla separazione in livelli.

Ciclo di vita del Cloud container:

1. Creare il container
2. Fare checkout del repo
3. Eseguire setup script
4. Applicare le impostazioni di rete
5. L’agent esegue il ciclo dei comandi
6. Produrre answer/diff

Confine setup vs agent phase: secrets solo nel setup

fase	Accesso rete	secrets disponibili	environment variables	Installazione dipendenze
setup scripts	Disponibile	Disponibili	Presenti per tutta la durata	Possibile
agent phase	Offline di default	Rimossi	Presenti per tutta la durata	Offline di default

Nella fase setup ci sono rete, installazione delle dipendenze e secrets. Nella agent phase l’ambiente è offline di default, i secrets sono stati rimossi e restano solo environment variables.

setup scripts gira in una sessione Bash separata; export non passa automaticamente alla agent phase. Se nel setup fai export MY_KEY=xxx, la agent phase non eredita quella variabile. Tra le fasi passano solo Cloud secrets ed environment variables secondo le rispettive regole.

secrets vs environment variables: la differenza chiave

Tipo	Cifratura	Fase disponibile	Uso	Ciclo di vita
environment variables	Nessuna cifratura aggiuntiva	setup + agent sempre	Configurazione non sensibile, percorsi, switch	Presenti per tutta la vita del container
secrets	Cifratura aggiuntiva	Solo setup scripts	Accesso a repository privati, autenticazione per dipendenze	Rimossi prima della agent phase

secrets sono disponibili solo nei setup scripts. Sono adatti per installare dipendenze e collegarsi a repository privati. La agent phase non dovrebbe contenere secrets di produzione. environment variables restano sempre e sono adatte a configurazione non sensibile.

Confini dell’installazione delle dipendenze:

• setup phase può installare dipendenze con rete.
• agent phase è offline di default.
• setup scripts può accedere ai secrets; uno script sconosciuto può farli trapelare.
• Raccomandazione: controlla script e origine, usa fonti affidabili ed evita script sconosciuti nel setup.

Il container cache dura al massimo 12 ore. Cambiamenti a setup, maintenance, env o secrets causano cache invalidation.

CI e GitHub Action: codex exec, divieti sulle API key e strategia sicura della official Action

codex exec usa per default una read-only sandbox, ma molti workflow mettono OPENAI_API_KEY come job-level environment variable. Gli script di test, third-party actions e dependency lifecycle scripts nello stesso job possono leggere quella key. sandbox non è audit; la sicurezza viene da permessi minimi e protezione della key.

Divieto sulle API key: non usare job-level env

Non definire OPENAI_API_KEY o CODEX_API_KEY come job-level environment variable in un workflow che fa checkout o esegue codice del repository. Codice del repository, test, dependency lifecycle scripts e third-party actions possono ancora accedere alle variabili d’ambiente nello stesso job.

Checklist dei divieti:

• Non mettere OPENAI_API_KEY come job-level env.
• Non configurare una job-level key in workflow che fanno checkout o eseguono codice del repository.
• auth.json / ChatGPT-managed auth non è adatto a workflow di repository public/open-source.
• Non eseguire codice non affidabile nello stesso process environment della key.

Modalità corrette:

1. Invocation inline singola: imposta CODEX_API_KEY solo per una invocation di codex exec.

- name: Run Codex
  run: CODEX_API_KEY=${{ secrets.CODEX_API_KEY }} codex exec "review PR #${{ github.event.number }}"

2. Proxy della official Action: usa il proxy di openai/codex-action@v1.

- uses: openai/codex-action@v1
  with:
    prompt: "review PR #${{ github.event.number }}"
    sandbox: read-only
    safety-strategy: drop-sudo

danger-full-access in CI ha senso solo in isolated CI runner/container. Non dovrebbe essere il default, perché può accedere a tutte le risorse del runner.

Checklist di sicurezza GitHub Action: limitare i trigger, proteggere la key, ruotare la key

Parametri della official Action:

parametro	valore di default	spiegazione
safety-strategy	drop-sudo	Rimuove i permessi sudo
sandbox	-	Sceglie read-only/workspace-write/danger-full-access
allow-users	utenti con write access	Solo utenti specifici possono attivare
allow-bots	-	Se consentire l’attivazione da bot

read-only non significa che tutti i secrets del runner siano protetti. L’Action gira comunque sul runner; limita soprattutto il filesystem in lettura. drop-sudo rimuove sudo. sandbox dovrebbe essere il modo più stretto che completa il task.

Checklist di sicurezza GitHub Action:

• Limitare chi può attivare: allow-users solo per utenti specifici, allow-bots con cautela.
• Pulire input PR/issue/prompt: evitare prompt injection e non passare input non affidabile direttamente a Codex.
• Proteggere API key: niente job-level env, usare invocation inline singola o proxy.
• Eseguire Codex come ultimo passaggio: ridurre il tempo di esposizione della key.
• Se sospetti un leak, ruota la key: non indagare prima, riduci prima il danno.

Gli input PR/issue/prompt vanno trattati come non affidabili. Non passare un PR comment o un issue body direttamente al prompt di Codex.

Gestione di un leak di secret: la prima mossa dopo un sospetto

Se sospetti un leak, la prima mossa non è investigare, ma ruotare la key. Prima riduci il danno, poi fai audit. sandbox può limitare i spawned commands, ma non può impedire a Codex di scrivere una key in log, PR comment o answer.

Passaggi in caso di leak: rotazione key, audit, revoca

Primo passaggio: ruotare la key. Non cercare prima la fonte; rendi non valida la key vecchia.

Passaggi successivi:

1. Audit dei log: controlla lo storico d’uso della key e cerca chiamate anomale.
2. Revoca del token: verifica che la key vecchia sia completamente non valida e che non resti alcuna session attiva.
3. Ricerca della fonte: controlla Codex log, output di GitHub Action, script di installazione delle dipendenze e third-party actions.

Misure preventive:

• Non mettere API key nel codice frontend o nel repository.
• Non mettere API key come job-level env (CI).
• Usa permission profile deny per .env.
• Ruota le key regolarmente, come suggerisce OWASP Secrets Management Cheat Sheet.

Limiti di Codex Security: non sostituisce SAST e non applica patch automaticamente

Codex Security è un LLM-driven security analysis toolkit che gira in un ephemeral isolated container e produce finding strutturati e patch suggestions. Può aiutare a scoprire e verificare vulnerabilità, ma non sostituisce SAST o una revisione manuale di sicurezza.

Checklist dei limiti:

• Non sostituisce SAST.
• Non sostituisce manual security review.
• Un proposed patch richiede review dell’utente e non viene applicato automaticamente.
• Serve ad aiutare a trovare, verificare e suggerire, non a riparare automaticamente.

Non trattare Codex Security come uno scanner di sicurezza universale. AI-driven analysis può trovare alcuni problemi, ma la sicurezza reale nasce da livelli: area leggibile, area scrivibile, rete, secrets, approval, review e revoca.

Conclusione

Il confine di sicurezza di Codex nasce da tre livelli: sandbox limita l’ambito dei spawned commands, approval policy decide quando fermarsi e chiedere, permission profile applica il controllo d’accesso obbligatorio. Insieme formano i permessi reali.

Tre confini da ricordare:

• Le istruzioni non sono permessi: AGENTS.md è una guida, non controllo d’accesso obbligatorio. Non proteggere .env e API key solo con regole verbali.
• L’approvazione non è isolamento: approval policy può fermare alcune operazioni, ma l’isolamento reale viene da sandbox e permission profile.
• sandbox non è audit: sandbox può limitare spawned commands, ma non impedisce a Codex di scrivere una key in log, PR comment o answer. La sicurezza nasce da livelli.

Checklist rapida:

• Hai configurato un deny glob per .env?
• Eviti API key come job-level env in CI?
• Limiti chi può attivare la GitHub Action?
• Hai fatto audit degli script di installazione delle dipendenze?
• Hai un piano di rotazione delle key?

I confini di sicurezza non bloccano gli errori logici. Codex può rispettare tutte le regole di permesso e generare comunque codice con bug, i test possono fallire e può servire un rollback. Validare il diff, eseguire i test e preparare un piano di rollback è la seconda linea di difesa fuori dal confine di sicurezza.

Prossimi passi:

• Retrospettiva dei fallimenti e flusso di validazione: capire come gestire errori di Codex, validare diff e preparare rollback.
• Automazione con codex exec e CI: approfondire modalità non interattiva, design dei workflow e gestione degli errori in CI.
• Regole di progetto AGENTS.md: imparare a scrivere regole di progetto, ricordando che sono una guida e non un sistema di permessi.

Letture correlate:

• Panoramica degli strumenti di AI coding 2026: capire l’ecosistema complessivo degli strumenti di AI coding.
• Fondamenti di GitHub Actions CI: ripassare i concetti base dei workflow CI.
• Strategia di deployment con GitHub Actions: capire i confini d’uso dei secrets nel deployment.
• Rischio di leak delle API key nel frontend: capire perché le key non devono finire nel frontend o nel repository.