SDK TypeScript de Codex Security

Utilisez le SDK TypeScript de Codex Security pour analyser la sécurité de dépôts et de modifications du code depuis votre application ou votre outil de développement. Le SDK renvoie les constats sous forme d’objets typés, le manifeste de l’analyse et les chemins des rapports enregistrés.

Le SDK utilise les modules ECMAScript (ESM) et s’exécute côté serveur avec Node.js 24 ou 26, ou avec Node.js 22 à partir de la version 22.13.0. Les analyses nécessitent également Python 3.10 ou une version ultérieure. Avec Python 3.10, le paquet tomli est également nécessaire.

Pour lire ou reprendre des sessions Codex compressées (.jsonl.zst), utilisez Node.js 22.15.0 ou une version ultérieure de la série 22.x, ou encore Node.js 24 ou 26. Les sessions .jsonl non compressées fonctionnent avec toutes les versions de Node.js prises en charge.

Configurez le SDK

Installez le SDK :

npm install @openai/codex-security

Avant de lancer une analyse, définissez OPENAI_API_KEY ou CODEX_API_KEY, utilisez une connexion Codex déjà enregistrée dans un fichier ou configurez un autre fournisseur. Amazon Bedrock utilise des identifiants AWS. OpenRouter et Fireworks utilisent chacun une clé API et une configuration propres au fournisseur.

Certaines requêtes de cybersécurité et certains constats protégés nécessitent que votre compte ChatGPT ou votre organisation API bénéficie de Trusted Access for Cyber.

Lancez une analyse

Le SDK s’exécute avec les permissions que vous accorde le système d’exploitation local et ne s’interrompt pas pour demander une approbation. Les processus d’analyse peuvent hériter de votre environnement. Supprimez donc les identifiants sans rapport avec l’analyse avant de la lancer. Consultez les permissions des analyses locales.

Enregistrez cet exemple dans scan.mjs. Passez le chemin du dépôt, puis celui du répertoire de résultats, en arguments de ligne de commande. Lancez une analyse standard du dépôt, puis fermez le client une fois l’analyse terminée. Utilisez outputDir pour choisir un répertoire de résultats privé en dehors de l’arbre de travail Git qui contient le code.

Si vous omettez outputDir, Codex Security enregistre les résultats dans son propre répertoire d’état persistant. Les résultats peuvent contenir des extraits de code source et des détails sur les vulnérabilités. Définissez qui peut les lire et combien de temps les conserver.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import { CodexSecurity } from "@openai/codex-security";

const [repository, outputDir] = process.argv.slice(2);
if (!repository || !outputDir) {
  throw new Error("Usage: node scan.mjs <repository> <results-directory>");
}
const security = new CodexSecurity();

try {
  const result = await security.run(repository, {
    outputDir,
  });

  console.log(result.reportPath);
  console.log(result.manifest.scan.status);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}

Exécutez le script avec Node.js :

node scan.mjs /path/to/repository /path/outside/repository/results

L’exemple affiche le chemin du rapport, l’état de l’analyse et le nombre de constats. Ouvrez le rapport pour examiner les éléments qui étayent ces constats.

run valide les artefacts enregistrés et renvoie un objet ScanResult lorsque result.manifest.scan.status vaut "completed". Consultez result.manifest.scan.scope pour connaître la cible demandée et result.manifest.scan.warnings pour lire les éventuels avertissements. Le seul fait que l’analyse soit terminée ne vous indique pas quels fichiers ont été examinés. Un problème d’exécution, de données d’entrée ou d’intégrité des résultats peut entraîner une erreur.

Dans les exemples suivants, réutilisez le client security ouvert et conservez l’appel à close() dans le bloc finally pour libérer l’environnement d’exécution. Ajoutez les imports nécessaires en tête de scan.mjs.

Vérifiez les entrées avant l’analyse

Utilisez preflight pour vérifier le dépôt, la cible, le mode, les documents de la base de connaissances, l’emplacement de sortie et la configuration de Codex avant de lancer une analyse. Cet exemple lit le fichier security.md à la racine du dépôt :

1
2
3
4
5
6
7
8
9
10
11
12
13
14import { join } from "node:path";

