SDK TypeScript Codex Security

Utilisez le SDK TypeScript Codex Security pour exécuter des analyses de sécurité sur des dépôts et des modifications de code depuis votre application ou outil de développement. Le SDK renvoie des résultats typés, des détails sur la couverture et les chemins des artefacts d’analyse. Pour les analyses longues, il prend en charge les vérifications préalables, les limites de coût, les rappels de progression et l’annulation.

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

Configurer le SDK

Installez le SDK :

npm install @openai/codex-security

Avant de démarrer une analyse, définissez OPENAI_API_KEY ou CODEX_API_KEY, utilisez une connexion Codex existante enregistrée dans un fichier, ou configurez un autre fournisseur. Amazon Bedrock utilise des identifiants AWS ; OpenRouter et Fireworks utilisent des API keys et une configuration propres à chaque fournisseur.

Pour obtenir les meilleurs résultats, utilisez un compte vérifié pour Trusted Access for Cyber. La connexion ou la fourniture d’une API key ne confère pas Trusted Access.

Exécuter une analyse

Le SDK s’exécute avec vos autorisations locales du système d’exploitation 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 avant de commencer. Consultez Autorisations des analyses locales.

Enregistrez cet exemple sous scan.mjs. Remplacez les chemins, lancez une analyse standard du dépôt et fermez le client une fois le travail terminé. Fournissez outputDir pour choisir un répertoire privé de résultats situé en dehors du worktree Git qui englobe le dépôt.

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

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
  });

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

Exécutez-le avec Node.js :

node scan.mjs

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 de preuve. Ce nombre varie selon le dépôt et l’analyse ; ne vous servez donc pas d’un nombre attendu pour vérifier que l’intégration fonctionne.

run valide les artefacts enregistrés et renvoie un ScanResult lorsque result.manifest.scan.status vaut "completed". Consultez result.coverage pour connaître les périmètres examinés, les exclusions et les travaux différés. Une analyse terminée peut encore présenter des lacunes de couverture. Des défaillances liées à l’exécution, aux entrées ou à l’intégrité des résultats peuvent déclencher une erreur.

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

Vérifier les entrées avec une vérification préalable

Utilisez preflight pour vérifier un dépôt, une cible, un mode, des documents de base de connaissances, un emplacement de sortie et la configuration Codex avant de démarrer une analyse :

const plan = await security.preflight("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
  knowledgeBasePaths: ["/path/to/architecture.md"],
  outputDir: "/path/outside/repository/results",
});

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

La vérification préalable contrôle les entrées locales sans démarrer Codex, charger les identifiants ni vérifier la disponibilité de Python et du plugin. Sa réussite ne prouve pas que l’analyse pourra s’authentifier ou démarrer.

Pour prévisualiser l’archivage d’un répertoire de résultats existant, définissez archiveExisting: true :

const plan = await security.preflight("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  archiveExisting: true,
});

console.log(plan.archiveDir);

La valeur archiveDir renvoyée prévisualise le nom de l’archive. Le chemin final peut être différent, car run génère sa propre destination unique. Récupérez le chemin réel de l’archive avec onOutputArchived :

await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  archiveExisting: true,
  onOutputArchived(archiveDir) {
    console.log("Archived results:", archiveDir);
  },
});

L’analyse archive les résultats antérieurs et démarre avec un répertoire de sortie vide.

Choisir une cible d’analyse

Le SDK prend en charge les cibles de type dépôt, chemin, diff validé et worktree. La cible par défaut est le dépôt complet.

Analyser des chemins sélectionnés

Transmettez un tableau de chemins au sein du dépôt :

const result = await security.run("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
});

Les chemins peuvent désigner des fichiers ou des répertoires. Le SDK résout chaque chemin dans le dépôt et supprime les doublons.

Analyser les modifications validées

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

const target = DiffTarget.refs({
  base: "origin/main",
  head: "HEAD",
});

const result = await security.run("/path/to/repository", { target });

La tête utilise HEAD par défaut. Pour les cibles de type diff, l’argument du dépôt doit être la racine du worktree Git.

Analyser le worktree

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

const target = DiffTarget.workingTree({ base: "HEAD" });
const result = await security.run("/path/to/repository", { target });

