Codex Security TypeScript SDK

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

Das SDK verwendet ECMAScript-Module (ESM) und wird serverseitig mit Node.js 22 oder höher ausgeführt. Für Scans ist außerdem Python 3.10 oder höher erforderlich.

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 Amazon Bedrock mit AWS-Anmeldedaten und ausdrücklichen Überschreibungen für model_provider und model.

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

Scan ausführen

Erstellen Sie einen Client vom Typ CodexSecurity, 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 weglassen, speichert Codex Security die Ergebnisse in seinem eigenen persistenten Zustandsverzeichnis. Ergebnisse können Quelltextausschnitte und Details zu Schwachstellen 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 den 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, Ausgabeort und Codex-Konfiguration zu prüfen, bevor Sie einen Scan starten:

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

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

Um die Archivierung für ein vorhandenes Ergebnisverzeichnis vorab 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 generiert. 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.

Scanziel auswählen

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

Ausgewählte Pfade scannen

Übergeben Sie ein Array von Pfaden innerhalb des Repositorys:

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 Repositorys 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 gestagte und nicht gestagte Änderungen gegenüber einer Base- Revision zu scannen:

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

Die Base 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 Pfadscan fest, der eine umfassendere Prüfung benötigt:

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

Der Tiefenmodus unterstützt Repository- und Pfadziele. Verwenden Sie für Diff- und Working-Tree-Scans den Standardmodus.

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 lehnt verlinkte Eingabepfade ab, überspringt verlinkte Verzeichniseinträge und hält extrahierte Dokumentinhalte von den gespeicherten Scanergebnissen getrennt.

Scanbudget 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 ist eine Schätzung und keine feste Ausgabenobergrenze. Bereits laufende Anfragen können darüber hinaus abgeschlossen werden. Wenn der Scan das Limit überschreitet, löst das SDK ScanCostLimitExceededError aus und bewahrt die verfügbaren Ergebnisse auf.

Mit Scanergebnissen arbeiten

ScanResult stellt die strukturierten Dokumente, Scanmetadaten und Artefakt- pfade bereit:

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

Die Vollständigkeit der Abdeckung 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, Befunde, Abdeckung, Scan- und Thread- IDs, reportPath, artifactsDir, sarifPath sowie Turn-Metadaten in einem JSON-kompatiblen Objekt zurück.

Scan verfolgen oder abbrechen

Übergeben Sie ScanOptions-Callbacks, um über Scanstart, Worker-Fortschritt und Verbindungswiederholungen zu berichten:

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

Übergeben Sie ein AbortSignal, wenn der Abbruch durch eine Anfrage, einen Job-Controller oder ein Zeitlimit ausgelöst wird:

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 eine Teilausgabe in scanDir hinterlassen. Bewahren Sie dieses Verzeichnis auf, wenn das Ergebnis untersucht werden muss.

Anwendungen, die den Einrichtungsfortschritt eines Scans anzeigen, können auch die Lebenszyklus-Callbacks ScanOptions verwenden:

Laufzeit und Anmeldedaten konfigurieren

Übergeben Sie eine Laufzeitkonfiguration, wenn Sie ein bestimmtes Plugin, einen Interpreter oder eine 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 ZIP. 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 extra-high reasoning effort. Legen Sie model und model_reasoning_effort in codexOverrides fest, um ein anderes Modell oder einen anderen reasoning effort zu verwenden. Um Amazon Bedrock zu verwenden, legen Sie model_provider und model in codexOverrides fest.

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

Scanfehler behandeln

Fangen Sie die exportierte Fehlerklasse ab, die der Aktion entspricht, die Ihre Anwendung ausführen kann:

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