const knowledgeBase = join(repository, "security.md");

const plan = await security.preflight(repository, {
  target: ["services/billing", "packages/auth"],
  knowledgeBasePaths: [knowledgeBase],
  outputDir: outputDir,
});

console.log(plan.repository);
console.log(plan.target.kind);
console.log(plan.mode);
console.log(plan.outputDir);

Cette vérification préalable porte sur les entrées locales. Elle ne démarre pas Codex, ne charge pas les identifiants et ne vérifie pas la disponibilité de Python ni du plugin. Même si elle réussit, l’authentification ou le démarrage de l’analyse peuvent échouer.

Pour obtenir un aperçu de l’archivage d’un répertoire de résultats existant, spécifiez archiveExisting: true :

1
2
3
4
5
6const plan = await security.preflight(repository, {
  outputDir: outputDir,
  archiveExisting: true,
});

console.log(plan.archiveDir);

La valeur renvoyée dans archiveDir illustre la façon dont l’archive sera nommée. Le chemin final peut différer, car run génère sa propre destination unique. Récupérez le chemin réel de l’archive avec onOutputArchived :

1
2
3
4
5
6
7
8
9
10
11try {
  await security.run(repository, {
    outputDir: outputDir,
    archiveExisting: true,
    onOutputArchived(archiveDir) {
      console.log("Archived results:", archiveDir);
    },
  });
} finally {
  await security.close();
}

L’analyse archive les résultats précédents et démarre avec un répertoire de sortie vide.

Choisissez une cible d’analyse

Le SDK peut analyser un dépôt, des chemins précis, les différences entre deux commits ou les modifications de l’arbre de travail. Par défaut, l’analyse porte sur l’ensemble du dépôt.

Analysez des chemins précis

Passez un tableau de chemins situés dans le dépôt :

1
2
3
4
5
6
7try {
  const result = await security.run(repository, {
    target: ["services/billing", "packages/auth"],
  });
} finally {
  await security.close();
}

Les chemins peuvent désigner des fichiers ou des répertoires. Le SDK résout chaque chemin à l’intérieur du dépôt et élimine les doublons.

Analysez les modifications entre deux commits

Utilisez DiffTarget.refs pour analyser les modifications entre deux révisions Git disponibles localement :

1
2
3
4
5
6
7
8
9
10
11
12import { DiffTarget } from "@openai/codex-security";

const target = DiffTarget.refs({
  base: "HEAD~1",
  head: "HEAD",
});

try {
  const result = await security.run(repository, { target });
} finally {
  await security.close();
}

La révision finale est HEAD par défaut. Indiquez la racine de l’arbre de travail Git comme dépôt et placez-vous sur la révision finale demandée avant de lancer l’analyse.

Analysez l’arbre de travail

Utilisez DiffTarget.workingTree pour analyser les modifications indexées et non indexées par rapport à une révision de référence :

1
2
3
4
5
6
7import { DiffTarget } from "@openai/codex-security";
const target = DiffTarget.workingTree({ base: "HEAD" });
try {
  const result = await security.run(repository, { target });
} finally {
  await security.close();
}

La révision de référence est HEAD par défaut. Récupérez les révisions choisies avant de lancer une analyse des différences ou de l’arbre de travail.

Choisissez le mode approfondi

Spécifiez mode: "deep" lorsqu’un dépôt ou certains chemins nécessitent un examen plus étendu :

1
2
3
4
5
6
7
8
9
10
11
12
13try {
  const result = await security.run(repository, {
    target: ["services/billing"],
    mode: "deep",
    workers: 2,
    subagents: 0,
    stopAfterNoNew: 3,
    maxDiscoveryRuns: 10,
    maxTimeMinutes: 90,
  });
} finally {
  await security.close();
}

Le mode approfondi prend en charge les dépôts et les chemins. Utilisez le mode standard pour analyser les différences entre commits ou l’arbre de travail. En mode approfondi, workers limite le nombre de processus d’analyse exécutés en parallèle et subagents fixe le nombre de sous-agents par processus. stopAfterNoNew arrête la recherche après le nombre indiqué d’exécutions consécutives sans nouveau constat. maxDiscoveryRuns limite le nombre total d’exécutions de ces processus.

