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

feat(cli): add mock scans with synthetic findings (#783)

Kyle Brown5e788c700d5c
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 1ea8a36b7..b7f135f79 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -299,6 +299,41 @@ Scans are report-only by default. Set `--fail-on-severity high` to exit with
`1` if a completed scan finds high or critical issues. Incomplete scans exit
with `2`, writing available results to stdout and a coverage warning to stderr.
+### Generate mock scan results
+
+Use `--mock` to populate a Standard scan with synthetic test data in seconds,
+without Codex authentication or any LLM calls:
+
+```bash
+codex-security scan /path/to/repository --mock
+codex-security scan /path/to/repository --mock --output-dir /path/outside/repository/mock-results
+```
+
+The SDK equivalent is `await security.run(repository, { mock: true })`.
+Mock mode is off by default. It uses normal target validation, scan registration,
+artifact finalization, reports, and local scan/finding history. Output directories,
+archiving, JSON output, exports, and `--fail-on-severity` work as usual.
+`--dry-run` only validates inputs; `--mock` saves a completed scan.
+
+Each run contains 12 findings across all severity levels: eight stable findings
+recur on subsequent scans of the same repository, and four have new identities
+on every run. Two pairs describe the same root causes with different titles and
+identities, providing inputs for deduplication testing. Mock scans skip automatic
+LLM matching; existing identity-based history indexing still runs. Separate
+comparison or deduplication commands retain their usual model behavior.
+
+Titles, provenance, artifact metadata, and reports identify the results as
+synthetic. Paths and code snippets are fictional and are never written into the
+repository. Completion means fixture generation finished, not that the repository
+was audited. Results enter the selected local state just like other scans; set
+`CODEX_SECURITY_STATE_DIR` to a separate directory when creating disposable data.
+Token usage is zero. `scans rerun` preserves mock mode.
+
+Mock mode supports repository, path, and diff targets in Standard mode. It cannot
+be combined with `--dry-run`, `--patch`, Deep mode, custom validation, or post-scan
+prompts. Scan prompts and knowledge-base inputs do not change the fixtures, and
+mock scans do not offer interactive patching.
+
### Attribute scans to end users
When scanning on behalf of users, pass each user's stable hashed ID:
diff --git a/sdk/typescript/scripts/check-package.mjs b/sdk/typescript/scripts/check-package.mjs
index 41ae672f4..6a810715e 100644
--- a/sdk/typescript/scripts/check-package.mjs
+++ b/sdk/typescript/scripts/check-package.mjs
@@ -187,6 +187,7 @@ const distFiles = new Set(
"linear",
"models",
"multiscan",
+ "mock-scan",
"patch-tui",
"publication",
"publication-events",
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index f966847dd..bfc9b06f1 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -5,6 +5,7 @@ import {
chmod,
lstat,
mkdir,
+ mkdtemp,
readFile,
realpath,
rm,
@@ -48,6 +49,7 @@ import {
shellEnvironmentReference,
} from "./codex-prompt.js";
import {
+ DEFAULT_CODEX_CONFIG,
EXTERNAL_CODEX_PROVIDERS,
isExternalModelProvider,
hasCommandAuth,
@@ -108,6 +110,7 @@ import {
type ScanResultOptions,
} from "./result.js";
import type { SeverityLevel } from "./models.js";
+import { writeMockScanDraft } from "./mock-scan.js";
import { scanActivitiesFromEvent, type ScanActivity } from "./scan-activity.js";
import {
matchCompletedScan,
@@ -138,6 +141,7 @@ import {
prepareCodexSecurityCredentialHome,
preserveCodexSecurityPluginRegistration,
pluginExecutionEnvironment,
+ pluginMetadata,
planOutputArchive,
prepareScanArtifactRestorer,
prepareOutputDir,
@@ -230,6 +234,8 @@ export interface DeepScanOptions {
}
export interface ScanOptions extends DeepScanOptions {
+ /** Save synthetic Standard scan results without calling Codex or a model. */
+ mock?: boolean;
/** Opt into a durable scan -> custom publication -> dedupe workflow. */
workflowId?: string;
auth?: ScanAuthMode;
@@ -758,6 +764,7 @@ export class CodexSecurity {
async #run(repository: string, options: ScanOptions): Promise<ScanResult> {
this.#requireOpen();
+ if (options.mock) return await this.#runMock(repository, options);
const costAbortController = new AbortController();
const signal = AbortSignal.any([
this.#abortController.signal,
@@ -2466,11 +2473,263 @@ export class CodexSecurity {
runtime.effectiveConfig = mergedConfig;
}
+ async #runMock(
+ repository: string,
+ options: ScanOptions,
+ ): Promise<ScanResult> {
+ const signal = AbortSignal.any([
+ this.#abortController.signal,
+ ...(options.signal ? [options.signal] : []),
+ ]);
+ const local = await this.#validateLocalInputs(repository, options, signal);
+ const temporaryRoot = await realpath(tmpdir());
+ requireOutputOutsideRepository(
+ local.protectedRoot,
+ temporaryRoot,
+ "temporary",
+ );
+ const workspace = await mkdtemp(
+ join(temporaryRoot, "codex-security-mock-"),
+ );
+ const workbench = this.#dependencies.runWorkbench ?? runWorkbench;
+ let activeScan:
+ | { id: string; options: WorkbenchCommandOptions }
+ | undefined;
+ let scanDir = "";
+ try {
+ const pluginRoot = await resolvePluginPath(
+ this.config.pluginPath,
+ workspace,
+ signal,
+ );
+ const plugin = await pluginMetadata(pluginRoot);
+ if (
+ options.expectedPluginVersion !== undefined &&
+ options.expectedPluginVersion !== plugin.version
+ ) {
+ throw new CodexSecurityError(
+ "The selected plugin version does not match the expected plugin version.",
+ );
+ }
+ const python = await (
+ this.#dependencies.resolvePluginPython ?? resolvePluginPython
+ )({
+ configuredPath: this.config.pythonPath,
+ environment: this.#dependencies.environment,
+ protectedRoot: local.protectedRoot,
+ signal,
+ });
+ if (options.knowledgeBasePaths?.length) {
+ const knowledgeBase = await prepareKnowledgeBase(
+ options.knowledgeBasePaths,
+ signal,
+ );
+ await knowledgeBase.cleanup();
+ }
+ const outputRoot =
+ local.outputDir === null
+ ? await preparePersistentOutputRoot(
+ local.stateDirectory,
+ "scans",
+ basename(local.repository),
+ )
+ : undefined;
+ let archivedScanDir: string | undefined;
+ scanDir = await prepareOutputDir(
+ local.outputDir ?? undefined,
+ basename(local.repository),
+ outputRoot,
+ (path) => requireOutputOutsideRepository(local.protectedRoot, path),
+ options.archiveExisting,
+ (path) => {
+ archivedScanDir = path;
+ notifyObserver(
+ "onOutputArchived",
+ options.onOutputArchived,
+ options.onObserverError,
+ path,
+ );
+ },
+ );
+ requireModelSafeOutputDir(scanDir);
+ notifyObserver(
+ "onOutputDirReady",
+ options.onOutputDirReady,
+ options.onObserverError,
+ scanDir,
+ );
+ const revision = await repositoryRevision(local.repository, signal);
+ const { model } = scanModelConfiguration({
+ ...DEFAULT_CODEX_CONFIG,
+ ...this.config.codexOverrides,
+ });
+ const workbenchOptions: WorkbenchCommandOptions = {
+ python,
+ pluginRoot,
+ environment: {
+ ...this.#dependencies.environment,
+ CODEX_SECURITY_STATE_DIR: local.stateDirectory,
+ },
+ signal,
+ failureMessage: "Could not save the mock scan",
+ };
+ const registration = await workbench(
+ workbenchOptions,
+ [
+ "register-cli-scan",
+ "--repository",
+ local.repository,
+ "--scan-dir",
+ scanDir,
+ "--registration-json-stdin",
+ ...(options.archiveExisting ? ["--archive-existing"] : []),
+ ...(archivedScanDir === undefined
+ ? []
+ : ["--archived-scan-dir", archivedScanDir]),
+ ...(options.parentScanId === undefined
+ ? []
+ : ["--parent-scan-id", options.parentScanId]),
+ ],
+ JSON.stringify({
+ recipe: {
+ ...scanRecipe(
+ local.repository,
+ local.target,
+ local.mode,
+ revision,
+ plugin.version,
+ { model },
+ options.failureSeverity,
+ options.knowledgeBasePaths,
+ options.maxCostUsd,
+ ),
+ mock: true,
+ },
+ userContext: options.scanPrompt,
+ ...(options.workflowId === undefined
+ ? {}
+ : { workflowId: options.workflowId }),
+ }),
+ );
+ const scanId = registration["scanId"];
+ const targetId = registration["targetId"];
+ if (
+ typeof scanId !== "string" ||
+ typeof targetId !== "string" ||
+ registration["scanDir"] !== scanDir
+ ) {
+ throw new CodexSecurityError(
+ "The workbench returned an invalid mock scan registration.",
+ );
+ }
+ activeScan = { id: scanId, options: workbenchOptions };
+ notifyObserver(
+ "onScanStarted",
+ options.onScanStarted,
+ options.onObserverError,
+ );
+ await writeMockScanDraft(
+ scanDir,
+ scanId,
+ local.target,
+ registration,
+ signal,
+ );
+ const usage = {
+ input_tokens: 0,
+ cached_input_tokens: 0,
+ output_tokens: 0,
+ };
+ const cost = estimateScanCost(model, usage);
+ await workbench(workbenchOptions, [
+ "prepare-scan-completion",
+ "--scan-id",
+ scanId,
+ ]);
+ const completion = await workbench(workbenchOptions, [
+ "complete-scan",
+ "--scan-id",
+ scanId,
+ ...(cost === null ? [] : ["--cost-json", JSON.stringify(cost)]),
+ ]);
+ activeScan = undefined;
+ const completedScan = completion["scan"];
+ if (isRecord(completedScan) && Array.isArray(completedScan["warnings"])) {
+ for (const warning of completedScan["warnings"]) {
+ if (typeof warning === "string")
+ notifyObserver(
+ "onWarning",
+ options.onWarning,
+ options.onObserverError,
+ warning,
+ Array.isArray(completion["targetWarnings"]) &&
+ completion["targetWarnings"].includes(warning)
+ ? { kind: "target_changed" }
+ : undefined,
+ );
+ }
+ }
+ const result = await collectResult(
+ {
+ status: "completed",
+ model,
+ usage,
+ mock: true,
+ finalResponse:
+ "Synthetic mock scan; no security analysis was performed.",
+ },
+ "",
+ scanDir,
+ pluginRoot,
+ {
+ repository: local.repository,
+ repositoryRevision: revision,
+ target: local.target,
+ mode: local.mode,
+ pluginVersion: plugin.version,
+ },
+ signal,
+ true,
+ );
+ // Stable fixture identities are indexed by complete-scan without model matching.
+ result.repositoryFindings = (await listRepositoryFindings(
+ (args) => workbench(workbenchOptions, args),
+ targetId,
+ )) as RepositoryFinding[] | undefined;
+ return result;
+ } catch (error) {
+ if (activeScan !== undefined) {
+ await workbench({ ...activeScan.options, signal: undefined }, [
+ "fail-scan",
+ "--scan-id",
+ activeScan.id,
+ "--message",
+ safeErrorMessage(error).slice(0, 2400),
+ ]).catch(() => undefined);
+ }
+ if (this.#closed) this.#requireOpen();
+ throwIfAborted(signal, scanDir);
+ throw error;
+ } finally {
+ await cleanupSdkDirectory(workspace);
+ }
+ }
+
async #validateLocalInputs(
repository: string,
options: ScanOptions,
signal?: AbortSignal,
): Promise<LocalScanInputs> {
+ if (
+ options.mock &&
+ (options.mode === "deep" ||
+ options.validationPrompt !== undefined ||
+ options.postScanPrompt !== undefined)
+ ) {
+ throw new CodexSecurityError(
+ "Mock scans support Standard mode without custom validation or post-scan prompts; those workflows require model calls.",
+ );
+ }
deepScanOptions(options);
const identifier = options.safetyIdentifier;
if (
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 8a633f6ce..d803ed425 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -978,6 +978,7 @@ export function resolveCliPath(directory: string, value: string): string {
}
interface ScanArguments extends DeepScanOptions {
+ mock?: boolean;
workflowId?: string;
auth?: ScanAuthMode;
safetyIdentifier?: string;
@@ -2927,6 +2928,12 @@ export async function main(
.boolean()
.default(false)
.describe("Validate local scan inputs without starting a scan."),
+ mock: z
+ .boolean()
+ .default(false)
+ .describe(
+ "Save synthetic Standard scan findings without calling an LLM.",
+ ),
})
.refine(
(options) =>
@@ -2966,6 +2973,12 @@ export async function main(
.refine((options) => !options.patch || !options.dryRun, {
message: "--patch cannot be combined with --dry-run.",
})
+ .refine(
+ (options) => !options.mock || (!options.dryRun && !options.patch),
+ {
+ message: "--mock cannot be combined with --dry-run or --patch.",
+ },
+ )
.refine(
(options) =>
options.mode === "deep" ||
@@ -3040,6 +3053,7 @@ export async function main(
maxCostUsd: options.maxCost,
headless: options.headless,
dryRun: options.dryRun,
+ mock: options.mock,
},
errorOutput,
dependencies,
@@ -4662,6 +4676,7 @@ function scanArgumentsFromRecipe(
maxCostUsd,
dryRun: false,
parentScanId,
+ ...(recipe["mock"] === true ? { mock: true } : {}),
expectedPluginVersion:
typeof recipe["pluginVersion"] === "string"
? recipe["pluginVersion"]
@@ -6465,7 +6480,7 @@ async function executeScan(
scanModelConfiguration(effectiveConfiguration));
const provider = scanModelProvider(effectiveConfiguration);
const auth =
- !arguments_.dryRun && interactive
+ !arguments_.dryRun && !arguments_.mock && interactive
? await chooseInteractiveAuthentication(
{
auth: arguments_.auth,
@@ -6487,11 +6502,9 @@ async function executeScan(
)?.[provider],
};
}
- selectedAuthentication = scanAuthentication(
- dependencies.environment,
- auth,
- provider,
- );
+ selectedAuthentication = arguments_.mock
+ ? null
+ : scanAuthentication(dependencies.environment, auth, provider);
diagnostic("scan.configuration", {
cli_version: VERSION,
bundled_plugin_version: BUNDLED_PLUGIN_VERSION,
@@ -6509,6 +6522,7 @@ async function executeScan(
: "repository",
requested_auth: auth ?? "auto",
dry_run: arguments_.dryRun,
+ mock: arguments_.mock,
profile:
typeof selectedProfileName === "string"
? selectedProfileName
@@ -6583,7 +6597,13 @@ async function executeScan(
}
}
security = dependencies.createSecurity(config);
+ if (arguments_.mock) {
+ errorOutput.write(
+ "codex-security: Mock scan: generating synthetic findings; no security analysis or LLM calls.\n",
+ );
+ }
const options: ScanOptions = {
+ ...(arguments_.mock ? { mock: true } : {}),
...(arguments_.workflowId === undefined
? {}
: { workflowId: arguments_.workflowId }),
@@ -7000,6 +7020,7 @@ async function executeScan(
: undefined;
let patchSelection: PatchSelection | null = null;
if (
+ !arguments_.mock &&
actionableFindings.length > 0 &&
arguments_.patchSeverity === undefined &&
progress?.interactive === true &&
diff --git a/sdk/typescript/src/mock-scan.ts b/sdk/typescript/src/mock-scan.ts
new file mode 100644
index 000000000..62bddf48d
--- /dev/null
+++ b/sdk/typescript/src/mock-scan.ts
@@ -0,0 +1,269 @@
+import { writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import type { JsonObject } from "./config.js";
+import type { Finding, SeverityLevel } from "./models.js";
+import type { NormalizedTarget } from "./targets.js";
+
+type DraftFinding = Omit<
+ Finding,
+ "findingId" | "occurrenceId" | "fingerprints"
+>;
+
+interface MockFinding {
+ id: string;
+ title: string;
+ severity: SeverityLevel;
+ cwe: string;
+ summary: string;
+ code: string;
+ remediation: string;
+}
+
+// Entirely synthetic examples; the paths and snippets do not come from the target.
+const EXAMPLES: readonly MockFinding[] = [
+ {
+ id: "command-injection",
+ title: "Export filename reaches a shell command",
+ severity: "critical",
+ cwe: "CWE-78",
+ summary:
+ "The example export route interpolates an untrusted filename into a shell command, allowing shell metacharacters to execute another command.",
+ code: "exec(`convert ${request.body.filename} output.pdf`);",
+ remediation:
+ "Pass the filename as a separate argument to a process API that does not invoke a shell.",
+ },
+ {
+ id: "path-traversal",
+ title: "Archive entry escapes the extraction directory",
+ severity: "high",
+ cwe: "CWE-22",
+ summary:
+ "The example archive extractor writes a supplied entry name without checking containment, allowing a parent-directory entry to overwrite a file outside the extraction directory.",
+ code: "await writeFile(join(outputDirectory, entry.name), entry.contents);",
+ remediation:
+ "Resolve each entry destination and reject paths outside the extraction directory before writing.",
+ },
+ {
+ id: "missing-authorization",
+ title: "Document download omits the ownership check",
+ severity: "high",
+ cwe: "CWE-862",
+ summary:
+ "The example download handler accepts a document ID from any signed-in account and returns the document without checking that the account owns it.",
+ code: "response.json(await documents.findById(request.params.id));",
+ remediation:
+ "Restrict document lookup to records the authenticated account is authorized to read.",
+ },
+ {
+ id: "stored-xss",
+ title: "Comment preview renders stored HTML",
+ severity: "medium",
+ cwe: "CWE-79",
+ summary:
+ "The example preview inserts a stored comment directly into HTML, allowing a comment author to execute script in another viewer's browser.",
+ code: "preview.innerHTML = comment.body;",
+ remediation:
+ "Render comments as text or sanitize intentionally supported HTML before insertion.",
+ },
+ {
+ id: "verbose-errors",
+ title: "Error response exposes an internal stack trace",
+ severity: "low",
+ cwe: "CWE-209",
+ summary:
+ "The example error handler returns a stack trace to a remote caller, revealing internal module names and filesystem layout.",
+ code: "response.status(500).send(error.stack);",
+ remediation:
+ "Return a generic error identifier and retain diagnostic details in internal logs.",
+ },
+ {
+ id: "version-disclosure",
+ title: "Response header advertises the framework version",
+ severity: "informational",
+ cwe: "CWE-200",
+ summary:
+ "The example response header exposes the precise framework version. This helps fingerprint the service but does not establish an exploitable vulnerability.",
+ code: 'response.setHeader("X-Example-Version", frameworkVersion);',
+ remediation: "Omit the framework version from public response headers.",
+ },
+ {
+ id: "sql-injection",
+ title: "Search term is concatenated into a SQL query",
+ severity: "high",
+ cwe: "CWE-89",
+ summary:
+ "The example search handler concatenates request text into SQL, allowing a caller to change the query and read records beyond the intended search.",
+ code: "db.query(`SELECT * FROM items WHERE name = '${request.query.name}'`);",
+ remediation: "Use a parameterized query for the search term.",
+ },
+ {
+ id: "ssrf",
+ title: "Image proxy fetches arbitrary destinations",
+ severity: "medium",
+ cwe: "CWE-918",
+ summary:
+ "The example image proxy fetches a caller-supplied URL without restricting its destination, allowing requests to internal services reachable by the proxy.",
+ code: "return await fetch(request.query.imageUrl);",
+ remediation:
+ "Restrict fetch destinations to the intended image hosts and enforce that policy across redirects.",
+ },
+ {
+ id: "open-redirect",
+ title: "Sign-in callback accepts an external redirect",
+ severity: "medium",
+ cwe: "CWE-601",
+ summary:
+ "The example sign-in callback redirects to a supplied URL without checking its origin, allowing an attacker to send users from the sign-in flow to an unrelated site.",
+ code: "response.redirect(request.query.returnTo);",
+ remediation:
+ "Accept only application-relative return paths or explicitly permitted origins.",
+ },
+ {
+ id: "cookie-flags",
+ title: "Session cookie omits HttpOnly",
+ severity: "low",
+ cwe: "CWE-1004",
+ summary:
+ "The example session cookie is accessible to browser scripts because HttpOnly is absent, increasing the impact of a separate script-injection vulnerability.",
+ code: 'response.cookie("session", sessionId, { secure: true });',
+ remediation: "Set HttpOnly on the session cookie.",
+ },
+];
+
+function mockFindings(scanId: string): DraftFinding[] {
+ const findings = EXAMPLES.map((example, index): DraftFinding => {
+ const unique = index >= 6;
+ const path = `mock/${example.id}${unique ? `-${scanId}` : ""}.ts`;
+ return {
+ ruleId: `mock.${example.id}`,
+ identity: { anchor: example.id, ...(unique ? { instance: scanId } : {}) },
+ title: `[Mock] ${example.title}`,
+ summary: `Synthetic test finding. ${example.summary}`,
+ severity: { level: example.severity },
+ confidence: {
+ level: "high",
+ rationale:
+ "Deterministic fixture; not a conclusion about the scanned repository.",
+ },
+ taxonomy: { category: example.id, cwe: [example.cwe] },
+ locations: [{ path, startLine: 10, endLine: 10, role: "sink" }],
+ codeEvidence: [
+ {
+ id: "example-sink",
+ label: "Synthetic vulnerable operation",
+ path,
+ startLine: 10,
+ language: "typescript",
+ role: "sink",
+ code: example.code,
+ explanation:
+ "Illustrative fixture code; this file is not read from or written to the repository.",
+ },
+ ],
+ rootCause: { summary: example.summary, evidenceRefs: ["example-sink"] },
+ remediation: example.remediation,
+ validation: {
+ status: "mock",
+ method: "synthetic",
+ summary: "Fixture only; no code was analyzed or executed.",
+ },
+ attackPath: {
+ summary: example.summary,
+ assumptions: [
+ "The fictional example exposes this operation to untrusted input.",
+ ],
+ evidenceRefs: ["example-sink"],
+ },
+ remediationTests: [
+ `In the example application, verify the fix: ${example.remediation}`,
+ ],
+ preventiveControls: [example.remediation],
+ provenance: { source: "mock" },
+ extensions: {
+ mock: true,
+ mockGroup: example.id,
+ mockRecurrence: unique ? "unique" : "shared",
+ },
+ };
+ });
+ // Alternate reports have distinct identities but describe the same root causes.
+ for (const [index, title] of [
+ [0, "Shell metacharacters in the export name execute commands"],
+ [1, "Parent-directory archive names overwrite files outside extraction"],
+ ] as const) {
+ const original = findings[index]!;
+ findings.push({
+ ...structuredClone(original),
+ identity: { anchor: `${EXAMPLES[index]!.id}-alternate-report` },
+ title: `[Mock] ${title}`,
+ });
+ }
+ return findings;
+}
+
+export async function writeMockScanDraft(
+ scanDir: string,
+ scanId: string,
+ target: NormalizedTarget,
+ registration: JsonObject,
+ signal: AbortSignal,
+): Promise<void> {
+ const contract = registration["contract"] as {
+ target: { allowedKinds: string[] };
+ diffTarget?: {
+ kind: string;
+ baseRevision: string;
+ headRevision: string;
+ } | null;
+ };
+ const diff = contract.diffTarget;
+ const snapshotDigest =
+ diff && diff.kind !== "working_tree"
+ ? `codex-security-snapshot/v1:sha256:${createHash("sha256").update(["codex-security-diff/v1", diff.kind, diff.baseRevision, diff.headRevision].join("\0")).digest("hex")}`
+ : undefined;
+ const description =
+ "Synthetic mock scan for testing. No LLM calls or security analysis were performed. Locations and code snippets describe fictional examples.";
+ const documents = {
+ "scan-manifest.json": {
+ scan: {
+ target: {
+ kind: contract.target.allowedKinds[0],
+ ...(snapshotDigest === undefined ? {} : { snapshotDigest }),
+ },
+ scope: {
+ summary: description,
+ runtimeStatus: "mock",
+ limitations: [description],
+ },
+ extensions: { mock: true },
+ },
+ },
+ "findings.json": { findings: mockFindings(scanId) },
+ "coverage.json": {
+ completeness: "complete",
+ inventoryStrategy:
+ target.kind === "paths"
+ ? "scoped_path"
+ : target.kind === "repository"
+ ? "repository"
+ : "diff",
+ surfaces: EXAMPLES.map((example) => ({
+ id: `mock-${example.id}`,
+ label: `[Mock] ${example.title}`,
+ disposition: "reported",
+ receiptRefs: [],
+ notes: description,
+ })),
+ explicitExclusions: [],
+ deferred: [],
+ },
+ };
+ for (const [name, document] of Object.entries(documents)) {
+ await writeFile(
+ join(scanDir, name),
+ `${JSON.stringify(document, null, 2)}\n`,
+ { flag: "wx", signal },
+ );
+ }
+}
diff --git a/sdk/typescript/tests-ts/mock-scan.test.ts b/sdk/typescript/tests-ts/mock-scan.test.ts
new file mode 100644
index 000000000..711ae63fd
--- /dev/null
+++ b/sdk/typescript/tests-ts/mock-scan.test.ts
@@ -0,0 +1,336 @@
+import {
+ mkdir,
+ mkdtemp,
+ readFile,
+ readdir,
+ realpath,
+ rm,
+ writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test } from "bun:test";
+import { main } from "../src/cli.js";
+import { DiffTarget } from "../src/targets.js";
+import { runWorkbench } from "../src/runtime.js";
+import { loadContract } from "../src/contract.js";
+import { ScanInterruptedError } from "../src/errors.js";
+import { TestClient } from "./support/api-client.js";
+import { capture, dependencies, fakeResult } from "./cli-fixtures.js";
+import { PLUGIN_ROOT } from "./plugin-root.js";
+import { runCommand } from "./support/shell.js";
+
+const roots: string[] = [];
+afterEach(async () => {
+ await Promise.all(
+ roots.splice(0).map((root) => rm(root, { recursive: true, force: true })),
+ );
+});
+
+async function fixture() {
+ const root = await mkdtemp(join(await realpath(tmpdir()), "mock-scan-test-"));
+ roots.push(root);
+ const repository = join(root, "repository");
+ await mkdir(repository);
+ await writeFile(
+ join(repository, "example.ts"),
+ "export const example = 1;\n",
+ );
+ const environment = {
+ PATH: process.env["PATH"],
+ SystemRoot: process.env["SystemRoot"],
+ CODEX_HOME: join(root, "codex-home"),
+ CODEX_SECURITY_STATE_DIR: join(root, "state"),
+ };
+ const python = Bun.which("python3") ?? Bun.which("python");
+ expect(python).not.toBeNull();
+ const client = new TestClient(
+ { pythonPath: python! },
+ {
+ environment,
+ runWorkbench,
+ prepareRuntime: async () => {
+ throw new Error("Mock scan initialized Codex");
+ },
+ matchFindings: async () => {
+ throw new Error("Mock scan called model matching");
+ },
+ },
+ );
+ return { root, repository, client, environment, python: python! };
+}
+
+test("mock scans seal real artifacts and index shared and unique findings without Codex", async () => {
+ const { repository, client, environment, python } = await fixture();
+ const callbacks: string[] = [];
+ try {
+ const first = await client.run(repository, {
+ mock: true,
+ auth: "api-key",
+ maxCostUsd: 0.01,
+ onAuthentication: () => callbacks.push("authentication"),
+ onScanStarted: () => callbacks.push("started"),
+ });
+ const second = await client.run(repository, { mock: true });
+ expect(callbacks).toEqual(["started"]);
+ expect(first.findings.findings).toHaveLength(12);
+ expect(first.coverage.completeness).toBe("complete");
+ expect(first.manifest.scan.status).toBe("completed");
+ expect(first.manifest.scan.sealedAt).toBeTruthy();
+ expect(first.turnResult["mock"]).toBe(true);
+ expect(first.threadId).toBe("");
+ expect(first.cost?.estimatedUsd).toBe(0);
+ expect(first.cost?.inputTokens).toBe(0);
+ expect(first.cost?.outputTokens).toBe(0);
+ expect(await readFile(first.reportPath, "utf8")).toContain(
+ "Synthetic mock scan",
+ );
+ expect(
+ await loadContract(first.scanDir, { pluginRoot: PLUGIN_ROOT }),
+ ).toEqual({
+ manifest: first.manifest,
+ findings: first.findings,
+ coverage: first.coverage,
+ });
+ const previousIds = new Set(
+ first.findings.findings.map((finding) => finding.findingId),
+ );
+ const recurring = second.findings.findings.filter((finding) =>
+ previousIds.has(finding.findingId),
+ );
+ expect(recurring).toHaveLength(8);
+ expect(
+ new Set([
+ ...previousIds,
+ ...second.findings.findings.map((finding) => finding.findingId),
+ ]).size,
+ ).toBe(16);
+ expect(
+ new Set(first.findings.findings.map((finding) => finding.severity.level))
+ .size,
+ ).toBe(5);
+ for (const id of ["command-injection", "path-traversal"]) {
+ const pair = first.findings.findings.filter(
+ (finding) => finding.extensions?.["mockGroup"] === id,
+ );
+ expect(pair).toHaveLength(2);
+ expect(pair[0]!.findingId).not.toBe(pair[1]!.findingId);
+ expect(pair[0]!.locations).toEqual(pair[1]!.locations);
+ }
+ expect(second.repositoryFindings).toHaveLength(16);
+ expect(
+ second.repositoryFindings?.filter(
+ (finding) => finding.knownScanIds?.length === 2,
+ ),
+ ).toHaveLength(8);
+ expect(await readdir(repository)).toEqual(["example.ts"]);
+ expect(await readFile(join(repository, "example.ts"), "utf8")).toBe(
+ "export const example = 1;\n",
+ );
+ const history = await runWorkbench(
+ { python, pluginRoot: PLUGIN_ROOT, environment },
+ ["list-scans", "--repository", repository],
+ );
+ expect(history["scans"]).toHaveLength(2);
+ const recipe = await runWorkbench(
+ { python, pluginRoot: PLUGIN_ROOT, environment },
+ ["get-scan-recipe", "--scan-id", first.manifest.scan.id],
+ );
+ let rerunMock: boolean | undefined;
+ expect(
+ await main(
+ ["scans", "rerun", first.manifest.scan.id],
+ capture().stream,
+ capture().stream,
+ dependencies({
+ currentDirectory: repository,
+ onWorkbench: async () => recipe,
+ onTurn: (_repository, options) => {
+ rerunMock = (options as { mock?: boolean }).mock;
+ },
+ }),
+ ),
+ ).toBe(0);
+ expect(rerunMock).toBe(true);
+ } finally {
+ await client.close();
+ }
+});
+
+test("mock scans preserve output protection and archive existing completed results", async () => {
+ const { root, repository, client } = await fixture();
+ try {
+ await expect(
+ client.run(repository, {
+ mock: true,
+ outputDir: join(repository, "results"),
+ }),
+ ).rejects.toThrow();
+ const outputDir = join(root, "results");
+ const first = await client.run(repository, {
+ mock: true,
+ outputDir,
+ target: ["example.ts"],
+ });
+ const original = await readFile(first.manifestPath, "utf8");
+ await expect(
+ client.run(repository, { mock: true, outputDir }),
+ ).rejects.toThrow();
+ expect(await readFile(first.manifestPath, "utf8")).toBe(original);
+ let archive = "";
+ const second = await client.run(repository, {
+ mock: true,
+ outputDir,
+ archiveExisting: true,
+ onOutputArchived: (path) => {
+ archive = path;
+ },
+ });
+ expect(await readFile(join(archive, "scan-manifest.json"), "utf8")).toBe(
+ original,
+ );
+ expect(second.manifest.scan.id).not.toBe(first.manifest.scan.id);
+ expect(first.coverage.mode).toBe("scoped_path");
+ expect(first.coverage.includePaths).toEqual(["example.ts"]);
+ } finally {
+ await client.close();
+ }
+});
+
+test("mock scan CLI forwards the flag and never offers authentication or patching", async () => {
+ const stdout = capture();
+ const stderr = capture(true);
+ let mock: boolean | undefined;
+ const code = await main(
+ ["scan", ".", "--mock", "--fail-on-severity", "high", "--auth", "api-key"],
+ stdout.stream,
+ stderr.stream,
+ {
+ ...dependencies({
+ result: fakeResult(["high"]),
+ onTurn: (_repository, options) => {
+ mock = (options as { mock?: boolean }).mock;
+ },
+ }),
+ confirmPatchReview: async () => {
+ throw new Error("Unexpected patch prompt");
+ },
+ },
+ );
+ expect(code).toBe(1);
+ expect(mock).toBe(true);
+ expect(stderr.text()).toContain("Mock scan");
+});
+
+test("mock scans bind clean Git, committed diff, and working-tree snapshots", async () => {
+ const { root, repository, client } = await fixture();
+ const git = async (...args: string[]) => {
+ const result = await runCommand(
+ "git",
+ [
+ "-C",
+ repository,
+ "-c",
+ `core.hooksPath=${join(root, "hooks")}`,
+ "-c",
+ "commit.gpgsign=false",
+ "-c",
+ "user.name=Example",
+ "-c",
+ ...args,
+ ],
+ { timeout: 10000 },
+ );
+ expect(result.status).toBe(0);
+ };
+ try {
+ await git("init");
+ await git("add", ".");
+ await git("commit", "-m", "Initial synthetic fixture");
+ const clean = await client.run(repository, { mock: true });
+ expect(clean.manifest.scan.target.kind).toBe("git_revision");
+ await writeFile(
+ join(repository, "example.ts"),
+ "export const example = 2;\n",
+ );
+ await git("commit", "-am", "Update synthetic fixture");
+ const diff = await client.run(repository, {
+ mock: true,
+ target: DiffTarget.refs({ base: "HEAD~1" }),
+ });
+ expect(diff.manifest.scan.target.kind).toBe("git_diff");
+ expect(diff.coverage.completeness).toBe("complete");
+ expect(diff.coverage.mode).toBe("branch_diff");
+ await writeFile(
+ join(repository, "example.ts"),
+ "export const example = 3;\n",
+ );
+ const workingTree = await client.run(repository, {
+ mock: true,
+ target: DiffTarget.workingTree({}),
+ });
+ expect(workingTree.manifest.scan.target.kind).toBe("git_diff");
+ expect(workingTree.coverage.completeness).toBe("complete");
+ expect(workingTree.coverage.mode).toBe("working_tree");
+ } finally {
+ await client.close();
+ }
+});
+
+test("aborting mock generation leaves a terminal scan record", async () => {
+ const { client, repository, environment, python } = await fixture();
+ const controller = new AbortController();
+ try {
+ await expect(
+ client.run(repository, {
+ mock: true,
+ signal: controller.signal,
+ onScanStarted: () => controller.abort(),
+ }),
+ ).rejects.toThrow(ScanInterruptedError);
+ const history = await runWorkbench(
+ { python, pluginRoot: PLUGIN_ROOT, environment },
+ ["list-scans", "--repository", repository],
+ );
+ expect(history["scans"]).toMatchObject([
+ { progress: { status: "failed" } },
+ ]);
+ } finally {
+ await client.close();
+ }
+});
+
+test.each(["--dry-run", "--patch"])(
+ "mock scan CLI rejects %s",
+ async (flag) => {
+ const stderr = capture();
+ const code = await main(
+ ["scan", "--mock", flag],
+ capture().stream,
+ stderr.stream,
+ dependencies({
+ onRun: () => {
+ throw new Error("Unexpected scan");
+ },
+ }),
+ );
+ expect(code).toBe(2);
+ expect(stderr.text()).toContain("--mock cannot be combined");
+ },
+);
+
+test.each([
+ { mode: "deep" as const },
+ { validationPrompt: "Validate" },
+ { postScanPrompt: "Follow up" },
+])("mock scans reject model-dependent workflows: %j", async (options) => {
+ const { client, repository } = await fixture();
+ try {
+ await expect(
+ client.run(repository, { mock: true, ...options }),
+ ).rejects.toThrow("require model calls");
+ } finally {
+ await client.close();
+ }
+});