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 votre outil de développement. Le SDK renvoie des constats 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 callbacks de progression et l’annulation.

Le SDK utilise les modules ECMAScript (ESM) et s’exécute côté serveur avec Node.js 22 ou une version ultérieure. L’analyse nécessite également Python 3.10 ou une version ultérieure.

Configurer 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 existante stockée dans un fichier, ou configurez Amazon Bedrock avec des identifiants AWS et des valeurs de remplacement explicites pour model_provider et model.

Pour obtenir de meilleurs résultats, utilisez un compte validé pour Trusted Access for Cyber. Se connecter ou fournir une API key n’accorde pas Trusted Access.

Exécuter une analyse

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é en dehors 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 contenir 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 lance l’analyse, attend sa fin, valide les artefacts scellés et renvoie un ScanResult. close libère le runtime isolé et prend en charge les appels répétés.

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

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

const plan = await security.preflight("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
  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 le runtime Codex ni les identifiants. Elle laisse également la détection du plugin et de Python à l’analyse elle-même. La vérification préalable est ainsi 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érences validées et worktree. La cible par défaut est le dépôt complet.

Analyser les chemins sélectionnés

Transmettez un tableau de chemins à l’intérieur 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 à l’intérieur du 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 est définie par défaut sur HEAD. Pour les cibles de différences, l’argument du dépôt doit correspondre à 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 est définie par défaut sur HEAD. Récupérez les révisions sélectionnées avant de lancer une analyse de différences ou du worktree.

Sélectionner le mode approfondi

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

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

Le mode approfondi prend en charge les cibles de type dépôt et chemin. Utilisez le mode standard pour les analyses de différences et du worktree.

Ajouter une base de connaissances sur la sécurité

Transmettez des documents d’architecture, des modèles de menace 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 les fichiers ou les 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.

Définir un budget d’analyse

Définissez maxCostUsd pour arrêter une analyse lorsque son coût estimé de modèle 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 est une estimation et non un plafond de dépenses strict. Les requêtes déjà en cours peuvent se terminer au-delà de celle-ci. Si l’analyse dépasse la limite, le SDK lève ScanCostLimitExceededError et conserve les résultats disponibles.

Exploiter les résultats d’analyse

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

Utilisez directement les constats 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);
}

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 élément probant pour une décision de sécurité.

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

Suivre ou annuler une analyse

Transmettez des callbacks 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");
  },
  onWorkerStatus(status) {
    console.log(status.kind, status);
  },
  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 job 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 callbacks de cycle de vie ScanOptions :

Configurer le runtime et les identifiants

Transmettez la configuration du runtime lorsque vous avez besoin d’un plugin, d’un interpréteur ou d’un paramètre Codex spécifique :

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. Les analyses utilisent gpt-5.6-sol avec un effort de raisonnement extra-high par défaut. Définissez model et model_reasoning_effort dans codexOverrides pour utiliser un autre modèle ou un autre effort de raisonnement. Pour utiliser Amazon Bedrock, définissez model_provider et model dans codexOverrides.

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 mener à bien le flux de connexion sélectionné. Le SDK peut réutiliser une connexion Codex stockée dans un fichier. Les API keys conviennent bien à 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 à la place 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 effectuer :

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