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
import { setFindingIdentity, sha256 } from "./support/finding-identity.js";
import type { Stats } from "node:fs";
import { createRequire } from "node:module";
import {
chmod,
cp,
lstat,
mkdir,
readFile,
realpath,
rename,
symlink,
type FileHandle,
writeFile,
} from "node:fs/promises";
import { dirname, join } from "node:path";
import { afterEach, describe, expect, test, mock, spyOn } from "bun:test";
import { ContractValidationError, loadContract } from "../src/index.js";
import {
loadContractWithScanDirectory,
readScanFile,
sameCheckedFileDevice,
validatedFileDigests,
} from "../src/contract.js";
import type { NormalizedTarget, ScanExpectation } from "../src/index.js";
import { PLUGIN_ROOT } from "./plugin-root.js";
import { useTestPython } from "./support/python.js";
import { runPython } from "./support/python-probe.js";
import { createContractTestFixtures } from "./support/contract-fixture.js";
import { readJson as readJsonFile, writeJson } from "./support/json.js";
import { runTestInSubprocess } from "./support/test-subprocess.js";
const pythonExecutable = useTestPython();
const EXAMPLE = join(PLUGIN_ROOT, "examples", "legacy-completed-scan");
const { temporaryDirectory, cleanup, copyExample } =
createContractTestFixtures();
afterEach(cleanup);
const readJson = readJsonFile<Record<string, any>>;
async function reseal(scanDir: string): Promise<void> {
const manifestPath = join(scanDir, "scan-manifest.json");
const manifest = await readJson(manifestPath);
for (const artifact of manifest["scan"]["artifacts"]) {
const path = join(scanDir, artifact["path"]);
try {
artifact["sha256"] = sha256(await readFile(path));
} catch {}
}
await writeJson(manifestPath, manifest);
}
function pythonExport(scanDir: string) {
return runPython(pythonExecutable() ?? "python", [
join(PLUGIN_ROOT, "scripts", "finalize_scan_contract.py"),
"--scan-dir",
scanDir,
"--export-format",
"json",
]);
}
function expectation(
target: NormalizedTarget,
mode: "standard" | "deep" = "standard",
): ScanExpectation {
return {
repository: dirname(target.paths[0] ?? "/tmp"),
repositoryRevision: "deadbeef",
target,
mode,
pluginVersion: "0.1.0",
};
}
describe("canonical scan contract", () => {
test("re-finalizing an imported bundle preserves its sealed projections", async () => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const manifest = await readJson(manifestPath);
const projections = ["report.md", "report.html", "exports/results.sarif"];
for (const path of projections) {
await mkdir(dirname(join(scanDir, path)), { recursive: true });
await writeFile(join(scanDir, path), path);
manifest["scan"].artifacts.push({
path,
sha256: sha256(path),
mediaType: "text/plain",
});
}
await writeJson(manifestPath, manifest);
await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
const result = runPython(pythonExecutable() ?? "python", [
join(PLUGIN_ROOT, "scripts", "finalize_scan_contract.py"),
"--scan-dir",
scanDir,
]);
expect(result.exitCode, new TextDecoder().decode(result.stderr)).toBe(0);
for (const path of projections)
expect(await readFile(join(scanDir, path), "utf8")).toBe(path);
await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
});
test.each([
"duplicate finding",
"blank title",
"inverted range",
"backslash remote",
])("both readers reject %s in a sealed contract", async (variant) => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
const manifestPath = join(scanDir, "scan-manifest.json");
const manifest = await readJson(manifestPath);
if (variant === "duplicate finding")
findings["findings"].push(structuredClone(findings["findings"][0]));
if (variant === "blank title") findings["findings"][0].title = " ";
if (variant === "inverted range")
Object.assign(findings["findings"][0].locations[0], {
startLine: 10,
endLine: 2,
});
if (variant === "backslash remote")
manifest["scan"].target.remote = "https://example.com/repository\\path";
await writeJson(findingsPath, findings);
await writeJson(manifestPath, manifest);
await reseal(scanDir);
const result = runPython(pythonExecutable() ?? "python", [
"-c",
"import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); from finalize_scan_contract import _prepare_scan_finalization; _prepare_scan_finalization(Path(sys.argv[2]))",
join(PLUGIN_ROOT, "scripts"),
scanDir,
]);
expect(result.exitCode, new TextDecoder().decode(result.stderr)).not.toBe(
0,
);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toBeInstanceOf(ContractValidationError);
});
test("compares exact Windows volume serials without rounding file identity", async () => {
const scanDir = await copyExample();
const path = join(scanDir, "scan-manifest.json");
const metadata = await lstat(path);
const identity = await lstat(path, { bigint: true });
const volume = BigInt.asUintN(32, identity.dev);
const highDevice = (1n << 60n) | volume;
expect(highDevice).toBeGreaterThan(BigInt(Number.MAX_SAFE_INTEGER));
let device = highDevice;
let inode = identity.ino;
let regular = true;
let inspected = 0;
let referenceDevice = highDevice;
let referenceInode = identity.ino;
let referenceRegular = true;
const closeMock = mock(async () => {});
const file = {
stat: async () => {
inspected += 1;
return {
dev: device,
ino: inode,
isFile: () => regular,
};
},
} as unknown as FileHandle;
const reference = {
stat: async () => ({
dev: referenceDevice,
ino: referenceInode,
isFile: () => referenceRegular,
}),
close: closeMock,
} as unknown as FileHandle;
const openReference = async () => reference;
const checked = { path, metadata, parents: [] };
const opened = { dev: Number(highDevice), ino: metadata.ino } as Stats;
await expect(
sameCheckedFileDevice(file, checked, opened, "win32", openReference),
).resolves.toBe(true);
expect(closeMock).toHaveBeenCalledTimes(1);
const inconsistentNumberInode = {
dev: metadata.dev,
ino: metadata.ino + 1024,
} as Stats;
await expect(
sameCheckedFileDevice(
file,
checked,
inconsistentNumberInode,
"win32",
openReference,
),
).resolves.toBe(false);
device = highDevice ^ 1n;
await expect(
sameCheckedFileDevice(file, checked, opened, "win32", openReference),
).resolves.toBe(false);
expect(closeMock).toHaveBeenCalledTimes(2);
referenceDevice = device;
await expect(
sameCheckedFileDevice(file, checked, opened, "win32", openReference),
).resolves.toBe(true);
expect(closeMock).toHaveBeenCalledTimes(3);
device = highDevice;
referenceDevice = highDevice;
inode = identity.ino + 1n;
await expect(
sameCheckedFileDevice(file, checked, opened, "win32", openReference),
).resolves.toBe(false);
inode = identity.ino;
regular = false;
await expect(
sameCheckedFileDevice(file, checked, opened, "win32", openReference),
).resolves.toBe(false);
regular = true;
referenceInode = identity.ino + 1n;
await expect(
sameCheckedFileDevice(file, checked, opened, "win32", openReference),
).resolves.toBe(false);
referenceInode = identity.ino;
referenceRegular = false;
await expect(
sameCheckedFileDevice(file, checked, opened, "win32", openReference),
).resolves.toBe(false);
const windowsInspections = inspected;
await expect(
sameCheckedFileDevice(file, checked, opened, "linux", openReference),
).resolves.toBe(false);
expect(inspected).toBe(windowsInspections);
device = referenceDevice = highDevice;
inode = referenceInode = identity.ino;
regular = referenceRegular = true;
await expect(
sameCheckedFileDevice(
file,
{ path, metadata: identity },
{ dev: highDevice, ino: identity.ino },
"win32",
openReference,
),
).resolves.toBe(true);
const largeInode = 2n ** 60n;
expect(Number(largeInode)).toBe(Number(largeInode + 1n));
await expect(
sameCheckedFileDevice(
file,
{ path, metadata: { dev: identity.dev, ino: largeInode } },
{ dev: identity.dev, ino: largeInode + 1n },
),
).resolves.toBe(false);
});
// macOS can reject the unreadable path before the checked open.
test.skipIf(process.platform !== "linux" || process.geteuid?.() === 0)(
"reports the permission error when opening an unreadable scan file",
async () => {
const scanDir = await realpath(await temporaryDirectory());
const path = join(scanDir, "report.md");
await writeFile(path, "Scan report", { mode: 0o000 });
const reading = readScanFile(scanDir, "report.md", "scan report");
await expect(reading).rejects.toBeInstanceOf(ContractValidationError);
await expect(reading).rejects.toMatchObject({
message: expect.stringContaining(
"scan report: unable to open the checked regular file.",
),
cause: expect.objectContaining({ code: "EACCES", path }),
});
},
);
test.skipIf(process.platform === "win32")(
"rejects scan root replacement when numeric directory IDs collide",
async () => {
const title =
"rejects scan root replacement when numeric directory IDs collide";
if (runTestInSubprocess(import.meta.path, title)) return;
const scanDir = await realpath(await copyExample());
const before = 2n ** 60n;
const after = before + 1n;
expect(Number(before)).toBe(Number(after));
const files: typeof import("node:fs/promises") = createRequire(
import.meta.url,
)("node:fs/promises");
const original = { lstat: files.lstat, realpath: files.realpath };
let replaced = false;
const inspecting = spyOn(files, "lstat").mockImplementation((async (
...args: Parameters<typeof original.lstat>
) => {
const metadata = await original.lstat(...args);
if (args[0].toString() === scanDir) {
const identity = replaced ? after : before;
Object.defineProperty(metadata, "ino", {
value:
typeof metadata.ino === "bigint" ? identity : Number(identity),
});
}
return metadata;
}) as typeof original.lstat);
const resolving = spyOn(files, "realpath").mockImplementation((async (
...args: Parameters<typeof original.realpath>
) => {
const canonical = await original.realpath(...args);
if (args[0].toString() === scanDir && !replaced) {
replaced = true;
await rename(scanDir, `${scanDir}.original`);
await mkdir(scanDir, { mode: 0o700 });
}
return canonical;
}) as typeof original.realpath);
try {
await expect(
readScanFile(scanDir, "coverage.json", "coverage.json"),
).rejects.toThrow(
"Scan directory must be an existing non-symlink directory",
);
expect(replaced).toBe(true);
} finally {
resolving.mockRestore();
inspecting.mockRestore();
}
},
);
test("loads the unchanged plugin example with typed canonical names", async () => {
const scanDir = await copyExample();
const contract = await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
expect(contract.manifest.documentType).toBe("codex-security.scan-manifest");
expect(contract.manifest.scan.target.targetId).toBe(
"target_sha256_example",
);
expect(contract.findings.findings[0]?.severity.level).toBe("high");
expect(contract.review).toEqual({ excludedPaths: [] });
expect(contract.findings.scanId).toBe(contract.manifest.scan.id);
});
test("loads structured models with historical metadata extensions unchanged", async () => {
const scanDir = await copyExample();
const path = join(scanDir, "scan-manifest.json");
const manifest = await readJson(path);
for (const extensions of [
{ scope: "Repository-wide", origin: "legacy-import" },
{ scope: { includePaths: 42 }, origin: { tool: "legacy" } },
]) {
const model = { summary: "Existing structured model.", ...extensions };
manifest["scan"]["threatModel"] = model;
await writeJson(path, manifest);
const original = await readFile(path, "utf8");
const contract = await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
expect(contract.manifest.scan.threatModel).toEqual(model);
expect(await readFile(path, "utf8")).toBe(original);
}
});
test("preserves schema-valid sealed finding details", async () => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
const validation = {
evidence: "single proof",
counterEvidence: [],
status: null,
disposition: null,
result: null,
};
findings["findings"][0]["validation"] = validation;
findings["findings"][0]["code_evidence"] = null;
await writeJson(findingsPath, findings);
await reseal(scanDir);
const loaded = await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
expect(loaded.findings.findings[0]?.validation).toEqual(validation);
expect(loaded.findings.findings[0]?.code_evidence).toBeNull();
expect(await readJson(findingsPath)).toEqual(findings);
});
test("preserves valid details while normalizing malformed legacy siblings", async () => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
const validation = {
evidence: "single proof",
counterEvidence: [],
status: null,
disposition: null,
result: null,
};
findings["findings"][0]["validation"] = validation;
const codeEvidence = [{ id: " ", code: " " }];
findings["findings"][0]["code_evidence"] = codeEvidence;
findings["findings"][0]["attackPath"] = {
steps: { first: "upload" },
};
await writeJson(findingsPath, findings);
await reseal(scanDir);
const loaded = await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
expect(loaded.findings.findings[0]?.validation).toEqual(validation);
expect(loaded.findings.findings[0]?.code_evidence).toEqual(codeEvidence);
expect(loaded.findings.findings[0]?.attackPath?.steps).toBeUndefined();
expect(await readJson(findingsPath)).toEqual(findings);
});
test("preserves empty union lists while normalizing malformed siblings", async () => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
findings["findings"][0]["validation"] = { evidence: [] };
findings["findings"][0]["attackPath"] = {
steps: { first: "upload" },
};
await writeJson(findingsPath, findings);
await reseal(scanDir);
const loaded = await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
expect(loaded.findings.findings[0]?.validation?.evidence).toEqual([]);
expect(loaded.findings.findings[0]?.attackPath?.steps).toBeUndefined();
expect(await readJson(findingsPath)).toEqual(findings);
});
test("normalizes pre-typed sealed finding details without changing the artifact", async () => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
const legacyValidation = {
evidence: { kind: "trace" },
counterEvidence: [null, "The mitigation was checked."],
};
const legacyAttackPath = { steps: { first: "upload" } };
findings["findings"][0]["validation"] = legacyValidation;
findings["findings"][0]["attackPath"] = legacyAttackPath;
findings["findings"][0]["root_cause"] = null;
findings["findings"][0]["rootCause"] = {
summary: "Synthetic legacy details.",
evidenceRefs: [null, "evidence/source.md", 2],
};
findings["findings"][0]["code_evidence"] = [
{ id: "legacy-source", code: "legacy_source()" },
];
await writeJson(findingsPath, findings);
await reseal(scanDir);
const originalBytes = await readFile(findingsPath);
const result = await loadContractWithScanDirectory(scanDir, {
pluginRoot: PLUGIN_ROOT,
});
expect(Object.keys(result).sort()).toEqual(["contract", "scanDirectory"]);
const loaded = result.contract;
expect(
validatedFileDigests.get(loaded.manifest)?.get("findings.json"),
).toBe(sha256(originalBytes));
expect(loaded.findings.findings[0]?.code_evidence?.[0]?.id).toBe(
"legacy-source",
);
const loadedFinding = loaded.findings.findings[0];
expect(loadedFinding?.validation?.evidence).toBeUndefined();
expect(
loadedFinding?.validation?.counterEvidence?.map((item) =>
item.toUpperCase(),
),
).toEqual(["THE MITIGATION WAS CHECKED."]);
expect(loadedFinding?.attackPath?.steps).toBeUndefined();
expect(loadedFinding?.root_cause).toBeNull();
expect(loadedFinding?.rootCause).toEqual({
summary: "Synthetic legacy details.",
evidenceRefs: ["evidence/source.md"],
});
expect(await readJson(findingsPath)).toEqual(findings);
});
test("rejects malformed canonical root-cause details", async () => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
findings["findings"][0]["rootCause"] = { summary: [] };
await writeJson(findingsPath, findings);
await reseal(scanDir);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow("findings.json");
expect(await readJson(findingsPath)).toEqual(findings);
});
test.each(["directory_snapshot", "git_worktree", "git_diff"])(
"both readers accept an empty unused revision for %s",
async (kind) => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const manifest = await readJson(manifestPath);
manifest["scan"]["target"]["kind"] = kind;
manifest["scan"]["target"]["revision"] = "";
await writeJson(manifestPath, manifest);
const result = runPython(pythonExecutable() ?? "python", [
join(PLUGIN_ROOT, "scripts", "finalize_scan_contract.py"),
"--scan-dir",
scanDir,
]);
expect(result.exitCode, new TextDecoder().decode(result.stderr)).toBe(0);
await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
},
);
test.each(["rootCause", "root_cause"])(
"reads legacy %s evidence references in both readers without rewriting the seal",
async (section) => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
findings["findings"][0]["code_evidence"] = [
{ id: "synthetic-evidence", code: "handler()" },
];
findings["findings"][0][section] = {
summary: "Synthetic root cause.",
evidenceRefs: [null, "synthetic-evidence", 3],
};
await writeJson(findingsPath, findings);
await reseal(scanDir);
const bytes = await readFile(findingsPath);
const exported = pythonExport(scanDir);
expect(exported.exitCode, new TextDecoder().decode(exported.stderr)).toBe(
0,
);
const loaded = await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
expect(loaded.findings.findings[0]?.[section as "rootCause"]).toEqual({
summary: "Synthetic root cause.",
evidenceRefs: ["synthetic-evidence"],
});
expect(await readFile(findingsPath)).toEqual(bytes);
},
);
test("rejects duplicate sealed findings in both readers", async () => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
findings["findings"].push(structuredClone(findings["findings"][0]));
await writeJson(findingsPath, findings);
await reseal(scanDir);
expect(pythonExport(scanDir).exitCode).not.toBe(0);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow("duplicate finding");
});
test.each([
["title", " \t\n", false],
["summary", " \t\n", false],
["remediation", " \t\n", false],
["confidence.rationale", " \t\n", false],
["taxonomy.category", " \t\n", false],
["provenance.source", " \t\n", false],
["severity.scoringSystem", " \t\n", false],
["severity.scoringSystem", undefined, false],
["title", "\u0085\u001c", false],
["title", "\ufeff", true],
["title", " Synthetic required text. \n", true],
] as const)(
"agrees with Python on required finding text %s %j",
async (field, text, valid) => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
const finding = findings["findings"][0];
finding["severity"]["score"] = 5;
finding["severity"]["scoringSystem"] = "synthetic";
const parts = field.split(".");
const object = parts.length === 1 ? finding : finding[parts[0]!];
object[parts.at(-1)!] = text;
await writeJson(findingsPath, findings);
await reseal(scanDir);
const exported = pythonExport(scanDir);
expect(exported.exitCode === 0).toBe(valid);
const loaded = loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
if (valid) {
await expect(loaded).resolves.toBeDefined();
expect(JSON.parse(new TextDecoder().decode(exported.stdout))).toEqual(
findings,
);
} else {
await expect(loaded).rejects.toThrow("non-empty string");
}
expect(await readJson(findingsPath)).toEqual(findings);
},
);
test.each(["scan-manifest.json", "findings.json", "coverage.json"])(
"reads a UTF-8 BOM in sealed %s without changing its bytes",
async (filename) => {
const scanDir = await copyExample();
const path = join(scanDir, filename);
const bytes = Buffer.concat([
Buffer.from([0xef, 0xbb, 0xbf]),
await readFile(path),
]);
await writeFile(path, bytes);
if (filename !== "scan-manifest.json") await reseal(scanDir);
const exported = pythonExport(scanDir);
expect(exported.exitCode, new TextDecoder().decode(exported.stderr)).toBe(
0,
);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).resolves.toBeDefined();
expect(await readFile(path)).toEqual(bytes);
},
);
test.each([
"\\",
"\t",
"\n",
"\r",
"\u0000",
"\u001b",
"\u007f",
"\u0085",
"\u2028",
"\u2029",
])(
"rejects noncanonical remote character %j in both readers",
async (character) => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const manifest = await readJson(manifestPath);
manifest["scan"]["target"]["remote"] =
`https://example.test/synthetic/repo${character}name`;
await writeJson(manifestPath, manifest);
expect(pythonExport(scanDir).exitCode).not.toBe(0);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow("canonical absolute URL");
},
);
test("loads an empty legacy root cause without changing the artifact", async () => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
findings["findings"][0]["root_cause"] = "";
await writeJson(findingsPath, findings);
await reseal(scanDir);
const loaded = await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
expect(loaded.findings.findings[0]?.root_cause).toBe("");
expect(await readJson(findingsPath)).toEqual(findings);
});
test("honors cancellation during contract validation", async () => {
const scanDir = await copyExample();
const controller = new AbortController();
controller.abort(new DOMException("canceled", "AbortError"));
await expect(
loadContract(scanDir, {
pluginRoot: PLUGIN_ROOT,
signal: controller.signal,
}),
).rejects.toMatchObject({ name: "AbortError" });
});
test.skipIf(process.platform === "win32").each([0o755, 0o775])(
"reads a scan directory with mode %o without changing its permissions",
async (mode) => {
const scanDir = await copyExample();
await chmod(scanDir, mode);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).resolves.toBeDefined();
const exported = pythonExport(scanDir);
expect(exported.exitCode, new TextDecoder().decode(exported.stderr)).toBe(
0,
);
expect((await lstat(scanDir)).mode & 0o777).toBe(mode);
},
);
test.skipIf(process.platform === "win32")(
"rejects a private scan beneath an insecure shared ancestor",
async () => {
const scanDir = await copyExample();
const parent = dirname(scanDir);
await chmod(parent, 0o777);
try {
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow("sticky bit");
} finally {
await chmod(parent, 0o700);
}
},
);
test.skipIf(process.platform === "win32")(
"accepts a scan directory beneath a symlinked parent",
async () => {
const root = await temporaryDirectory("codex-security-contract-link-");
const parent = join(root, "actual-parent");
const linkedParent = join(root, "linked-parent");
await mkdir(parent, { mode: 0o700 });
const scanDir = join(parent, "scan");
await cp(EXAMPLE, scanDir, { recursive: true });
if (process.platform !== "win32") await chmod(scanDir, 0o700);
await symlink(parent, linkedParent);
await expect(
loadContract(join(linkedParent, "scan"), { pluginRoot: PLUGIN_ROOT }),
).resolves.toBeDefined();
},
);
test("loads contract documents larger than the previous size limit", async () => {
const scanDir = await copyExample();
const path = join(scanDir, "scan-manifest.json");
const manifest = await readJson(path);
manifest["metadata"] = "x".repeat(16 * 1024 * 1024);
await writeJson(path, manifest);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).resolves.toBeDefined();
});
test("loads contract schemas larger than the previous size limit", async () => {
const pluginRoot = await temporaryDirectory("codex-security-schema-large-");
await cp(join(PLUGIN_ROOT, "schemas"), join(pluginRoot, "schemas"), {
recursive: true,
});
const path = join(pluginRoot, "schemas", "scan-manifest.schema.json");
const schema = await readJson(path);
schema["description"] = "x".repeat(4 * 1024 * 1024);
await writeJson(path, schema);
await expect(
loadContract(await copyExample(), { pluginRoot }),
).resolves.toBeDefined();
});
test("loads valid JSON nested beyond the previous depth limit", async () => {
const scanDir = await copyExample();
const path = join(scanDir, "findings.json");
const findings = await readJson(path);
let nested: unknown = "value";
for (let depth = 0; depth < 258; depth += 1) nested = [nested];
findings["findings"][0]["extensions"] = { nested };
await writeJson(path, findings);
await reseal(scanDir);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).resolves.toBeDefined();
});
test("identifies unusual property names unambiguously in validation errors", async () => {
const scanDir = await copyExample();
const marker = 'synthetic/"~\nkey';
await writeFile(
join(scanDir, "findings.json"),
JSON.stringify({ [marker]: 9007199254740992 }),
);
let thrown: unknown;
try {
await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
} catch (error) {
thrown = error;
}
expect(thrown).toBeInstanceOf(ContractValidationError);
expect((thrown as Error).message).toContain("unsafe integer-valued");
expect((thrown as Error).message).toContain(`[${JSON.stringify(marker)}]`);
});
test("accepts valid schemas beyond the previous complexity limit", async () => {
const pluginRoot = await temporaryDirectory(
"codex-security-schema-complex-",
);
await cp(join(PLUGIN_ROOT, "schemas"), join(pluginRoot, "schemas"), {
recursive: true,
});
const path = join(pluginRoot, "schemas", "scan-manifest.schema.json");
const schema = await readJson(path);
schema["allOf"] = Array.from({ length: 129 }, () => ({ type: "object" }));
await writeJson(path, schema);
await expect(
loadContract(await copyExample(), { pluginRoot }),
).resolves.toBeDefined();
});
test("does not expose attacker-controlled schema compilation errors", async () => {
const pluginRoot = await temporaryDirectory(
"codex-security-schema-compile-",
);
await mkdir(join(pluginRoot, "schemas"));
const marker = "PRIVATE_SCHEMA_KEY";
await writeJson(join(pluginRoot, "schemas", "scan-manifest.schema.json"), {
type: "object",
properties: {
[marker]: { type: "not-a-valid-json-schema-type" },
},
});
let thrown: unknown;
try {
await loadContract(await copyExample(), { pluginRoot });
} catch (error) {
thrown = error;
}
expect(thrown).toBeInstanceOf(ContractValidationError);
expect((thrown as Error).message).toBe(
"scan-manifest.schema.json: invalid JSON Schema.",
);
expect((thrown as Error).message).not.toContain(marker);
expect((thrown as Error).cause).toBeUndefined();
});
test("rejects changed sealed artifacts and duplicate paths", async () => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
findings["findings"][0]["title"] = "tampered";
await writeJson(findingsPath, findings);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow("sealed artifact changed");
const second = await copyExample();
const manifestPath = join(second, "scan-manifest.json");
const manifest = await readJson(manifestPath);
manifest["scan"]["artifacts"].push({ ...manifest["scan"]["artifacts"][0] });
await writeJson(manifestPath, manifest);
await expect(
loadContract(second, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow("schema validation failed");
});
test("rejects unsafe Windows and traversal artifact paths", async () => {
const scanDir = await copyExample();
const path = join(scanDir, "scan-manifest.json");
const manifest = await readJson(path);
const invalidArtifact = {
path: "",
sha256: "0".repeat(64),
mediaType: "text/plain",
};
manifest["scan"]["artifacts"].push(invalidArtifact);
for (const unsafe of [
"/escape",
"D:/escape",
"../escape",
"artifacts/../escape",
"artifacts\\escape",
"artifacts/report?.json",
"artifacts/report.json.",
"artifacts/report.json ",
"artifacts/CON.txt",
" ",
"\u00a0",
]) {
invalidArtifact.path = unsafe;
await writeJson(path, manifest);
const rejected = loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
await expect(rejected).rejects.toBeInstanceOf(ContractValidationError);
await expect(rejected).rejects.toThrow(
/safe scan-relative POSIX path|schema validation failed \(pattern/u,
);
}
});
test("keeps bundled finalizer paths portable to Windows", () => {
const python = pythonExecutable();
expect(python).not.toBeNull();
const program = [
"import json, sys",
"sys.path.insert(0, sys.argv[1])",
"import finalize_scan_contract as finalizer",
"def accepted(value):",
" try:",
" finalizer._require_portable_relative_path(value, 'artifact path')",
" except finalizer.ContractError:",
" return False",
" return True",
"print(json.dumps([accepted(value) for value in ['artifacts/report.json.', 'artifacts/report.json ', 'artifacts/CON.txt', 'artifacts/report?.json', 'artifacts/report:stream']]))",
].join("\n");
const result = runPython(python!, [
"-c",
program,
join(PLUGIN_ROOT, "scripts"),
]);
expect(result.exitCode, new TextDecoder().decode(result.stderr)).toBe(0);
expect(JSON.parse(new TextDecoder().decode(result.stdout))).toEqual([
false,
false,
false,
false,
false,
]);
});
test("accepts Unix-valid source and scope path components", async () => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const findingsPath = join(scanDir, "findings.json");
const coveragePath = join(scanDir, "coverage.json");
const manifest = await readJson(manifestPath);
const findings = await readJson(findingsPath);
const coverage = await readJson(coveragePath);
findings["findings"][0]["locations"][0]["path"] = "src/app.ts:fixture";
manifest["scan"]["scope"]["includePaths"] = ["src/CON.py"];
coverage["includePaths"] = ["src/CON.py"];
await writeJson(findingsPath, findings);
await writeJson(coveragePath, coverage);
await writeJson(manifestPath, manifest);
await reseal(scanDir);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).resolves.toBeDefined();
});
test.each([" ", " ", "\u00a0"])(
"preserves literal whitespace repository path %j in the contract",
async (path) => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const findingsPath = join(scanDir, "findings.json");
const coveragePath = join(scanDir, "coverage.json");
const manifest = await readJson(manifestPath);
const findings = await readJson(findingsPath);
const coverage = await readJson(coveragePath);
manifest["scan"]["scope"]["includePaths"] = [path];
coverage["includePaths"] = [path];
findings["findings"][0]["locations"][0]["path"] = path;
await writeJson(manifestPath, manifest);
await writeJson(findingsPath, findings);
await writeJson(coveragePath, coverage);
await reseal(scanDir);
const contract = await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
expect(contract.manifest.scan.scope.includePaths).toEqual([path]);
expect(contract.findings.findings[0]!.locations[0]!.path).toBe(path);
},
);
test("preserves accepted paths in sealed deferred coverage", async () => {
const paths = [
".",
"./",
"././",
"src",
"src/parser.ts",
"./src/parser.ts",
"src/./parser.ts",
"src//parser.ts",
"src/",
"src:parser.ts",
"src/a:b.py",
"src/.hidden",
"src/na\u00efve file.ts",
"src/\u007fparser.ts",
"src/\u2028parser.ts",
"src/\u2029parser.ts",
" ",
"\u0085",
"\ufeff",
];
const scanDir = await copyExample();
const coveragePath = join(scanDir, "coverage.json");
const coverage = await readJson(coveragePath);
coverage["deferred"] = [
{ id: "review", reason: "Review is incomplete.", paths },
];
await writeJson(coveragePath, coverage);
await reseal(scanDir);
const sealedBytes = await readFile(coveragePath);
await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
expect(await readFile(coveragePath)).toEqual(sealedBytes);
});
test("rejects unsafe paths in sealed deferred coverage", async () => {
for (const path of [
"",
"../../outside.ts",
"src/../outside.ts",
"src/..",
"/outside.ts",
"//server/share",
"C:/outside.ts",
"c:outside.ts",
"src\\outside.ts",
"src/\u0000outside.ts",
"src/\u0001outside.ts",
"src/\toutside.ts",
"src/outside.ts\n",
"src/\routside.ts",
"src/\u2028/../outside.ts",
]) {
const scanDir = await copyExample();
const coveragePath = join(scanDir, "coverage.json");
const coverage = await readJson(coveragePath);
coverage["deferred"] = [
{ 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(
path === ""
? /coverage.*\/deferred\/1\/paths\/1/
: "coverage.deferred[1].paths[1]: expected a safe repository-relative POSIX path.",
);
}
});
test.each([-1, 0])(
"agrees with Python on a finding end-line offset of %i",
async (offset) => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
const location = findings["findings"][0]["locations"][0];
location["endLine"] = location["startLine"] + offset;
await writeJson(findingsPath, findings);
await reseal(scanDir);
expect(pythonExport(scanDir).exitCode === 0).toBe(offset === 0);
const loaded = loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
if (offset === 0) {
await expect(loaded).resolves.toBeDefined();
} else {
await expect(loaded).rejects.toThrow(
"findings.findings[0].locations[0].endLine: expected an integer >= startLine.",
);
}
},
);
test("rejects trailing-dot aliases for sealed artifacts", async () => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const manifest = await readJson(manifestPath);
await writeFile(
join(scanDir, "findings.json."),
await readFile(join(scanDir, "findings.json")),
);
manifest["scan"]["artifacts"].push({
...manifest["scan"]["artifacts"][0],
path: "findings.json.",
});
await writeJson(manifestPath, manifest);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow("safe scan-relative POSIX path");
});
test("rejects case-insensitive aliases for sealed artifacts", async () => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const manifest = await readJson(manifestPath);
await writeFile(
join(scanDir, "FINDINGS.json"),
await readFile(join(scanDir, "findings.json")),
);
manifest["scan"]["artifacts"].push({
...manifest["scan"]["artifacts"][0],
path: "FINDINGS.json",
});
await writeJson(manifestPath, manifest);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow("duplicate artifact path");
const python = pythonExecutable();
expect(python).not.toBeNull();
const result = runPython(python!, [
join(PLUGIN_ROOT, "scripts", "finalize_scan_contract.py"),
"--scan-dir",
await realpath(scanDir),
]);
const stderr = new TextDecoder().decode(result.stderr);
expect(result.exitCode, stderr).not.toBe(0);
expect(stderr).toContain("duplicate artifact path");
});
test.each([
["2026-02-30T18:00:00Z", false],
["0000-01-01T00:00:00Z", false],
["1900-02-29T00:00:00Z", false],
["2026-01-01T24:00:00Z", false],
["2026-01-01T00:00:60Z", false],
["2026-01-01T00:00:00+24:00", false],
["2026-01-01T00:00Z", false],
["2026-05-31t18:09:00z", true],
["0001-01-01T00:00:00Z", true],
["2000-02-29T23:59:59.123456+23:59", true],
["2026-01-01T00:00:00Z\n", false],
] as const)("validates RFC 3339 timestamp %j", async (value, valid) => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const manifest = await readJson(manifestPath);
manifest["scan"]["completedAt"] = value;
manifest["scan"]["sealedAt"] = value;
await writeJson(manifestPath, manifest);
const loaded = loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
if (valid) await expect(loaded).resolves.toBeDefined();
else await expect(loaded).rejects.toThrow("date-time");
});
test("requires completed and sealed timestamps to match exactly", async () => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const manifest = await readJson(manifestPath);
manifest["scan"]["completedAt"] = "2026-01-01T00:00:01.000400Z";
manifest["scan"]["sealedAt"] = "2026-01-01T00:00:01.000400Z";
await writeJson(manifestPath, manifest);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).resolves.toBeDefined();
manifest["scan"]["sealedAt"] = "2026-01-01T01:00:01.000400+01:00";
await writeJson(manifestPath, manifest);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow("Manifest sealedAt must match completedAt.");
});
test("rejects invalid UTF-8 in JSON documents", async () => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readFile(findingsPath);
const contentOffset = findings.indexOf("findingId");
expect(contentOffset).toBeGreaterThanOrEqual(0);
findings[contentOffset] = 0xff;
await writeFile(findingsPath, findings);
const manifestPath = join(scanDir, "scan-manifest.json");
const manifest = await readJson(manifestPath);
const artifact = manifest["scan"]["artifacts"].find(
(candidate: Record<string, unknown>) =>
candidate["path"] === "findings.json",
);
artifact["sha256"] = sha256(findings);
await writeJson(manifestPath, manifest);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow("unreadable JSON document");
});
test.each([
["src/handler.py", true],
["src/a:b.py", true],
["report:summary.py", true],
["é:helper.ts", true],
["./é:helper.ts", true],
["src/name with spaces.py", true],
["src/日本語.py", true],
["./src//handler.py", true],
["src/line\u2028separator.py", true],
["../outside.py", false],
["src/../../outside.py", false],
["/outside.py", false],
["C:/outside.py", false],
["C:outside.py", false],
["c:outside.py", false],
["src\\outside.py", false],
[".", false],
["src/\u0000outside.py", false],
["src/name\t.py", false],
] as const)(
"validates canonical code-evidence path %j",
async (path, valid) => {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
findings["findings"][0]["codeEvidence"] = [
{
id: "source",
label: "Source",
path,
startLine: 1,
code: "source()",
explanation: "Synthetic repository evidence.",
},
];
await writeJson(findingsPath, findings);
await reseal(scanDir);
const saved = await readFile(findingsPath);
const loaded = loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
const exported = pythonExport(scanDir);
const stderr = new TextDecoder().decode(exported.stderr);
if (valid) {
const contract = await loaded;
expect(contract.findings.findings[0]?.codeEvidence?.[0]?.path).toBe(
path,
);
expect(exported.exitCode, stderr).toBe(0);
} else {
await expect(loaded).rejects.toThrow(
"codeEvidence[0].path: expected a safe repository-relative POSIX path",
);
expect(exported.exitCode).not.toBe(0);
expect(stderr).toContain(
"codeEvidence[0].path: expected a safe repository-relative POSIX path",
);
}
expect(await readFile(findingsPath)).toEqual(saved);
},
);
test("rejects schema-valid but canonically invalid contract data", async () => {
const cases: Array<
[
string,
(
manifest: Record<string, any>,
findings: Record<string, any>,
coverage: Record<string, any>,
) => void,
string,
]
> = [
[
"unsafe location",
(_manifest, findings) => {
findings["findings"][0]["locations"][0]["path"] = "../outside.ts";
},
"safe repository-relative POSIX path",
],
[
"ill-formed Unicode location",
(_manifest, findings) => {
findings["findings"][0]["locations"][0]["path"] =
"src/bad-\ud800-name.ts";
},
"well-formed Unicode",
],
[
"unsafe scope",
(manifest, _findings, coverage) => {
manifest["scan"]["scope"]["includePaths"] = ["../outside"];
coverage["includePaths"] = ["../outside"];
},
"safe repository-relative POSIX path",
],
[
"ill-formed Unicode scope",
(manifest, _findings, coverage) => {
manifest["scan"]["scope"]["includePaths"] = ["src/bad-\ud800-name"];
coverage["includePaths"] = ["src/bad-\ud800-name"];
},
"well-formed Unicode",
],
[
"ill-formed Unicode artifact",
(manifest) => {
manifest["scan"]["artifacts"].push({
path: "artifacts/bad-\ud800-name.txt",
sha256: "0".repeat(64),
mediaType: "text/plain",
});
},
"well-formed Unicode",
],
[
"ill-formed Unicode receipt",
(_manifest, _findings, coverage) => {
coverage["surfaces"][0]["receiptRefs"] = [
"artifacts/bad-\ud800-name.txt",
];
},
"well-formed Unicode",
],
[
"wrong identities",
(_manifest, findings) => {
findings["findings"][0]["findingId"] = `csf_${"0".repeat(24)}`;
findings["findings"][0]["occurrenceId"] = `occ_${"1".repeat(24)}`;
findings["findings"][0]["fingerprints"] = {
algorithm: "codex-security/v1",
primary: `codex-security/v1:sha256:${"2".repeat(64)}`,
};
},
"derived fingerprint identity",
],
[
"opaque remote",
(manifest) => {
manifest["scan"]["target"]["remote"] = "ssh:opaque";
},
"canonical absolute URL",
],
[
"relative remote",
(manifest) => {
manifest["scan"]["target"]["remote"] = "relative/repository";
},
"canonical absolute URL",
],
[
"scheme-without-authority remote",
(manifest) => {
manifest["scan"]["target"]["remote"] = "https:example.com/repo";
},
"canonical absolute URL",
],
[
"single-slash remote",
(manifest) => {
manifest["scan"]["target"]["remote"] = "https:/example.com/repo";
},
"canonical absolute URL",
],
[
"backslash authority remote",
(manifest) => {
manifest["scan"]["target"]["remote"] =
"https://example.com\\@evil.test/repo";
},
"/scan/target/remote",
],
];
for (const [_name, mutate, expected] of cases) {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const findingsPath = join(scanDir, "findings.json");
const coveragePath = join(scanDir, "coverage.json");
const manifest = await readJson(manifestPath);
const findings = await readJson(findingsPath);
const coverage = await readJson(coveragePath);
mutate(manifest, findings, coverage);
await writeJson(findingsPath, findings);
await writeJson(coveragePath, coverage);
await writeJson(manifestPath, manifest);
await reseal(scanDir);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow(expected);
}
});
test("accepts distinct finding siblings and Unicode target identities", async () => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const findingsPath = join(scanDir, "findings.json");
const manifest = await readJson(manifestPath);
const findings = await readJson(findingsPath);
manifest["scan"]["target"]["targetId"] = "target_仓库_😀";
const first = findings["findings"][0];
const second = structuredClone(first);
first["identity"]["instance"] = "first-sink";
second["identity"]["instance"] = "second-sink";
setFindingIdentity(manifest["scan"], first);
setFindingIdentity(manifest["scan"], second);
findings["findings"].push(second);
await writeJson(manifestPath, manifest);
await writeJson(findingsPath, findings);
await reseal(scanDir);
const loaded = await loadContract(scanDir, { pluginRoot: PLUGIN_ROOT });
expect(loaded.findings.findings).toHaveLength(2);
expect(loaded.findings.findings[0]?.findingId).not.toBe(
loaded.findings.findings[1]?.findingId,
);
});
test("identifies the failing schema field and required member", async () => {
for (const field of ["severity", "confidence"]) {
const scanDir = await copyExample();
const path = join(scanDir, "findings.json");
const document = await readJson(path);
document["findings"][0][field].level = null;
await writeJson(path, document);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow(`/findings/0/${field}/level`);
delete document["findings"][0][field].level;
await writeJson(path, document);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow("required property 'level'");
}
});
test("rejects unsafe and non-finite JSON numbers before contract typing", async () => {
for (const [field, expected] of [
["startLine", "unsafe integer-valued JSON numbers"],
["endLine", "unsafe integer-valued JSON numbers"],
["evidenceStartLine", "unsafe integer-valued JSON numbers"],
["evidenceEndLine", "unsafe integer-valued JSON numbers"],
["overflow", "non-finite JSON numbers"],
] as const) {
const scanDir = await copyExample();
const findingsPath = join(scanDir, "findings.json");
const findings = await readJson(findingsPath);
const finding = findings["findings"][0];
if (field === "evidenceStartLine" || field === "evidenceEndLine") {
finding["codeEvidence"] = [
{
id: "source",
label: "Source",
path: "src/extract.py",
startLine: 41,
endLine: 44,
code: "extract()",
explanation: "Source evidence",
},
];
}
if (field === "overflow") {
finding["extensions"] = { 'evidence/"~\n': { overflow: 0 } };
}
await writeJson(findingsPath, findings);
let text = await readFile(findingsPath, "utf8");
const replacement = field === "overflow" ? "1e400" : "9007199254740993";
const needle =
field === "startLine"
? '"startLine": 41'
: field === "endLine"
? '"endLine": 44'
: field === "evidenceStartLine"
? '"startLine": 41'
: field === "evidenceEndLine"
? '"endLine": 44'
: '"overflow": 0';
if (field === "evidenceStartLine" || field === "evidenceEndLine") {
const last = text.lastIndexOf(needle);
text = `${text.slice(0, last)}${needle.replace(/: \d+$/, `: ${replacement}`)}${text.slice(last + needle.length)}`;
} else {
text = text.replace(
needle,
needle.replace(/: \d+$/, `: ${replacement}`),
);
}
await writeFile(findingsPath, text);
await reseal(scanDir);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow(expected);
if (field === "overflow")
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow('["extensions"]["evidence/\\"~\\n"]["overflow"]');
}
});
test.skipIf(process.platform === "win32")(
"rejects missing or symlinked derived writeup and hardening files",
async () => {
for (const kind of ["writeup", "hardening"] as const) {
for (const symlinked of [false, true]) {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const findingsPath = join(scanDir, "findings.json");
const manifest = await readJson(manifestPath);
const findings = await readJson(findingsPath);
const relativePath =
kind === "writeup"
? "findings/report/report.md"
: "hardening/hardening.md";
if (kind === "writeup") {
findings["findings"][0]["writeup"] = { reportPath: relativePath };
} else {
manifest["scan"]["hardening"] = { portfolioPath: relativePath };
}
await writeJson(manifestPath, manifest);
await writeJson(findingsPath, findings);
await reseal(scanDir);
if (symlinked) {
const external = join(scanDir, "external.md");
const referenced = join(scanDir, relativePath);
await writeFile(external, "external\n");
await mkdir(dirname(referenced), { recursive: true });
await symlink(external, referenced);
}
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow(
kind === "writeup"
? "writeup.reportPath"
: "hardening.portfolioPath",
);
}
}
},
);
test("accepts regular derived artifacts and a schema-valid scope summary", async () => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const findingsPath = join(scanDir, "findings.json");
const manifest = await readJson(manifestPath);
const findings = await readJson(findingsPath);
manifest["scan"]["scope"]["summary"] = "\u0085";
manifest["scan"]["hardening"] = {
portfolioPath: "hardening/hardening.md",
};
findings["findings"][0]["writeup"] = {
reportPath: "findings/report/report.md",
};
await mkdir(join(scanDir, "hardening"));
await mkdir(join(scanDir, "findings", "report"), { recursive: true });
await writeFile(join(scanDir, "hardening", "hardening.md"), "hardening\n");
await writeFile(
join(scanDir, "findings", "report", "report.md"),
"report\n",
);
await writeJson(manifestPath, manifest);
await writeJson(findingsPath, findings);
await reseal(scanDir);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).resolves.toBeDefined();
});
test.each([
"accepts whitespace in schema-only minLength contract fields",
"accepts representative schema-only minLength fields in each contract document",
])("%s", async (description) => {
const cases: Array<
[
string,
(
manifest: Record<string, any>,
findings: Record<string, any>,
coverage: Record<string, any>,
) => void,
]
> = [
[
"scope list",
(manifest) => {
manifest["scan"]["scope"]["artifactsReviewed"] = [" "];
},
],
[
"threat summary",
(manifest) => {
manifest["scan"]["threatModel"] = { summary: " " };
},
],
[
"threat list",
(manifest) => {
manifest["scan"]["threatModel"] = { summary: "ok", assets: [" "] };
},
],
[
"severity vector",
(_manifest, findings) => {
findings["findings"][0]["severity"]["vector"] = " ";
},
],
[
"location role",
(_manifest, findings) => {
findings["findings"][0]["locations"][0]["role"] = " ";
},
],
[
"evidence label",
(_manifest, findings) => {
findings["findings"][0]["codeEvidence"] = [
{
id: "source",
label: " ",
path: "src/x.ts",
startLine: 41,
code: "x()",
explanation: "ok",
},
];
},
],
[
"evidence path",
(_manifest, findings) => {
findings["findings"][0]["codeEvidence"] = [
{
id: "source",
label: "ok",
path: " ",
startLine: 41,
code: "x()",
explanation: "ok",
},
];
},
],
[
"root summary",
(_manifest, findings) => {
findings["findings"][0]["rootCause"] = { summary: " " };
},
],
[
"root code",
(_manifest, findings) => {
findings["findings"][0]["rootCause"] = { summary: "ok", code: " " };
},
],
[
"remediation test",
(_manifest, findings) => {
findings["findings"][0]["remediationTests"] = [" "];
},
],
[
"extensions candidate",
(_manifest, findings) => {
findings["findings"][0]["extensions"] = { candidateId: " " };
},
],
[
"surface notes",
(_manifest, _findings, coverage) => {
coverage["surfaces"][0]["notes"] = " ";
},
],
[
"surface risk",
(_manifest, _findings, coverage) => {
coverage["surfaces"][0]["riskArea"] = " ";
},
],
[
"explicit exclusion",
(_manifest, _findings, coverage) => {
coverage["explicitExclusions"] = [{ pattern: " ", reason: "ok" }];
},
],
[
"deferred",
(_manifest, _findings, coverage) => {
coverage["completeness"] = "partial";
coverage["deferred"] = [{ id: " ", reason: "ok" }];
},
],
[
"open question",
(_manifest, _findings, coverage) => {
coverage["openQuestions"] = [{ question: " " }];
},
],
];
const selectedCases =
description ===
"accepts representative schema-only minLength fields in each contract document"
? cases.filter(([name]) =>
["scope list", "severity vector", "surface notes"].includes(name),
)
: cases;
for (const [_name, mutate] of selectedCases) {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const findingsPath = join(scanDir, "findings.json");
const coveragePath = join(scanDir, "coverage.json");
const manifest = await readJson(manifestPath);
const findings = await readJson(findingsPath);
const coverage = await readJson(coveragePath);
mutate(manifest, findings, coverage);
await writeJson(manifestPath, manifest);
await writeJson(findingsPath, findings);
await writeJson(coveragePath, coverage);
await reseal(scanDir);
await expect(
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).resolves.toBeDefined();
}
});
test("accepts Git-backed scans when the SDK cannot resolve a revision", async () => {
const scanDir = await copyExample();
await expect(
loadContract(scanDir, {
pluginRoot: PLUGIN_ROOT,
expectation: {
...expectation({ kind: "repository", paths: [] }),
repositoryRevision: null,
},
}),
).resolves.toBeDefined();
});
test("accepts directory scans without requiring a Git repository", async () => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const coveragePath = join(scanDir, "coverage.json");
const manifest = await readJson(manifestPath);
const coverage = await readJson(coveragePath);
manifest["scan"]["target"]["kind"] = "directory_snapshot";
delete manifest["scan"]["target"]["revision"];
delete manifest["scan"]["target"]["remote"];
coverage["inventoryStrategy"] = "directory";
await writeJson(manifestPath, manifest);
await writeJson(coveragePath, coverage);
await reseal(scanDir);
for (const repositoryRevision of [null, "deadbeef"]) {
await expect(
loadContract(scanDir, {
pluginRoot: PLUGIN_ROOT,
expectation: {
...expectation({ kind: "repository", paths: [] }),
repositoryRevision,
},
}),
).resolves.toBeDefined();
}
});
test("rejects Git-backed scans for a different revision", async () => {
const scanDir = await copyExample();
await expect(
loadContract(scanDir, {
pluginRoot: PLUGIN_ROOT,
expectation: {
...expectation({ kind: "repository", paths: [] }),
repositoryRevision: "different-revision",
},
}),
).rejects.toThrow("Scan target revision does not match the repository.");
});
test("rejects diff targets for repository scans", async () => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const manifest = await readJson(manifestPath);
manifest["scan"]["target"]["kind"] = "git_diff";
await writeJson(manifestPath, manifest);
await reseal(scanDir);
await expect(
loadContract(scanDir, {
pluginRoot: PLUGIN_ROOT,
expectation: {
...expectation({ kind: "repository", paths: [] }),
repositoryRevision: null,
},
}),
).rejects.toThrow("Repository scan manifest target must not be git_diff.");
});
test("binds requested path scope, mode, and plugin version", async () => {
const scanDir = await copyExample();
const manifestPath = join(scanDir, "scan-manifest.json");
const manifest = await readJson(manifestPath);
manifest["scan"]["scope"]["includePaths"] = ["src"];
await writeJson(manifestPath, manifest);
const coveragePath = join(scanDir, "coverage.json");
const coverage = await readJson(coveragePath);
coverage["mode"] = "scoped_path";
coverage["inventoryStrategy"] = "scoped_path";
coverage["includePaths"] = ["src"];
await writeJson(coveragePath, coverage);
await reseal(scanDir);
const target: NormalizedTarget = { kind: "paths", paths: ["src"] };
await expect(
loadContract(scanDir, {
pluginRoot: PLUGIN_ROOT,
expectation: expectation(target),
}),
).resolves.toBeDefined();
await expect(
loadContract(scanDir, {
pluginRoot: PLUGIN_ROOT,
expectation: expectation({ kind: "paths", paths: ["packages/auth"] }),
}),
).rejects.toThrow("include paths");
await expect(
loadContract(scanDir, {
pluginRoot: PLUGIN_ROOT,
expectation: { ...expectation(target), pluginVersion: "9.9.9" },
}),
).rejects.toThrow("producer version");
});
});