Codex Security TypeScript SDK

使用 Codex Security TypeScript SDK，從您的應用程式或開發工具對程式碼庫與 程式碼變更執行安全性掃描。SDK 會傳回具型別的 發現項目、涵蓋範圍詳細資料及掃描產物路徑。對於執行時間較長的掃描，也 支援預檢、成本上限、進度回呼及取消操作。

SDK 採用 ECMAScript 模組（ESM），並透過 Node.js 22 （22.13.0 或更新版本）、24 或 26 在伺服器端執行。掃描也需要 Python 3.10 或更新版本。 使用 Python 3.10 時，另須安裝 tomli 套件。

設定 SDK

安裝 SDK：

npm install @openai/codex-security

開始掃描前，請設定 OPENAI_API_KEY 或 CODEX_API_KEY、使用 現有且儲存在檔案中的 Codex 登入狀態，或設定其他 供應商。Amazon Bedrock 使用 AWS 認證資料；OpenRouter 和 Fireworks 則使用各供應商專用的 API 金鑰與 組態。

為獲得最佳結果，請使用已通過 Trusted Access for Cyber 驗證的帳戶。登入或提供 API 金鑰並不會 讓帳戶取得 Trusted Access。

執行掃描

只掃描您信任且有權評估的程式碼庫。SDK 會以您本機作業系統的權限 執行，且不會暫停等待核准。 掃描程序可能繼承您的環境，因此請在開始前移除無關的 認證資料。請參閱本機掃描 權限。

建立一個 CodexSecurity 用戶端、執行標準程式碼庫掃描，並在作業完成後關閉 該用戶端。傳入 outputDir，以選擇位於所屬 Git 工作樹之外的私有 結果目錄。

若省略 outputDir，Codex Security 會將結果儲存在專屬的持久性 狀態目錄中。結果可能包含原始碼摘錄與漏洞 詳細資料，因此請選擇適當的權限與保留政策。

import { CodexSecurity } from "@openai/codex-security";

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 會啟動掃描、等待掃描完成、驗證經密封的產物， 並傳回 ScanResult。close 會釋放隔離的執行階段，且支援 重複呼叫。

透過預檢檢查輸入

開始掃描前，使用 preflight 檢查程式碼庫、目標、模式、知識庫文件、 輸出位置和 Codex 組態：

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

預檢不會動用 Codex 執行階段或認證資料，也會將外掛程式與 Python 的偵測 留待掃描本身執行。因此，預檢適合在長時間執行 或需要認證資料的作業前，先檢查使用者輸入。

若要預覽現有結果目錄將如何封存，請設定 archiveExisting: true：

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

console.log(plan.archiveDir);

傳回的 archiveDir 可預覽封存目錄的命名方式。最終路徑可能 不同，因為 run 會自行產生唯一的目的地。若要擷取實際的 封存路徑，請使用 onOutputArchived：

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

掃描會先封存先前的結果，再以空白輸出 目錄開始執行。

選擇掃描目標

SDK 支援程式碼庫、路徑、已提交差異和工作樹目標。 預設目標是整個程式碼庫。

掃描所選路徑

傳入程式碼庫內的路徑陣列：

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

路徑可指向檔案或目錄。SDK 會解析程式碼庫內的每個 路徑並移除重複項目。

掃描已提交的變更

使用 DiffTarget.refs 掃描兩個本機可用的 Git 修訂版本之間已提交的變更：

import { DiffTarget } from "@openai/codex-security";

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

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

目標修訂版本預設為 HEAD。若為差異目標，程式碼庫引數必須 是 Git 工作樹的根目錄。

掃描工作樹

使用 DiffTarget.workingTree，以基準 修訂版本為依據，掃描已暫存與未暫存的變更：

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

基準版本預設為 HEAD。在開始 差異或工作樹掃描前，請先擷取所選修訂版本。

選擇深度模式

若程式碼庫或路徑掃描需要更全面的審查，請設定 mode: "deep"：

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

深度模式支援程式碼庫和路徑目標。差異與 工作樹掃描請使用標準模式。選用設定可控制同時執行且彼此獨立的 標準掃描工作程序數量、每個工作程序的子代理程式數量、連續完成但未產生新發現項目的 工作程序掃描次數，以及工作程序執行的總次數與持續時間。這些設定 需要 mode: "deep"。

maxTimeHours 的預設值為 96，可設為不超過 96 的正數， 也接受小數小時。到達時限時，Codex Security 會停止尚未完成的 工作程序、保留已完成的掃描結果，並將其彙整成最終 報告。請先審查 result.coverage.completeness，再將限時 掃描視為完整涵蓋的證據。

新增安全性知識庫

傳入架構文件、威脅模型或安全性政策時，請使用 knowledgeBasePaths：

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

SDK 接受檔案或目錄，並會以遞迴方式搜尋目錄。 支援的文件格式為 .md、.markdown、.txt、.pdf 和 .docx。 SDK 會拒絕連結形式的輸入路徑、略過目錄中的連結項目，而且不會將 擷取出的文件內容納入已儲存的掃描結果。

