Cos’è Codex Security, e cosa non dimostra da solo

Codex Security è distribuito come pacchetto npm pubblico e repository open source con licenza Apache 2.0. Offre una CLI per lavorare da terminale e un SDK TypeScript per integrare le scansioni in altri strumenti. OpenAI lo presenta come un sistema per trovare, validare e correggere vulnerabilità nel codice.

Pubblico non significa immediatamente utilizzabile da ogni account: l’installazione del pacchetto è aperta, mentre l’esecuzione delle scansioni richiede accesso a Codex Security. La documentazione raccomanda inoltre un account verificato per Trusted Access for Cyber per ottenere i risultati migliori.

Soprattutto, uno scan non certifica che il repository sia sicuro. I risultati possono variare tra esecuzioni e la copertura può essere completa, parziale o sconosciuta. Un finding è un’ipotesi tecnica sostenuta da evidenze; va confermato sul codice e nel contesto dell’applicazione.

Preparare la prima scansione senza sporcare il repository

Il README attuale richiede una versione supportata di Node.js — 22.13 o successiva nella linea 22.x, oppure 24.x o 26.x — Python 3.10 o successivo e accesso a Codex Security. Per l’uso locale puoi autenticarti con ChatGPT; in CI si usa invece una chiave conservata nel secret manager del runner.

Salva i risultati fuori dal repository. Possono contenere estratti di codice, dettagli di vulnerabilità ed evidenze che non devono finire per errore in un commit. Prima dello scan reale usa il dry run: controlla input, target e cartella di output senza avviare Codex, caricare credenziali o verificare l’interprete Python.

  1. Controlla repository, branch e stato Git prima di iniziare.
  2. Verifica versione della CLI e requisiti locali.
  3. Scegli una cartella privata fuori dal worktree e definisci una retention appropriata.
  4. Esegui il dry run e leggi target, scope e destinazione mostrati.
  5. Avvia il primo scan in modalità report-only, senza soglie che blocchino il lavoro.
  6. Conserva comando, commit analizzato e percorso dei risultati nel registro della review.
Primo scan controllato 
npm install @openai/codex-security
npx @openai/codex-security --version
npx @openai/codex-security login

REPOSITORY=/percorso/al/repository
SCAN_DIR=/percorso/privato/fuori-dal-repository/codex-security-results

npx @openai/codex-security scan "$REPOSITORY"   --output-dir "$SCAN_DIR"   --dry-run

npx @openai/codex-security scan "$REPOSITORY"   --output-dir "$SCAN_DIR"

Leggere quattro artefatti, non soltanto il numero dei finding

Al termine, la CLI indica la cartella dei risultati e il percorso di report.md. Il report è il punto di ingresso leggibile, ma per decidere se la scansione è utilizzabile servono anche manifest, finding strutturati e copertura.

La gravità descrive l’impatto potenziale; la confidence esprime quanto il sistema considera sostenuta l’ipotesi. Nessuna delle due sostituisce la verifica di raggiungibilità, precondizioni e comportamento reale. Prima di correggere, leggi sempre quali parti non sono state esaminate.

scan-manifest.json
Registra target, scope, produttore e artefatti sigillati della scansione. Serve a capire esattamente cosa è stato analizzato.
findings.json
Contiene gravità, confidence, posizioni, evidenze e indicazioni di remediation per ogni finding.
coverage.json
Elenca superfici esaminate, esclusioni, lavoro rinviato, domande aperte e completezza della copertura.
report.md
Presenta il risultato in una forma leggibile per la review umana e collega i finding alle evidenze disponibili.

Scegliere lo scan in base alla domanda

Scansionare tutto per abitudine può costare più tempo senza rispondere meglio. Parti dalla decisione che devi prendere: valutare il repository, approfondire un servizio, controllare una pull request o esaminare modifiche locali.

Per repository complessi puoi fornire documenti di architettura, threat model e policy tramite --knowledge-base. È un modo per dare contesto verificabile, non per suggerire al sistema di ignorare codice che contraddice la documentazione.

