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 wird serverseitig mit Node.js 22 (22.13.0 oder höher), 24 oder 26 ausgeführt. Für Scans ist außerdem Python 3.10 oder höher erforderlich. Python 3.10 benötigt 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.

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

Scan ausführen

Scannen Sie nur Repositories, denen Sie vertrauen und zu deren Prüfung Sie berechtigt sind. Das SDK wird mit den Berechtigungen Ihres lokalen Betriebssystems ausgeführt und hält nie für eine Genehmigung an. Scan-Prozesse können Ihre Umgebung übernehmen; entfernen Sie daher vor dem Start nicht benötigte Anmeldedaten. Siehe Berechtigungen für lokale Scans.

Erstellen Sie einen CodexSecurity-Client, führen Sie einen regulären 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 auslassen, speichert Codex Security die Ergebnisse in seinem eigenen persistenten Zustandsverzeichnis. Ergebnisse können Quelltextauszüge und Details zu Sicherheitslücken enthalten. Wählen Sie daher geeignete Berechtigungen und Aufbewahrungsrichtlinien.

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 startet den Scan, wartet auf dessen Abschluss, validiert die versiegelten Artefakte und gibt ein ScanResult zurück. close gibt die isolierte Laufzeit frei und unterstützt wiederholte Aufrufe.

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

Die Vorabprüfung lässt Codex-Laufzeit und Anmeldedaten unverändert. Auch die Plugin- und Python-Erkennung bleibt dem eigentlichen Scan vorbehalten. Dadurch eignet sich die Vorabprüfung zum Prüfen von Benutzereingaben vor einem lang laufenden Vorgang oder einem Vorgang mit Anmeldedaten.

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 Ausgabe- verzeichnis.

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 bereitgestellte und nicht bereitgestellte Änderungen gegenüber einer Basis- revision 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 ist standardmäßig 96 und akzeptiert eine positive Zahl bis 96, einschließlich Bruchteilen von Stunden. Bei Ablauf der Frist stoppt Codex Security nicht abgeschlossene Worker, behält abgeschlossene Scan-Ergebnisse bei und fasst sie im endgültigen Bericht zusammen. Prüfen Sie result.coverage.completeness, bevor Sie einen zeitlich begrenzten Scan als Nachweis einer vollständigen Abdeckung betrachten.

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 jedoch keine feste Obergrenze. Bereits laufende Anfragen können daher geringfügig darüber hinausgehen. Wenn ein Tiefenscan das Limit erreicht, nachdem Codex Security abgeschlossene Worker-Ergebnisse zusammengefasst hat, gibt run ein Ergebnis zurück, bei dem coverage.completeness auf "partial" gesetzt ist, und meldet die Budgetwarnung über onWarning.

Wenn der Scan kein abgeschlossenes Teilergebnis erzeugen kann, löst run ScanCostLimitExceededError aus und bewahrt jede verfügbare Ausgabe auf.

Mit Scan-Ergebnissen arbeiten

ScanResult stellt die strukturierten Dokumente, Scan-Metadaten und Artefakt- pfade 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);
}

Die Abdeckungsvollständigkeit ist complete, partial oder unknown. Prüfen Sie zurückgestellte Bereiche, Ausschlüsse und offene Fragen, bevor Sie einen Scan als Nachweis für eine Sicherheitsentscheidung verwenden.

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, wenn der Abbruch von einer Anfrage, einer Jobsteuerung oder einem Timeout ausgeht:

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

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 nicht redigierte Ereignisse, 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 bestimmte Codex-Einstellung benötigen:

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 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 Anmeldevorgang darstellen und abschließen kann. Das SDK kann eine dateibasierte Codex-Anmeldung wiederverwenden. API keys eignen sich gut 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.