OpenAI Codex Security 自定义验证（Custom Validation）实战：用本地 HTTP 证据判定越权读取漏洞

应用安全漏洞扫描AI 应用【免费下载链接】codex-securityOpenAIs Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/openai/codex-security项目地址https://gitcode.com/gh_mirrors/co/codex-security点击查看免费下载本指南聚焦 codex-security 扫描管线中的**自定义验证Custom Validation**阶段当默认的源码级验证不足以证明某个发现时如何编写一份独立的验证提示词validation prompt让扫描 Agent 在一个受控的本地 fixture 上运行真实 HTTP 请求、落盘证据文件并按结构化契约回传reportable / suppressed / deferred判定。读完本文你将掌握 examples/custom-validation/validation.md 中五步验证协议的完整含义、validate.mts证据脚本与app.mts漏洞 fixture 的实现细节以及 SDK 端如何消费并校验这些结果、如何把该模式移植到自己的项目包括 Docker/Compose 场景。一、什么是自定义验证为什么需要它codex-security 的标准扫描流程通常按发现discovery→ 验证validation→ 攻击路径attack path三个阶段推进其中验证阶段由内置工作流基于源码证据与反证判断某个候选问题是否可上报。但对于需要运行时行为才能确证的漏洞——例如认证通过后能否越权读取他人资源——仅靠源码静态分析往往只能给出推断无法形成确实发生了越权的硬证据。自定义验证正是在此场景下提供的逃生通道由开发者/安全工程师编写一段专属验证工作流提示词即validation.md描述目标环境、可执行的测试步骤、证据落盘位置以及判定规则SDK 会接管整个验证阶段的编排禁用掉默认验证与攻击路径相关的工具强制 Agent 只按这份提示词执行。从 sdk/typescript/src/custom-validation-prompt.ts 的源码可以看到进入自定义验证后以下工具会被显式禁用start_codex_security_standard_scan/start_codex_security_prompt_only_scan/start_codex_security_deep_scancomplete_codex_security_scanrecord_codex_security_candidate_validationsrecord_candidate_attack_paths同时 SDK 会校验内置工作流文件references/core-scan.md、skills/security-scan/SKILL.md、skills/security-diff-scan/SKILL.md的 SHA-256 哈希一旦与预期不符就抛出IncompleteScanError并明确提示Default validation was not started默认验证不会悄悄启动。这保证了自定义验证是全有或全无的要么按你的协议完整跑完要么扫描失败绝不回退到默认验证流程examples/custom-validation/README.md 也写明 The scan fails if custom validation cannot complete。二、演示项目全景一个故意留洞的发票 API本仓库的 examples/custom-validation/ 目录提供了一个完整的可运行示例包含四个核心文件文件角色app.mts故意包含漏洞的本地 fixture发票 API仅含合成数据scan.md发现阶段提示词限定审查范围、说明哪些是测试桩validate.mts验证阶段证据脚本起服务、发请求、存证据、关服务validation.md自定义验证工作流提示词本文核心2.1 漏洞 fixtureapp.mtsapp.mts启动一个监听127.0.0.1的 HTTP 服务内置两组合成身份与两张发票令牌demo-alice → alice、demo-bob → bob发票1001owner: alice, amount: 25、1002owner: bob, amount: 80它只接受GET /invoices/:id非 GET 返回 501没有合法令牌返回 401发票不存在返回 404。关键缺陷位于 app.mts 的注释处// BUG: authentication does not establish ownership of this invoice. reply(200, invoice);即服务端只校验了调用者是否登录却从未校验该发票是否属于调用者——任何已登录用户都可以读取任意他人的发票。这正是invoice-ownership发票所有权类发现所要验证的对象。2.2 发现阶段提示词scan.mdscan.md 的作用是给发现阶段划定边界只审查app.mts中的发票所有权检查明确已认证账户不得读取他人发票强调令牌与记录均为合成测试数据validate.mts是测试脚手架而非应用端点发现阶段保持纯源码source-only不做运行时验证。三、如何运行整个演示从仓库根目录构建 CLI 并运行见 examples/custom-validation/README.mdpnpm --dir sdk/typescript install --frozen-lockfile pnpm --dir sdk/typescript run build node examples/custom-validation/run.mjsrun.mjs会做四件事对应 examples/custom-validation/run.mjs 的实现在临时目录创建target/与scan/两个子目录并把app.mts、validate.mts复制进去用 SDK 自带的 TypeScript 编译器build:examples把.mts编译为.mjs调用sdk/typescript/bin/codex-security.mjs scan传入--path app.mts指定目标文件--scan-prompt-file scan.md--validation-prompt-file validation.md--output-dir 临时scan目录--headless以及你追加的任意 CLI 参数例如--model gpt-5.6-terra --effort high打印目标目录与扫描输出目录路径。扫描完成后输出目录中会生成README 中列出的产物report.md最终安全报告artifacts/custom-validation/candidates.json固定候选集artifacts/custom-validation/http-proof.json观察到的 HTTP 响应证据artifacts/custom-validation/results.json结构化判定结果若只想单独跑 HTTP 证据脚本、不触发扫描pnpm --dir sdk/typescript run build:examples node examples/custom-validation/validate.mts --output reports/http-proof.json四、validation.md 五步协议逐条拆解examples/custom-validation/validation.md 全文共五步是给验证 Agent 的指令契约。下面逐条给出原文语义、对应的实现证据与判定要点。步骤 1运行证据脚本并指定输出路径Runnode validate.mjsfrom the supplied repository root. Pass--outputwith the absolute path toartifacts/custom-validation/http-proof.jsoninside this scans directory. The runner has already compiled the TypeScript fixture to JavaScript.工作目录为扫描提供的仓库根示例中即临时target/目录--output必须是指向扫描目录内artifacts/custom-validation/http-proof.json的绝对路径runner 已把 TypeScript fixture 编译成 JavaScript呼应了run.mjs中的build:examples步骤Agent 无需也无法自己编译。从 validate.mts 的实现看--output是必填参数缺省时打印--output is required并以退出码 2 结束-h/--help则打印用法node validate.mts --output PATH后返回 0。步骤 2本地服务是唯一被授权的测试目标The script starts a server on an ephemeral127.0.0.1port, makes three HTTP requests using synthetic identities, and shuts the server down. This local server is the only authorized test target. Do not install packages or contact any external service.证据脚本的行为validate.mtscreateServer()启动服务并监听临时端口server.listen(0, 127.0.0.1)端口 0 表示由系统分配依次发起三个请求GET /invoices/1002匿名无令牌→ 预期 401GET /invoices/1001Alice 读自己的发票Bearer demo-alice→ 预期 200GET /invoices/1002Alice 读 Bob 的发票Bearer demo-alice→ 预期 200 且owner bob即越权成立通过finally块保证服务最终关闭。每个请求带AbortSignal.timeout(5_000)的 5 秒超时防止网络异常导致脚本悬挂。协议层面强调本地服务是唯一授权目标、禁止安装依赖、禁止联系外部服务这是为了让验证行为可复现、可审计、不越权。步骤 3读取证据并强制校验控制组Read the saved JSON. The anonymous request must return 401, the own-account request must return 200, andserver_stoppedmust be true. If the script or those controls fail, returnstatus: incompletewith the reason. Do not substitute source-only validation.这一条确立了三组控制断言缺一不可断言含义匿名请求 401认证机制确实生效服务确实要求登录本人请求 200合法用户能正常读取自己的发票正向通路正常server_stopped true服务已干净关闭无残留进程对应地validate.mts内部用assert.equal(anonymous.status, 401, Authentication control failed)与assert.equal(own_invoice.status, 200, Own-account control failed)做硬断言任一控制失败都会抛错、脚本非零退出server_stopped字段则是在finally中确认关闭后写truevalidate.mts。重点约束任何控制组失败都必须以status: incomplete 原因返回不允许退而求其次用纯源码分析冒充验证结论Do not substitute source-only validation。这与 SDK 端status ! complete即抛错、最终让整个扫描以IncompleteScanError失败的行为一致见 sdk/typescript/src/custom-validation.ts。步骤 4按证据映射 disposition 判定For each invoice-ownership candidate, returnreportablewhencross_account_readis true. Usesuppressedif the other-account request returns 403 or 404. Usedeferredfor an unexpected or inconclusive result. Explain the actual HTTP results. Referenceartifacts/custom-validation/http-proof.jsoninartifact_paths.这是把原始 HTTP 观测翻译成结构化判定的规则表reportable可上报cross_account_read true即 Alice 确实以 200 读到了owner bob的发票——越权行为被运行时证实suppressed压制其他账户请求返回403明确拒绝或 404资源不可见说明存在所有权/可见性保护该候选不成立deferred延期结果意外或无法定论例如服务不可达、断言失败、响应异常留待人工跟进。同时要求解释实际 HTTP 结果每个状态码与响应体并在artifact_paths中引用artifacts/custom-validation/http-proof.json让证据可追溯。cross_account_read的计算逻辑位于 validate.mtsother_invoice.status 200 other_invoice.body.owner bob即请求成功且返回的确实是他人bob的发票才算越权读取成立。步骤 5精确返回且绝不越界Return exactly one result for every supplied candidate. Defer unrelated candidates with an explicit proof gap. Usenullfor severity and impact unless the observed behavior supports a change. Return only the required structured result; do not edit the canonical scan files.四条收尾纪律一一对应每个候选恰好一个结果不能多、不能漏、不能改候选身份无关候选与当前证据无关的候选必须以明确的证据缺口proof gap理由deferred而不是跳过严重度与影响除非观测到的行为确实支持调整否则severity与impact一律返回null——自定义验证只负责确证/否定发现不擅自改分只读原则只返回结构化结果不得编辑规范化的扫描文件scan-manifest.json、findings.json、coverage.json等由 SDK 统一回写。五、SDK 端如何消费这份协议验证 Agent 的输出并不是自由文本而是必须匹配一套 JSON Schema 的结构化对象。核心契约定义在 sdk/typescript/src/custom-validation.tsinterface CustomValidationResult { status: complete | incomplete; reason: string | null; validations: Array{ candidateId: string; validation: { disposition: reportable | suppressed | not_applicable | deferred; method: string; confidence: high | medium | low; confidence_rationale: string; rubric: string; evidence: string[]; // 至少 1 条 counterevidence_or_proof_gap: string; remaining_uncertainty: string; artifact_paths: string[]; }; severity: { level: string; rationale: string } | null; impact: { level: string; rationale: string } | null; }; }5.1 候选集从哪里来验证开始前SDK 会读取扫描草稿scan-manifest.json、findings.json、coverage.json校验scan.scope.validationMode custom_pending且草稿未封存sealedAt undefined然后按每个 finding 的extensions.customValidationSurfaceIds生成固定候选集写入artifacts/custom-validation/candidates.json见 sdk/typescript/src/custom-validation.ts。这意味着候选是扫描阶段确定的验证 Agent 不能新增候选、不能改动候选的源码位置每个已上报reported的 coverage surface 必须至少对应一个候选否则直接判为IncompleteScanError。5.2 结果校验四道硬关卡runCustomValidation在拿到 Agent 返回的 JSON 后sdk/typescript/src/custom-validation.ts会依次校验Schema 校验用 Ajv 2020 编译动态生成的 schema由candidate-validations.schema.json、scan-draft.schema.json、artifact-common.schema.json组合而成不匹配即抛错状态校验status必须为complete否则抛出reason候选完整性validations中的candidateId必须与候选集一一对应——重复、未知、遗漏都会报错unknown or duplicate candidate / omitted one or more candidates证据路径校验每个artifact_paths必须以artifacts/开头且对应文件真实存在于扫描目录内防止越权引用扫描目录之外的路径。任何一步失败SDK 都会把三个规范文件恢复为草稿原样并抛出IncompleteScanError从而让整个扫描以失败告终——绝不会带着残缺的自定义验证结果继续产出报告。5.3 disposition 如何驱动 coverage 与最终发现判定结果会回流并改写三份规范化文件sdk/typescript/src/custom-validation.tsdeferredcoverage.completeness置为partial并追加一条deferred记录原因取counterevidence_or_proof_gap/remaining_uncertainty/ 证据摘要对应 surface 的 disposition 变为needs_follow_upreportable候选 finding 被保留其validation、confidence用验证结果填充confidence.level来自验证返回的high/medium/low若返回了非null的severity/impact则同步更新并删除customValidationSurfaceIds扩展字段suppressedsurface 变为rejectednot_applicablesurface 变为not_applicable候选被压制的兜底判定。最终results.json与更新后的三份文件一起构成扫描产物findings.json里只保留真正reportable的发现。六、命令行与配置入口自定义验证通过--validation-prompt-file FILE启用相关入口分散在 CLI 与项目配置中入口位置说明codex-security scan --validation-prompt-file FILEsdk/typescript/src/cli.tsReplace final validation with the workflow in FILE (not Deep)即标准扫描专用Deep 扫描不支持重跑自定义验证扫描sdk/typescript/src/cli.ts已保存的扫描若validationMode custom重跑时必须再次提供--validation-prompt-file否则报错项目配置文件scan.validation_filesdk/typescript/src/project-config-schema.tsCustom validation instructions, relative to this file; not supported in active deep scans.导入扫描的限制sdk/typescript/src/cli.ts导入import的扫描不做安全分析不支持--validation-prompt-file/--scan-prompt-file提示词解析sdk/typescript/src/prompt-files.tsvalidationPrompt与validationPromptFile二选一读入后回填为内联文本配置文件中对应的 YAML 形如scan: validation_file: custom-validation/validation.md注意 sdk/typescript/src/multiscan.ts 的约束内联提示词与提示词文件不能同时为空/同时存在导致歧义且与--scan-prompt-file、--post-scan-prompt-file的配套关系会被统一校验。七、如何把这份协议移植到自己的项目examples/custom-validation/README.md 明确指出validation.md是可适配的模板Adapt validation.md for your own setup, tests, and cleanupDocker 项目则可以让同样的提示词改调 compose 或现有测试脚本。移植时建议遵循以下骨架1. 运行 你的验证命令例如 docker compose up --build 后执行测试脚本 从 仓库根 开始把证据输出到 artifacts/module/proof.json。 2. 说明你的测试环境边界允许启动哪些本地服务、禁止访问哪些外部资源、 是否需要安装依赖如需安装明确使用项目锁文件。 3. 定义控制组断言环境自身必须满足哪些前置条件服务可达、认证生效、 清理完成不满足则以 status: incomplete 返回原因。 4. 给出每个候选的判定规则 - reportable什么观测算确证对应本示例的 cross_account_read true - suppressed什么观测算否定403/404 等防御性响应 - deferred什么情况算无法定论。 要求解释实际观测并在 artifact_paths 引用证据文件。 5. 收尾纪律每个候选恰好一个结果无关候选显式给出证据缺口 severity/impact 默认 null不修改规范化扫描文件。同时要满足 SDK 端的硬性要求证据必须落在扫描目录内的artifacts/下artifact_paths使用相对路径以artifacts/开头候选集以candidates.json为准验证阶段不得增删改候选若验证无法执行或控制组失败务必返回status: incomplete与原因不要用源码分析冒充运行时验证保证扫描可无人工干预跑通因为 SDK 不会回退到默认验证流程。八、常见失败模式与排查要点结合 sdk/typescript/src/custom-validation.ts 的抛错点以下是实践中容易触发的失败失败模式触发条件定位线索草稿不合法validationMode不是custom_pending、草稿已封存、scanId不匹配The scan did not return an unsealed custom-validation draft.覆盖率/发现集非法coverage 含重复 surface ID、finding 不满足 schemaCustom validation requires valid provisional coverage.候选与 surface 不匹配已上报 surface 没有对应候选、候选引用未知 surfaceA reported coverage surface has no provisional finding.Schema 不符合返回 JSON 缺少必填字段或多出未知字段The custom validation output does not match its schema.状态非 complete验证脚本/控制组失败后仍返回incomplete之外的 statusThe custom validation workflow did not complete.候选数不符重复、未知或遗漏 candidateIdunknown or duplicate candidate / omitted one or more candidates.证据路径越界artifact_paths不以artifacts/开头或文件不存在Validation evidence must be stored under the scans artifacts directory.插件与 SDK 版本不匹配内置工作流文件哈希与 SDK 预期不一致Update the SDK and plugin together. Default validation was not started.最后一类失败尤其值得注意自定义验证对 SDK 与插件版本的耦合非常敏感升级时需保持二者同步sdk/typescript/src/custom-validation-prompt.ts 会对三份内置工作流文件做 SHA-256 校验。九、小结validation.md看似只有五句话实则是 codex-security 自定义验证能力的完整契约它规定了验证命令与输出位置步骤 1、测试边界与资源约束步骤 2、控制组断言与失败语义步骤 3、观测到判定的映射规则步骤 4、以及结构化返回与只读纪律步骤 5。SDK 侧custom-validation.ts、custom-validation-prompt.ts用候选集、动态 Schema、四道硬校验和 coverage 回流把这份自然语言协议落成了可审计、可复现、不可绕过的工程流程。对需要运行时证据的安全扫描场景——尤其是越权、鉴权缺失、SSRF 等行为型漏洞——这就是把疑似变成确证的标准姿势。想要进一步深入可继续阅读完整演示说明examples/custom-validation/README.md漏洞 fixtureexamples/custom-validation/app.mts证据脚本examples/custom-validation/validate.mts发现阶段提示词examples/custom-validation/scan.mdSDK 端核心实现sdk/typescript/src/custom-validation.ts工具禁用与握手逻辑sdk/typescript/src/custom-validation-prompt.ts相关 Schemaplugins/codex-security/schemas/tools/candidate-validations.schema.json、plugins/codex-security/schemas/tools/scan-draft.schema.json、plugins/codex-security/schemas/coverage.schema.json赞分享应用安全漏洞扫描AI 应用【免费下载链接】codex-securityOpenAIs Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/openai/codex-security项目地址https://gitcode.com/gh_mirrors/co/codex-security点击查看免费下载相关推荐Nginx Proxy Manager 证书管理实战HTTP 验证、DNS 验证与自定义证书全解析Nginx Proxy Manager 证书管理实战HTTP 验证、DNS 验证与自定义证书全解析 导读 本指南以 Nginx Proxy Manager 内后端API网关因子测试与分层回测3 个指标看懂你的策略到底灵不灵因子测试与分层回测3 个指标看懂你的策略到底灵不灵 跑量化回测最容易掉进一个坑曲线看着漂亮却不知道因子是真本事还是运气好。本文带你用「30天掌握量金融科技数据分析机器学习NetBox 自定义校验Custom Validation配置规则、自定义逻辑与删除保护实战指南NetBox 自定义校验Custom Validation配置规则、自定义逻辑与删除保护实战指南 导读 NetBox 在对象写入数据库之前会执行一套内置校后端网络数据建模创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考