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 key 和 設定。

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

執行掃描

僅掃描你信任且有權評估的儲存庫。SDK 使用 本機作業系統權限執行，且絕不會暫停以等待核准。 掃描程序可能繼承你的環境，因此請在開始前移除無關憑據。請參閱本機掃描 權限。

建立一個 CodexSecurity 客戶端，執行標準儲存庫掃描，並在 工作完成後關閉客戶端。傳入 outputDir，以選擇位於外圍 Git 工作樹 之外的私有結果目錄。

如果省略 outputDir，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 修訂版本之間已提交的更改：

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 報告錯誤。它還會恢復被後續操作更改的所有已完成掃描工件。

設定掃描預算

設定 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：

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 和超高推理強度。 在 codexOverrides 中設定 model 和 model_reasoning_effort，可使用 其他模型或推理強度。若要使用 Amazon Bedrock，請在 codexOverrides 中設定 model_provider 和 model。

codexOverrides 無法限制掃描的檔案系統存取權限或更改其 核准策略。請參閱本機掃描 權限。

對於 OpenRouter 或 Fireworks，還需提供相應的 API key，並在 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 key 非常適合 CI 和服務端自動化。

當 API key 和已儲存的登入資訊同時可用時，SDK 預設使用 API key。若要改用你的 ChatGPT 登入資訊，請為掃描選擇該資訊：

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

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

處理掃描錯誤

捕獲與應用程式可採取操作相對應的匯出錯誤類：

接下來可參閱 CLI 快速入門、CI 指南或 CLI 參考。