Codex Security TypeScript SDK

Verwenden Sie das Codex Security TypeScript SDK, um Sicherheits-Scans für Repositories und Codeänderungen aus Ihrer Anwendung oder Ihrem Entwicklertool heraus auszuführen. Das SDK gibt typisierte Befunde, Abdeckungsdetails und Pfade zu Scan-Artefakten zurück. Für längere Scans unterstützt es Vorabprüfungen, Kostenlimits, Fortschritts-Callbacks und Abbruchvorgänge.

Das SDK verwendet ECMAScript-Module (ESM) und läuft serverseitig mit Node.js 24 oder 26 oder mit Node.js 22 ab Version 22.13.0. Für Scans ist außerdem Python 3.10 oder höher erforderlich. Python 3.10 erfordert zusätzlich das Paket tomli.

SDK einrichten

Installieren Sie das SDK:

npm install @openai/codex-security

Legen Sie vor dem Start eines Scans OPENAI_API_KEY oder CODEX_API_KEY fest, verwenden Sie eine vorhandene dateibasierte Codex-Anmeldung oder konfigurieren Sie einen anderen Anbieter. Amazon Bedrock verwendet AWS- Anmeldedaten; OpenRouter und Fireworks verwenden anbieterspezifische API keys und Konfigurationen.

Für optimale Ergebnisse verwenden Sie ein Konto, das für Trusted Access for Cyber verifiziert ist. Die Anmeldung oder die Angabe eines API key gewährt keinen Trusted Access.

Scan ausführen

Das SDK wird mit Ihren lokalen Betriebssystemberechtigungen ausgeführt und wartet nicht auf eine Genehmigung. Scan-Prozesse können Ihre Umgebung übernehmen. Entfernen Sie daher nicht benötigte Zugangsdaten, bevor Sie beginnen. Siehe Berechtigungen für lokale Scans.

Speichern Sie dieses Beispiel als scan.mjs. Ersetzen Sie die Pfade, führen Sie einen Standard-Repository-Scan aus und schließen Sie den Client nach Abschluss der Arbeit. Übergeben Sie outputDir, um ein privates Ergebnisverzeichnis außerhalb des umgebenden Git-Worktrees auszuwählen.

Wenn Sie outputDir weglassen, speichert Codex Security die Ergebnisse in seinem eigenen persistenten Zustandsverzeichnis. Ergebnisse können Quellcodeauszüge und Details zu Sicherheitslücken enthalten. Legen Sie fest, wer sie lesen darf und wie lange sie aufbewahrt werden.

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

Führen Sie das Beispiel mit Node.js aus:

node scan.mjs

Das Beispiel gibt den Berichtspfad, den Scan-Status und die Anzahl der Befunde aus. Öffnen Sie den Bericht, um die Nachweise zu prüfen. Die Anzahl variiert je nach Repository und Scan. Verwenden Sie daher keine erwartete Anzahl, um die Funktionsfähigkeit der Integration zu prüfen.

run validiert die gespeicherten Artefakte und gibt ein ScanResult zurück, wenn result.manifest.scan.status den Wert "completed" hat. Prüfen Sie result.coverage auf überprüfte Bereiche, Ausschlüsse und zurückgestellte Arbeiten. Ein abgeschlossener Scan kann weiterhin Abdeckungslücken aufweisen. Laufzeit-, Eingabe- oder Ergebnisintegritätsfehler können einen Fehler auslösen.

Verwenden Sie in späteren Beispielen den geöffneten Client security erneut und belassen Sie close() in finally, um die Laufzeitumgebung freizugeben. Fügen Sie zusätzliche Importe am Anfang von scan.mjs hinzu.

Eingaben mit einer Vorabprüfung prüfen

Verwenden Sie preflight, um Repository, Ziel, Modus, Wissensbasisdokumente, Ausgabeort und Codex-Konfiguration vor dem Start eines Scans zu prüfen:

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

Preflight prüft lokale Eingaben, ohne Codex zu starten, Zugangsdaten zu laden oder die Verfügbarkeit von Python und Plugins zu prüfen. Ein erfolgreicher Preflight belegt nicht, dass sich der Scan authentifizieren lässt oder gestartet werden kann.

Um die Archivierung für ein vorhandenes Ergebnisverzeichnis in der Vorschau anzuzeigen, setzen Sie archiveExisting: true:

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

console.log(plan.archiveDir);

Das zurückgegebene archiveDir zeigt eine Vorschau der Archivbenennung. Der endgültige Pfad kann abweichen, da run ein eigenes eindeutiges Ziel erzeugt. Erfassen Sie den tatsächlichen Archivpfad mit onOutputArchived:

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

Der Scan archiviert die früheren Ergebnisse und beginnt mit einem leeren Ausgabeverzeichnis.

Scan-Ziel auswählen

Das SDK unterstützt Repository-, Pfad-, Commit-Diff- und Working-Tree-Ziele. Standardziel ist das vollständige Repository.