Définissez maxTimeMinutes pour limiter la durée de la recherche approfondie. La valeur par défaut et la valeur maximale sont de 5 760 minutes (96 heures). À l’échéance, la recherche s’arrête et le SDK regroupe les résultats des processus qui ont terminé leur travail. Pour les analyses standard, maxTimeMinutes donne une durée indicative pour l’investigation. La production du rapport peut se terminer plus tard. La validation personnalisée et les instructions de suivi s’exécutent en dehors de ce délai.

Ajoutez une base de connaissances sur la sécurité

Utilisez knowledgeBasePaths pour fournir des documents d’architecture, des modèles de menace ou des politiques de sécurité :

1
2
3
4
5
6
7
8
9
10
11import { join } from "node:path";

const knowledgeBase = join(repository, "security.md");

try {
  const result = await security.run(repository, {
    knowledgeBasePaths: [knowledgeBase],
  });
} finally {
  await security.close();
}

Le SDK accepte des fichiers ou des répertoires et parcourt les répertoires de manière récursive. Les formats pris en charge comprennent le texte UTF-8 (y compris JSON et SARIF), PDF et DOCX. Le SDK refuse les chemins d’entrée qui sont des liens et ignore les liens qu’il rencontre en parcourant les répertoires.

Le SDK enregistre le texte extrait des documents dans le fichier privé .scan-knowledge.json, aux côtés des artefacts de l’analyse. Conservez ce fichier dans le répertoire de l’analyse. À la reprise d’une analyse approfondie interrompue, codex-security scans resume utilise ce texte enregistré, même si les documents d’origine ont été modifiés ou supprimés. Les rapports de référence n’intègrent pas le texte des documents.

Ajoutez des instructions d’analyse et de suivi

Utilisez scanPrompt pour orienter l’analyse et postScanPrompt pour demander une action de suivi :

1
2
3
4
5
6
7
8try {
  const result = await security.run(repository, {
    scanPrompt: "Focus on tenant isolation and authorization checks.",
    postScanPrompt: "Write confirmed findings to post-scan-summary.md.",
  });
} finally {
  await security.close();
}

Si l’action de suivi échoue, le SDK conserve l’analyse terminée et signale l’erreur via onWarning. Il restaure les artefacts de l’analyse terminée que l’action de suivi a modifiés. Cette action s’exécute après l’arrêt du suivi des coûts de l’analyse et n’est pas soumise à maxCostUsd.

Validez les constats dans votre environnement

Passez validationPrompt pour vérifier les constats potentiels avec votre propre procédure de test. Par exemple, indiquez dans le prompt le chemin d’un script que vous contrôlez, situé en dehors de la copie de travail, et exécutez ce script en ciblant votre serveur de test local. Après les arguments indiquant le dépôt et le répertoire de résultats, passez le chemin du script de validation, puis l’URL du serveur :

1
2
3
4
5
6
7const [validationScript, validationUrl] = process.argv.slice(4);
if (!validationScript || !validationUrl)
  throw new Error("Pass a validation script path and service URL.");
const result = await security.run(repository, {
  outputDir,
  validationPrompt: `Run ${validationScript} against ${validationUrl} and report which findings reproduce.`,
});

node scan.mjs /path/to/repository /path/outside/repository/results /path/to/validate.sh http://localhost:3000

Utilisez validationPrompt avec les analyses standard portant sur un dépôt, des chemins, des différences entre commits ou un arbre de travail. Pour appliquer la même procédure à chaque analyse standard de composant, passez scanOptions.validationPrompt à runComponentScans. Les analyses approfondies n’acceptent pas de validation personnalisée.

Définissez un budget d’analyse

Définissez maxCostUsd pour arrêter une analyse lorsque le coût estimé d’utilisation du modèle dépasse la limite choisie. Utilisez onCost pour suivre le coût pendant l’analyse et afficher estimatedUsdRange :