新增掃描與後續指示

使用 scanPrompt 指定掃描重點，並使用 postScanPrompt 要求後續處理：

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

若後續處理失敗，SDK 仍會保留已完成的掃描，並透過 onWarning 回報錯誤。對於遭後續處理變更的任何已完成掃描產物， SDK 也會加以還原。

設定掃描預算

設定 maxCostUsd，即可在預估模型成本超過上限時停止掃描。 使用 onCost 在掃描執行期間追蹤成本：

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

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

此限額僅用於預估支出，並非硬性上限，因此進行中的 要求完成時，實際費用可能略高於限額。若深度掃描在 Codex Security 彙整已完成工作程序的結果後達到限額，run 會傳回 將 coverage.completeness 設為 "partial" 的結果，並透過 onWarning 回報預算警告。

若掃描無法產生已完成的部分結果，run 會擲回 ScanCostLimitExceededError，並保留任何可用的輸出。

處理掃描結果

ScanResult 會提供結構化文件、掃描中繼資料和產物 路徑：

若後續掃描必須使用相同的外掛程式，請傳入 expectedPluginVersion: result.pluginVersion。如果已安裝的外掛程式版本 不同，SDK 會拒絕該次掃描。

直接使用結構化的發現項目和涵蓋範圍：

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

發現項目可包含 codeEvidence、rootCause、validation、 attackPath、remediationTests 和 preventiveControls 等選填欄位。

針對整個程式碼庫的發現項目，confirmedInLatestScan 可區分最新掃描中發現的項目 與先前發現但仍未解決的項目：

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

涵蓋完整度為 complete、partial 或 unknown。在將掃描結果作為 安全性決策的依據之前，請先審查延後審查的範圍、排除項目及 尚待釐清的問題。

result.toJSON() 會以單一可直接轉換為 JSON 的物件，傳回資訊清單、程式碼庫與本次掃描的發現項目、 涵蓋範圍、掃描與執行緒識別碼、reportPath、artifactsDir、 sarifPath、成本及輪次中繼資料。

追蹤或取消掃描

傳入 ScanOptions 回呼，以回報掃描啟動、工作程式進度及 連線重試情形：

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

傳入 AbortSignal，以處理來自請求、工作控制器 或逾時的取消操作：

import { ScanInterruptedError } from "@openai/codex-security";

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

掃描中斷時，可能會在 scanDir 留下部分輸出。若需要調查結果，請保留該 目錄。

顯示掃描設定進度的應用程式，也可以使用 ScanOptions 的 生命週期回呼：

Trusted Access 狀態為 granted、not_granted 或 unknown。缺少存取權或 存取狀態不明時，也會觸發 onWarning。

onSessionEvent 接收的事件未經遮蔽處理，且可能包含原始 程式碼或憑證。將這些事件傳送至共用紀錄或其他 服務前，請先加以篩選。

設定執行階段與憑證

需要特定的外掛程式、解譯器或 Codex 設定時，請傳入執行階段組態：

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 接受外掛程式目錄或 ZIP 檔。pythonPath 用於選取 外掛程式解譯器。codexOverrides 會將支援的值合併至隔離的 Codex 組態。掃描預設使用 gpt-5.6-sol，並採用 極高推理強度。將 model 與 model_reasoning_effort 設定於 codexOverrides 中，即可使用 不同的模型或推理強度。若要使用 Amazon Bedrock，請 將 model_provider 與 model 設定於 codexOverrides 中。

codexOverrides 無法限制掃描對檔案系統的存取，也無法變更其 核准政策。請參閱本機掃描 權限。

若使用 OpenRouter 或 Fireworks，也須提供對應的 API 金鑰，並在 codexOverrides 中設定完整的供應商組態。例如，請設定 OPENROUTER_API_KEY 並設定 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",
      },
    },
  },
});

若使用 Fireworks，請將兩個 openrouter 鍵都改為 fireworks，將 name 設為 Fireworks AI，將 env_key 設為 FIREWORKS_API_KEY，使用 https://api.fireworks.ai/inference/v1 作為 base_url，並選取 Fireworks 模型。

用戶端也提供支援的身分驗證方法：

登入控制代碼提供 waitForInstructions、authUrl、verificationUrl、 userCode、wait 和 cancel，讓應用程式能夠顯示並完成 所選的登入流程。SDK 可重複使用儲存於檔案中的 Codex 登入資訊。API 金鑰 適合用於 CI 和伺服器端自動化。

當 API 金鑰和已儲存的登入資訊皆可用時，SDK 預設會使用 API 金鑰。若要改用 ChatGPT 登入，請為掃描選取該方式：

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

設定 auth: "api-key"，即可要求使用環境中的 API 金鑰。preflight 也接受 相同的 auth 選項。

處理掃描錯誤

根據應用程式可採取的處理動作， 捕捉對應的匯出錯誤類別：

接著請參閱 CLI 快速入門、CI 指南或 CLI 參考資料。