Codex Security TypeScript SDK

使用 Codex Security TypeScript SDK 从服务端应用或开发工具运行仓库与代码变更扫描，选择目标和 OpenAI 或 Amazon Bedrock 提供商，并管理扫描生命周期。

Codex Security TypeScript SDK#

Codex 中文站说明： 本页围绕“Codex Security TypeScript SDK”重新补充了中文使用场景和验证重点。界面名称可能随 Codex 版本更新，请以当前客户端为准。

从 TypeScript 运行 Codex Security 扫描、选择目标和提供商、检查结果并管理扫描生命周期。

使用 Codex Security TypeScript SDK，可以从应用或开发者工具对仓库和代码变更运行安全扫描。SDK 会返回类型化的发现、覆盖范围详情以及扫描工件的路径。对于耗时较长的扫描，它还支持预检、成本限制、进度回调和取消操作。

SDK 使用 ECMAScript 模块 (ESM)，并在服务器端通过 Node.js 22.13.0 或更高版本运行。扫描还需要 Python 3.10 或更高版本。

Codex Security SDK 已在 GitHub 上公开提供。运行扫描需要 Codex Security 访问权限。有关通用编程智能体，请参阅 Codex SDK 指南。有关终端和 CI 工作流，请参阅 Codex Security CLI 快速入门。

设置 SDK#

安装 SDK：

bash

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。

运行扫描#

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

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

typescript


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 配置：

typescript

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：

typescript

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

console.log(plan.archiveDir);

返回的 archiveDir 会预览归档命名。最终路径可能有所不同，因为 run 会生成自己的唯一目标位置。使用 onOutputArchived 捕获实际归档路径：

typescript

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

扫描会归档先前的结果，并从空的输出目录开始。

选择扫描目标#

SDK 支持仓库、路径、已提交差异和工作树目标。默认目标是完整仓库。

扫描选定路径#

传入仓库内的路径数组：

typescript

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

路径可以指向文件或目录。SDK 会解析仓库内的每个路径并移除重复项。

扫描已提交的变更#

使用 DiffTarget.refs 扫描本地可用的两个 Git 修订版本之间已提交的变更：

typescript


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

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

head 默认为 HEAD。差异目标要求仓库参数为 Git 工作树根目录。

扫描工作树#

使用 DiffTarget.workingTree 扫描相对于基准修订版本的已暂存和未暂存变更：

typescript

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

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

选择深度模式#

对于需要更广泛审查的仓库或路径扫描，请设置 mode: "deep"：

typescript

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

深度模式支持仓库和路径目标。差异和工作树扫描请使用标准模式。可选设置可控制并发发现工作进程、每个工作进程的子智能体数量、未发现新问题的连续发现运行次数，以及发现运行总次数。这些设置需要 mode: "deep"。

添加安全知识库#

通过 knowledgeBasePaths 传入架构文档、威胁模型或安全策略：

typescript

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 请求后续操作：

typescript

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

设置扫描预算#

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

typescript

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` 读取发现对象。
`repositoryFindings`	扫描历史可用时，列出仓库历次扫描中仍处于 open 状态的发现。
`coverage`	已审查的表面、排除项、延期工作、未决问题和完整性。
`scanDir`	扫描目录。
`threadId`	扫描的 Codex thread 标识符。
`turnResult`	turn 状态、响应和可用的用量元数据。
`cost`	预估的模型和 token 成本；不可用时为 `null`。
`reportPath`	`report.md` 的路径。
`manifestPath`	`scan-manifest.json` 的路径。
`findingsPath`	`findings.json` 的路径。
`coveragePath`	`coverage.json` 的路径。
`artifactsDir`	配套产物目录。
`sarifPath`	生成的 SARIF 路径；没有 SARIF 时为 `null`。
`pluginVersion`	扫描生成方记录的版本。

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

typescript

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

对于仓库范围的发现，confirmedInLatestScan 可以区分最新扫描中出现的发现，以及仍处于 open 状态的较早发现：

typescript

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

覆盖完整性为 complete、partial 或 unknown。将扫描用作安全决策依据之前，请检查延期处理的表面、排除项和未决问题。

result.toJSON() 会在一个可直接用于 JSON 的对象中返回 manifest、仓库级和当前扫描的 findings、coverage、扫描与 thread 标识符、reportPath、artifactsDir、sarifPath、cost 和 turn 元数据。

跟踪或取消扫描#

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

typescript

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);
},
onReconnect(attempt, maxAttempts) {
console.log(`Reconnect attempt ${attempt} of ${maxAttempts}`);
},
onObserverError(observer, error) {
console.error(`${observer} failed`, error);
},
});

console.log(result.reportPath);

当取消操作来自请求、作业控制器或超时时，传入 AbortSignal：

typescript


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 生命周期回调：

回调	调用时机
`onAuthentication(authentication)`	扫描选择其认证方式时。
`onOutputArchived(archiveDir)`	现有结果移至归档目录时。
`onOutputDirReady(scanDir)`	私有扫描目录准备就绪时。
`onScanStarted()`	扫描设置完成并开始执行时。
`onTrustedAccessStatus(status)`	Trusted Access 状态可用时。
`onReconnect(attempt, maxAttempts)`	SDK 重试已断开的扫描流时。
`onActivity(activity)`	命令、工具、推理步骤或消息更新时。
`onProgress(progress)`	扫描阶段或已审查文件数发生变化时。
`onWorkerStatus(status)`	工作进程预检或分派状态发生变化时。
`onCost(cost)`	更新后的预估扫描成本可用时。
`onWarning(warning)`	扫描报告警告时。
`onObserverError(observer, error)`	其他扫描生命周期回调引发错误时。

Trusted Access 状态为 granted、not_granted 或 unknown。缺失或未知的访问权限也会触发 onWarning。

配置运行时和凭据#

需要特定插件、解释器或 Codex 设置时，请传入运行时配置：

typescript

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，推理强度为 extra-high。在 codexOverrides 中设置 model 和 model_reasoning_effort，可使用其他模型或推理强度。要使用 Amazon Bedrock，请在 codexOverrides 中设置 model_provider 和 model。

对于 OpenRouter 或 Fireworks，还需提供匹配的 API key，并在 codexOverrides 中提供完整的提供商配置。例如，设置 OPENROUTER_API_KEY 并配置 OpenRouter：

typescript

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 模型。

客户端还提供支持的认证方式：

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

登录句柄提供 waitForInstructions、authUrl、verificationUrl、 userCode、wait 和 cancel，以便应用呈现并完成所选登录流程。SDK 可以复用基于文件的 Codex 登录。API key 非常适合 CI 和服务器端自动化。

当 API key 和已存储的登录信息同时可用时，SDK 默认使用 API key。要改用 ChatGPT 登录，请为扫描选择该方式：

typescript

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

设置 auth: "api-key" 可要求使用环境变量中的 API key。preflight 接受相同的 auth 选项。

处理扫描错误#

根据应用可以采取的操作，捕获相应的导出错误类：

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

接下来可参阅 CLI 快速入门、CI 指南或 CLI 参考。

本站实践建议#

应用“Codex Security TypeScript SDK”中的安全设置时，应从最小权限开始，再根据实际任务逐步开放。涉及网络、密钥、生产环境或删除操作时，仍应保留人工确认。

Codex API 与国内使用#

在实践“Codex Security TypeScript SDK”相关功能时，如需为 Codex 配置 OpenAI-compatible API，可以前往 APIBest 获取 API Key。第三方服务的模型映射、价格、额度和数据处理方式以 APIBest 当前说明为准。