OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
fix(contract): constrain deferred coverage paths (#558)
Sylvester Kaczmarek7173ff4d3f04
diff --git a/plugins/codex-security/mcp-app/scripts/canonical-schemas.mts b/plugins/codex-security/mcp-app/scripts/canonical-schemas.mtsindex 51c53d2a3..01faef316 100644--- a/plugins/codex-security/mcp-app/scripts/canonical-schemas.mts+++ b/plugins/codex-security/mcp-app/scripts/canonical-schemas.mts@@ -242,6 +242,19 @@ const scanManifest = z.looseObject({}),});+// The empty branch always matches. A forbidden sequence matches both branches,+// so oneOf rejects it. This also works in Zod's JSON Schema importer.+const sealedDeferredPath = text.meta({+ oneOf: [+ {},+ {+ type: "string",+ $comment: "invalidSealedDeferredPath",+ pattern: String.raw`^(?:/|[A-Za-z]:)|(?:^|/)\.\.(?:/|$)|[\\\x00-\x1f]|[\ud800-\udbff](?![\udc00-\udfff])|(?:^|[^\ud800-\udbff])[\udc00-\udfff]`,+ },+ ],+});+const coverageDocument = z.looseObject({documentType: z.literal("codex-security.coverage"),schemaVersion: z.literal("1.0"),@@ -281,7 +294,7 @@ const coverageDocument = z.looseObject({z.looseObject({id: text,reason: text,- paths: textList.optional(),+ paths: z.array(sealedDeferredPath).optional(),surfaceIds: textList.optional(),}),),diff --git a/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts b/plugins/codex-security/mcp-app/src/artifact-scan-draft.tsindex c40a5824c..d098e2e04 100644--- a/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts+++ b/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts@@ -45,6 +45,23 @@ function canonicalFieldSchema(schema: object): z.ZodType {return z.fromJSONSchema(schema as Parameters<typeof z.fromJSONSchema>[0]);}+const deferredFields = coverageDocument.properties.deferred.items.properties;+function provisionalPaths(schema: Record<string, unknown>) {+ const items = schema.items;+ if (!isObject(items) || !Array.isArray(items.oneOf)) return schema;+ return {+ ...schema,+ items: {+ ...items,+ oneOf: items.oneOf.map((branch) =>+ isObject(branch) && branch.$comment === "invalidSealedDeferredPath"+ ? false+ : branch,+ ),+ },+ };+}+// Canonical files can retain fields that the compact tool input does not accept.const canonicalScanDraftInputSchema = fileScanDraftInputSchema.extend({scope: canonicalFieldSchema({@@ -79,6 +96,10 @@ const canonicalScanDraftInputSchema = fileScanDraftInputSchema.extend({...coverageDocument.properties.deferred,items: {...coverageDocument.properties.deferred.items,+ properties: {+ ...deferredFields,+ paths: provisionalPaths(deferredFields.paths),+ },required: z.toJSONSchema(draftDefinitions.coverage.shape.deferred.element,{ io: "input" },diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts b/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.tsindex 964776dc3..a1e6fbdf2 100644--- a/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts+++ b/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts@@ -508,6 +508,15 @@ test("worker checkpoints retain typed surface IDs", async (t) => {);});+test("parent: resume provisional deferred paths until the task is closed", async (t) => {+ const f = await fixture(t, "standard");+ const pending = { id: "review", ...generic, paths: ["../outside"] };+ await f.write(f.draft({ deferred: [pending] }));+ assert.deepEqual((await f.write(f.draft())).coverage.deferred, [pending]);+ await f.write(f.draft({ resolvedDeferred: [close(pending.id)] }, true));+ assert.deepEqual((await f.read()).deferred, []);+});+for (const observation of ["checkpoint head", "worker result"]) {test(`worker: reopening survives replacement of the ${observation} during a read`, async (t) => {const f = await fixture(t, "worker");diff --git a/plugins/codex-security/mcp-app/tests/test_canonical_artifact_contracts.ts b/plugins/codex-security/mcp-app/tests/test_canonical_artifact_contracts.tsindex b37f8e772..e1b618415 100644--- a/plugins/codex-security/mcp-app/tests/test_canonical_artifact_contracts.ts+++ b/plugins/codex-security/mcp-app/tests/test_canonical_artifact_contracts.ts@@ -1,5 +1,6 @@import assert from "node:assert/strict";import Ajv2020 from "ajv/dist/2020.js";+import * as z from "zod/v4";import { readJson } from "./support/json.ts";const ajv = new Ajv2020({ strict: false, validateFormats: false });@@ -140,6 +141,8 @@ for (const path of ["findings.json", "coverage.json"]) {assert.equal(manifest.validate(document), false);}const coverage = canonical.coverage;+const validateCoverage = new Ajv2020().compile(coverage.schema);+const coverageInZod = z.fromJSONSchema(coverage.schema);for (const fields of [{ deferred: [{ id: "task", reason: "Review remains." }] },{@@ -155,6 +158,37 @@ for (const fields of [])assert.equal(coverage.validate({ ...coverage.example, ...fields }), true);+for (const [path, valid] of [+ [".", true],+ ["./src//./name:part/", true],+ [" ", true],+ ["\u0085", true],+ ["\ufeff", true],+ ["src/\u007f", true],+ ["src/..\u2028", true],+ ["src/\u2029emoji-😀", true],+ ["", false],+ ["..", false],+ ["src/../outside", false],+ ["src/\u2028/..", false],+ ["/absolute", false],+ ["C:relative", false],+ ["src\\file", false],+ ["name\n", false],+ ["src/\u0000file", false],+ ["\ud800", false],+ ["\udfff", false],+] as const) {+ const deferred = [{ id: "task", reason: "Review remains.", paths: [path] }];+ const document = { ...coverage.example, deferred };+ assert.equal(validateCoverage(document), valid, JSON.stringify(path));+ assert.equal(+ coverageInZod.safeParse(document).success,+ valid,+ JSON.stringify(path),+ );+}+// Shared named definitions remain available to consumers that extract fragments.assert.deepEqual(Object.keys(findingSchema.$defs).sort(), ["assessment",diff --git a/plugins/codex-security/schemas/coverage.schema.json b/plugins/codex-security/schemas/coverage.schema.jsonindex 033023fc8..5fdbd9963 100644--- a/plugins/codex-security/schemas/coverage.schema.json+++ b/plugins/codex-security/schemas/coverage.schema.json@@ -73,7 +73,18 @@"reason": { "type": "string", "minLength": 1 },"paths": {"type": "array",- "items": { "type": "string", "minLength": 1 }+ "items": {+ "type": "string",+ "minLength": 1,+ "oneOf": [+ {},+ {+ "type": "string",+ "$comment": "invalidSealedDeferredPath",+ "pattern": "^(?:/|[A-Za-z]:)|(?:^|/)\\.\\.(?:/|$)|[\\\\\\x00-\\x1f]|[\\ud800-\\udbff](?![\\udc00-\\udfff])|(?:^|[^\\ud800-\\udbff])[\\udc00-\\udfff]"+ }+ ]+ }},"surfaceIds": {"type": "array",diff --git a/plugins/codex-security/scripts/finalize_scan_contract.py b/plugins/codex-security/scripts/finalize_scan_contract.pyindex 0917daf8c..608beb260 100644--- a/plugins/codex-security/scripts/finalize_scan_contract.py+++ b/plugins/codex-security/scripts/finalize_scan_contract.py@@ -1971,6 +1971,21 @@ def _resolve_schema_reference(return target+def _matches_sealed_path_exclusion(value: str, one_of: Any) -> bool:+ # The empty alternative always matches, so a path must not match the second one.+ if not isinstance(one_of, list) or len(one_of) != 2 or one_of[0] != {}:+ return False+ excluded = one_of[1]+ return (+ isinstance(excluded, dict)+ and excluded.keys() == {"$comment", "type", "pattern"}+ and excluded["$comment"] == "invalidSealedDeferredPath"+ and excluded["type"] == "string"+ and isinstance(excluded["pattern"], str)+ and re.search(excluded["pattern"], value) is not None+ )++def _validate_schema_node(value: Any,schema: dict[str, Any],@@ -2020,6 +2035,8 @@ def _validate_schema_node(raise ContractError(f"{context}: string is too long")if "pattern" in schema and not re.search(schema["pattern"], value):raise ContractError(f"{context}: string does not match schema pattern")+ if _matches_sealed_path_exclusion(value, schema.get("oneOf")):+ raise ContractError(f"{context}: string matches excluded schema pattern")if schema.get("format") == "date-time":_validate_date_time(value, context)if isinstance(value, (int, float)) and not isinstance(value, bool):diff --git a/plugins/codex-security/tests/test_saved_deferred_identity.py b/plugins/codex-security/tests/test_saved_deferred_identity.pyindex baf160a33..d7e57510a 100644--- a/plugins/codex-security/tests/test_saved_deferred_identity.py+++ b/plugins/codex-security/tests/test_saved_deferred_identity.py@@ -575,6 +575,26 @@ def test_accepted_generic_update_keeps_its_id_in_frozen_recovery(tmp_path: Path,assert all(path.read_bytes() == contents for path, contents in originals.items())+def test_unsafe_deferred_update_keeps_the_earlier_valid_path(tmp_path: Path) -> None:+ state, codex_home, _, scan_dir, scan_id = deep_scan_fixture(tmp_path)+ _, result = accepted_standard_worker(state, codex_home, scan_dir, scan_id)+ original = {"id": "review", "reason": "Review remains.", "paths": ["app.py"]}+ checkpoint = write_checkpoint(+ result.parent / "checkpoints", saved_draft(scan_id, deferred=[original])+ )+ os.utime(checkpoint, ns=(100, 100))+ update = {**original, "paths": ["../outside.py"]}+ result.write_text(json.dumps(saved_draft(scan_id, deferred=[update])))+ os.utime(result, ns=(200, 200))++ fail_deep_scan(state, codex_home, scan_id, deep_status="failed")++ coverage = json.loads((scan_dir / "coverage.json").read_text())+ assert [row["paths"] for row in coverage["deferred"] if "paths" in row] == [["app.py"]]+ warnings = json.loads((scan_dir / "scan-manifest.json").read_text())["scan"]["warnings"]+ assert any("expected a safe repository-relative POSIX path" in warning for warning in warnings)++def test_unnamed_changed_observation_stays_pending(tmp_path: Path, saved_results):generic = {"reason": "Review remains.", "paths": ["api.py"], "notes": "Initial review."}identity = "source-review"diff --git a/sdk/typescript/src/contract.ts b/sdk/typescript/src/contract.tsindex 6cb9125c8..efde911c0 100644--- a/sdk/typescript/src/contract.ts+++ b/sdk/typescript/src/contract.ts@@ -65,6 +65,9 @@ export interface LoadedContract {export class ContractSchemaError extends ContractValidationError {}+export const SEALED_DEFERRED_PATH_RULE = "invalidSealedDeferredPath";+export const DEFERRED_PATH_LOCATION = /^\/deferred\/(\d+)\/paths\/(\d+)$/u;+type LoadContractOptions = {pluginRoot: string;expectedScanId?: string;@@ -912,7 +915,7 @@ async function loadContractValidators(// The plugin schemas are the immutable v0 contract. They are valid Draft// 2020-12 but intentionally omit redundant local `type` keywords that Ajv's// optional strict-schema linter requires.- const ajv = new Ajv2020({ allErrors: false, strict: false });+ const ajv = new Ajv2020({ allErrors: false, strict: false, verbose: true });ajv.addFormat("date-time", {type: "string",validate: validRfc3339DateTime,@@ -1096,6 +1099,23 @@ function schemaError(errors: readonly ErrorObject[],): ContractValidationError {const first = errors[0];+ if (+ filename === "coverage.json" &&+ first?.keyword === "oneOf" &&+ Array.isArray(first.schema) &&+ first.schema.some(+ (rule, index) =>+ isRecord(rule) &&+ rule["$comment"] === SEALED_DEFERRED_PATH_RULE &&+ first.params["passingSchemas"]?.includes(index),+ )+ ) {+ const match = DEFERRED_PATH_LOCATION.exec(first.instancePath);+ if (match)+ return new ContractValidationError(+ `coverage.deferred[${match[1]}].paths[${match[2]}]: expected a safe repository-relative POSIX path.`,+ );+ }const location = first?.instancePath? JSON.stringify(first.instancePath): "<root>";diff --git a/sdk/typescript/src/custom-validation.ts b/sdk/typescript/src/custom-validation.tsindex d4a1797c0..a654a83cd 100644--- a/sdk/typescript/src/custom-validation.ts+++ b/sdk/typescript/src/custom-validation.ts@@ -8,10 +8,16 @@ import {writeFile,} from "node:fs/promises";import { basename, dirname, join } from "node:path";-import Ajv2020 from "ajv/dist/2020.js";-import { readScanFile, requireScanFile } from "./contract.js";+import Ajv2020, { _, type CodeKeywordDefinition } from "ajv/dist/2020.js";+import {+ DEFERRED_PATH_LOCATION,+ readScanFile,+ requireScanFile,+ SEALED_DEFERRED_PATH_RULE,+} from "./contract.js";import { IncompleteScanError, errorMessage } from "./errors.js";import type { CoverageDocument, FindingsDocument } from "./models.js";+import { isRecord } from "./record.js";import { requirePrivateOutputDirectory } from "./runtime.js";import type { NormalizedTarget } from "./targets.js";@@ -234,6 +240,35 @@ export async function runCustomValidation(options: {]);const schema = customValidationSchema(common, candidatesSchema, draft);const ajv = new Ajv2020({ strict: false, validateFormats: false });+ // Skip the sealed oneOf only at provisional paths. Plugins may also $ref+ // either branch on its own, where it must retain its ordinary meaning.+ const oneOf = ajv.getKeyword("oneOf") as CodeKeywordDefinition;+ ajv.removeKeyword("oneOf").addKeyword({+ ...oneOf,+ before: "allOf",+ code(cxt) {+ const branches: unknown[] = cxt.schema;+ const [empty, forbidden] = branches;+ if (+ branches.length !== 2 ||+ !isRecord(empty) ||+ Object.keys(empty).length !== 0 ||+ !isRecord(forbidden) ||+ forbidden["$comment"] !== SEALED_DEFERRED_PATH_RULE+ ) {+ return oneOf.code(cxt);+ }+ const enforce = cxt.gen.scopeValue("func", {+ ref: (root: unknown, path: string) =>+ root !== coverage || !DEFERRED_PATH_LOCATION.test(path),+ });+ cxt.gen.if(+ _`${enforce}(rootData, instancePath + ${cxt.it.errorPath})`,+ () => cxt.gen.block(() => oneOf.code(cxt)),+ );+ cxt.ok(_`errors === ${cxt.errsCount!}`);+ },+ });ajv.addSchema(common).addSchema(draft);const validFinding = ajv.compile({ $ref: `${draft.$id}#/$defs/finding` });if (!ajv.validate(coverageSchema, coverage))diff --git a/sdk/typescript/tests-ts/contract.test.ts b/sdk/typescript/tests-ts/contract.test.tsindex 48b444a65..ffae199a0 100644--- a/sdk/typescript/tests-ts/contract.test.ts+++ b/sdk/typescript/tests-ts/contract.test.ts@@ -1082,14 +1082,23 @@ describe("canonical scan contract", () => {const coveragePath = join(scanDir, "coverage.json");const coverage = await readJson(coveragePath);coverage["deferred"] = [- { id: "review", reason: "Review is incomplete.", paths: [path] },+ { id: "earlier", reason: "Follow up.", paths: ["src/earlier.ts"] },+ {+ id: "review",+ reason: "Review is incomplete.",+ paths: ["src/valid.ts", path],+ },];await writeJson(coveragePath, coverage);await reseal(scanDir);await expect(loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),- ).rejects.toThrow(/coverage.*deferred/);+ ).rejects.toThrow(+ path === ""+ ? /coverage.*\/deferred\/1\/paths\/1/+ : "coverage.deferred[1].paths[1]: expected a safe repository-relative POSIX path.",+ );}});diff --git a/sdk/typescript/tests-ts/custom-validation.test.ts b/sdk/typescript/tests-ts/custom-validation.test.tsindex afda2efae..29d3ef103 100644--- a/sdk/typescript/tests-ts/custom-validation.test.ts+++ b/sdk/typescript/tests-ts/custom-validation.test.ts@@ -1,6 +1,7 @@import { execFileSync } from "node:child_process";import { randomUUID } from "node:crypto";import {+ cp,mkdir,readFile,rename,@@ -641,6 +642,99 @@ describe("custom validation", () => {},);+ test.each([+ ["bundled", ""],+ ["unmarked oneOf", "coverage/deferred/0/paths/1"],+ ["additional pattern", "coverage/deferred/0/paths/1"],+ ["referenced array", "coverage/checkedPaths"],+ ["conditional", "must have required property 'reviewReceipt'"],+ ["referenced predicate", "must have required property 'reviewReceipt'"],+ ])(+ "honors %s deferred path rules before custom validation",+ async (rules, expectedError) => {+ const f = await fixture();+ const path = join(f.scanDir, "coverage.json");+ const coverage = await json<CoverageDocument>(path);+ coverage.deferred = [+ {+ id: "pending",+ reason: "Review pending.",+ paths: ["src/valid", "../outside"],+ },+ ];+ await save(path, coverage);+ const run = mock(async () => JSON.stringify(result("reportable")));+ if (rules === "bundled") {+ await runCustomValidation({ ...f, run });+ expect(run).toHaveBeenCalledTimes(1);+ expect((await json<CoverageDocument>(path)).deferred).toEqual(+ coverage.deferred,+ );+ return;+ }+ const pluginRoot = join(f.root, "plugin");+ await cp(join(f.pluginRoot, "schemas"), join(pluginRoot, "schemas"), {+ recursive: true,+ });+ const schemaPath = join(pluginRoot, "schemas", "coverage.schema.json");+ const schema = JSON.parse(await readFile(schemaPath, "utf8"));+ const deferred = schema.properties.deferred.items;+ const paths = deferred.properties.paths;+ if (rules === "unmarked oneOf") delete paths.items.oneOf[1].$comment;+ if (rules === "additional pattern") paths.items.pattern = "^src/";+ if (rules === "referenced array") {+ schema.$id = "relative/coverage.json";+ paths.$id = "deferred-paths.json";+ schema.$defs = { ...schema.$defs, sharedPaths: paths };+ schema.properties.deferred.items.properties.paths = {+ $ref: "#/$defs/sharedPaths",+ };+ schema.properties.checkedPaths = {+ anyOf: [{ $ref: "#/$defs/sharedPaths" }, { type: "null" }],+ };+ await save(path, {+ ...coverage,+ checkedPaths: ["src/other", "../outside"],+ });+ }+ if (rules === "conditional") {+ schema.if = {+ properties: { deferred: { $ref: "#/properties/deferred" } },+ };+ schema.then = { required: ["reviewReceipt"] };+ }+ if (rules === "referenced predicate") {+ deferred.properties.reviewReceipt = { type: "boolean" };+ deferred.if = {+ properties: {+ paths: {+ contains: {+ $ref: "#/properties/deferred/items/properties/paths/items/oneOf/1",+ },+ },+ },+ };+ deferred.then = { required: ["reviewReceipt"] };+ }+ await save(schemaPath, schema);+ await expect(+ runCustomValidation({ ...f, pluginRoot, run }),+ ).rejects.toThrow(expectedError);+ expect(run).not.toHaveBeenCalled();+ if (rules === "referenced array" || rules === "referenced predicate") {+ if (rules === "referenced array")+ Object.assign(coverage, { checkedPaths: ["src/other"] });+ else Object.assign(coverage.deferred[0]!, { reviewReceipt: true });+ await save(path, coverage);+ await runCustomValidation({ ...f, pluginRoot, run });+ expect(run).toHaveBeenCalledTimes(1);+ expect((await json<CoverageDocument>(path)).deferred).toEqual(+ coverage.deferred,+ );+ }+ },+ );+test("identifies invalid provisional coverage before validation", async () => {const f = await fixture();const path = join(f.scanDir, "coverage.json");