Ausgewählte Pfade scannen

Übergeben Sie ein Array von Pfaden innerhalb des Repositories:

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

Pfade können Dateien oder Verzeichnisse bezeichnen. Das SDK löst jeden Pfad innerhalb des Repositories auf und entfernt Duplikate.

Committete Änderungen scannen

Verwenden Sie DiffTarget.refs, um committete Änderungen zwischen zwei lokal verfügbaren Git-Revisionen zu scannen:

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

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

Der Head ist standardmäßig HEAD. Bei Diff-Zielen muss das Repository-Argument das Stammverzeichnis des Git-Worktrees sein.

Working Tree scannen

Verwenden Sie DiffTarget.workingTree, um vorgemerkte und nicht vorgemerkte Änderungen gegenüber einer Basisrevision zu scannen:

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

Die Basis ist standardmäßig HEAD. Rufen Sie die ausgewählten Revisionen ab, bevor Sie einen Diff- oder Working-Tree-Scan starten.

Tiefenmodus auswählen

Legen Sie mode: "deep" für einen Repository- oder Pfad-Scan fest, der eine umfassendere Prüfung erfordert:

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

Der Tiefenmodus unterstützt Repository- und Pfadziele. Verwenden Sie den Standardmodus für Diff- und Working-Tree-Scans. Die optionalen Einstellungen steuern gleichzeitig ausgeführte, unabhängige Standard-Scan-Worker, Subagenten pro Worker, aufeinanderfolgende abgeschlossene Worker-Scans ohne neue Befunde sowie die Gesamtzahl und Dauer der Worker-Läufe. Sie erfordern mode: "deep".

maxTimeHours hat den Standardwert 96 und akzeptiert eine positive Zahl bis 96, auch Bruchteile von Stunden. Bei Erreichen des Zeitlimits stoppt Codex Security noch laufende Worker, behält abgeschlossene Scan-Ergebnisse bei und führt sie im Abschlussbericht zusammen. Prüfen Sie result.coverage auf zurückgestellte Arbeiten und offene Fragen.

Sicherheitswissensbasis hinzufügen

Übergeben Sie Architekturdokumente, Bedrohungsmodelle oder Sicherheitsrichtlinien über knowledgeBasePaths:

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

Das SDK akzeptiert Dateien oder Verzeichnisse und durchsucht Verzeichnisse rekursiv. Unterstützte Dokumentformate sind .md, .markdown, .txt, .pdf und .docx. Das SDK weist verknüpfte Eingabepfade zurück, überspringt verknüpfte Verzeichniseinträge und hält extrahierte Dokumentinhalte von den gespeicherten Scan-Ergebnissen getrennt.

Scan- und Folgeanweisungen hinzufügen

Verwenden Sie scanPrompt, um den Scan zu fokussieren, und postScanPrompt, um eine Folgeprüfung anzufordern:

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.",
});

Wenn die Folgeprüfung fehlschlägt, behält das SDK den abgeschlossenen Scan bei und meldet den Fehler über onWarning. Es stellt alle abgeschlossenen Scan-Artefakte wieder her, die durch die Folgeprüfung geändert wurden.

Scan-Budget festlegen

Legen Sie maxCostUsd fest, um einen Scan zu stoppen, wenn seine geschätzten Modellkosten ein Limit überschreiten. Verwenden Sie onCost, um die Kosten während des Scans zu verfolgen:

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

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

Das Limit schätzt die Ausgaben, ist aber keine feste Obergrenze. Bereits laufende Anfragen können daher mit Kosten leicht oberhalb des Limits abgeschlossen werden. Wenn ein Deep-Scan das Limit erreicht, nachdem Codex Security die Ergebnisse abgeschlossener Worker zusammengeführt hat, kann run ein Ergebnis zurückgeben, bei dem manifest.scan.status auf "completed" gesetzt ist, und die Budgetwarnung über onWarning melden. Prüfen Sie result.coverage auf nicht abgeschlossene Arbeiten.

Wenn der Scan kein gültiges abgeschlossenes Ergebnis erzeugen kann, löst run ScanCostLimitExceededError aus und behält alle verfügbaren Ausgaben bei.

Mit Scan-Ergebnissen arbeiten

ScanResult stellt die strukturierten Dokumente, Scan-Metadaten und Artefaktpfade bereit:

Um dasselbe Plugin für einen späteren Scan vorauszusetzen, übergeben Sie expectedPluginVersion: result.pluginVersion. Das SDK weist den Scan zurück, wenn die installierte Plugin-Version abweicht.

Verwenden Sie die strukturierten Befunde und Abdeckungsdaten direkt:

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

Befunde können die optionalen Felder codeEvidence, rootCause, validation, attackPath, remediationTests und preventiveControls enthalten.

Bei repositoryweiten Befunden unterscheidet confirmedInLatestScan zwischen Befunden, die im neuesten Scan erkannt wurden, und früheren Befunden, die weiterhin offen sind:

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

