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 22 (22.13.0 ou version ultérieure), 24 ou 26. L’analyse nécessite également Python 3.10 ou version ultérieure. Python 3.10 nécessite aussi le package 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 de meilleurs résultats, utilisez un compte vérifié pour Trusted Access for Cyber. La connexion ou la fourniture d’une API key n’accorde pas Trusted Access.

Exécuter une analyse

Analysez uniquement les dépôts auxquels vous faites confiance et que vous êtes autorisé à évaluer. Le SDK s’exécute avec les autorisations locales de votre système d’exploitation et ne s’interrompt jamais 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 commencer. Consultez Autorisations des analyses locales.

Créez un client CodexSecurity, exécutez une analyse standard du dépôt et fermez le client une fois le travail terminé. Transmettez outputDir pour choisir un répertoire de résultats privé situé hors du worktree Git englobant.

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 ; choisissez donc des autorisations et des politiques de conservation appropriées.

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.coverage.completeness);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}

run démarre l’analyse, attend qu’elle se termine, valide les artefacts scellés et renvoie un ScanResult. close libère l’environnement d’exécution isolé et permet des appels répétés.

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 ne modifie ni l’environnement d’exécution Codex ni les identifiants. Elle laisse également la détection du plugin et de Python à l’analyse elle-même. Elle est donc utile pour vérifier les entrées utilisateur avant une opération longue ou nécessitant des identifiants.

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 utilise 96 par défaut et accepte un nombre positif allant jusqu’à 96, y compris un nombre d’heures fractionnaire. À l’échéance, Codex Security arrête les workers non terminés, conserve les résultats des analyses terminées et les agrège dans le rapport final. Examinez result.coverage.completeness avant de considérer une analyse limitée dans le temps comme une preuve de couverture complète.

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 estime les dépenses, mais ne constitue pas un plafond strict ; les requêtes déjà en cours peuvent donc se terminer légèrement au-dessus. Si une analyse approfondie atteint la limite après l’agrégation par Codex Security des résultats terminés des workers, run renvoie un résultat où coverage.completeness est défini sur "partial" et signale l’avertissement de budget via onWarning.

Si l’analyse ne peut pas produire un résultat partiel terminé, 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);
}

L’exhaustivité de la couverture est complete, partial ou unknown. Examinez les surfaces différées, les exclusions et les questions ouvertes avant d’utiliser une analyse comme preuve pour une décision de sécurité.

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);

Transmettez un AbortSignal lorsque l’annulation provient d’une requête, d’un contrôleur de tâche ou d’un délai d’expiration :

const controller = new AbortController();

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

  controller.abort();
  await scan;
} 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 une configuration d’exécution lorsqu’un plugin, un interpréteur ou un paramètre Codex précis est nécessaire :

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

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 handle de connexion fournit waitForInstructions, authUrl, verificationUrl, userCode, wait et cancel afin qu’une application puisse présenter et terminer le flux de connexion sélectionné. Le SDK peut réutiliser une connexion Codex enregistrée dans un fichier. Les API keys conviennent bien à 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.