La base utilise HEAD par défaut. Récupérez les révisions sélectionnées avant de démarrer une analyse de diff ou de worktree.

Sélectionner le mode approfondi

Définissez mode: "deep" pour une analyse de dépôt ou de chemins nécessitant un examen plus large :

const result = await security.run("/path/to/repository", {
  target: ["services/billing"],
  mode: "deep",
  workers: 2,
  subagents: 0,
  stopAfterNoNew: 3,
  maxDiscoveryRuns: 10,
  maxTimeHours: 1.5,
});

Le mode approfondi prend en charge les cibles de type dépôt et chemin. Utilisez le mode standard pour les analyses de diff et de worktree. Les paramètres facultatifs contrôlent les workers indépendants d’analyse standard exécutés en parallèle, les sous-agents par worker, le nombre d’analyses de worker consécutives terminées sans nouveau résultat, ainsi que le nombre total et la durée des exécutions de workers. Ils nécessitent mode: "deep".

maxTimeHours vaut par défaut 96 et accepte un nombre positif jusqu’à 96, y compris des fractions d’heure. À l’échéance, Codex Security arrête les workers qui n’ont pas terminé, conserve les résultats des analyses terminées et les regroupe dans le rapport final. Consultez result.coverage pour connaître les travaux différés et les questions en suspens.

Ajouter une base de connaissances de sécurité

Transmettez des documents d’architecture, des modèles de menaces ou des politiques de sécurité via knowledgeBasePaths :

const result = await security.run("/path/to/repository", {
  knowledgeBasePaths: [
    "/path/to/architecture.md",
    "/path/to/security-policies",
  ],
});

Le SDK accepte des fichiers ou des répertoires et parcourt les répertoires de manière récursive. Les formats de document pris en charge sont .md, .markdown, .txt, .pdf et .docx. Le SDK rejette les chemins d’entrée liés, ignore les entrées de répertoire liées et conserve le contenu extrait des documents en dehors des résultats d’analyse enregistrés.

Ajouter des instructions d’analyse et de suivi

Utilisez scanPrompt pour cibler l’analyse et postScanPrompt pour demander un suivi :

const result = await security.run("/path/to/repository", {
  scanPrompt: "Focus on tenant isolation and authorization checks.",
  postScanPrompt: "Write confirmed findings to post-scan-summary.md.",
});

Si le suivi échoue, le SDK conserve l’analyse terminée et signale l’erreur via onWarning. Il restaure tous les artefacts d’analyse terminée que le suivi a modifiés.

Définir un budget d’analyse

Définissez maxCostUsd pour arrêter une analyse lorsque son coût de modèle estimé dépasse une limite. Utilisez onCost pour suivre le coût pendant l’analyse :

const result = await security.run("/path/to/repository", {
  maxCostUsd: 5,
  onCost(cost) {
    console.log(cost.estimatedUsd);
  },
});

console.log(result.cost?.estimatedUsd);

La limite repose sur une estimation des dépenses et ne constitue pas un plafond strict ; les requêtes déjà en cours peuvent donc se terminer légèrement au-delà. Si une analyse approfondie atteint la limite après que Codex Security a regroupé les résultats des workers ayant terminé, run peut renvoyer un résultat dont manifest.scan.status vaut "completed" et signaler l’avertissement budgétaire via onWarning. Consultez result.coverage pour connaître les travaux restés inachevés.

Si l’analyse ne peut pas produire de résultat terminé valide, run lève ScanCostLimitExceededError et conserve toute sortie disponible.

Utiliser les résultats d’analyse

ScanResult expose les documents structurés, les métadonnées d’analyse et les chemins des artefacts :

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

Utilisez directement les résultats structurés et la couverture :

for (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
  );
}

for (const deferred of result.coverage.deferred) {
  console.log(deferred.id, deferred.reason);
}

Les résultats peuvent inclure les champs facultatifs codeEvidence, rootCause, validation, attackPath, remediationTests et preventiveControls.

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

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

Les nouveaux résultats ne comportent pas coverage.completeness. Utilisez manifest.scan.status pour connaître l’état d’exécution et consultez les périmètres différés, les exclusions et les questions en suspens dans coverage pour comprendre ce que l’analyse a examiné.