Neue Ergebnisse enthalten kein coverage.completeness. Verwenden Sie manifest.scan.status für den Ausführungsstatus und prüfen Sie zurückgestellte Bereiche, Ausschlüsse und offene Fragen in coverage, um nachzuvollziehen, was der Scan überprüft hat.

result.toJSON() gibt Manifest, Repository- und aktuelle Scan-Befunde, Abdeckung, Scan- und Thread-IDs, reportPath, artifactsDir, sarifPath, Kosten und Turn-Metadaten in einem JSON-fähigen Objekt zurück.

Scan verfolgen oder abbrechen

Übergeben Sie ScanOptions-Callbacks, um Scan-Start, Worker-Fortschritt und Verbindungswiederholungen zu melden:

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

Übergeben Sie ein AbortSignal aus Ihrer Anfrage- oder Jobsteuerung, um einen Scan abzubrechen. Wenn der Scan nach 30 Minuten noch läuft, unterbricht ihn dieses Beispiel und gibt das Verzeichnis mit allen gespeicherten Ausgaben aus:

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

Ein unterbrochener Scan kann Teilausgaben in scanDir hinterlassen. Bewahren Sie dieses Verzeichnis auf, wenn das Ergebnis untersucht werden muss.

Anwendungen, die den Fortschritt der Scan-Einrichtung anzeigen, können außerdem die ScanOptions- Lebenszyklus-Callbacks verwenden:

Der Trusted-Access-Status ist granted, not_granted oder unknown. Fehlender oder unbekannter Zugriff löst ebenfalls onWarning aus.

onSessionEvent empfängt Ereignisse ohne Unkenntlichmachung vertraulicher Inhalte, die Quellcode oder Anmeldedaten enthalten können. Filtern Sie sie, bevor Sie sie an gemeinsame Protokolle oder andere Dienste senden.

Laufzeit und Anmeldedaten konfigurieren

Übergeben Sie eine Laufzeitkonfiguration, wenn Sie ein bestimmtes Plugin, einen bestimmten Interpreter oder eine Codex-Einstellung benötigen. Wählen Sie ein Modell, auf das Sie mit Ihren Anmeldedaten zugreifen können. Wenn Sie die ChatGPT-Anmeldung verwenden, prüfen Sie die Verfügbarkeit von GPT-6.1 Sol, bevor Sie dieses Beispiel verwenden:

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 akzeptiert ein Plugin-Verzeichnis oder eine ZIP-Datei. pythonPath wählt den Plugin-Interpreter aus. codexOverrides führt unterstützte Werte mit der isolierten Codex-Konfiguration zusammen. Scans verwenden standardmäßig gpt-5.6-sol mit besonders hohem Reasoning-Aufwand. Legen Sie model und model_reasoning_effort in codexOverrides fest, um ein anderes Modell oder einen anderen Reasoning-Aufwand zu verwenden. Um Amazon Bedrock zu verwenden, legen Sie model_provider und model in codexOverrides fest.

codexOverrides kann den Dateisystemzugriff des Scans nicht einschränken oder seine Genehmigungsrichtlinie ändern. Siehe Berechtigungen für lokale Scans.

Geben Sie für OpenRouter oder Fireworks außerdem den passenden API key und eine vollständige Anbieterkonfiguration in codexOverrides an. Legen Sie beispielsweise OPENROUTER_API_KEY fest und konfigurieren Sie 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",
      },
    },
  },
});

Ändern Sie für Fireworks beide openrouter-Schlüssel in fireworks, setzen Sie name auf Fireworks AI, setzen Sie env_key auf FIREWORKS_API_KEY, verwenden Sie https://api.fireworks.ai/inference/v1 als base_url und wählen Sie ein Fireworks- Modell aus.

Der Client stellt außerdem unterstützte Authentifizierungsmethoden bereit:

Ein Anmelde-Handle stellt waitForInstructions, authUrl, verificationUrl, userCode, wait und cancel bereit, damit eine Anwendung den ausgewählten Anmeldeablauf anzeigen und abschließen kann. Das SDK kann eine dateibasierte Codex-Anmeldung wiederverwenden. Verwenden Sie API keys für CI und serverseitige Automatisierung.

Wenn sowohl ein API key als auch eine gespeicherte Anmeldung verfügbar sind, verwendet das SDK standardmäßig den API key. Um stattdessen Ihre ChatGPT-Anmeldung zu verwenden, wählen Sie sie für den Scan aus:

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

Legen Sie auth: "api-key" fest, um einen API key aus der Umgebung vorauszusetzen. preflight akzeptiert dieselbe Option auth.

Scan-Fehler behandeln

Fangen Sie die exportierte Fehlerklasse ab, die der möglichen Reaktion Ihrer Anwendung entspricht:

Fahren Sie mit dem CLI-Schnellstart, dem CI-Leitfaden oder der CLI-Referenz fort.