Codex 安全 TypeScript SDK

身份 非官方简体中文镜像

翻译状态 AI 翻译

来源版本 官方未提供

同步日期 2026-07-31

官方原文 learn.chatgpt.com

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

使用 Codex 安全 TypeScript SDK 对代码库运行安全扫描，并 从你的应用程序或开发者工具扫描代码更改。 SDK 会返回类型化的 发现项、覆盖范围详情以及扫描产物的路径。对于较长时间的扫描，它 支持预检检查、成本限制、进度回调和取消。

该 SDK 使用 ECMAScript 模块（ESM），并在服务器端运行，要求 Node.js 22 或 更高版本。扫描还需要 Python 3.10 或更高版本。

该 Codex 安全 SDK 已在 上公开提供 GitHub。运行扫描需要 Codex 安全访问权限。对于通用编码 Agent，请参阅 Codex SDK 指南。对于终端和 CI 工作流，请参阅 Codex 安全 CLI 快速入门。

设置 SDK

安装 SDK：

npm install @openai/codex-security

在开始扫描之前，请设置 OPENAI_API_KEY 或 CODEX_API_KEY，或者使用一个 现有的基于文件的 Codex 登录。

为获得最佳结果，请使用已通过 Trusted Access for Cyber验证的账户。登录或提供 API 密钥并不会 授予 Trusted Access。

运行扫描

创建一个 CodexSecurity 客户端，运行标准代码库扫描，并在工作完成后关闭 客户端。传入 outputDir 以选择位于外层 Git 工作树之外的私有 结果目录。

如果省略 outputDir， Codex 安全会将结果保存在其自己的持久 状态目录中。结果可能包含源代码摘录和漏洞 详情，因此请选择合适的权限和保留策略。

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"],
  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 默认为 HEAD。差异目标要求代码库参数 为 Git 工作树根目录。

扫描工作树

使用 DiffTarget.workingTree 针对基础修订版本扫描暂存和未暂存的更改 ：

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

base 默认为 HEAD。在开始 差异或工作树扫描前，请获取所选修订版本。

选择深度模式

为需要更广泛审查的代码库或路径扫描设置 mode: "deep" ：

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

深度模式支持代码库和路径目标。对差异和 工作树扫描使用标准模式。

添加安全知识库

通过 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 会拒绝链接的输入路径，跳过链接的目录条目，并将 提取的文档内容保存在已保存的扫描结果之外。

设置扫描预算

设置 maxCostUsd 以在估算模型成本超过限制时停止扫描。 使用 onCost 在扫描运行时跟踪成本：

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

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

该限制是估算值，不是严格的支出上限。已在进行中的请求 可能会在超过限制后完成。如果扫描超出限制， SDK 会抛出 ScanCostLimitExceededError 并保留可用结果。

处理扫描结果

ScanResult 公开结构化文档、扫描元数据和产物 路径：

属性	内容
manifest	密封的扫描清单，包括目标、范围、生成方和产物记录。
findings	发现项文档。从 findings.findings读取发现项对象。
coverage	已审查表面、排除项、延后工作、开放问题和完整性。
scanDir	扫描目录。
threadId	扫描的 Codex 线程标识符。
turnResult	轮次状态、响应和可用的用量元数据。
cost	估算的模型和 token 成本，或 null 在不可用时的值。
reportPath	通往 report.md的路径。
manifestPath	通往 scan-manifest.json的路径。
findingsPath	通往 findings.json的路径。
coveragePath	通往 coverage.json的路径。
artifactsDir	支持产物目录。
sarifPath	生成的 SARIF 路径，或 null 当 SARIF 不存在时的值。
pluginVersion	扫描生成方记录的版本。

直接使用结构化发现项和覆盖范围：

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

覆盖完整性为 complete、 partial或 unknown。在将扫描用作 安全决策证据之前，请审查延后 表面、排除项和开放问题。

result.toJSON() 返回清单、发现项、覆盖率、扫描和线程 标识符， reportPath， artifactsDir， sarifPath以及轮次元数据，全部包含在 一个 JSON就绪对象中。

跟踪或取消扫描

传入 ScanOptions 回调来报告扫描启动、工作器进度和 连接重试：

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

当取消来自请求、作业控制器 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 生命周期回调：

回调	调用时机
onOutputArchived(archiveDir)	现有结果移动到归档目录。
onOutputDirReady(scanDir)	私有扫描目录已准备就绪。
onScanStarted()	扫描设置完成并开始执行。
onReconnect(attempt, maxAttempts)	该 SDK 重试已断开的扫描流。
onWorkerStatus(status)	工作器预检或调度状态发生变化。
onCost(cost)	有更新后的估算扫描成本可用。
onObserverError(observer, error)	另一个扫描生命周期回调引发错误。

配置运行时和凭据

当需要特定插件、解释器或 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 以使用 不同模型或推理强度。

客户端还公开支持的身份验证方法：

方法	用途
loginApiKey(apiKey)	使用 API 密钥对隔离运行时进行身份验证。
loginChatGPT()	启动浏览器登录流程并返回登录句柄。
loginChatGPTDeviceCode()	启动设备代码登录流程并返回登录句柄。
account()	返回当前身份验证状态。
logout()	清除隔离身份验证。

登录句柄提供 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 选项。

处理扫描错误

捕获与你的应用程序可 采取的操作相匹配的导出错误类：

错误	含义
AuthenticationRequiredError	扫描需要受支持的凭据。
ConfigurationError	Codex 配置或覆盖不适用。
InvalidTargetError	代码库、路径、模式或 Git 目标不适用。
OutputDirectoryError	输出位置或其权限不适用。
OutputInsideProtectedRootError	输出目录位于被扫描的代码库或工作树内。
PluginPythonUnavailableError	没有可用的 Python 解释器。
PluginBootstrapError	插件运行时无法启动。
ScanCostLimitExceededError	扫描超出了其估算成本限制。
IncompleteScanError	扫描在生成所需结果之前结束。
ContractValidationError	已完成的扫描返回了结构化契约错误。
ScanInterruptedError	中断停止了扫描，并可能留下部分输出。

继续阅读 CLI 快速入门、 CI 指南或 CLI 参考。