Skip to content

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

fix(scans)!: preserve original knowledge context when resuming (#1556)

mldangelo-oai9613a6a0305a
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 28c9750c2..f24b614ab 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -1157,6 +1157,14 @@ scan and custom-validation prompts when the original used them:
codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
```
+A rerun creates a new scan. When the original has saved input identities, the
+rerun reports changes to the scan instructions or knowledge base. `scans show`
+includes the saved scope, runtime and Deep Scan settings, instruction digest,
+and knowledge snapshot/document digests. JSON includes these identities under
+`recipe.scanInputs`. The instruction digest covers the exact UTF-8 prompt text;
+document digests cover the extracted text workers receive. These identities
+describe supplied inputs, not proof that a model read or followed every passage.
+
History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
`$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. Keep it private,
writable, and outside the target repository. Session logs may contain sensitive
@@ -1180,7 +1188,14 @@ and Codex session in the same state directory. Checkout identity, revision, and
contents must match. Completed, failed, and canceled scans need a rerun instead.
Resume retains scan ID, completed workers, artifacts, accumulated cost, and saved
-settings/instructions. New records save the authentication mode, explicit safety
+settings/instructions. Knowledge-bearing scans save their extracted documents in
+the private `.scan-knowledge.json` continuation file beside the scan artifacts.
+Resume verifies and uses that snapshot even if the original files changed or were
+deleted. Preserve it with the scan directory; canonical reports do not embed its
+document text. Old individual scans without a saved knowledge snapshot require a
+new scan when they used a knowledge base. Old scans without a knowledge base and
+bulk campaigns with an already-bound snapshot retain their existing resume path.
+New records save the authentication mode, explicit safety
identifier, and post-scan prompt; older records cannot reconstruct missing values.
A failed connection leaves the scan available for another resume attempt.
Compatible scans can resume after plugin updates; sealed results keep their
diff --git a/sdk/typescript/scripts/check-package.mjs b/sdk/typescript/scripts/check-package.mjs
index 89122d9ef..6d2d01090 100644
--- a/sdk/typescript/scripts/check-package.mjs
+++ b/sdk/typescript/scripts/check-package.mjs
@@ -201,6 +201,7 @@ const allowedFiles = new Set([
"scan-comparison",
"scan-dashboard",
"scan-history-renderer",
+ "scan-inputs",
"scan-logs",
"security-policy",
"security-policy-cli",
diff --git a/sdk/typescript/scripts/fixtures/package-deep-codex.mjs b/sdk/typescript/scripts/fixtures/package-deep-codex.mjs
index c57ba26ae..8e313e33e 100644
--- a/sdk/typescript/scripts/fixtures/package-deep-codex.mjs
+++ b/sdk/typescript/scripts/fixtures/package-deep-codex.mjs
@@ -27,6 +27,8 @@ async function run() {
const args = process.argv.slice(2);
if (args.includes("app-server")) {
await trace({ phase: "preflight", args });
+ const threadId = "package-sdk-owner";
+ const sessionPath = join(process.env.CODEX_HOME, `${threadId}.jsonl`);
for await (const line of createInterface({ input: process.stdin })) {
const message = JSON.parse(line);
if (message.id === undefined) continue;
@@ -35,6 +37,41 @@ async function run() {
case "initialize":
result = { userAgent: "package-fixture" };
break;
+ case "thread/start":
+ assert.equal(message.params.threadSource, "security_scan");
+ assert.equal(message.params.ephemeral, false);
+ result = {
+ thread: { id: threadId, path: sessionPath },
+ model: "gpt-5.5",
+ reasoningEffort: "high",
+ };
+ break;
+ case "thread/inject_items":
+ assert.equal(message.params.threadId, threadId);
+ assert.equal(message.params.items[0].role, "user");
+ await writeFile(
+ sessionPath,
+ `${JSON.stringify({
+ type: "turn_context",
+ payload: {
+ permission_profile: {
+ type: "managed",
+ file_system: {
+ type: "restricted",
+ entries: [
+ {
+ path: { type: "special", value: { kind: "root" } },
+ access: "read",
+ },
+ ],
+ },
+ network: "restricted",
+ },
+ },
+ })}\n`,
+ );
+ result = {};
+ break;
case "config/read":
result = {
config: {
diff --git a/sdk/typescript/scripts/fixtures/package-deep-scan.mjs b/sdk/typescript/scripts/fixtures/package-deep-scan.mjs
index 4abe15ee9..e62b5b039 100644
--- a/sdk/typescript/scripts/fixtures/package-deep-scan.mjs
+++ b/sdk/typescript/scripts/fixtures/package-deep-scan.mjs
@@ -62,6 +62,11 @@ try {
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 runInstalledSdk(installedPlugin, executable);
await runDetachedPlugin(detachedPlugin, executable);
@@ -386,43 +391,16 @@ async function runInstalledSdk(pluginRoot, executable) {
version: manifest.version,
},
}),
- // Replace only the parent model's tool choice. The installed SDK registers
- // and finalizes the scan; the packaged MCP runs the real Deep lifecycle.
- createCodex({ env, apiKey }) {
+ // The installed SDK runs the direct engine without a parent model turn.
+ createCodex() {
return {
startThread() {
return {
id: owner,
async runStreamed() {
- return {
- events: (async function* () {
- yield { type: "thread.started", thread_id: owner };
- scanId = env.CODEX_SECURITY_SCAN_ID;
- // The pinned SDK maps its apiKey option to this child variable.
- const rpc = await server(f, {
- ...env,
- ...(apiKey ? { CODEX_API_KEY: apiKey } : {}),
- });
- try {
- const result = await rpc.call(
- "start_codex_security_deep_scan",
- { scanId },
- metadata(f, owner),
- );
- await assertDraft(result.manifestPath);
- } finally {
- await rpc.close();
- }
- yield {
- type: "turn.completed",
- usage: {
- input_tokens: 1,
- cached_input_tokens: 0,
- output_tokens: 1,
- },
- };
- })(),
- };
+ assert.fail(
+ "The direct engine must not start a parent model turn.",
+ );
},
};
},
@@ -439,6 +417,9 @@ async function runInstalledSdk(pluginRoot, executable) {
maxDiscoveryRuns: 2,
stopAfterNoNew: 1,
outputDir: join(f.directory, "output"),
+ onScanRegistered(scan) {
+ scanId = scan.scanId;
+ },
});
assert.equal(result.threadId, owner);
assert.equal(result.manifest.scan.status, "completed");
@@ -452,7 +433,7 @@ async function runInstalledSdk(pluginRoot, executable) {
} finally {
await client.close();
}
- await assertExecutions(f, scanId, 4);
+ await assertExecutions(f, scanId, 5);
}
async function assertDraft(path) {
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index cefad44f9..801006670 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -136,9 +136,11 @@ import {
} from "./errors.js";
import {
prepareKnowledgeBase,
+ readKnowledgeBaseSnapshot,
type PreparedKnowledgeBase,
type KnowledgeBaseSnapshot,
} from "./knowledge-base.js";
+import { scanInputIdentity, saveScanKnowledge } from "./scan-inputs.js";
import { FindingWorkflow, workflowDigest } from "./finding-workflow.js";
import {
ScanResult,
@@ -298,7 +300,7 @@ const DEEP_SCAN_CONFIG_PATH_ENVIRONMENT =
"CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH";
export interface ScanOptions extends ScanSettings {
- /** @internal Reuse the knowledge inputs bound to a bulk campaign manifest. */
+ /** @internal Reuse captured knowledge inputs for related operations or resume. */
knowledgeBaseSnapshot?: KnowledgeBaseSnapshot;
/** @internal Resume a CLI Deep Scan with its saved launch recipe. */
resumeScanId?: string;
@@ -1297,8 +1299,25 @@ export class CodexSecurity {
);
}
if (options.knowledgeBasePaths?.length) {
+ if (
+ options.resumeScanId !== undefined &&
+ options.knowledgeBaseSnapshot === undefined
+ ) {
+ throw new CodexSecurityError(
+ "Resuming a scan requires its saved knowledge-base snapshot. Use scans resume with the original scan state, or start a new scan.",
+ );
+ }
+ options = {
+ ...options,
+ knowledgeBaseSnapshot:
+ options.knowledgeBaseSnapshot ??
+ (await readKnowledgeBaseSnapshot(
+ options.knowledgeBasePaths,
+ signal,
+ )),
+ };
knowledgeBase = await prepareKnowledgeBase(
- options.knowledgeBaseSnapshot ?? options.knowledgeBasePaths,
+ options.knowledgeBaseSnapshot!,
signal,
);
}
@@ -1648,6 +1667,8 @@ export class CodexSecurity {
onError: reportTrackingError,
});
costTracker = tracker;
+ const scanKnowledge =
+ knowledgeBase === null ? undefined : options.knowledgeBaseSnapshot;
const recipe = scanRecipe({
repository: repo,
target: normalized,
@@ -1663,6 +1684,10 @@ export class CodexSecurity {
cyberAccessProgram: options.cyberAccessProgram,
});
if (options.scanPrompt?.trim()) recipe["requiresScanPrompt"] = true;
+ recipe["scanInputs"] = scanInputIdentity(
+ options.scanPrompt,
+ scanKnowledge,
+ );
if (options.safetyIdentifier !== undefined)
recipe["safetyIdentifier"] = options.safetyIdentifier;
if (options.postScanPrompt !== undefined)
@@ -1744,6 +1769,18 @@ export class CodexSecurity {
if (typeof registration["sealedProducerVersion"] === "string") {
expectation.pluginVersion = registration["sealedProducerVersion"];
}
+ const savedInputs = savedRecipe["scanInputs"];
+ if (
+ isRecord(savedInputs) &&
+ workflowDigest(savedInputs["knowledgeBase"]) !==
+ workflowDigest(
+ (recipe["scanInputs"] as JsonObject)["knowledgeBase"],
+ )
+ ) {
+ throw new CodexSecurityError(
+ "The supplied knowledge base differs from this scan's original context. Restore the saved snapshot or start a new scan.",
+ );
+ }
}
const targetId = registration["targetId"];
const contract = registration["contract"];
@@ -1819,6 +1856,9 @@ export class CodexSecurity {
? { startedAt: registration["startedAt"] }
: {}),
});
+ if (options.resumeScanId === undefined && scanKnowledge !== undefined) {
+ await saveScanKnowledge(scanDir, scanKnowledge);
+ }
if (typeof registration["archivedScanDir"] === "string") {
notifyObserver(
options,
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 28f7dfc67..f03cf43d1 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -146,6 +146,12 @@ import {
formatTokenUsage,
} from "./cost-model.js";
import { readRegularInputFile, resolveScanPrompts } from "./prompt-files.js";
+import {
+ readKnowledgeBaseSnapshot,
+ type KnowledgeBaseSnapshot,
+} from "./knowledge-base.js";
+import { restoreScanKnowledge, scanInputIdentity } from "./scan-inputs.js";
+import { workflowDigest } from "./finding-workflow.js";
import {
CodexSecurityError,
AuthenticationRequiredError,
@@ -936,6 +942,8 @@ export function resolveCliPath(directory: string, value: string): AbsolutePath {
}
interface ScanArguments extends ResolvedScanSettings {
+ rerunInputIdentity?: JsonValue;
+ knowledgeBaseSnapshot?: KnowledgeBaseSnapshot;
codexOverrides: JsonObject;
projectConfig?: ProjectConfigProvenance;
resumeScanId?: string;
@@ -2296,6 +2304,13 @@ export async function main(
dependencies.currentDirectory(),
saved["scanDir"],
);
+ if (scanArguments.knowledgeBasePaths.length > 0) {
+ scanArguments.knowledgeBaseSnapshot = await restoreScanKnowledge(
+ scanArguments.outputDir,
+ scanArguments.repository!,
+ (saved["recipe"] as JsonObject)["scanInputs"],
+ );
+ }
scanArguments.parentScanId = undefined;
// Resume uses the installed engine with the saved recipe and checkpoints.
scanArguments.expectedPluginVersion = undefined;
@@ -2316,7 +2331,8 @@ export async function main(
},
})
.command("rerun", {
- description: "Rerun a saved scan with its original configuration.",
+ description:
+ "Start a new scan using saved settings and current checkout/context files.",
hint: "Incomplete full-output JSON or JSONL uses ok: false and keeps available scan results under data.",
destructive: true,
mcp: false,
@@ -2444,6 +2460,9 @@ export async function main(
);
scanArguments.verbose = options.verbose;
scanArguments.showCost = options.showCost;
+ scanArguments.rerunInputIdentity = isJsonObject(recipe)
+ ? (recipe["scanInputs"] ?? null)
+ : null;
} catch (error) {
const message = errorMessage(error);
errorOutput.write(`codex-security: ${diagnosticLines(message)}\n`);
@@ -8433,6 +8452,7 @@ async function executeScan(
}
const options: ScanOptions = {
...pickScanSettings(arguments_),
+ knowledgeBaseSnapshot: arguments_.knowledgeBaseSnapshot,
...(arguments_.resumeScanId === undefined
? {}
: { resumeScanId: arguments_.resumeScanId }),
@@ -8720,6 +8740,41 @@ async function executeScan(
}
},
};
+ if (arguments_.rerunInputIdentity !== undefined) {
+ if (options.knowledgeBasePaths?.length) {
+ options.knowledgeBaseSnapshot = await readKnowledgeBaseSnapshot(
+ options.knowledgeBasePaths,
+ preparationAbortController.signal,
+ );
+ }
+ const previousInputs = arguments_.rerunInputIdentity;
+ const currentInputs = scanInputIdentity(
+ options.scanPrompt,
+ options.knowledgeBaseSnapshot,
+ );
+ const changes = isJsonObject(previousInputs)
+ ? ["scanPromptSha256", "knowledgeBase"]
+ .filter(
+ (key) =>
+ workflowDigest(previousInputs[key] ?? null) !==
+ workflowDigest(currentInputs[key] ?? null),
+ )
+ .map((key) =>
+ key === "scanPromptSha256"
+ ? "scan instructions"
+ : "knowledge base",
+ )
+ : [];
+ try {
+ writeAboveProgress(() =>
+ errorOutput.write(
+ `codex-security: Starting a new scan with current checkout/context files.${changes.length ? ` Changed inputs: ${changes.join(", ")}.` : ""}\n`,
+ ),
+ );
+ } catch {
+ // Optional input-change diagnostics must not prevent the new scan.
+ }
+ }
if (arguments_.dryRun) {
preflight = await security.preflight(repository, options);
} else {
diff --git a/sdk/typescript/src/scan-history-renderer.ts b/sdk/typescript/src/scan-history-renderer.ts
index 305152274..879d373d2 100644
--- a/sdk/typescript/src/scan-history-renderer.ts
+++ b/sdk/typescript/src/scan-history-renderer.ts
@@ -297,6 +297,16 @@ export function renderScanHistory(
);
}
const recipe = result["recipe"] as JsonObject | undefined;
+ const target = recipe?.["target"] as JsonObject | undefined;
+ if (target) {
+ lines.push(` ${strong("SCOPE")} ${clean(JSON.stringify(target))}`);
+ }
+ const deepScan = recipe?.["deepScan"] as JsonObject | undefined;
+ if (deepScan) {
+ lines.push(
+ ` ${strong("DEEP SCAN")} ${clean(JSON.stringify(deepScan))}`,
+ );
+ }
const config = recipe?.["config"] as JsonObject | undefined;
if (config && Object.keys(config).length > 0) {
lines.push(
@@ -333,6 +343,23 @@ export function renderScanHistory(
` ${strong("KNOWLEDGE BASE")} ${knowledgeBase.map((path) => dim(clean(path))).join(", ")}`,
);
}
+ const inputs = recipe?.["scanInputs"] as JsonObject | undefined;
+ if (inputs) {
+ lines.push(
+ ` ${strong("SCAN INSTRUCTIONS")} ${inputs["scanPromptSha256"] ? `sha256:${clean(inputs["scanPromptSha256"])}` : "none"}`,
+ );
+ const knowledge = inputs["knowledgeBase"] as JsonObject | null;
+ if (knowledge) {
+ lines.push(
+ ` ${strong("KNOWLEDGE SNAPSHOT")} sha256:${clean(knowledge["sha256"])}`,
+ );
+ for (const document of knowledge["documents"] as JsonObject[]) {
+ lines.push(
+ ` ${clean(document["name"])} sha256:${clean(document["sha256"])}`,
+ );
+ }
+ }
+ }
const artifacts = result["artifacts"] as JsonObject | undefined;
if (artifacts && Object.keys(artifacts).length > 0) {
lines.push(` ${strong("ARTIFACTS")}`);
diff --git a/sdk/typescript/src/scan-inputs.ts b/sdk/typescript/src/scan-inputs.ts
new file mode 100644
index 000000000..612245dd9
--- /dev/null
+++ b/sdk/typescript/src/scan-inputs.ts
@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { z } from "zod";
+import type { JsonObject } from "./config.js";
+import { CodexSecurityError, errorMessage } from "./errors.js";
+import { workflowDigest } from "./finding-workflow.js";
+import type { KnowledgeBaseSnapshot } from "./knowledge-base.js";
+import { readRegularInputFile } from "./prompt-files.js";
+
+const KNOWLEDGE_SNAPSHOT_FILE = ".scan-knowledge.json";
+
+const knowledgeSnapshotSchema = z.object({
+ sources: z.array(z.string()),
+ protectedRoots: z.array(z.string()).optional(),
+ documents: z.record(z.string(), z.string()),
+});
+
+function textDigest(text: string): string {
+ return createHash("sha256").update(text).digest("hex");
+}
+
+export function scanInputIdentity(
+ prompt: string | undefined,
+ knowledge?: KnowledgeBaseSnapshot,
+): JsonObject {
+ return {
+ scanPromptSha256: prompt?.trim() ? textDigest(prompt) : null,
+ knowledgeBase:
+ knowledge === undefined
+ ? null
+ : {
+ sha256: workflowDigest(knowledge),
+ documents: Object.entries(knowledge.documents).map(
+ ([name, text]) => ({
+ name,
+ sha256: textDigest(text),
+ }),
+ ),
+ },
+ };
+}
+
+export async function saveScanKnowledge(
+ scanDir: string,
+ snapshot: KnowledgeBaseSnapshot,
+): Promise<void> {
+ // This private continuation input is separate from canonical report artifacts.
+ await writeFile(
+ join(scanDir, KNOWLEDGE_SNAPSHOT_FILE),
+ JSON.stringify(snapshot),
+ {
+ flag: "wx",
+ mode: 0o600,
+ },
+ );
+}
+
+export async function restoreScanKnowledge(
+ scanDir: string,
+ repository: string,
+ identity: unknown,
+): Promise<KnowledgeBaseSnapshot> {
+ const parsedIdentity = z
+ .object({
+ knowledgeBase: z.object({ sha256: z.string() }),
+ })
+ .safeParse(identity);
+ if (!parsedIdentity.success) {
+ throw new CodexSecurityError(
+ "This scan has no saved knowledge-base snapshot. Start a new scan with the original knowledge-base files; resuming could mix different context versions.",
+ );
+ }
+ const path = join(scanDir, KNOWLEDGE_SNAPSHOT_FILE);
+ let text: string;
+ try {
+ text = await readRegularInputFile(path, repository);
+ } catch (error) {
+ throw new CodexSecurityError(
+ `Cannot restore the original scan knowledge base at ${path}: ${errorMessage(error)} Restore that file or start a new scan.`,
+ { cause: error },
+ );
+ }
+ let snapshot: KnowledgeBaseSnapshot;
+ try {
+ snapshot = knowledgeSnapshotSchema.parse(JSON.parse(text));
+ } catch (error) {
+ throw new CodexSecurityError(
+ `Cannot read the saved knowledge-base snapshot: ${errorMessage(error)} Restore the original snapshot or start a new scan.`,
+ { cause: error },
+ );
+ }
+ if (workflowDigest(snapshot) !== parsedIdentity.data.knowledgeBase.sha256) {
+ throw new CodexSecurityError(
+ "The saved knowledge-base snapshot changed. Restore the original snapshot or start a new scan.",
+ );
+ }
+ // Document names become staging filenames; imported state cannot escape that directory.
+ if (
+ Object.keys(snapshot.documents).some(
+ (name) => name === "." || name === ".." || basename(name) !== name,
+ )
+ ) {
+ throw new CodexSecurityError(
+ "Saved knowledge-base documents must have plain filenames.",
+ );
+ }
+ return snapshot;
+}
diff --git a/sdk/typescript/tests-ts/api-direct-deep-scan.test.ts b/sdk/typescript/tests-ts/api-direct-deep-scan.test.ts
index 45b4512aa..95daf13bc 100644
--- a/sdk/typescript/tests-ts/api-direct-deep-scan.test.ts
+++ b/sdk/typescript/tests-ts/api-direct-deep-scan.test.ts
@@ -13,6 +13,7 @@ import {
scanRuntimeDependencies,
} from "./support/api-events.js";
import { createApiTestFixtures } from "./support/temporary-directories.js";
+import { runTestInSubprocess } from "./support/test-subprocess.js";
const { temporaryDirectory, cleanup } = createApiTestFixtures();
afterEach(cleanup);
@@ -220,6 +221,13 @@ test.each(["configured", "managed"] as const)(
);
test("Node retains the direct Deep Scan capability", async () => {
+ if (
+ runTestInSubprocess(
+ import.meta.path,
+ "Node retains the direct Deep Scan capability",
+ )
+ )
+ return;
const root = await temporaryDirectory();
const source = new URL("../src/deep-scan.ts", import.meta.url);
const built = await Bun.build({
diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.ts
index b85439344..5150ada7b 100644
--- a/sdk/typescript/tests-ts/api.test.ts
+++ b/sdk/typescript/tests-ts/api.test.ts
@@ -89,6 +89,7 @@ import { runTestInSubprocess } from "./support/test-subprocess.js";
import { writeSession as writeUsageSession } from "./support/usage-rollout.js";
import { importScan } from "../src/import-scan.js";
import { FindingWorkflow } from "../src/finding-workflow.js";
+import { restoreScanKnowledge, scanInputIdentity } from "../src/scan-inputs.js";
import { DEFAULT_DEEP_SCAN_SETTINGS } from "../src/deep-scan-defaults.js";
import { VERSION } from "../src/version.js";
import { createProviderProfile } from "../src/provider-profile.js";
@@ -2117,6 +2118,42 @@ describe("CodexSecurity orchestration", () => {
await client.close();
});
+ test("retains the registered scan ID when continuation storage becomes unavailable", async () => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const document = join(root, "architecture.md");
+ await writeFile(document, "Synthetic original architecture.");
+ const onScanRegistered = mock();
+ const createCodex = mock(() =>
+ fail("No worker can start without its saved context"),
+ );
+ const failedScans: Array<readonly string[]> = [];
+ await using client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (_options, args, input) => {
+ const result = mockWorkbench(args, input);
+ if (args[0] === "register-cli-scan") {
+ // Simulate storage disappearing after the database accepts registration.
+ await rm(scanDir, { recursive: true });
+ }
+ if (args[0] === "fail-scan") failedScans.push(args);
+ return result;
+ },
+ createCodex,
+ });
+ await expect(
+ client.run(repository, {
+ knowledgeBasePaths: [document],
+ onScanRegistered,
+ }),
+ ).rejects.toThrow("ENOENT");
+ expect(onScanRegistered.mock.calls).toEqual([
+ [{ scanId: "scan_example_001", scanDir }],
+ ]);
+ expect(failedScans).toHaveLength(1);
+ expect(failedScans[0]).toContain("scan_example_001");
+ expect(createCodex).not.toHaveBeenCalled();
+ });
+
test("identifies stored credential types without exposing stored secrets", async () => {
for (const [storedAuthentication, expected] of [
[
@@ -5475,7 +5512,7 @@ describe("CodexSecurity orchestration", () => {
});
test.each(["repository", "standalone-file"])(
- "protects %s knowledge-base context without retaining its documents",
+ "protects %s knowledge-base context and retains private continuation inputs",
async (kind) => {
const scanPrompt = "Review the synthetic authorization boundary.";
const root = await temporaryDirectory();
@@ -5570,12 +5607,11 @@ describe("CodexSecurity orchestration", () => {
}),
});
- await expect(
- client.run(repository, {
- knowledgeBasePaths: [knowledgeBase],
- scanPrompt,
- }),
- ).resolves.toMatchObject({ threadId: "thread-1" });
+ const result = await client.run(repository, {
+ knowledgeBasePaths: [knowledgeBase],
+ scanPrompt,
+ });
+ expect(result).toMatchObject({ threadId: "thread-1" });
expect(existsSync(knowledgeDirectory)).toBe(false);
expect(workbenchGit).toBe(expectedGit);
expect(prompt).toContain(
@@ -5587,6 +5623,16 @@ describe("CodexSecurity orchestration", () => {
expect(prompt).not.toContain("deep-discovery userContext");
expect(prompt).not.toContain(context.trim());
expect(recipe).toMatchObject({ knowledgeBasePaths: [knowledgeBase] });
+ await rm(document);
+ const saved = await restoreScanKnowledge(
+ scanDir,
+ repository,
+ (recipe as JsonObject)["scanInputs"],
+ );
+ expect(Object.values(saved.documents)).toContain(context);
+ expect((recipe as JsonObject)["scanInputs"]).toEqual(
+ scanInputIdentity(scanPrompt, saved),
+ );
expect(await readdir(scanDir)).not.toContain("knowledge-base");
await client.close();
},
diff --git a/sdk/typescript/tests-ts/cli-workbench.test.ts b/sdk/typescript/tests-ts/cli-workbench.test.ts
index cd350d1ad..7d0ec0381 100644
--- a/sdk/typescript/tests-ts/cli-workbench.test.ts
+++ b/sdk/typescript/tests-ts/cli-workbench.test.ts
@@ -1528,58 +1528,64 @@ describe("CLI workbench", () => {
test("reruns canonical recipes with exact config, policy, plugin, and lineage", async () => {
const onConfig = mock<(config: CodexSecurityConfig) => void>();
const onTurn = mock<(repository: string, options: ScanOptions) => void>();
- const knowledgeBasePath = resolve("/original/security.md");
- const savedConfig = {
- approval_policy: "on-request",
- model: "gpt-original",
- model_reasoning_effort: "high",
- features: { goals: true },
- agents: { max_threads: 6 },
- };
- expect(
- await runCapturedCli(
- main,
- ["scans", "rerun", "scan-original"],
- dependencies({
- onConfig,
- onTurn,
- onWorkbench: () => ({
- scanId: "scan-original",
- recipe: {
- repository: "/original/repository",
- target: { kind: "paths", paths: ["src", "packages/core"] },
- mode: "deep",
- pluginVersion: "1.2.3",
- failOnSeverity: "high",
- knowledgeBasePaths: [knowledgeBasePath],
- deepScan: {
- workers: 2,
- subagents: 0,
- stopAfterNoNew: 3,
- maxDiscoveryRuns: 10,
- maxTimeHours: 1.5,
+ const knowledgeRoot = await temporaryDirectory("rerun-knowledge-");
+ try {
+ const knowledgeBasePath = join(knowledgeRoot, "security.md");
+ await writeFile(knowledgeBasePath, "Synthetic architecture context.\n");
+ const savedConfig = {
+ approval_policy: "on-request",
+ model: "gpt-original",
+ model_reasoning_effort: "high",
+ features: { goals: true },
+ agents: { max_threads: 6 },
+ };
+ expect(
+ await runCapturedCli(
+ main,
+ ["scans", "rerun", "scan-original"],
+ dependencies({
+ onConfig,
+ onTurn,
+ onWorkbench: () => ({
+ scanId: "scan-original",
+ recipe: {
+ repository: "/original/repository",
+ target: { kind: "paths", paths: ["src", "packages/core"] },
+ mode: "deep",
+ pluginVersion: "1.2.3",
+ failOnSeverity: "high",
+ knowledgeBasePaths: [knowledgeBasePath],
+ deepScan: {
+ workers: 2,
+ subagents: 0,
+ stopAfterNoNew: 3,
+ maxDiscoveryRuns: 10,
+ maxTimeHours: 1.5,
+ },
+ config: savedConfig,
},
- config: savedConfig,
- },
+ }),
}),
- }),
- ),
- ).toBe(0);
- expect(onConfig.mock.lastCall?.[0]?.codexOverrides).toEqual(savedConfig);
- expect(onTurn.mock.lastCall?.[0]).toBe("/original/repository");
- expect(onTurn.mock.lastCall?.[1]).toMatchObject({
- target: ["src", "packages/core"],
- mode: "deep",
- parentScanId: "scan-original",
- expectedPluginVersion: "1.2.3",
- failureSeverity: "high",
- knowledgeBasePaths: [knowledgeBasePath],
- workers: 2,
- subagents: 0,
- stopAfterNoNew: 3,
- maxDiscoveryRuns: 10,
- maxTimeHours: 1.5,
- });
+ ),
+ ).toBe(0);
+ expect(onConfig.mock.lastCall?.[0]?.codexOverrides).toEqual(savedConfig);
+ expect(onTurn.mock.lastCall?.[0]).toBe("/original/repository");
+ expect(onTurn.mock.lastCall?.[1]).toMatchObject({
+ target: ["src", "packages/core"],
+ mode: "deep",
+ parentScanId: "scan-original",
+ expectedPluginVersion: "1.2.3",
+ failureSeverity: "high",
+ knowledgeBasePaths: [knowledgeBasePath],
+ workers: 2,
+ subagents: 0,
+ stopAfterNoNew: 3,
+ maxDiscoveryRuns: 10,
+ maxTimeHours: 1.5,
+ });
+ } finally {
+ await rm(knowledgeRoot, { recursive: true, force: true });
+ }
const references: Array<[JsonObject, ReturnType<typeof DiffTarget.refs>]> =
[
diff --git a/sdk/typescript/tests-ts/scan-history-renderer.test.ts b/sdk/typescript/tests-ts/scan-history-renderer.test.ts
index df7714380..8a2d06750 100644
--- a/sdk/typescript/tests-ts/scan-history-renderer.test.ts
+++ b/sdk/typescript/tests-ts/scan-history-renderer.test.ts
@@ -274,6 +274,17 @@ describe("scan history renderer", () => {
findingsTruncated: true,
artifacts: { markdownReport: "/demo/results/report.md" },
recipe: {
+ target: { kind: "paths", paths: ["src"] },
+ deepScan: { workers: 2, subagents: 0 },
+ scanInputs: {
+ scanPromptSha256: "a".repeat(64),
+ knowledgeBase: {
+ sha256: "b".repeat(64),
+ documents: [
+ { name: "0-architecture.md.txt", sha256: "c".repeat(64) },
+ ],
+ },
+ },
config: {
model: "gpt-5.6-sol",
model_reasoning_effort: "high",
@@ -293,6 +304,14 @@ describe("scan history renderer", () => {
"FINDINGS 20 of 75",
"PARENT SCAN 87654321",
"CONFIGURATION",
+ "SCOPE",
+ '"paths":["src"]',
+ "DEEP SCAN",
+ '"workers":2',
+ `SCAN INSTRUCTIONS sha256:${"a".repeat(64)}`,
+ `KNOWLEDGE SNAPSHOT sha256:${"b".repeat(64)}`,
+ "0-architecture.md.txt",
+ `sha256:${"c".repeat(64)}`,
"model=gpt-5.6-sol",
'features={"goals":true,"multi_agent_v2":{"enabled":true}}',
'trusted_paths=["src","packages/core"]',
diff --git a/sdk/typescript/tests-ts/scan-resume.test.ts b/sdk/typescript/tests-ts/scan-resume.test.ts
index fd49b32b7..b22268d6a 100644
--- a/sdk/typescript/tests-ts/scan-resume.test.ts
+++ b/sdk/typescript/tests-ts/scan-resume.test.ts
@@ -22,6 +22,7 @@ import { scanPreflightCodexConfig, type ScanOptions } from "../src/api.js";
import type { JsonObject } from "../src/config.js";
import { runWorkbench } from "../src/runtime.js";
import { readKnowledgeBaseSnapshot } from "../src/knowledge-base.js";
+import { saveScanKnowledge, scanInputIdentity } from "../src/scan-inputs.js";
import { workflowDigest } from "../src/finding-workflow.js";
import { capture, dependencies } from "./cli-fixtures.js";
import { runPython } from "./support/python-probe.js";
@@ -47,6 +48,7 @@ async function interruptedScan(
> & { config?: JsonObject } = {},
resolvedDeep = false,
modelProvider?: string,
+ knowledgeState: "saved" | "legacy" = "saved",
) {
const root = await temporaryDirectory();
const repository = bulk
@@ -139,6 +141,10 @@ async function interruptedScan(
: { OPENAI_API_KEY: "synthetic-resume-key" }),
};
const command = workbenchCommand(python, () => environment);
+ const knowledgeSnapshot =
+ !bulk && knowledgeState === "saved" && settings.knowledgeBasePaths?.length
+ ? await readKnowledgeBaseSnapshot(settings.knowledgeBasePaths)
+ : undefined;
const recipe = {
repository,
target: { kind: "repository", paths: [] },
@@ -151,6 +157,14 @@ async function interruptedScan(
pluginVersion: "0.1.0",
requiresScanPrompt: true,
...settings,
+ ...(knowledgeSnapshot === undefined
+ ? {}
+ : {
+ scanInputs: scanInputIdentity(
+ "Keep the original scan instructions.",
+ knowledgeSnapshot,
+ ),
+ }),
...(mode === "deep"
? {
deepScan: {
@@ -184,6 +198,8 @@ async function interruptedScan(
}),
);
const scanId = registration["scanId"] as string;
+ if (knowledgeSnapshot !== undefined)
+ await saveScanKnowledge(scanDir, knowledgeSnapshot);
const threadId = randomUUID();
await command([
"set-scan-thread",
@@ -1083,6 +1099,117 @@ test.each([
},
);
+test.each(["unchanged", "edited", "deleted"] as const)(
+ "single Deep resume uses saved knowledge when original files are %s",
+ async (sourceState) => {
+ const documentRoot = await temporaryDirectory();
+ const document = join(documentRoot, "architecture.md");
+ await writeFile(document, "Original architecture.\n");
+ const f = await interruptedScan("deep", false, {
+ knowledgeBasePaths: [document],
+ });
+ const before = await f.command([
+ "get-deep-scan",
+ "--scan-id",
+ f.scanId,
+ "--thread-id",
+ f.threadId,
+ ]);
+ if (sourceState === "edited")
+ await writeFile(document, "Changed architecture.\n");
+ if (sourceState === "deleted") await rm(document);
+ const stdout = capture();
+ const stderr = capture();
+ let resumed = false;
+ let staged = "";
+ const code = await main(
+ ["scans", "resume", f.scanId, "--json"],
+ stdout.stream,
+ stderr.stream,
+ resumeDependencies(f, (codex) => ({
+ startThread() {
+ throw new Error("Expected original session");
+ },
+ resumeThread(threadId) {
+ expect(threadId).toBe(f.threadId);
+ return {
+ id: threadId,
+ async runStreamed(prompt) {
+ expect(prompt).toContain("Keep the original scan instructions.");
+ staged = codex.env!["CODEX_SECURITY_KNOWLEDGE_BASE"]!;
+ expect(
+ await readFile(join(staged, "0-architecture.md.txt"), "utf8"),
+ ).toBe("Original architecture.\n");
+ resumed = true;
+ throw new Error("synthetic interrupted transport");
+ },
+ };
+ },
+ })),
+ );
+ expect(resumed, stderr.text()).toBe(true);
+ expect(code).toBe(2);
+ expect(
+ await readFile(join(f.scanDir, ".scan-knowledge.json"), "utf8"),
+ ).toContain("Original architecture.");
+ expect(await readdir(staged).catch(() => null)).toBeNull();
+ expect(
+ await f.command([
+ "get-deep-scan",
+ "--scan-id",
+ f.scanId,
+ "--thread-id",
+ f.threadId,
+ ]),
+ ).toEqual(before);
+ expect(
+ (await f.command(["get-scan-recipe", "--scan-id", f.scanId]))["recipe"],
+ ).toEqual(f.recipe);
+ },
+);
+
+test.each(["legacy", "missing", "modified"] as const)(
+ "single Deep resume preserves saved work when knowledge snapshot is %s",
+ async (snapshotState) => {
+ const documentRoot = await temporaryDirectory();
+ const document = join(documentRoot, "architecture.md");
+ await writeFile(document, "Original architecture.");
+ const f = await interruptedScan(
+ "deep",
+ false,
+ { knowledgeBasePaths: [document] },
+ false,
+ undefined,
+ snapshotState === "legacy" ? "legacy" : "saved",
+ );
+ const snapshot = join(f.scanDir, ".scan-knowledge.json");
+ if (snapshotState === "missing") await rm(snapshot);
+ if (snapshotState === "modified") {
+ const value = JSON.parse(await readFile(snapshot, "utf8"));
+ value.documents["0-architecture.md.txt"] = "Changed architecture.";
+ await writeFile(snapshot, JSON.stringify(value));
+ }
+ const before = await readFile(f.checkpoint, "utf8");
+ const stderr = capture();
+ const code = await main(
+ ["scans", "resume", f.scanId, "--json"],
+ capture().stream,
+ stderr.stream,
+ resumeDependencies(f, () =>
+ fail("Cannot run with missing or changed original context"),
+ ),
+ );
+ expect(code).toBe(2);
+ expect(stderr.text()).toMatch(/new scan/i);
+ expect(await readFile(f.checkpoint, "utf8")).toBe(before);
+ expect(
+ (await f.command(["get-cli-scan-resume", "--scan-id", f.scanId]))[
+ "recipe"
+ ],
+ ).toEqual(f.recipe);
+ },
+);
+
test("bulk Deep resume stages campaign knowledge after its source is removed", async () => {
const documentRoot = await temporaryDirectory();
const document = join(documentRoot, "architecture.md");
diff --git a/sdk/typescript/tests-ts/sdk-scan-prompts.test.ts b/sdk/typescript/tests-ts/sdk-scan-prompts.test.ts
index 4724c68fa..1b12c67c6 100644
--- a/sdk/typescript/tests-ts/sdk-scan-prompts.test.ts
+++ b/sdk/typescript/tests-ts/sdk-scan-prompts.test.ts
@@ -1,18 +1,213 @@
import { captureCli } from "./support/cli-run.js";
-import { mkdir, symlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile, symlink, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { afterEach, expect, test, mock } from "bun:test";
import type { JsonObject } from "../src/index.js";
import { main } from "../src/cli.js";
-import { dependencies } from "./cli-fixtures.js";
+import { capture, dependencies } from "./cli-fixtures.js";
import { mockWorkbench, TestClient } from "./support/api-client.js";
import { completedCodex, preparedRuntime } from "./support/api-events.js";
import { createApiTestFixtures } from "./support/temporary-directories.js";
import { rejecting } from "./support/errors.js";
+import {
+ prepareKnowledgeBase,
+ readKnowledgeBaseSnapshot,
+} from "../src/knowledge-base.js";
+import {
+ restoreScanKnowledge,
+ saveScanKnowledge,
+ scanInputIdentity,
+} from "../src/scan-inputs.js";
+import { workbenchCommand } from "./support/workbench-command.js";
const { cleanup, temporaryDirectory } = createApiTestFixtures();
afterEach(cleanup);
+test("rerun recognizes unchanged context after the workbench serializes its recipe", async () => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ const scanDir = join(root, "scan");
+ await mkdir(repository);
+ await mkdir(scanDir, { mode: 0o700 });
+ await writeFile(join(repository, "source.ts"), "// synthetic source\n");
+ const document = join(root, "architecture.md");
+ await writeFile(document, "Original architecture.");
+ const scanInputs = scanInputIdentity(
+ undefined,
+ await readKnowledgeBaseSnapshot([document]),
+ );
+ const python = Bun.which("python3") ?? Bun.which("python");
+ expect(python).not.toBeNull();
+ const command = workbenchCommand(python!, join(root, "state"));
+ const saved = await command(
+ [
+ "register-cli-scan",
+ "--repository",
+ repository,
+ "--scan-dir",
+ scanDir,
+ "--registration-json-stdin",
+ ],
+ JSON.stringify({
+ recipe: {
+ repository,
+ target: { kind: "repository", paths: [] },
+ mode: "standard",
+ config: {},
+ knowledgeBasePaths: [document],
+ scanInputs,
+ },
+ }),
+ );
+ const stderr = captureCli(main, "stderr");
+ const onTurn = mock();
+ const code = await stderr.run(
+ ["scans", "rerun", saved["scanId"] as string, "--json"],
+ dependencies({
+ currentDirectory: repository,
+ onWorkbench: command,
+ onTurn,
+ }),
+ );
+ expect(code, stderr.text()).toBe(0);
+ expect(onTurn).toHaveBeenCalledTimes(1);
+ expect(stderr.text()).toContain("Starting a new scan");
+ expect(stderr.text()).not.toContain("Changed inputs:");
+});
+
+test("a throwing rerun notice does not prevent the requested scan", async () => {
+ const repository = await temporaryDirectory();
+ const stdout = capture();
+ const stderr = capture();
+ const onTurn = mock();
+ let attemptedNotice = false;
+ const code = await main(
+ ["scans", "rerun", "saved", "--json"],
+ stdout.stream,
+ {
+ write(value) {
+ if (String(value).includes("Starting a new scan")) {
+ attemptedNotice = true;
+ throw new Error("Synthetic diagnostic sink failure");
+ }
+ return stderr.stream.write(value);
+ },
+ },
+ dependencies({
+ currentDirectory: repository,
+ onTurn,
+ onWorkbench: async () => ({
+ scanId: "saved",
+ recipe: {
+ repository,
+ target: { kind: "repository", paths: [] },
+ mode: "standard",
+ config: {},
+ },
+ }),
+ }),
+ );
+ expect(attemptedNotice).toBe(true);
+ expect(code, stderr.text()).toBe(0);
+ expect(onTurn).toHaveBeenCalledTimes(1);
+ expect(JSON.parse(stdout.text())).toHaveProperty("manifest");
+});
+
+test.skipIf(process.platform === "win32")(
+ "saved knowledge preserves a POSIX backslash filename through capture and restoration",
+ async () => {
+ const root = await temporaryDirectory();
+ const directory = join(root, "documents");
+ const scanDir = join(root, "scan");
+ await mkdir(directory);
+ await mkdir(scanDir);
+ await writeFile(
+ join(directory, "architecture\\v1.md"),
+ "Original architecture.",
+ );
+ const captured = await readKnowledgeBaseSnapshot([directory]);
+ await saveScanKnowledge(scanDir, captured);
+ const restored = await restoreScanKnowledge(
+ scanDir,
+ root,
+ scanInputIdentity(undefined, captured),
+ );
+ const staged = await prepareKnowledgeBase(restored, undefined, root);
+ try {
+ expect(
+ await readFile(join(staged.path, "0-architecture\\v1.md.txt"), "utf8"),
+ ).toBe("Original architecture.");
+ } finally {
+ await staged.cleanup();
+ }
+ },
+);
+
+test("saved knowledge cannot stage documents outside its input directory", async () => {
+ const root = await temporaryDirectory();
+ const scanDir = join(root, "scan");
+ await mkdir(scanDir);
+ const captured = {
+ sources: [],
+ protectedRoots: [],
+ documents: { "../outside.txt": "Synthetic document." },
+ };
+ await saveScanKnowledge(scanDir, captured);
+ await expect(
+ restoreScanKnowledge(scanDir, root, scanInputIdentity(undefined, captured)),
+ ).rejects.toThrow("plain filenames");
+});
+
+test("rerun identifies changed instructions and captures current knowledge for the new scan", async () => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ await mkdir(repository);
+ const document = join(root, "architecture.md");
+ const prompt = join(root, "instructions.md");
+ await writeFile(document, "Original architecture.");
+ const scanInputs = scanInputIdentity(
+ "Original instructions.",
+ await readKnowledgeBaseSnapshot([document]),
+ );
+ await writeFile(document, "Current architecture.");
+ await writeFile(prompt, "Current instructions.");
+ let selected: unknown;
+ const stderr = captureCli(main, "stderr");
+ const code = await stderr.run(
+ ["scans", "rerun", "saved", "--scan-prompt-file", prompt, "--json"],
+ dependencies({
+ currentDirectory: repository,
+ onWorkbench: async () => ({
+ scanId: "saved",
+ recipe: {
+ repository,
+ target: { kind: "repository", paths: [] },
+ mode: "deep",
+ config: {},
+ knowledgeBasePaths: [document],
+ requiresScanPrompt: true,
+ scanInputs,
+ },
+ }),
+ onTurn: (_repository, options) => {
+ selected = options;
+ },
+ }),
+ );
+ expect(code, stderr.text()).toBe(0);
+ expect(selected).toMatchObject({
+ parentScanId: "saved",
+ scanPrompt: "Current instructions.",
+ knowledgeBaseSnapshot: {
+ documents: { "0-architecture.md.txt": "Current architecture." },
+ },
+ });
+ expect(stderr.text()).toContain("Starting a new scan");
+ expect(stderr.text()).toContain(
+ "Changed inputs: scan instructions, knowledge base",
+ );
+});
+
test.each([
["omitted", undefined],
["empty inline", ""],