Codex Security

Codex Security ti aiuta a trovare, analizzare e correggere le vulnerabilità nel tuo codice. Usa i suoi flussi di lavoro di sicurezza in Codex, oppure automatizzali con la CLI @openai/codex-security e l'SDK TypeScript.

• In Codex: scegli un flusso di lavoro di sicurezza.
• In un terminale: installa la CLI e scansiona il tuo repository.
• Nell'automazione: usa l'SDK TypeScript o la GitHub Action.

Funzionalità

• Scansiona repository, percorsi selezionati o modifiche Git. Le scansioni approfondite ripetono le scansioni Standard e restituiscono i loro risultati deduplicati.
• Convalida i risultati candidati, genera patch e verifica le correzioni esistenti.
• Redigi policy SECURITY.md e salva modelli di minaccia per revisioni successive.
• Sfoglia le scansioni e i risultati salvati, identifica i duplicati, valuta la gravità in base alla tua rubrica e suggerisci i responsabili dalla cronologia del codice sorgente e di Git.
• Visualizza in anteprima i risultati degli scanner di terze parti, salvali localmente o pubblica i report supportati su Codex Security Cloud. Guide all'importazione degli scanner.
• Monitora i risultati in Linear, Jira o GitHub, pubblica le scansioni completate o esporta in SARIF, JSON e CSV. Flussi di lavoro di integrazione.
• Automatizza le scansioni su repository o componenti di progetto, anche in CI e container.

Uso in Codex

Apri il tuo repository in una sessione Codex con il plugin Codex Security abilitato, poi chiedi:

Esegui una scansione di Codex Security su questo repository, concentrandoti su autenticazione e autorizzazione. Restituisci il report salvato, le evidenze nel codice sorgente e i limiti di copertura.

Una scansione completata salva un report e i risultati. Leggi il report per le evidenze nel codice sorgente e le esclusioni, poi richiedi una patch o chiedi a Codex di verificare una correzione esistente. Consulta la guida ai flussi di lavoro dell'agente per la configurazione, la selezione delle attività e il recupero.

Avvio rapido

Richiede Node.js 22.13.0+ all'interno della serie 22.x, oppure Node.js 24.x o 26.x, e Python 3.10+. Python 3.10 richiede anche tomli.

Installa la CLI a livello globale e accedi:

npm install --global @openai/codex-security
cs login

Esegui la tua prima scansione dalla directory del repository:

cs scan .

Al termine della scansione, apri il file Markdown nel percorso REPORT nel terminale. Esegui cs scans show dallo stesso repository per trovare nuovamente la sua ultima scansione completata. Consulta scan scope and follow-up work per capire come interpretare le esclusioni nel report.

cs e codex-security eseguono la stessa CLI. Se il nome breve è in conflitto con un altro comando, usa codex-security. Per saltare l'installazione globale, o se npm segnala un conflitto EEXIST, usa npx @openai/codex-security al posto di cs sia per il login che per la scansione.

Per la CI, imposta OPENAI_API_KEY o CODEX_API_KEY nell'ambiente del processo di scansione. Per una macchina headless, consulta device or SSH login.

Opzioni di scansione

Scegli un ambito e una modalità di scansione:

# Scan selected paths.
cs scan . --path src --path tests

# Scan committed changes from a base revision to HEAD.
cs scan . --diff origin/main

# Run a deep scan of the repository.
cs scan . --mode deep

Usa cs scan . --max-time 15 per un'indagine Standard consultiva con un limite di 15 minuti. Vedi investigation time per la semantica temporale e i limiti di Deep Scan.

Usa cs --help per sfogliare i comandi, oppure cs scan --help per le opzioni di scansione, i limiti di costo e il patching dopo una scansione.

Per un'applicazione distribuita su più repository, vedi review one system across repositories. Usa bulk scans per revisioni indipendenti dei repository in un'unica campagna ripristinabile.

Le scansioni utilizzano le indicazioni esistenti di root e componente SECURITY.md. Per scriverlo o revisionarlo, vedi Generate SECURITY.md.

Alcune richieste di cybersecurity e risultati protetti richiedono Trusted Access for Cyber. Per gli account con accesso Daybreak, vedi Daybreak opt-in per l'interruttore Codex e Cyber access programs per selezionare esplicitamente un programma.

TypeScript SDK

Installa il pacchetto localmente nel tuo progetto TypeScript:

npm install @openai/codex-security

Poi importalo:

import { CodexSecurity } from "@openai/codex-security";

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository");
  console.log(result.reportPath);
} finally {
  await security.close();
}

La guida SDK include la configurazione della scansione approfondita, la validazione, la classificazione della gravità, i suggerimenti sui proprietari e la gestione dei risultati.

Leggere i risultati Cloud esistenti

Quando Codex Security Cloud è disponibile per il tuo account, la skill $cloud-findings del plugin Security può leggere risultati, report, assegnazioni e verifiche registrate e lo stato delle scansioni in Codex desktop o nella Codex CLI. Cloud è una connessione opzionale; le scansioni locali funzionano senza di essa.

Consulta Configurazione della connessione Cloud e letture CLI per i requisiti di autenticazione e un esempio di sola lettura.

Generare SECURITY.md

Usa policy per redigere un nuovo SECURITY.md o aggiornarne uno esistente. Usa --path per selezionare un componente:

cs policy .
cs policy . --path services/api --knowledge-base architecture.md

Il comando salva la sua bozza fuori dal repository e lascia invariati i file esistenti. Rivedi il diff e le note, modifica la bozza, quindi copia solo SECURITY.md nel Policy target visualizzato. Mantieni i documenti salvati di architettura e modello di minaccia fuori dal repository.

Le scansioni utilizzano già i file SECURITY.md nella radice e nei componenti. Mantieni la tua policy attuale se non necessita di modifiche. Quando la aggiorni, preserva le sue istruzioni per la segnalazione delle vulnerabilità. Se il comando indica che la policy è già aggiornata, non è necessaria alcuna copia.