1
2
3
4
5
6
7
8
9
10
11
12try {
  const result = await security.run(repository, {
    maxCostUsd: 5,
    onCost(cost) {
      console.log(cost.estimatedUsdRange);
    },
  });

  console.log(result.cost?.estimatedUsdRange);
} finally {
  await security.close();
}

La limite s’appuie sur estimatedUsd, l’estimation de référence pour un contexte court. Les requêtes déjà en cours peuvent porter cette estimation au-delà de la limite. La tarification des contextes longs peut aussi porter estimatedUsdRange au-delà de cette limite. Il ne s’agit pas d’un plafond de facturation.

Si une analyse approfondie atteint la limite après que Codex Security a regroupé les résultats des processus terminés, run peut renvoyer un résultat dont manifest.scan.status vaut "completed" et signaler l’avertissement budgétaire via onWarning.

Si l’analyse ne peut pas produire de résultat final valide, run lève l’exception ScanCostLimitExceededError et conserve les sorties disponibles.

Analysez les composants d’un projet

Utilisez runComponentScans pour analyser des services ou des paquets en parallèle et regrouper leurs constats. Attribuez à chaque composant un nom et un ou plusieurs chemins relatifs à la racine du dépôt. Choisissez un répertoire de sortie nouveau ou vide, en dehors de l’arbre de travail Git qui contient le projet.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import { runComponentScans } from "@openai/codex-security";

const result = await runComponentScans({
  repository: repository,
  outputDir: outputDir,
  components: [
    { name: "API", paths: ["services/api", "packages/auth"] },
    { name: "Web", paths: ["services/billing"] },
  ],
  workers: 2,
  onProgress: ({ name, status }) => console.log(name, status),
});

console.log(result.reportPath);
if (result.failed > 0) {
  throw new Error(`${result.failed} component scans failed.`);
}

Définissez workers pour choisir le nombre de composants à analyser en parallèle. La valeur par défaut est quatre.

Pour laisser Codex proposer des composants, passez auto: true à la place de components. Ajoutez planOnly: true pour enregistrer le plan dans components.json sans lancer d’analyse :

1
2
3
4
5
6
7
8
9
10import { runComponentScans } from "@openai/codex-security";

const plan = await runComponentScans({
  repository: repository,
  outputDir: outputDir,
  auto: true,
  planOnly: true,
});

console.log(plan.planPath);

Si l’analyse de certains composants a échoué, lisez le fichier JSON dont le chemin figure dans result.retryPlanPath. Passez son tableau components à runComponentScans en indiquant un nouveau outputDir. Le rapport de cette nouvelle exécution couvre uniquement ces composants. Consultez les rapports des deux exécutions.

Exploitez les résultats d’analyse

ScanResult donne accès aux documents structurés, aux métadonnées de l’analyse et aux chemins des artefacts :

Pour exiger la même version du plugin lors d’une analyse ultérieure, passez expectedPluginVersion: result.pluginVersion. Le SDK refuse de lancer l’analyse si la version du plugin installé diffère.

Pour chaque constat, consultez le niveau de gravité et le premier emplacement dans le code source :

1
2
3
4
5
6
7
8
9
10for (const finding of result.findings.findings) {
  const location = finding.locations[0];
  if (location === undefined) continue;

  console.log(
    finding.severity.level,
    `${location.path}:${location.startLine}`,
    finding.title
  );
}

Les constats peuvent contenir les champs facultatifs codeEvidence, rootCause, validation, attackPath, remediationTests et preventiveControls.

Pour les constats à l’échelle du dépôt, confirmedInLatestScan distingue ceux observés lors de la dernière analyse des constats antérieurs encore ouverts :

1
2
3for (const finding of result.repositoryFindings ?? []) {
  console.log(finding.title, finding.confirmedInLatestScan);
}

Utilisez result.toJSON() pour sérialiser le manifeste, les constats, les exclusions consignées lors de l’examen, les chemins des artefacts et les métadonnées du tour.

Consultez les modèles de menace enregistrés

Vérifiez si threatModel et threatModelPath valent null avant de les utiliser. Vous pouvez exporter un modèle enregistré même si Codex Security n’a pas pu écrire le fichier Markdown correspondant. Utilisez le chemin renvoyé par l’export sans présumer du nom de fichier.