Repository scan
Per una prima mappa del progetto e delle superfici principali. È il baseline più ampio.
Path scan
Per concentrarsi su servizi o pacchetti selezionati con uno o più flag --path.
Diff scan
Per confrontare revisioni Git e cercare regressioni introdotte da una modifica già committata.
Working-tree scan
Per esaminare modifiche staged e unstaged rispetto a una base scelta.
Deep mode
Per una revisione più ampia di repository o path. Non è disponibile per diff e working tree.
Esempi di scope 
# Due aree specifiche
npx @openai/codex-security scan "$REPOSITORY"   --path services/billing   --path packages/auth

# Modifiche committate rispetto alla base
npx @openai/codex-security scan "$REPOSITORY"   --diff origin/main   --head HEAD

# Modifiche locali rispetto a HEAD
npx @openai/codex-security scan "$REPOSITORY"   --working-tree   --base HEAD

Dal finding alla prova: un triage in sei passaggi

La parte più importante inizia dopo lo scan. Un finding può indicare una sink pericolosa ma sbagliare sull’origine dell’input, non vedere un controllo applicato altrove o assumere una configurazione che in produzione non esiste. Può anche scoprire un problema reale che un rule-based scanner non collega facilmente tra file.

Per questo il triage deve produrre una conclusione verificabile: confermato, falso positivo motivato oppure ancora incerto. “Sembra plausibile” non è uno stato finale.

  1. Identifica finding, file, righe e commit esatto coperto dalla scansione.
  2. Ricostruisci il percorso dall’input controllabile dall’attaccante alla sink indicata.
  3. Verifica autenticazione, autorizzazioni, configurazione e altri prerequisiti assunti dal report.
  4. Controlla sanitizzazione, escaping, query parametrizzate e guardie applicate lungo il percorso reale.
  5. Prepara un test o riproduttore sicuro nell’ambiente isolato, senza dati o sistemi di produzione.
  6. Registra esito, evidenze, lacune e persona che ha revisionato il finding.
Scheda di triage copiabile 
Finding: [ID]
Commit e scope: [revisione e path coperti]
Input controllabile: [origine]
Sink: [operazione sensibile]
Percorso raggiungibile: [sì / no / incerto]
Controlli esistenti: [elenco]
Riproduzione sicura: [comando o test]
Esito: [confermato / falso positivo / incerto]
Evidenze: [file, righe, output]
Lacune residue: [elenco]
Reviewer: [nome o ruolo]

Confrontare due scansioni senza dichiarare “risolto” troppo presto

La documentazione OpenAI chiarisce che scansioni assistite dall’AI possono variare anche con la stessa configurazione. Per un confronto ripetibile, riesegui il baseline, abbina i finding con la stessa causa radice e poi confronta gli stati.

Il confronto distingue finding nuovi, persistenti, riaperti, risolti o sconosciuti. “Sconosciuto” è il risultato corretto quando la nuova scansione non copre il target originale o presenta lacune. Anche un finding assente va ricontrollato direttamente se è importante.

Rieseguire, abbinare, confrontare 
npx @openai/codex-security scans rerun BEFORE_SCAN_ID

npx @openai/codex-security scans match   BEFORE_SCAN_ID   AFTER_SCAN_ID

npx @openai/codex-security scans compare   BEFORE_SCAN_ID   AFTER_SCAN_ID

Correggere un finding con una patch piccola e una prova forte

Per un finding confermato, definisci prima l’invariante di sicurezza: quale input deve essere rifiutato, trasformato o autorizzato e quale comportamento legittimo deve restare disponibile. La patch migliore è circoscritta e rende quel vincolo visibile nel codice.

