OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
fix(scans)!: preserve original knowledge context when resuming (#1556)
mldangelo-oai9613a6a0305a
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.mdindex 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, andcontents 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 safetyidentifier, 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 theirdiff --git a/sdk/typescript/scripts/check-package.mjs b/sdk/typescript/scripts/check-package.mjsindex 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.mjsindex 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.mjsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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", ""],