result.toJSON() renvoie le manifeste, les résultats du dépôt et de l’analyse actuelle, la couverture, les identifiants d’analyse et de thread, reportPath, artifactsDir, sarifPath, le coût et les métadonnées du tour dans un seul objet prêt pour JSON.

Suivre ou annuler une analyse

Transmettez des rappels ScanOptions pour signaler le démarrage de l’analyse, la progression des workers et les nouvelles tentatives de connexion :

const result = await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  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);

Fournissez un AbortSignal depuis le contrôleur de votre requête ou de votre job pour annuler une analyse. Si l’analyse est toujours en cours après 30 minutes, cet exemple l’interrompt et affiche le répertoire contenant toute sortie enregistrée :

try {
  await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
    signal: AbortSignal.timeout(30 * 60 * 1000),
  });
} catch (error) {
  if (error instanceof ScanInterruptedError) {
    console.error(error.scanDir);
  } else {
    throw error;
  }
}

Une analyse interrompue peut laisser une sortie partielle dans scanDir. Conservez ce répertoire si le résultat doit être examiné.

Les applications qui affichent la progression de la configuration de l’analyse peuvent également utiliser les rappels de cycle de vie ScanOptions :

L’état de Trusted Access est granted, not_granted ou unknown. Un accès manquant ou inconnu déclenche également onWarning.

onSessionEvent reçoit des événements qui ne sont pas expurgés et peuvent contenir du code source ou des identifiants. Filtrez-les avant de les envoyer vers des journaux partagés ou d’autres services.

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

Transmettez la configuration d’exécution lorsque vous avez besoin d’un plugin, d’un interpréteur ou d’un paramètre Codex spécifique. Choisissez un modèle auquel vos identifiants donnent accès. Si vous vous connectez avec ChatGPT, vérifiez la disponibilité de GPT-6.1 Sol avant d’utiliser cet exemple :

const security = new CodexSecurity({
  pluginPath: "/path/to/codex-security-plugin",
  pythonPath: "/path/to/python",
  codexOverrides: {
    model: "gpt-6.1-sol",
    model_reasoning_effort: "medium",
  },
});

pluginPath accepte un répertoire de plugin ou un fichier ZIP. pythonPath sélectionne l’interpréteur du plugin. codexOverrides fusionne les valeurs prises en charge dans la configuration Codex isolée. Par défaut, les analyses utilisent gpt-5.6-sol avec un effort de raisonnement extra-high. Définissez model et model_reasoning_effort dans codexOverrides pour utiliser un autre modèle ou effort de raisonnement. Pour utiliser Amazon Bedrock, définissez model_provider et model dans codexOverrides.

codexOverrides ne peut pas restreindre l’accès de l’analyse au système de fichiers ni modifier sa politique d’approbation. Consultez Autorisations des analyses locales.

Pour OpenRouter ou Fireworks, fournissez également l’API key correspondante et une configuration complète du fournisseur dans codexOverrides. Par exemple, définissez OPENROUTER_API_KEY et configurez OpenRouter :

const security = new CodexSecurity({
  codexOverrides: {
    model: "anthropic/claude-sonnet-4.5",
    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, définissez env_key sur FIREWORKS_API_KEY, utilisez https://api.fireworks.ai/inference/v1 comme base_url et sélectionnez un modèle Fireworks.

Le client expose également les méthodes d’authentification prises en charge :

Un descripteur de connexion fournit waitForInstructions, authUrl, verificationUrl, userCode, wait et cancel afin qu’une application puisse présenter et mener à bien le parcours de connexion choisi. Le SDK peut réutiliser une connexion Codex enregistrée dans un fichier. Utilisez des API keys pour la CI et l’automatisation côté serveur.

Lorsqu’une API key et une connexion enregistrée sont toutes deux disponibles, le SDK utilise l’API key par défaut. Pour utiliser plutôt votre connexion ChatGPT, sélectionnez-la pour l’analyse :

const result = await security.run("/path/to/repository", {
  auth: "chatgpt",
});

Définissez auth: "api-key" pour exiger une API key d’environnement. preflight accepte la même option auth.

Gérer les erreurs d’analyse

Interceptez la classe d’erreur exportée correspondant à l’action que votre application peut entreprendre :

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