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

refactor(artifacts): share scan result validation across scan modes (#920)

Michael D'Angeloc45fd5938f6e
diff --git a/plugins/codex-security/mcp-app/helpers-main.ts b/plugins/codex-security/mcp-app/helpers-main.ts
index 1a361e6c9..4b0ef6e49 100644
--- a/plugins/codex-security/mcp-app/helpers-main.ts
+++ b/plugins/codex-security/mcp-app/helpers-main.ts
@@ -1,4 +1,6 @@
-import { closeSync, readFileSync } from "node:fs";
+import { closeSync, readFileSync, existsSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+export { parseCanonicalScanDraft } from "./src/artifact-scan-draft.js";
import { parseArgs } from "node:util";
import { isMainThread, parentPort, workerData } from "node:worker_threads";
import { resolveSecurityMdCommand } from "./src/helpers/resolve-security-md";
@@ -16,121 +18,136 @@ import { bindRepoScopesCommand } from "./src/helpers/bind-repo-scopes";
import { escapeControls, stringifyJson } from "./src/helpers/json";
import { decodeUtf8 } from "./src/helpers/utf8";
-let commandLine = isMainThread ? process.argv.slice(2) : [];
-if (isMainThread && process.platform === "win32") {
- const original = windowsBinding().windowsArguments();
- commandLine = original
- .slice(original.length - commandLine.length)
- .map((argument) => argument.toString("utf16le"));
+// Importing the bundled parser does not invoke its CLI adapter.
+const entryPath = import.meta.url.startsWith("file:")
+ ? fileURLToPath(import.meta.url)
+ : import.meta.url;
+const invokedPath = process.argv[1];
+if (
+ invokedPath &&
+ existsSync(invokedPath) &&
+ realpathSync(invokedPath) === realpathSync(entryPath)
+) {
+ if (isMainThread) runHelper();
+ else parentPort!.postMessage(normalizeCandidateBatch(workerData));
}
-let posixHome = process.env.HOME;
-if (commandLine[0] === "--helper") {
+
+function runHelper(): void {
+ let commandLine = process.argv.slice(2);
if (process.platform === "win32") {
- commandLine = commandLine.slice(1);
- } else {
- const encoded = readFileSync(3, "ascii");
- closeSync(3);
- const [homeSet, home, ...args] = decodePosixBytes(
- Buffer.from(encoded.trim(), "hex"),
- )
- .split("\0")
- .slice(0, -1);
- posixHome = homeSet ? home : undefined;
- commandLine = args;
+ const original = windowsBinding().windowsArguments();
+ commandLine = original
+ .slice(original.length - commandLine.length)
+ .map((argument) => argument.toString("utf16le"));
}
-}
-const [command, ...args] = commandLine;
-const workbenchUsage: Record<string, string> = {
- "database-info":
- "Usage: database-info (reads a JSON absolute state-directory string from stdin)",
- "store-findings":
- "Usage: store-findings\nReads a JSON object from stdin with an absolute stateDirectory and payload.entries containing finding and embedding records; payload.repositoryId is optional.",
- "list-stored-findings":
- "Usage: list-stored-findings\nReads a JSON object from stdin with an absolute stateDirectory, positive payload.limit and non-negative payload.offset.",
- "find-potential-duplicates":
- "Usage: find-potential-duplicates\nReads a JSON object from stdin with an absolute stateDirectory, payload.findingId and payload.scope containing either repositoryId or allRepositories: true.",
- "store-dedupe-groups":
- "Usage: store-dedupe-groups\nReads a JSON object from stdin with an absolute stateDirectory and payload.groups containing arrays of finding IDs.",
- "list-dedupe-groups":
- "Usage: list-dedupe-groups\nReads a JSON object from stdin with an absolute stateDirectory and payload.findingId.",
- "severity-classification":
- "Usage: severity-classification\nReads a JSON object from stdin with an absolute stateDirectory and payload describing the begin or save action.",
- "read-severity-classification":
- "Usage: read-severity-classification --scan-id <id>\nReads a JSON object from stdin with an absolute stateDirectory. Reads saved assessments without updating the database.",
-};
-if (!isMainThread) {
- parentPort!.postMessage(normalizeCandidateBatch(workerData));
-} else if (command === "resolve-security-md") {
- process.exitCode = resolveSecurityMdCommand(args, posixHome);
-} else if (command === "normalize-candidates") {
- process.exitCode = normalizeCandidatesCommand(args, posixHome);
-} else if (command === "validate-patch-risk-assessment") {
- process.exitCode = validatePatchRiskAssessmentCommand(args);
-} else if (
- command === "copy-deep-review-input" ||
- command === "select-deep-review-input"
-) {
- process.exitCode = deepReviewInputCommand(command, args, posixHome);
-} else if (
- command === "make-rank-shards" ||
- command === "validate-rank-shard" ||
- command === "merge-rank-outputs"
-) {
- process.exitCode = rankShardsCommand(command, args, posixHome);
-} else if (
- command === "make-rank-pool-plan" ||
- command === "validate-rank-worker" ||
- command === "validate-rank-pool"
-) {
- process.exitCode = rankPoolCommand(command, args, posixHome);
-} else if (command === "bind-repo-scopes") {
- process.exitCode = bindRepoScopesCommand(args, posixHome);
-} else if (Object.hasOwn(workbenchUsage, command)) {
- void (async () => {
- const { values } = parseArgs({
- args,
- options: {
- help: { type: "boolean", short: "h" },
- ...(command === "read-severity-classification"
- ? { "scan-id": { type: "string" as const } }
- : {}),
- },
- });
- if (values.help) {
- console.log(workbenchUsage[command]);
- return;
- }
- let result: unknown;
- if (command === "database-info") {
- const { databaseInfo } = await import("./src/workbench/database");
- result = await databaseInfo(JSON.parse(decodeUtf8(readFileSync(0))));
+ let posixHome = process.env.HOME;
+ if (commandLine[0] === "--helper") {
+ if (process.platform === "win32") {
+ commandLine = commandLine.slice(1);
} else {
- const { workbenchCommand } = await import("./src/workbench/commands");
- result = await workbenchCommand(
- command,
- decodeUtf8(readFileSync(0)),
- values["scan-id"] as string | undefined,
- );
+ const encoded = readFileSync(3, "ascii");
+ closeSync(3);
+ const [homeSet, home, ...args] = decodePosixBytes(
+ Buffer.from(encoded.trim(), "hex"),
+ )
+ .split("\0")
+ .slice(0, -1);
+ posixHome = homeSet ? home : undefined;
+ commandLine = args;
}
- console.log(
- stringifyJson(result, 0).replace(/[\p{Cc}\p{Cf}]/gu, (character) =>
- character
- .split("")
- .map(
- (unit) => `\\u${unit.charCodeAt(0).toString(16).padStart(4, "0")}`,
- )
- .join(""),
- ),
- );
- })().catch((error: unknown) => {
+ }
+ const [command, ...args] = commandLine;
+ const workbenchUsage: Record<string, string> = {
+ "database-info":
+ "Usage: database-info (reads a JSON absolute state-directory string from stdin)",
+ "store-findings":
+ "Usage: store-findings\nReads a JSON object from stdin with an absolute stateDirectory and payload.entries containing finding and embedding records; payload.repositoryId is optional.",
+ "list-stored-findings":
+ "Usage: list-stored-findings\nReads a JSON object from stdin with an absolute stateDirectory, positive payload.limit and non-negative payload.offset.",
+ "find-potential-duplicates":
+ "Usage: find-potential-duplicates\nReads a JSON object from stdin with an absolute stateDirectory, payload.findingId and payload.scope containing either repositoryId or allRepositories: true.",
+ "store-dedupe-groups":
+ "Usage: store-dedupe-groups\nReads a JSON object from stdin with an absolute stateDirectory and payload.groups containing arrays of finding IDs.",
+ "list-dedupe-groups":
+ "Usage: list-dedupe-groups\nReads a JSON object from stdin with an absolute stateDirectory and payload.findingId.",
+ "severity-classification":
+ "Usage: severity-classification\nReads a JSON object from stdin with an absolute stateDirectory and payload describing the begin or save action.",
+ "read-severity-classification":
+ "Usage: read-severity-classification --scan-id <id>\nReads a JSON object from stdin with an absolute stateDirectory. Reads saved assessments without updating the database.",
+ };
+ if (command === "resolve-security-md") {
+ process.exitCode = resolveSecurityMdCommand(args, posixHome);
+ } else if (command === "normalize-candidates") {
+ process.exitCode = normalizeCandidatesCommand(args, posixHome);
+ } else if (command === "validate-patch-risk-assessment") {
+ process.exitCode = validatePatchRiskAssessmentCommand(args);
+ } else if (
+ command === "copy-deep-review-input" ||
+ command === "select-deep-review-input"
+ ) {
+ process.exitCode = deepReviewInputCommand(command, args, posixHome);
+ } else if (
+ command === "make-rank-shards" ||
+ command === "validate-rank-shard" ||
+ command === "merge-rank-outputs"
+ ) {
+ process.exitCode = rankShardsCommand(command, args, posixHome);
+ } else if (
+ command === "make-rank-pool-plan" ||
+ command === "validate-rank-worker" ||
+ command === "validate-rank-pool"
+ ) {
+ process.exitCode = rankPoolCommand(command, args, posixHome);
+ } else if (command === "bind-repo-scopes") {
+ process.exitCode = bindRepoScopesCommand(args, posixHome);
+ } else if (Object.hasOwn(workbenchUsage, command)) {
+ void (async () => {
+ const { values } = parseArgs({
+ args,
+ options: {
+ help: { type: "boolean", short: "h" },
+ ...(command === "read-severity-classification"
+ ? { "scan-id": { type: "string" as const } }
+ : {}),
+ },
+ });
+ if (values.help) {
+ console.log(workbenchUsage[command]);
+ return;
+ }
+ let result: unknown;
+ if (command === "database-info") {
+ const { databaseInfo } = await import("./src/workbench/database");
+ result = await databaseInfo(JSON.parse(decodeUtf8(readFileSync(0))));
+ } else {
+ const { workbenchCommand } = await import("./src/workbench/commands");
+ result = await workbenchCommand(
+ command,
+ decodeUtf8(readFileSync(0)),
+ values["scan-id"] as string | undefined,
+ );
+ }
+ console.log(
+ stringifyJson(result, 0).replace(/[\p{Cc}\p{Cf}]/gu, (character) =>
+ character
+ .split("")
+ .map(
+ (unit) =>
+ `\\u${unit.charCodeAt(0).toString(16).padStart(4, "0")}`,
+ )
+ .join(""),
+ ),
+ );
+ })().catch((error: unknown) => {
+ console.error(
+ escapeControls(error instanceof Error ? error.message : String(error)),
+ );
+ process.exitCode = 1;
+ });
+ } else {
console.error(
- escapeControls(error instanceof Error ? error.message : String(error)),
+ `Usage: launch_codex_security_mcp[.cmd] --helper <resolve-security-md | normalize-candidates | validate-patch-risk-assessment | copy-deep-review-input | select-deep-review-input | make-rank-shards | validate-rank-shard | merge-rank-outputs | make-rank-pool-plan | validate-rank-worker | validate-rank-pool | bind-repo-scopes | ${Object.keys(workbenchUsage).join(" | ")}> [options]`,
);
- process.exitCode = 1;
- });
-} else {
- console.error(
- `Usage: launch_codex_security_mcp[.cmd] --helper <resolve-security-md | normalize-candidates | validate-patch-risk-assessment | copy-deep-review-input | select-deep-review-input | make-rank-shards | validate-rank-shard | merge-rank-outputs | make-rank-pool-plan | validate-rank-worker | validate-rank-pool | bind-repo-scopes | ${Object.keys(workbenchUsage).join(" | ")}> [options]`,
- );
- process.exitCode = 2;
+ process.exitCode = 2;
+ }
}
diff --git a/plugins/codex-security/mcp-app/scripts/build_mcp_app.mjs b/plugins/codex-security/mcp-app/scripts/build_mcp_app.mjs
index c981431d4..9bb09a1eb 100644
--- a/plugins/codex-security/mcp-app/scripts/build_mcp_app.mjs
+++ b/plugins/codex-security/mcp-app/scripts/build_mcp_app.mjs
@@ -196,5 +196,6 @@ const runtimeModule = new Module(loaderPath);
runtimeModule.filename = loaderPath;
runtimeModule.paths = Module._nodeModulePaths(dirname(loaderPath));
runtimeModule._compile(runtimeSource, loaderPath);
+export default runtimeModule.exports;
`;
}
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 09eb04f42..fde91abc4 100644
--- a/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts
+++ b/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts
@@ -2,11 +2,14 @@ import type { JsonObject } from "./types.js";
import { isRecord as isObject, isNonEmptyString } from "./record.js";
import { createHash, randomUUID } from "node:crypto";
import { promises as fs } from "node:fs";
-import { dirname, join, sep } from "node:path";
+import { dirname, isAbsolute, join, posix, sep } from "node:path";
import { isDeepStrictEqual } from "node:util";
import type * as z from "zod/v4";
import commonSchema from "../../schemas/definitions/artifact-common.schema.json";
import scanDraftDocument from "../../schemas/tools/scan-draft.schema.json";
+import scanManifestDocument from "../../schemas/scan-manifest.schema.json";
+import coverageDocument from "../../schemas/coverage.schema.json";
+import findingsDocument from "../../schemas/findings.schema.json";
import type { ArtifactContext } from "./artifact-context.js";
import type { RunArtifactWorkbench } from "./artifact-context.js";
import {
@@ -72,6 +75,68 @@ export const scanDraftInputSchema = loadArtifactZodSchema(
"scanDraftInput",
) as z.ZodType<ScanDraftInput>;
+// Keep draft completion/host-field handling, using canonical persisted field rules.
+const canonicalScanDraftInputSchema = loadArtifactZodSchema(
+ [
+ commonSchema,
+ {
+ ...scanDraftDocument,
+ $defs: {
+ ...scanManifestDocument.$defs,
+ ...findingsDocument.$defs,
+ ...scanDraftDocument.$defs,
+ scanId: scanManifestDocument.properties.scan.properties.id,
+ scope: {
+ ...scanDraftDocument.$defs.scope,
+ properties:
+ scanManifestDocument.properties.scan.properties.scope.properties,
+ },
+ threatModel:
+ scanManifestDocument.properties.scan.properties.threatModel,
+ finding: {
+ ...scanDraftDocument.$defs.finding,
+ properties: findingsDocument.properties.findings.items.properties,
+ },
+ coverage: {
+ ...scanDraftDocument.$defs.coverage,
+ properties: {
+ ...coverageDocument.properties,
+ surfaces: {
+ ...coverageDocument.properties.surfaces,
+ items: {
+ ...coverageDocument.properties.surfaces.items,
+ required: scanDraftDocument.$defs.surface.required,
+ },
+ },
+ deferred: {
+ ...coverageDocument.properties.deferred,
+ items: {
+ ...coverageDocument.properties.deferred.items,
+ required:
+ scanDraftDocument.$defs.coverage.properties.deferred.items
+ .required,
+ },
+ },
+ // String questions are normalized by the finalizer after admission.
+ openQuestions: {
+ ...coverageDocument.properties.openQuestions,
+ items: {
+ anyOf: [
+ scanDraftDocument.$defs.coverage.properties.openQuestions
+ .items.anyOf[0],
+ coverageDocument.properties.openQuestions.items,
+ ],
+ },
+ },
+ },
+ },
+ },
+ },
+ ] as SchemaDocument[],
+ scanDraftDocument.$id,
+ "scanDraftInput",
+) as z.ZodType<ScanDraftInput>;
+
export const completedScanInputSchema = loadArtifactZodSchema(
schemaDocuments,
scanDraftDocument.$id,
@@ -1122,10 +1187,10 @@ async function readSavedCheckpoints(
await readArtifactText(context, ["checkpoints", entry.name], label),
label,
);
- const input =
- kind === "current"
- ? parsePersistedCheckpoint(draft)
- : parsePersistedScanDraft(draft);
+ let input: ScanDraftInput;
+ if (kind === "archived") input = parsePersistedScanDraft(draft);
+ else if (context.layout === "scan") input = parseCanonicalCheckpoint(draft);
+ else input = parsePersistedCheckpoint(draft);
if (kind === "archived") requireMatchingScan(context, input);
else if (input.scanId !== context.scanId) {
throw new Error(
@@ -1205,7 +1270,6 @@ async function readPreviousScanDraft(
contents[2]!,
"previous scan draft coverage",
);
- const scan = requireObject(manifest.scan, "previous scan draft.scan");
return {
digest,
// File-authored coverage may leave its manifest unchanged; tool writes have a head.
@@ -1213,12 +1277,10 @@ async function readPreviousScanDraft(
(await readCheckpointHead(context, "current")) === undefined
? saved[2]!.modifiedMs
: Math.min(...saved.map((record) => record!.modifiedMs)),
- input: parsePersistedCheckpoint({
+ input: parseCanonicalScanDraft({
scanId: context.scanId,
- ...(scan.complete === false ? { complete: false } : {}),
- ...(isObject(scan.scope) ? { scope: scan.scope } : {}),
- ...(isObject(scan.threatModel) ? { threatModel: scan.threatModel } : {}),
- findings: findings.findings,
+ manifest,
+ findings,
coverage,
}),
};
@@ -1744,8 +1806,83 @@ export async function getCodexSecurityCompletedScan(
return { scanId: parsed.scanId, manifest, findings, coverage };
}
+function safeRelativePath(value: string, context: string): string {
+ const parts = value.split("/");
+ if (
+ value.trim().length === 0 ||
+ Buffer.from(value, "utf8").toString("utf8") !== value ||
+ value === "." ||
+ value.startsWith("/") ||
+ /^[A-Za-z]:/.test(value) ||
+ parts.includes("..") ||
+ value.includes("\\") ||
+ /[\u0000-\u001f]/u.test(value)
+ ) {
+ throw new Error(`${context}: expected a safe scan-relative POSIX path.`);
+ }
+ const normalized = posix.normalize(value).replace(/\/+$/, "");
+ if (
+ normalized === "." ||
+ normalized.startsWith("../") ||
+ isAbsolute(normalized)
+ ) {
+ throw new Error(`${context}: expected a safe scan-relative POSIX path.`);
+ }
+ return normalized;
+}
+
+/** Admit canonical fields while retaining shared audit semantics and path safety. */
+export function parseCanonicalScanDraft(input: {
+ scanId?: string;
+ manifest: JsonObject;
+ findings: JsonObject;
+ coverage: JsonObject;
+}): ScanDraftInput {
+ const scan = requireObject(input.manifest.scan, "scan draft manifest.scan");
+ for (const scanId of [
+ scan.id,
+ input.findings.scanId,
+ input.coverage.scanId,
+ ]) {
+ if (scanId !== undefined && scanId !== input.scanId) {
+ throw new Error(
+ "scan draft: canonical documents belong to a different scan.",
+ );
+ }
+ }
+ return parseCanonicalCheckpoint({
+ scanId: input.scanId,
+ ...(scan.complete === undefined ? {} : { complete: scan.complete }),
+ ...(scan.scope === undefined ? {} : { scope: scan.scope }),
+ ...(scan.threatModel === undefined
+ ? {}
+ : { threatModel: scan.threatModel }),
+ findings: input.findings.findings,
+ coverage: input.coverage,
+ });
+}
+
+function parseCanonicalCheckpoint(
+ input: Record<string, unknown>,
+): ScanDraftInput {
+ const parsed = parsePersistedCheckpoint(input, canonicalScanDraftInputSchema);
+ for (const [index, finding] of parsed.findings.entries()) {
+ for (const field of ["locations", "codeEvidence"] as const) {
+ for (const [locationIndex, location] of (
+ (finding[field] as JsonObject[] | undefined) ?? []
+ ).entries()) {
+ safeRelativePath(
+ location.path as string,
+ `findings[${index}].${field}[${locationIndex}].path`,
+ );
+ }
+ }
+ }
+ return parsed;
+}
+
export function parseScanDraft(input: ScanDraftInput): ScanDraftInput {
- const parsed = parseScanDraftDocument(input);
+ const parsed = parseSemanticScanDraft(input, scanDraftInputSchema);
const deferredIds = new Set<string>();
const ambiguousIds = ambiguousGenericDeferredIds([parsed]);
for (const row of parsed.coverage.deferred as JsonObject[]) {
@@ -1767,9 +1904,15 @@ export function parseScanDraft(input: ScanDraftInput): ScanDraftInput {
return parsed;
}
-function parseScanDraftDocument(input: unknown): ScanDraftInput {
- const parsed = scanDraftInputSchema.parse(input);
- validateFindingSemantics(parsed.findings);
+function parseSemanticScanDraft(
+ input: unknown,
+ schema: z.ZodType<ScanDraftInput>,
+): ScanDraftInput {
+ const parsed = schema.parse(input);
+ validateFindingSemantics(
+ parsed.findings,
+ schema !== canonicalScanDraftInputSchema,
+ );
validateCoverageSemantics(parsed.coverage);
return parsed;
}
@@ -1778,19 +1921,24 @@ function parseScanDraftDocument(input: unknown): ScanDraftInput {
export function parsePersistedScanDraft(
input: Record<string, unknown>,
): ScanDraftInput {
- const compatible = structuredClone(input);
- if (!Array.isArray(compatible.findings)) {
- return parseScanDraftDocument(compatible);
- }
- for (const finding of compatible.findings) {
- if (!isObject(finding)) continue;
- normalizePersistedFindingDetails(finding);
+ return parsePersistedDraft(structuredClone(input), scanDraftInputSchema);
+}
+
+function parsePersistedDraft(
+ compatible: Record<string, unknown>,
+ schema: z.ZodType<ScanDraftInput>,
+): ScanDraftInput {
+ if (Array.isArray(compatible.findings)) {
+ for (const finding of compatible.findings) {
+ if (isObject(finding)) normalizePersistedFindingDetails(finding);
+ }
}
- return parseScanDraftDocument(compatible);
+ return parseSemanticScanDraft(compatible, schema);
}
function parsePersistedCheckpoint(
input: Record<string, unknown>,
+ schema = scanDraftInputSchema,
): ScanDraftInput {
const compatible = structuredClone(input);
if (isObject(compatible.scope)) {
@@ -1819,7 +1967,7 @@ function parsePersistedCheckpoint(
delete finding.fingerprints;
}
}
- return parsePersistedScanDraft(compatible);
+ return parsePersistedDraft(compatible, schema);
}
function normalizePersistedFindingDetails(finding: JsonObject): void {
@@ -2348,7 +2496,10 @@ function inventoryStrategy(
return "repository";
}
-function validateFindingSemantics(findings: JsonObject[]): void {
+function validateFindingSemantics(
+ findings: JsonObject[],
+ enforceLegacyEvidenceBounds: boolean,
+): void {
for (const [findingIndex, finding] of findings.entries()) {
const severity = finding.severity as JsonObject;
if (
@@ -2390,6 +2541,7 @@ function validateFindingSemantics(findings: JsonObject[]): void {
}
evidenceIds.add(id);
if (
+ (evidenceName === "codeEvidence" || enforceLegacyEvidenceBounds) &&
typeof evidence.endLine === "number" &&
evidence.endLine < (evidence.startLine as number)
) {
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 548b29c53..064f386d1 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
@@ -41,6 +41,26 @@ const findingFor = (candidateId: string) => ({
provenance: { source: "local_plugin", candidateId },
});
+test("worker checkpoints retain typed surface IDs", async (t) => {
+ const f = await fixture(t, "worker");
+ await f.write(
+ f.draft({
+ surfaces: [
+ { id: "http-api", label: "HTTP API", disposition: "no_issue_found" },
+ ],
+ }),
+ );
+ const head = await readJson(f.root, "checkpoint-head.json");
+ const checkpointPath = path.join(f.root, "checkpoints", head.checkpoint);
+ const checkpoint = await readJson(checkpointPath);
+ checkpoint.coverage.surfaces[0].id = "HTTP API";
+ await writeJson(checkpointPath, checkpoint);
+ await assert.rejects(
+ f.write(f.draft({ deferred: [generic] })),
+ /Invalid string/,
+ );
+});
+
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_deep_scan_store_integration.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_store_integration.ts
index 50e907b93..961fb4b76 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_store_integration.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_store_integration.ts
@@ -1,4 +1,5 @@
import { readJson, writeJsonLine } from "./support/json.ts";
+import { finding } from "./scan-draft-fixture.ts";
import { temporaryDirectory } from "./support/temporary-directories.ts";
import assert from "node:assert/strict";
import { mock } from "node:test";
@@ -32,6 +33,7 @@ export { recordCodexSecurityScanDraftViaWorkbench } from "./src/artifact-scan-dr
},
});
+await testCanonicalParentCheckpointsSurviveSuccessiveWrites();
await testFreeformFailureMessagesAgainstRealWorkbench();
await testReducerCommitAndFinishAgainstRealWorkbench();
await testReducerCommitAndFinishAgainstRealWorkbench(true);
@@ -372,6 +374,89 @@ function checkpoint(scanId: string, candidateId: string, reason: string) {
};
}
+async function testCanonicalParentCheckpointsSurviveSuccessiveWrites() {
+ const { fixtureRoot, targetPath, environment } = await createWorkbenchFixture(
+ "canonical-parent-checkpoint-",
+ );
+ const runWorkbench = createWorkbenchRunner(environment);
+ try {
+ const run = await new WorkbenchDeepScanStore(runWorkbench).begin({
+ targetPath,
+ scope: ".",
+ threadId: "canonical-checkpoint-owner",
+ scanRoot: path.join(fixtureRoot, "scans"),
+ });
+ const context = await createScanArtifactContext(run.scanId, runWorkbench, {
+ requireRunning: true,
+ });
+ await recordCodexSecurityScanDraftViaWorkbench(
+ context,
+ {
+ ...checkpoint(run.scanId, "initial-review", "Review remains pending."),
+ findings: [finding("canonical-checkpoint", "fixture.py")],
+ },
+ runWorkbench,
+ );
+ const coverage = await readJson(run.scanDir, "coverage.json");
+ coverage.surfaces = [
+ { id: "HTTP API", label: "HTTP API", disposition: "reported" },
+ ];
+ const findings = await readJson(run.scanDir, "findings.json");
+ findings.findings[0].locations[0].path = "./fixture.py";
+ await writeJsonLine(path.join(run.scanDir, "coverage.json"), coverage);
+ await writeJsonLine(path.join(run.scanDir, "findings.json"), findings);
+
+ for (const update of ["first-update", "reloaded-update"]) {
+ const reloaded = await createScanArtifactContext(
+ run.scanId,
+ runWorkbench,
+ { requireRunning: true },
+ );
+ await recordCodexSecurityScanDraftViaWorkbench(
+ reloaded,
+ checkpoint(run.scanId, update, "Additional review remains pending."),
+ runWorkbench,
+ );
+ assert.equal(
+ (await readJson(run.scanDir, "coverage.json")).surfaces[0].id,
+ "HTTP API",
+ );
+ const head = await readJson(run.scanDir, "checkpoint-head.json");
+ const saved = await readJson(run.scanDir, "checkpoints", head.checkpoint);
+ assert.equal(saved.coverage.surfaces[0].id, "HTTP API");
+ assert.equal(saved.findings[0].locations[0].path, "./fixture.py");
+ }
+
+ const head = await readJson(run.scanDir, "checkpoint-head.json");
+ const saved = await readJson(run.scanDir, "checkpoints", head.checkpoint);
+ saved.findings[0].locations[0].path = "../outside.py";
+ await writeJsonLine(
+ path.join(run.scanDir, "checkpoints", head.checkpoint),
+ saved,
+ );
+ const names = ["scan-manifest.json", "findings.json", "coverage.json"];
+ const before = await Promise.all(
+ names.map((name) => readFile(path.join(run.scanDir, name))),
+ );
+ await assert.rejects(
+ recordCodexSecurityScanDraftViaWorkbench(
+ context,
+ checkpoint(run.scanId, "unsafe-checkpoint", "Review remains pending."),
+ runWorkbench,
+ ),
+ /expected a safe scan-relative POSIX path/,
+ );
+ assert.deepEqual(
+ await Promise.all(
+ names.map((name) => readFile(path.join(run.scanDir, name))),
+ ),
+ before,
+ );
+ } finally {
+ await rm(fixtureRoot, { recursive: true, force: true });
+ }
+}
+
async function testConcurrentParentDraftsPreserveBothCheckpoints() {
const { fixtureRoot, targetPath, environment } = await createWorkbenchFixture(
"scan-draft-concurrency-integration-",
diff --git a/plugins/codex-security/native/proof-policy-windows.mts b/plugins/codex-security/native/proof-policy-windows.mts
index d649cde92..ace760696 100644
--- a/plugins/codex-security/native/proof-policy-windows.mts
+++ b/plugins/codex-security/native/proof-policy-windows.mts
@@ -19,10 +19,11 @@ import {
const testDirectory = join(output, "policy-proof");
const helper = join(testDirectory, "helpers.cjs");
if (process.argv[2] === "build") {
+ const sdkModules = join(root, "../../../sdk/typescript/node_modules");
execFileSync(
process.execPath,
[
- join(root, "../../../sdk/typescript/node_modules/esbuild/bin/esbuild"),
+ join(sdkModules, "esbuild/bin/esbuild"),
join(root, "../mcp-app/helpers-main.ts"),
"--bundle",
"--platform=node",
@@ -31,7 +32,11 @@ if (process.argv[2] === "build") {
"--define:import.meta.url=__filename",
`--outfile=${helper}`,
],
- { stdio: "inherit" },
+ {
+ stdio: "inherit",
+ // Native CI installs the helper's dependencies only in the SDK.
+ env: { ...process.env, NODE_PATH: sdkModules },
+ },
);
const nativeDirectory = join(testDirectory, "native", nativeTarget);
mkdirSync(nativeDirectory, { recursive: true });
diff --git a/sdk/typescript/scripts/fixtures/package-deep-scan.mjs b/sdk/typescript/scripts/fixtures/package-deep-scan.mjs
index e62b5b039..553b86574 100644
--- a/sdk/typescript/scripts/fixtures/package-deep-scan.mjs
+++ b/sdk/typescript/scripts/fixtures/package-deep-scan.mjs
@@ -29,6 +29,7 @@ const root = await realpath(
await mkdtemp(join(tmpdir(), "package deep % fixture-")),
);
const installedPlugin = join(installedRoot, "_bundled_plugin");
+let restoreSpawn;
try {
const detachedPlugin = join(root, "standalone plugin %", "codex-security");
await cp(installedPlugin, detachedPlugin, { recursive: true });
@@ -59,17 +60,28 @@ try {
? "package-codex.exe"
: "package-deep-codex.mjs",
);
- if (process.platform === "win32")
- await copyFile(process.execPath, executable);
- await chmod(executable, 0o700);
if (process.platform === "win32") {
- // The direct SDK engine launches its preflight from this process too.
- process.env.PACKAGE_DEEP_EXECUTABLE = executable;
- await import(pathToFileURL(join(root, "package-deep-spawn.mjs")).href);
+ await copyFile(process.execPath, executable);
+ const { installFixtureSpawn } = await import(
+ pathToFileURL(join(root, "package-deep-spawn.mjs")).href
+ );
+ restoreSpawn = installFixtureSpawn(executable);
}
+ await chmod(executable, 0o700);
- await runInstalledSdk(installedPlugin, executable);
- await runDetachedPlugin(detachedPlugin, executable);
+ const checks = await Promise.allSettled([
+ runInstalledSdk(installedPlugin, executable).then(() =>
+ console.log("Validated installed SDK direct Deep Scan and worker retry."),
+ ),
+ runDetachedPlugin(detachedPlugin, executable).then(() =>
+ console.log("Validated detached plugin restart and finalization."),
+ ),
+ ]);
+ const failures = checks.flatMap((check) =>
+ check.status === "rejected" ? [check.reason] : [],
+ );
+ if (failures.length > 0)
+ throw new AggregateError(failures, "Deep Scan package checks failed.");
console.log(
"Validated installed SDK and detached plugin: real Deep processes, bound artifact tools, checkpoints, reducer acceptance, restart before finalization, and sealed results.",
);
@@ -83,6 +95,7 @@ try {
}
throw error;
} finally {
+ restoreSpawn?.();
await rm(root, {
recursive: true,
force: true,
diff --git a/sdk/typescript/scripts/fixtures/package-deep-spawn.mjs b/sdk/typescript/scripts/fixtures/package-deep-spawn.mjs
index e59440558..f75f1f2db 100644
--- a/sdk/typescript/scripts/fixtures/package-deep-spawn.mjs
+++ b/sdk/typescript/scripts/fixtures/package-deep-spawn.mjs
@@ -6,15 +6,25 @@ import { fileURLToPath } from "node:url";
// Windows cannot execute the POSIX fixture's shebang. Preserve the selected
// native executable and its options, inserting only the deterministic protocol
// script, as in the worker launch tests. Every other child runs unchanged.
-const executable = win32.toNamespacedPath(process.env.PACKAGE_DEEP_EXECUTABLE);
const script = fileURLToPath(
new URL("package-deep-codex.mjs", import.meta.url),
);
-const spawn = childProcess.spawn;
-childProcess.spawn = (command, args, options) =>
- spawn(
- command,
- win32.toNamespacedPath(command) === executable ? [script, ...args] : args,
- options,
- );
-syncBuiltinESMExports();
+
+export function installFixtureSpawn(executable) {
+ const selected = win32.toNamespacedPath(executable);
+ const spawn = childProcess.spawn;
+ childProcess.spawn = (command, args, options) =>
+ spawn(
+ command,
+ win32.toNamespacedPath(command) === selected ? [script, ...args] : args,
+ options,
+ );
+ syncBuiltinESMExports();
+ return () => {
+ childProcess.spawn = spawn;
+ syncBuiltinESMExports();
+ };
+}
+
+if (process.env.PACKAGE_DEEP_EXECUTABLE !== undefined)
+ installFixtureSpawn(process.env.PACKAGE_DEEP_EXECUTABLE);
diff --git a/sdk/typescript/scripts/fixtures/package-plugin-compatibility.mjs b/sdk/typescript/scripts/fixtures/package-plugin-compatibility.mjs
new file mode 100644
index 000000000..627771887
--- /dev/null
+++ b/sdk/typescript/scripts/fixtures/package-plugin-compatibility.mjs
@@ -0,0 +1,237 @@
+import assert from "node:assert/strict";
+import {
+ cp,
+ mkdir,
+ readFile,
+ realpath,
+ stat,
+ writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const [installedRoot, consumer, selectedPlugin] = process.argv.slice(2);
+assert.ok(selectedPlugin, "Compatibility fixture requires a selected plugin.");
+assert.notEqual(
+ await realpath(selectedPlugin),
+ await realpath(join(installedRoot, "_bundled_plugin")),
+);
+const selectedHelper = await import(
+ pathToFileURL(join(selectedPlugin, "mcp", "helpers.mjs")).href
+);
+assert.equal(selectedHelper.default, undefined);
+const { CodexSecurity } = await import(
+ pathToFileURL(join(installedRoot, "dist", "index.js")).href
+);
+const { runWorkbench } = await import(
+ pathToFileURL(join(installedRoot, "dist", "runtime.js")).href
+);
+const repository = join(consumer, "compatibility-repository");
+const home = join(consumer, "compatibility-home");
+await mkdir(repository, { mode: 0o700 });
+await mkdir(home, { mode: 0o700 });
+await writeFile(join(repository, "example.py"), "print('synthetic fixture')\n");
+const environment = {
+ ...Object.fromEntries(
+ [
+ "PATH",
+ "Path",
+ "SystemRoot",
+ "WINDIR",
+ "ComSpec",
+ "PATHEXT",
+ "TMP",
+ "TEMP",
+ "TMPDIR",
+ ]
+ .filter((key) => process.env[key] !== undefined)
+ .map((key) => [key, process.env[key]]),
+ ),
+ HOME: home,
+ USERPROFILE: home,
+ CODEX_HOME: home,
+ CODEX_SECURITY_STATE_DIR: join(consumer, "compatibility-state"),
+ OPENAI_API_KEY: "synthetic-compatibility-key",
+};
+const postScanPrompt = "Summarize the completed synthetic scan.";
+const turns = [];
+let scanEnvironment;
+// Model execution and its sandbox probe are inert. Plugin selection, bootstrap, admission,
+// finalization, report generation and workbench completion use the installed SDK.
+const client = new CodexSecurity(
+ { pythonPath: process.env.PYTHON, pluginPath: selectedPlugin },
+ {
+ environment,
+ probeCodexSandbox: async () => {},
+ createCodex({ env }) {
+ scanEnvironment = env;
+ return {
+ startThread() {
+ return {
+ id: "compatibility-thread",
+ async runStreamed(prompt) {
+ turns.push(prompt);
+ return {
+ events: (async function* () {
+ if (turns.length === 1) {
+ const plugin = env.CODEX_SECURITY_PLUGIN_ROOT;
+ const scanDir = env.CODEX_SECURITY_SCAN_DIR;
+ await cp(
+ join(plugin, "examples", "completed-scan"),
+ scanDir,
+ { recursive: true },
+ );
+ const manifestPath = join(scanDir, "scan-manifest.json");
+ const manifest = JSON.parse(
+ await readFile(manifestPath, "utf8"),
+ );
+ const metadata = JSON.parse(
+ await readFile(
+ join(plugin, ".codex-plugin", "plugin.json"),
+ "utf8",
+ ),
+ );
+ manifest.scan.id = env.CODEX_SECURITY_SCAN_ID;
+ manifest.scan.producer.version = metadata.version;
+ delete manifest.scan.sealedAt;
+ delete manifest.scan.artifacts;
+ manifest.scan.scope.context = " ";
+ manifest.scan.threatModel = {
+ summary: "Archive input",
+ assumptions: [" "],
+ };
+ manifest.scan.target = {
+ kind: env.CODEX_SECURITY_TARGET_KIND,
+ targetId: env.CODEX_SECURITY_TARGET_ID,
+ displayName: env.CODEX_SECURITY_TARGET_DISPLAY_NAME,
+ snapshotDigest: env.CODEX_SECURITY_TARGET_SNAPSHOT_DIGEST,
+ };
+ for (const name of ["findings.json", "coverage.json"]) {
+ const file = join(scanDir, name);
+ const document = JSON.parse(await readFile(file, "utf8"));
+ document.scanId = manifest.scan.id;
+ for (const finding of document.findings ?? []) {
+ delete finding.findingId;
+ delete finding.occurrenceId;
+ delete finding.fingerprints;
+ finding.locations[0].path = "src/./extract.py";
+ finding.locations[0].role = " ";
+ }
+ if (name === "coverage.json") {
+ document.openQuestions = [
+ "What deployment controls apply?",
+ ];
+ document.surfaces = ["HTTP API", "ArchiveSurface"].map(
+ (id) => ({
+ ...document.surfaces[0],
+ id,
+ notes: " ",
+ riskArea: " ",
+ }),
+ );
+ delete document.surfaces[1].receiptRefs;
+ document.surfaces.push({
+ label: "Unidentified surface",
+ disposition: "reported",
+ });
+ document.completeness = "partial";
+ document.deferred = [
+ { reason: "Deployment review remains." },
+ ];
+ }
+ await writeFile(file, JSON.stringify(document));
+ }
+ await writeFile(manifestPath, JSON.stringify(manifest));
+ } else {
+ assert.equal(prompt, postScanPrompt);
+ const manifest = JSON.parse(
+ await readFile(
+ join(env.CODEX_SECURITY_SCAN_DIR, "scan-manifest.json"),
+ "utf8",
+ ),
+ );
+ assert.equal(manifest.scan.status, "completed");
+ assert.ok(manifest.scan.sealedAt);
+ assert.ok(
+ (
+ await stat(
+ join(env.CODEX_SECURITY_SCAN_DIR, "report.md"),
+ )
+ ).isFile(),
+ );
+ }
+ yield {
+ type: "thread.started",
+ thread_id: "compatibility-thread",
+ };
+ yield { type: "turn.completed", usage: null };
+ })(),
+ };
+ },
+ };
+ },
+ };
+ },
+ },
+);
+try {
+ const result = await client.run(repository, {
+ outputDir: join(consumer, "compatibility-output"),
+ postScanPrompt,
+ });
+ assert.equal(
+ await realpath(scanEnvironment.CODEX_SECURITY_PLUGIN_ROOT),
+ await realpath(selectedPlugin),
+ );
+ assert.equal(result.manifest.scan.status, "completed");
+ assert.ok(result.manifest.scan.sealedAt);
+ assert.deepEqual(
+ result.coverage.surfaces.map((surface) => surface.id),
+ ["HTTP API", "ArchiveSurface"],
+ );
+ assert.equal(turns.length, 2);
+ assert.equal(result.findings.findings.length, 1);
+ assert.equal(
+ result.findings.findings[0].locations[0].path,
+ "src/./extract.py",
+ );
+ assert.equal(result.findings.findings[0].locations[0].role, " ");
+ assert.equal(result.coverage.surfaces[0].notes, " ");
+ assert.equal(result.coverage.surfaces[0].riskArea, " ");
+ assert.equal(result.coverage.completeness, "partial");
+ // Main normalizes absent receipt references without changing review disposition.
+ assert.equal(result.coverage.surfaces[1].disposition, "reported");
+ assert.deepEqual(result.coverage.surfaces[1].receiptRefs, []);
+ assert.deepEqual(result.coverage.deferred, []);
+ assert.ok(
+ result.coverage.openQuestions.length > 0 &&
+ result.coverage.openQuestions.every(
+ (entry) => entry.question === "What deployment controls apply?",
+ ),
+ );
+ assert.equal(result.manifest.scan.scope.context, " ");
+ assert.deepEqual(result.manifest.scan.threatModel.assumptions, [" "]);
+ const saved = await runWorkbench(
+ {
+ python: scanEnvironment.PYTHON,
+ pluginRoot: scanEnvironment.CODEX_SECURITY_PLUGIN_ROOT,
+ environment: scanEnvironment,
+ },
+ ["get-scan", "--scan-id", result.manifest.scan.id],
+ );
+ assert.equal(saved.scan.progress.status, "complete");
+ assert.equal(process.exitCode ?? 0, 0);
+ console.log(
+ JSON.stringify({
+ selectedPlugin,
+ installedPlugin: scanEnvironment.CODEX_SECURITY_PLUGIN_ROOT,
+ scanId: result.manifest.scan.id,
+ scanDir: result.scanDir,
+ turns: turns.length,
+ status: saved.scan.progress.status,
+ coverageIds: result.coverage.surfaces.map((surface) => surface.id),
+ }),
+ );
+} finally {
+ await client.close();
+}
diff --git a/sdk/typescript/scripts/smoke-package.mjs b/sdk/typescript/scripts/smoke-package.mjs
index d57b921e3..4edb9d308 100644
--- a/sdk/typescript/scripts/smoke-package.mjs
+++ b/sdk/typescript/scripts/smoke-package.mjs
@@ -797,6 +797,34 @@ try {
],
{ cwd: consumer },
);
+ const selectedPlugin = join(consumer, "compatibility-selected-plugin");
+ await cp(join(installedRoot, "_bundled_plugin"), selectedPlugin, {
+ recursive: true,
+ });
+ const selectedHelper = join(selectedPlugin, "mcp", "helpers.mjs");
+ const loader = await readFile(selectedHelper, "utf8");
+ // Selected plugins can provide the CLI helpers without the SDK admission export.
+ const olderLoader = loader.replace(
+ "export default runtimeModule.exports;",
+ "",
+ );
+ assert.notEqual(olderLoader, loader);
+ await writeFile(selectedHelper, olderLoader);
+ run(
+ process.execPath,
+ [
+ join(
+ packageRoot,
+ "scripts",
+ "fixtures",
+ "package-plugin-compatibility.mjs",
+ ),
+ installedRoot,
+ consumer,
+ selectedPlugin,
+ ],
+ { cwd: consumer },
+ );
await smokeNestedDeepScanWorker(installedRoot, consumer);
run(
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index b3d804ba4..f18ade1b9 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -2098,6 +2098,7 @@ export class CodexSecurity {
events,
signal,
scanDir,
+ scanId,
pluginRoot: runtime.plugin.installedRoot,
pythonPath: session.python,
protectedRoot,
@@ -2351,6 +2352,7 @@ export class CodexSecurity {
events: (await followUp()).events,
signal,
scanDir,
+ scanId,
pluginRoot: runtime.plugin.installedRoot,
pythonPath: session.python,
protectedRoot,
@@ -3868,6 +3870,7 @@ async function removeTargetPathsFile(path: string | null): Promise<void> {
}
interface ScanEventRunOptions extends Pick<ScanOptions, "onReconnect"> {
+ scanId?: string;
thread: Pick<CodexThreadLike, "id">;
events: AsyncGenerator<ScanEvent>;
signal: AbortSignal;
@@ -3898,6 +3901,7 @@ export async function runScanEvents(
let scanStarted = false;
let tacStatusReported = false;
try {
+ options.signal.throwIfAborted();
const turn = await readCodexTurn({
thread: options.thread,
events: options.events,
@@ -3969,7 +3973,44 @@ export async function runScanEvents(
"Codex Security did not report a thread ID.",
);
}
- if (options.onFinalize !== undefined) {
+ // Managed scans reconcile saved checkpoints before admitting canonical artifacts.
+ if (options.workbenchValidated && options.onFinalize !== undefined) {
+ usage = (await options.onFinalize(usage)) ?? usage;
+ }
+ options.signal.throwIfAborted();
+ await requireScanArtifacts(
+ options.scanDir,
+ ["scan-manifest.json", "findings.json", "coverage.json"],
+ options.signal,
+ );
+ const [manifest, findings, coverage] = await Promise.all(
+ ["scan-manifest.json", "findings.json", "coverage.json"].map(
+ async (name) =>
+ JSON.parse(
+ new TextDecoder("utf-8", { fatal: true }).decode(
+ await readScanFile(options.scanDir, name, name, options.signal),
+ ),
+ ),
+ ),
+ );
+ const helper = (
+ await import(
+ pathToFileURL(join(await bundledPluginRoot(), "mcp/helpers.mjs")).href
+ )
+ ).default;
+ const draft = helper.parseCanonicalScanDraft({
+ scanId: options.scanId ?? manifest.scan.id,
+ manifest,
+ findings,
+ coverage,
+ });
+ options.signal.throwIfAborted();
+ if (draft.complete === false) {
+ throw new IncompleteScanError(
+ "Codex Security produced only an unfinished audit checkpoint.",
+ );
+ }
+ if (!options.workbenchValidated && options.onFinalize !== undefined) {
usage = (await options.onFinalize(usage)) ?? usage;
}
const result = await collectResult(
@@ -4359,23 +4400,11 @@ function addScanCosts(
};
}
-async function collectResult(
- turnResult: TurnResultMetadata,
- threadId: string,
+async function requireScanArtifacts(
scanDir: string,
- pluginRoot: string,
- expectation: ScanExpectation,
+ required: readonly string[],
signal: AbortSignal,
- workbenchValidated = false,
- pythonPath?: string,
- protectedRoot?: string,
-): Promise<ScanResult> {
- const required = [
- "scan-manifest.json",
- "findings.json",
- "coverage.json",
- "report.md",
- ];
+): Promise<void> {
const missing: string[] = [];
for (const name of required) {
try {
@@ -4394,6 +4423,24 @@ async function collectResult(
`Codex Security scan completed without required artifacts: ${missing.join(", ")}`,
);
}
+}
+
+async function collectResult(
+ turnResult: TurnResultMetadata,
+ threadId: string,
+ scanDir: string,
+ pluginRoot: string,
+ expectation: ScanExpectation,
+ signal: AbortSignal,
+ workbenchValidated = false,
+ pythonPath?: string,
+ protectedRoot?: string,
+): Promise<ScanResult> {
+ await requireScanArtifacts(
+ scanDir,
+ ["scan-manifest.json", "findings.json", "coverage.json", "report.md"],
+ signal,
+ );
const { manifest, findings, coverage } = await loadContract(scanDir, {
pluginRoot,
expectation,
diff --git a/sdk/typescript/tests-ts/api-audit-admission.test.ts b/sdk/typescript/tests-ts/api-audit-admission.test.ts
new file mode 100644
index 000000000..604dd94a9
--- /dev/null
+++ b/sdk/typescript/tests-ts/api-audit-admission.test.ts
@@ -0,0 +1,651 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { afterEach, expect, test } from "bun:test";
+import { build } from "esbuild";
+import { createApiTestFixtures } from "./support/temporary-directories.js";
+import { runScanEvents } from "../src/api.js";
+import { loadContract } from "../src/contract.js";
+import { PLUGIN_ROOT, copyCompletedScan } from "./plugin-root.js";
+import { completedEvents } from "./support/api-events.js";
+import { sha256 } from "./support/finding-identity.js";
+
+const { temporaryDirectory, cleanup } = createApiTestFixtures();
+afterEach(cleanup);
+
+const bundle = await build({
+ stdin: {
+ resolveDir: fileURLToPath(
+ new URL("../../../plugins/codex-security/mcp-app/", import.meta.url),
+ ),
+ contents: `export * from "./src/artifact-scan-draft.ts";
+ export * from "./src/deep-scan/artifacts.ts";
+ export * from "./src/deep-scan/artifact-validation.ts";
+ export * from "./src/deep-scan/worker-runner.ts";`,
+ },
+ bundle: true,
+ format: "esm",
+ platform: "node",
+ loader: { ".md": "text" },
+ write: false,
+});
+const bundlePath = join(await temporaryDirectory(), "deep-admission.mjs");
+await writeFile(bundlePath, bundle.outputFiles[0]!.contents);
+const {
+ createDeepScanArtifacts,
+ recordCodexSecurityScanDraftViaWorkbench,
+ parseCanonicalScanDraft,
+ parseScanDraft,
+ validateDiscoveryArtifacts,
+ DeepScanWorkerRunner,
+} = await import(pathToFileURL(bundlePath).href);
+
+interface DraftFixture {
+ scanId: string;
+ complete?: boolean;
+ scope?: Record<string, unknown>;
+ threatModel?: Record<string, unknown>;
+ findings: Record<string, unknown>[];
+ coverage: Record<string, unknown>;
+}
+
+const scanId = "811aef98-3709-4c2d-8b7a-742977521865";
+type Mutation =
+ | "missing-findings"
+ | "contradictory-coverage"
+ | "inverted-lines"
+ | "wrong-scan"
+ | "legacy-details";
+const cases: {
+ name: string;
+ coverage: "complete" | "partial" | "unknown";
+ complete?: boolean;
+ mutation?: Mutation;
+ accepted: boolean;
+}[] = [
+ {
+ name: "complete coverage",
+ coverage: "complete",
+ complete: true,
+ accepted: true,
+ },
+ {
+ name: "partial coverage",
+ coverage: "partial",
+ complete: true,
+ accepted: true,
+ },
+ {
+ name: "unknown coverage",
+ coverage: "unknown",
+ complete: true,
+ accepted: true,
+ },
+ { name: "omitted completion marker", coverage: "partial", accepted: true },
+ {
+ name: "persisted legacy details",
+ coverage: "partial",
+ mutation: "legacy-details",
+ accepted: true,
+ },
+ {
+ name: "unfinished checkpoint",
+ coverage: "partial",
+ complete: false,
+ accepted: false,
+ },
+ {
+ name: "missing findings",
+ coverage: "partial",
+ mutation: "missing-findings",
+ accepted: false,
+ },
+ {
+ name: "complete coverage with deferred work",
+ coverage: "partial",
+ mutation: "contradictory-coverage",
+ accepted: false,
+ },
+ {
+ name: "inverted finding lines",
+ coverage: "partial",
+ mutation: "inverted-lines",
+ accepted: false,
+ },
+ {
+ name: "mismatched canonical scan ID",
+ coverage: "partial",
+ mutation: "wrong-scan",
+ accepted: false,
+ },
+];
+
+for (const scenario of cases) {
+ test(`Standard and Deep production admission: ${scenario.name}`, async () => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ const standardRoot = join(root, "standard");
+ const deepRoot = join(root, "deep");
+ await Promise.all([
+ mkdir(repository),
+ mkdir(standardRoot, { mode: 0o700 }),
+ mkdir(deepRoot, { mode: 0o700 }),
+ ]);
+ const semantic: DraftFixture = {
+ scanId,
+ ...(scenario.complete === undefined
+ ? {}
+ : { complete: scenario.complete }),
+ scope: { summary: "Archive extraction." },
+ threatModel: { summary: "An untrusted caller supplies archive entries." },
+ findings: [
+ {
+ ruleId: "path-traversal.archive",
+ title: "Unsafe archive extraction",
+ summary: "An archive entry reaches a filesystem write.",
+ severity: { level: "high" },
+ confidence: { level: "high", rationale: "Source review." },
+ taxonomy: { category: "path-traversal", cwe: ["CWE-22"] },
+ locations: [{ path: "extract.py", startLine: 4, endLine: 7 }],
+ remediation: "Validate the resolved output path before writing.",
+ provenance: { source: "local_plugin", candidateId: "archive-entry" },
+ },
+ ],
+ coverage: {
+ completeness: scenario.coverage,
+ surfaces: [
+ {
+ label: "Archive extraction",
+ disposition: "reported",
+ },
+ ],
+ explicitExclusions: [],
+ deferred:
+ scenario.coverage === "complete"
+ ? []
+ : [
+ {
+ reason: "Deployment controls remain unverified.",
+ },
+ ],
+ },
+ };
+ await recordCodexSecurityScanDraftViaWorkbench(
+ {
+ root: standardRoot,
+ repoRoot: repository,
+ layout: "scan",
+ scanId,
+ mode: "standard",
+ status: "running",
+ scope: ".",
+ targetContract: {
+ target: {
+ allowedKinds: ["directory_snapshot"],
+ targetId: "target_example",
+ displayName: "example",
+ requiredSnapshotDigest: `codex-security-snapshot/v1:sha256:${"a".repeat(64)}`,
+ },
+ scope: { requiredIncludePaths: ["."], requiredExcludePaths: [] },
+ diffTarget: null,
+ },
+ },
+ semantic,
+ async (args: string[]) => {
+ const draft = JSON.parse(
+ await readFile(args[args.indexOf("--draft-path") + 1]!, "utf8"),
+ );
+ await Promise.all(
+ [
+ ["manifest", "scan-manifest.json"],
+ ["findings", "findings.json"],
+ ["coverage", "coverage.json"],
+ ].map(([key, name]) =>
+ writeFile(join(standardRoot, name!), JSON.stringify(draft[key!])),
+ ),
+ );
+ },
+ );
+ const submitted = mutateDraft(semantic, scenario.mutation);
+ const findings = {
+ scanId: submitted.scanId,
+ findings: submitted.findings?.map((finding) => ({
+ ...finding,
+ findingId: "finding_example",
+ occurrenceId: "occurrence_example",
+ fingerprints: { identity: "synthetic" },
+ })),
+ };
+ const coverage = JSON.parse(
+ await readFile(join(standardRoot, "coverage.json"), "utf8"),
+ );
+ Object.assign(coverage, submitted.coverage);
+ await Promise.all([
+ writeFile(join(standardRoot, "findings.json"), JSON.stringify(findings)),
+ writeFile(join(standardRoot, "coverage.json"), JSON.stringify(coverage)),
+ ]);
+ const standard = await observeStandardAdmission(
+ repository,
+ standardRoot,
+ scanId,
+ );
+
+ const artifacts = createDeepScanArtifacts(deepRoot);
+ const acceptedPaths: string[] = [];
+ let executions = 0;
+ const runner = new DeepScanWorkerRunner({
+ run: {
+ scanId,
+ scanDir: deepRoot,
+ targetPath: repository,
+ scope: ".",
+ config: { subagents: 0 },
+ },
+ artifacts,
+ pluginRoot: PLUGIN_ROOT,
+ signal: new AbortController().signal,
+ retryDelaysMs: [],
+ random: () => 0,
+ log: () => {},
+ clock: { now: () => Date.now(), sleep: async () => {} },
+ executor: {
+ async run(request: {
+ artifactContext: { root: string };
+ onThreadStarted?: (id: string) => Promise<void>;
+ }) {
+ executions++;
+ await request.onThreadStarted?.("deep-thread");
+ await writeFile(
+ join(request.artifactContext.root, "result.json"),
+ JSON.stringify(submitted),
+ );
+ return { threadId: "deep-thread" };
+ },
+ },
+ store: {
+ async updateWorker(update: {
+ status: string;
+ resultManifestPath?: string;
+ }) {
+ if (update.status === "succeeded") {
+ acceptedPaths.push(update.resultManifestPath!);
+ return { ...update, completionSequence: 1 };
+ }
+ return update;
+ },
+ },
+ });
+ const deepResult = await runner.runDiscoveryWorker(
+ "worker-1",
+ "discovery-1",
+ );
+ expect(executions).toBe(1);
+ if (scenario.accepted) {
+ expect(standard.error).toBe(standard.finalization);
+ expect(standard.finalizations).toBe(1);
+ expect(deepResult.status).toBe("succeeded");
+ expect(acceptedPaths).toEqual([deepResult.worker.resultPath]);
+ const deepDraft: DraftFixture = await validateDiscoveryArtifacts(
+ artifacts,
+ deepResult.worker.resultPath,
+ scanId,
+ );
+ const canonicalDraft = parseCanonicalScanDraft({
+ scanId,
+ manifest: JSON.parse(
+ await readFile(join(standardRoot, "scan-manifest.json"), "utf8"),
+ ),
+ findings,
+ coverage,
+ });
+ expect(deepDraft.findings).toEqual(canonicalDraft.findings);
+ expect(deepDraft.coverage).toEqual(canonicalDraft.coverage);
+ expect(deepDraft.scope).toEqual(canonicalDraft.scope);
+ expect(deepDraft.threatModel).toEqual(canonicalDraft.threatModel);
+ if (scenario.mutation === "legacy-details") {
+ expect(deepDraft.findings[0]!["validation"]).toEqual({
+ limitations: ["Legacy persisted limitation."],
+ });
+ }
+ } else {
+ expect(standard.error).toBeInstanceOf(Error);
+ expect(standard.error).not.toBe(standard.finalization);
+ expect(standard.finalizations).toBe(0);
+ expect(deepResult.status).toBe("failed");
+ expect(acceptedPaths).toHaveLength(0);
+ }
+ const manifest = JSON.parse(
+ await readFile(join(standardRoot, "scan-manifest.json"), "utf8"),
+ );
+ expect(manifest.scan.sealedAt).toBeUndefined();
+ await expect(readFile(join(standardRoot, "report.md"))).rejects.toThrow();
+ });
+}
+
+test("Standard admission preserves existing canonical scan IDs", async () => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ await mkdir(repository);
+ const scanDir = await copyCompletedScan(root);
+ const manifest = JSON.parse(
+ await readFile(join(scanDir, "scan-manifest.json"), "utf8"),
+ );
+ const standard = await observeStandardAdmission(repository, scanDir);
+ expect(manifest.scan.id).toBe("scan_example_001");
+ expect(standard.error).toBe(standard.finalization);
+ expect(standard.finalizations).toBe(1);
+});
+
+test.each(["scan-manifest.json", "findings.json", "coverage.json"])(
+ "Standard admission preserves BOM-prefixed %s bytes",
+ async (name) => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ await mkdir(repository);
+ const scanDir = await copyCompletedScan(root);
+ const file = join(scanDir, name);
+ const bytes = Buffer.concat([
+ Buffer.from([0xef, 0xbb, 0xbf]),
+ await readFile(file),
+ ]);
+ await writeFile(file, bytes);
+ const standard = await observeStandardAdmission(repository, scanDir);
+ expect(standard.error).toBe(standard.finalization);
+ expect(standard.finalizations).toBe(1);
+ expect(await readFile(file)).toEqual(bytes);
+ },
+);
+
+test.each(["HTTP API", "ArchiveSurface", "", 17])(
+ "canonical coverage ID %j follows the canonical contract",
+ async (id) => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ await mkdir(repository);
+ const scanDir = await copyCompletedScan(root);
+ const [manifest, findings, coverage] = await Promise.all(
+ ["scan-manifest.json", "findings.json", "coverage.json"].map(
+ async (name) => JSON.parse(await readFile(join(scanDir, name), "utf8")),
+ ),
+ );
+ coverage.surfaces[0].id = id;
+ await writeFile(join(scanDir, "coverage.json"), JSON.stringify(coverage));
+ const canonical = {
+ scanId: manifest.scan.id,
+ manifest,
+ findings,
+ coverage,
+ };
+ const standard = await observeStandardAdmission(repository, scanDir);
+ if (typeof id === "string" && id.length > 0) {
+ const draft = parseCanonicalScanDraft(canonical);
+ expect(draft.coverage.surfaces[0].id).toBe(id);
+ expect(standard.error).toBe(standard.finalization);
+ expect(standard.finalizations).toBe(1);
+ expect(() => parseScanDraft({ ...draft, scanId })).toThrow();
+ const live = structuredClone(draft);
+ for (const surface of live.coverage.surfaces) surface.id = "http-api";
+ expect(() => parseScanDraft({ ...live, scanId })).not.toThrow();
+ } else {
+ expect(() => parseCanonicalScanDraft(canonical)).toThrow();
+ expect(standard.error).toBeInstanceOf(Error);
+ expect(standard.error).not.toBe(standard.finalization);
+ expect(standard.finalizations).toBe(0);
+ }
+ },
+);
+
+test.each([
+ { path: "src/./extract.py", notes: " ", accepted: true },
+ { path: "src//extract.py", notes: " ", accepted: true },
+ { path: "src/extract.py/", notes: " ", accepted: true },
+ { path: "../extract.py", notes: "Checked", accepted: false },
+ { path: "/src/extract.py", notes: "Checked", accepted: false },
+ { path: "C:/extract.py", notes: "Checked", accepted: false },
+ { path: "src\\extract.py", notes: "Checked", accepted: false },
+ { path: "src/\u0000extract.py", notes: "Checked", accepted: false },
+ { path: "src/\ud800extract.py", notes: "Checked", accepted: false },
+ { path: ".", notes: "Checked", accepted: false },
+ { path: "src/extract.py", notes: "", accepted: false },
+ { path: "src/extract.py", notes: 17, accepted: false },
+ {
+ path: "src/extract.py",
+ notes: "Checked",
+ questions: [17],
+ accepted: false,
+ },
+])(
+ "canonical fields retain their rules: %j",
+ async ({ path, notes, questions, accepted }) => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ await mkdir(repository);
+ const scanDir = await copyCompletedScan(root);
+ const [manifest, findings, coverage] = await Promise.all(
+ ["scan-manifest.json", "findings.json", "coverage.json"].map(
+ async (name) => JSON.parse(await readFile(join(scanDir, name), "utf8")),
+ ),
+ );
+ manifest.scan.scope.context = " ";
+ manifest.scan.threatModel = {
+ summary: "Archive input",
+ assumptions: [" "],
+ };
+ const finding = findings.findings[0];
+ finding.locations[0].path = path;
+ finding.locations[0].role = " ";
+ finding.severity.vector = " ";
+ finding.codeEvidence = [
+ {
+ id: "archive-write",
+ label: "Filesystem write",
+ path,
+ startLine: 41,
+ code: "write(entry)",
+ explanation: "Archive entry reaches a write.",
+ },
+ ];
+ coverage.surfaces[0].notes = notes;
+ coverage.surfaces[0].riskArea = " ";
+ coverage.openQuestions = questions ?? [
+ "What deployment controls apply?",
+ { question: "Which controls apply?", followUpPrompt: " " },
+ ];
+ await Promise.all([
+ writeFile(join(scanDir, "scan-manifest.json"), JSON.stringify(manifest)),
+ writeFile(join(scanDir, "findings.json"), JSON.stringify(findings)),
+ writeFile(join(scanDir, "coverage.json"), JSON.stringify(coverage)),
+ ]);
+ const canonical = {
+ scanId: manifest.scan.id,
+ manifest,
+ findings,
+ coverage,
+ };
+ const standard = await observeStandardAdmission(repository, scanDir);
+ if (accepted) {
+ const draft = parseCanonicalScanDraft(canonical);
+ expect(draft.findings[0].locations[0].path).toBe(path);
+ expect(draft.coverage.surfaces[0].notes).toBe(notes);
+ expect(draft.coverage.openQuestions).toEqual(coverage.openQuestions);
+ expect(draft.scope.context).toBe(" ");
+ expect(draft.threatModel.assumptions).toEqual([" "]);
+ expect(standard.error).toBe(standard.finalization);
+ expect(standard.finalizations).toBe(1);
+ expect(() => parseScanDraft({ ...draft, scanId })).toThrow();
+ const live = structuredClone(draft);
+ delete live.scope.context;
+ delete live.threatModel;
+ delete live.findings[0].severity.vector;
+ live.findings[0].locations[0] = { path: "src/extract.py", startLine: 41 };
+ live.findings[0].codeEvidence[0].path = "src/extract.py";
+ live.coverage.surfaces[0].notes = "Checked";
+ delete live.coverage.surfaces[0].riskArea;
+ live.coverage.openQuestions[1].followUpPrompt = "Describe controls.";
+ expect(() => parseScanDraft({ ...live, scanId })).not.toThrow();
+ const unsafeEvidence = structuredClone(canonical);
+ unsafeEvidence.findings.findings[0].codeEvidence[0].path =
+ "../outside.py";
+ expect(() => parseCanonicalScanDraft(unsafeEvidence)).toThrow();
+ } else {
+ expect(() => parseCanonicalScanDraft(canonical)).toThrow();
+ expect(standard.error).toBeInstanceOf(Error);
+ expect(standard.error).not.toBe(standard.finalization);
+ expect(standard.finalizations).toBe(0);
+ }
+ },
+);
+
+test("canonical admission preserves legacy evidence coordinates", async () => {
+ const scanDir = await copyCompletedScan(await temporaryDirectory());
+ const file = join(scanDir, "findings.json");
+ const findings = JSON.parse(await readFile(file, "utf8"));
+ const evidence = {
+ id: "legacy-reversed-end",
+ code: "read(input)",
+ path: "src/legacy.py",
+ startLine: 48,
+ endLine: 47,
+ };
+ findings.findings[0].code_evidence = [evidence];
+ const saved = JSON.stringify(findings);
+ await writeFile(file, saved);
+ const manifestFile = join(scanDir, "scan-manifest.json");
+ const manifest = JSON.parse(await readFile(manifestFile, "utf8"));
+ manifest.scan.artifacts.find(
+ (artifact: { path: string }) => artifact.path === "findings.json",
+ ).sha256 = sha256(saved);
+ await writeFile(manifestFile, JSON.stringify(manifest));
+ const expectation = {
+ repository: "/repository",
+ repositoryRevision: "deadbeef",
+ target: { kind: "repository" as const, paths: [] },
+ mode: "standard" as const,
+ pluginVersion: "0.1.0",
+ };
+ let finalizations = 0;
+ const result = await runScanEvents({
+ thread: { id: null },
+ events: completedEvents(),
+ signal: new AbortController().signal,
+ scanDir,
+ pluginRoot: PLUGIN_ROOT,
+ expectation,
+ workbenchValidated: true,
+ onFinalize: async () => {
+ const contract = await loadContract(scanDir, {
+ pluginRoot: PLUGIN_ROOT,
+ expectation,
+ workbenchValidated: true,
+ });
+ expect(contract.findings.findings[0]?.["code_evidence"]).toEqual([
+ evidence,
+ ]);
+ finalizations++;
+ },
+ });
+ expect(finalizations).toBe(1);
+ expect(result.turnResult.status).toBe("completed");
+ expect(await readFile(file, "utf8")).toBe(saved);
+
+ const coverage = JSON.parse(
+ await readFile(join(scanDir, "coverage.json"), "utf8"),
+ );
+ const draft = parseCanonicalScanDraft({
+ scanId: manifest.scan.id,
+ manifest,
+ findings,
+ coverage,
+ });
+ draft.coverage.surfaces[0].id = "archive-extraction";
+ expect(() => parseScanDraft({ ...draft, scanId })).toThrow(
+ "code_evidence[0].endLine must not precede startLine",
+ );
+});
+
+test("canonical admission still rejects reversed typed evidence bounds", async () => {
+ const scanDir = await copyCompletedScan(await temporaryDirectory());
+ const file = join(scanDir, "findings.json");
+ const findings = JSON.parse(await readFile(file, "utf8"));
+ findings.findings[0].codeEvidence = [
+ {
+ id: "typed-reversed-end",
+ label: "Source read",
+ code: "read(input)",
+ explanation: "The input reaches a read.",
+ path: "src/typed.py",
+ startLine: 48,
+ endLine: 47,
+ },
+ ];
+ await writeFile(file, JSON.stringify(findings));
+ const outcome = await observeStandardAdmission("/repository", scanDir);
+ expect(outcome.error).toMatchObject({
+ message: expect.stringContaining(
+ "codeEvidence[0].endLine must not precede startLine",
+ ),
+ });
+ expect(outcome.finalizations).toBe(0);
+});
+
+async function observeStandardAdmission(
+ repository: string,
+ scanDir: string,
+ scanId?: string,
+) {
+ const finalization = new Error("The enclosing finalizer owns the next step.");
+ let finalizations = 0;
+ const thread = {
+ id: "standard-thread",
+ async runStreamed() {
+ return { events: completedEvents("standard-thread") };
+ },
+ };
+ const error = await runScanEvents({
+ scanId,
+ thread,
+ events: completedEvents("standard-thread"),
+ signal: new AbortController().signal,
+ scanDir,
+ pluginRoot: PLUGIN_ROOT,
+ expectation: {
+ repository,
+ repositoryRevision: null,
+ target: { kind: "repository", paths: [] },
+ mode: "standard",
+ pluginVersion: "0.1.0",
+ },
+ onFinalize: async () => {
+ finalizations++;
+ throw finalization;
+ },
+ }).catch((error: unknown) => error);
+ return {
+ error,
+ finalization,
+ finalizations,
+ };
+}
+
+function mutateDraft(input: DraftFixture, mutation?: Mutation): DraftFixture {
+ const draft = structuredClone(input);
+ if (mutation === "missing-findings")
+ return { ...draft, findings: undefined } as unknown as DraftFixture;
+ if (mutation === "wrong-scan")
+ draft.scanId = "553a0c18-dcdf-4a3b-8e39-2751a8187bce";
+ if (mutation === "contradictory-coverage")
+ draft.coverage["completeness"] = "complete";
+ if (mutation === "inverted-lines") {
+ const locations = draft.findings[0]!["locations"] as Record<
+ string,
+ unknown
+ >[];
+ locations[0]!["endLine"] = 1;
+ }
+ if (mutation === "legacy-details")
+ draft.findings[0]!["validation"] = {
+ method: null,
+ limitations: "Legacy persisted limitation.",
+ };
+ return draft;
+}
diff --git a/sdk/typescript/tests-ts/api-events.test.ts b/sdk/typescript/tests-ts/api-events.test.ts
index 8c786f53c..4b9bb38f7 100644
--- a/sdk/typescript/tests-ts/api-events.test.ts
+++ b/sdk/typescript/tests-ts/api-events.test.ts
@@ -1,6 +1,6 @@
import { copyCompletedScan, PLUGIN_ROOT } from "./plugin-root.js";
import { once } from "node:events";
-import { chmod, mkdir, rm, stat } from "node:fs/promises";
+import { chmod, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
import { existsSync } from "node:fs";
import { join } from "node:path";
import {
@@ -539,7 +539,8 @@ describe("one-shot scan events", () => {
test("lets the workbench seal artifacts before validating completed scans", async () => {
const root = await temporaryDirectory();
- const scanDir = join(root, "scan");
+ const scanDir = await copyCompletedScan(root);
+ await rm(join(scanDir, "report.md"));
const events = completedEvents();
let finalized = false;
@@ -552,7 +553,8 @@ describe("one-shot scan events", () => {
cache_write_input_tokens: 0,
output_tokens: 3,
});
- expect(existsSync(join(scanDir, "scan-manifest.json"))).toBe(false);
+ expect(existsSync(join(scanDir, "scan-manifest.json"))).toBe(true);
+ expect(existsSync(join(scanDir, "report.md"))).toBe(false);
await copyCompletedScan(root);
finalized = true;
},
@@ -1148,16 +1150,60 @@ describe("one-shot scan events", () => {
});
});
-test("missing required artifacts remain incomplete scans", async () => {
+test.each([
+ "scan-manifest.json",
+ "findings.json",
+ "coverage.json",
+ "report.md",
+])("missing required artifact %s remains an incomplete scan", async (name) => {
const scanDir = await copyCompletedScan(await temporaryDirectory());
- await rm(join(scanDir, "report.md"));
+ await rm(join(scanDir, name));
await expect(runEvents(scanDir, completedEvents())).rejects.toMatchObject({
name: IncompleteScanError.name,
- message:
- "Codex Security scan completed without required artifacts: report.md",
+ message: `Codex Security scan completed without required artifacts: ${name}`,
});
});
+test("an aborted completed turn cannot prepare workbench artifacts", async () => {
+ const abortController = new AbortController();
+ let finalizations = 0;
+ async function* events() {
+ yield { type: "thread.started", thread_id: "synthetic-thread" } as const;
+ yield { type: "turn.started" } as const;
+ abortController.abort("synthetic cancellation");
+ yield completedTurn();
+ }
+ await expect(
+ runEvents("/synthetic-scan", events(), {
+ abortController,
+ workbenchValidated: true,
+ onFinalize: async () => {
+ finalizations++;
+ },
+ }),
+ ).rejects.toMatchObject({ name: ScanInterruptedError.name });
+ expect(finalizations).toBe(0);
+});
+
+test("workbench reconciliation precedes admission of canonical artifacts", async () => {
+ const scanDir = await copyCompletedScan(await temporaryDirectory());
+ const file = join(scanDir, "scan-manifest.json");
+ const original = await readFile(file, "utf8");
+ const interrupted = JSON.parse(original);
+ interrupted.scan.complete = false;
+ await writeFile(file, JSON.stringify(interrupted));
+ let reconciliations = 0;
+ const result = await runEvents(scanDir, completedEvents(), {
+ workbenchValidated: true,
+ onFinalize: async () => {
+ reconciliations++;
+ await writeFile(file, original);
+ },
+ });
+ expect(reconciliations).toBe(1);
+ expect(result.turnResult.status).toBe("completed");
+});
+
test.skipIf(process.platform === "win32")(
"preserves unsafe scan-root diagnostics instead of reporting missing files",
async () => {
diff --git a/sdk/typescript/tests-ts/build-plugin.test.ts b/sdk/typescript/tests-ts/build-plugin.test.ts
index ba23197b1..3d5bbdcd0 100644
--- a/sdk/typescript/tests-ts/build-plugin.test.ts
+++ b/sdk/typescript/tests-ts/build-plugin.test.ts
@@ -1,6 +1,7 @@
import { execFile } from "node:child_process";
import {
chmod,
+ copyFile,
cp,
mkdir,
readFile,
@@ -212,6 +213,119 @@ describe("bundled plugin build", () => {
]);
expect(helper.stdout).toBe("[]\n");
expect(helper.stderr).toBe("");
+ const repository = await temporaryDirectory();
+ const policy = "Preserve this synthetic inherited security policy.";
+ await writeFixture(
+ repository,
+ "SECURITY.md",
+ `# Synthetic policy\n${policy}\n`,
+ );
+ const alias = join(await temporaryDirectory(), "plugin link");
+ await symlink(
+ root,
+ alias,
+ process.platform === "win32" ? "junction" : "dir",
+ );
+ await mkdir(join(root, "scripts"), { recursive: true });
+ await copyFile(
+ join(plugin, "scripts", "launch_codex_security_mcp"),
+ join(root, "scripts", "launch_codex_security_mcp"),
+ );
+ const node = (
+ await execFileAsync("node", ["--print", "process.execPath"])
+ ).stdout.trim();
+ for (const pluginPath of [root, alias]) {
+ const linkedHelper = join(pluginPath, "mcp", "helpers.mjs");
+ const list = await execFileAsync(
+ process.platform === "win32" ? node : "/bin/sh",
+ [
+ ...(process.platform === "win32"
+ ? [linkedHelper]
+ : [
+ join(pluginPath, "scripts", "launch_codex_security_mcp"),
+ "--helper",
+ ]),
+ "resolve-security-md",
+ "--repo",
+ repository,
+ "--list",
+ ],
+ { env: { ...process.env, CODEX_MCP_NODE_PATH: node, NODE_PATH: "" } },
+ );
+ expect(list.stdout).toBe('["SECURITY.md"]\n');
+ expect(list.stderr).toBe("");
+ const guidance = await execFileAsync(node, [
+ linkedHelper,
+ "resolve-security-md",
+ "--repo",
+ repository,
+ "--scope",
+ repository,
+ "--out",
+ "-",
+ ]);
+ expect(guidance.stdout).toContain(policy);
+ expect(guidance.stderr).toBe("");
+ }
+
+ const imported = await execFileAsync(
+ "node",
+ [
+ "--input-type=module",
+ "--eval",
+ `
+ import assert from "node:assert/strict";
+ import { pathToFileURL } from "node:url";
+ const { default: helpers } = await import(pathToFileURL(process.argv[2]).href);
+ const input = {
+ scanId: "synthetic-scan",
+ manifest: { scan: {} },
+ findings: { findings: [] },
+ coverage: {
+ completeness: "complete", surfaces: [], explicitExclusions: [], deferred: [],
+ },
+ };
+ assert.equal(helpers.parseCanonicalScanDraft(input).scanId, input.scanId);
+ assert.throws(() => helpers.parseCanonicalScanDraft({
+ ...input, coverage: { ...input.coverage, completeness: "invalid" },
+ }));
+ assert.equal(process.exitCode, undefined);
+ `,
+ "helper-import-test",
+ join(destination, "helpers.mjs"),
+ ],
+ { cwd: root, env: { ...process.env, NODE_PATH: "" } },
+ );
+ expect(imported.stdout).toBe("");
+ expect(imported.stderr).toBe("");
+ const workerImport = await execFileAsync(
+ "node",
+ [
+ "--input-type=module",
+ "--eval",
+ `
+ import assert from "node:assert/strict";
+ import { Worker } from "node:worker_threads";
+ import { pathToFileURL } from "node:url";
+ const worker = new Worker(
+ "const { parentPort, workerData } = require('node:worker_threads');" +
+ "import(workerData).then(() => parentPort.postMessage('imported'));",
+ { eval: true, workerData: pathToFileURL(process.argv[1]).href, execArgv: [] },
+ );
+ const messages = [];
+ worker.on("message", (message) => messages.push(message));
+ await new Promise((resolve, reject) => {
+ worker.on("error", reject);
+ worker.on("exit", (code) => code === 0 ? resolve() : reject(new Error(String(code))));
+ });
+ assert.deepEqual(messages, ["imported"]);
+ `,
+ join(destination, "helpers.mjs"),
+ ],
+ { cwd: root, env: { ...process.env, NODE_PATH: "" } },
+ );
+ expect(workerImport.stdout).toBe("");
+ expect(workerImport.stderr).toBe("");
const preflight = await execFileAsync(
"node",
[