Exportez les artefacts enregistrés

Exportez les résultats enregistrés sans démarrer Codex, charger d’identifiants ni appeler de modèle. Cet exemple exporte un modèle de menace enregistré vers la sortie standard. Passez le chemin d’un répertoire existant de résultats d’analyse comme premier argument de ligne de commande :

1
2
3
4
5
6
7
8
9
10
11
12
13
14import { exportArtifact } from "@openai/codex-security";

const directory = process.argv[2];
if (!directory) {
  throw new Error(
    "Pass an existing scan results directory as the first argument."
  );
}

await exportArtifact({
  source: { directory },
  artifact: "threat-model",
  output: "-",
});

Pour sélectionner une analyse enregistrée à partir de son identifiant, utilisez plutôt source: { scanId: "SCAN_ID" }. Définissez output sur le chemin de destination pour enregistrer l’artefact dans un fichier.

Les modèles de menace s’exportent au format Markdown. L’export renvoie une erreur si aucun modèle de menace n’a été enregistré pour l’analyse. Pour les constats, spécifiez artifact: "findings" et choisissez format: "sarif" (format par défaut), "json", "csv" ou "servicenow-avit".

Le résultat contient le chemin de sortie path et, si vous exportez un modèle de menace dans un fichier, le champ provenance issu des mêmes résultats enregistrés. Ces deux champs valent null lorsque output: "-" dirige l’export vers la sortie standard. L’export nécessite Python 3.10 ou une version ultérieure.

Pour utiliser ServiceNow Manual AVIT Ingestion, spécifiez artifact: "findings" et format: "servicenow-avit". Préparez le modèle d’application et passez son chemin dans avitTemplate. Indiquez dans output le chemin du fichier CSV de destination, dans un emplacement privé en dehors du dépôt. Utilisez source.directory pour sélectionner le répertoire existant qui contient les résultats de l’analyse.

Validez un constat existant

Utilisez validate pour vérifier dans le code source un constat provenant d’un autre outil ou workflow. Cette méthode ne lance pas de nouvelle analyse et n’exécute ni l’application ni ses tests. Si vous avez besoin d’éléments observables à l’exécution, reproduisez le problème séparément.

1
2
3
4
5
6
7
8
9
10const validation = await security.validate({
  repositoryPath: repository,
  finding: {
    title: "Possible SQL injection",
    location: "src/index.js:1",
  },
});

console.log(validation.disposition);
console.log(validation.report);

Fournissez le constat sous forme de texte non vide ou d’objet JSON. S’il se trouve dans un fichier, lisez le fichier et passez son contenu.

Le champ disposition indique le statut du constat : reportable, suppressed, not_applicable ou deferred. Le texte Markdown de validation.report décrit les éléments à l’appui du constat et ceux qui manquent encore. Enregistrez cette chaîne si vous avez besoin d’un fichier de rapport.

Suivez ou annulez une analyse

Passez des fonctions de rappel dans ScanOptions pour suivre le démarrage de l’analyse, la progression des processus d’analyse et les tentatives de reconnexion :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27try {
  const result = await security.run(repository, {
    outputDir: outputDir,
    onScanStarted() {
      console.log("Scan started");
    },
    onProgress(progress) {
      console.log(progress.phase, progress.filesCompleted, progress.filesTotal);
    },
    onWorkerStatus(status) {
      console.log(status.kind, status);
    },
    onSessionEvent(session) {
      console.log(session.threadId, session.worker, session.event["type"]);
    },
    onReconnect(attempt, maxAttempts) {
      console.log(`Reconnect attempt ${attempt} of ${maxAttempts}`);
    },
    onObserverError(observer, error) {
      console.error(`${observer} failed`, error);
    },
  });

  console.log(result.reportPath);
} finally {
  await security.close();
}

Pour annuler une analyse, passez un AbortSignal provenant de votre contrôleur de requêtes ou de tâches. Si l’analyse est toujours en cours après 30 minutes, cet exemple l’interrompt et affiche le chemin du répertoire contenant les éventuelles sorties enregistrées :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import { ScanInterruptedError } from "@openai/codex-security";