Quando è sicuro e pratico, aggiungi un regression test che fallisce prima della correzione e passa dopo. Se il test non è possibile, registra la lacuna e conserva la verifica ripetibile più forte disponibile. Dopo la patch, riesegui lo scan originale, confronta copertura e finding e ricontrolla direttamente il problema sul checkout corrente.

  1. Conferma il finding e scrivi l’invariante atteso.
  2. Crea la modifica minima, senza refactor o pulizia non collegati.
  3. Dimostra il fallimento sul codice precedente con un test o una verifica isolata.
  4. Esegui lo stesso controllo dopo la patch e prova anche il comportamento legittimo.
  5. Lancia i test collegati e controlla il diff completo.
  6. Riesegui, abbina e confronta gli scan; leggi di nuovo coverage.json.
  7. Chiudi il finding soltanto dopo una decisione umana documentata.

Portarlo in CI solo dopo aver capito rumore e copertura

Inizia in modalità report-only su alcune pull request rappresentative. Misura durata, costo, copertura, finding confermati e falsi positivi. Soltanto dopo definisci una soglia che possa fallire il job, per esempio high.

La guida ufficiale installa la CLI fuori dal checkout prima di leggere il codice della pull request, usa una chiave limitata al solo step di scan e salva stato e risultati fuori dal repository. È una separazione importante: il codice non fidato della pull request non deve controllare l’eseguibile o ricevere la credenziale usata per analizzarlo.

In CI, exit code 0 indica scan completo e policy superata; 1 indica un finding alla soglia configurata o superiore; 2 indica errore oppure copertura incompleta. Trattare 2 come “nessun problema trovato” renderebbe il controllo ingannevole.

  • Credenziale in un secret manager, mai nel repository o nei log.
  • CLI installata in una directory fidata esterna al checkout.
  • Base e head risolte esplicitamente con la cronologia Git necessaria.
  • Risultati conservati come artefatti privati per un periodo breve.
  • SARIF pubblicato solo verso una destinazione con accessi appropriati.
  • Copertura incompleta distinta da policy superata.
Soglia da introdurre dopo il periodo report-only 
codex-security scan .   --diff "$BASE_REVISION"   --head "$HEAD_REVISION"   --auth api-key   --output-dir "$SCAN_DIR"   --fail-on-severity high

Checklist per una prova che produca evidenze utili

Per la prima adozione scegli un repository che sei autorizzato a valutare e un flusso non critico. L’obiettivo non è ottenere zero finding: è capire se sai riprodurre il processo e motivare le decisioni.

Checklist copiabile 
[ ] Repository e autorizzazione verificati
[ ] Node, Python, CLI e accesso controllati
[ ] Stato Git e commit registrati
[ ] Cartella risultati privata e fuori dal repository
[ ] Dry run completato
[ ] Primo scan in modalità report-only
[ ] report.md e scan-manifest.json letti
[ ] findings.json revisionato per evidenze e precondizioni
[ ] coverage.json controllato per esclusioni e domande aperte
[ ] Finding importanti riprodotti o marcati come incerti
[ ] Fix limitati e accompagnati da test o prova ripetibile
[ ] Scan successivo abbinato e confrontato con il baseline
[ ] Lacune e rischi residui documentati
[ ] Nessun segreto o artefatto sensibile finito in Git

Fonti ufficiali da controllare prima di usarlo

Codex Security è un progetto giovane e comandi, accesso, modelli predefiniti e requisiti possono cambiare. Prima di automatizzarlo verifica sempre README, riferimento CLI e guida CI correnti. Questa guida usa la documentazione disponibile il 30 luglio 2026.

La regola pratica

CONTINUA A LEGGERE

Altre guide collegate

01 OpenAI Academy: 3 corsi gratuiti per imparare l’AI, anche se non sei tecnico Leggi → 02 Agent Data Injection: perché fermare la prompt injection non basta Leggi → 03 Codex dentro ChatGPT: la checklist prima di affidargli il tuo progetto Leggi →
PROSSIMO PASSO

Prova su un caso reale, ma piccolo

Parti da una email, un riassunto o un confronto semplice. Controlla sempre dati personali, date, numeri e decisioni importanti.

Torna a AI pratica