Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

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.mts
index 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.ts
index 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.ts
index 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.ts
index 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.json
index 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.py
index 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.py
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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");