try {
  await security.run(repository, {
    outputDir: outputDir,
    signal: AbortSignal.timeout(30 * 60 * 1000),
  });
} catch (error) {
  if (error instanceof ScanInterruptedError) {
    console.error(error.scanDir);
  } else {
    throw error;
  }
} finally {
  await security.close();
}

Une analyse interrompue peut laisser des résultats partiels dans scanDir. Conservez ce répertoire si vous devez examiner ces résultats.

Les applications qui affichent la progression des préparatifs de l’analyse peuvent également utiliser les fonctions de rappel du cycle de vie proposées par ScanOptions :

Le statut de Trusted Access peut être granted, not_granted ou unknown. Si l’accès n’est pas accordé ou si son statut est inconnu, onWarning est également appelée.

onSessionEvent reçoit les événements sans masquage des données sensibles. Ils peuvent contenir du code source ou des identifiants. Filtrez-les avant de les envoyer vers des journaux partagés ou d’autres services.

Configurez l’environnement d’exécution et les identifiants

Fournissez une configuration d’exécution si vous avez besoin d’un plugin, d’un interpréteur ou d’un paramètre Codex particulier. Choisissez un modèle auquel votre compte a accès :

1
2
3
4
5
6
7
8const security = new CodexSecurity({
  // To override the bundled plugin, add pluginPath: "/path/to/plugin".
  pythonPath: "python3",
  codexOverrides: {
    model: "gpt-6.1-sol",
    model_reasoning_effort: "medium",
  },
});

Pour remplacer le plugin fourni avec le SDK, indiquez dans pluginPath le chemin d’un répertoire de plugin ou d’une archive ZIP. pythonPath sélectionne l’interpréteur du plugin. codexOverrides intègre les valeurs prises en charge à la configuration isolée de Codex. Pour utiliser Amazon Bedrock, définissez model_provider et model dans codexOverrides.

Définissez codexOverrides.approval_policy sur "never" pour refuser les demandes de permission. Dans les autres cas, les analyses utilisent la révision automatique des demandes d’approbation. Consultez les permissions des analyses locales pour en savoir plus sur l’accès au système de fichiers et les identifiants hérités.

Pour OpenRouter ou Fireworks, fournissez également la clé API correspondante et la configuration complète du fournisseur dans codexOverrides. Définissez OPENROUTER_API_KEY et passez l’identifiant d’un modèle OpenRouter disponible à cette fonction TypeScript :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16function createOpenRouterClient(model: string) {
  return new CodexSecurity({
    codexOverrides: {
      model,
      model_provider: "openrouter",
      model_providers: {
        openrouter: {
          name: "OpenRouter",
          base_url: "https://openrouter.ai/api/v1",
          env_key: "OPENROUTER_API_KEY",
          wire_api: "responses",
        },
      },
    },
  });
}

Pour Fireworks, remplacez les deux clés openrouter par fireworks, définissez name sur Fireworks AI et env_key sur FIREWORKS_API_KEY, utilisez https://api.fireworks.ai/inference/v1 comme base_url et choisissez un modèle Fireworks.

Le client propose également les méthodes d’authentification suivantes :

L’objet de connexion fournit waitForInstructions, authUrl, verificationUrl, userCode, wait et cancel pour que l’application puisse présenter les étapes de connexion choisies et mener la procédure à son terme. Le SDK peut réutiliser une connexion Codex enregistrée dans un fichier. Utilisez des clés API pour la CI et les automatisations côté serveur.

Si une clé API et une connexion enregistrée sont toutes deux disponibles, le SDK utilise la clé API par défaut. Pour utiliser votre connexion ChatGPT à la place, sélectionnez-la pour l’analyse :

1
2
3const result = await security.run(repository, {
  auth: "chatgpt",
});

Spécifiez auth: "api-key" pour exiger une clé API fournie par une variable d’environnement. preflight accepte la même option auth.

Gérez les erreurs d’analyse

Interceptez l’exception dont la classe exportée correspond à l’action que votre application peut entreprendre :

Poursuivez avec le guide de démarrage rapide de la CLI, le guide de la CI ou la référence de la CLI.