Mit dem TypeScript-SDK für Codex Security kannst du aus deiner Anwendung oder deinem Entwicklungstool heraus Repositories und Codeänderungen auf Sicherheitsprobleme prüfen. Das SDK liefert typisierte Befunde, das Scan-Manifest und die Pfade zu den gespeicherten Berichten.
Das SDK verwendet ECMAScript-Module (ESM) und läuft serverseitig mit Node.js 24 oder 26 sowie mit Node.js 22 ab Version 22.13.0. Für Scans brauchst du außerdem Python 3.10 oder höher. Für Python 3.10 ist zusätzlich das Paket tomli erforderlich.
Informationen zu Coding-Agenten für allgemeine Aufgaben findest du im Leitfaden zum Codex SDK. Für Workflows im Terminal und in CI siehe den Schnelleinstieg in die CLI von Codex Security.
SDK einrichten
Installiere das SDK:
npm install @openai/codex-security
Bevor du einen Scan startest, setze OPENAI_API_KEY oder CODEX_API_KEY, verwende eine bereits in einer Datei gespeicherte Codex-Anmeldung oder konfiguriere einen anderen Anbieter. Amazon Bedrock verwendet AWS-Anmeldedaten. OpenRouter und Fireworks benötigen jeweils eigene API-Schlüssel und eine anbieterspezifische Konfiguration.
Für bestimmte Anfragen zur Cybersicherheit und geschützte Befunde benötigt dein ChatGPT-Konto oder deine API-Organisation Trusted Access for Cyber.
Scan ausführen
Das SDK läuft mit deinen lokalen Betriebssystemberechtigungen und wartet nicht auf eine Genehmigung. Scan-Prozesse können deine Umgebungsvariablen erben. Entferne deshalb vor dem Start alle Anmeldedaten, die der Scan nicht benötigt. Siehe Berechtigungen für lokale Scans.
Speichere dieses Beispiel als scan.mjs. Übergib die Pfade zum Repository und zum Ergebnisverzeichnis als Befehlszeilenargumente. Führe einen Standardscan des Repositorys aus und schließe anschließend den Client. Gib mit outputDir ein privates Ergebnisverzeichnis außerhalb des umgebenden Git-Worktrees an.
Wenn du outputDir weglässt, speichert Codex Security die Ergebnisse im eigenen persistenten Zustandsverzeichnis. Die Ergebnisse können Quellcodeauszüge und Details zu Schwachstellen enthalten. Lege fest, wer sie lesen darf und wie lange sie aufbewahrt werden.
import { CodexSecurity } from "@openai/codex-security";
const [repository, outputDir] = process.argv.slice(2);
if (!repository || !outputDir) {
throw new Error("Usage: node scan.mjs <repository> <results-directory>");
}
const security = new CodexSecurity();
try {
const result = await security.run(repository, {
outputDir,
});
console.log(result.reportPath);
console.log(result.manifest.scan.status);
console.log(result.findings.findings.length);
} finally {
await security.close();
}Führe das Beispiel mit Node.js aus:
node scan.mjs /path/to/repository /path/outside/repository/results
Das Beispiel gibt den Berichtspfad, den Scan-Status und die Anzahl der Befunde aus. Öffne den Bericht, um die Belege zu prüfen.
run validiert die gespeicherten Artefakte und gibt ein ScanResult zurück, wenn result.manifest.scan.status den Wert "completed" hat. In result.manifest.scan.scope findest du das angeforderte Ziel und in result.manifest.scan.warnings etwaige Warnungen. Aus dem Abschlussstatus allein geht nicht hervor, welche Dateien geprüft wurden. Probleme mit der Laufzeitumgebung, den Eingaben oder der Integrität der Ergebnisse können einen Fehler auslösen.
Verwende in den folgenden Beispielen den geöffneten Client security weiter. Lass den Aufruf close() im finally-Block, damit die Laufzeitumgebung freigegeben wird. Ergänze weitere Imports am Anfang von scan.mjs.
Eingaben vorab prüfen
Prüfe mit preflight vor dem Scan das Repository, das Ziel, den Modus, die Dokumente der Wissensbasis, den Ausgabepfad und die Codex-Konfiguration. Dieses Beispiel liest security.md aus dem Stammverzeichnis des Repositorys:
import { join } from "node:path";
const knowledgeBase = join(repository, "security.md");
const plan = await security.preflight(repository, {
target: ["services/billing", "packages/auth"],
knowledgeBasePaths: [knowledgeBase],
outputDir: outputDir,
});
console.log(plan.repository);
console.log(plan.target.kind);
console.log(plan.mode);
console.log(plan.outputDir);Die Vorabprüfung kontrolliert lokale Eingaben, ohne Codex zu starten, Anmeldedaten zu laden oder die Verfügbarkeit von Python und des Plugins zu prüfen. Auch nach erfolgreicher Vorabprüfung können die Authentifizierung oder der Scan-Start fehlschlagen.
Um vorab zu sehen, wie ein vorhandenes Ergebnisverzeichnis archiviert wird, setze archiveExisting: true:
const plan = await security.preflight(repository, {
outputDir: outputDir,
archiveExisting: true,
});
console.log(plan.archiveDir);Der Rückgabewert archiveDir zeigt, wie das Archiv benannt wird. Der endgültige Pfad kann abweichen, da run einen eigenen eindeutigen Zielpfad erzeugt. Erfasse den tatsächlichen Archivpfad mit onOutputArchived:
try {
await security.run(repository, {
outputDir: outputDir,
archiveExisting: true,
onOutputArchived(archiveDir) {
console.log("Archived results:", archiveDir);
},
});
} finally {
await security.close();
}Der Scan archiviert die bisherigen Ergebnisse und startet mit einem leeren Ausgabeverzeichnis.
Scan-Ziel auswählen
Als Ziel unterstützt das SDK ein Repository, einzelne Pfade, Unterschiede zwischen Commits und Änderungen im Arbeitsverzeichnis. Standardmäßig scannt es das gesamte Repository.
Ausgewählte Pfade scannen
Übergib ein Array mit Pfaden innerhalb des Repositorys:
try {
const result = await security.run(repository, {
target: ["services/billing", "packages/auth"],
});
} finally {
await security.close();
}Die Pfade können auf Dateien oder Verzeichnisse verweisen. Das SDK löst jeden Pfad innerhalb des Repositorys auf und entfernt Duplikate.
Änderungen zwischen Commits scannen
Verwende DiffTarget.refs, um die per Commit gespeicherten Änderungen zwischen zwei lokal verfügbaren Git-Revisionen zu scannen:
import { DiffTarget } from "@openai/codex-security";
const target = DiffTarget.refs({
base: "HEAD~1",
head: "HEAD",
});
try {
const result = await security.run(repository, { target });
} finally {
await security.close();
}Die Zielrevision ist standardmäßig HEAD. Übergib das Stammverzeichnis des Git-Worktrees als Repository und checke vor dem Scan die gewünschte Zielrevision aus.
Arbeitsverzeichnis scannen
Verwende DiffTarget.workingTree, um Änderungen im Vergleich zu einer Basisrevision zu scannen. Dabei werden sowohl Änderungen im Staging-Bereich als auch noch nicht vorgemerkte Änderungen berücksichtigt:
import { DiffTarget } from "@openai/codex-security";
const target = DiffTarget.workingTree({ base: "HEAD" });
try {
const result = await security.run(repository, { target });
} finally {
await security.close();
}Die Basisrevision ist standardmäßig HEAD. Rufe die ausgewählten Revisionen mit Git ab, bevor du einen Diff-Scan oder einen Scan des Arbeitsverzeichnisses startest.
Tiefenscan auswählen
Setze mode: "deep", wenn du ein Repository oder einzelne Pfade umfassender prüfen möchtest:
try {
const result = await security.run(repository, {
target: ["services/billing"],
mode: "deep",
workers: 2,
subagents: 0,
stopAfterNoNew: 3,
maxDiscoveryRuns: 10,
maxTimeMinutes: 90,
});
} finally {
await security.close();
}Tiefenscans unterstützen Repositories und Pfade als Ziele. Verwende für Diff-Scans und Scans des Arbeitsverzeichnisses den Standardmodus. Bei Tiefenscans begrenzt workers die Anzahl gleichzeitig aktiver Scan-Worker. Mit subagents legst du die Anzahl der Subagenten pro Worker fest. stopAfterNoNew beendet die Suche, sobald die angegebene Anzahl aufeinanderfolgender Worker-Durchläufe keine neuen Befunde ergeben hat. maxDiscoveryRuns begrenzt die Gesamtzahl der Worker-Durchläufe.
Mit maxTimeMinutes begrenzt du die Suchdauer bei Tiefenscans. Der Standardwert entspricht dem Höchstwert von 5.760 Minuten (96 Stunden). Nach Ablauf der Frist endet die Suche und das SDK führt die Ergebnisse der abgeschlossenen Worker-Durchläufe zusammen. Bei Standardscans dient maxTimeMinutes als Richtwert für die Untersuchungsdauer. Der Bericht kann später fertig werden. Benutzerdefinierte Validierungen und Anweisungen für die Nachbearbeitung werden außerhalb dieses Zeitbudgets ausgeführt.
Wissensbasis zur Sicherheit hinzufügen
Übergib Architekturdokumente, Bedrohungsmodelle oder Sicherheitsrichtlinien über knowledgeBasePaths:
import { join } from "node:path";
const knowledgeBase = join(repository, "security.md");
try {
const result = await security.run(repository, {
knowledgeBasePaths: [knowledgeBase],
});
} finally {
await security.close();
}Das SDK akzeptiert Dateien und Verzeichnisse und durchsucht Verzeichnisse rekursiv. Unterstützt werden unter anderem UTF-8-Text (einschließlich JSON und SARIF), PDF und DOCX. Das SDK weist verknüpfte Eingabepfade zurück und überspringt Verknüpfungen innerhalb von Verzeichnissen.
Das SDK speichert den extrahierten Dokumenttext in der privaten Datei .scan-knowledge.json neben den Scan-Artefakten. Bewahre die Datei zusammen mit dem Scan-Verzeichnis auf. Wenn du einen unterbrochenen Tiefenscan fortsetzt, verwendet codex-security scans resume den gespeicherten Text auch dann, wenn die Originaldokumente inzwischen geändert oder gelöscht wurden. Die kanonischen Berichte enthalten den Dokumenttext nicht.
Anweisungen für den Scan und die Nachbearbeitung hinzufügen
Gib mit scanPrompt einen Schwerpunkt für den Scan vor und fordere mit postScanPrompt eine Nachbearbeitung an:
try {
const result = await security.run(repository, {
scanPrompt: "Focus on tenant isolation and authorization checks.",
postScanPrompt: "Write confirmed findings to post-scan-summary.md.",
});
} finally {
await security.close();
}Wenn die Nachbearbeitung fehlschlägt, behält das SDK den abgeschlossenen Scan bei und meldet den Fehler über onWarning. Hat die Nachbearbeitung Artefakte des abgeschlossenen Scans verändert, stellt das SDK diese wieder her. Die Nachbearbeitung beginnt nach dem Ende der Kostenerfassung für den Scan und fällt nicht unter maxCostUsd.
Befunde in deiner Umgebung validieren
Übergib validationPrompt, um mögliche Befunde mit deinem eigenen Testverfahren zu prüfen. Verweise im Prompt beispielsweise auf ein Skript, das du selbst kontrollierst und das außerhalb des ausgecheckten Repositorys liegt. Lass das Skript gegen deinen lokalen Testserver laufen. Gib in der Befehlszeile nach den Pfaden zum Repository und zum Ergebnisverzeichnis den Pfad zum Validierungsskript und dann die Server-URL an:
const [validationScript, validationUrl] = process.argv.slice(4);
if (!validationScript || !validationUrl)
throw new Error("Pass a validation script path and service URL.");
const result = await security.run(repository, {
outputDir,
validationPrompt: `Run ${validationScript} against ${validationUrl} and report which findings reproduce.`,
});node scan.mjs /path/to/repository /path/outside/repository/results /path/to/validate.sh http://localhost:3000
Verwende validationPrompt für Standardscans von Repositories, Pfaden, Änderungen zwischen Commits oder Änderungen im Arbeitsverzeichnis. Damit jeder Standardscan einer Komponente dasselbe Verfahren verwendet, übergib scanOptions.validationPrompt an runComponentScans. Tiefenscans lassen keine benutzerdefinierte Validierung zu.
Richtlinie zur Einstufung des Schweregrads anwenden
Übergib mit rubricPath den Pfad zu einer Markdown-Richtlinie, nach der der Scan den Schweregrad der Befunde einstuft. Alternativ kannst du mit severityRubric einen Snapshot der Richtlinie übergeben. Er enthält den Richtlinientext in markdown, eine positive ganze Zahl als revision und den sha256-Hashwert des exakten UTF-8-kodierten Markdown-Texts. Ein Snapshot hat Vorrang vor einer Datei. Standard- und Tiefenscans speichern die ausgewählte Richtlinie für erneute Versuche, das Fortsetzen unterbrochener Scans und neue Durchläufe.
Scan-Budget festlegen
Setze maxCostUsd, um einen Scan zu stoppen, wenn die geschätzten Modellkosten einen Grenzwert überschreiten. Verfolge die Kosten während des Scans mit onCost und gib estimatedUsdRange aus:
try {
const result = await security.run(repository, {
maxCostUsd: 5,
onCost(cost) {
console.log(cost.estimatedUsdRange);
},
});
console.log(result.cost?.estimatedUsdRange);
} finally {
await security.close();
}Für den Grenzwert ist estimatedUsd maßgeblich, die Kostenschätzung auf Basis eines kurzen Kontexts. Durch bereits laufende Anfragen kann die Schätzung über den Grenzwert steigen. Die Preise für lange Kontexte können dazu führen, dass auch estimatedUsdRange den Grenzwert übersteigt. Der Grenzwert deckelt nicht die abgerechneten Kosten.
Kann der Scan kein gültiges Abschlussergebnis erzeugen, löst run einen ScanCostLimitExceededError aus und behält alle verfügbaren Ausgaben bei.
Projektkomponenten scannen
Mit runComponentScans kannst du Dienste oder Pakete parallel scannen und ihre Befunde zusammenführen. Gib für jede Komponente einen Namen und mindestens einen Pfad relativ zum Repository an. Wähle ein neues oder leeres Ausgabeverzeichnis außerhalb des umgebenden Git-Worktrees.
import { runComponentScans } from "@openai/codex-security";
const result = await runComponentScans({
repository: repository,
outputDir: outputDir,
components: [
{ name: "API", paths: ["services/api", "packages/auth"] },
{ name: "Web", paths: ["services/billing"] },
],
workers: 2,
onProgress: ({ name, status }) => console.log(name, status),
});
console.log(result.reportPath);
if (result.failed > 0) {
throw new Error(`${result.failed} component scans failed.`);
}Mit workers legst du fest, wie viele Komponenten gleichzeitig gescannt werden. Der Standardwert ist vier.
Wenn Codex Komponenten vorschlagen soll, übergib auto: true anstelle von components. Ergänze planOnly: true, um den Plan in components.json zu speichern, ohne Scans auszuführen:
import { runComponentScans } from "@openai/codex-security";
const plan = await runComponentScans({
repository: repository,
outputDir: outputDir,
auto: true,
planOnly: true,
});
console.log(plan.planPath);Falls der Scan einzelner Komponenten fehlgeschlagen ist, lies die JSON-Datei unter result.retryPlanPath. Übergib das darin enthaltene Array components an runComponentScans und gib ein neues outputDir an. Der Bericht des zweiten Durchlaufs umfasst nur die erneut gescannten Komponenten. Prüfe die Berichte aus beiden Durchläufen.
Scan-Ergebnisse verwenden
Über ScanResult kannst du auf strukturierte Dokumente, Scan-Metadaten und Artefaktpfade zugreifen:
| Eigenschaft | Inhalt |
|---|---|
manifest |
Das versiegelte Scan-Manifest mit Ziel, Umfang, Angaben zum Erzeuger und Einträgen zu den Artefakten. |
findings |
Befunde des aktuellen Scans. Die einzelnen Befundobjekte findest du in findings.findings. |
repositoryFindings |
Offene Befunde aus den Scans des Repositorys, sofern ein Scan-Verlauf verfügbar ist. |
review |
Pfadmuster, die von der Prüfung ausgeschlossen sind (review.excludedPaths). |
scanDir |
Das Scan-Verzeichnis. |
threadId |
Die ID des Codex-Threads für diesen Scan. |
turnResult |
Status und Antwort des Gesprächsschritts sowie verfügbare Nutzungsmetadaten. |
cost |
Geschätzte Modell- und Tokenkosten oder null, wenn keine Schätzung verfügbar ist. |
reportPath |
Der Pfad zu report.md. |
threatModel |
Das gespeicherte Bedrohungsmodell oder null, wenn es nicht verfügbar ist. |
threatModelPath |
Der Pfad zum gespeicherten Bedrohungsmodell oder null, wenn er nicht verfügbar ist. |
manifestPath |
Der Pfad zu scan-manifest.json. |
findingsPath |
Der Pfad zu findings.json. |
artifactsDir |
Das Verzeichnis mit ergänzenden Artefakten. |
sarifPath |
Der Pfad zur generierten SARIF-Datei oder null, wenn keine SARIF-Datei vorliegt. |
pluginVersion |
Die vom Erzeuger des Scans protokollierte Plugin-Version. |
Um für einen späteren Scan dieselbe Plugin-Version vorauszusetzen, übergib expectedPluginVersion: result.pluginVersion. Weicht die installierte Plugin-Version ab, lehnt das SDK den Scan ab.
Lies für jeden Befund den Schweregrad und die erste Fundstelle im Quellcode aus:
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
);
}Befunde können die optionalen Felder codeEvidence, rootCause, validation, attackPath, remediationTests und preventiveControls enthalten.
Bei repositoryweiten Befunden erkennst du an confirmedInLatestScan, ob der letzte Scan den Befund erfasst hat oder ob er aus einem früheren Scan stammt und weiterhin offen ist:
for (const finding of result.repositoryFindings ?? []) {
console.log(finding.title, finding.confirmedInLatestScan);
}Mit result.toJSON() serialisierst du das Manifest, die Befunde, die protokollierten Ausschlüsse von der Prüfung, die Artefaktpfade und die Metadaten des Gesprächsschritts.
Gespeicherte Bedrohungsmodelle lesen
Prüfe threatModel und threatModelPath vor der Verwendung auf null. Du kannst ein gespeichertes Modell auch dann exportieren, wenn Codex Security die zugehörige Markdown-Datei nicht schreiben konnte. Verwende den beim Export zurückgegebenen Pfad, statt einen bestimmten Dateinamen vorauszusetzen.
Gespeicherte Artefakte exportieren
Du kannst gespeicherte Ergebnisse exportieren, ohne Codex zu starten, Anmeldedaten zu laden oder ein Modell aufzurufen. Dieses Beispiel schreibt ein gespeichertes Bedrohungsmodell auf die Standardausgabe. Übergib als erstes Befehlszeilenargument den Pfad zu einem vorhandenen Verzeichnis mit Scan-Ergebnissen:
import { exportArtifact } from "@openai/codex-security";
const directory = process.argv[2];
if (!directory) {
throw new Error(
"Pass an existing scan results directory as the first argument."
);
}
await exportArtifact({
source: { directory },
artifact: "threat-model",
output: "-",
});Um einen gespeicherten Scan anhand seiner ID auszuwählen, verwende stattdessen source: { scanId: "SCAN_ID" }. Gib für output einen Zielpfad an, um das Artefakt in einer Datei zu speichern.
Bedrohungsmodelle werden als Markdown exportiert. Liegt für den Scan kein gespeichertes Bedrohungsmodell vor, gibt der Export einen Fehler zurück. Setze für Befunde artifact: "findings" und wähle format: "sarif" (Standard), "json", "csv" oder "servicenow-avit".
Das Ergebnis enthält den Ausgabepfad path und beim Export eines Bedrohungsmodells in eine Datei zusätzlich die Herkunftsangaben provenance aus denselben gespeicherten Ergebnissen. Beide Felder sind null, wenn output: "-" auf die Standardausgabe schreibt. Für den Export ist Python 3.10 oder höher erforderlich.
Setze für ServiceNow Manual AVIT Ingestion artifact: "findings" und format: "servicenow-avit". Bereite die Anwendungsvorlage vor und übergib ihren Pfad als avitTemplate. Gib für output den Pfad zu einer privaten CSV-Zieldatei außerhalb des Repositorys an. Wähle mit source.directory das vorhandene Verzeichnis mit den Scan-Ergebnissen aus.
Vorhandenen Befund validieren
Mit validate prüfst du einen Befund aus einem anderen Tool oder Workflow anhand des Quellcodes. Die Methode startet keinen neuen Scan und führt weder die Anwendung noch deren Tests aus. Wenn du Belege aus der laufenden Anwendung brauchst, reproduziere den Befund separat.
const validation = await security.validate({
repositoryPath: repository,
finding: {
title: "Possible SQL injection",
location: "src/index.js:1",
},
});
console.log(validation.disposition);
console.log(validation.report);Übergib den Befund als nicht leere Zeichenfolge oder als JSON-Objekt. Liegt er in einer Datei, lies die Datei ein und übergib ihren Inhalt.
Das Feld disposition gibt an, ob der Befund als reportable, suppressed, not_applicable oder deferred eingestuft wurde. Der Markdown-Text in validation.report erläutert die Belege und die noch offenen Punkte. Speichere diese Zeichenfolge, wenn du eine Berichtsdatei benötigst.
Scan verfolgen oder abbrechen
Übergib Callbacks über ScanOptions, um den Start des Scans, den Fortschritt der Worker und erneute Verbindungsversuche zu melden:
try {
const result = await security.run(repository, {
outputDir: outputDir,
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);
} finally {
await security.close();
}Übergib ein AbortSignal aus deiner Anfrage oder deinem Job-Controller, um einen Scan abzubrechen. Läuft der Scan nach 30 Minuten noch, unterbricht ihn dieses Beispiel und gibt das Verzeichnis aus, in dem bereits gespeicherte Ausgaben liegen:
import { ScanInterruptedError } from "@openai/codex-security";
try {
await security.run(repository, {
outputDir: outputDir,
signal: AbortSignal.timeout(30 * 60 * 1000),
});
} catch (error) {
if (error instanceof ScanInterruptedError) {
console.error(error.scanDir);
} else {
throw error;
}
} finally {
await security.close();
}Ein unterbrochener Scan kann Teilergebnisse in scanDir hinterlassen. Bewahre das Verzeichnis auf, wenn du das Ergebnis näher untersuchen musst.
Anwendungen, die den Fortschritt der Scan-Vorbereitung anzeigen, können auch die folgenden Callbacks in ScanOptions verwenden:
| Callback | Zeitpunkt des Aufrufs |
|---|---|
onAuthentication(authentication) |
Der Scan wählt die Authentifizierungsmethode aus. |
onOutputArchived(archiveDir) |
Vorhandene Ergebnisse werden ins Archivverzeichnis verschoben. |
onOutputDirReady(scanDir) |
Das private Scan-Verzeichnis ist bereit. |
onScanStarted() |
Die Vorbereitung ist abgeschlossen und der Scan beginnt. |
onTrustedAccessStatus(status) |
Der Status von Trusted Access ist verfügbar. |
onReconnect(attempt, maxAttempts) |
Das SDK versucht, die Verbindung zu einem unterbrochenen Scan-Stream wiederherzustellen. |
onActivity(activity) |
Es gibt ein Update zu einem Befehl, einem Tool, einem Reasoning-Schritt oder einer Nachricht. |
onProgress(progress) |
Die Scan-Phase oder die Anzahl der geprüften Dateien ändert sich. |
onDeepProgress(progress) |
Die Anzahl der laufenden oder der abgeschlossenen Prüfungen im Tiefenscan ändert sich. |
onWorkerStatus(status) |
Der Scan meldet, wie viele Worker geplant und wie viele gestartet wurden, soweit sich diese Zahlen ermitteln lassen. |
onSessionEvent(session) |
Eine Scan- oder Worker-Sitzung löst ein Ereignis aus. |
onCost(cost) |
Eine aktualisierte Kostenschätzung für den Scan liegt vor. |
onWarning(warning) |
Der Scan meldet eine Warnung. |
onObserverError(observer, error) |
Ein anderer Callback im Scan-Ablauf löst einen Fehler aus. |
Der Status von Trusted Access lautet granted, not_granted oder unknown. Fehlender oder unbekannter Zugriff löst außerdem onWarning aus.
onSessionEvent empfängt Ereignisse ohne Schwärzungen. Sie können Quellcode oder Anmeldedaten enthalten. Filtere sie, bevor du sie an gemeinsam genutzte Protokolle oder andere Dienste weiterleitest.
Laufzeitumgebung und Anmeldedaten konfigurieren
Übergib eine Laufzeitkonfiguration, wenn du ein bestimmtes Plugin, einen bestimmten Interpreter oder eine bestimmte Codex-Einstellung benötigst. Wähle ein Modell, auf das dein Konto Zugriff hat:
const security = new CodexSecurity({
// To override the bundled plugin, add pluginPath: "/path/to/plugin".
pythonPath: "python3",
codexOverrides: {
model: "gpt-6.1-sol",
model_reasoning_effort: "medium",
},
});Gib mit pluginPath den Pfad zu einem Plugin-Verzeichnis oder einer ZIP-Datei an, um das mitgelieferte Plugin zu ersetzen. Mit pythonPath wählst du den Interpreter für das Plugin. Über codexOverrides werden unterstützte Werte in die isolierte Codex-Konfiguration übernommen. Für Amazon Bedrock setze model_provider und model in codexOverrides.
Setze codexOverrides.approval_policy auf "never", um Berechtigungsanfragen abzulehnen. Andernfalls werden Genehmigungsanfragen bei Scans automatisch überprüft. Informationen zum Dateisystemzugriff und zu geerbten Anmeldedaten findest du unter Berechtigungen für lokale Scans.
Gib für OpenRouter oder Fireworks außerdem den passenden API-Schlüssel und eine vollständige Anbieterkonfiguration in codexOverrides an. Setze OPENROUTER_API_KEY und übergib dieser TypeScript-Funktion die ID eines verfügbaren OpenRouter-Modells:
function createOpenRouterClient(model: string) {
return new CodexSecurity({
codexOverrides: {
model,
model_provider: "openrouter",
model_providers: {
openrouter: {
name: "OpenRouter",
base_url: "https://openrouter.ai/api/v1",
env_key: "OPENROUTER_API_KEY",
wire_api: "responses",
},
},
},
});
}Ersetze für Fireworks beide Vorkommen von openrouter durch fireworks, setze name auf Fireworks AI und env_key auf FIREWORKS_API_KEY, verwende https://api.fireworks.ai/inference/v1 als base_url und wähle ein Fireworks-Modell aus.
Der Client stellt außerdem folgende Methoden zur Authentifizierung bereit:
| Methode | Zweck |
|---|---|
loginApiKey(apiKey) |
Authentifiziert die isolierte Laufzeitumgebung mit einem API-Schlüssel. |
loginChatGPT() |
Startet die Anmeldung im Browser und gibt ein Anmelde-Handle zurück. |
loginChatGPTDeviceCode() |
Startet die Anmeldung per Gerätecode und gibt ein Anmelde-Handle zurück. |
account() |
Gibt den aktuellen Authentifizierungsstatus zurück. |
logout() |
Löscht die Anmeldedaten der isolierten Laufzeitumgebung. |
Ein Anmelde-Handle stellt waitForInstructions, authUrl, verificationUrl, userCode, wait und cancel bereit. Damit kann eine Anwendung den gewählten Anmeldevorgang anzeigen und abschließen. Das SDK kann eine in einer Datei gespeicherte Codex-Anmeldung wiederverwenden. Nutze für CI und serverseitige Automatisierung API-Schlüssel.
Sind sowohl ein API-Schlüssel als auch eine gespeicherte Anmeldung verfügbar, verwendet das SDK standardmäßig den API-Schlüssel. Wenn du stattdessen deine ChatGPT-Anmeldung nutzen möchtest, wähle sie für den Scan aus:
const result = await security.run(repository, {
auth: "chatgpt",
});Setze auth: "api-key", wenn der Scan einen API-Schlüssel aus den Umgebungsvariablen verwenden muss. preflight unterstützt dieselbe Option auth.
Scan-Fehler behandeln
Fange die exportierte Fehlerklasse ab, für die deine Anwendung eine passende Fehlerbehandlung bereitstellt:
| Fehler | Bedeutung |
|---|---|
AuthenticationRequiredError |
Der Scan benötigt unterstützte Anmeldedaten. |
ConfigurationError |
Die Codex-Konfiguration oder ein überschriebener Konfigurationswert ist ungeeignet. |
InvalidTargetError |
Das Repository, der Pfad, der Modus oder das Git-Ziel ist ungeeignet. |
OutputDirectoryError |
Der Ausgabepfad oder die zugehörigen Berechtigungen sind ungeeignet. |
OutputInsideProtectedRootError |
Das Ausgabeverzeichnis liegt innerhalb des gescannten Repositorys oder Worktrees. |
PluginPythonUnavailableError |
Es ist kein nutzbarer Python-Interpreter verfügbar. |
PluginBootstrapError |
Die Laufzeitumgebung des Plugins konnte nicht starten. |
ScanCostLimitExceededError |
Die geschätzten Scan-Kosten haben den Grenzwert überschritten. |
IncompleteScanError |
Der Scan endete, bevor das erforderliche Ergebnis vorlag. |
ContractValidationError |
Das Ergebnis eines abgeschlossenen Scans entspricht nicht den vereinbarten Strukturvorgaben. |
ScanInterruptedError |
Der Scan wurde unterbrochen. Möglicherweise liegen Teilergebnisse vor. |
Weitere Informationen findest du im CLI-Schnelleinstieg, im CI-Leitfaden oder in der CLI-Referenz.