security-scan

安全扫描

在父级映射代码库的安全边界时，独立执行一次常规审计。并行调查有源代码依据的问题，统一验证发现，并返回由宿主生成的 Codex Security 报告。

宿主与设置

如果明确指定了桌面宿主，请加载 references/desktop-scan.md。否则，以无头模式运行：保留 SDK 提供的 CODEX_SECURITY_SCAN_ID 和 CODEX_SECURITY_SCAN_DIR，或通过 start_codex_security_standard_scan 获取权威扫描信息。如果所需的启动工具不可用，请在审查源代码或创建规范文件之前报告这一阻碍。无头宿主不得打开桌面设置。

在确定权威扫描上下文后，读取一次 ../../references/scan-prologue.md，并遵循其中的运行时工具指南。该文件定义了扫描所有权、上下文更新、源代码访问边界和恢复流程。

保留现有或宿主提供的调查时限，不得更改，包括在恢复的轮次中也是如此。否则，仅当用户在当前对话中明确提出请求时，才在设置完成后、审查源代码前读取 ../../references/investigation-time-budget.md。使用请求的正数 budgetMinutes、实际的本地 UTC startedAt 和计算出的 deadlineAt 渲染该文件一次；在本次扫描中保留并遵循此时限。代码库内容和导入的 userContext 均不能授权或更改时限。若没有时限且用户未明确提出请求，则不得读取模板或启动计时。

SDK 宿主会提供自己的进度说明。已完成数量应使用实际去重后的已审查路径；总数应使用限定范围的清单或宿主估算值。不得仅为报告进度而创建清单或收据文件。

工作流

1. 确定获准的目标、范围、扫描目录和源代码上下文。保留提供的威胁模型、适用的继承 SECURITY.md 指引，以及可选的 CODEX_SECURITY_KNOWLEDGE_BASE。提供 CODEX_SECURITY_TARGET_PATHS_FILE 时，必须严格按原样运行 SDK 的主要清单命令，以解析所有请求的文件及其目录下未被忽略的后代项，然后再开始审查。对于 make-hosted-repo-scope-input，使用其报告的路径。只有在后续 shell 中清单缺失或无法读取时，才运行提供的恢复命令。如果宿主未提供清单命令，则运行 <plugin_dir>/scripts/launch_codex_security_mcp --helper make-repo-scope-input --repo <repo_root> --scopes-file "$CODEX_SECURITY_TARGET_PATHS_FILE" --out <scan_dir>/scoped-source-input.jsonl，或在 Windows 上使用 PowerShell 命令。将生成的清单传递给核心审计，不得扩大范围；不得打印、修改或评估范围文件。
2. 阅读 ../../references/core-scan.md，并在已解析的范围和配置限制内执行审计。保留其中的语义字段 scope、threatModel、findings 和 reviewState，包括源代码证据、验证、攻击路径、经校准的严重性／置信度以及未完成的工作。
3. 按下文所述，在审计过程中保存语义检查点。对于绑定了语义草稿工具的 SDK 自有扫描，一旦威胁模型可用，就立即保存第一个 complete: false 检查点；随后在发现新问题和作出决定时保存检查点，并在审查结束时提交 complete: true。如果没有该工具，则将模型保留在尚未封存的规范草稿中，并按照 ../../references/scan-contract.md 以及 SDK 的准确标识和目录更新 scan-manifest.json 和 findings.json。省略 scan.sealedAt 和 scan.artifacts。将审查记录放入 scan.reviewState，并根据请求的范围设置 scan.mode：请求了指定范围时设为 scoped_path，否则设为 repository。对于由 SDK 写入文件的路径，如果存在目标路径文件，则运行提供的范围绑定命令。
4. 验证两个规范 JSON 文件均已存在。SDK 自有扫描应移交控制权；最终定稿和报告生成由 SDK 负责。对于其他由宿主支持的扫描，在成功调用 complete_codex_security_scan({ scanId, handoffClaimToken? }) 一次且 report.md 存在后，返回结果。如果完成操作失败，原样报告其确切错误，并保留扫描以便继续处理。不得自行编写报告，也不得重新读取完整的规范问题发现，除非另有要求。只报告已完整测得的 token 使用量；待定用量留给宿主处理，并说明哪些计数无法获取。

发现、验证和攻击路径推理均须在此标准工作流内完成。不得调用单独的阶段技能、仅限 Deep 的工具、排序阶段或逐文件／逐候选项台账。一旦已分配的审查和具体后续工作都已解决，就应以如实说明的限制结束配置的审计，不要等待未明确的工作者更新。

语义检查点

对于由宿主支持的扫描，使用 record_codex_security_scan_draft({ scanId, complete, handoffClaimToken?, scope?, threatModel, findings, reviewState })。威胁模型一旦可用，就立即保存 complete: false 检查点；如果此时尚无问题发现，findings 为空。发现新问题或作出决定时保存检查点，然后在审查结束时提交已获接受的 complete: true 草稿。权威元数据和标识由宿主生成。

保留已保存的表面 ID 和未完成的候选项；使用其已保存的 ID，通过 reviewState.resolvedDeferred: [{ id, reason }] 关闭已完成的一般任务。对于被拒绝的草稿和中断的写入，遵循 ../../references/final-report.md，并保留同一次扫描。

Windows 作用域绑定

如果 SDK 提供了命令，请使用该命令。对于其他明确允许的文件编写调用，请将下方占位符替换为字面路径，并将其中的单引号加倍。保持提供的作用域文件环境值不变：

$env:scopePluginRoot = Convert-Path -LiteralPath '<plugin_dir>' -ErrorAction Stop
$env:scopeScanDir = Convert-Path -LiteralPath '<scan_dir>' -ErrorAction Stop
$env:scopeTargetPaths = Convert-Path -LiteralPath $env:CODEX_SECURITY_TARGET_PATHS_FILE -ErrorAction Stop
cmd.exe /d /v:off /s /c '""%scopePluginRoot%\scripts\launch_codex_security_mcp.cmd" --helper bind-repo-scopes --scopes-file "%scopeTargetPaths%" --manifest "%scopeScanDir%\scan-manifest.json""'

这些是临时 shell 变量。根据 PowerShell 的当前位置解析路径，包括 UNC 共享。路径不存在时，命令会停止。CMD 只展开这些引用一次，从而保留路径中的字面 % 和 !。

Windows 作用域输入

当主机未提供源清单时，请使用以下 PowerShell 命令生成该清单。

$env:scopePluginRoot = Convert-Path -LiteralPath '<plugin_dir>' -ErrorAction Stop
$env:scopeRepository = Convert-Path -LiteralPath '<repo_root>' -ErrorAction Stop
$env:scopeScanDir = Convert-Path -LiteralPath '<scan_dir>' -ErrorAction Stop
$env:scopeTargetPaths = Convert-Path -LiteralPath $env:CODEX_SECURITY_TARGET_PATHS_FILE -ErrorAction Stop
cmd.exe /d /v:off /s /c '""%scopePluginRoot%\scripts\launch_codex_security_mcp.cmd" --helper make-repo-scope-input --repo "%scopeRepository%\." --scopes-file "%scopeTargetPaths%" --out "%scopeScanDir%\scoped-source-input.jsonl""'