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
feat: share scan settings across the CLI and SDK (#742)
mldangelo-oai408ce4465eff
diff --git a/README.md b/README.mdindex ca63cad35..2d1306f29 100644--- a/README.md+++ b/README.md@@ -110,3 +110,6 @@ codex-security scan . --provider fireworks --model accounts/fireworks/models/qwe## Documentation**👉👉 See the [Codex Security documentation](https://learn.chatgpt.com/docs/security/cli)** for full documentation.++See [project configuration](docs/project-configuration.md) for reusable YAML/JSON+settings, CLI overrides, and editor schema support.diff --git a/docs/examples/codex-security.json b/docs/examples/codex-security.jsonnew file mode 100644index 000000000..84eda53b6--- /dev/null+++ b/docs/examples/codex-security.json@@ -0,0 +1,12 @@+{+ "$schema": "./node_modules/@openai/codex-security/schemas/project-config.schema.json",+ "scan": {+ "mode": "standard",+ "scope": { "paths": ["sdk/typescript/src"] }+ },+ "codex": {+ "model": "gpt-5.6-sol",+ "model_reasoning_effort": "xhigh"+ },+ "policy": { "fail_on_severity": "high" }+}diff --git a/docs/examples/codex-security.yaml b/docs/examples/codex-security.yamlnew file mode 100644index 000000000..e7b888818--- /dev/null+++ b/docs/examples/codex-security.yaml@@ -0,0 +1,11 @@+# yaml-language-server: $schema=./node_modules/@openai/codex-security/schemas/project-config.schema.json+# Schema path assumes this file is copied to the root of your project.+scan:+ mode: standard+ scope:+ paths: [sdk/typescript/src]+codex:+ model: gpt-5.6-sol+ model_reasoning_effort: xhigh+policy:+ fail_on_severity: highdiff --git a/docs/project-configuration.md b/docs/project-configuration.mdnew file mode 100644index 000000000..6433cfdda--- /dev/null+++ b/docs/project-configuration.md@@ -0,0 +1,350 @@+# Project configuration++Use `scan [repository] -c FILE` or `scan [repository] --config FILE` to load one+YAML or JSON file:++```sh+codex-security scan . -c codex-security.yaml --dry-run --json+codex-security scan . -c codex-security.json --model gpt-5.6-terra+```++The supported extensions are `.yaml`, `.yml`, and `.json`. `scan`, `bulk-scan`,+`scan-components`, and `info` accept `-c` / `--config`. An operator can set+`CODEX_SECURITY_PROJECT_CONFIG` instead; an explicit `-c` takes precedence. With+neither, no file is loaded, even if `codex-security.yaml` exists. SDK `run()` calls+and saved reruns do not read this environment variable or discover project files.+The repository comes from the command's target selection, not the config file.++**Treat the selected file as trusted operator configuration, with the same+authority as CLI options and SDK `codexOverrides`.** Native Codex settings can+start configured MCP server processes and select model-service destinations. Do not select a+file controlled by an untrusted repository or pull request. In CI, keep the+scanner configuration in an operator-controlled location outside the checkout+being assessed. Explicit selection does not make a file safe to trust.++Create a starter and inspect its settings without a repository or runtime:++```sh+codex-security init+codex-security info -c codex-security.yaml --json+```++`init [file]` defaults to `codex-security.yaml`, refuses to overwrite an existing+file, and accepts `.yaml`, `.yml`, or `.json`. YAML starters show current defaults+as comments so future releases can still update defaults you have not overridden.+The editor hint is relative to the chosen file and expects the package to be+installed in the invocation directory's `node_modules`.++For a project with a `src` directory:++```yaml+scan:+ scope:+ paths: [src]+ knowledge_base: [SECURITY.md, docs/architecture.md]+codex:+ model: gpt-5.6-sol+ model_reasoning_effort: xhigh+policy:+ fail_on_severity: high+```++All settings are optional; `{}` uses the existing defaults. No `version` field+is needed. Unknown wrapper keys and invalid types are errors. Values are literal:+the loader does not evaluate JavaScript, interpolate environment values, include remote files,+or merge multiple files. Wrapper `null` values do not reset settings. Project-file+keys use `snake_case`, matching native Codex configuration. Keys inside `codex`+keep their native spelling; names and values are not converted.+YAML anchors are supported; the parser retains its guard against excessive nested+alias expansion.++The [YAML example](examples/codex-security.yaml) and equivalent+[JSON example](examples/codex-security.json) select this repository's TypeScript+source. After [setting up the source checkout](../sdk/typescript/TESTING.md), try:++```sh+cd sdk/typescript+pnpm run build:plugin+pnpm run build+cd ../..+node sdk/typescript/bin/codex-security.mjs scan . -c docs/examples/codex-security.yaml --dry-run --json+```++## Settings++| Field | Meaning | Default |+| ------------------------------ | ---------------------------------------------------------------------------- | ---------------------------------- |+| `auth` | Credential source: `auto`, `chatgpt`, or `api-key`; never a credential value | `auto` |+| `scan.mode` | `standard` or `deep` | `standard` |+| `scan.scope` | Exactly one of `paths: [src]`, `diff: {base: HEAD}`, or `working_tree: {}` | Whole repository |+| `scan.knowledge_base` | Context files or directories | Empty list |+| `scan.instructions_file` | Additional scan instructions | Unset |+| `scan.validation_file` | Custom validation instructions; incompatible with active deep mode | Built-in validation |+| `scan.deep` | Deep discovery settings shown below | Existing deep defaults |+| `codex` | Native Codex settings and profiles | Existing isolated configuration |+| `limits.max_cost_usd_per_scan` | Estimated USD limit for one scan attempt | No limit |+| `policy.fail_on_severity` | Exit threshold: `critical`, `high`, `medium`, or `low` | Report-only |+| `output.directory` | Artifact directory outside the scanned Git worktree | Existing private artifact location |++The file configures scan settings. Patching, PR creation, publication, post-scan+actions, and machine-specific plugin or Python selection remain explicit CLI/SDK+inputs.++## SDK and CLI contract++The SDK's `ScanSettings` type is shared by `ScanOptions`, CLI resolution, and+project-file resolution. Project files and typed `ProjectConfigInput` objects+use `snake_case`; SDK options keep `camelCase`, and CLI flags keep `kebab-case`.+The resolver maps file keys to the existing SDK options:++| Project file | SDK option | CLI flag |+| ----------------------------------------- | ------------------------------------- | ------------------------------- |+| `auth` | `auth` | `--auth` |+| `scan.mode` | `mode` | `--mode` |+| `scan.scope.paths` | `target: ["src"]` | `--path` |+| `scan.scope.diff` | `target: DiffTarget.refs(...)` | `--diff`, `--head` |+| `scan.scope.working_tree` | `target: DiffTarget.workingTree(...)` | `--working-tree`, `--base` |+| `scan.knowledge_base` | `knowledgeBasePaths` | `--knowledge-base` |+| `scan.instructions_file` | `scanPromptFile` | `--scan-prompt-file` |+| `scan.validation_file` | `validationPromptFile` | `--validation-prompt-file` |+| `scan.deep.workers` | `workers` | `--workers` |+| `scan.deep.subagents_per_worker` | `subagents` | `--subagents` |+| `scan.deep.stop_after_no_new` | `stopAfterNoNew` | `--stop-after-no-new` |+| `scan.deep.stop_after_consecutive_errors` | `stopAfterConsecutiveErrors` | No flag |+| `scan.deep.max_discovery_runs` | `maxDiscoveryRuns` | `--max-discovery-runs` |+| `scan.deep.max_time_hours` | `maxTimeHours` | `--max-time-hours` |+| `limits.max_cost_usd_per_scan` | `maxCostUsd` | `--max-cost` |+| `policy.fail_on_severity` | `failureSeverity` | `--fail-on-severity` |+| `output.directory` | `outputDir` | `--output-dir` |+| `codex` | Constructor `codexOverrides` | `--codex`, model/provider flags |++Use an explicit file with `loadProjectConfig()`:++```ts+import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";++const { config, options } = await loadProjectConfig("codex-security.yaml");+await using security = new CodexSecurity(config);+const result = await security.run(repository, options);+if (+ options.failureSeverity !== undefined &&+ result.hasFindingsAtOrAbove(options.failureSeverity)+) {+ process.exitCode = 1;+}+```++For configuration already in memory, pass the same structured object to+`resolveProjectConfig()`:++```ts+import {+ resolveProjectConfig,+ type ProjectConfigInput,+} from "@openai/codex-security";++const input = {+ scan: { mode: "deep", scope: { paths: ["src"] } },+ limits: { max_cost_usd_per_scan: 5 },+} satisfies ProjectConfigInput;+const { config, options } = resolveProjectConfig(input, process.cwd());+```++Both return constructor `config`, scan `options`, and an immutable `sources` map;+the file loader also returns+`projectConfig` path and source metadata. The optional directory argument defaults+to the current directory. It locates a selected file or anchors an in-memory+object's context, prompt, and output paths. Files anchor those paths to their own+directory. Neither helper reads prompt contents or prepares a runtime.+Resolved context, prompt, and output paths have the SDK's `AbsolutePath` type;+scope paths remain relative to the selected repository.++Use `security.preflight(repository, options)` for the same local checks as CLI+`--dry-run`, including active-mode compatibility and remaining legacy deep+defaults. To override a resolved value or attach a callback, pass+`{ ...options, maxCostUsd: 10, onProgress }` to `run()`.++SDK callers can use inline `scanPrompt`, `validationPrompt`, and `postScanPrompt`,+or the corresponding `*PromptFile` options. Inline text wins without reading the+matching file. Direct SDK file paths resolve from the current directory and use+the CLI's existing file protections. Post-scan instructions remain explicit+SDK/CLI options and are not part of project files.++`failureSeverity` records the policy in the scan recipe. The SDK does not throw or+set process status when the threshold is met; call `hasFindingsAtOrAbove()` and+choose the caller's response. The method uses the same ordering as the CLI and+does not filter findings. The CLI/file contract keeps its four reportable levels;+existing SDK calls also accept `informational`. An unknown threshold throws,+including when the result has no findings.++## Overrides and paths++Settings apply in this order: built-in defaults, applicable legacy deep settings,+the project file, then explicitly supplied CLI values. Schema defaults are editor+hints; parsing does not insert them. Lists are replaced, not concatenated.++| Path | Relative to |+| ------------------------------------------------------- | ------------------------------ |+| Repository positional argument | Invocation directory |+| File `scan.scope.paths` | Selected repository |+| File context, instruction, validation, and output paths | Configuration file's directory |+| CLI context, prompt, and output paths | Invocation directory |+| Native values under `codex` | Existing native Codex rules |++Scope paths follow `scan --path`: the same config can select `src` in each target+repository. Context, instruction, validation, and output paths belong to the config+file and therefore stay anchored to its directory when the invocation moves.++For example, `--knowledge-base context.md` replaces the file's entire context list+and resolves from the invocation directory. Existing regular-file, protected-path,+credential, and outside-worktree output checks still apply.++A CLI scope selector replaces the file's scope variant: `--diff HEAD` discards+configured paths, and `--path src` discards a configured diff. `--head` can refine a+file diff; `--base` can refine a file working-tree scope. Contradictory explicit+selectors fail. `--no-working-tree` disables a configured working-tree scope but+does not clear a path or committed-diff scope.++There is no general CLI reset for configured context, policy, cost limit, or scope.+Edit the file, select another file, or omit `-c` and unset+`CODEX_SECURITY_PROJECT_CONFIG`. An empty context list is valid.++Native objects merge using the existing configuration code. Duplicate native CLI+assignments remain errors; overriding a file value is valid. Selected native+profiles can still override root model/effort values, including convenience flags.+`--provider openai` retains its existing behavior and does not clear a native+provider selected by the file.++## Deep settings and limits++```yaml+scan:+ mode: deep+ deep:+ workers: 4+ subagents_per_worker: 3+ stop_after_no_new: 4+ stop_after_consecutive_errors: 3+ max_discovery_runs: 40+ max_time_hours: 96+limits:+ max_cost_usd_per_scan: 10+```++These deep settings show the existing defaults, shared with the Python plugin.+The cost limit is illustrative. Legacy user `[deep_scan]` TOML remains supported,+including `workers = "auto"`. File and CLI values override individual settings.+All six effective values are resolved before runtime preparation and saved in new+recipes.+If a runtime aliases the ambient TOML file, only explicit overrides are written+back; unrelated sections and inherited defaults remain untouched. Isolated runtime+files still receive a complete snapshot.++A valid deep block can stay inactive in standard mode. Explicit deep CLI options+still require deep mode. Deep diff scans and custom validation remain unsupported.+Counts retain their existing bounds; zero subagents is valid, and discovery time+cannot exceed 96 hours.++`max_cost_usd_per_scan` has the same meaning as `--max-cost`: an estimated limit for one+scan attempt. In-flight work may exceed it. It is not a total budget for a batch or+follow-up actions. `fail_on_severity` changes the exit status without filtering the+retained findings.++## Batch and component scans++```sh+codex-security bulk-scan repositories.csv -c codex-security.yaml --output-dir ../batch-results+codex-security scan-components . --component src -c codex-security.yaml --output-dir ../component-results+```++`output.directory` can supply the batch output directory; `--output-dir` overrides+it. In the interactive bulk wizard, it supplies the proposed output directory.+Both commands use the same config precedence, path anchoring, native settings,+context, prompts, per-attempt cost limit, and severity policy as `scan`.++A bulk CSV row's mode and scope override the file's defaults for that repository.+Bulk checkouts are clean, shallow snapshots, so bulk scans accept repository or+path scopes. A configured diff or working-tree scope is rejected before work+starts unless every affected row supplies its own CSV path scope. Deep settings+apply only to deep rows. Component plans select each component's+scope, overriding `scan.scope`; `scan.mode` selects standard or deep component+scans. Batch `--workers` controls concurrent repositories or components, while+`scan.deep.workers` controls discovery workers within each deep scan.++The severity policy returns exit `1` without discarding completed results or+retrying a scan just because it found issues. Errors or incomplete results take+precedence with exit `2`. Bulk resume retains the saved policy outcome and checks+that the selected scan configuration still matches the campaign.++## Dry run and editor support++`info [-c FILE] --json` reports resolved settings and their sources without a scan+target, prompt-file reads, credentials checks, or runtime initialization. With no+file, it shows defaults. Active deep mode also resolves legacy TOML. It reports+effective model details and native key sources without dumping raw native values.+This is configuration inspection,+not a filesystem, target, or model-availability check.++`scan ... --dry-run --json` checks local inputs without starting Codex, verifying+credentials, or establishing model availability. Removing `--dry-run` starts a+scan and may incur model charges. Deep preflight shows all six effective settings+and `deepScanSources`, including when no project file was selected; invalid+applicable legacy settings now fail before runtime startup.++With `-c`, the output also includes `projectConfig.path`, per-setting sources,+selected instruction/validation file paths, and the finding policy. Native sources+identify which layer supplied a key; profile selection still determines the+effective model and effort. Raw native configuration and credentials are not dumped.+Source paths use the project-file spelling, such as+`scan.deep.stop_after_no_new`; existing output properties such as `deepScanSources`+keep their names.+The source map includes all wrapper settings, including unset values attributed+to `default`; resolving preflight sources does not mutate previously returned maps.++Help, version, and command schema output do not load project files. Missing,+malformed, or invalid selected files exit `2`. Scan exit codes remain `0` for+completion without a policy failure, `1` for the finding threshold, and `2` for+failed, invalid, or incomplete scans. Signal cancellation retains `130` for+`SIGINT` and `143` for `SIGTERM`.++The generated [project schema](../sdk/typescript/schemas/project-config.schema.json)+is self-contained Draft-07 and ships in the npm package. A project-root YAML file+can use:++```yaml+# yaml-language-server: $schema=./node_modules/@openai/codex-security/schemas/project-config.schema.json+{}+```++JSON files can use a root `$schema` string with the same relative path. The CLI+uses its bundled schema and never fetches the hint. Validation does not coerce+values, insert defaults, or discard unknown wrapper keys. Completion inside+`codex` covers common model/provider fields; other native JSON settings retain+existing checks. CLI `scan --schema --json` and result artifact schemas remain+separate contracts.++## Saved reruns++New recipes retain resolved native configuration, scope, auth choice, finding+policy, cost limit, context paths, and all active deep settings. Reruns do not load+the project file again. Complete saved deep settings do not use the current legacy+file; older partial recipes continue using applicable defaults for missing values.++Recipes do not snapshot source or context contents. Reruns use the current checkout+and current context files. Reruns require replacement scan instructions when the+original scan used them: a new recipe records that requirement, and `scans rerun`+refuses to omit them silently.+Use `scans rerun [SCAN_ID] --scan-prompt-file FILE` to supply them again. A required+replacement must not be empty. The file resolves from the invocation directory.+Custom validation keeps its existing `scans rerun --validation-prompt-file FILE`+requirement.++`scans resume SCAN_ID` and eligible `bulk-scan --recover` attempts continue the+original session with its saved instructions, authentication choice, and deep+settings. They do not reload the project file or require replacement instructions.+Bulk recovery still checks the selected configuration against the campaign manifest+and applies its severity policy to recovered findings.++Workflow identity records explicitly requested deep settings, not ambient values+or shipped defaults, so changing those defaults does not prevent resumption.+Changing the explicit request still requires a different workflow ID.diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.mjs b/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.mjsindex 2a18a3ab8..b47ec19ff 100644--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.mjs+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.mjs@@ -739,7 +739,7 @@ async function testWorkerReasoningSummaries() {['model_reasoning_summary = "none"\nprofile = "selected"\n[profiles.selected]\nmodel = "fixture-model"\n[profiles.other]\nmodel_reasoning_summary = "detailed"\n', "none"]];const saved = Object.fromEntries(- ["CODEX_CLI_PATH", "CODEX_SECURITY_CONFIG_PATH", "OPENAI_API_KEY", "CODEX_API_KEY"].map((name) => [name, process.env[name]])+ ["CODEX_CLI_PATH", "CODEX_SECURITY_CONFIG_PATH", "CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH", "OPENAI_API_KEY", "CODEX_API_KEY"].map((name) => [name, process.env[name]]));const originalSpawn = childProcess.spawn;try {@@ -753,6 +753,7 @@ async function testWorkerReasoningSummaries() {await writeFile(promptPath, "synthetic worker configuration fixture");process.env.CODEX_CLI_PATH = process.execPath;process.env.CODEX_SECURITY_CONFIG_PATH = configPath;+ process.env.CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH = path.join(fixture.root, "deep settings.toml");childProcess.spawn = (command, args, options) => originalSpawn(command,command === process.execPath || command === path.toNamespacedPath(process.execPath)@@ -780,6 +781,8 @@ async function testWorkerReasoningSummaries() {assert.equal(invocation.argv.includes(`model_reasoning_summary=${JSON.stringify(expected)}`), true);}assert.equal(invocation.argv.includes('model_reasoning_effort="xhigh"'), true);+ assert.equal(invocation.configPath, configPath);+ assert.equal(invocation.deepConfigPath, process.env.CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH);assertReadOnlyWorkerPolicy(invocation.argv);assertWorkerSubagentPolicy(invocation.argv, 0);await writeFile(configPath, 'model_reasoning_summary = "detailed"\n');@@ -1512,7 +1515,7 @@ async function fakeCodexFixture("for await (const chunk of process.stdin) stdin += chunk;","const openaiAuthentication = stdin.includes('CAPTURE_SYNTHETIC_OPENAI_AUTH') ? { OPENAI_API_KEY: process.env.OPENAI_API_KEY, CODEX_API_KEY: process.env.CODEX_API_KEY } : undefined;","const bedrockAuthentication = stdin.includes('CAPTURE_SYNTHETIC_BEDROCK_AUTH') ? Object.fromEntries(JSON.parse(process.env.FAKE_CODEX_BEDROCK_ENV_KEYS).map((name) => [name, process.env[name]])) : undefined;",- "writeFileSync(process.env.FAKE_CODEX_MARKER, JSON.stringify({ argv: process.argv.slice(2), stdin, cwd: process.cwd(), codexHome: process.env.CODEX_HOME, originator: process.env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE, ...(stdin.includes('COMPLETE_THEN_HANG') ? { pid: process.pid } : {}), ...(openaiAuthentication ? { openaiAuthentication } : {}), ...(bedrockAuthentication ? { bedrockAuthentication } : {}) }));",+ "writeFileSync(process.env.FAKE_CODEX_MARKER, JSON.stringify({ argv: process.argv.slice(2), stdin, cwd: process.cwd(), codexHome: process.env.CODEX_HOME, configPath: process.env.CODEX_SECURITY_CONFIG_PATH, deepConfigPath: process.env.CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH, originator: process.env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE, ...(stdin.includes('COMPLETE_THEN_HANG') ? { pid: process.pid } : {}), ...(openaiAuthentication ? { openaiAuthentication } : {}), ...(bedrockAuthentication ? { bedrockAuthentication } : {}) }));","if (stdin.includes('COMPLETE_THEN_HANG')) process.on('SIGTERM', () => setTimeout(() => process.exit(0), 100));","if (stdin.includes('THREAD_START_CONFIG_ERROR')) { console.error('Error: thread/start: thread/start failed: agents.max_threads cannot be set when features.multi_agent_v2 is enabled (code -32600)'); process.exit(1); }","if (stdin.includes('CONFIG_ERROR')) { console.error('failed to load configuration: invalid value'); process.exit(2); }",diff --git a/plugins/codex-security/plugin-files.json b/plugins/codex-security/plugin-files.jsonindex dbb67cc74..72e5e3838 100644--- a/plugins/codex-security/plugin-files.json+++ b/plugins/codex-security/plugin-files.json@@ -58,6 +58,7 @@"schemas/tools/worker-threat-model.schema.json","scripts/config_preflight.py","scripts/deep_scan_config.py",+ "scripts/deep_scan_defaults.json","scripts/deep_scan_workbench.py","scripts/filesystem_identity.py","scripts/finalize_scan_contract.py",diff --git a/plugins/codex-security/scripts/deep_scan_config.py b/plugins/codex-security/scripts/deep_scan_config.pyindex 36130417d..5d3ffcd1a 100644--- a/plugins/codex-security/scripts/deep_scan_config.py+++ b/plugins/codex-security/scripts/deep_scan_config.py@@ -3,6 +3,7 @@from __future__ import annotationsimport argparse+import jsonimport mathimport osfrom pathlib import Path@@ -13,12 +14,15 @@ try:except ModuleNotFoundError: # pragma: no cover - Python 3.10 onlyimport tomli as tomllib-DEFAULT_WORKERS = 4-DEFAULT_SUBAGENTS = 3-DEFAULT_STOP_AFTER_NO_NEW = 4-DEFAULT_STOP_AFTER_CONSECUTIVE_ERRORS = 3-DEFAULT_MAX_DISCOVERY_RUNS = 40-DEFAULT_MAX_TIME_HOURS = 96+DEFAULTS = json.loads(+ Path(__file__).with_name("deep_scan_defaults.json").read_text(encoding="utf-8")+)+DEFAULT_WORKERS = DEFAULTS["workers"]+DEFAULT_SUBAGENTS = DEFAULTS["subagents"]+DEFAULT_STOP_AFTER_NO_NEW = DEFAULTS["stopAfterNoNew"]+DEFAULT_STOP_AFTER_CONSECUTIVE_ERRORS = DEFAULTS["stopAfterConsecutiveErrors"]+DEFAULT_MAX_DISCOVERY_RUNS = DEFAULTS["maxDiscoveryRuns"]+DEFAULT_MAX_TIME_HOURS = DEFAULTS["maxTimeHours"]MAX_TIME_HOURS = 96CONFIG_KEYS = {"workers",@@ -130,8 +134,6 @@ def main() -> None:parser = argparse.ArgumentParser(description=__doc__)parser.add_argument("--available-parallelism", type=int, required=True)args = parser.parse_args()- import json-print(json.dumps(resolve_deep_scan_config(args.available_parallelism), sort_keys=True))diff --git a/plugins/codex-security/scripts/deep_scan_defaults.json b/plugins/codex-security/scripts/deep_scan_defaults.jsonnew file mode 100644index 000000000..84dcb3f9c--- /dev/null+++ b/plugins/codex-security/scripts/deep_scan_defaults.json@@ -0,0 +1,8 @@+{+ "workers": 4,+ "subagents": 3,+ "stopAfterNoNew": 4,+ "stopAfterConsecutiveErrors": 3,+ "maxDiscoveryRuns": 40,+ "maxTimeHours": 96+}diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex e321c22a0..96f7d900a 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -139,21 +139,25 @@ Constructor options:Options for `security.run(repository, options)` and`security.preflight(repository, options)`:-| Option | Description |-| ----------------------- | ------------------------------------------------------------------------------ |-| `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |-| `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |-| `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |-| `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |-| `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |-| `outputDir` | Artifact directory outside the enclosing Git worktree. |-| `archiveExisting` | Archive existing results in `outputDir` before scanning. |-| `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |-| `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |-| `failureSeverity` | Finding-severity policy to record in the saved scan recipe. |-| `parentScanId` | Parent scan ID for a rerun. |-| `expectedPluginVersion` | Required original plugin version when replaying a scan. |-| `signal` | `AbortSignal` to cancel a scan. |+| Option | Description |+| ------------------------------------------- | ----------------------------------------------------------------------------------- |+| `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |+| `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |+| `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |+| `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |+| `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |+| `scanPrompt` / `scanPromptFile` | Additional scan instructions as text or a local file. |+| `validationPrompt` / `validationPromptFile` | Custom validation instructions as text or a local file; not Deep. |+| `postScanPrompt` / `postScanPromptFile` | Follow-up instructions as text or a local file. |+| `outputDir` | Artifact directory outside the enclosing Git worktree. |+| `archiveExisting` | Archive existing results in `outputDir` before scanning. |+| `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |+| `stopAfterConsecutiveErrors` | Stop deep discovery after this many consecutive errors (default: 3). |+| `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |+| `failureSeverity` | Severity threshold recorded in the recipe; the SDK caller decides how to handle it. |+| `parentScanId` | Parent scan ID for a rerun. |+| `expectedPluginVersion` | Required original plugin version when replaying a scan. |+| `signal` | `AbortSignal` to cancel a scan. |Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receivessaved events with thread IDs and worker numbers. Deep scans can additionally use@@ -164,6 +168,46 @@ and `maximum`. The maximum is a configured cap, not a percentage denominator.`preflight` and CLI `--dry-run` check local inputs without starting Codex orusing the network. They don't authenticate, verify model access, resolve Python,inspect the plugin, or run scan-lifecycle callbacks. Dry runs print effective settings.+Deep preflight includes all six resolved deep settings and their origins in+`deepScanSources`. Applicable legacy deep configuration is validated during+preflight rather than after runtime startup.++`ScanSettings` is the shared settings type. `ScanOptions` adds callbacks,+cancellation, workflow, and runtime controls. Load the same project file used by+`scan -c` through the SDK:++```ts+import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";++const { config, options } = await loadProjectConfig("codex-security.yaml");+await using security = new CodexSecurity(config);+const result = await security.run(repository, options);+if (+ options.failureSeverity !== undefined &&+ result.hasFindingsAtOrAbove(options.failureSeverity)+) {+ process.exitCode = 1;+}+```++`resolveProjectConfig(input, directory?)` accepts a typed `ProjectConfigInput`+object with the same `snake_case` keys as YAML/JSON and returns the same `{ config,+options }` pair and an immutable `sources` map. Resolved context, prompt, and output+paths have the `AbsolutePath` type. `loadProjectConfig(file, directory?)` resolves the selected file+from `directory`, which defaults to the current directory; paths inside the file+are relative to that file. Object paths are relative to the supplied directory.+Scope paths remain relative to the selected repository. Neither helper starts a+scan, reads prompt contents, or discovers another configuration file. `preflight`+and `run` apply the existing local checks and remaining legacy deep defaults.+Project-file keys follow Codex's configuration convention; SDK options keep their+existing `camelCase` names, and CLI flags keep `kebab-case`.++Override resolved SDK options with `{ ...options, maxCostUsd: 5 }`, or add+callbacks there. Direct SDK prompt-file paths use the current directory; inline+text takes precedence over its matching file. Files use the same regular-file+protections as the CLI. The SDK records `failureSeverity` without throwing or+changing process status. `hasFindingsAtOrAbove()` uses the CLI's severity ordering+and leaves the findings unchanged.## Authentication@@ -446,7 +490,73 @@ npx @openai/codex-security scan /path/to/repository --dry-runUse `scan --help` for options, `--version` for the installed version, and`info --json` for package, plugin, runtime, and model details. `--dry-run`-runs local preflight checks.+runs local preflight checks. `info -c FILE --json` inspects resolved configuration+and its sources without a repository or runtime.++### Project files++Use `scan -c FILE` / `scan --config FILE` to load reusable scan settings:++```bash+codex-security scan . -c codex-security.yaml --dry-run --json+codex-security scan . -c codex-security.json --model gpt-5.6-terra+codex-security init+codex-security info -c codex-security.yaml --json+```++Select one `.yaml`, `.yml`, or `.json` file. `scan`, `bulk-scan`, `scan-components`,+and `info` accept `-c`. They also accept an operator-set+`CODEX_SECURITY_PROJECT_CONFIG`; an explicit `-c` wins. Without either, no file is+loaded or discovered. The repository still comes from the command's target+selection. SDK `run()` and saved reruns do not load project files automatically.++The selected file is trusted like CLI options and SDK `codexOverrides`. Native+settings can start configured MCP server processes and select model-service destinations. Do not+select configuration controlled by an untrusted repository or pull request; keep+CI scanner configuration outside the checkout being assessed.++`init [file]` writes `codex-security.yaml` by default and never overwrites an+existing file. YAML starters show defaults as comments; JSON starters contain the+editor schema hint, relative to the chosen file and the invocation directory's+local package installation. `info` reports effective model details and native key sources+without dumping raw native values.++```yaml+# yaml-language-server: $schema=./node_modules/@openai/codex-security/schemas/project-config.schema.json+scan:+ mode: standard+ scope:+ paths: [src]+codex:+ model: gpt-5.6-sol+ model_reasoning_effort: xhigh+policy:+ fail_on_severity: high+```++All settings are optional; `{}` uses the existing defaults. JSON files can use a+root `$schema` string pointing to the same packaged schema. Schema hints are for+editors; the CLI uses its bundled validator without fetching URLs, coercing values,+or dropping unknown keys. Native `codex` settings retain their existing checks and+profile semantics. CLI `scan --schema --json` describes command arguments.++Settings use built-in defaults, applicable legacy deep defaults, the file, then+explicit CLI values. Lists and scope variants are replaced. `--head` can refine+a file diff and `--base` a file working-tree scope. A selected native profile can+still override root model/effort values. Existing native alias-conflict checks+and the behavior of `--provider openai` are unchanged.++File context, instruction, validation, and output paths resolve from the file's+directory. CLI file paths resolve from the invocation directory; scope paths+resolve from the repository. The file cannot select a different repository or+enable automatic patching/publication. The loader does not evaluate code,+interpolate environment values, include remote files, or merge multiple files.++Dry-run output adds `projectConfig.path` and `projectConfig.sources`, selected+prompt paths, and the finding policy without dumping raw native configuration.+Missing or invalid selected files exit `2`. Help, version, and command schema+output do not load project files. Existing scan and finding-policy exit codes+remain unchanged.### Scan options and output@@ -454,6 +564,10 @@ runs local preflight checks.and `--working-tree` scans staged and unstaged changes. Deep scans supportrepository and path targets.+Bulk scans use clean, shallow checkouts and support repository or path scopes.+They reject configured diff or working-tree scopes before starting unless each+affected CSV row supplies its own path scope.+Working-tree snapshots include files from untracked nested Git repositories.Initialized submodules must be clean and checked out at the commit recorded bythe parent repository.@@ -567,7 +681,7 @@ runtime or plugin compatibility. Older versions may omit the ID.### Scan project components`scan --path` runs one scan across selected paths. To scan each local project-component separately in standard mode, use `scan-components`:+component separately (standard mode by default), use `scan-components`:```bashnpx @openai/codex-security scan-components /path/to/project \@@ -575,6 +689,12 @@ npx @openai/codex-security scan-components /path/to/project \--workers 4 --output-dir /path/outside/project/results```+Use `-c FILE` to share settings, including `scan.mode: deep`, context and prompt+files, per-scan deep workers, cost limits, and severity policy. Component plans+override the file's scope. `output.directory` supplies the results directory when+`--output-dir` is omitted. A configured severity threshold returns exit `1` after+completed scans; failures or incomplete results return `2`.+Use `--auto` instead of `--component` for a proposed split. Save a plan toreview or edit, then run it with a new output directory:@@ -651,6 +771,7 @@ await security.run("/path/to/repository", {workers: 2,subagents: 0,stopAfterNoNew: 3,+ stopAfterConsecutiveErrors: 2,maxDiscoveryRuns: 10,maxTimeHours: 1.5,});@@ -668,8 +789,10 @@ max_discovery_runs = 40max_time_hours = 96```-CLI and SDK options override these defaults. Set `stop_after_consecutive_errors`-in the file; `--codex` cannot configure this section. Worker and run counts must+CLI and SDK options override these defaults. Project files can use+`scan.deep.stop_after_consecutive_errors`, and SDK calls can use+`stopAfterConsecutiveErrors`; there is no new CLI flag for it. `--codex` cannot+configure this section. Worker and run counts mustbe positive integers; `subagents` can be zero. Legacy `workers = "auto"` meansfour workers. Unknown keys are rejected.@@ -679,6 +802,12 @@ At the deadline, discovery stops; the scan combines and returns completed findin`scan --workers` controls discovery workers within one deep scan;`bulk-scan --workers` controls how many repositories are scanned concurrently.+The project-file deep block uses `subagents_per_worker` for the existing SDK/CLI+`subagents` setting. A valid deep block can remain inactive in standard mode;+explicit deep CLI options require deep mode. All six active values are resolved+before runtime preparation and saved in new recipes. Complete saved values are+independent of later changes to the legacy TOML file.+### Runtime configuration and worker limitsScans use these isolated Codex defaults instead of your user or repository@@ -761,23 +890,24 @@ restrictions.### Environment variables-| Variable | Effect |-| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |-| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |-| `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |-| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |-| `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |-| `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |-| `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |-| `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |-| `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |-| `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |-| `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |-| `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |-| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |-| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |-| `CI` | Disables interactive update notices. |-| `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |+| Variable | Effect |+| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |+| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |+| `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |+| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |+| `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |+| `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |+| `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |+| `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |+| `CODEX_SECURITY_PROJECT_CONFIG` | Trusted project file for `scan`, `bulk-scan`, `scan-components`, and `info`; `-c` wins. Unset by default. |+| `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |+| `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |+| `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |+| `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |+| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |+| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |+| `CI` | Disables interactive update notices. |+| `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |Custom Codex executables need thread source attribution for `exec` and`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;@@ -873,6 +1003,11 @@ npx @openai/codex-security bulk-scan repositories.csv \`--scan-prompt-file PATH` adds instructions to a scan or all bulk scans. Eachrepository's CSV `prompt` follows the shared instructions.+`-c FILE` shares config with single scans: CSV mode/scope override file defaults,+and deep settings apply only to deep rows. `output.directory` can supply the+results directory. `fail_on_severity` returns exit `1` without retrying completed+scans, including when resuming saved results. A changed project configuration+requires a new campaign output directory.`--post-scan-prompt-file PATH` runs a follow-up in the same authenticated session,even after a failed or incomplete scan, but not after cancellation or acost-limit stop.@@ -927,7 +1062,8 @@ file. Source review still runs; discovery workers do not receive this prompt.npx @openai/codex-security scan . --validation-prompt-file validation.md```-The SDK accepts the same text as `validationPrompt`:+The SDK accepts the same file as `validationPromptFile`, or inline text as+`validationPrompt`:```tsconst result = await security.run(repository, {@@ -1280,6 +1416,18 @@ The command uses Codex's feedback service and respects `feedback.enabled = falseCommands default to the current repository. Select scans by full ID or aunique prefix of at least eight characters.+New recipes retain resolved settings and the authentication choice, not+credentials. Reruns do not reload project files; complete saved deep settings do+not use current legacy defaults. Older partial recipes retain their previous+fallback behavior. Context paths and the current checkout are not immutable input+snapshots.++Reruns require replacement scan instructions when the original scan used them.+New recipes mark this requirement, and `scans rerun` refuses to omit them silently; use+`scans rerun [SCAN_ID] --scan-prompt-file FILE` to supply a nonempty replacement.+Replacement files resolve from the invocation directory. Custom validation keeps its existing+`scans rerun --validation-prompt-file` requirement.+| Command | Purpose || ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- || `scans list [REPOSITORY]` | List scans. Filter by artifact root with `--scan-root DIR`. |diff --git a/sdk/typescript/package.json b/sdk/typescript/package.jsonindex dcbf2bbaa..b2640e766 100644--- a/sdk/typescript/package.json+++ b/sdk/typescript/package.json@@ -27,7 +27,8 @@"types": "./dist/index.d.ts","import": "./dist/index.js","default": "./dist/index.js"- }+ },+ "./schemas/project-config.schema.json": "./schemas/project-config.schema.json"},"bin": {"codex-security": "./bin/codex-security.mjs"@@ -35,6 +36,7 @@"files": ["bin","dist",+ "schemas","_bundled_plugin","LICENSE","README.md"@@ -48,7 +50,7 @@"scripts": {"audit:prod": "pnpm audit --prod --audit-level high","clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",- "build": "node --run clean && tsc -p tsconfig.build.json && node scripts/build-dashboard.mjs",+ "build": "node --run clean && node scripts/generate-deep-defaults.mjs && tsc -p tsconfig.build.json && node scripts/generate-project-config-schema.mjs && node scripts/build-dashboard.mjs","build:ci": "tsc -p tsconfig.ci.json","build:examples": "tsc -p tsconfig.examples.json","build:plugin": "node scripts/build-plugin.mjs",@@ -65,7 +67,7 @@"test:mcp": "node --run build:plugin && pnpm --dir ../../plugins/codex-security/mcp-app run test:mcp","test:mutation": "stryker run","test:package": "node scripts/smoke-package.mjs",- "types": "pnpm run generate:models:check && pnpm --dir ../../plugins/codex-security/mcp-app run typecheck && tsc --noEmit"+ "types": "node scripts/generate-deep-defaults.mjs --check && node scripts/generate-project-config-schema.mjs --check && pnpm run generate:models:check && pnpm --dir ../../plugins/codex-security/mcp-app run typecheck && tsc --noEmit"},"dependencies": {"@inquirer/prompts": "8.3.0",@@ -84,7 +86,9 @@"pdfjs-dist": "6.2.108","react": "19.2.4","semver": "7.8.5",- "smol-toml": "1.7.1"+ "smol-toml": "1.7.1",+ "yaml": "2.9.0",+ "zod": "4.4.3"},"devDependencies": {"@openai/apps-sdk-ui": "0.2.2",diff --git a/sdk/typescript/pnpm-lock.yaml b/sdk/typescript/pnpm-lock.yamlindex ae18a5b55..3aa2c93e2 100644--- a/sdk/typescript/pnpm-lock.yaml+++ b/sdk/typescript/pnpm-lock.yaml@@ -59,6 +59,12 @@ importers:smol-toml:specifier: 1.7.1version: 1.7.1+ yaml:+ specifier: 2.9.0+ version: 2.9.0+ zod:+ specifier: 4.4.3+ version: 4.4.3devDependencies:'@openai/apps-sdk-ui':specifier: 0.2.2diff --git a/sdk/typescript/schemas/project-config.schema.json b/sdk/typescript/schemas/project-config.schema.jsonnew file mode 100644index 000000000..263de9e6f--- /dev/null+++ b/sdk/typescript/schemas/project-config.schema.json@@ -0,0 +1,211 @@+{+ "$schema": "http://json-schema.org/draft-07/schema#",+ "type": "object",+ "properties": {+ "$schema": {+ "description": "Editor schema URI or relative path. The CLI does not fetch or select a validator from this value.",+ "type": "string",+ "minLength": 1+ },+ "auth": {+ "default": "auto",+ "description": "Credential-source choice only; never a credential value.",+ "type": "string",+ "enum": ["auto", "chatgpt", "api-key"]+ },+ "scan": {+ "type": "object",+ "properties": {+ "mode": {+ "default": "standard",+ "type": "string",+ "enum": ["standard", "deep"]+ },+ "scope": {+ "description": "One scope variant. Omit for the whole repository. Mode compatibility is checked after overrides.",+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "paths": {+ "minItems": 1,+ "type": "array",+ "items": { "type": "string", "minLength": 1 },+ "description": "Literal paths relative to the selected repository."+ }+ },+ "required": ["paths"],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "diff": {+ "type": "object",+ "properties": {+ "base": { "type": "string", "minLength": 1 },+ "head": {+ "default": "HEAD",+ "type": "string",+ "minLength": 1+ }+ },+ "required": ["base"],+ "additionalProperties": false+ }+ },+ "required": ["diff"],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "working_tree": {+ "type": "object",+ "properties": {+ "base": {+ "default": "HEAD",+ "type": "string",+ "minLength": 1+ }+ },+ "additionalProperties": false+ }+ },+ "required": ["working_tree"],+ "additionalProperties": false+ }+ ]+ },+ "knowledge_base": {+ "description": "Context files or directories, relative to this file. An empty list selects no additional context.",+ "type": "array",+ "items": { "type": "string", "minLength": 1 }+ },+ "instructions_file": {+ "description": "Additional scan instructions, relative to this file.",+ "type": "string",+ "minLength": 1+ },+ "validation_file": {+ "description": "Custom validation instructions, relative to this file; not supported in active deep scans.",+ "type": "string",+ "minLength": 1+ },+ "deep": {+ "description": "Deep defaults; a valid block may be retained while standard mode is selected.",+ "type": "object",+ "properties": {+ "workers": {+ "default": 4,+ "description": "Maximum concurrent deep-scan discovery workers.",+ "type": "integer",+ "exclusiveMinimum": 0,+ "maximum": 9007199254740991+ },+ "subagents_per_worker": {+ "default": 3,+ "description": "Subagents available to each deep-scan worker. Zero is valid.",+ "type": "integer",+ "minimum": 0,+ "maximum": 9007199254740991+ },+ "stop_after_no_new": {+ "default": 4,+ "description": "Stop after this many runs find no new issues.",+ "type": "integer",+ "exclusiveMinimum": 0,+ "maximum": 9007199254740991+ },+ "stop_after_consecutive_errors": {+ "default": 3,+ "description": "Stop after this many consecutive discovery errors.",+ "type": "integer",+ "exclusiveMinimum": 0,+ "maximum": 9007199254740991+ },+ "max_discovery_runs": {+ "default": 40,+ "description": "Maximum deep-scan discovery runs.",+ "type": "integer",+ "exclusiveMinimum": 0,+ "maximum": 9007199254740991+ },+ "max_time_hours": {+ "default": 96,+ "description": "Maximum deep-scan discovery hours (default: 96; maximum: 96).",+ "type": "number",+ "exclusiveMinimum": 0,+ "maximum": 96+ }+ },+ "additionalProperties": false+ }+ },+ "additionalProperties": false+ },+ "codex": {+ "description": "Native Codex overrides. Common key types are checked here; existing native and wrapper restrictions still apply.",+ "type": "object",+ "properties": {+ "model": { "type": "string", "minLength": 1 },+ "model_reasoning_effort": { "type": "string", "minLength": 1 },+ "model_provider": { "type": "string", "minLength": 1 }+ },+ "additionalProperties": { "$ref": "#/definitions/__schema0" }+ },+ "limits": {+ "type": "object",+ "properties": {+ "max_cost_usd_per_scan": {+ "description": "Estimated USD limit per launched scan attempt, not a total batch budget. Omit for no limit.",+ "type": "number",+ "exclusiveMinimum": 0+ }+ },+ "additionalProperties": false+ },+ "policy": {+ "type": "object",+ "properties": {+ "fail_on_severity": {+ "description": "Exit threshold; does not filter retained findings. Omit for report-only behavior.",+ "type": "string",+ "enum": ["critical", "high", "medium", "low"]+ }+ },+ "additionalProperties": false+ },+ "output": {+ "type": "object",+ "properties": {+ "directory": {+ "description": "Artifact directory relative to this file; existing outside-worktree checks still apply.",+ "type": "string",+ "minLength": 1+ }+ },+ "additionalProperties": false+ }+ },+ "additionalProperties": false,+ "definitions": {+ "__schema0": {+ "anyOf": [+ { "type": "string" },+ { "type": "number" },+ { "type": "boolean" },+ { "type": "null" },+ { "type": "array", "items": { "$ref": "#/definitions/__schema0" } },+ {+ "type": "object",+ "propertyNames": { "type": "string" },+ "additionalProperties": { "$ref": "#/definitions/__schema0" }+ }+ ]+ }+ },+ "title": "Codex Security project configuration",+ "description": "Input schema for explicitly selected YAML or JSON project files. Filesystem, active scan combinations, native configuration, and runtime availability are checked separately.",+ "$comment": "Generated from ProjectConfigInputSchema. Defaults are annotations; apply defaults only after merging input layers."+}diff --git a/sdk/typescript/scripts/check-package.mjs b/sdk/typescript/scripts/check-package.mjsindex 36f9598b4..e894aba38 100644--- a/sdk/typescript/scripts/check-package.mjs+++ b/sdk/typescript/scripts/check-package.mjs@@ -108,6 +108,7 @@ const required = ["package/dist/index.js","package/dist/index.d.ts","package/dist/cli.js",+ "package/schemas/project-config.schema.json","package/_bundled_plugin/.codex-plugin/plugin.json",];@@ -161,6 +162,7 @@ const allowedRoot = new Set(["package/README.md","package/LICENSE","package/bin/codex-security.mjs",+ "package/schemas/project-config.schema.json",]);const distFiles = new Set([@@ -176,6 +178,7 @@ const distFiles = new Set("component-plan","component-scan","config",+ "config-path","contract","cost","cost-model",@@ -183,6 +186,13 @@ const distFiles = new Set("custom-validation-prompt","custom-publish","deep-progress",+ "deep-config",+ "deep-scan-defaults",+ "project-config",+ "project-config-schema",+ "prompt-files",+ "scan-modes",+ "scan-settings","errors","feedback","finding-catalogue",@@ -265,6 +275,7 @@ for (const file of files) {const allowed = file.endsWith("/")? normalized === "package" ||normalized === "package/bin" ||+ normalized === "package/schemas" ||normalized === "package/dist" ||normalized === "package/dist/server" ||normalized === "package/dist/server/dashboard" ||diff --git a/sdk/typescript/scripts/fixtures/package-consumer.ts b/sdk/typescript/scripts/fixtures/package-consumer.tsindex 0f21c42f7..d98c7c9b5 100644--- a/sdk/typescript/scripts/fixtures/package-consumer.ts+++ b/sdk/typescript/scripts/fixtures/package-consumer.ts@@ -6,15 +6,18 @@ import {classifyScanDirectorySeverity,deduplicateScan,estimateScanCost,+ loadProjectConfig,matchScanFindings,planComponents,publishScanToCustom,publishScan,runComponentScans,+ resolveProjectConfig,type ComponentScanOptions,type DeduplicateScanResult,type CustomPublicationResult,type Finding,+ type ProjectConfigInput,type SeverityClassification,type ScanSeverityClassification,type ScanCost,@@ -24,6 +27,7 @@ import {type ScanOptions,type ScanProgress,type ScanResult,+ type ScanSettings,type ValidationOptions,type ValidationResult,} from "@openai/codex-security";@@ -118,6 +122,35 @@ export async function scan(repository: string): Promise<ScanResult> {}}+export function configuredScanOptions(+ input: ProjectConfigInput = {+ scan: {+ mode: "deep",+ scope: { paths: ["src"] },+ deep: { subagents_per_worker: 0, stop_after_consecutive_errors: 2 },+ },+ limits: { max_cost_usd_per_scan: 5 },+ policy: { fail_on_severity: "high" },+ },+): ScanSettings {+ return resolveProjectConfig(input).options;+}++export async function scanFromFile(repository: string, file: string) {+ const { config, options } = await loadProjectConfig(file);+ await using client = new CodexSecurity(config);+ const result = await client.run(repository, {+ ...options,+ postScanPromptFile: "follow-up.md",+ });+ return {+ result,+ failed:+ options.failureSeverity !== undefined &&+ result.hasFindingsAtOrAbove(options.failureSeverity),+ };+}+export const cost: ScanCost | null = estimateScanCost("gpt-5.6-sol", {input_tokens: 10,output_tokens: 2,diff --git a/sdk/typescript/scripts/generate-deep-defaults.mjs b/sdk/typescript/scripts/generate-deep-defaults.mjsnew file mode 100644index 000000000..8b86e9b97--- /dev/null+++ b/sdk/typescript/scripts/generate-deep-defaults.mjs@@ -0,0 +1,24 @@+import { readFile, writeFile } from "node:fs/promises";+import { format } from "prettier";++const defaults = JSON.parse(+ await readFile(+ new URL(+ "../../../plugins/codex-security/scripts/deep_scan_defaults.json",+ import.meta.url,+ ),+ "utf8",+ ),+);+const contents = await format(+ `// Generated from the plugin deep_scan_defaults.json. Run pnpm build.\nexport const DEFAULT_DEEP_SCAN_SETTINGS = ${JSON.stringify(defaults)} as const;\n`,+ { parser: "typescript" },+);+const output = new URL("../src/deep-scan-defaults.ts", import.meta.url);+if (process.argv.includes("--check")) {+ if ((await readFile(output, "utf8")).replaceAll("\r\n", "\n") !== contents) {+ throw new Error("Deep scan defaults are out of date. Run pnpm build.");+ }+} else {+ await writeFile(output, contents);+}diff --git a/sdk/typescript/scripts/generate-project-config-schema.mjs b/sdk/typescript/scripts/generate-project-config-schema.mjsnew file mode 100644index 000000000..7a0e1a789--- /dev/null+++ b/sdk/typescript/scripts/generate-project-config-schema.mjs@@ -0,0 +1,34 @@+import { mkdir, readFile, writeFile } from "node:fs/promises";+import { fileURLToPath } from "node:url";+import { build } from "esbuild";+import { format } from "prettier";++// Load the source schema without requiring a prior SDK build during typechecks.+const bundled = await build({+ entryPoints: [+ fileURLToPath(new URL("../src/project-config-schema.ts", import.meta.url)),+ ],+ bundle: true,+ platform: "node",+ format: "esm",+ write: false,+});+const { projectConfigJsonSchema } = await import(+ `data:text/javascript;base64,${Buffer.from(bundled.outputFiles[0].contents).toString("base64")}`+);++const directory = new URL("../schemas/", import.meta.url);+const output = new URL("project-config.schema.json", directory);+const contents = await format(JSON.stringify(projectConfigJsonSchema()), {+ parser: "json",+});+if (process.argv.includes("--check")) {+ if ((await readFile(output, "utf8")).replaceAll("\r\n", "\n") !== contents) {+ throw new Error(+ "Project configuration schema is out of date. Run pnpm build.",+ );+ }+} else {+ await mkdir(directory, { recursive: true });+ await writeFile(output, contents);+}diff --git a/sdk/typescript/scripts/smoke-package.mjs b/sdk/typescript/scripts/smoke-package.mjsindex f3040eec5..576d08422 100644--- a/sdk/typescript/scripts/smoke-package.mjs+++ b/sdk/typescript/scripts/smoke-package.mjs@@ -6,8 +6,8 @@ import {mkdir,mkdtemp,readFile,- realpath,readdir,+ realpath,rm,stat,writeFile,@@ -426,7 +426,7 @@ try {"--input-type=module","--eval",`const sdk = await import(${JSON.stringify(packageManifest.name)});- for (const name of ["CodexSecurity", "publishScan", "publishScanToCustom", "checkScanPublication", "deduplicateScan", "classifySeverity", "classifyScanSeverity", "classifyScanDirectorySeverity", "matchScanFindings", "securityPolicyDiff"]) {+ for (const name of ["CodexSecurity", "publishScan", "publishScanToCustom", "checkScanPublication", "deduplicateScan", "classifySeverity", "classifyScanSeverity", "classifyScanDirectorySeverity", "matchScanFindings", "securityPolicyDiff", "loadProjectConfig", "resolveProjectConfig"]) {if (typeof sdk[name] !== "function") {throw new Error("The installed package does not export " + name + ".");}@@ -437,7 +437,19 @@ try {const result = await sdk.matchScanFindings({ before: [], after: [] });if (result.matches.length !== 0 || result.uncertain.length !== 0) {throw new Error("Empty finding comparison did not return an empty result.");- }`,+ } const assert = await import("node:assert/strict");+ const { writeFile } = await import("node:fs/promises");+ const input = { scan: { mode: "deep", deep: { subagents_per_worker: 0 } }, policy: { fail_on_severity: "high" } };+ await writeFile("scan.json", JSON.stringify(input));+ const loaded = await sdk.loadProjectConfig("scan.json");+ const resolved = sdk.resolveProjectConfig(input);+ assert.deepEqual(loaded.config, resolved.config);+ assert.deepEqual(loaded.options, resolved.options);+ assert.equal(loaded.options.subagents, 0);+ assert.equal(loaded.options.failureSeverity, "high");+ assert.equal(loaded.sources["scan.deep.subagents_per_worker"], "project");+ assert.equal(loaded.sources["output.directory"], "default");+ assert.equal(Object.isFrozen(loaded.sources), true);`,],{ cwd: consumer },);@@ -563,6 +575,44 @@ try {assert.equal(policyPreflight.dryRun, true);assert.deepEqual(await readdir(policyTarget), []);+ const starterPath = join(consumer, "codex-security.yaml");+ const starter = JSON.parse(+ run(process.execPath, [launcher, "init", "--json"], {+ cwd: consumer,+ capture: true,+ }),+ );+ // Compare file identities across symlink aliases and Windows short names.+ const canonicalStarterPath = await realpath(starterPath);+ assert.equal(await realpath(starter.path), canonicalStarterPath);+ for (const args of [["-c", starterPath], []]) {+ const info = JSON.parse(+ run(process.execPath, [launcher, "info", ...args, "--json"], {+ cwd: consumer,+ capture: true,+ env: { ...process.env, CODEX_SECURITY_PROJECT_CONFIG: starterPath },+ }),+ );+ assert.equal(await realpath(info.configuration.path), canonicalStarterPath);+ assert.equal(info.configuration.settings.mode, "standard");+ assert.equal(info.configuration.sources["scan.mode"], "default");+ }++ const nestedDirectory = join(consumer, "settings");+ await mkdir(nestedDirectory);+ const nestedPath = join(nestedDirectory, "security.json");+ run(process.execPath, [launcher, "init", nestedPath, "--json"], {+ cwd: consumer,+ capture: true,+ });+ const nestedConfig = JSON.parse(await readFile(nestedPath, "utf8"));+ assert.equal(+ await realpath(resolve(nestedDirectory, nestedConfig.$schema)),+ await realpath(+ join(installedRoot, "schemas", "project-config.schema.json"),+ ),+ );+const publicationScan = join(consumer, "publication-scan");await cp(join(installedRoot, "_bundled_plugin", "examples", "completed-scan"),diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.tsindex 838dadfa6..fe35ad71b 100644--- a/sdk/typescript/src/api.ts+++ b/sdk/typescript/src/api.ts@@ -29,11 +29,6 @@ import {type ThreadOptions,type TurnOptions,} from "@openai/codex-sdk";-import {- parse as parseToml,- stringify as stringifyToml,- type TomlTable,-} from "smol-toml";import { z } from "incur";import {CODEX_AUTH_CONFIG_KEYS,@@ -78,6 +73,26 @@ import {type DeepScanProgress,} from "./deep-progress.js";import { findScanSession } from "./scan-logs.js";+import {+ deepScanOptions,+ resolveDeepScanConfig,+ writeDeepScanConfig,+ type DeepScanSources,+ type ResolvedDeepScanConfig,+} from "./deep-config.js";+import {+ DEFAULT_SCAN_AUTH,+ DEFAULT_SCAN_MODE,+ SCAN_AUTH_MODES,+ ScanSettingsSchema,+ type DeepScanOptions,+ type ScanAuthMode,+ type ScanSettings,+ type ScanPromptSettings,+} from "./scan-settings.js";+import { resolveScanPrompts } from "./prompt-files.js";+export { SCAN_AUTH_MODES } from "./scan-settings.js";+export type { DeepScanOptions, ScanAuthMode } from "./scan-settings.js";import {loadContract,readScanFile,@@ -196,7 +211,6 @@ import {resolveRepositoryPath,type NormalizedTarget,type ScanMode,- type ScanTarget,validatedGitEnvironment,validateCommittedDiffCheckout,validateMode,@@ -254,36 +268,18 @@ interface PreparedSession {const DEEP_SCAN_CONFIG_PATH_ENVIRONMENT ="CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH";-export interface DeepScanOptions {- workers?: number;- subagents?: number;- stopAfterNoNew?: number;- maxDiscoveryRuns?: number;- maxTimeHours?: number;-}--export interface ScanOptions extends DeepScanOptions {+export interface ScanOptions extends ScanSettings {/** @internal Resume a CLI Deep Scan with its saved launch recipe. */resumeScanId?: string;/** 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;/** Stable, privacy-preserving end-user ID for this scan's model requests. */safetyIdentifier?: string;- target?: ScanTarget;- mode?: ScanMode;- knowledgeBasePaths?: string[];- scanPrompt?: string;- validationPrompt?: string;- postScanPrompt?: string;- outputDir?: string;archiveExisting?: boolean;parentScanId?: string;expectedPluginVersion?: string;- failureSeverity?: SeverityLevel;- maxCostUsd?: number;onCost?: (cost: Readonly<ScanCost>, maxCostUsd?: number) => void;onBudgetApproaching?: (budget: ScanBudget,@@ -336,9 +332,6 @@ export interface ValidationResult {threadId: string | null;}-export const SCAN_AUTH_MODES = ["auto", "chatgpt", "api-key"] as const;-export type ScanAuthMode = (typeof SCAN_AUTH_MODES)[number];-export type ScanAuthentication =| { method: "command"; verified: false }| {@@ -413,6 +406,7 @@ export interface ScanPreflight extends DeepScanOptions {modelProvider?: string;reasoningEffort: string;maxCostUsd?: number;+ deepScanSources?: DeepScanSources;}interface LocalScanInputs@@ -420,6 +414,8 @@ interface LocalScanInputsprotectedRoot: string;protectedRoots: readonly string[];stateDirectory: string;+ deepScanConfiguration?: ResolvedDeepScanConfig;+ prompts: ScanPromptSettings;}export interface CodexSecurityMetadata {@@ -463,13 +459,6 @@ const SAFETY_IDENTIFIER_ENV = "CODEX_SAFETY_IDENTIFIER";const PERSONAL_TRUSTED_ACCESS_URL = "https://chatgpt.com/cyber";const ORGANIZATIONAL_TRUSTED_ACCESS_URL ="https://openai.com/form/enterprise-trusted-access-for-cyber/";-const DEEP_SCAN_SETTINGS = [- ["workers", "workers", 1],- ["subagents", "subagents", 0],- ["stopAfterNoNew", "stop_after_no_new", 1],- ["maxDiscoveryRuns", "max_discovery_runs", 1],- ["maxTimeHours", "max_time_hours", 0],-] as const;export class CodexSecurity {public readonly config: Readonly<CodexSecurityConfig>;public readonly metadata: CodexSecurityMetadata = {@@ -528,7 +517,7 @@ export class CodexSecurity {this.#abortController.signal,...(options.signal ? [options.signal] : []),]);- const local = await this.#validateLocalInputs(+ const local = await this.#prepareLocalInputs(repository,{ ...options, outputDir: undefined, archiveExisting: false },signal,@@ -547,8 +536,9 @@ export class CodexSecurity {config: this.config,options: {...options,+ ...local.prompts,target: options.target ?? "repository",- mode: options.mode ?? "standard",+ mode: options.mode ?? DEFAULT_SCAN_MODE,outputDir:options.outputDir === undefined? undefined@@ -597,7 +587,7 @@ export class CodexSecurity {}await workflow.begin("scan");try {- const result = await this.#run(repository, options);+ const result = await this.#run(repository, options, local);await workflow.protectArtifacts(result.scanDir);await workflow.bind({scanId: result.manifest.scan.id,@@ -643,7 +633,7 @@ export class CodexSecurity {);}const finding = jsonForPrompt(options.finding);- const inputs = await this.#validateLocalInputs(+ const inputs = await this.#prepareLocalInputs(options.repositoryPath,options,signal,@@ -740,7 +730,7 @@ export class CodexSecurity {options: ScanOptions = {},): Promise<ScanPreflight> {this.#requireOpen();- const inputs = await this.#validateLocalInputs(+ const inputs = await this.#prepareLocalInputs(repository,options,options.signal,@@ -777,7 +767,10 @@ export class CodexSecurity {repository: inputs.repository,target: inputs.target,mode: inputs.mode,- ...deepScanOptions(options),+ ...inputs.deepScanConfiguration?.settings,+ ...(inputs.deepScanConfiguration === undefined+ ? {}+ : { deepScanSources: inputs.deepScanConfiguration.sources }),...(options.knowledgeBasePaths?.length? { knowledgeBasePaths: options.knowledgeBasePaths }: {}),@@ -1176,7 +1169,11 @@ export class CodexSecurity {}}- async #run(repository: string, options: ScanOptions): Promise<ScanResult> {+ async #run(+ repository: string,+ options: ScanOptions,+ preparedInputs?: LocalScanInputs,+ ): Promise<ScanResult> {this.#requireOpen();if (options.mock) return await this.#runMock(repository, options);const costAbortController = new AbortController();@@ -1226,7 +1223,18 @@ export class CodexSecurity {throwIfAborted(signal, scanDir);};- // Validate all local inputs before runtime initialization or plugin-Python discovery.+ // Workflows reuse the prepared prompts and deep settings, but validate the+ // output only when starting new work; a completed workflow may already own it.+ const inputs =+ preparedInputs === undefined+ ? await this.#prepareLocalInputs(repository, options, signal)+ : {+ ...preparedInputs,+ outputDir: await prepareScanOutputDir(+ options,+ preparedInputs.protectedRoots,+ ),+ };const {repository: repo,target: normalized,@@ -1234,7 +1242,10 @@ export class CodexSecurity {outputDir: requestedOutput,protectedRoot,stateDirectory,- } = await this.#validateLocalInputs(repository, options, signal);+ deepScanConfiguration,+ prompts,+ } = inputs;+ options = { ...options, ...prompts };checkOpen();let temporaryRoot: string | undefined;if (@@ -1280,13 +1291,11 @@ export class CodexSecurity {? runtime.deepScanConfigPath ??join(runtimeHome, "codex-security", "config.toml"): undefined;- if (deepScanConfigPath !== undefined) {- await prepareDeepScanConfig(- deepScanConfigPath,- this.#dependencies.environment,- options,- signal,- );+ if (+ deepScanConfigPath !== undefined &&+ deepScanConfiguration !== undefined+ ) {+ await writeDeepScanConfig(deepScanConfigPath, deepScanConfiguration);}checkOpen();const scanOutputRoot =@@ -1540,18 +1549,20 @@ export class CodexSecurity {onError: reportTrackingError,});costTracker = tracker;- const recipe = scanRecipe(- repo,- normalized,+ const recipe = scanRecipe({+ repository: repo,+ target: normalized,mode,- expectation.repositoryRevision,- runtime.plugin.version,- { ...preflightConfig, approval_policy: approvalPolicy },- options.failureSeverity,- knowledgeBase?.sources,- options.maxCostUsd,- deepScanOptions(options),- );+ repositoryRevision: expectation.repositoryRevision,+ pluginVersion: runtime.plugin.version,+ config: { ...preflightConfig, approval_policy: approvalPolicy },+ failOnSeverity: options.failureSeverity,+ knowledgeBasePaths: knowledgeBase?.sources,+ maxCostUsd: options.maxCostUsd,+ deepScan: deepScanConfiguration?.settings,+ auth: options.auth,+ });+ if (options.scanPrompt?.trim()) recipe["requiresScanPrompt"] = true;if (options.safetyIdentifier !== undefined)recipe["safetyIdentifier"] = options.safetyIdentifier;if (options.postScanPrompt !== undefined)@@ -3005,7 +3016,7 @@ export class CodexSecurity {...sources.gitMetadataPaths,]),];- const inputs = await this.#validateLocalInputs(+ const inputs = await this.#prepareLocalInputs(target.repository,{auth: options.auth,@@ -3034,7 +3045,8 @@ export class CodexSecurity {this.#abortController.signal,...(options.signal ? [options.signal] : []),]);- const local = await this.#validateLocalInputs(repository, options, signal);+ const local = await this.#prepareLocalInputs(repository, options, signal);+ options = { ...options, ...local.prompts };const temporaryRoot = await realpath(tmpdir());requireOutputOutsideRepository(local.protectedRoot,@@ -3145,17 +3157,18 @@ export class CodexSecurity {],JSON.stringify({recipe: {- ...scanRecipe(- local.repository,- local.target,- local.mode,- revision,- plugin.version,- { model },- options.failureSeverity,- options.knowledgeBasePaths,- options.maxCostUsd,- ),+ ...scanRecipe({+ repository: local.repository,+ target: local.target,+ mode: local.mode,+ repositoryRevision: revision,+ pluginVersion: plugin.version,+ config: { model },+ failOnSeverity: options.failureSeverity,+ knowledgeBasePaths: options.knowledgeBasePaths,+ maxCostUsd: options.maxCostUsd,+ auth: options.auth,+ }),mock: true,},userContext: options.scanPrompt,@@ -3268,7 +3281,7 @@ export class CodexSecurity {}}- async #validateLocalInputs(+ async #prepareLocalInputs(repository: string,options: ScanOptions,signal?: AbortSignal,@@ -3291,13 +3304,15 @@ export class CodexSecurity {options.mock &&(options.mode === "deep" ||options.validationPrompt !== undefined ||- options.postScanPrompt !== undefined)+ options.postScanPrompt !== undefined ||+ options.validationPromptFile !== undefined ||+ options.postScanPromptFile !== undefined)) {throw new CodexSecurityError("Mock scans support Standard mode without custom validation or post-scan prompts; those workflows require model calls.",);}- deepScanOptions(options);+ const deep = deepScanOptions(options);const identifier = options.safetyIdentifier;if (identifier !== undefined &&@@ -3312,7 +3327,7 @@ export class CodexSecurity {}if (options.maxCostUsd !== undefined &&- (!Number.isFinite(options.maxCostUsd) || options.maxCostUsd <= 0)+ !ScanSettingsSchema.shape.maxCostUsd.safeParse(options.maxCostUsd).success) {throw new CodexSecurityError("The scan cost limit must be a positive USD amount.",@@ -3325,12 +3340,13 @@ export class CodexSecurity {validatedGitEnvironment(this.#dependencies.environment);const normalized = await normalizeTarget(repo, requestedTarget, signal);throwIfAborted(signal);- const mode = options.mode ?? "standard";+ const mode = options.mode ?? DEFAULT_SCAN_MODE;validateMode(normalized, mode);- if (options.validationPrompt !== undefined) {+ const prompts = await resolveScanPrompts(options, repo);+ if (prompts.validationPrompt !== undefined) {if (- typeof options.validationPrompt !== "string" ||- !options.validationPrompt.trim()+ typeof prompts.validationPrompt !== "string" ||+ !prompts.validationPrompt.trim()) {throw new CodexSecurityError("The validation prompt must not be empty.",@@ -3348,13 +3364,7 @@ export class CodexSecurity {(await enclosingGitWorktreeRoot(repo, signal)) ??repo;protectedRoots ??= [protectedRoot];- const requestedOutput = await validateOutputDir(- options.outputDir,- options.resumeScanId !== undefined || options.archiveExisting,- );- if (requestedOutput !== null) {- requireOutputOutsideRepositories(protectedRoots, requestedOutput);- }+ const requestedOutput = await prepareScanOutputDir(options, protectedRoots);const stateDirectory = codexSecurityStateDirectory(this.#dependencies.environment,);@@ -3382,6 +3392,26 @@ export class CodexSecurity {protectedRoot,protectedRoots,stateDirectory,+ prompts,+ ...(mode === "deep"+ ? {+ deepScanConfiguration: await resolveDeepScanConfig(+ deep,+ join(+ expandHome(+ environmentValue(+ this.#dependencies.environment,+ "CODEX_HOME",+ ) ?? join(homedir(), ".codex"),+ this.#dependencies.environment,+ ),+ "codex-security",+ "config.toml",+ ),+ signal,+ ),+ }+ : {}),};}@@ -3517,94 +3547,6 @@ export async function listRepositoryFindings(return findings;}-function deepScanOptions(options: ScanOptions): DeepScanOptions {- const selected: DeepScanOptions = {};- for (const [name, , minimum] of DEEP_SCAN_SETTINGS) {- const value = options[name];- if (value === undefined) continue;- if ((options.mode ?? "standard") !== "deep") {- throw new CodexSecurityError("Deep scan settings require deep mode.");- }- if (name === "maxTimeHours") {- if (!Number.isFinite(value) || value <= 0 || value > 96) {- throw new CodexSecurityError(- "Deep scan maxTimeHours must be a positive number no greater than 96.",- );- }- } else if (!Number.isSafeInteger(value) || value < minimum) {- throw new CodexSecurityError(- `Deep scan ${name} must be ${minimum === 0 ? "a non-negative" : "a positive"} integer.`,- );- }- selected[name] = value;- }- return selected;-}--async function prepareDeepScanConfig(- destination: string,- environment: ProcessEnvironment,- options: DeepScanOptions,- signal: AbortSignal,-): Promise<void> {- const ambientHome = expandHome(- environmentValue(environment, "CODEX_HOME") ?? join(homedir(), ".codex"),- environment,- );- const source = join(ambientHome, "codex-security", "config.toml");- let configured: TomlTable = {};- try {- configured = parseToml(- await readFile(source, { encoding: "utf8", signal }),- );- } catch (error) {- if (!isRecord(error) || error["code"] !== "ENOENT") {- throw new CodexSecurityError(- `Cannot read Codex Security configuration at ${source}.`,- { cause: error },- );- }- }- const existing = configured["deep_scan"];- if (existing !== undefined && !isRecord(existing)) {- throw new CodexSecurityError(- `Codex Security configuration [deep_scan] at ${source} must be a TOML table.`,- );- }- const overrides: TomlTable = {};- for (const [name, key] of DEEP_SCAN_SETTINGS) {- const value = options[name];- if (value !== undefined) overrides[key] = value;- }- const sharedConfig = await sameExistingPath(source, destination);- const hasOverrides = Object.keys(overrides).length > 0;- if (existing === undefined && !hasOverrides) {- if (!sharedConfig) {- await rm(destination, { force: true });- }- return;- }- if (sharedConfig && !hasOverrides) return;- await mkdir(dirname(destination), { recursive: true, mode: 0o700 });- await writeFile(- destination,- stringifyToml({- ...configured,- deep_scan: { ...existing, ...overrides },- }),- { mode: 0o600, signal },- );-}--async function sameExistingPath(left: string, right: string): Promise<boolean> {- if (left === right) return true;- const [canonicalLeft, canonicalRight] = await Promise.all([- realpath(left).catch(() => null),- realpath(right).catch(() => null),- ]);- return canonicalLeft !== null && canonicalLeft === canonicalRight;-}-export function createSecurity(config: CodexSecurityConfig = {},): CodexSecurity {@@ -4109,18 +4051,31 @@ function targetInstruction(target: NormalizedTarget, python: string): string {return `Scan target: staged and unstaged working-tree changes against ${target.base}.`;}-function scanRecipe(- repository: string,- target: NormalizedTarget,- mode: ScanMode,- repositoryRevision: string | null,- pluginVersion: string,- preflightConfig: JsonObject,- failOnSeverity?: SeverityLevel,- knowledgeBasePaths?: string[],- maxCostUsd?: number,- deepScan?: DeepScanOptions,-): JsonObject {+function scanRecipe({+ repository,+ target,+ mode,+ repositoryRevision,+ pluginVersion,+ config,+ failOnSeverity,+ knowledgeBasePaths,+ maxCostUsd,+ deepScan,+ auth,+}: {+ repository: string;+ target: NormalizedTarget;+ mode: ScanMode;+ repositoryRevision: string | null;+ pluginVersion: string;+ config: JsonObject;+ failOnSeverity?: SeverityLevel;+ knowledgeBasePaths?: string[];+ maxCostUsd?: number;+ deepScan?: Required<DeepScanOptions>;+ auth?: ScanAuthMode;+}): JsonObject {return {repository,target: {@@ -4134,16 +4089,29 @@ function scanRecipe(mode,...(repositoryRevision === null ? {} : { repositoryRevision }),pluginVersion,- config: preflightConfig,+ config,+ ...(auth === undefined ? {} : { auth }),...(failOnSeverity === undefined ? {} : { failOnSeverity }),...(knowledgeBasePaths === undefined ? {} : { knowledgeBasePaths }),...(maxCostUsd === undefined ? {} : { maxCostUsd }),- ...(deepScan === undefined || Object.keys(deepScan).length === 0+ ...(deepScan === undefined? {}- : { deepScan: { ...deepScan } }),+ : { deepScan: { ...deepScan }, deepScanResolved: true }),};}+async function prepareScanOutputDir(+ options: Pick<ScanOptions, "outputDir" | "archiveExisting" | "resumeScanId">,+ protectedRoots: readonly string[],+): Promise<string | null> {+ const output = await validateOutputDir(+ options.outputDir,+ options.resumeScanId !== undefined || options.archiveExisting,+ );+ if (output !== null) requireOutputOutsideRepositories(protectedRoots, output);+ return output;+}+function validateScanCostLimit(maxCostUsd: number | undefined,model: string,@@ -4231,7 +4199,7 @@ async function collectResult(export function scanAuthentication(environment: ProcessEnvironment,- auth: ScanAuthMode = "auto",+ auth: ScanAuthMode = DEFAULT_SCAN_AUTH,modelProvider?: unknown,commandAuth = false,): ScanAuthentication {diff --git a/sdk/typescript/src/bulk-scan-discovery.ts b/sdk/typescript/src/bulk-scan-discovery.tsindex ef2511df2..3558bccf6 100644--- a/sdk/typescript/src/bulk-scan-discovery.ts+++ b/sdk/typescript/src/bulk-scan-discovery.ts@@ -120,6 +120,7 @@ export function createBulkScanDiscoveryDependencies(options: {export async function runBulkScanWizard(dependencies: BulkScanDiscoveryDependencies,signal?: AbortSignal,+ defaultOutputDir = "./security-scans",): Promise<BulkScanWizardResult | null> {const { prompt } = dependencies;if (!prompt.isInteractive()) {@@ -153,7 +154,7 @@ export async function runBulkScanWizard(expandHome(await prompt.input("Where should scan results be saved?",- "./security-scans",+ defaultOutputDir,),),);diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex 881293d28..e0f904c0f 100644--- a/sdk/typescript/src/cli.ts+++ b/sdk/typescript/src/cli.ts@@ -13,7 +13,6 @@ import {existsSync,lstatSync,realpathSync,- type BigIntStats,writeSync,} from "node:fs";import {@@ -21,7 +20,6 @@ import {lstat,mkdir,mkdtemp,- open,readFile,realpath,rm,@@ -36,7 +34,6 @@ import {parse,relative,resolve,- sep,win32,} from "node:path";import { cwd } from "node:process";@@ -100,11 +97,13 @@ import {DEFAULT_CODEX_CONFIG,EXTERNAL_CODEX_PROVIDERS,isExternalModelProvider,+ mergeCodexOverrides,hasCommandAuth,inlineToml,modelProviderConfigOverride,resolveCommandAuthConfig,mergedCodexConfig,+ scanModel,scanModelConfiguration,scanModelProvider,writeCodexConfig,@@ -115,6 +114,11 @@ import {} from "./config.js";import { formatUsd, type ScanCost } from "./cost.js";import { formatScanCostTokens, formatTokenUsage } from "./cost-model.js";+import {+ isOutsidePath,+ readRegularInputFile,+ resolveScanPrompts,+} from "./prompt-files.js";import {CodexSecurityError,AuthenticationRequiredError,@@ -215,7 +219,6 @@ import {abortable,DiffTarget,enclosingGitWorktreeRoots,- type ScanMode,type ScanTarget,} from "./targets.js";import { resolveTrustedExecutable } from "./trusted-executable.js";@@ -230,6 +233,34 @@ import {VERSION,} from "./version.js";+import {+ readProjectConfig,+ resolveScanSettings,+ projectScopeTarget,+ configurationSources,+ projectConfigStarter,+ type ConfigurationSource,+ type ScopeProvenanceKey,+ type ProjectConfigProvenance,+} from "./project-config.js";+import type { ProjectScope } from "./project-config-schema.js";+import { resolveConfigPath, type AbsolutePath } from "./config-path.js";+import { resolveDeepScanConfig } from "./deep-config.js";+import { SCAN_MODES } from "./scan-modes.js";+import {+ DEEP_SCAN_SETTINGS,+ DeepScanSettingsSchema,+ DEFAULT_SCAN_AUTH,+ FailureSeveritySchema,+ REPORTABLE_SEVERITIES,+ SCAN_SEVERITIES,+ ScanSettingsSchema,+ pickScanSettings,+ meetsSeverity,+ type FailureSeverity,+ type ResolvedScanSettings,+} from "./scan-settings.js";+const PROGRESS_REFRESH_MILLISECONDS = 1_000;const execFile = promisify(execFileCallback);const WINDOWS_NETWORK_PATH = /^[\\/]{2}/u;@@ -253,18 +284,8 @@ type Writable = Pick<NodeJS.WriteStream, "write"> & {readonly columns?: number;};type SignalName = "SIGINT" | "SIGTERM";-type FailureSeverity = Exclude<SeverityLevel, "informational">;-const REPORTABLE_SEVERITIES: readonly FailureSeverity[] = [- "critical",- "high",- "medium",- "low",-];-const DISPLAY_SEVERITIES: readonly SeverityLevel[] = [- ...REPORTABLE_SEVERITIES,- "informational",-];+const DISPLAY_SEVERITIES: readonly SeverityLevel[] = SCAN_SEVERITIES;const MODEL_REASONING_EFFORTS = ["minimal","low",@@ -282,12 +303,19 @@ const PLUGIN_PATH_DESCRIPTION ="Codex Security plugin directory or ZIP (default: bundled plugin).";const PYTHON_PATH_DESCRIPTION ="Python interpreter (default: PYTHON or automatic discovery).";+const PROJECT_CONFIG_OPTION = optionValue("--config")+ .optional()+ .describe(+ "Load a trusted YAML/JSON file (default: CODEX_SECURITY_PROJECT_CONFIG, otherwise no file).",+ );const EXPORT_DEFAULT_OUTPUTS = {csv: "findings.csv",json: "findings.json",sarif: "results.sarif",} as const;const VALUE_OPTIONS = new Set([+ "--config",+ "-c","--port","--workflow-id","--concurrency",@@ -902,161 +930,36 @@ function effortOption() {);}-const DEEP_SCAN_OPTION_SCHEMAS = {- workers: z- .number()- .int()- .positive()- .optional()- .describe("Maximum concurrent deep-scan discovery workers."),- subagents: z- .number()- .int()- .nonnegative()- .optional()- .describe("Subagents available to each deep-scan worker."),- stopAfterNoNew: z- .number()- .int()- .positive()- .optional()- .describe("Stop after this many runs find no new issues."),- maxDiscoveryRuns: z- .number()- .int()- .positive()- .optional()- .describe("Maximum deep-scan discovery runs."),- maxTimeHours: z- .number()- .positive()- .max(96)- .optional()- .describe("Maximum deep-scan discovery hours (default: 96; maximum: 96)."),-};--async function readPromptFiles(- directory: string,- scanPromptFile?: string,- postScanPromptFile?: string,- repository = directory,- validationPromptFile?: string,-): Promise<- Pick<ScanOptions, "scanPrompt" | "validationPrompt" | "postScanPrompt">-> {- const [scanPrompt, postScanPrompt, validationPrompt] = await Promise.all([- scanPromptFile === undefined- ? undefined- : readRegularInputFile(- resolveCliPath(directory, scanPromptFile),- repository,- ),- postScanPromptFile === undefined- ? undefined- : readRegularInputFile(- resolveCliPath(directory, postScanPromptFile),- repository,- ),- validationPromptFile === undefined- ? undefined- : readRegularInputFile(- resolveCliPath(directory, validationPromptFile),- repository,- ),- ]);- if (validationPrompt !== undefined && !validationPrompt.trim()) {- throw new CodexSecurityError("The validation prompt must not be empty.");- }- return {- ...(scanPrompt?.trim() ? { scanPrompt } : {}),- ...(validationPrompt === undefined ? {} : { validationPrompt }),- ...(postScanPrompt?.trim() ? { postScanPrompt } : {}),- };-}--async function readRegularInputFile(- path: string,- repository: string,- metadata?: Pick<BigIntStats, "isFile" | "dev" | "ino">,-): Promise<string> {- const selected = metadata ?? (await lstat(path, { bigint: true }));- if (!selected.isFile()) {- throw new CodexSecurityError("Input files must be regular files.");- }- const canonicalRepository = await realpath(repository);- const canonicalParent = await realpath(dirname(path));- if (isOutsidePath(relative(canonicalRepository, canonicalParent))) {- for (let ancestor = dirname(path); ; ancestor = dirname(ancestor)) {- if (- !isOutsidePath(relative(canonicalRepository, await realpath(ancestor)))- ) {- throw new CodexSecurityError(- "Input files must not follow repository directory links outside the selected repository.",- );- }- if (dirname(ancestor) === ancestor) {- break;- }- }- }- const file = await open(- join(canonicalParent, basename(path)),- constants.O_RDONLY |- (constants.O_NOFOLLOW ?? 0) |- (constants.O_NONBLOCK ?? 0),- );- try {- const opened = await file.stat({ bigint: true });- if (- !opened.isFile() ||- opened.dev !== selected.dev ||- opened.ino !== selected.ino- ) {- throw new CodexSecurityError("Input files must remain regular files.");- }- return await file.readFile({ encoding: "utf8" });- } finally {- await file.close();- }-}--export function resolveCliPath(directory: string, value: string): string {- return resolve(directory, expandHome(value));+type DeepCliOptionName = Extract<+ (typeof DEEP_SCAN_SETTINGS)[number],+ readonly [string, string, string, string]+>[0];+const DEEP_SCAN_OPTION_SCHEMAS = Object.fromEntries(+ DEEP_SCAN_SETTINGS.filter(([, , , flag]) => flag !== null).map(([name]) => [+ name,+ DeepScanSettingsSchema.shape[name],+ ]),+) as Pick<typeof DeepScanSettingsSchema.shape, DeepCliOptionName>;++export function resolveCliPath(directory: string, value: string): AbsolutePath {+ return resolveConfigPath(directory, value);}-interface ScanArguments extends DeepScanOptions {+interface ScanArguments extends ResolvedScanSettings {+ codexOverrides: JsonObject;+ projectConfig?: ProjectConfigProvenance;resumeScanId?: string;mock?: boolean;workflowId?: string;- auth?: ScanAuthMode;safetyIdentifier?: string;verbose?: boolean;repository?: string;- paths: string[];- knowledgeBasePaths: string[];- scanPromptFile?: string;- validationPromptFile?: string;- postScanPromptFile?: string;- postScanPrompt?: string;- diff?: string;- workingTree: boolean;- head?: string;- base?: string;- mode: ScanMode;- model?: string;- effort?: ScanReasoningEffort;- provider?: "openai" | "amazon-bedrock" | ExternalModelProvider;- outputDir?: string;archiveExisting: boolean;pluginPath?: string;pythonPath?: string;- codex: string[];- codexOverrides?: JsonObject;- failOnSeverity?: FailureSeverity;patch?: boolean;patchSeverity?: FailureSeverity;createPr?: boolean;- maxCostUsd?: number;headless?: boolean;dryRun: boolean;parentScanId?: string;@@ -2231,12 +2134,22 @@ export async function main("The workbench returned invalid scan resume context.",);}- scanArguments = scanArgumentsFromRecipe(+ scanArguments = await prepareScanArgumentsFromRecipe(saved["recipe"],saved["scanId"],+ {+ scanPrompt:+ typeof saved["userContext"] === "string"+ ? saved["userContext"]+ : undefined,+ },+ dependencies.currentDirectory(),);scanArguments.resumeScanId = saved["scanId"];- scanArguments.outputDir = saved["scanDir"];+ scanArguments.outputDir = resolveCliPath(+ dependencies.currentDirectory(),+ saved["scanDir"],+ );scanArguments.parentScanId = undefined;// Resume uses the installed engine with the saved recipe and checkpoints.scanArguments.expectedPluginVersion = undefined;@@ -2275,6 +2188,11 @@ export async function main(.describe("Saved scan identifier (default: latest completed scan)."),}),options: z.object({+ scanPromptFile: optionValue("--scan-prompt-file")+ .optional()+ .describe(+ "Supply additional scan instructions; required when the saved scan used them.",+ ),validationPromptFile: optionValue("--validation-prompt-file").optional().describe(@@ -2302,9 +2220,16 @@ export async function main(recipe["import"] !== undefined &&isJsonObject(recipe["import"])) {- if (options.validationPromptFile !== undefined) {+ if (+ options.validationPromptFile !== undefined ||+ options.scanPromptFile !== undefined+ ) {+ const option =+ options.validationPromptFile !== undefined+ ? "--validation-prompt-file"+ : "--scan-prompt-file";throw new CodexSecurityError(- "--validation-prompt-file is not supported when rerunning an imported scan; imports do not perform security analysis.",+ `${option} is not supported when rerunning an imported scan; imports do not perform security analysis.`,);}const imported = recipe["import"];@@ -2334,10 +2259,26 @@ export async function main(}return outcome.data;}- scanArguments = scanArgumentsFromRecipe(+ scanArguments = await prepareScanArgumentsFromRecipe(recipe,scanId,- options.validationPromptFile,+ {+ scanPromptFile:+ options.scanPromptFile === undefined+ ? undefined+ : resolveCliPath(+ dependencies.currentDirectory(),+ options.scanPromptFile,+ ),+ validationPromptFile:+ options.validationPromptFile === undefined+ ? undefined+ : resolveCliPath(+ dependencies.currentDirectory(),+ options.validationPromptFile,+ ),+ },+ dependencies.currentDirectory(),);scanArguments.verbose = options.verbose;} catch (error) {@@ -3388,6 +3329,7 @@ export async function main("Use ./import to scan a repository named import.",destructive: true,mcp: false,+ alias: { config: "c" },args: z.object({repository: z.string()@@ -3396,17 +3338,15 @@ export async function main(}),options: z.object({+ config: PROJECT_CONFIG_OPTION,workflowId: optionValue("--workflow-id").optional().describe("Reuse completed work in the named local findings workflow.",),- auth: z- .enum(SCAN_AUTH_MODES)- .default("auto")- .describe(- "Select ChatGPT, OPENAI_API_KEY/CODEX_API_KEY, or automatic authentication.",- ),+ auth: ScanSettingsSchema.shape.auth.describe(+ "Select ChatGPT, OPENAI_API_KEY/CODEX_API_KEY, or automatic authentication (default: auto).",+ ),verbose: z.boolean().default(false)@@ -3418,13 +3358,15 @@ export async function main(),path: z.array(optionValue("--path"))- .default([])+ .optional()+ .meta({ default: [] }).describe("Scan only PATH; repeat for multiple repository-relative paths.",),knowledgeBase: z.array(optionValue("--knowledge-base"))- .default([])+ .optional()+ .meta({ default: [] }).describe("Add security-context files or directories; repeat for multiple paths.",),@@ -3444,7 +3386,8 @@ export async function main(.describe("Scan committed Git changes from BASE to --head."),workingTree: z.boolean()- .default(false)+ .optional()+ .meta({ default: false }).describe("Scan staged and unstaged changes against --base."),head: optionValue("--head").optional()@@ -3452,10 +3395,9 @@ export async function main(base: optionValue("--base").optional().describe("Git base ref for --working-tree (default: HEAD)."),- mode: z- .enum(["standard", "deep"])- .default("standard")- .describe("Scan mode; deep supports repository and path targets."),+ mode: ScanSettingsSchema.shape.mode.describe(+ "Scan mode (default: standard); deep supports repository and path targets.",+ ),...DEEP_SCAN_OPTION_SCHEMAS,model: optionValue("--model").optional()@@ -3483,10 +3425,9 @@ export async function main(.array(optionValue("--codex")).default([]).describe(CODEX_OVERRIDE_DESCRIPTION),- failOnSeverity: z- .enum(REPORTABLE_SEVERITIES)- .optional()- .describe("Exit 1 for findings at or above LEVEL."),+ failOnSeverity: FailureSeveritySchema.optional().describe(+ "Exit 1 for findings at or above LEVEL.",+ ),patch: z.boolean().default(false)@@ -3496,13 +3437,9 @@ export async function main(.optional().describe("Patch findings at or above LEVEL; requires --patch."),createPr: CREATE_PR_OPTION,- maxCost: z- .number()- .positive()- .optional()- .describe(- "Stop above AMOUNT in estimated USD; the dashboard offers increases near the limit.",- ),+ maxCost: ScanSettingsSchema.shape.maxCostUsd.describe(+ "Stop above AMOUNT in estimated USD; the dashboard offers increases near the limit.",+ ),headless: z.boolean().default(false)@@ -3520,32 +3457,6 @@ export async function main("Save synthetic Standard scan findings without calling an LLM.",),})- .refine(- (options) =>- Number(options.path.length > 0) +- Number(options.diff !== undefined) +- Number(options.workingTree) <=- 1,- {- message:- "--path, --diff, and --working-tree are mutually exclusive.",- },- )- .refine(- (options) => options.head === undefined || options.diff !== undefined,- { message: "--head requires --diff." },- )- .refine(- (options) => options.base === undefined || options.workingTree,- {- message: "--base requires --working-tree.",- },- )- .refine(- (options) =>- !options.archiveExisting || options.outputDir !== undefined,- { message: "--archive-existing requires --output-dir." },- ).refine((options) => options.patchSeverity === undefined || options.patch,{@@ -3563,19 +3474,13 @@ export async function main({message: "--mock cannot be combined with --dry-run or --patch.",},- )- .refine(- (options) =>- options.mode === "deep" ||- (options.workers === undefined &&- options.subagents === undefined &&- options.stopAfterNoNew === undefined &&- options.maxDiscoveryRuns === undefined &&- options.maxTimeHours === undefined),- { message: "Deep scan settings require --mode deep." },),examples: [{ args: { repository: "." } },+ {+ args: { repository: "." },+ options: { config: "codex-security.yaml" },+ },{ args: { repository: "." }, options: { model: "gpt-5.6-terra" } },{args: { repository: "." },@@ -3601,49 +3506,86 @@ export async function main(exitCode = 2;return;}- const outcome = await runScan(- {- auth: options.auth,- workflowId: options.workflowId,- safetyIdentifier: options.safetyIdentifier,- verbose: options.verbose,- repository: args.repository,+ let outcome: ScanOutcome;+ try {+ const directory = dependencies.currentDirectory();+ const project = await selectedProjectConfig(+ options.config,+ dependencies,+ );+ const scope = resolveCliScope(project?.input.scan?.scope, {paths: options.path,- knowledgeBasePaths: options.knowledgeBase,- scanPromptFile: options.scanPromptFile,- validationPromptFile: options.validationPromptFile,- postScanPromptFile: options.postScanPromptFile,diff: options.diff,workingTree: options.workingTree,head: options.head,base: options.base,- mode: options.mode,- workers: options.workers,- subagents: options.subagents,- stopAfterNoNew: options.stopAfterNoNew,- maxDiscoveryRuns: options.maxDiscoveryRuns,- maxTimeHours: options.maxTimeHours,- model: options.model,- effort: options.effort,- provider: options.provider,- outputDir: options.outputDir,- archiveExisting: options.archiveExisting,- pluginPath: options.pluginPath,- pythonPath: options.python,- codex: options.codex,- failOnSeverity: options.failOnSeverity,- patch: options.patch,- patchSeverity: options.patchSeverity,- createPr: options.createPr,- maxCostUsd: options.maxCost,- headless: options.headless,- dryRun: options.dryRun,- mock: options.mock,- },- errorOutput,- dependencies,- format !== "json" && format !== "jsonl",- );+ });+ const {+ config,+ options: settings,+ projectConfig: provenance,+ } = resolveScanSettings(+ project,+ {+ auth: options.auth,+ target: scope.target,+ knowledgeBasePaths: options.knowledgeBase,+ scanPromptFile: options.scanPromptFile,+ validationPromptFile: options.validationPromptFile,+ postScanPromptFile: options.postScanPromptFile,+ mode: options.mode,+ workers: options.workers,+ subagents: options.subagents,+ stopAfterNoNew: options.stopAfterNoNew,+ maxDiscoveryRuns: options.maxDiscoveryRuns,+ maxTimeHours: options.maxTimeHours,+ outputDir: options.outputDir,+ failureSeverity: options.failOnSeverity,+ maxCostUsd: options.maxCost,+ codexOverrides: parseCodexOverrides(+ options.codex,+ options.model,+ options.effort,+ options.provider,+ project?.input.codex,+ ),+ },+ directory,+ scope.sources,+ );+ if (options.archiveExisting && settings.outputDir === undefined) {+ throw new CodexSecurityError(+ "--archive-existing requires --output-dir.",+ );+ }+ outcome = await runScan(+ {+ ...settings,+ codexOverrides: config.codexOverrides,+ projectConfig: provenance,+ workflowId: options.workflowId,+ safetyIdentifier: options.safetyIdentifier,+ verbose: options.verbose,+ repository: args.repository,+ archiveExisting: options.archiveExisting,+ pluginPath: options.pluginPath,+ pythonPath: options.python,+ patch: options.patch,+ patchSeverity: options.patchSeverity,+ createPr: options.createPr,+ headless: options.headless,+ dryRun: options.dryRun,+ mock: options.mock,+ },+ errorOutput,+ dependencies,+ format !== "json" && format !== "jsonl",+ );+ } catch (error) {+ const message = errorMessage(error);+ errorOutput.write(`${message}\n`);+ outcome = { exitCode: 2, error: message };+ }exitCode = outcome.exitCode;if (outcome.error !== undefined) {return incurError({@@ -3943,6 +3885,7 @@ export async function main("Run standard scans for project components and combine the results.",destructive: true,mcp: false,+ alias: { config: "c" },args: z.object({repository: z.string()@@ -3952,12 +3895,10 @@ export async function main(}),options: z.object({- auth: z- .enum(SCAN_AUTH_MODES)- .default("auto")- .describe(- "Select ChatGPT, OPENAI_API_KEY/CODEX_API_KEY, or automatic authentication.",- ),+ config: PROJECT_CONFIG_OPTION,+ auth: ScanSettingsSchema.shape.auth.describe(+ "Select ChatGPT, OPENAI_API_KEY/CODEX_API_KEY, or automatic authentication.",+ ),component: z.array(optionValue("--component")).default([])@@ -3981,18 +3922,21 @@ export async function main(.describe("Print status lines instead of the interactive dashboard.",),- outputDir: optionValue("--output-dir").describe(- "Empty results directory outside the repository.",- ),+ outputDir: optionValue("--output-dir")+ .optional()+ .describe("Empty results directory outside the repository."),workers: z.number().int().positive().default(4)- .describe("Concurrent standard component scans."),+ .describe(+ "Concurrent component scans; deep workers are configured per scan.",+ ),knowledgeBase: z.array(optionValue("--knowledge-base"))- .default([])+ .optional()+ .meta({ default: [] }).describe("Read shared security docs for every component."),scanPromptFile: optionValue("--scan-prompt-file").optional()@@ -4057,15 +4001,38 @@ export async function main(try {const directory = dependencies.currentDirectory();const repository = resolveCliPath(directory, args.repository ?? ".");+ const project = await selectedProjectConfig(+ options.config,+ dependencies,+ );+ const resolved = resolveScanSettings(+ project,+ {+ auth: options.auth,+ outputDir: options.outputDir,+ knowledgeBasePaths: options.knowledgeBase,+ scanPromptFile: options.scanPromptFile,+ postScanPromptFile: options.postScanPromptFile,+ maxCostUsd: options.maxCost,+ codexOverrides: parseCodexOverrides(+ options.codex,+ options.model,+ options.effort,+ options.provider,+ project?.input.codex,+ ),+ },+ directory,+ );+ const settings = resolved.options;+ if (settings.outputDir === undefined)+ throw new ConfigurationError(+ "--output-dir or output.directory is required for component scans.",+ );const config: CodexSecurityConfig = {+ ...resolved.config,pluginPath: options.pluginPath,pythonPath: options.python,- codexOverrides: parseCodexOverrides(- options.codex,- options.model,- options.effort,- options.provider,- ),};const components =options.componentsFile === undefined@@ -4089,7 +4056,8 @@ export async function main(repository,presentation: "components",model: scanModelConfiguration(await mergedCodexConfig(config)),- maxCostUsd: options.maxCost,+ mode: settings.mode,+ maxCostUsd: settings.maxCostUsd,clock: dependencies,color: dependencies.environment["NO_COLOR"] === undefined,sanitize: safeErrorMessage,@@ -4110,25 +4078,14 @@ export async function main(}const result = await runComponentScans({repository,- outputDir: resolveCliPath(directory, options.outputDir),+ outputDir: settings.outputDir,...(options.auto ? { auto: true } : { components }),planOnly: options.planOnly,workers: options.workers,config,scanOptions: {- auth: options.auth,- knowledgeBasePaths: options.knowledgeBase.map((path) =>- resolveCliPath(directory, path),- ),- ...(await readPromptFiles(- directory,- options.scanPromptFile,- options.postScanPromptFile,- repository,- )),- ...(options.maxCost === undefined- ? {}- : { maxCostUsd: options.maxCost }),+ ...settings,+ ...(await resolveScanPrompts(settings, repository, directory)),},createSecurity: dependencies.createSecurity,planComponents: dependencies.planComponents,@@ -4183,7 +4140,9 @@ export async function main(result.incomplete ||result.deduplication?.status === "incomplete"? 2- : 0);+ : result.policyFailed+ ? 1+ : 0);return { ...result };} catch (error) {stopDashboard();@@ -4201,6 +4160,7 @@ export async function main("Discover repositories and run resumable bulk security scans.",destructive: true,mcp: false,+ alias: { config: "c" },args: z.object({input: z.string()@@ -4211,6 +4171,7 @@ export async function main(),}),options: z.object({+ config: PROJECT_CONFIG_OPTION,recover: z.boolean().default(false)@@ -4226,7 +4187,8 @@ export async function main(),knowledgeBase: z.array(optionValue("--knowledge-base"))- .default([])+ .optional()+ .meta({ default: [] }).describe("Read shared security docs for every repository."),workers: z.number()@@ -4236,10 +4198,9 @@ export async function main(.describe("Concurrent repository scans. Per-scan Codex workers are separate.",),- mode: z- .enum(["standard", "deep"])- .default("standard")- .describe("Default scan mode for repositories without a CSV mode."),+ mode: ScanSettingsSchema.shape.mode.describe(+ "Default scan mode for repositories without a CSV mode.",+ ),scanPromptFile: optionValue("--scan-prompt-file").optional().describe("Append instructions from FILE to every scan."),@@ -4313,13 +4274,40 @@ export async function main("Bulk recovery requires the original repository CSV and --output-dir.",);}- const prompts = await readPromptFiles(- currentDirectory,- options.scanPromptFile,- options.postScanPromptFile,+ const project = await selectedProjectConfig(+ options.config,+ dependencies,+ );+ const overrides = {+ mode: options.mode,+ outputDir: options.outputDir,+ knowledgeBasePaths: options.knowledgeBase,+ scanPromptFile: options.scanPromptFile,+ validationPromptFile: options.validationPromptFile,+ postScanPromptFile: options.postScanPromptFile,+ maxCostUsd: options.maxCost,+ };+ const resolved = resolveScanSettings(+ project,+ overrides,currentDirectory,- options.validationPromptFile,);+ const settings = resolved.options;+ // A CSV row may choose a different mode; resolve the same file for both+ // modes so inactive deep defaults remain available to deep rows.+ const scanOptionsByMode =+ project === undefined+ ? undefined+ : Object.fromEntries(+ SCAN_MODES.map((mode) => [+ mode,+ resolveScanSettings(+ project,+ { ...overrides, mode },+ currentDirectory,+ ).options,+ ]),+ );let inputPath: string;let outputDir: string;let githubHost: string | undefined;@@ -4337,46 +4325,54 @@ export async function main(currentDirectory: dependencies.currentDirectory,}),controller.signal,+ settings.outputDir,);if (wizard === null) return;inputPath = wizard.inputPath;outputDir = wizard.outputDir;githubHost = wizard.githubHost;} else {- if (options.outputDir === undefined) {+ if (settings.outputDir === undefined) {throw new Error("--output-dir is required with a repository CSV.",);}inputPath = resolveCliPath(currentDirectory, args.input);- outputDir = resolveCliPath(currentDirectory, options.outputDir);+ outputDir = settings.outputDir;}const result = await runMultiscan({inputPath,outputDir,...(githubHost === undefined ? {} : { githubHost }),workers: options.workers,- mode: options.mode,+ mode: settings.mode,maxAttempts: options.maxAttempts,- ...(options.maxCost === undefined+ ...(settings.maxCostUsd === undefined? {}- : { maxCostUsd: options.maxCost }),- knowledgeBasePaths: options.knowledgeBase,- ...prompts,+ : { maxCostUsd: settings.maxCostUsd }),+ knowledgeBasePaths: settings.knowledgeBasePaths,+ scanOptionsByMode,+ scanPromptFile: settings.scanPromptFile,+ validationPromptFile: settings.validationPromptFile,+ postScanPromptFile: settings.postScanPromptFile,config: {+ codexOverrides: mergeCodexOverrides(+ resolved.config.codexOverrides,+ parseCodexOverrides(+ options.codex,+ options.model,+ options.effort,+ options.provider,+ project?.input.codex,+ ),+ ),pluginPath: options.pluginPath,pythonPath: options.python,- codexOverrides: parseCodexOverrides(- options.codex,- options.model,- options.effort,- options.provider,- ),},createSecurity: dependencies.createSecurity,...(options.recover? {- recoverScan: async (scanDir: string) => {+ recoverScan: async (scanDir, prompts) => {const history = await dependencies.runWorkbench(["list-scans", "--scan-root", scanDir],undefined,@@ -4395,6 +4391,7 @@ export async function main(});return {coverage: contract.coverage,+ findings: contract.findings,cost:(scan["cost"] as unknown as ScanCost | undefined) ??null,@@ -4433,9 +4430,16 @@ export async function main();return undefined;}- const recipe = scanArgumentsFromRecipe(+ const recipe = await prepareScanArgumentsFromRecipe(saved["recipe"],scan.scanId,+ {+ scanPrompt:+ typeof saved["userContext"] === "string"+ ? saved["userContext"]+ : undefined,+ },+ currentDirectory,);const security = dependencies.createSecurity({pluginPath: options.pluginPath,@@ -4444,18 +4448,9 @@ export async function main(});try {return await security.run(recipe.repository!, {+ ...pickScanSettings(recipe),resumeScanId: scan.scanId,outputDir: scanDir,- mode: recipe.mode,- target: targetFromArguments(recipe),- knowledgeBasePaths: recipe.knowledgeBasePaths,- workers: recipe.workers,- subagents: recipe.subagents,- stopAfterNoNew: recipe.stopAfterNoNew,- maxDiscoveryRuns: recipe.maxDiscoveryRuns,- maxTimeHours: recipe.maxTimeHours,- maxCostUsd: recipe.maxCostUsd,- failureSeverity: recipe.failOnSeverity,safetyIdentifier: recipe.safetyIdentifier,postScanPrompt:recipe.postScanPrompt ?? prompts.postScanPrompt,@@ -4477,7 +4472,11 @@ export async function main(});exitCode =interruptedExitCode() ??- (result.failed > 0 || result.incomplete > 0 ? 2 : 0);+ (result.failed > 0 || result.incomplete > 0+ ? 2+ : result.policyFailed+ ? 1+ : 0);return { ...result };} catch (error) {exitCode =@@ -5257,6 +5256,37 @@ export async function main(}},})+ .command("init", {+ description:+ "Write a starter project configuration without overwriting an existing file.",+ destructive: true,+ mcp: false,+ args: z.object({+ file: z+ .string()+ .min(1)+ .optional()+ .describe("YAML or JSON destination (default: codex-security.yaml)."),+ }),+ output: z.object({ path: z.string() }).optional(),+ async run({ args }) {+ try {+ const directory = dependencies.currentDirectory();+ const path = resolveCliPath(+ directory,+ args.file ?? "codex-security.yaml",+ );+ await writeFile(path, projectConfigStarter(path, directory), {+ flag: "wx",+ mode: 0o600,+ });+ return { path };+ } catch (error) {+ exitCode = 2;+ errorOutput.write(`codex-security: ${errorMessage(error)}\n`);+ }+ },+ }).command("feedback", {description: "Send feedback to OpenAI and return a feedback ID.",destructive: true,@@ -5332,7 +5362,10 @@ export async function main(},}).command("info", {- description: "Show read-only SDK and bundled-plugin metadata.",+ description:+ "Show SDK metadata and resolved configuration without preparing a scan.",+ alias: { config: "c" },+ options: z.object({ config: PROJECT_CONFIG_OPTION }),mcp: {annotations: {readOnlyHint: true,@@ -5352,8 +5385,31 @@ export async function main(model: z.string(),reasoningEffort: z.string(),nextStep: z.string(),+ configuration: z.record(z.string(), z.unknown()),}),- run() {+ async run({ options }) {+ const directory = dependencies.currentDirectory();+ const project = await selectedProjectConfig(+ options.config,+ dependencies,+ );+ const resolved = resolveScanSettings(project, {}, directory);+ const codex = await mergedCodexConfig(resolved.config);+ const deep =+ resolved.options.mode === "deep"+ ? await resolveDeepScanConfig(+ resolved.options,+ join(+ expandHome(+ environmentValue(dependencies.environment, "CODEX_HOME") ??+ join(homedir(), ".codex"),+ dependencies.environment,+ ),+ "codex-security",+ "config.toml",+ ),+ )+ : undefined;return {sdkVersion: VERSION,bundledPluginVersion: BUNDLED_PLUGIN_VERSION,@@ -5363,8 +5419,13 @@ export async function main(cliVersion: VERSION,codexVersion: CODEX_EXECUTABLE_VERSION,codexSdkVersion: CODEX_SDK_VERSION,- ...scanModelConfiguration(DEFAULT_CODEX_CONFIG),+ ...scanModelConfiguration(codex),nextStep: "codex-security scan . --dry-run",+ configuration: {+ ...(project?.path === undefined ? {} : { path: project.path }),+ settings: { ...resolved.options, ...deep?.settings },+ sources: configurationSources(resolved.sources, deep?.sources),+ },};},});@@ -5603,16 +5664,33 @@ function defaultListCommand(argv: readonly string[]): readonly string[] {];}-function scanArgumentsFromRecipe(+async function prepareScanArgumentsFromRecipe(recipe: JsonValue | undefined,parentScanId: string,- validationPromptFile?: string,-): ScanArguments {+ {+ scanPrompt,+ scanPromptFile,+ validationPromptFile,+ }: Pick<+ ScanArguments,+ "scanPrompt" | "scanPromptFile" | "validationPromptFile"+ >,+ directory: string,+): Promise<ScanArguments> {if (recipe === undefined || !isJsonObject(recipe)) {throw new CodexSecurityError("This scan does not have a saved launch recipe.",);}+ if (+ recipe["requiresScanPrompt"] === true &&+ scanPrompt === undefined &&+ scanPromptFile === undefined+ ) {+ throw new CodexSecurityError(+ "This scan used additional instructions. Supply --scan-prompt-file to rerun it.",+ );+ }if (recipe["validationMode"] === "custom" &&validationPromptFile === undefined@@ -5712,15 +5790,27 @@ function scanArgumentsFromRecipe("The saved scan recipe contains an invalid cost limit.",);}- const deepScan = z- .object(DEEP_SCAN_OPTION_SCHEMAS)- .optional()- .safeParse(recipe["deepScan"]);+ const deepScan = DeepScanSettingsSchema.optional().safeParse(+ recipe["deepScan"],+ );if (!deepScan.success) {throw new CodexSecurityError("The saved scan recipe contains invalid deep scan settings.",);}+ if (+ recipe["deepScanResolved"] === true &&+ DEEP_SCAN_SETTINGS.some(([name]) => deepScan.data?.[name] === undefined)+ ) {+ throw new CodexSecurityError(+ "The saved scan recipe is missing resolved deep scan settings.",+ );+ }+ const auth = z.enum(SCAN_AUTH_MODES).optional().safeParse(recipe["auth"]);+ if (!auth.success)+ throw new CodexSecurityError(+ "The saved scan recipe contains an invalid authentication choice.",+ );if (mode !== "deep" &&deepScan.data !== undefined &&@@ -5740,25 +5830,40 @@ function scanArgumentsFromRecipe("The saved scan recipe contains invalid launch settings.",);}+ const prompts = await resolveScanPrompts(+ { scanPrompt, scanPromptFile, validationPromptFile },+ repository,+ directory,+ );+ if (recipe["requiresScanPrompt"] === true && !prompts.scanPrompt?.trim()) {+ throw new CodexSecurityError(+ "This scan used additional instructions. The --scan-prompt-file must not be empty.",+ );+ }return {repository,- paths,- knowledgeBasePaths,- validationPromptFile,+ auth: auth.data ?? DEFAULT_SCAN_AUTH,+ target:+ paths.length > 0+ ? paths+ : kind === "refs"+ ? DiffTarget.refs({ base: reference!, head: head ?? "HEAD" })+ : kind === "working_tree"+ ? DiffTarget.workingTree({ base: reference ?? "HEAD" })+ : "repository",+ knowledgeBasePaths: knowledgeBasePaths.map((path) =>+ resolveCliPath(directory, path),+ ),+ ...prompts,safetyIdentifier,postScanPrompt,- diff: kind === "refs" ? reference : undefined,- workingTree: kind === "working_tree",- head: kind === "refs" ? head ?? "HEAD" : undefined,- base: kind === "working_tree" ? reference : undefined,mode,...deepScan.data,archiveExisting: false,- codex: [],codexOverrides: Object.hasOwn(config, "approval_policy")? config: { ...config, approval_policy: "never" },- failOnSeverity: threshold as FailureSeverity | undefined,+ failureSeverity: threshold as FailureSeverity | undefined,maxCostUsd,dryRun: false,parentScanId,@@ -5798,6 +5903,7 @@ function validateCliArguments("serve","feedback","info",+ "init",].includes(command)) {return undefined;@@ -5875,6 +5981,7 @@ function validateCliArguments("model","reasoningEffort","nextStep",+ "configuration",]);for (let index = 0; index < argv.length; index += 1) {const argument = argv[index]!;@@ -6053,11 +6160,6 @@ function isFindingIdentifier(value: string): boolean {return /^(?:occ|csf)_[A-Za-z0-9_-]+$/u.test(value);}-function meetsSeverity(finding: Finding, threshold: FailureSeverity): boolean {- const severity = DISPLAY_SEVERITIES.indexOf(finding.severity.level);- return severity >= 0 && severity <= REPORTABLE_SEVERITIES.indexOf(threshold);-}-async function* workbenchFindings(arguments_: readonly string[],dependencies: CliDependencies,@@ -7338,10 +7440,6 @@ function incurErrorMessage(output: string): string {}}-function isOutsidePath(path: string): boolean {- return path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path);-}-async function runExport(arguments_: ExportArguments,output: Writable,@@ -7631,7 +7729,7 @@ async function executeScan(let effectiveReasoningEffort =DEFAULT_SCAN_MODEL_CONFIGURATION.reasoningEffort;let providerOptions: SkillRunOptions = { provider: "openai" };- let auth = arguments_.auth;+ let auth: ScanAuthMode | undefined = arguments_.auth;let patchAnalyticsOverride: string | undefined;let selectedAuthentication: ScanAuthentication | null = null;let repository = "";@@ -7640,25 +7738,16 @@ async function executeScan(try {const directory = dependencies.currentDirectory();repository = arguments_.repository ?? directory;- const target = targetFromArguments(arguments_);- const prompts = await readPromptFiles(- directory,- arguments_.scanPromptFile,- arguments_.postScanPromptFile,+ const target = arguments_.target;+ const prompts = await resolveScanPrompts(+ arguments_,resolve(directory, repository),- arguments_.validationPromptFile,+ directory,);const config: CodexSecurityConfig = {pluginPath: arguments_.pluginPath,pythonPath: arguments_.pythonPath,- codexOverrides:- arguments_.codexOverrides ??- parseCodexOverrides(- arguments_.codex,- arguments_.model,- arguments_.effort,- arguments_.provider,- ),+ codexOverrides: arguments_.codexOverrides,};const selectedProfileName = config.codexOverrides?.["profile"];const effectiveConfiguration = {@@ -7719,14 +7808,14 @@ async function executeScan(mode: arguments_.mode,max_cost_usd: arguments_.maxCostUsd,target:- arguments_.paths.length > 0+ Array.isArray(target) && target.length > 0? "paths"- : arguments_.diff !== undefined+ : target instanceof DiffTarget && target.kind === "refs"? "diff"- : arguments_.workingTree+ : target instanceof DiffTarget? "working_tree": "repository",- requested_auth: auth ?? "auto",+ requested_auth: auth ?? DEFAULT_SCAN_AUTH,dry_run: arguments_.dryRun,mock: arguments_.mock,profile:@@ -7804,6 +7893,7 @@ async function executeScan();}const options: ScanOptions = {+ ...pickScanSettings(arguments_),...(arguments_.resumeScanId === undefined? {}: { resumeScanId: arguments_.resumeScanId }),@@ -7813,22 +7903,10 @@ async function executeScan(: { workflowId: arguments_.workflowId }),auth,safetyIdentifier: arguments_.safetyIdentifier,- target,- knowledgeBasePaths: arguments_.knowledgeBasePaths,...prompts,- postScanPrompt: arguments_.postScanPrompt ?? prompts.postScanPrompt,- mode: arguments_.mode,- workers: arguments_.workers,- subagents: arguments_.subagents,- stopAfterNoNew: arguments_.stopAfterNoNew,- maxDiscoveryRuns: arguments_.maxDiscoveryRuns,- maxTimeHours: arguments_.maxTimeHours,- outputDir: arguments_.outputDir,archiveExisting: arguments_.archiveExisting,parentScanId: arguments_.parentScanId,expectedPluginVersion: arguments_.expectedPluginVersion,- failureSeverity: arguments_.failOnSeverity,- maxCostUsd: arguments_.maxCostUsd,onCost: (cost, limit = maxCostUsd) => {if (limit !== maxCostUsd && limit !== undefined) {dashboard?.note(`Total cost limit increased to ${formatUsd(limit)}.`);@@ -7887,7 +7965,7 @@ async function executeScan(onAuthentication: (authentication) => {selectedAuthentication = authentication;diagnostic("authentication.selected", {- requested: auth ?? "auto",+ requested: auth ?? DEFAULT_SCAN_AUTH,method: authentication.method,source:"source" in authentication ? authentication.source : undefined,@@ -8149,7 +8227,27 @@ async function executeScan(verified: effectivePreflight.authentication.verified,});progress?.stopTimer();- return { exitCode: 0, data: { dryRun: true, ...effectivePreflight } };+ return {+ exitCode: 0,+ data: {+ dryRun: true,+ ...effectivePreflight,+ ...(arguments_.projectConfig === undefined+ ? {}+ : {+ projectConfig: {+ ...arguments_.projectConfig,+ sources: configurationSources(+ arguments_.projectConfig.sources,+ preflight.deepScanSources,+ ),+ },+ scanPromptFile: arguments_.scanPromptFile,+ validationPromptFile: arguments_.validationPromptFile,+ failOnSeverity: arguments_.failureSeverity,+ }),+ },+ };}if (result === null) {diagnostic("scan.failed", {@@ -8159,7 +8257,7 @@ async function executeScan(errorOutput.write("scan completed without a result\n");return { exitCode: 2, error: "Scan completed without a result." };}- const threshold = arguments_.failOnSeverity;+ const threshold = arguments_.failureSeverity;const findings = result.findings.findings;const actionableFindings = findings.filter((finding) =>meetsSeverity(finding, "low"),@@ -8466,8 +8564,11 @@ function scanFailureMessage(}function scanScope(arguments_: ScanArguments): string | null {- if (arguments_.paths.length > 0) {- const displayed = arguments_.paths.slice(0, 3).map((path) => {+ const paths: readonly string[] = Array.isArray(arguments_.target)+ ? arguments_.target+ : [];+ if (paths.length > 0) {+ const displayed = paths.slice(0, 3).map((path) => {const portable = path.replaceAll("\\", "/");const scoped =isAbsolute(path) ||@@ -8477,10 +8578,12 @@ function scanScope(arguments_: ScanArguments): string | null {: portable;return errorMessage(scoped.replaceAll(/[\u0000-\u001F\u007F]/gu, " "));});- return `${displayed.join(", ")}${arguments_.paths.length > displayed.length ? `, +${arguments_.paths.length - displayed.length} more` : ""}`;+ return `${displayed.join(", ")}${paths.length > displayed.length ? `, +${paths.length - displayed.length} more` : ""}`;}- if (arguments_.diff !== undefined) return "committed changes";- if (arguments_.workingTree) return "working-tree changes";+ if (arguments_.target instanceof DiffTarget)+ return arguments_.target.kind === "refs"+ ? "committed changes"+ : "working-tree changes";return null;}@@ -8714,18 +8817,87 @@ function quoteCliPath(path: string): string {: `'${path.replaceAll("'", `'"'"'`)}'`;}-function targetFromArguments(arguments_: ScanArguments): ScanTarget {- if (arguments_.paths.length > 0) return arguments_.paths;- if (arguments_.diff !== undefined) {- return DiffTarget.refs({- base: arguments_.diff,- head: arguments_.head ?? "HEAD",- });- }- if (arguments_.workingTree) {- return DiffTarget.workingTree({ base: arguments_.base ?? "HEAD" });+async function selectedProjectConfig(+ file: string | undefined,+ dependencies: Pick<CliDependencies, "environment" | "currentDirectory">,+) {+ const selected =+ file ??+ environmentValue(dependencies.environment, "CODEX_SECURITY_PROJECT_CONFIG");+ return selected === undefined+ ? undefined+ : readProjectConfig(selected, dependencies.currentDirectory());+}++function resolveCliScope(+ configured: ProjectScope | undefined,+ overrides: {+ paths?: string[];+ diff?: string;+ workingTree?: boolean;+ head?: string;+ base?: string;+ },+): {+ target?: ScanTarget;+ sources: Partial<Record<ScopeProvenanceKey, ConfigurationSource>>;+} {+ const sources: Partial<Record<ScopeProvenanceKey, ConfigurationSource>> = {};+ const explicitScopes =+ Number(!!overrides.paths?.length) ++ Number(overrides.diff !== undefined) ++ Number(overrides.workingTree === true);+ if (explicitScopes > 1)+ throw new ConfigurationError(+ "--path, --diff, and --working-tree are mutually exclusive.",+ );+ if (+ explicitScopes === 0 &&+ overrides.workingTree !== false &&+ overrides.head === undefined &&+ overrides.base === undefined+ ) {+ return { sources };+ }+ let scope = configured;+ let changed = false;+ sources["scan.scope"] = scope === undefined ? "default" : "project";+ if (overrides.paths?.length) scope = { paths: overrides.paths };+ else if (overrides.diff !== undefined)+ scope = { diff: { base: overrides.diff } };+ else if (overrides.workingTree === true) scope = { working_tree: {} };+ else if (+ overrides.workingTree === false &&+ scope !== undefined &&+ "working_tree" in scope+ ) {+ scope = undefined;+ changed = true;+ }+ if (explicitScopes > 0 || changed) {+ changed = true;+ sources["scan.scope"] = "cli";+ }+ // A ref-only override refines the selected project scope; it does not take+ // ownership of the whole scope variant.+ if (overrides.head !== undefined) {+ if (scope === undefined || !("diff" in scope))+ throw new ConfigurationError("--head requires --diff.");+ scope = { diff: { ...scope.diff, head: overrides.head } };+ sources["scan.scope.diff.head"] = "cli";+ changed = true;+ }+ if (overrides.base !== undefined) {+ if (scope === undefined || !("working_tree" in scope))+ throw new ConfigurationError("--base requires --working-tree.");+ scope = { working_tree: { base: overrides.base } };+ sources["scan.scope.working_tree.base"] = "cli";+ changed = true;}- return "repository";+ return {+ ...(changed ? { target: projectScopeTarget(scope) ?? "repository" } : {}),+ sources,+ };}export function parseCodexOverrides(@@ -8733,6 +8905,7 @@ export function parseCodexOverrides(model?: string,effort?: ScanReasoningEffort,provider?: "openai" | "amazon-bedrock" | ExternalModelProvider,+ defaults?: JsonObject,): JsonObject {const result = Object.create(null) as JsonObject;if (model !== undefined) result["model"] = model;@@ -8805,13 +8978,17 @@ export function parseCodexOverrides(}cursor[final] = parsed;}- if (- (isExternalModelProvider(provider) || provider === "amazon-bedrock") &&- !("model" in result)- ) {- throw new CodexSecurityError(- `--model is required when using --provider ${provider}`,+ if (isExternalModelProvider(provider) || provider === "amazon-bedrock") {+ const selectedModel = scanModel(+ mergeCodexOverrides(defaults ?? {}, result),);+ if (typeof selectedModel !== "string" || !selectedModel.trim()) {+ throw new CodexSecurityError(+ selectedModel === undefined+ ? `--model is required when using --provider ${provider}`+ : `--model must be a nonempty string when using --provider ${provider}`,+ );+ }}return result;}diff --git a/sdk/typescript/src/component-scan.ts b/sdk/typescript/src/component-scan.tsindex cea57bc0d..4c7bb186b 100644--- a/sdk/typescript/src/component-scan.ts+++ b/sdk/typescript/src/component-scan.ts@@ -23,6 +23,7 @@ import { safeErrorMessage } from "./errors.js";import type { CoverageCompleteness, Finding } from "./models.js";import type { ScanResult } from "./result.js";import type { ScanActivity } from "./scan-activity.js";+import type { ScanSettings } from "./scan-settings.js";import type { ScanProgress, ScanWorkerStatus } from "./worker-progress.js";import {matchScanFindings,@@ -39,14 +40,7 @@ export interface ComponentScanOptions {planOnly?: boolean;workers?: number;config?: CodexSecurityConfig;- scanOptions?: Pick<- ScanOptions,- | "auth"- | "knowledgeBasePaths"- | "scanPrompt"- | "postScanPrompt"- | "maxCostUsd"- >;+ scanOptions?: Omit<ScanSettings, "target" | "outputDir">;signal?: AbortSignal;createSecurity?: (config: CodexSecurityConfig,@@ -120,6 +114,7 @@ export interface ComponentScanResult {findingCount?: number;sourceFindingCount?: number;deduplication?: ComponentDeduplicationSummary;+ policyFailed?: boolean;}export async function runComponentScans(@@ -222,7 +217,7 @@ export async function runComponentScans(const result = await security.run(repository, {...options.scanOptions,...observers,- mode: "standard",+ mode: options.scanOptions?.mode ?? "standard",target: receipt.paths,outputDir: receipt.outputDir,signal: options.signal,@@ -276,6 +271,7 @@ export async function runComponentScans(: join(output, "retry-components.json");if (retryPlanPath !== undefined)await writeJson(retryPlanPath, { components: retryComponents });+ const failureSeverity = options.scanOptions?.failureSeverity;const summary = {...base,completed: receipts.filter(({ status }) => status === "completed").length,@@ -291,6 +287,13 @@ export async function runComponentScans(0,),deduplication,+ ...(failureSeverity === undefined+ ? {}+ : {+ policyFailed: [...results.values()].some((result) =>+ result.hasFindingsAtOrAbove(failureSeverity),+ ),+ }),};await writeJson(summary.findingsPath, {documentType: "codex-security.component-findings",diff --git a/sdk/typescript/src/config-path.ts b/sdk/typescript/src/config-path.tsnew file mode 100644index 000000000..c745e95ce--- /dev/null+++ b/sdk/typescript/src/config-path.ts@@ -0,0 +1,12 @@+import { resolve } from "node:path";+import { expandHome } from "./runtime.js";++/** A config, SDK, or CLI path anchored to its input directory. */+export type AbsolutePath = string & { readonly __absolutePath: unique symbol };++export function resolveConfigPath(+ directory: string,+ value: string,+): AbsolutePath {+ return resolve(directory, expandHome(value)) as AbsolutePath;+}diff --git a/sdk/typescript/src/config.ts b/sdk/typescript/src/config.tsindex 3db36c0c7..9d28e61df 100644--- a/sdk/typescript/src/config.ts+++ b/sdk/typescript/src/config.ts@@ -79,10 +79,7 @@ export function scanModelConfiguration(config: Readonly<JsonObject>,): ScanModelConfiguration {const selectedProfile = selectedScanProfile(config);- const model =- selectedProfile !== undefined && Object.hasOwn(selectedProfile, "model")- ? selectedProfile["model"]- : config["model"];+ const model = scanModel(config);if (typeof model !== "string" || model.trim().length === 0) {throw new ConfigurationError("The configured Codex model must be a nonempty string.",@@ -104,6 +101,14 @@ export function scanModelConfiguration(return { model, reasoningEffort };}+export function scanModel(config: Readonly<JsonObject>): unknown {+ const selectedProfile = selectedScanProfile(config);+ return selectedProfile !== undefined &&+ Object.hasOwn(selectedProfile, "model")+ ? selectedProfile["model"]+ : config["model"];+}+export function scanModelProvider(config: Readonly<JsonObject>): unknown {const selectedProfile = selectedScanProfile(config);return selectedProfile !== undefined &&@@ -410,6 +415,15 @@ function validateNativeMultiAgentV2Overrides(overrides: JsonObject): void {}}+export function mergeCodexOverrides(+ base: JsonObject,+ overrides: JsonObject,+): JsonObject {+ validateOverrideKeys(base);+ validateOverrideKeys(overrides);+ return deepMerge(cloneJson(base), overrides);+}+/** @internal */export function deepMerge(base: JsonObject, overrides: JsonObject): JsonObject {for (const [key, value] of Object.entries(overrides)) {diff --git a/sdk/typescript/src/deep-config.ts b/sdk/typescript/src/deep-config.tsnew file mode 100644index 000000000..7fb83291c--- /dev/null+++ b/sdk/typescript/src/deep-config.ts@@ -0,0 +1,203 @@+import { lstat, readFile, realpath } from "node:fs/promises";+import { basename, dirname, join, resolve } from "node:path";+import { parse as parseToml, type TomlTable } from "smol-toml";+import { writeCodexConfig, type JsonObject } from "./config.js";+import { DEFAULT_DEEP_SCAN_SETTINGS } from "./deep-scan-defaults.js";+import { CodexSecurityError } from "./errors.js";+import {+ DEFAULT_SCAN_MODE,+ DEEP_SCAN_SETTINGS,+ DeepScanSettingsSchema,+ type DeepScanOptions,+} from "./scan-settings.js";+import type { ScanMode } from "./scan-modes.js";++export type DeepScanSources = Record<+ keyof DeepScanOptions,+ "default" | "legacy" | "override"+>;+export interface ResolvedDeepScanConfig {+ settings: Required<DeepScanOptions>;+ sources: DeepScanSources;+ source: string;+ document: TomlTable;+ overrides: DeepScanOptions;+}++export function deepScanOptions(+ options: DeepScanOptions & { mode?: ScanMode },+): DeepScanOptions {+ const selected: DeepScanOptions = {};+ for (const [name] of DEEP_SCAN_SETTINGS) {+ const value = options[name];+ if (value === undefined) continue;+ if ((options.mode ?? DEFAULT_SCAN_MODE) !== "deep") {+ throw new CodexSecurityError("Deep scan settings require deep mode.");+ }+ selected[name] = requireDeepScanValue(name, value, name);+ }+ return selected;+}++function requireDeepScanValue(+ name: keyof DeepScanOptions,+ value: unknown,+ label: string,+): number {+ const parsed = DeepScanSettingsSchema.shape[name].unwrap().safeParse(value);+ if (!parsed.success) {+ throw new CodexSecurityError(+ `Deep scan ${label} ${parsed.error.issues[0]!.message}.`,+ );+ }+ return parsed.data;+}++export async function resolveDeepScanConfig(+ options: DeepScanOptions,+ source: string,+ signal?: AbortSignal,+): Promise<ResolvedDeepScanConfig> {+ const explicit = deepScanOptions({ ...options, mode: "deep" });+ let document: TomlTable = {};+ // Complete saved settings do not depend on today's ambient configuration.+ if (!DEEP_SCAN_SETTINGS.every(([name]) => explicit[name] !== undefined)) {+ document = await readDeepScanDocument(source, signal);+ }+ const existing = document["deep_scan"];+ if (+ existing !== undefined &&+ (typeof existing !== "object" ||+ existing === null ||+ Array.isArray(existing) ||+ ![Object.prototype, null].includes(Object.getPrototypeOf(existing)))+ ) {+ throw new CodexSecurityError(+ `Codex Security configuration [deep_scan] at ${source} must be a TOML table.`,+ );+ }+ const configured = (existing ?? {}) as TomlTable;+ const keys = new Set<string>(DEEP_SCAN_SETTINGS.map(([, key]) => key));+ const unknown = Object.keys(configured).filter((key) => !keys.has(key));+ if (unknown.length > 0) {+ throw new CodexSecurityError(+ `Unknown Codex Security Deep Scan configuration ${unknown.join(", ")} in ${source}.`,+ );+ }+ const settings = {+ ...DEFAULT_DEEP_SCAN_SETTINGS,+ } as Required<DeepScanOptions>;+ const sources = {} as DeepScanSources;+ for (const [name, key] of DEEP_SCAN_SETTINGS) {+ let value = Object.hasOwn(configured, key)+ ? configured[key]+ : DEFAULT_DEEP_SCAN_SETTINGS[name];+ if (name === "workers" && value === "auto")+ value = DEFAULT_DEEP_SCAN_SETTINGS.workers;+ if (explicit[name] !== undefined) value = explicit[name];+ sources[name] =+ explicit[name] !== undefined+ ? "override"+ : Object.hasOwn(configured, key)+ ? "legacy"+ : "default";+ settings[name] = requireDeepScanValue(+ name,+ value,+ sources[name] === "legacy" ? `${key} in ${source}` : name,+ );+ }+ return {+ settings,+ sources,+ source,+ document,+ overrides: explicit,+ };+}++export async function writeDeepScanConfig(+ destination: string,+ resolved: ResolvedDeepScanConfig,+): Promise<void> {+ const [source, target] = await Promise.all([+ canonicalConfigPath(resolved.source),+ runtimeConfigPath(destination),+ ]);+ let document = resolved.document;+ const sameFile = source === target;+ if (sameFile) {+ if (Object.keys(resolved.overrides).length === 0) return;+ document = await readDeepScanDocument(destination);+ }+ // An isolated runtime needs a complete snapshot. An ambient file keeps+ // inherited defaults unset so future releases can still update them.+ const settings = sameFile ? resolved.overrides : resolved.settings;+ const retainAmbientSettings =+ sameFile &&+ DEEP_SCAN_SETTINGS.some(([name]) => settings[name] === undefined);+ await writeCodexConfig(destination, {+ ...document,+ deep_scan: {+ ...(retainAmbientSettings+ ? (document["deep_scan"] as TomlTable | undefined)+ : {}),+ ...Object.fromEntries(+ DEEP_SCAN_SETTINGS.filter(([name]) => settings[name] !== undefined).map(+ ([name, key]) => [key, settings[name]],+ ),+ ),+ },+ } as JsonObject);+}++async function runtimeConfigPath(path: string): Promise<string> {+ try {+ return await canonicalConfigPath(path);+ } catch (error) {+ if (+ (error as NodeJS.ErrnoException).code !== "ELOOP" ||+ !(await lstat(path)).isSymbolicLink()+ )+ throw error;+ // A stale cyclic file link is replaced by writeCodexConfig's atomic rename.+ // Errors resolving its parent (or the ambient source) still fail the write.+ return join(await canonicalConfigPath(dirname(path)), basename(path));+ }+}++async function canonicalConfigPath(path: string): Promise<string> {+ let existing = resolve(path);+ const missing: string[] = [];+ while (true) {+ try {+ return join(await realpath(existing), ...missing);+ } catch (error) {+ const parent = dirname(existing);+ if (+ (error as NodeJS.ErrnoException).code !== "ENOENT" ||+ parent === existing+ )+ throw error;+ missing.unshift(basename(existing));+ existing = parent;+ }+ }+}++async function readDeepScanDocument(+ source: string,+ signal?: AbortSignal,+): Promise<TomlTable> {+ try {+ return parseToml(await readFile(source, { encoding: "utf8", signal }));+ } catch (error) {+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") {+ throw new CodexSecurityError(+ `Cannot read Codex Security configuration at ${source}.`,+ { cause: error },+ );+ }+ return {};+ }+}diff --git a/sdk/typescript/src/deep-scan-defaults.ts b/sdk/typescript/src/deep-scan-defaults.tsnew file mode 100644index 000000000..57b167f63--- /dev/null+++ b/sdk/typescript/src/deep-scan-defaults.ts@@ -0,0 +1,9 @@+// Generated from the plugin deep_scan_defaults.json. Run pnpm build.+export const DEFAULT_DEEP_SCAN_SETTINGS = {+ workers: 4,+ subagents: 3,+ stopAfterNoNew: 4,+ stopAfterConsecutiveErrors: 3,+ maxDiscoveryRuns: 40,+ maxTimeHours: 96,+} as const;diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.tsindex 0f14c1fa7..c62ad02c6 100644--- a/sdk/typescript/src/index.ts+++ b/sdk/typescript/src/index.ts@@ -1,4 +1,14 @@export { CodexSecurity, createSecurity } from "./api.js";+export { loadProjectConfig, resolveProjectConfig } from "./project-config.js";+export type {+ ResolvedProjectConfig,+ ProjectConfigProvenance,+} from "./project-config.js";+export type {+ ProjectConfigInput,+ ProjectScope,+} from "./project-config-schema.js";+export type { ScanSettings } from "./scan-settings.js";export { classifySeverity } from "./classify-severity.js";export type {ClassifySeverityOptions,@@ -169,4 +179,5 @@ export {validateMode,} from "./targets.js";export type { NormalizedTarget, ScanMode, ScanTarget } from "./targets.js";+export type { AbsolutePath } from "./config-path.js";export { BUNDLED_PLUGIN_VERSION, VERSION } from "./version.js";diff --git a/sdk/typescript/src/multiscan.ts b/sdk/typescript/src/multiscan.tsindex 4d0c0105c..41ef15a40 100644--- a/sdk/typescript/src/multiscan.ts+++ b/sdk/typescript/src/multiscan.ts@@ -28,8 +28,15 @@ import {ScanCostLimitExceededError,} from "./errors.js";import type { CoverageDocument } from "./models.js";+import { resolveScanPrompts } from "./prompt-files.js";import { requireSecureOutputAncestry, validateOutputDir } from "./runtime.js";-import type { ScanMode } from "./targets.js";+import { DiffTarget, type ScanMode } from "./targets.js";+import {+ meetsSeverity,+ type ScanPromptSettings,+ type ScanSettings,+} from "./scan-settings.js";+import { workflowDigest } from "./finding-workflow.js";import type { ScanResult } from "./result.js";import { resolveTrustedExecutable } from "./trusted-executable.js";@@ -62,9 +69,10 @@ interface MultiscanReceipt extends MultiscanTask {cost?: ScanCost;error?: string;warning?: string;+ policyFailed?: boolean;}-export interface MultiscanOptions {+export interface MultiscanOptions extends ScanPromptSettings {inputPath: string;outputDir: string;githubHost?: string;@@ -74,11 +82,13 @@ export interface MultiscanOptions {maxAttempts: number;recoverScan?(scanDir: string,- ): Promise<Pick<ScanResult, "coverage" | "cost"> | undefined>;+ prompts: ScanPromptSettings,+ ): Promise<Pick<ScanResult, "coverage" | "cost" | "findings"> | undefined>;maxCostUsd?: number;- scanPrompt?: string;- validationPrompt?: string;- postScanPrompt?: string;+ // Prompts are shared across modes and prepared from the top-level options.+ scanOptionsByMode?: Partial<+ Record<ScanMode, Omit<ScanSettings, keyof ScanPromptSettings>>+ >;config: CodexSecurityConfig;createSecurity(config: CodexSecurityConfig,@@ -104,6 +114,7 @@ export interface MultiscanResult {failed: number;skipped: number;resultsPath: string;+ policyFailed?: boolean;}export async function runMultiscan(@@ -122,7 +133,53 @@ export async function runMultiscan(options.mode,);if (- options.validationPrompt !== undefined &&+ tasks.some(+ (task) =>+ task.scope === undefined &&+ options.scanOptionsByMode?.[task.mode]?.target instanceof DiffTarget,+ )+ ) {+ throw new Error(+ "Bulk scans do not support diff or working-tree scopes because their checkouts are clean, shallow snapshots. Use repository or path scopes instead.",+ );+ }+ const repositories: string[] = [];+ if (+ [+ [options.scanPrompt, options.scanPromptFile],+ [options.validationPrompt, options.validationPromptFile],+ [options.postScanPrompt, options.postScanPromptFile],+ ].some(([inline, file]) => inline === undefined && file !== undefined)+ ) {+ for (const repository of new Set(tasks.map((task) => task.repository))) {+ if (!isAbsolute(repository)) continue;+ try {+ repositories.push(await realpath(repository));+ } catch (error) {+ // Missing sources retain the campaign's per-repository failure behavior.+ const code = (error as NodeJS.ErrnoException).code;+ if (code !== "ENOENT" && code !== "ENOTDIR") throw error;+ }+ }+ }+ // Shared inputs use actual local CSV sources as directory-link boundaries,+ // not the invocation directory, and are read once before any scan starts.+ const prompts = await resolveScanPrompts(options, repositories);+ const resolvedOptions: MultiscanOptions = {+ ...options,+ ...prompts,+ ...(options.scanOptionsByMode === undefined+ ? {}+ : {+ scanOptionsByMode: Object.fromEntries(+ Object.entries(options.scanOptionsByMode).map(+ ([mode, settings]) => [mode, { ...settings, ...prompts }],+ ),+ ),+ }),+ };+ if (+ resolvedOptions.validationPrompt !== undefined &&tasks.some((task) => task.mode === "deep")) {throw new Error("Custom validation is not supported for Deep scans.");@@ -142,7 +199,7 @@ export async function runMultiscan(await requireSecureOutputAncestry(output);const unlock = await acquireLock(output);try {- const result = await runCampaign(options, tasks, output);+ const result = await runCampaign(resolvedOptions, tasks, output);return (await realpath(requestedOutput).catch(() => undefined)) === output? { ...result, resultsPath: join(requestedOutput, "results.jsonl") }: result;@@ -167,6 +224,10 @@ async function runCampaign(const pending: MultiscanTask[] = [];let completed = 0;let incomplete = 0;+ let policyFailed = false;+ const hasPolicy = Object.values(options.scanOptionsByMode ?? {}).some(+ (settings) => settings.failureSeverity !== undefined,+ );let untouched = 0;for (const task of tasks) {const receipt = receipts.get(task.id.toLowerCase());@@ -202,6 +263,7 @@ async function runCampaign((await hasArtifacts(artifactOutput))) {if (receipt.status === "completed") {+ policyFailed ||= receipt.policyFailed === true;completed += 1;continue;}@@ -213,6 +275,7 @@ async function runCampaign(outputDir: artifactOutput,});if (coverage !== undefined) {+ policyFailed ||= receipt.policyFailed === true;incomplete += 1;notifyProgress(options, {repository: task.id,@@ -236,6 +299,7 @@ async function runCampaign(failed: 0,skipped,resultsPath: ledger,+ ...(hasPolicy ? { policyFailed } : {}),};}@@ -266,13 +330,16 @@ async function runCampaign(let attemptedResume = false;let failure: string | undefined;let warning: string | undefined;+ let attemptPolicyFailed: boolean | undefined;let coverage: CoverageDocument["completeness"] | undefined;let cost: Readonly<ScanCost> | null = null;let exhaustedBudget = false;let requiresRecovery = false;try {await ensureOutputDirectory(artifactRoot);- let result: Pick<ScanResult, "coverage" | "cost"> | undefined;+ let result:+ | Pick<ScanResult, "coverage" | "cost" | "findings">+ | undefined;if (options.recoverScan !== undefined && retry === 0 && attempt > 0) {const existing = await lstat(scanDir).catch((error: NodeJS.ErrnoException) => {@@ -288,10 +355,11 @@ async function runCampaign(attempt,status: "started",});- result = await options.recoverScan(scanDir);+ result = await options.recoverScan(scanDir, options);attemptedResume = result !== undefined;}}+ const scanSettings = options.scanOptionsByMode?.[task.mode];if (result === undefined) {if (options.recoverScan !== undefined) attempt += 1;scanDir = join(artifactRoot, `attempt-${attempt}`);@@ -338,6 +406,7 @@ async function runCampaign(.filter(Boolean).join("\n\n");result = await security.run(checkout, {+ ...scanSettings,...(task.scope === undefined ? {} : { target: [task.scope] }),...(options.knowledgeBasePaths?.length? { knowledgeBasePaths: options.knowledgeBasePaths }@@ -367,6 +436,12 @@ async function runCampaign(});}cost = result.cost;+ const failureSeverity = scanSettings?.failureSeverity;+ if (failureSeverity !== undefined) {+ attemptPolicyFailed = result.findings.findings.some((finding) =>+ meetsSeverity(finding, failureSeverity),+ );+ }coverage = result.coverage.completeness;if (coverage !== "complete") {if (!(await hasArtifacts(scanDir))) {@@ -410,6 +485,9 @@ async function runCampaign(...(cost === null ? {} : { cost }),...(failure === undefined ? {} : { error: failure }),...(warning === undefined ? {} : { warning }),+ ...(attemptPolicyFailed === undefined+ ? {}+ : { policyFailed: attemptPolicyFailed }),})}\n`,);if (@@ -427,6 +505,7 @@ async function runCampaign(...(warning === undefined ? {} : { warning }),});if (failure === undefined) {+ policyFailed ||= attemptPolicyFailed === true;if (warning === undefined) completed += 1;else incomplete += 1;break;@@ -461,6 +540,7 @@ async function runCampaign(failed,skipped,resultsPath: ledger,+ ...(hasPolicy ? { policyFailed } : {}),};}@@ -732,7 +812,12 @@ async function ensureManifest(tasks: MultiscanTask[],options: Pick<MultiscanOptions,- "scanPrompt" | "validationPrompt" | "postScanPrompt" | "maxCostUsd"+ | "scanPrompt"+ | "validationPrompt"+ | "postScanPrompt"+ | "maxCostUsd"+ | "scanOptionsByMode"+ | "config">,): Promise<void> {const expected = `${JSON.stringify(@@ -751,6 +836,14 @@ async function ensureManifest(...(options.maxCostUsd === undefined? {}: { maxCostUsd: options.maxCostUsd }),+ ...(options.scanOptionsByMode === undefined+ ? {}+ : {+ configurationDigest: workflowDigest({+ scanOptions: options.scanOptionsByMode,+ codex: options.config.codexOverrides,+ }),+ }),},null,2,diff --git a/sdk/typescript/src/project-config-schema.ts b/sdk/typescript/src/project-config-schema.tsnew file mode 100644index 000000000..8e9fbe955--- /dev/null+++ b/sdk/typescript/src/project-config-schema.ts@@ -0,0 +1,120 @@+import { z } from "zod";+import {+ DeepScanSettingsSchema,+ FailureSeveritySchema,+ ScanSettingsSchema,+} from "./scan-settings.js";++const nonempty = z.string().min(1);++export const ProjectScopeSchema = z.union([+ z.strictObject({+ paths: z+ .array(nonempty)+ .min(1)+ .describe("Literal paths relative to the selected repository."),+ }),+ z.strictObject({+ diff: z.strictObject({+ base: nonempty,+ head: nonempty.optional().meta({ default: "HEAD" }),+ }),+ }),+ z.strictObject({+ working_tree: z.strictObject({+ base: nonempty.optional().meta({ default: "HEAD" }),+ }),+ }),+]);++export const ProjectConfigInputSchema = z.strictObject({+ $schema: nonempty+ .optional()+ .describe(+ "Editor schema URI or relative path. The CLI does not fetch or select a validator from this value.",+ ),+ auth: ScanSettingsSchema.shape.auth.describe(+ "Credential-source choice only; never a credential value.",+ ),+ scan: z+ .strictObject({+ mode: ScanSettingsSchema.shape.mode,+ scope: ProjectScopeSchema.optional().describe(+ "One scope variant. Omit for the whole repository. Mode compatibility is checked after overrides.",+ ),+ knowledge_base: ScanSettingsSchema.shape.knowledgeBasePaths.describe(+ "Context files or directories, relative to this file. An empty list selects no additional context.",+ ),+ instructions_file: ScanSettingsSchema.shape.scanPromptFile.describe(+ "Additional scan instructions, relative to this file.",+ ),+ validation_file: ScanSettingsSchema.shape.validationPromptFile.describe(+ "Custom validation instructions, relative to this file; not supported in active deep scans.",+ ),+ deep: z+ .strictObject({+ workers: DeepScanSettingsSchema.shape.workers,+ subagents_per_worker: DeepScanSettingsSchema.shape.subagents,+ stop_after_no_new: DeepScanSettingsSchema.shape.stopAfterNoNew,+ stop_after_consecutive_errors:+ DeepScanSettingsSchema.shape.stopAfterConsecutiveErrors,+ max_discovery_runs: DeepScanSettingsSchema.shape.maxDiscoveryRuns,+ max_time_hours: DeepScanSettingsSchema.shape.maxTimeHours,+ })+ .optional()+ .describe(+ "Deep defaults; a valid block may be retained while standard mode is selected.",+ ),+ })+ .optional(),+ codex: z+ .object({+ model: nonempty.optional(),+ model_reasoning_effort: nonempty.optional(),+ model_provider: nonempty.optional(),+ })+ .catchall(z.json())+ .optional()+ .describe(+ "Native Codex overrides. Common key types are checked here; existing native and wrapper restrictions still apply.",+ ),+ limits: z+ .strictObject({+ max_cost_usd_per_scan: ScanSettingsSchema.shape.maxCostUsd.describe(+ "Estimated USD limit per launched scan attempt, not a total batch budget. Omit for no limit.",+ ),+ })+ .optional(),+ policy: z+ .strictObject({+ fail_on_severity: FailureSeveritySchema.optional().describe(+ "Exit threshold; does not filter retained findings. Omit for report-only behavior.",+ ),+ })+ .optional(),+ output: z+ .strictObject({+ directory: ScanSettingsSchema.shape.outputDir.describe(+ "Artifact directory relative to this file; existing outside-worktree checks still apply.",+ ),+ })+ .optional(),+});++export type ProjectConfigInput = z.infer<typeof ProjectConfigInputSchema>;+export type ProjectScope = z.infer<typeof ProjectScopeSchema>;++export function projectConfigJsonSchema() {+ return {+ ...z.toJSONSchema(ProjectConfigInputSchema, {+ target: "draft-07",+ io: "input",+ unrepresentable: "throw",+ }),+ title: "Codex Security project configuration",+ description:+ "Input schema for explicitly selected YAML or JSON project files. Filesystem, active scan combinations, native configuration, and runtime availability are checked separately.",+ $comment:+ "Generated from ProjectConfigInputSchema. Defaults are annotations; apply defaults only after merging input layers.",+ };+}diff --git a/sdk/typescript/src/project-config.ts b/sdk/typescript/src/project-config.tsnew file mode 100644index 000000000..e853bcbee--- /dev/null+++ b/sdk/typescript/src/project-config.ts@@ -0,0 +1,385 @@+import { readFile } from "node:fs/promises";+import {+ dirname,+ extname,+ isAbsolute,+ relative,+ resolve,+ sep,+} from "node:path";+import { pathToFileURL } from "node:url";+import Ajv from "ajv";+import { parseDocument } from "yaml";+import {+ DEFAULT_CODEX_CONFIG,+ mergeCodexOverrides,+ type JsonObject,+} from "./config.js";+import { ConfigurationError } from "./errors.js";+import { DEFAULT_DEEP_SCAN_SETTINGS } from "./deep-scan-defaults.js";+import { resolveConfigPath, type AbsolutePath } from "./config-path.js";+import { deepScanOptions, type DeepScanSources } from "./deep-config.js";+import {+ projectConfigJsonSchema,+ type ProjectConfigInput,+ type ProjectScope,+} from "./project-config-schema.js";+import { expandHome } from "./runtime.js";+import {+ DEFAULT_SCAN_AUTH,+ DEFAULT_SCAN_MODE,+ DEEP_SCAN_SETTINGS,+ pickScanSettings,+ type DeepScanOptions,+ type ResolvedScanSettings,+ type ScanSettings,+} from "./scan-settings.js";+import { DiffTarget, type ScanTarget } from "./targets.js";++const validateProjectConfig = new Ajv({+ allErrors: true,+}).compile<ProjectConfigInput>(projectConfigJsonSchema());++export interface ProjectConfigSource {+ path?: string;+ directory: string;+ input: ProjectConfigInput;+}++export interface ResolvedProjectConfig {+ config: { codexOverrides: JsonObject };+ options: ResolvedScanSettings;+ sources: ConfigurationSources;+ projectConfig?: ProjectConfigProvenance;+}++export type ConfigurationSource = "default" | "legacy" | "project" | "cli";+const PROJECT_SETTING_KEYS = {+ auth: "auth",+ mode: "scan.mode",+ target: "scan.scope",+ knowledgeBasePaths: "scan.knowledge_base",+ scanPromptFile: "scan.instructions_file",+ validationPromptFile: "scan.validation_file",+ outputDir: "output.directory",+ failureSeverity: "policy.fail_on_severity",+ maxCostUsd: "limits.max_cost_usd_per_scan",+} as const satisfies Partial<Record<keyof ScanSettings, string>>;+type SettingProvenanceKey =+ (typeof PROJECT_SETTING_KEYS)[keyof typeof PROJECT_SETTING_KEYS];+export type ScopeProvenanceKey =+ | "scan.scope"+ | "scan.scope.diff.head"+ | "scan.scope.working_tree.base";+export type ProvenanceKey =+ | SettingProvenanceKey+ | ScopeProvenanceKey+ | `scan.deep.${(typeof DEEP_SCAN_SETTINGS)[number][2]}`+ | `codex.${string}`;+export type ConfigurationSources = Readonly<+ Record<SettingProvenanceKey, ConfigurationSource> &+ Partial<Record<ProvenanceKey, ConfigurationSource>>+>;+export interface ProjectConfigProvenance {+ path: string;+ sources: ConfigurationSources;+}++/** Build a complete, immutable source map after layer and preflight resolution. */+export function configurationSources(+ values: Partial<Record<ProvenanceKey, ConfigurationSource>> = {},+ deepSources?: DeepScanSources,+): ConfigurationSources {+ const sources = {+ ...Object.fromEntries(+ Object.values(PROJECT_SETTING_KEYS).map((key) => [key, "default"]),+ ),+ ...values,+ } as Record<SettingProvenanceKey, ConfigurationSource> &+ Partial<Record<ProvenanceKey, ConfigurationSource>>;+ for (const [name, , key] of DEEP_SCAN_SETTINGS) {+ const source = deepSources?.[name];+ if (source !== undefined && source !== "override")+ sources[`scan.deep.${key}`] = source;+ }+ return Object.freeze(sources);+}++export async function loadProjectConfig(+ file: string,+ directory = process.cwd(),+): Promise<ResolvedProjectConfig> {+ return resolveScanSettings(+ await readProjectConfig(file, directory),+ {},+ directory,+ );+}++export function resolveProjectConfig(+ input: ProjectConfigInput,+ directory = process.cwd(),+): ResolvedProjectConfig {+ requireProjectConfig(input);+ return resolveScanSettings(+ { input, directory: resolve(directory) },+ {},+ directory,+ );+}++export async function readProjectConfig(+ file: string,+ directory = process.cwd(),+): Promise<ProjectConfigSource> {+ const path = resolve(directory, expandHome(file));+ const extension = projectConfigExtension(path);+ let text: string;+ try {+ text = await readFile(path, "utf8");+ } catch (error) {+ throw new ConfigurationError(+ `Cannot read project configuration at ${path}.`,+ { cause: error },+ );+ }+ let value: unknown;+ try {+ if (extension === ".json") {+ value = JSON.parse(text);+ } else {+ const document = parseDocument(text, { prettyErrors: false });+ if (document.errors.length > 0) throw document.errors[0];+ // Keep YAML's expansion guard while allowing repeated native profiles.+ value = document.toJS({ maxAliasCount: 10_000 });+ }+ } catch (error) {+ throw new ConfigurationError(+ `Cannot parse project configuration at ${path}.`,+ { cause: error },+ );+ }+ requireProjectConfig(value, path);+ return { path, directory: dirname(path), input: value };+}++function projectConfigExtension(path: string): string {+ const extension = extname(path).toLowerCase();+ if (![".yaml", ".yml", ".json"].includes(extension)) {+ throw new ConfigurationError(+ "Project configuration must be a .yaml, .yml, or .json file.",+ );+ }+ return extension;+}++export function projectConfigStarter(+ path: string,+ directory = process.cwd(),+): string {+ const schemaPath = resolve(+ directory,+ "node_modules/@openai/codex-security/schemas/project-config.schema.json",+ );+ const relativeSchema = relative(+ dirname(resolve(directory, path)),+ schemaPath,+ );+ const schema = isAbsolute(relativeSchema)+ ? pathToFileURL(schemaPath).href+ : `${relativeSchema.startsWith(".") ? "" : "./"}${relativeSchema+ .split(sep)+ .join("/")}`;+ if (projectConfigExtension(path) === ".json")+ return `${JSON.stringify({ $schema: schema }, null, 2)}\n`;+ return [+ "# This file is trusted like CLI options. Keep it outside untrusted inputs.",+ `$schema: ${schema}`,+ "",+ "# Uncomment the settings you want to override. Defaults remain unpinned.",+ `# auth: ${DEFAULT_SCAN_AUTH}`,+ "# scan:",+ `# mode: ${DEFAULT_SCAN_MODE}`,+ "# scope:",+ "# paths: [src] # Relative to each selected repository.",+ "# knowledge_base: [] # Paths relative to this file.",+ "# instructions_file: instructions.md",+ "# validation_file: validation.md # Standard mode only.",+ "# deep: # Used when mode is deep.",+ ...DEEP_SCAN_SETTINGS.map(+ ([name, , key]) => `# ${key}: ${DEFAULT_DEEP_SCAN_SETTINGS[name]}`,+ ),+ "# codex:",+ `# model: ${DEFAULT_CODEX_CONFIG["model"]}`,+ `# model_reasoning_effort: ${DEFAULT_CODEX_CONFIG["model_reasoning_effort"]}`,+ "# limits:",+ "# max_cost_usd_per_scan: 10 # Optional limit per scan attempt.",+ "# policy:",+ "# fail_on_severity: high # Omitted by default (report only).",+ "# output:",+ "# directory: ../scan-results # Outside the selected repositories.",+ "",+ ].join("\n");+}++function requireProjectConfig(+ value: unknown,+ path?: string,+): asserts value is ProjectConfigInput {+ if (!validateProjectConfig(value)) {+ const issues = validateProjectConfig+ .errors!.map((issue) => {+ const message =+ issue.keyword === "additionalProperties"+ ? `Unknown key ${issue.params["additionalProperty"]}.`+ : issue.message;+ return `${issue.instancePath || "configuration"}: ${message}`;+ })+ .join("; ");+ throw new ConfigurationError(+ `Invalid project configuration${path === undefined ? "" : ` at ${path}`}: ${issues}`,+ );+ }+}++export function resolveScanSettings(+ project: ProjectConfigSource | undefined,+ overrides: Partial<ScanSettings> & { codexOverrides?: JsonObject },+ directory: string,+ scopeSources: Partial<Record<ScopeProvenanceKey, ConfigurationSource>> = {},+): ResolvedProjectConfig {+ const file = project?.input;+ const sources: Partial<Record<ProvenanceKey, ConfigurationSource>> = {};+ const choose = <T>(+ key: ProvenanceKey,+ configured: T | undefined,+ explicit: T | undefined,+ ): T | undefined => {+ if (explicit !== undefined) {+ sources[key] = "cli";+ return explicit;+ }+ if (configured !== undefined) {+ sources[key] = "project";+ return configured;+ }+ return undefined;+ };+ const projectDirectory = project?.directory ?? directory;+ const filePath = (value: string | undefined): AbsolutePath | undefined =>+ value === undefined+ ? undefined+ : resolveConfigPath(projectDirectory, value);+ const cliPath = (value: string | undefined): AbsolutePath | undefined =>+ value === undefined ? undefined : resolveConfigPath(directory, value);++ const mode =+ choose("scan.mode", file?.scan?.mode, overrides.mode) ?? DEFAULT_SCAN_MODE;+ const explicitDeep = deepScanOptions({ ...overrides, mode });+ const target =+ choose(+ "scan.scope",+ projectScopeTarget(file?.scan?.scope),+ overrides.target,+ ) ?? "repository";+ const configuredDeep = file?.scan?.deep;+ const deep: DeepScanOptions = {};+ if (mode === "deep") {+ for (const [name, , field] of DEEP_SCAN_SETTINGS) {+ const value = choose(+ `scan.deep.${field}`,+ configuredDeep?.[field],+ explicitDeep[name],+ );+ if (value !== undefined) deep[name] = value;+ }+ }++ const codexOverrides = mergeCodexOverrides(+ file?.codex ?? {},+ overrides.codexOverrides ?? {},+ );+ const recordNativeSources = (+ value: JsonObject,+ source: ConfigurationSource,+ prefix: "codex" | `codex.${string}` = "codex",+ ) => {+ for (const [key, item] of Object.entries(value)) {+ const path: `codex.${string}` = `${prefix}.${key}`;+ if (item !== null && typeof item === "object" && !Array.isArray(item)) {+ delete sources[path];+ recordNativeSources(item, source, path);+ } else {+ for (const existing of Object.keys(sources) as ProvenanceKey[]) {+ if (existing.startsWith(`${path}.`)) delete sources[existing];+ }+ sources[path] = source;+ }+ }+ };+ recordNativeSources(DEFAULT_CODEX_CONFIG, "default");+ recordNativeSources(file?.codex ?? {}, "project");+ recordNativeSources(overrides.codexOverrides ?? {}, "cli");+ const knowledgeBasePaths =+ choose(+ "scan.knowledge_base",+ file?.scan?.knowledge_base?.map((value) =>+ resolveConfigPath(projectDirectory, value),+ ),+ overrides.knowledgeBasePaths?.map((value) =>+ resolveConfigPath(directory, value),+ ),+ ) ?? [];+ const settings: ResolvedScanSettings = {+ ...pickScanSettings(overrides),+ auth: choose("auth", file?.auth, overrides.auth) ?? DEFAULT_SCAN_AUTH,+ mode,+ target,+ knowledgeBasePaths,+ scanPromptFile: choose(+ "scan.instructions_file",+ filePath(file?.scan?.instructions_file),+ cliPath(overrides.scanPromptFile),+ ),+ validationPromptFile: choose(+ "scan.validation_file",+ filePath(file?.scan?.validation_file),+ cliPath(overrides.validationPromptFile),+ ),+ postScanPromptFile: cliPath(overrides.postScanPromptFile),+ outputDir: choose(+ "output.directory",+ filePath(file?.output?.directory),+ cliPath(overrides.outputDir),+ ),+ failureSeverity: choose(+ "policy.fail_on_severity",+ file?.policy?.fail_on_severity,+ overrides.failureSeverity,+ ),+ maxCostUsd: choose(+ "limits.max_cost_usd_per_scan",+ file?.limits?.max_cost_usd_per_scan,+ overrides.maxCostUsd,+ ),+ ...deep,+ };+ const resolvedSources = configurationSources({ ...sources, ...scopeSources });+ return {+ config: { codexOverrides },+ options: settings,+ sources: resolvedSources,+ ...(project?.path === undefined+ ? {}+ : { projectConfig: { path: project.path, sources: resolvedSources } }),+ };+}++export function projectScopeTarget(+ scope: ProjectScope | undefined,+): ScanTarget | undefined {+ if (scope === undefined) return undefined;+ if ("paths" in scope) return [...scope.paths];+ if ("diff" in scope) return DiffTarget.refs(scope.diff);+ return DiffTarget.workingTree(scope.working_tree);+}diff --git a/sdk/typescript/src/prompt-files.ts b/sdk/typescript/src/prompt-files.tsnew file mode 100644index 000000000..9b4b0b171--- /dev/null+++ b/sdk/typescript/src/prompt-files.ts@@ -0,0 +1,120 @@+import { constants, type BigIntStats } from "node:fs";+import { lstat, open, realpath } from "node:fs/promises";+import {+ basename,+ dirname,+ isAbsolute,+ join,+ relative,+ resolve,+ sep,+} from "node:path";+import { CodexSecurityError } from "./errors.js";+import { expandHome } from "./runtime.js";+import type { ScanPromptSettings } from "./scan-settings.js";++type ResolvedScanPrompts = Pick<+ ScanPromptSettings,+ "scanPrompt" | "validationPrompt" | "postScanPrompt"+> & {+ scanPromptFile: undefined;+ validationPromptFile: undefined;+ postScanPromptFile: undefined;+};++/** Resolve selected files once; an inline SDK prompt overrides its file. */+export async function resolveScanPrompts(+ options: ScanPromptSettings,+ repository: string | readonly string[],+ directory = process.cwd(),+): Promise<ResolvedScanPrompts> {+ const read = async (inline: string | undefined, file: string | undefined) =>+ inline !== undefined || file === undefined+ ? inline+ : await readRegularInputFile(+ resolve(directory, expandHome(file)),+ repository,+ );+ const [scanPrompt, validationPrompt, postScanPrompt] = await Promise.all([+ read(options.scanPrompt, options.scanPromptFile),+ read(options.validationPrompt, options.validationPromptFile),+ read(options.postScanPrompt, options.postScanPromptFile),+ ]);+ if (+ options.validationPrompt === undefined &&+ validationPrompt !== undefined &&+ !validationPrompt.trim()+ ) {+ throw new CodexSecurityError("The validation prompt must not be empty.");+ }+ return {+ scanPrompt:+ options.scanPrompt !== undefined || scanPrompt?.trim()+ ? scanPrompt+ : undefined,+ validationPrompt,+ postScanPrompt:+ options.postScanPrompt !== undefined || postScanPrompt?.trim()+ ? postScanPrompt+ : undefined,+ // Spreading the resolved prompts back into options must clear file inputs,+ // including blank files, so later preparation does not read them again.+ scanPromptFile: undefined,+ validationPromptFile: undefined,+ postScanPromptFile: undefined,+ };+}++export async function readRegularInputFile(+ path: string,+ repository: string | readonly string[],+ metadata?: Pick<BigIntStats, "isFile" | "dev" | "ino">,+): Promise<string> {+ const selected = metadata ?? (await lstat(path, { bigint: true }));+ if (!selected.isFile()) {+ throw new CodexSecurityError("Input files must be regular files.");+ }+ const canonicalParent = await realpath(dirname(path));+ const repositories =+ typeof repository === "string" ? [repository] : repository;+ for (const repository of repositories) {+ const canonicalRepository = await realpath(repository);+ if (isOutsidePath(relative(canonicalRepository, canonicalParent))) {+ for (let ancestor = dirname(path); ; ancestor = dirname(ancestor)) {+ if (+ !isOutsidePath(+ relative(canonicalRepository, await realpath(ancestor)),+ )+ ) {+ throw new CodexSecurityError(+ "Input files must not follow repository directory links outside the selected repository.",+ );+ }+ if (dirname(ancestor) === ancestor) break;+ }+ }+ }+ const file = await open(+ join(canonicalParent, basename(path)),+ constants.O_RDONLY |+ (constants.O_NOFOLLOW ?? 0) |+ (constants.O_NONBLOCK ?? 0),+ );+ try {+ const opened = await file.stat({ bigint: true });+ if (+ !opened.isFile() ||+ opened.dev !== selected.dev ||+ opened.ino !== selected.ino+ ) {+ throw new CodexSecurityError("Input files must remain regular files.");+ }+ return await file.readFile({ encoding: "utf8" });+ } finally {+ await file.close();+ }+}++export function isOutsidePath(path: string): boolean {+ return path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path);+}diff --git a/sdk/typescript/src/result.ts b/sdk/typescript/src/result.tsindex e871e23c8..1fb5d8c19 100644--- a/sdk/typescript/src/result.ts+++ b/sdk/typescript/src/result.ts@@ -5,8 +5,10 @@ import type {Finding,FindingsDocument,ScanManifest,+ SeverityLevel,} from "./models.js";import { estimateScanCost, type ScanCost } from "./cost.js";+import { meetsSeverity, severityThresholdRank } from "./scan-settings.js";export interface TurnResultMetadata {id?: string;@@ -111,6 +113,13 @@ export class ScanResult {return join(this.scanDir, "artifacts");}+ public hasFindingsAtOrAbove(threshold: SeverityLevel): boolean {+ severityThresholdRank(threshold);+ return this.findings.findings.some((finding) =>+ meetsSeverity(finding, threshold),+ );+ }+public toJSON(): Record<string, unknown> {return {manifest: this.manifest,diff --git a/sdk/typescript/src/scan-modes.ts b/sdk/typescript/src/scan-modes.tsnew file mode 100644index 000000000..75925283d--- /dev/null+++ b/sdk/typescript/src/scan-modes.ts@@ -0,0 +1,2 @@+export const SCAN_MODES = ["standard", "deep"] as const;+export type ScanMode = (typeof SCAN_MODES)[number];diff --git a/sdk/typescript/src/scan-settings.ts b/sdk/typescript/src/scan-settings.tsnew file mode 100644index 000000000..9f46321d8--- /dev/null+++ b/sdk/typescript/src/scan-settings.ts@@ -0,0 +1,172 @@+import { z } from "zod";+import { DEFAULT_DEEP_SCAN_SETTINGS } from "./deep-scan-defaults.js";+import { ConfigurationError } from "./errors.js";+import type { Finding, SeverityLevel } from "./models.js";+import type { AbsolutePath } from "./config-path.js";+import { SCAN_MODES, type ScanMode } from "./scan-modes.js";+import type { ScanTarget } from "./targets.js";++export const SCAN_AUTH_MODES = ["auto", "chatgpt", "api-key"] as const;+export type ScanAuthMode = (typeof SCAN_AUTH_MODES)[number];+export const DEFAULT_SCAN_AUTH = "auto";+export const DEFAULT_SCAN_MODE = "standard";+export const REPORTABLE_SEVERITIES = [+ "critical",+ "high",+ "medium",+ "low",+] as const;+export const SCAN_SEVERITIES = [+ ...REPORTABLE_SEVERITIES,+ "informational",+] as const;+export const FailureSeveritySchema = z.enum(REPORTABLE_SEVERITIES);+export type FailureSeverity = z.infer<typeof FailureSeveritySchema>;++// SDK name, legacy TOML key, project key, and CLI flag (when exposed).+export const DEEP_SCAN_SETTINGS = [+ ["workers", "workers", "workers", "--workers"],+ ["subagents", "subagents", "subagents_per_worker", "--subagents"],+ [+ "stopAfterNoNew",+ "stop_after_no_new",+ "stop_after_no_new",+ "--stop-after-no-new",+ ],+ [+ "stopAfterConsecutiveErrors",+ "stop_after_consecutive_errors",+ "stop_after_consecutive_errors",+ null,+ ],+ [+ "maxDiscoveryRuns",+ "max_discovery_runs",+ "max_discovery_runs",+ "--max-discovery-runs",+ ],+ ["maxTimeHours", "max_time_hours", "max_time_hours", "--max-time-hours"],+] as const;++const positiveIntegerError = "must be a positive integer";+const positiveInteger = z+ .number({ error: positiveIntegerError })+ .int({ error: positiveIntegerError })+ .positive({ error: positiveIntegerError });+const nonnegativeIntegerError = "must be a non-negative integer";+const nonnegativeInteger = z+ .number({ error: nonnegativeIntegerError })+ .int({ error: nonnegativeIntegerError })+ .nonnegative({ error: nonnegativeIntegerError });+const maximumHours = 96;+const hoursError = `must be a positive number no greater than ${maximumHours}`;++export const DeepScanSettingsSchema = z.strictObject({+ workers: positiveInteger.optional().meta({+ default: DEFAULT_DEEP_SCAN_SETTINGS.workers,+ description: "Maximum concurrent deep-scan discovery workers.",+ }),+ subagents: nonnegativeInteger.optional().meta({+ default: DEFAULT_DEEP_SCAN_SETTINGS.subagents,+ description: "Subagents available to each deep-scan worker. Zero is valid.",+ }),+ stopAfterNoNew: positiveInteger.optional().meta({+ default: DEFAULT_DEEP_SCAN_SETTINGS.stopAfterNoNew,+ description: "Stop after this many runs find no new issues.",+ }),+ stopAfterConsecutiveErrors: positiveInteger.optional().meta({+ default: DEFAULT_DEEP_SCAN_SETTINGS.stopAfterConsecutiveErrors,+ description: "Stop after this many consecutive discovery errors.",+ }),+ maxDiscoveryRuns: positiveInteger.optional().meta({+ default: DEFAULT_DEEP_SCAN_SETTINGS.maxDiscoveryRuns,+ description: "Maximum deep-scan discovery runs.",+ }),+ maxTimeHours: z+ .number({ error: hoursError })+ .positive({ error: hoursError })+ .max(maximumHours, { error: hoursError })+ .optional()+ .meta({+ default: DEFAULT_DEEP_SCAN_SETTINGS.maxTimeHours,+ description:+ "Maximum deep-scan discovery hours (default: 96; maximum: 96).",+ }),+});++export type DeepScanOptions = z.infer<typeof DeepScanSettingsSchema>;++const inputPath = z.string().min(1);++export const ScanSettingsSchema = DeepScanSettingsSchema.extend({+ auth: z.enum(SCAN_AUTH_MODES).optional().meta({ default: DEFAULT_SCAN_AUTH }),+ mode: z.enum(SCAN_MODES).optional().meta({ default: DEFAULT_SCAN_MODE }),+ knowledgeBasePaths: z.array(inputPath).optional(),+ scanPrompt: z.string().optional(),+ scanPromptFile: inputPath.optional(),+ validationPrompt: z.string().optional(),+ validationPromptFile: inputPath.optional(),+ postScanPrompt: z.string().optional(),+ postScanPromptFile: inputPath.optional(),+ outputDir: inputPath.optional(),+ failureSeverity: z.enum(SCAN_SEVERITIES).optional(),+ maxCostUsd: z.number().positive().optional(),+});++/** Scan settings shared by SDK calls, CLI flags, and project files. */+export interface ScanSettings extends z.infer<typeof ScanSettingsSchema> {+ target?: ScanTarget;+}++export interface ResolvedScanSettings extends ScanSettings {+ auth: ScanAuthMode;+ mode: ScanMode;+ target: ScanTarget;+ knowledgeBasePaths: AbsolutePath[];+ scanPromptFile?: AbsolutePath;+ validationPromptFile?: AbsolutePath;+ postScanPromptFile?: AbsolutePath;+ outputDir?: AbsolutePath;+}++export type ScanPromptSettings = Pick<+ ScanSettings,+ | "scanPrompt"+ | "scanPromptFile"+ | "validationPrompt"+ | "validationPromptFile"+ | "postScanPrompt"+ | "postScanPromptFile"+>;++/** Pick defined scan settings without copying callbacks or workflow controls. */+export function pickScanSettings(settings: ScanSettings): ScanSettings {+ const keys = [+ "target",+ ...Object.keys(ScanSettingsSchema.shape),+ ] as (keyof ScanSettings)[];+ return Object.fromEntries(+ keys+ .filter((key) => settings[key] !== undefined)+ .map((key) => [key, settings[key]]),+ ) as ScanSettings;+}++export function meetsSeverity(+ finding: Pick<Finding, "severity">,+ threshold: SeverityLevel,+): boolean {+ const thresholdRank = severityThresholdRank(threshold);+ const severity = SCAN_SEVERITIES.indexOf(finding.severity.level);+ return severity >= 0 && severity <= thresholdRank;+}++export function severityThresholdRank(threshold: SeverityLevel): number {+ const rank = SCAN_SEVERITIES.indexOf(threshold);+ if (rank < 0) {+ throw new ConfigurationError(+ `Unknown severity threshold: ${String(threshold)}.`,+ );+ }+ return rank;+}diff --git a/sdk/typescript/src/targets.ts b/sdk/typescript/src/targets.tsindex c1480b5dc..53b440bc4 100644--- a/sdk/typescript/src/targets.ts+++ b/sdk/typescript/src/targets.ts@@ -16,6 +16,9 @@ import { InvalidTargetError } from "./errors.js";import { resolveTrustedExecutable } from "./trusted-executable.js";import { windowsUnsafePathComponent } from "./windows-path.js";+import type { ScanMode } from "./scan-modes.js";+export type { ScanMode } from "./scan-modes.js";+const execFile = promisify(execFileCallback);const UNSUPPORTED_GIT_ENVIRONMENT = new Set(["GIT_DIR",@@ -38,7 +41,6 @@ const GIT_REPOSITORY_ENVIRONMENT = new Set(["GIT_SHALLOW_FILE",]);-export type ScanMode = "standard" | "deep";export type DiffTargetKind = "refs" | "working_tree";export interface DiffTargetOptions {diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.tsindex e04523354..68fa92e1a 100644--- a/sdk/typescript/tests-ts/api.test.ts+++ b/sdk/typescript/tests-ts/api.test.ts@@ -15,7 +15,7 @@ import * as fsPromises from "node:fs/promises";import { execFileSync } from "node:child_process";import { createHash } from "node:crypto";import { existsSync } from "node:fs";-import { basename, delimiter, dirname, join, win32 } from "node:path";+import { basename, delimiter, dirname, join, relative, win32 } from "node:path";import { fileURLToPath, pathToFileURL } from "node:url";import {Codex,@@ -71,6 +71,7 @@ import {} from "./support/api-events.js";import { runTestInSubprocess } from "./support/test-subprocess.js";import { FindingWorkflow } from "../src/finding-workflow.js";+import { DEFAULT_DEEP_SCAN_SETTINGS } from "../src/deep-scan-defaults.js";type ScanObserverName = Parameters<NonNullable<ScanOptions["onObserverError"]>@@ -82,7 +83,7 @@ const { cleanup, copyCompletedScan, temporaryDirectory } =createApiTestFixtures();afterEach(cleanup);-test.each(["completed", "receipt-lost", "scan-interrupted"])(+test.each(["completed", "receipt-lost", "scan-interrupted", "prompt-files"])("durable scan workflow resumes after %s without rerunning completed work",async (scenario) => {const root = await temporaryDirectory();@@ -98,6 +99,9 @@ test.each(["completed", "receipt-lost", "scan-interrupted"])(CODEX_SECURITY_STATE_DIR: join(root, "state"),};const workflowId = "durable-scan";+ const scanPrompt = "Review synthetic authentication boundaries.";+ const promptFile = join(root, "instructions.md");+ if (scenario === "prompt-files") await writeFile(promptFile, scanPrompt);let modelCalls = 0;let completed = false;let loseReceipt = scenario === "receipt-lost";@@ -123,7 +127,10 @@ test.each(["completed", "receipt-lost", "scan-interrupted"])(loseReceipt = false;throw new Error("Synthetic receipt write failure");}- return await runWorkbench(options, args, input);+ const state = await runWorkbench(options, args, input);+ if (scenario === "prompt-files" && payload.action === "begin")+ await rm(promptFile);+ return state;}if (args[0] === "get-scan")return {@@ -147,8 +154,10 @@ test.each(["completed", "receipt-lost", "scan-interrupted"])(createCodex: () => ({startThread: () => ({id: "thread-1",- async runStreamed() {+ async runStreamed(input: string) {modelCalls++;+ if (scenario === "prompt-files")+ expect(input).toContain(scanPrompt);if (scenario === "scan-interrupted" && modelCalls === 1)throw new Error("Synthetic interrupted scan");await copyCompletedScan(root);@@ -162,8 +171,15 @@ test.each(["completed", "receipt-lost", "scan-interrupted"])(const first = await makeClient(1);let original: Record<string, unknown> | undefined;try {- if (scenario === "completed")- original = (await first.run(repository, { workflowId })).toJSON();+ if (scenario === "completed" || scenario === "prompt-files")+ original = (+ await first.run(repository, {+ workflowId,+ ...(scenario === "prompt-files"+ ? { scanPromptFile: promptFile }+ : {}),+ })+ ).toJSON();elseawait expect(first.run(repository, { workflowId })).rejects.toThrow("Synthetic",@@ -173,7 +189,12 @@ test.each(["completed", "receipt-lost", "scan-interrupted"])(}const resumed = await makeClient(2);try {- const result = await resumed.run(repository, { workflowId });+ const replacement = join(root, "replacement-instructions.md");+ if (scenario === "prompt-files") await writeFile(replacement, scanPrompt);+ const result = await resumed.run(repository, {+ workflowId,+ ...(scenario === "prompt-files" ? { scanPromptFile: replacement } : {}),+ });expect(result.manifest.scan.id).toBe("scan_example_001");if (original) expect(result.toJSON()).toEqual(original);expect(modelCalls).toBe(scenario === "scan-interrupted" ? 2 : 1);@@ -190,6 +211,60 @@ test.each(["completed", "receipt-lost", "scan-interrupted"])(},);+test.each(["ambient settings", "shipped defaults"])(+ "a deep workflow can resume after changing %s but rejects a different request",+ async (change) => {+ const root = await temporaryDirectory();+ const repository = join(root, "repository");+ const codexHome = join(root, "codex-home");+ const source = join(codexHome, "codex-security", "config.toml");+ await mkdir(repository);+ await mkdir(dirname(source), { recursive: true });+ await writeFile(source, "[deep_scan]\nsubagents = 1\n");+ const environment = {+ PATH: process.env["PATH"],+ SystemRoot: process.env["SystemRoot"],+ CODEX_HOME: codexHome,+ CODEX_SECURITY_STATE_DIR: join(root, "state"),+ };+ const client = new TestClient(+ {},+ {+ environment,+ runWorkbench: async (options, args, input) => {+ if (+ args[0] === "finding-workflow" &&+ JSON.parse(input!).action === "begin"+ ) {+ throw new Error("Synthetic stop before scan");+ }+ return runWorkbench(options, args, input);+ },+ },+ );+ const defaults = DEFAULT_DEEP_SCAN_SETTINGS as { workers: number };+ const originalWorkers = defaults.workers;+ const request = { workflowId: "deep-resume", mode: "deep" } as const;+ try {+ await expect(client.run(repository, request)).rejects.toThrow(+ "Synthetic stop before scan",+ );+ if (change === "ambient settings")+ await writeFile(source, "[deep_scan]\nworkers = 9\nsubagents = 2\n");+ else defaults.workers = originalWorkers + 1;+ await expect(client.run(repository, request)).rejects.toThrow(+ "Synthetic stop before scan",+ );+ await expect(+ client.run(repository, { ...request, workers: 2 }),+ ).rejects.toThrow("already bound to a different");+ } finally {+ defaults.workers = originalWorkers;+ await client.close();+ }+ },+);+const EXTERNAL_PROVIDER_CASES = [["OpenRouter",@@ -767,7 +842,10 @@ describe("CodexSecurity orchestration", () => {const client = new TestClient({ pythonPath: "/definitely/missing/python" },{- environment: { OPENAI_API_KEY: "must-not-be-used" },+ environment: {+ OPENAI_API_KEY: "must-not-be-used",+ CODEX_HOME: join(root, "ambient"),+ },prepareRuntime: async () => {runtimeStarted = true;throw new Error("runtime should not initialize");@@ -785,6 +863,20 @@ describe("CodexSecurity orchestration", () => {repository,target: { kind: "paths", paths: ["src"] },mode: "deep",+ workers: 4,+ subagents: 3,+ stopAfterNoNew: 4,+ stopAfterConsecutiveErrors: 3,+ maxDiscoveryRuns: 40,+ maxTimeHours: 96,+ deepScanSources: {+ workers: "default",+ subagents: "default",+ stopAfterNoNew: "default",+ stopAfterConsecutiveErrors: "default",+ maxDiscoveryRuns: "default",+ maxTimeHours: "default",+ },outputDir: output,authentication: {method: "api_key",@@ -1637,7 +1729,7 @@ describe("CodexSecurity orchestration", () => {await client.close();});- test("isolates resolved Deep worker summaries across concurrent Bedrock scans", async () => {+ test("isolates resolved Deep settings across concurrent Bedrock scans", async () => {const root = await temporaryDirectory();const repository = join(root, "repository");const stateDirectory = join(root, "state");@@ -1668,6 +1760,7 @@ describe("CodexSecurity orchestration", () => {release = resolve;});const configPaths = new Set<string>();+ const deepConfigPaths = new Set<string>();const manifest = JSON.parse(await readFile(join(PLUGIN_ROOT, ".mcp.json"), "utf8"),) as {@@ -1712,6 +1805,18 @@ describe("CodexSecurity orchestration", () => {mcpEnvironment["CODEX_SECURITY_CONFIG_PATH"];expect(typeof configPath).toBe("string");configPaths.add(configPath!);+ const deepConfigPath =+ mcpEnvironment["CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH"]!;+ deepConfigPaths.add(deepConfigPath);+ expect(+ parseToml(await readFile(deepConfigPath, "utf8"))[+ "deep_scan"+ ],+ ).toMatchObject({+ workers: index + 1,+ subagents: index,+ stop_after_consecutive_errors: index + 2,+ });const config = parseToml(await readFile(configPath!, "utf8"),) as JsonObject;@@ -1740,8 +1845,15 @@ describe("CodexSecurity orchestration", () => {);try {const results = await Promise.allSettled(- clients.map((client) =>- client.run(repository, { mode: "deep" }).finally(release),+ clients.map((client, index) =>+ client+ .run(repository, {+ mode: "deep",+ workers: index + 1,+ subagents: index,+ stopAfterConsecutiveErrors: index + 2,+ })+ .finally(release),),);for (const result of results)@@ -1753,6 +1865,7 @@ describe("CodexSecurity orchestration", () => {});expect(started).toBe(scenarios.length);expect(configPaths.size).toBe(scenarios.length);+ expect(deepConfigPaths.size).toBe(scenarios.length);} finally {release();await Promise.all(clients.map((client) => client.close()));@@ -2493,10 +2606,17 @@ describe("CodexSecurity orchestration", () => {},);+ const scanPromptFile = join(root, "instructions.md");+ const postScanPromptFile = join(root, "follow-up.md");+ await writeFile(+ scanPromptFile,+ "Focus on authentication and authorization.",+ );+ await writeFile(postScanPromptFile, "Draft fixes for confirmed findings.");const scanStartedAt = Date.now();const result = await client.run(repository, {- scanPrompt: "Focus on authentication and authorization.",- postScanPrompt: "Draft fixes for confirmed findings.",+ scanPromptFile,+ postScanPromptFile,onScanStarted: () => {scanStarted = true;},@@ -2707,7 +2827,7 @@ describe("CodexSecurity orchestration", () => {await client.close();});- test("applies deep scan overrides over the user's existing settings", async () => {+ test("resolves deep settings before runtime preparation and records the snapshot", async () => {const root = await temporaryDirectory();const repository = join(root, "repository");const ambientHome = join(root, "ambient-home");@@ -2736,7 +2856,13 @@ describe("CodexSecurity orchestration", () => {{},{environment: { CODEX_HOME: ambientHome },- prepareRuntime: async () => preparedRuntime(codexHome),+ prepareRuntime: async () => {+ await writeFile(+ join(ambientHome, "codex-security", "config.toml"),+ "[deep_scan]\nstop_after_no_new = 99\n",+ );+ return preparedRuntime(codexHome);+ },resolvePluginPython: async () => "/managed/python",prepareOutputDir: async () => scanDir,repositoryRevision: async () => "deadbeef",@@ -2770,8 +2896,10 @@ describe("CodexSecurity orchestration", () => {await expect(client.run(repository, {mode: "deep",+ auth: "auto",workers: 2,subagents: 0,+ stopAfterConsecutiveErrors: 2,maxDiscoveryRuns: 10,maxTimeHours: 1.5,}),@@ -2783,15 +2911,20 @@ describe("CodexSecurity orchestration", () => {expect(configuration).toContain("workers = 2");expect(configuration).toContain("subagents = 0");expect(configuration).toContain("stop_after_no_new = 7");+ expect(configuration).toContain("stop_after_consecutive_errors = 2");expect(configuration).toContain("max_discovery_runs = 10");expect(configuration).toContain("max_time_hours = 1.5");expect(configuration).toContain("[other]");expect(configuration).toContain("enabled = true");expect(recipe).toMatchObject({mode: "deep",+ auth: "auto",+ deepScanResolved: true,deepScan: {workers: 2,subagents: 0,+ stopAfterNoNew: 7,+ stopAfterConsecutiveErrors: 2,maxDiscoveryRuns: 10,maxTimeHours: 1.5,},@@ -2988,8 +3121,15 @@ describe("CodexSecurity orchestration", () => {await expect(client.run(repository, { mode: "deep" })).rejects.toThrow("deep scan settings captured",);- await expect(fsPromises.lstat(runtimeConfig)).rejects.toMatchObject({- code: "ENOENT",+ expect(+ parseToml(await readFile(runtimeConfig, "utf8"))["deep_scan"],+ ).toEqual({+ workers: 4,+ subagents: 3,+ stop_after_no_new: 4,+ stop_after_consecutive_errors: 3,+ max_discovery_runs: 40,+ max_time_hours: 96,});await writeFile(ambientConfig, "[deep_scan]\nworkers = 7\n");@@ -3002,47 +3142,99 @@ describe("CodexSecurity orchestration", () => {},);- test("preserves ambient configuration when the deep-scan runtime uses the same home", async () => {- const root = await temporaryDirectory();- const repository = join(root, "repository");- const codexHome = join(root, "codex-home");- const scanDir = join(root, "scan");- const configPath = join(codexHome, "codex-security", "config.toml");- const originalConfiguration = "[other]\nenabled = true\n";- await mkdir(repository);- await mkdir(join(codexHome, "codex-security"), { recursive: true });- await writeFile(configPath, originalConfiguration);- await mkdir(scanDir, { mode: 0o700 });+ test.each([+ ["defaults", "absolute"],+ ["complete overrides", "absolute"],+ ["missing configuration", "absolute"],+ ["missing configuration", "relative"],+ ] as const)(+ "preserves ambient configuration when the deep-scan runtime uses the same home with %s (%s path)",+ async (settings, homeKind) => {+ const root = await temporaryDirectory();+ const repository = join(root, "repository");+ const codexHome = join(root, "codex-home");+ const scanDir = join(root, "scan");+ const configPath = join(codexHome, "codex-security", "config.toml");+ const originalConfiguration = "[other]\nenabled = true\n";+ await mkdir(repository);+ await mkdir(join(codexHome, "codex-security"), { recursive: true });+ if (settings !== "missing configuration")+ await writeFile(configPath, originalConfiguration);+ await mkdir(scanDir, { mode: 0o700 });- const client = new TestClient(- {},- {- environment: { CODEX_HOME: codexHome },- prepareRuntime: async () => preparedRuntime(codexHome),- resolvePluginPython: async () => "/managed/python",- prepareOutputDir: async () => scanDir,- repositoryRevision: async () => "deadbeef",- createCodex: () => ({- startThread: () => ({- id: null,- async runStreamed() {- throw new Error("deep scan settings captured");- },+ await using client = new TestClient(+ {},+ {+ environment: {+ CODEX_HOME:+ homeKind === "relative"+ ? relative(process.cwd(), codexHome)+ : codexHome,+ },+ prepareRuntime: async () => preparedRuntime(codexHome),+ resolvePluginPython: async () => "/managed/python",+ prepareOutputDir: async () => scanDir,+ repositoryRevision: async () => "deadbeef",+ createCodex: () => ({+ startThread: () => ({+ id: null,+ async runStreamed() {+ throw new Error("deep scan settings captured");+ },+ }),}),- }),- },- );+ },+ );- await expect(client.run(repository, { mode: "deep" })).rejects.toThrow(- "deep scan settings captured",- );- expect(await readFile(configPath, "utf8")).toBe(originalConfiguration);- await client.close();- });+ await expect(+ client.run(repository, {+ mode: "deep",+ ...(settings === "complete overrides"+ ? {+ workers: 2,+ subagents: 0,+ stopAfterNoNew: 7,+ stopAfterConsecutiveErrors: 2,+ maxDiscoveryRuns: 12,+ maxTimeHours: 1.5,+ }+ : {}),+ }),+ ).rejects.toThrow("deep scan settings captured");+ if (settings === "missing configuration") {+ await expect(readFile(configPath)).rejects.toMatchObject({+ code: "ENOENT",+ });+ } else {+ const written = await readFile(configPath, "utf8");+ if (settings === "defaults") {+ expect(written).toBe(originalConfiguration);+ } else {+ expect(parseToml(written)).toEqual({+ other: { enabled: true },+ deep_scan: {+ workers: 2,+ subagents: 0,+ stop_after_no_new: 7,+ stop_after_consecutive_errors: 2,+ max_discovery_runs: 12,+ max_time_hours: 1.5,+ },+ });+ }+ }+ },+ );- test.skipIf(process.platform !== "win32")(- "preserves ambient configuration when the same Windows home uses different casing",- async () => {+ test+ .skipIf(process.platform !== "win32")+ .each([+ "existing configuration",+ "missing configuration",+ "missing configuration directory",+ ])(+ "preserves ambient configuration when the same Windows home uses different casing with %s",+ async (state) => {const root = await temporaryDirectory();const repository = join(root, "repository");const codexHome = join(root, "codex-home");@@ -3050,11 +3242,14 @@ describe("CodexSecurity orchestration", () => {const configPath = join(codexHome, "codex-security", "config.toml");const originalConfiguration = "[other]\nenabled = true\n";await mkdir(repository);- await mkdir(join(codexHome, "codex-security"), { recursive: true });- await writeFile(configPath, originalConfiguration);+ await mkdir(codexHome);+ if (state !== "missing configuration directory")+ await mkdir(join(codexHome, "codex-security"));+ if (state === "existing configuration")+ await writeFile(configPath, originalConfiguration);await mkdir(scanDir, { mode: 0o700 });- const client = new TestClient(+ await using client = new TestClient({},{environment: { CODEX_HOME: codexHome.toUpperCase() },@@ -3076,8 +3271,13 @@ describe("CodexSecurity orchestration", () => {await expect(client.run(repository, { mode: "deep" })).rejects.toThrow("deep scan settings captured",);- expect(await readFile(configPath, "utf8")).toBe(originalConfiguration);- await client.close();+ if (state === "existing configuration") {+ expect(await readFile(configPath, "utf8")).toBe(originalConfiguration);+ } else {+ await expect(readFile(configPath)).rejects.toMatchObject({+ code: "ENOENT",+ });+ }},);diff --git a/sdk/typescript/tests-ts/cli-project-config.test.ts b/sdk/typescript/tests-ts/cli-project-config.test.tsnew file mode 100644index 000000000..a1d6a9cda--- /dev/null+++ b/sdk/typescript/tests-ts/cli-project-config.test.ts@@ -0,0 +1,1254 @@+import {+ mkdir,+ mkdtemp,+ readFile,+ realpath,+ rm,+ symlink,+ writeFile,+} from "node:fs/promises";+import { execFileSync } from "node:child_process";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, expect, test } from "bun:test";+import { CodexSecurity, type ScanOptions } from "../src/api.js";+import { main } from "../src/cli.js";+import type { CodexSecurityConfig, JsonObject } from "../src/config.js";+import type { ProjectConfigInput } from "../src/project-config-schema.js";+import { readProjectConfig } from "../src/project-config.js";+import {+ capture,+ dependencies,+ fakePreflight,+ fakeResult,+} from "./cli-fixtures.js";++const directories: string[] = [];+afterEach(async () => {+ await Promise.all(+ directories+ .splice(0)+ .map((path) => rm(path, { recursive: true, force: true })),+ );+});++async function fixture(input: ProjectConfigInput | string) {+ const root = await realpath(+ await mkdtemp(join(tmpdir(), "cli-project-config-")),+ );+ directories.push(root);+ const repository = join(root, "repository");+ const configDirectory = join(root, "settings");+ await mkdir(repository);+ await mkdir(configDirectory);+ await mkdir(join(repository, "src"));+ await mkdir(join(repository, "lib"));+ const config = join(+ configDirectory,+ typeof input === "string" ? "scan.yaml" : "scan.json",+ );+ await writeFile(+ config,+ typeof input === "string" ? input : JSON.stringify(input),+ );+ return { root, repository, configDirectory, config };+}++test.each([+ [undefined, "./node_modules"],+ ["starter.json", "./node_modules"],+ ["settings/starter.yaml", "../node_modules"],+ ["settings/starter.json", "../node_modules"],+])(+ "init writes a valid unpinned starter and refuses overwrites: %s",+ async (file, modules) => {+ const input = await fixture({});+ const args = ["init", ...(file === undefined ? [] : [file]), "--json"];+ const output = capture();+ const deps = dependencies({+ currentDirectory: input.root,+ onConfig: () => {+ throw new Error("No runtime for init");+ },+ });+ expect(await main(args, output.stream, capture().stream, deps)).toBe(0);+ const path = join(input.root, file ?? "codex-security.yaml");+ expect(JSON.parse(output.text())).toEqual({ path });+ const selected = await readProjectConfig(path);+ expect(selected.input).toEqual({+ $schema: `${modules}/@openai/codex-security/schemas/project-config.schema.json`,+ });+ const contents = await readFile(path, "utf8");+ expect(await main(args, capture().stream, capture().stream, deps)).toBe(2);+ expect(await readFile(path, "utf8")).toBe(contents);+ },+);++test("info resolves a config and its sources without a target, prompt reads, or runtime", async () => {+ const input = await fixture({+ scan: {+ mode: "deep",+ instructions_file: "not-read.md",+ deep: { workers: 2 },+ },+ codex: {+ model: "gpt-5.6-terra",+ synthetic_private_setting: "synthetic-private-value",+ },+ });+ const home = join(input.root, "home");+ await mkdir(join(home, "codex-security"), { recursive: true });+ await writeFile(+ join(home, "codex-security", "config.toml"),+ "[deep_scan]\nsubagents = 1\n",+ );+ const stdout = capture();+ expect(+ await main(+ ["info", "-c", input.config, "--json"],+ stdout.stream,+ capture().stream,+ dependencies({+ currentDirectory: input.configDirectory,+ environment: { CODEX_HOME: home },+ onConfig: () => {+ throw new Error("No runtime for info");+ },+ }),+ ),+ ).toBe(0);+ expect(stdout.text()).not.toContain("synthetic-private-value");+ expect(JSON.parse(stdout.text())).toMatchObject({+ model: "gpt-5.6-terra",+ configuration: {+ path: input.config,+ settings: {+ mode: "deep",+ workers: 2,+ subagents: 1,+ scanPromptFile: join(input.configDirectory, "not-read.md"),+ },+ sources: {+ "scan.deep.workers": "project",+ "scan.deep.subagents_per_worker": "legacy",+ "scan.deep.max_time_hours": "default",+ "policy.fail_on_severity": "default",+ },+ },+ });+});++test("info without a file reports default sources, including unset settings", async () => {+ const input = await fixture({});+ const stdout = capture();+ expect(+ await main(+ ["info", "--json", "--filter-output", "configuration"],+ stdout.stream,+ capture().stream,+ dependencies({ currentDirectory: input.root }),+ ),+ ).toBe(0);+ expect(JSON.parse(stdout.text())).toMatchObject({+ configuration: {+ sources: {+ auth: "default",+ "scan.mode": "default",+ "scan.scope": "default",+ "scan.knowledge_base": "default",+ "scan.instructions_file": "default",+ "scan.validation_file": "default",+ "output.directory": "default",+ "policy.fail_on_severity": "default",+ "limits.max_cost_usd_per_scan": "default",+ },+ },+ });+});++test("an explicit config flag overrides the operator-selected environment file", async () => {+ const input = await fixture({ codex: { model: "gpt-5.6-terra" } });+ const override = join(input.root, "override.json");+ await writeFile(+ override,+ JSON.stringify({ codex: { model: "gpt-5.6-sol" } }),+ );+ for (const [flags, expected] of [+ [[], "gpt-5.6-terra"],+ [["-c", override], "gpt-5.6-sol"],+ ] as const) {+ let selected: CodexSecurityConfig | undefined;+ expect(+ await main(+ ["scan", ...flags, "--json"],+ capture().stream,+ capture().stream,+ dependencies({+ currentDirectory: input.repository,+ environment: { CODEX_SECURITY_PROJECT_CONFIG: input.config },+ onConfig: (config) => {+ selected = config;+ },+ }),+ ),+ ).toBe(0);+ expect(selected?.codexOverrides?.["model"]).toBe(expected);+ }+});++test("a missing operator-selected environment file fails without falling back", async () => {+ const input = await fixture({});+ let initialized = false;+ expect(+ await main(+ ["scan", "--json"],+ capture().stream,+ capture().stream,+ dependencies({+ currentDirectory: input.repository,+ environment: {+ CODEX_SECURITY_PROJECT_CONFIG: join(input.root, "missing.yaml"),+ },+ onConfig: () => {+ initialized = true;+ },+ }),+ ),+ ).toBe(2);+ expect(initialized).toBe(false);+});++test.each([123, "", " "])(+ "a selected profile's invalid model is reported at the provider flag: %j",+ async (model) => {+ const input = await fixture({+ codex: { profile: "selected", profiles: { selected: { model } } },+ });+ let initialized = false;+ const stderr = capture();+ expect(+ await main(+ ["scan", "-c", input.config, "--provider", "amazon-bedrock", "--json"],+ capture().stream,+ stderr.stream,+ dependencies({+ currentDirectory: input.repository,+ onConfig: () => {+ initialized = true;+ },+ }),+ ),+ ).toBe(2);+ expect(stderr.text()).toContain(+ "--model must be a nonempty string when using --provider amazon-bedrock",+ );+ expect(initialized).toBe(false);+ },+);++test("rerun rejects a blank replacement when scan instructions are required", async () => {+ const input = await fixture({});+ const prompt = join(input.root, "empty.md");+ await writeFile(prompt, " \n");+ const stderr = capture();+ let initialized = false;+ expect(+ await main(+ ["scans", "rerun", "saved", "--scan-prompt-file", prompt, "--json"],+ capture().stream,+ stderr.stream,+ dependencies({+ currentDirectory: input.root,+ onWorkbench: async () => ({+ recipe: {+ repository: input.repository,+ target: { kind: "repository", paths: [] },+ mode: "standard",+ config: {},+ requiresScanPrompt: true,+ },+ }),+ onConfig: () => {+ initialized = true;+ },+ }),+ ),+ ).toBe(2);+ expect(stderr.text()).toContain("--scan-prompt-file must not be empty");+ expect(initialized).toBe(false);+});++test.each(["instructions_file", "validation_file"] as const)(+ "bulk %s retains directory-link protection for local CSV repositories",+ async (file) => {+ const input = await fixture({+ scan: { [file]: "../repository/linked/prompt.md" },+ output: { directory: "../batch-results" },+ });+ const external = join(input.root, "external");+ await mkdir(external);+ await writeFile(join(external, "prompt.md"), "Synthetic external data.");+ await symlink(external, join(input.repository, "linked"), "junction");+ const csv = join(input.root, "repositories.csv");+ await writeFile(+ csv,+ `id,repository,revision\nsource,${input.repository},${"a".repeat(40)}\n`,+ );+ let initialized = false;+ const stderr = capture();+ const exit = await main(+ ["bulk-scan", csv, "-c", input.config, "--json"],+ capture().stream,+ stderr.stream,+ dependencies({+ currentDirectory: input.repository,+ onConfig: () => {+ initialized = true;+ throw new Error("Runtime must not start");+ },+ }),+ );+ expect(exit).toBe(2);+ expect(stderr.text()).toContain(+ "Input files must not follow repository directory links",+ );+ expect(initialized).toBe(false);+ },+);++test("bulk scans apply config and linked operator prompts, preserve CSV scope overrides, and retain the policy on resume", async () => {+ const config: ProjectConfigInput = {+ auth: "api-key",+ scan: {+ scope: { paths: ["src"] },+ knowledge_base: ["context.md"],+ instructions_file: "linked/instructions.md",+ deep: { workers: 2, subagents_per_worker: 0 },+ },+ codex: { model: "gpt-5.6-terra" },+ limits: { max_cost_usd_per_scan: 5 },+ policy: { fail_on_severity: "high" },+ output: { directory: "../batch-results" },+ };+ const input = await fixture(config);+ const promptDirectory = await realpath(+ await mkdtemp(join(tmpdir(), "bulk-operator-prompts-")),+ );+ directories.push(promptDirectory);+ await symlink(+ promptDirectory,+ join(input.configDirectory, "linked"),+ "junction",+ );+ await writeFile(+ join(input.configDirectory, "context.md"),+ "Synthetic context.",+ );+ await writeFile(+ join(promptDirectory, "instructions.md"),+ "Review synthetic boundaries.",+ );+ await writeFile(+ join(input.repository, "src", "index.ts"),+ "export const value = 1;\n",+ );+ await writeFile(+ join(input.repository, "lib", "index.ts"),+ "export const value = 2;\n",+ );+ for (const args of [+ ["init", "-q", input.repository],+ ["-C", input.repository, "add", "."],+ [+ "-C",+ input.repository,+ "-c",+ "user.name=Test",+ "-c",+ "[email protected]",+ "-c",+ "commit.gpgsign=false",+ "commit",+ "-qm",+ "fixture",+ ],+ ])+ execFileSync("git", args);+ const revision = execFileSync(+ "git",+ ["-C", input.repository, "rev-parse", "HEAD"],+ { encoding: "utf8" },+ ).trim();+ const csv = join(input.root, "repositories.csv");+ await writeFile(+ csv,+ `id,repository,revision,mode,scope\nstandard,${input.repository},${revision},standard,lib\ndeep,${input.repository},${revision},deep,\n`,+ );+ const selected: ScanOptions[] = [];+ const deps = dependencies({ currentDirectory: input.root });+ deps.createSecurity = (native) => {+ expect(native.codexOverrides?.["model"]).toBe("gpt-5.6-terra");+ return {+ preflight: async () => fakePreflight(),+ close: async () => {},+ run: async (_repository, options = {}) => {+ selected.push(options);+ const result = fakeResult(["high"]);+ await mkdir(options.outputDir!, { recursive: true });+ for (const [name, content] of Object.entries({+ "scan-manifest.json": result.manifest,+ "findings.json": result.findings,+ "coverage.json": result.coverage,+ "report.md": "Synthetic report.",+ }))+ await writeFile(+ join(options.outputDir!, name),+ typeof content === "string" ? content : JSON.stringify(content),+ );+ return result;+ },+ };+ };+ const args = [+ "bulk-scan",+ csv,+ "-c",+ input.config,+ "--max-cost",+ "3",+ "--json",+ ];+ const output = capture();+ expect(await main(args, output.stream, capture().stream, deps)).toBe(1);+ expect(JSON.parse(output.text())).toMatchObject({+ completed: 2,+ failed: 0,+ policyFailed: true,+ });+ expect(selected.find((options) => options.mode === "standard")).toMatchObject(+ {+ target: ["lib"],+ auth: "api-key",+ maxCostUsd: 3,+ failureSeverity: "high",+ knowledgeBasePaths: [join(input.configDirectory, "context.md")],+ scanPrompt: "Review synthetic boundaries.",+ },+ );+ expect(+ selected.find((options) => options.mode === "standard")?.workers,+ ).toBeUndefined();+ expect(selected.find((options) => options.mode === "deep")).toMatchObject({+ target: ["src"],+ workers: 2,+ subagents: 0,+ });+ const resumed = capture();+ expect(await main(args, resumed.stream, capture().stream, deps)).toBe(1);+ expect(JSON.parse(resumed.text())).toMatchObject({+ skipped: 2,+ policyFailed: true,+ });+ expect(selected).toHaveLength(2);+ await writeFile(+ input.config,+ JSON.stringify({ ...config, policy: { fail_on_severity: "low" } }),+ );+ const stderr = capture();+ expect(await main(args, capture().stream, stderr.stream, deps)).toBe(2);+ expect(stderr.text()).toContain("manifest does not match");+ expect(selected).toHaveLength(2);+});++test.each(["standard", "deep"] as const)(+ "component scans honor shared %s settings and severity policy",+ async (mode) => {+ const input = await fixture({+ scan: {+ mode,+ scope: { paths: ["src"] },+ instructions_file: "instructions.md",+ ...(mode === "standard" ? { validation_file: "validation.md" } : {}),+ deep: { workers: 2, subagents_per_worker: 0 },+ },+ codex: { model: "gpt-5.6-terra" },+ policy: { fail_on_severity: "high" },+ output: { directory: "../component-results" },+ });+ await writeFile(+ join(input.repository, "lib", "index.ts"),+ "export const value = 1;\n",+ );+ await writeFile(+ join(input.configDirectory, "instructions.md"),+ "Review synthetic boundaries.",+ );+ await writeFile(+ join(input.configDirectory, "validation.md"),+ "Validate synthetic boundaries.",+ );+ let selected: ScanOptions | undefined;+ const stdout = capture();+ expect(+ await main(+ [+ "scan-components",+ input.repository,+ "-c",+ input.config,+ "--component",+ "lib",+ "--headless",+ "--json",+ ],+ stdout.stream,+ capture().stream,+ dependencies({+ currentDirectory: input.root,+ result: fakeResult(["high"]),+ onTurn: (_repository, options) => {+ selected = options as ScanOptions;+ },+ }),+ ),+ ).toBe(1);+ expect(selected).toMatchObject({+ mode,+ target: ["lib"],+ scanPrompt: "Review synthetic boundaries.",+ failureSeverity: "high",+ });+ if (mode === "deep")+ expect(selected).toMatchObject({ workers: 2, subagents: 0 });+ else+ expect(selected?.validationPrompt).toBe("Validate synthetic boundaries.");+ expect(JSON.parse(stdout.text())).toMatchObject({+ completed: 1,+ failed: 0,+ policyFailed: true,+ });+ },+);++test("actual CLI parsing preserves file values when flags are absent", async () => {+ const input = await fixture({+ auth: "api-key",+ scan: {+ mode: "deep",+ scope: { paths: ["src"] },+ deep: {+ workers: 8,+ subagents_per_worker: 0,+ stop_after_consecutive_errors: 2,+ },+ },+ limits: { max_cost_usd_per_scan: 7 },+ policy: { fail_on_severity: "high" },+ codex: { model: "gpt-5.6-terra", model_reasoning_effort: "high" },+ });+ let selected: ScanOptions | undefined;+ let native: CodexSecurityConfig | undefined;+ let repository: string | undefined;+ const stdout = capture();+ const stderr = capture();+ expect(+ await main(+ ["scan", "-c", input.config, "--json"],+ stdout.stream,+ stderr.stream,+ dependencies({+ currentDirectory: input.repository,+ environment: { OPENAI_API_KEY: "synthetic-test-key" },+ onConfig: (value) => {+ native = value;+ },+ onTurn: (target, value) => {+ repository = target;+ selected = value as ScanOptions;+ },+ result: fakeResult(["high"]),+ }),+ ),+ ).toBe(1);+ expect(repository).toBe(input.repository);+ expect(selected).toMatchObject({+ auth: "api-key",+ mode: "deep",+ target: ["src"],+ workers: 8,+ subagents: 0,+ stopAfterConsecutiveErrors: 2,+ maxCostUsd: 7,+ failureSeverity: "high",+ });+ expect(native?.codexOverrides).toMatchObject({+ model: "gpt-5.6-terra",+ model_reasoning_effort: "high",+ });+ expect(JSON.parse(stdout.text())).toMatchObject({+ manifest: { scan: { status: "completed" } },+ });+});++test("CLI values override matching file values, including native objects and lists", async () => {+ const input = await fixture({+ auth: "chatgpt",+ scan: {+ mode: "deep",+ scope: { paths: ["src"] },+ knowledge_base: ["file-context.md"],+ deep: { workers: 8, subagents_per_worker: 3 },+ },+ limits: { max_cost_usd_per_scan: 7 },+ policy: { fail_on_severity: "high" },+ codex: {+ model: "gpt-5.6-sol",+ synthetic_setting: { enabled: true, names: ["first"] },+ },+ });+ let selected: ScanOptions | undefined;+ let native: CodexSecurityConfig | undefined;+ expect(+ await main(+ [+ "scan",+ "--config",+ input.config,+ "--auth",+ "auto",+ "--path",+ "lib",+ "--knowledge-base",+ "cli-context.md",+ "--subagents",+ "0",+ "--workers",+ "2",+ "--max-cost",+ "3",+ "--fail-on-severity",+ "low",+ "--model",+ "gpt-5.6-terra",+ "--codex",+ "synthetic_setting.enabled=false",+ "--codex",+ "synthetic_setting.names=[]",+ "--json",+ ],+ capture().stream,+ capture().stream,+ dependencies({+ currentDirectory: input.repository,+ onConfig: (value) => {+ native = value;+ },+ onTurn: (_target, value) => {+ selected = value as ScanOptions;+ },+ }),+ ),+ ).toBe(0);+ expect(selected).toMatchObject({+ auth: "auto",+ mode: "deep",+ target: ["lib"],+ knowledgeBasePaths: [join(input.repository, "cli-context.md")],+ workers: 2,+ subagents: 0,+ maxCostUsd: 3,+ failureSeverity: "low",+ });+ expect(native?.codexOverrides).toMatchObject({+ model: "gpt-5.6-terra",+ synthetic_setting: { enabled: false, names: [] },+ });+});++test("rerun accepts replacement scan and validation files relative to the invocation directory", async () => {+ const input = await fixture({});+ await writeFile(+ join(input.configDirectory, "instructions.md"),+ "Review the synthetic boundary.",+ );+ await writeFile(+ join(input.configDirectory, "validation.md"),+ "Validate the synthetic boundary.",+ );+ const recipe: JsonObject = {+ repository: input.repository,+ target: { kind: "repository", paths: [] },+ mode: "standard",+ config: {},+ requiresScanPrompt: true,+ validationMode: "custom",+ };+ let selected: ScanOptions | undefined;+ const stderr = capture();+ expect(+ await main(+ [+ "scans",+ "rerun",+ "saved",+ "--scan-prompt-file",+ "instructions.md",+ "--validation-prompt-file",+ "validation.md",+ "--json",+ ],+ capture().stream,+ stderr.stream,+ dependencies({+ currentDirectory: input.configDirectory,+ onWorkbench: async () => ({ recipe }),+ onTurn: (_target, options) => {+ selected = options as ScanOptions;+ },+ }),+ ),+ ).toBe(0);+ expect(selected).toMatchObject({+ scanPrompt: "Review the synthetic boundary.",+ validationPrompt: "Validate the synthetic boundary.",+ parentScanId: "saved",+ });+});++test.each([+ [+ { paths: ["src"] },+ ["--diff", "HEAD"],+ { kind: "refs", base: "HEAD", head: "HEAD" },+ ],+ [{ diff: { base: "HEAD", head: "HEAD~1" } }, ["--path", "lib"], ["lib"]],+ [+ { diff: { base: "HEAD", head: "HEAD~1" } },+ ["--head", "HEAD"],+ { kind: "refs", base: "HEAD", head: "HEAD" },+ ],+ [+ { working_tree: {} },+ ["--base", "HEAD~1"],+ { kind: "working_tree", base: "HEAD~1" },+ ],+ [{ working_tree: {} }, ["--no-working-tree"], "repository"],+] as const)(+ "resolves scope %j with overrides %j",+ async (scope, flags, target) => {+ const input = await fixture({+ scan: { scope: structuredClone(scope) },+ } as ProjectConfigInput);+ let selected: ScanOptions | undefined;+ const stderr = capture();+ expect(+ await main(+ ["scan", "-c", input.config, ...flags, "--json"],+ capture().stream,+ stderr.stream,+ dependencies({+ currentDirectory: input.repository,+ onTurn: (_target, value) => {+ selected = value as ScanOptions;+ },+ }),+ ),+ ).toBe(0);+ if (typeof target === "string" || Array.isArray(target))+ expect(selected?.target).toEqual(target);+ else expect(selected?.target).toMatchObject(target);+ },+);++test.each([+ [["--path", "src", "--diff", "HEAD"], "mutually exclusive"],+ [["--head", "HEAD"], "--head requires --diff"],+ [["--base", "HEAD"], "--base requires --working-tree"],+ [["--workers", "2", "--mode", "standard"], "require deep mode"],+ [+ ["--model", "gpt-5.6-terra", "--codex", 'model="gpt-5.6-sol"'],+ "--model conflicts",+ ],+] as const)(+ "rejects incompatible explicit overrides: %j",+ async (flags, message) => {+ const input = await fixture({});+ let initialized = false;+ const stderr = capture();+ expect(+ await main(+ ["scan", "-c", input.config, ...flags, "--json"],+ capture().stream,+ stderr.stream,+ dependencies({+ currentDirectory: input.repository,+ onConfig: () => {+ initialized = true;+ },+ }),+ ),+ ).toBe(2);+ expect(stderr.text()).toContain(message);+ expect(initialized).toBe(false);+ },+);++test("selecting standard mode leaves inactive file deep settings out of the active scan", async () => {+ const input = await fixture({+ scan: {+ mode: "deep",+ deep: { workers: 8, stop_after_consecutive_errors: 2 },+ },+ });+ let selected: ScanOptions | undefined;+ expect(+ await main(+ ["scan", "-c", input.config, "--mode", "standard", "--json"],+ capture().stream,+ capture().stream,+ dependencies({+ currentDirectory: input.repository,+ onTurn: (_target, value) => {+ selected = value as ScanOptions;+ },+ }),+ ),+ ).toBe(0);+ expect(selected?.mode).toBe("standard");+ expect(selected?.workers).toBeUndefined();+ expect(selected?.stopAfterConsecutiveErrors).toBeUndefined();+});++test("file prompts use the config directory and CLI prompt overrides use the invocation directory", async () => {+ const input = await fixture({+ scan: { instructions_file: "scan.md", validation_file: "validate.md" },+ });+ await writeFile(+ join(input.configDirectory, "scan.md"),+ "Synthetic file instructions.",+ );+ await writeFile(+ join(input.configDirectory, "validate.md"),+ "Synthetic file validation.",+ );+ await writeFile(+ join(input.repository, "validate.md"),+ "Synthetic CLI validation.",+ );+ let selected: ScanOptions | undefined;+ expect(+ await main(+ [+ "scan",+ "-c",+ input.config,+ "--validation-prompt-file",+ "validate.md",+ "--json",+ ],+ capture().stream,+ capture().stream,+ dependencies({+ currentDirectory: input.repository,+ onTurn: (_target, value) => {+ selected = value as ScanOptions;+ },+ }),+ ),+ ).toBe(0);+ expect(selected).toMatchObject({+ scanPrompt: "Synthetic file instructions.",+ validationPrompt: "Synthetic CLI validation.",+ });+});++test("an explicit file can supply the model required by a provider override", async () => {+ const input = await fixture({+ codex: { model: "synthetic-model" },+ });+ let native: CodexSecurityConfig | undefined;+ expect(+ await main(+ ["scan", "-c", input.config, "--provider", "amazon-bedrock", "--json"],+ capture().stream,+ capture().stream,+ dependencies({+ currentDirectory: input.repository,+ onConfig: (value) => {+ native = value;+ },+ }),+ ),+ ).toBe(0);+ expect(native?.codexOverrides).toMatchObject({+ model: "synthetic-model",+ model_provider: "amazon-bedrock",+ });+});++test.each(["file", "CLI"])(+ "a profile selected by the %s supplies the provider model",+ async (selection) => {+ const overrideProfile = selection === "CLI";+ const input = await fixture({+ codex: {+ profile: overrideProfile ? "other" : "review",+ profiles: {+ review: { model: "synthetic-profile-model" },+ other: { model: "synthetic-other-model" },+ },+ },+ });+ let native: CodexSecurityConfig | undefined;+ expect(+ await main(+ [+ "scan",+ "-c",+ input.config,+ "--provider",+ "amazon-bedrock",+ ...(overrideProfile ? ["--codex", 'profile="review"'] : []),+ "--json",+ ],+ capture().stream,+ capture().stream,+ dependencies({+ currentDirectory: input.repository,+ onConfig: (value) => {+ native = value;+ },+ }),+ ),+ ).toBe(0);+ expect(native?.codexOverrides).toMatchObject({+ profile: "review",+ profiles: { review: { model: "synthetic-profile-model" } },+ model_provider: "amazon-bedrock",+ });+ },+);++test("an unselected file profile does not satisfy the provider model requirement", async () => {+ const input = await fixture({+ codex: {+ profiles: { review: { model: "synthetic-profile-model" } },+ },+ });+ const stderr = capture();+ let initialized = false;+ expect(+ await main(+ ["scan", "-c", input.config, "--provider", "amazon-bedrock", "--json"],+ capture().stream,+ stderr.stream,+ dependencies({+ currentDirectory: input.repository,+ onConfig: () => {+ initialized = true;+ },+ }),+ ),+ ).toBe(2);+ expect(initialized).toBe(false);+ expect(stderr.text()).toContain(+ "--model is required when using --provider amazon-bedrock",+ );+});++test.each([+ { argv: ["scan", "--help"] },+ { argv: ["scan", "--schema", "--json"] },+ { argv: ["info", "--json"] },+])("malformed unselected files do not affect %j", async ({ argv }) => {+ const input = await fixture("scan: [");+ await writeFile(join(input.repository, "codex-security.yaml"), "scan: [");+ let initialized = false;+ expect(+ await main(+ [...argv],+ capture().stream,+ capture().stream,+ dependencies({+ currentDirectory: input.repository,+ onConfig: () => {+ initialized = true;+ },+ }),+ ),+ ).toBe(0);+ expect(initialized).toBe(false);+});++test.each(["--help", "--schema"])(+ "%s does not load even an explicitly selected invalid file",+ async (flag) => {+ const input = await fixture("scan: [");+ const stdout = capture();+ expect(+ await main(+ ["scan", "-c", input.config, flag, "--json"],+ stdout.stream,+ capture().stream,+ dependencies({ currentDirectory: input.repository }),+ ),+ ).toBe(0);+ if (flag === "--schema")+ expect(JSON.parse(stdout.text())).toMatchObject({+ options: { properties: { config: { type: "string" } } },+ });+ },+);++test("a malformed selected file fails before constructing a client", async () => {+ const input = await fixture("scan: [");+ let initialized = false;+ const stdout = capture();+ const stderr = capture();+ expect(+ await main(+ ["scan", "-c", input.config, "--dry-run", "--json"],+ stdout.stream,+ stderr.stream,+ dependencies({+ currentDirectory: input.repository,+ onConfig: () => {+ initialized = true;+ },+ }),+ ),+ ).toBe(2);+ expect(initialized).toBe(false);+ expect(stderr.text()).toContain("Cannot parse project configuration");+ expect(stdout.text()).toBe("");+});++test("dry-run uses the real SDK without initializing its runtime and reports provenance", async () => {+ const input = await fixture({+ scan: {+ mode: "deep",+ scope: { paths: ["src"] },+ deep: { workers: 8, stop_after_consecutive_errors: 2 },+ },+ codex: {+ profile: "review",+ model: "gpt-5.6-sol",+ profiles: {+ review: { model: "gpt-5.6-terra", model_reasoning_effort: "high" },+ },+ },+ policy: { fail_on_severity: "high" },+ });+ const ambient = join(input.root, "ambient");+ await mkdir(join(ambient, "codex-security"), { recursive: true });+ await writeFile(+ join(ambient, "codex-security", "config.toml"),+ "[deep_scan]\nworkers = 6\nsubagents = 1\nstop_after_no_new = 5\n",+ );+ const environment = {+ codex_home: ambient,+ CODEX_SECURITY_STATE_DIR: join(input.root, "state"),+ };+ const stdout = capture();+ const stderr = capture();+ let initialized = false;+ const deps = dependencies({+ currentDirectory: input.repository,+ environment,+ });+ deps.createSecurity = (config) =>+ new CodexSecurity(+ config,+ {+ environment,+ createCodex: () => {+ initialized = true;+ throw new Error("No inference in dry-run");+ },+ prepareRuntime: async () => {+ initialized = true;+ throw new Error("No runtime in dry-run");+ },+ },+ { surface: "cli" },+ );+ expect(+ await main(+ [+ "scan",+ "-c",+ input.config,+ "--subagents",+ "0",+ "--model",+ "gpt-5.6-sol",+ "--dry-run",+ "--json",+ ],+ stdout.stream,+ stderr.stream,+ deps,+ ),+ ).toBe(0);+ expect(initialized).toBe(false);+ expect(JSON.parse(stdout.text())).toMatchObject({+ dryRun: true,+ repository: input.repository,+ mode: "deep",+ model: "gpt-5.6-terra",+ reasoningEffort: "high",+ target: { kind: "paths", paths: ["src"] },+ workers: 8,+ subagents: 0,+ stopAfterNoNew: 5,+ stopAfterConsecutiveErrors: 2,+ maxDiscoveryRuns: 40,+ maxTimeHours: 96,+ projectConfig: {+ path: input.config,+ sources: {+ "scan.deep.workers": "project",+ "scan.deep.subagents_per_worker": "cli",+ "scan.deep.stop_after_no_new": "legacy",+ "scan.deep.max_time_hours": "default",+ "codex.model": "cli",+ "codex.profiles.review.model": "project",+ },+ },+ failOnSeverity: "high",+ });+});++test.each([+ [{ output: { directory: "../repository/artifacts" } }, "outside"],+ [{ codex: { plugins: {} } }, "plugin"],+ [{ scan: { mode: "deep", validation_file: "validate.md" } }, "Deep"],+] as const)(+ "project files retain active scan checks: %j",+ async (config, message) => {+ const input = await fixture(config as ProjectConfigInput);+ await writeFile(+ join(input.configDirectory, "validate.md"),+ "Synthetic validation instructions.",+ );+ const environment = {+ CODEX_HOME: join(input.root, "ambient"),+ CODEX_SECURITY_STATE_DIR: join(input.root, "state"),+ };+ const stderr = capture();+ let initialized = false;+ const deps = dependencies({+ currentDirectory: input.repository,+ environment,+ });+ deps.createSecurity = (configuration) =>+ new CodexSecurity(+ configuration,+ {+ environment,+ createCodex: () => {+ initialized = true;+ throw new Error("No inference");+ },+ prepareRuntime: async () => {+ initialized = true;+ throw new Error("No runtime");+ },+ },+ { surface: "cli" },+ );+ expect(+ await main(+ ["scan", "-c", input.config, "--dry-run", "--json"],+ capture().stream,+ stderr.stream,+ deps,+ ),+ ).toBe(2);+ expect(stderr.text().toLowerCase()).toContain(message.toLowerCase());+ expect(initialized).toBe(false);+ },+);++test("rerun restores all saved deep settings and authentication without loading project files", async () => {+ const input = await fixture("scan: [");+ const deep = {+ workers: 7,+ subagents: 0,+ stopAfterNoNew: 5,+ stopAfterConsecutiveErrors: 2,+ maxDiscoveryRuns: 12,+ maxTimeHours: 3,+ };+ const recipe: JsonObject = {+ repository: input.repository,+ target: { kind: "repository", paths: [] },+ mode: "deep",+ config: {},+ auth: "api-key",+ deepScan: deep,+ deepScanResolved: true,+ };+ let selected: ScanOptions | undefined;+ expect(+ await main(+ ["scans", "rerun", "saved", "--json"],+ capture().stream,+ capture().stream,+ dependencies({+ currentDirectory: input.repository,+ environment: {+ OPENAI_API_KEY: "synthetic-test-key",+ CODEX_SECURITY_PROJECT_CONFIG: input.config,+ },+ onWorkbench: async () => ({ recipe }),+ onTurn: (_target, value) => {+ selected = value as ScanOptions;+ },+ }),+ ),+ ).toBe(0);+ expect(selected).toMatchObject({+ ...deep,+ auth: "api-key",+ parentScanId: "saved",+ });+});++test.each([+ [{ requiresScanPrompt: true }, "additional instructions"],+ [+ { mode: "deep", deepScan: { workers: 7 }, deepScanResolved: true },+ "missing resolved deep scan settings",+ ],+] as const)(+ "rerun rejects an incomplete saved input: %j",+ async (extra, message) => {+ const input = await fixture({});+ const recipe: JsonObject = {+ repository: input.repository,+ target: { kind: "repository", paths: [] },+ mode: "standard",+ config: {},+ ...extra,+ };+ const stderr = capture();+ let ran = false;+ expect(+ await main(+ ["scans", "rerun", "saved", "--json"],+ capture().stream,+ stderr.stream,+ dependencies({+ currentDirectory: input.repository,+ onWorkbench: async () => ({ recipe }),+ onRun: () => {+ ran = true;+ },+ }),+ ),+ ).toBe(2);+ expect(stderr.text()).toContain(message);+ expect(ran).toBe(false);+ },+);diff --git a/sdk/typescript/tests-ts/cli-scan-import.test.ts b/sdk/typescript/tests-ts/cli-scan-import.test.tsindex db5d8c171..ac96dce28 100644--- a/sdk/typescript/tests-ts/cli-scan-import.test.ts+++ b/sdk/typescript/tests-ts/cli-scan-import.test.ts@@ -276,36 +276,33 @@ describe("scan import", () => {});});- test("rejects custom validation when rerunning an imported scan", async () => {- const { deps, calls } = importDependencies();- deps.runWorkbench = async () => ({- recipe: {- import: {- format: "csv",- sourcePath: resolve("retained", "source.csv"),+ test.each(["--validation-prompt-file", "--scan-prompt-file"])(+ "rejects %s when rerunning an imported scan",+ async (option) => {+ const { deps, calls } = importDependencies();+ deps.runWorkbench = async () => ({+ recipe: {+ import: {+ format: "csv",+ sourcePath: resolve("retained", "source.csv"),+ },},- },- });- const stderr = capture();- expect(- await main(- [- "scans",- "rerun",- "previous-scan",- "--validation-prompt-file",- "workflow.md",- ],- capture().stream,- stderr.stream,- deps,- ),- ).toBe(2);- expect(stderr.text()).toContain(- "--validation-prompt-file is not supported when rerunning an imported scan",- );- expect(calls).toHaveLength(0);- });+ });+ const stderr = capture();+ expect(+ await main(+ ["scans", "rerun", "previous-scan", option, "workflow.md"],+ capture().stream,+ stderr.stream,+ deps,+ ),+ ).toBe(2);+ expect(stderr.text()).toContain(+ `${option} is not supported when rerunning an imported scan`,+ );+ expect(calls).toHaveLength(0);+ },+ );test("reports import errors without leaving signal handlers", async () => {const signals = new FakeSignals();diff --git a/sdk/typescript/tests-ts/cli-workbench.test.ts b/sdk/typescript/tests-ts/cli-workbench.test.tsindex eb3d340bf..68bb13cef 100644--- a/sdk/typescript/tests-ts/cli-workbench.test.ts+++ b/sdk/typescript/tests-ts/cli-workbench.test.ts@@ -1259,6 +1259,7 @@ describe("CLI workbench", () => {let config: CodexSecurityConfig | undefined;let repository: string | undefined;let options: Record<string, unknown> | undefined;+ const knowledgeBasePath = resolve("/original/security.md");const savedConfig = {approval_policy: "on-request",model: "gpt-original",@@ -1286,7 +1287,7 @@ describe("CLI workbench", () => {mode: "deep",pluginVersion: "1.2.3",failOnSeverity: "high",- knowledgeBasePaths: ["/original/security.md"],+ knowledgeBasePaths: [knowledgeBasePath],deepScan: {workers: 2,subagents: 0,@@ -1308,7 +1309,7 @@ describe("CLI workbench", () => {parentScanId: "scan-original",expectedPluginVersion: "1.2.3",failureSeverity: "high",- knowledgeBasePaths: ["/original/security.md"],+ knowledgeBasePaths: [knowledgeBasePath],workers: 2,subagents: 0,stopAfterNoNew: 3,diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.tsindex 8009b9a26..f4580b956 100644--- a/sdk/typescript/tests-ts/cli.test.ts+++ b/sdk/typescript/tests-ts/cli.test.ts@@ -8,7 +8,7 @@ import {writeFile,} from "node:fs/promises";import { tmpdir } from "node:os";-import { delimiter, join, normalize } from "node:path";+import { delimiter, join, normalize, resolve } from "node:path";import { PassThrough, Writable } from "node:stream";import { fileURLToPath } from "node:url";import { stripVTControlCharacters } from "node:util";@@ -751,6 +751,8 @@ describe("CLI", () => {test("runs a bulk scan and keeps structured output on stdout", async () => {const root = await mkdtemp(join(tmpdir(), "codex-security-cli-multiscan-"));+ const architecturePath = resolve(root, "/shared/architecture.pdf");+ const threatModelsPath = resolve(root, "/shared/threat-models");try {await multiscanInventory(root);const stdout = capture();@@ -771,8 +773,8 @@ describe("CLI", () => {"--effort","high","--knowledge-base",- "/shared/architecture.pdf",- "--knowledge-base=/shared/threat-models",+ architecturePath,+ `--knowledge-base=${threatModelsPath}`,"--codex","features.goals=true","--json",@@ -802,10 +804,7 @@ describe("CLI", () => {});expect(scanOptions).toMatchObject({mode: "deep",- knowledgeBasePaths: [- "/shared/architecture.pdf",- "/shared/threat-models",- ],+ knowledgeBasePaths: [architecturePath, threatModelsPath],});expect(stderr.text()).toContain("sample started (attempt 1)");expect(stderr.text()).toContain("sample completed (attempt 1)");@@ -827,12 +826,12 @@ describe("CLI", () => {process.env["HOME"] = home;process.env["USERPROFILE"] = home;- expect(resolveCliPath(currentDirectory, "~/repositories.csv")).toBe(- join(home, "repositories.csv"),- );- expect(resolveCliPath(currentDirectory, "~person/repositories.csv")).toBe(- join(currentDirectory, "~person", "repositories.csv"),- );+ expect<string>(+ resolveCliPath(currentDirectory, "~/repositories.csv"),+ ).toBe(join(home, "repositories.csv"));+ expect<string>(+ resolveCliPath(currentDirectory, "~person/repositories.csv"),+ ).toBe(join(currentDirectory, "~person", "repositories.csv"));const stdout = capture();expect(@@ -2603,7 +2602,10 @@ describe("CLI", () => {).toBe(0);expect(pathOptions).toMatchObject({target: ["src", "--fixtures"],- knowledgeBasePaths: ["/shared/architecture.pdf", "/shared/threat-models"],+ knowledgeBasePaths: [+ resolve("/shared/architecture.pdf"),+ resolve("/shared/threat-models"),+ ],workers: 2,subagents: 0,stopAfterNoNew: 3,@@ -2738,37 +2740,34 @@ describe("CLI", () => {[["scan", ".", "--base", "HEAD"], "--base requires --working-tree"],[["scan", ".", "--archive-existing"], "requires --output-dir"],[["scan", ".", "--max-cost=0"], "expected number to be >0"],- [- ["scan", ".", "--workers", "2"],- "Deep scan settings require --mode deep",- ],+ [["scan", ".", "--workers", "2"], "Deep scan settings require deep mode"],[["scan", ".", "--max-time-hours", "1.5"],- "Deep scan settings require --mode deep",+ "Deep scan settings require deep mode",],[["scan", ".", "--mode", "deep", "--workers", "0"],- "expected number to be >0",+ "must be a positive integer",],[["scan", ".", "--mode", "deep", "--subagents", "-1"],- "expected number to be >=0",+ "must be a non-negative integer",],[["scan", ".", "--mode", "deep", "--stop-after-no-new", "0"],- "expected number to be >0",+ "must be a positive integer",],[["scan", ".", "--mode", "deep", "--max-discovery-runs", "0"],- "expected number to be >0",+ "must be a positive integer",],[["scan", ".", "--mode", "deep", "--max-time-hours", "0"],- "expected number to be >0",+ "must be a positive number no greater than 96",],[["scan", ".", "--mode", "deep", "--max-time-hours", "96.5"],- "expected number to be <=96",+ "must be a positive number no greater than 96",],[["scan", ".", "--path="], "--path must not be empty"],[@@ -5130,7 +5129,7 @@ describe("CLI", () => {dependencies({onTurn: (_repository, options) => {expect(options).toMatchObject({- outputDir: "/tmp/results",+ outputDir: resolve("/tmp/results"),archiveExisting: true,});(diff --git a/sdk/typescript/tests-ts/custom-validation.test.ts b/sdk/typescript/tests-ts/custom-validation.test.tsindex c1b3abe2b..c978e2bc7 100644--- a/sdk/typescript/tests-ts/custom-validation.test.ts+++ b/sdk/typescript/tests-ts/custom-validation.test.ts@@ -352,6 +352,8 @@ describe("custom validation", () => {);}const workflow = "Run the synthetic validation script, then clean up.";+ const workflowFile = join(root, "validation.md");+ if (scenario === "standard") await writeFile(workflowFile, workflow);const falsePositive = {reason: "The fixture is not included in the deployed application.",};@@ -518,7 +520,9 @@ describe("custom validation", () => {);try {const pending = client.run(repository, {- validationPrompt: workflow,+ ...(scenario === "standard"+ ? { validationPromptFile: workflowFile }+ : { validationPrompt: workflow }),onActivity: (activity) => activities.push(activity),...(diff ? { target: DiffTarget.workingTree({}) } : {}),});diff --git a/sdk/typescript/tests-ts/deep-config.test.ts b/sdk/typescript/tests-ts/deep-config.test.tsnew file mode 100644index 000000000..ad39e922c--- /dev/null+++ b/sdk/typescript/tests-ts/deep-config.test.ts@@ -0,0 +1,272 @@+import {+ mkdir,+ mkdtemp,+ readFile,+ realpath,+ rm,+ symlink,+ writeFile,+} from "node:fs/promises";+import { tmpdir } from "node:os";+import { dirname, join } from "node:path";+import { afterEach, expect, test } from "bun:test";+import { parse as parseToml } from "smol-toml";+import {+ resolveDeepScanConfig,+ writeDeepScanConfig,+} from "../src/deep-config.js";+import { DEFAULT_DEEP_SCAN_SETTINGS } from "../src/deep-scan-defaults.js";++const directories: string[] = [];+afterEach(async () => {+ await Promise.all(+ directories+ .splice(0)+ .map((path) => rm(path, { recursive: true, force: true })),+ );+});+async function fixture(contents?: string) {+ const root = await realpath(await mkdtemp(join(tmpdir(), "deep-config-")));+ directories.push(root);+ const ambient = join(root, "ambient");+ await mkdir(join(ambient, "codex-security"), { recursive: true });+ const source = join(ambient, "codex-security", "config.toml");+ if (contents !== undefined) await writeFile(source, contents);+ return { root, source };+}++test("resolves all six defaults without creating an ambient file", async () => {+ const input = await fixture();+ const result = await resolveDeepScanConfig({}, input.source);+ expect(result.settings).toEqual(DEFAULT_DEEP_SCAN_SETTINGS);+ expect(new Set(Object.values(result.sources))).toEqual(new Set(["default"]));+ await expect(readFile(input.source)).rejects.toMatchObject({+ code: "ENOENT",+ });+});++test.each(["missing file", "missing directory"])(+ "preserves absent ambient configuration through a directory link with a %s",+ async (state) => {+ const input = await fixture();+ if (state === "missing directory")+ await rm(dirname(input.source), { recursive: true });+ const home = dirname(dirname(input.source));+ const linkedHome = join(input.root, "linked-home");+ await symlink(home, linkedHome, "junction");+ const source = join(linkedHome, "codex-security", "config.toml");+ await writeDeepScanConfig(+ input.source,+ await resolveDeepScanConfig({}, source),+ );+ await expect(readFile(input.source)).rejects.toMatchObject({+ code: "ENOENT",+ });+ },+);++test("normalizes legacy auto and preserves explicit zero while merging", async () => {+ const input = await fixture(+ '[deep_scan]\nworkers = "auto"\nsubagents = 2\nstop_after_no_new = 6\nstop_after_consecutive_errors = 5\nmax_time_hours = 1.5\n',+ );+ const result = await resolveDeepScanConfig(+ { subagents: 0, stopAfterConsecutiveErrors: 2 },+ input.source,+ );+ expect(result.settings).toEqual({+ workers: 4,+ subagents: 0,+ stopAfterNoNew: 6,+ stopAfterConsecutiveErrors: 2,+ maxDiscoveryRuns: 40,+ maxTimeHours: 1.5,+ });+ expect(result.sources).toEqual({+ workers: "legacy",+ subagents: "override",+ stopAfterNoNew: "legacy",+ stopAfterConsecutiveErrors: "override",+ maxDiscoveryRuns: "default",+ maxTimeHours: "legacy",+ });+});++test("validates legacy values after matching explicit overrides", async () => {+ const input = await fixture('[deep_scan]\nworkers = "invalid"\n');+ await expect(resolveDeepScanConfig({}, input.source)).rejects.toThrow(+ "integer",+ );+ expect(+ (await resolveDeepScanConfig({ workers: 2 }, input.source)).settings+ .workers,+ ).toBe(2);+});++test("reports the TOML key and source file for an invalid ambient value", async () => {+ const input = await fixture("[deep_scan]\nstop_after_no_new = 0\n");+ await expect(resolveDeepScanConfig({}, input.source)).rejects.toThrow(+ `Deep scan stop_after_no_new in ${input.source} must be a positive integer`,+ );+});++test.each(["same path", "directory link"])(+ "updating ambient overrides through the %s does not pin inherited defaults",+ async (kind) => {+ const input = await fixture(+ "[deep_scan]\nworkers = 7\n[other]\nkeep = true\n",+ );+ let destination = input.source;+ if (kind === "directory link") {+ const link = join(input.root, "linked");+ await symlink(dirname(input.source), link, "junction");+ destination = join(link, "config.toml");+ }+ await writeDeepScanConfig(+ destination,+ await resolveDeepScanConfig({ workers: 8 }, input.source),+ );+ expect(parseToml(await readFile(input.source, "utf8"))).toEqual({+ deep_scan: { workers: 8 },+ other: { keep: true },+ });+ },+);++test("does not write a snapshot when source path resolution fails", async () => {+ const input = await fixture();+ const resolved = await resolveDeepScanConfig({}, input.source);+ const loop = join(input.root, "loop");+ await symlink(loop, loop, "junction");+ const destination = join(input.root, "runtime", "config.toml");+ await expect(+ writeDeepScanConfig(destination, {+ ...resolved,+ source: join(loop, "config.toml"),+ }),+ ).rejects.toThrow();+ await expect(readFile(destination)).rejects.toMatchObject({ code: "ENOENT" });+});++test.each([+ ["deep_scan = []\n", "TOML table"],+ ["deep_scan = 2026-01-01\n", "TOML table"],+ ["[deep_scan]\nworkers = true\n", "integer"],+ ["[deep_scan]\nstop_after_consecutive_errors = 0\n", "integer"],+ ["[deep_scan]\nmax_time_hours = 97\n", "no greater than 96"],+ ["[deep_scan]\nworkres = 2\n", "Unknown"],+ ["[deep_scan\n", "Cannot read"],+])("rejects invalid ambient settings: %s", async (contents, message) => {+ const input = await fixture(contents);+ await expect(resolveDeepScanConfig({}, input.source)).rejects.toThrow(+ message,+ );+});++test("complete saved settings do not read a changed or invalid legacy file", async () => {+ const input = await fixture("not valid TOML [");+ const saved = {+ workers: 2,+ subagents: 0,+ stopAfterNoNew: 7,+ stopAfterConsecutiveErrors: 2,+ maxDiscoveryRuns: 12,+ maxTimeHours: 1.5,+ };+ const result = await resolveDeepScanConfig(saved, input.source);+ expect(result.settings).toEqual(saved);+ expect(new Set(Object.values(result.sources))).toEqual(new Set(["override"]));+ const destination = join(input.root, "runtime", "deep-scan.toml");+ await writeDeepScanConfig(destination, result);+ expect(parseToml(await readFile(destination, "utf8"))).toMatchObject({+ deep_scan: { workers: 2, subagents: 0, stop_after_no_new: 7 },+ });+ expect(await readFile(input.source, "utf8")).toBe("not valid TOML [");+});++test.each(["same path", "directory link"])(+ "complete settings preserve ambient sections through the %s",+ async (destinationKind) => {+ const input = await fixture("[other]\nenabled = true\n");+ const result = await resolveDeepScanConfig(+ { ...DEFAULT_DEEP_SCAN_SETTINGS, workers: 2 },+ input.source,+ );+ await writeFile(+ input.source,+ "[deep_scan]\nworkers = 9\n[other]\nenabled = false\n",+ );+ let destination = input.source;+ if (destinationKind === "directory link") {+ const link = join(input.root, "runtime");+ await symlink(dirname(input.source), link, "junction");+ destination = join(link, "config.toml");+ }+ await writeDeepScanConfig(destination, result);+ expect(parseToml(await readFile(input.source, "utf8"))).toEqual({+ deep_scan: {+ workers: 2,+ subagents: 3,+ stop_after_no_new: 4,+ stop_after_consecutive_errors: 3,+ max_discovery_runs: 40,+ max_time_hours: 96,+ },+ other: { enabled: false },+ });+ },+);++test("complete settings do not overwrite an invalid ambient destination", async () => {+ const contents = "not valid TOML [";+ const input = await fixture(contents);+ const result = await resolveDeepScanConfig(+ DEFAULT_DEEP_SCAN_SETTINGS,+ input.source,+ );+ await expect(writeDeepScanConfig(input.source, result)).rejects.toThrow(+ "Cannot read Codex Security configuration",+ );+ expect(await readFile(input.source, "utf8")).toBe(contents);+});++test("a complete snapshot replaces stale deep keys but preserves other ambient sections", async () => {+ const input = await fixture(+ "[deep_scan]\nobsolete_setting = true\n[other]\nkeep = true\n",+ );+ await writeDeepScanConfig(+ input.source,+ await resolveDeepScanConfig(DEFAULT_DEEP_SCAN_SETTINGS, input.source),+ );+ const document = parseToml(await readFile(input.source, "utf8"));+ expect(document["other"]).toEqual({ keep: true });+ expect(document["deep_scan"]).toEqual({+ workers: 4,+ subagents: 3,+ stop_after_no_new: 4,+ stop_after_consecutive_errors: 3,+ max_discovery_runs: 40,+ max_time_hours: 96,+ });+});++test("runtime preparation writes the snapshot even if the ambient file changes", async () => {+ const input = await fixture(+ "[deep_scan]\nworkers = 7\nstop_after_no_new = 6\n[other]\nenabled = true\n",+ );+ const result = await resolveDeepScanConfig({ subagents: 0 }, input.source);+ await writeFile(input.source, "not valid TOML [");+ const destination = join(input.root, "runtime", "deep-scan.toml");+ await writeDeepScanConfig(destination, result);+ expect(parseToml(await readFile(destination, "utf8"))).toEqual({+ deep_scan: {+ workers: 7,+ subagents: 0,+ stop_after_no_new: 6,+ stop_after_consecutive_errors: 3,+ max_discovery_runs: 40,+ max_time_hours: 96,+ },+ other: { enabled: true },+ });+ expect(await readFile(input.source, "utf8")).toBe("not valid TOML [");+});diff --git a/sdk/typescript/tests-ts/multiscan.test.ts b/sdk/typescript/tests-ts/multiscan.test.tsindex d3ebd2a3e..41b56448a 100644--- a/sdk/typescript/tests-ts/multiscan.test.ts+++ b/sdk/typescript/tests-ts/multiscan.test.ts@@ -25,6 +25,7 @@ import { ScanCostLimitExceededError } from "../src/errors.js";import type { ScanResult } from "../src/result.js";import { buildGitHubCredentialArgs, runMultiscan } from "../src/multiscan.js";import { resolveTrustedExecutable } from "../src/trusted-executable.js";+import { DiffTarget } from "../src/targets.js";import { prepareOutputDir } from "../src/runtime.js";import { capture, dependencies, fakeResult } from "./cli-fixtures.js";import { runTestInSubprocess } from "./support/test-subprocess.js";@@ -136,6 +137,70 @@ async function results(path: string): Promise<Record<string, unknown>[]> {}describe("multiscan", () => {+ test("prepares shared prompt files once while missing sources remain row failures", async () => {+ const paths = await fixture();+ const source = await repository(paths.root, "prompt-source");+ const prompt = join(paths.root, "shared-prompt.md");+ await writeFile(prompt, "Review synthetic boundaries.");+ await writeFile(+ paths.input,+ `id,repository,revision\nmissing,${join(paths.root, "absent")},${source.revision}\nfirst,${source.path},${source.revision}\nsecond,${source.path},${source.revision}\n`,+ );+ let scans = 0;+ const summary = await runMultiscan(+ options(+ paths,+ client(async (_checkout, scanOptions = {}) => {+ expect(scanOptions.scanPrompt).toBe("Review synthetic boundaries.");+ expect(scanOptions.scanPromptFile).toBeUndefined();+ if (scans++ === 0) await rm(prompt);+ return await completedScan(scanOptions.outputDir!);+ }),+ { maxAttempts: 1, scanPromptFile: prompt },+ ),+ );+ expect(scans).toBe(2);+ expect(summary).toMatchObject({ total: 3, completed: 2, failed: 1 });+ expect(await results(summary.resultsPath)).toMatchObject([+ { id: "missing", status: "failed" },+ { id: "first", status: "completed" },+ { id: "second", status: "completed" },+ ]);+ });++ test.each([DiffTarget.refs({ base: "HEAD~1" }), DiffTarget.workingTree()])(+ "rejects unsupported bulk diff scopes before preparing a campaign: %j",+ async (target) => {+ const paths = await fixture();+ const source = await repository(paths.root, "configured-scope");+ await writeFile(+ paths.input,+ `id,repository,revision\nexample,${source.path},${source.revision}\n`,+ );+ let initialized = false;+ const security = client(async () => {+ throw new Error("The unsupported target must not reach a scan.");+ });+ await expect(+ runMultiscan(+ options(paths, security, {+ scanOptionsByMode: { standard: { target } },+ createSecurity: () => {+ initialized = true;+ return security;+ },+ }),+ ),+ ).rejects.toThrow(+ "Bulk scans do not support diff or working-tree scopes",+ );+ expect(initialized).toBe(false);+ await expect(access(paths.output)).rejects.toMatchObject({+ code: "ENOENT",+ });+ },+ );+test("canceled recovery retains the new checkout and attempt without appending a failure receipt", async () => {const paths = await fixture();const source = await repository(paths.root, "cancel-recovery");@@ -426,6 +491,60 @@ describe("multiscan", () => {},);+ test.each(["high", "low"] as const)(+ "recovery applies the campaign severity policy to %s findings and retains the outcome",+ async (severity) => {+ const paths = await fixture();+ const source = await repository(paths.root, "policy-recovery");+ await writeFile(+ paths.input,+ `id,repository,revision\nrepo,${source.path},${source.revision}\n`,+ );+ const configured = options(+ paths,+ client(async () => {+ throw new Error("Interrupted scan");+ }),+ {+ maxAttempts: 1,+ scanPrompt: "Shared scan instructions.",+ scanOptionsByMode: { standard: { failureSeverity: "high" } },+ },+ );+ await runMultiscan(configured);+ await mkdir(join(paths.output, "artifacts", "repo", "attempt-1"), {+ recursive: true,+ });+ const result = await runMultiscan({+ ...configured,+ recoverScan: async (scanDir, prompts) => {+ expect(prompts.scanPrompt).toBe("Shared scan instructions.");+ await completedScan(scanDir);+ const recovered = fakeResult([severity]);+ return {+ coverage: recovered.coverage,+ cost: recovered.cost,+ findings: recovered.findings,+ };+ },+ });+ expect(result).toMatchObject({+ completed: 1,+ failed: 0,+ policyFailed: severity === "high",+ });+ expect((await results(result.resultsPath)).at(-1)).toMatchObject({+ attempt: 1,+ policyFailed: severity === "high",+ });+ expect(await runMultiscan(configured)).toMatchObject({+ completed: 1,+ skipped: 1,+ policyFailed: severity === "high",+ });+ },+ );+test("bulk recovery requires an existing campaign and a CSV", async () => {const paths = await fixture();const source = await repository(paths.root, "missing-campaign");@@ -533,6 +652,9 @@ describe("multiscan", () => {scanPrompt: "Review boundaries.",postScanPrompt: "Draft confirmed fixes.",maxCostUsd: 12.5,+ scanOptionsByMode: {+ deep: { target: DiffTarget.workingTree() },+ },},),);diff --git a/sdk/typescript/tests-ts/project-config.test.ts b/sdk/typescript/tests-ts/project-config.test.tsnew file mode 100644index 000000000..575de53d3--- /dev/null+++ b/sdk/typescript/tests-ts/project-config.test.ts@@ -0,0 +1,417 @@+import { mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, describe, expect, test } from "bun:test";+import Ajv from "ajv";+import {+ readProjectConfig,+ resolveScanSettings,+} from "../src/project-config.js";+import {+ ProjectConfigInputSchema,+ projectConfigJsonSchema,+ type ProjectConfigInput,+} from "../src/project-config-schema.js";+import { DEFAULT_DEEP_SCAN_SETTINGS } from "../src/deep-scan-defaults.js";++const directories: string[] = [];+afterEach(async () => {+ await Promise.all(+ directories+ .splice(0)+ .map((path) => rm(path, { recursive: true, force: true })),+ );+});+async function temporaryDirectory() {+ const directory = await realpath(+ await mkdtemp(join(tmpdir(), "project-config-")),+ );+ directories.push(directory);+ return directory;+}++const cases: [string, unknown, boolean][] = [+ ["minimal file", {}, true],+ [+ "standard path scope",+ { scan: { mode: "standard", scope: { paths: ["src"] } } },+ true,+ ],+ [+ "zero subagents",+ {+ scan: {+ mode: "deep",+ deep: { workers: 4, subagents_per_worker: 0, max_time_hours: 96 },+ },+ },+ true,+ ],+ [+ "working tree with an absent base",+ { scan: { scope: { working_tree: {} } } },+ true,+ ],+ [+ "diff with an absent head",+ { scan: { scope: { diff: { base: "HEAD" } } } },+ true,+ ],+ ["empty context list", { scan: { knowledge_base: [] } }, true],+ [+ "editor metadata",+ { $schema: "../schemas/project-config.schema.json" },+ true,+ ],+ [+ "native JSON passthrough",+ {+ codex: { synthetic_setting: { enabled: false, names: [], value: null } },+ },+ true,+ ],+ [+ "model availability is a later check",+ { codex: { model: "synthetic-model" } },+ true,+ ],+ [+ "mode and scope may be overridden later",+ { scan: { mode: "deep", scope: { diff: { base: "HEAD" } } } },+ true,+ ],+ [+ "custom validation may be overridden later",+ { scan: { mode: "deep", validation_file: "validate.md" } },+ true,+ ],+ ["unknown wrapper key", { concurrency: 4 }, false],+ ["unknown scan key", { scan: { workres: 4 } }, false],+ [+ "camelCase names are not project-file keys",+ {+ scan: {+ knowledgeBase: [],+ deep: { stopAfterNoNew: 4 },+ scope: { workingTree: {} },+ },+ limits: { maxCostUsdPerScan: 5 },+ policy: { failOnSeverity: "high" },+ },+ false,+ ],+ [+ "repository selection is not file configuration",+ { repository: "." },+ false,+ ],+ ["null is not a reset", { policy: null }, false],+ ["empty scope", { scan: { scope: {} } }, false],+ [+ "multiple scope variants",+ { scan: { scope: { paths: ["src"], diff: { base: "HEAD" } } } },+ false,+ ],+ ["empty path list", { scan: { scope: { paths: [] } } }, false],+ ["missing diff base", { scan: { scope: { diff: {} } } }, false],+ ["zero workers", { scan: { deep: { workers: 0 } } }, false],+ ["fractional workers", { scan: { deep: { workers: 1.5 } } }, false],+ ["no string coercion", { scan: { deep: { workers: "4" } } }, false],+ [+ "negative subagents",+ { scan: { deep: { subagents_per_worker: -1 } } },+ false,+ ],+ [+ "hours above the existing maximum",+ { scan: { deep: { max_time_hours: 97 } } },+ false,+ ],+ ["nonpositive cost", { limits: { max_cost_usd_per_scan: 0 } }, false],+ ["incorrect native model type", { codex: { model: 42 } }, false],+];++describe("project configuration input contract", () => {+ const validate = new Ajv({ strict: true, allErrors: true }).compile(+ projectConfigJsonSchema(),+ );++ test.each(cases)(+ "Zod and JSON Schema agree: %s",+ (_name, input, accepted) => {+ const original = structuredClone(input);+ const parsed = ProjectConfigInputSchema.safeParse(input);+ expect(parsed.success).toBe(accepted);+ expect(validate(input)).toBe(accepted);+ expect(input).toEqual(original);+ if (parsed.success) expect<unknown>(parsed.data).toEqual(original);+ },+ );++ test("the packaged schema and shared deep defaults are current", async () => {+ expect(+ JSON.parse(+ await readFile(+ new URL("../schemas/project-config.schema.json", import.meta.url),+ "utf8",+ ),+ ),+ ).toEqual(projectConfigJsonSchema());+ expect(+ JSON.parse(+ await readFile(+ new URL(+ "../../../plugins/codex-security/scripts/deep_scan_defaults.json",+ import.meta.url,+ ),+ "utf8",+ ),+ ),+ ).toEqual(DEFAULT_DEEP_SCAN_SETTINGS);+ });++ test("YAML and JSON load the same literal data without adding defaults", async () => {+ const root = await temporaryDirectory();+ const yaml = join(root, "scan.yaml");+ const json = join(root, "scan.json");+ const input = {+ scan: { deep: { subagents_per_worker: 0 } },+ codex: { synthetic_setting: "${LITERAL_VALUE}" },+ } satisfies ProjectConfigInput;+ await writeFile(+ yaml,+ "scan:\n deep:\n subagents_per_worker: 0\ncodex:\n synthetic_setting: ${LITERAL_VALUE}\n",+ );+ await writeFile(json, JSON.stringify(input));+ expect((await readProjectConfig(yaml)).input).toEqual(input);+ expect((await readProjectConfig(json)).input).toEqual(input);+ });++ test.each([+ [150, 1],+ [500, 20],+ ])(+ "loads %i YAML profiles reusing a %i-field table",+ async (count, fields) => {+ const root = await temporaryDirectory();+ const path = join(root, "profiles.yaml");+ const profile = {+ model: "synthetic-model",+ ...Object.fromEntries(+ Array.from({ length: fields - 1 }, (_, index) => [+ `setting_${index}`,+ index,+ ]),+ ),+ };+ const names = Array.from(+ { length: count },+ (_, index) => `profile_${index}`,+ );+ await writeFile(+ path,+ [+ "codex:",+ " profiles:",+ ` shared: &shared ${JSON.stringify(profile)}`,+ ...names.map((name) => ` ${name}: *shared`),+ ].join("\n"),+ );+ const project = await readProjectConfig(path);+ expect(+ resolveScanSettings(project, {}, root).config.codexOverrides[+ "profiles"+ ],+ ).toEqual({+ shared: profile,+ ...Object.fromEntries(names.map((name) => [name, profile])),+ });+ },+ );++ test("rejects excessive nested YAML alias expansion before resolving settings", async () => {+ const root = await temporaryDirectory();+ const path = join(root, "nested-aliases.yaml");+ await writeFile(+ path,+ [+ "codex:",+ " shared_0: &shared_0 [value, value, value, value, value]",+ ...Array.from(+ { length: 6 },+ (_, index) =>+ ` shared_${index + 1}: &shared_${index + 1} [${Array(10).fill(`*shared_${index}`).join(", ")}]`,+ ),+ ].join("\n"),+ );+ await expect(readProjectConfig(path)).rejects.toThrow(+ "Cannot parse project configuration",+ );+ });++ test.each([+ ["invalid.yaml", "scan: [\n"],+ ["duplicate.yaml", "scan: {}\nscan: {}\n"],+ ["stream.yaml", "scan: {}\n---\nscan: {}\n"],+ ["invalid.json", '{"scan":'],+ ["invalid.ts", "export default {};"],+ ["unknown.yaml", "scan:\n workres: 2\n"],+ ])("rejects an invalid selected file: %s", async (name, contents) => {+ const root = await temporaryDirectory();+ const path = join(root, name);+ await writeFile(path, contents);+ await expect(readProjectConfig(path)).rejects.toThrow();+ });++ test("reports a missing selected file", async () => {+ await expect(+ readProjectConfig("missing.yaml", await temporaryDirectory()),+ ).rejects.toThrow("Cannot read project configuration");+ });+});++describe("project configuration resolution", () => {+ test("resolves paths according to their layer and replaces lists", async () => {+ const root = await temporaryDirectory();+ const project = {+ path: join(root, "settings", "scan.yaml"),+ directory: join(root, "settings"),+ input: {+ scan: {+ scope: { paths: ["src"] },+ knowledge_base: ["context.md"],+ instructions_file: "scan.md",+ validation_file: "validate.md",+ },+ output: { directory: "../artifacts" },+ } satisfies ProjectConfigInput,+ };+ const { options: settings, projectConfig: provenance } =+ resolveScanSettings(+ project,+ {+ knowledgeBasePaths: ["cli-context.md"],+ validationPromptFile: "cli-validate.md",+ },+ join(root, "invocation"),+ );+ expect(settings).toMatchObject({+ target: ["src"],+ knowledgeBasePaths: [join(root, "invocation", "cli-context.md")],+ scanPromptFile: join(root, "settings", "scan.md"),+ validationPromptFile: join(root, "invocation", "cli-validate.md"),+ outputDir: join(root, "artifacts"),+ });+ expect(provenance?.sources).toMatchObject({+ "scan.knowledge_base": "cli",+ "scan.instructions_file": "project",+ "scan.validation_file": "cli",+ "output.directory": "project",+ });+ expect(project.input.scan.knowledge_base).toEqual(["context.md"]);+ });++ test("keeps native key spelling and false/zero values when merging overrides", async () => {+ const root = await temporaryDirectory();+ const project = {+ path: join(root, "scan.yaml"),+ directory: root,+ input: {+ scan: { mode: "deep", deep: { subagents_per_worker: 3, workers: 8 } },+ codex: {+ profile: "reviewCase",+ profiles: {+ reviewCase: {+ model: "gpt-5.6-terra",+ model_reasoning_effort: "high",+ },+ },+ synthetic_setting: { enabled: true, itemCount: 2, names: ["first"] },+ },+ } satisfies ProjectConfigInput,+ };+ const {+ config,+ options: settings,+ projectConfig: provenance,+ } = resolveScanSettings(+ project,+ {+ subagents: 0,+ codexOverrides: {+ model: "gpt-5.6-sol",+ synthetic_setting: { enabled: false, itemCount: 0, names: [] },+ },+ },+ root,+ );+ expect(settings).toMatchObject({+ subagents: 0,+ workers: 8,+ });+ expect(config).toEqual({+ codexOverrides: {+ model: "gpt-5.6-sol",+ profile: "reviewCase",+ profiles: project.input.codex.profiles,+ synthetic_setting: { enabled: false, itemCount: 0, names: [] },+ },+ });+ expect(provenance?.sources).toMatchObject({+ "scan.deep.subagents_per_worker": "cli",+ "scan.deep.workers": "project",+ "codex.model": "cli",+ "codex.profiles.reviewCase.model": "project",+ "codex.synthetic_setting.itemCount": "cli",+ });+ });++ test("ignores valid inactive deep defaults but rejects explicit deep CLI options in standard mode", async () => {+ const root = await temporaryDirectory();+ const project = {+ path: join(root, "scan.yaml"),+ directory: root,+ input: {+ scan: { mode: "deep", deep: { workers: 8 } },+ } satisfies ProjectConfigInput,+ };+ expect(+ resolveScanSettings(project, { mode: "standard" }, root).options.workers,+ ).toBeUndefined();+ expect(() =>+ resolveScanSettings(project, { mode: "standard", workers: 2 }, root),+ ).toThrow("require deep mode");+ });++ test("keeps existing unsafe native-key protections before merging", async () => {+ const root = await temporaryDirectory();+ for (const [filename, contents] of [+ ["scan.json", '{"codex":{"__proto__":{"syntheticPollution":true}}}'],+ ["scan.yaml", "codex:\n __proto__:\n syntheticPollution: true\n"],+ ] as const) {+ await writeFile(join(root, filename), contents);+ const project = await readProjectConfig(filename, root);+ expect(() => resolveScanSettings(project, {}, root)).toThrow(+ "Invalid Codex override key: __proto__.",+ );+ }+ expect(+ ({} as Record<string, unknown>)["syntheticPollution"],+ ).toBeUndefined();+ });++ test.each([+ '{"__proto__":{"synthetic":true}}',+ '{"scan":{"__proto__":{"synthetic":true}}}',+ ])(+ "rejects reserved unknown wrapper keys without dropping them: %s",+ async (contents) => {+ const root = await temporaryDirectory();+ const path = join(root, "scan.json");+ await writeFile(path, contents);+ await expect(readProjectConfig(path)).rejects.toThrow(+ "Unknown key __proto__.",+ );+ },+ );+});diff --git a/sdk/typescript/tests-ts/result.test.ts b/sdk/typescript/tests-ts/result.test.tsindex 146fe9aa4..9c9e7622f 100644--- a/sdk/typescript/tests-ts/result.test.ts+++ b/sdk/typescript/tests-ts/result.test.ts@@ -3,11 +3,13 @@ import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";import { tmpdir } from "node:os";import { join } from "node:path";import { ScanResult } from "../src/index.js";+import { fakeResult } from "./cli-fixtures.js";import type {CoverageDocument,FindingsDocument,RepositoryFinding,ScanManifest,+ SeverityLevel,} from "../src/index.js";const manifest = {@@ -50,6 +52,31 @@ const coverage = {} satisfies CoverageDocument;describe("ScanResult", () => {+ test.each([{ levels: [] }, { levels: ["high"] }] satisfies {+ levels: SeverityLevel[];+ }[])("rejects an unknown threshold with findings %j", ({ levels }) => {+ expect(() =>+ fakeResult([...levels]).hasFindingsAtOrAbove("hihg" as SeverityLevel),+ ).toThrow("Unknown severity threshold");+ });++ test("evaluates a severity threshold without filtering findings or changing serialization", () => {+ const result = fakeResult(["medium", "informational"]);+ const serialized = result.toJSON();+ expect(result.hasFindingsAtOrAbove("high")).toBe(false);+ expect(result.hasFindingsAtOrAbove("medium")).toBe(true);+ expect(result.hasFindingsAtOrAbove("low")).toBe(true);+ expect(fakeResult(["informational"]).hasFindingsAtOrAbove("low")).toBe(+ false,+ );+ expect(+ fakeResult(["informational"]).hasFindingsAtOrAbove("informational"),+ ).toBe(true);+ expect(fakeResult([]).hasFindingsAtOrAbove("informational")).toBe(false);+ expect(result.findings.findings).toHaveLength(2);+ expect(result.toJSON()).toEqual(serialized);+ });+test("exposes canonical paths and machine serialization", () => {const repositoryFinding = {findingId: "finding",diff --git a/sdk/typescript/tests-ts/scan-resume.test.ts b/sdk/typescript/tests-ts/scan-resume.test.tsindex d5646bc52..41844f838 100644--- a/sdk/typescript/tests-ts/scan-resume.test.ts+++ b/sdk/typescript/tests-ts/scan-resume.test.ts@@ -29,7 +29,11 @@ afterEach(cleanup);async function interruptedScan(mode: "deep" | "standard" = "deep",bulk = false,- settings: Pick<ScanOptions, "safetyIdentifier" | "postScanPrompt"> = {},+ settings: Pick<+ ScanOptions,+ "safetyIdentifier" | "postScanPrompt" | "auth"+ > = {},+ resolvedDeep = false,) {const root = await temporaryDirectory();const repository = bulk@@ -108,9 +112,24 @@ async function interruptedScan(mode,config: { model: "gpt-5.6-sol", approval_policy: "never" },pluginVersion: "0.1.0",+ requiresScanPrompt: true,...settings,...(mode === "deep"- ? { deepScan: { workers: 2, maxDiscoveryRuns: 5 } }+ ? {+ deepScan: {+ workers: 2,+ maxDiscoveryRuns: 5,+ ...(resolvedDeep+ ? {+ subagents: 0,+ stopAfterNoNew: 6,+ stopAfterConsecutiveErrors: 2,+ maxTimeHours: 1.5,+ }+ : {}),+ },+ ...(resolvedDeep ? { deepScanResolved: true } : {}),+ }: {}),};const registration = await command(@@ -794,10 +813,20 @@ test.each([false, true])("resume restores saved launch settings (bulk: %s)",async (bulk) => {const settings = {+ auth: "api-key" as const,safetyIdentifier: "synthetic-original-user",postScanPrompt: "Run these exact saved post-scan instructions.\n",};- const f = await interruptedScan("deep", bulk, settings);+ const f = await interruptedScan("deep", bulk, settings, true);+ const ambientHome = join(f.root, "ambient-codex-home");+ f.environment.CODEX_HOME = ambientHome;+ const ambientDeepConfig = join(+ ambientHome,+ "codex-security",+ "config.toml",+ );+ await mkdir(join(ambientHome, "codex-security"), { recursive: true });+ await writeFile(ambientDeepConfig, "invalid ambient TOML [");const prompts: string[] = [];const stdout = capture();const stderr = capture();@@ -817,6 +846,7 @@ test.each([false, true])(expect(options.env?.["CODEX_SAFETY_IDENTIFIER"]).toBe(settings.safetyIdentifier,);+ expect(options.apiKey).toBe("synthetic-resume-key");return {startThread() {throw new Error("Resume must use the original session.");@@ -827,7 +857,19 @@ test.each([false, true])(id: threadId,async runStreamed(prompt) {prompts.push(prompt as string);- if (prompts.length === 1) await finishDiscovery(f);+ if (prompts.length === 1) {+ expect(prompt).toContain(+ "Keep the original scan instructions.",+ );+ const deep = await readFile(+ join(f.codexHome, "codex-security", "config.toml"),+ "utf8",+ );+ expect(deep).toContain("subagents = 0");+ expect(deep).toContain("stop_after_consecutive_errors = 2");+ expect(deep).toContain("max_time_hours = 1.5");+ await finishDiscovery(f);+ }return { events: completedEvents(threadId) };},};diff --git a/sdk/typescript/tests-ts/sdk-project-config.test.ts b/sdk/typescript/tests-ts/sdk-project-config.test.tsnew file mode 100644index 000000000..63421e482--- /dev/null+++ b/sdk/typescript/tests-ts/sdk-project-config.test.ts@@ -0,0 +1,252 @@+import { mkdir, stat, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { afterEach, expect, test } from "bun:test";+import { stringify } from "yaml";+import {+ DiffTarget,+ loadProjectConfig,+ resolveProjectConfig,+ type ProjectConfigInput,+ type ScanOptions,+ type ScanSettings,+} from "../src/index.js";+import { main } from "../src/cli.js";+import { capture, dependencies } from "./cli-fixtures.js";+import { TestClient } from "./support/api-client.js";+import { createApiTestFixtures } from "./support/api-events.js";++const { cleanup, temporaryDirectory } = createApiTestFixtures();+afterEach(cleanup);++test.each(["standard", "deep"] as const)(+ "%s settings agree across SDK options, typed configuration, YAML, JSON, and CLI flags",+ async (mode) => {+ const root = await temporaryDirectory();+ const repository = join(root, "repository");+ const directory = join(root, "settings");+ const output = join(root, "output");+ await mkdir(join(repository, "src"), { recursive: true });+ await mkdir(directory);+ await writeFile(join(directory, "context.md"), "Synthetic context.");+ await writeFile(join(directory, "scan.md"), "Synthetic instructions.");+ const deep = {+ workers: 2,+ subagents: 0,+ stopAfterNoNew: 3,+ stopAfterConsecutiveErrors: 2,+ maxDiscoveryRuns: 6,+ maxTimeHours: 1.5,+ };+ const input = {+ auth: "api-key",+ scan: {+ mode,+ scope: { paths: ["src"] },+ knowledge_base: ["context.md"],+ instructions_file: "scan.md",+ deep: {+ workers: 2,+ subagents_per_worker: 0,+ stop_after_no_new: 3,+ stop_after_consecutive_errors: 2,+ max_discovery_runs: 6,+ max_time_hours: 1.5,+ },+ },+ output: { directory: "../output" },+ limits: { max_cost_usd_per_scan: 5 },+ policy: { fail_on_severity: "high" },+ codex: {+ profile: "review",+ profiles: {+ review: { model: "gpt-5.6-terra", model_reasoning_effort: "high" },+ },+ },+ } satisfies ProjectConfigInput;+ const original = structuredClone(input);+ const options = {+ auth: "api-key",+ mode,+ target: ["src"],+ knowledgeBasePaths: [join(directory, "context.md")],+ scanPromptFile: join(directory, "scan.md"),+ outputDir: output,+ maxCostUsd: 5,+ failureSeverity: "high",+ ...(mode === "deep" ? deep : {}),+ } satisfies ScanSettings;+ const environment = {+ CODEX_HOME: join(root, "ambient"),+ CODEX_SECURITY_STATE_DIR: join(root, "state"),+ OPENAI_API_KEY: "synthetic-test-key",+ };+ const clientDependencies = {+ environment,+ prepareRuntime: async () => {+ throw new Error("Preflight must not initialize a runtime");+ },+ };+ await using direct = new TestClient(+ { codexOverrides: input.codex },+ clientDependencies,+ );+ const expected = await direct.preflight(repository, options);+ const configurations = [resolveProjectConfig(input, directory)];+ const commands: string[][] = [];+ for (const extension of ["yaml", "json"]) {+ const file = join(directory, `scan.${extension}`);+ await writeFile(+ file,+ extension === "yaml" ? stringify(input) : JSON.stringify(input),+ );+ const loaded = await loadProjectConfig(`scan.${extension}`, directory);+ expect(loaded.projectConfig?.path).toBe(file);+ configurations.push(loaded);+ commands.push(["scan", repository, "-c", file]);+ }+ for (const configuration of configurations) {+ expect(configuration.config).toEqual({ codexOverrides: input.codex });+ expect<ScanOptions>(configuration.options).toEqual({+ ...options,+ validationPromptFile: undefined,+ });+ await using client = new TestClient(+ configuration.config,+ clientDependencies,+ );+ expect(await client.preflight(repository, configuration.options)).toEqual(+ expected,+ );+ }+ commands.push([+ "scan",+ repository,+ "--auth",+ "api-key",+ "--mode",+ mode,+ "--path",+ "src",+ "--knowledge-base",+ join(directory, "context.md"),+ "--scan-prompt-file",+ join(directory, "scan.md"),+ "--output-dir",+ output,+ "--max-cost",+ "5",+ "--fail-on-severity",+ "high",+ "--codex",+ 'profile="review"',+ "--codex",+ 'profiles.review.model="gpt-5.6-terra"',+ "--codex",+ 'profiles.review.model_reasoning_effort="high"',+ ...(mode === "deep"+ ? [+ "--workers",+ "2",+ "--subagents",+ "0",+ "--stop-after-no-new",+ "3",+ "--max-discovery-runs",+ "6",+ "--max-time-hours",+ "1.5",+ ]+ : []),+ ]);+ for (const command of commands) {+ const stdout = capture();+ const stderr = capture();+ const deps = dependencies({ currentDirectory: root, environment });+ let selected: ScanOptions | undefined;+ deps.createSecurity = (config) => {+ const client = new TestClient(config, clientDependencies);+ return {+ run: client.run.bind(client),+ close: client.close.bind(client),+ preflight: async (repository, options) => {+ selected = options;+ return await client.preflight(repository, options);+ },+ };+ };+ expect(+ await main(+ [...command, "--dry-run", "--json"],+ stdout.stream,+ stderr.stream,+ deps,+ ),+ ).toBe(0);+ expect(selected).toMatchObject({+ failureSeverity: "high",+ scanPrompt: "Synthetic instructions.",+ });+ const resolved = JSON.parse(stdout.text());+ // The CLI has no flag for stopAfterConsecutiveErrors; files and SDK calls do.+ expect(resolved).toMatchObject({+ ...expected,+ ...(mode === "deep" && command[2] !== "-c"+ ? {+ stopAfterConsecutiveErrors: 3,+ deepScanSources: {+ ...expected.deepScanSources,+ stopAfterConsecutiveErrors: "default",+ },+ }+ : {}),+ ...(command[2] === "-c" ? { failOnSeverity: "high" } : {}),+ });+ }+ expect(input).toEqual(original);+ await expect(stat(output)).rejects.toThrow();+ await expect(stat(environment.CODEX_SECURITY_STATE_DIR)).rejects.toThrow();+ },+);++test("typed configuration keeps repository-relative scopes and does not discover files", async () => {+ const directory = await temporaryDirectory();+ await writeFile(join(directory, "codex-security.yaml"), "scan: [");+ expect(resolveProjectConfig({}, directory)).toMatchObject({+ config: { codexOverrides: {} },+ options: {+ auth: "auto",+ mode: "standard",+ target: "repository",+ knowledgeBasePaths: [],+ },+ });+ expect(resolveProjectConfig({}, directory).projectConfig).toBeUndefined();+ for (const [scope, target] of [+ [{ paths: ["src"] }, ["src"]],+ [{ diff: { base: "HEAD~1" } }, DiffTarget.refs({ base: "HEAD~1" })],+ [{ working_tree: {} }, DiffTarget.workingTree({})],+ ] as const) {+ expect(+ resolveProjectConfig(+ { scan: { scope: structuredClone(scope) } } as ProjectConfigInput,+ directory,+ ).options.target,+ ).toEqual(target);+ }+});++test("public file and object entry points reject the same invalid settings", async () => {+ const directory = await temporaryDirectory();+ for (const input of [+ { scan: { workres: 2 } },+ { limits: { max_cost_usd_per_scan: 0 } },+ { scan: { deep: { subagents_per_worker: -1 } } },+ { limits: { maxCostUsdPerScan: 5 } },+ JSON.parse('{"codex":{"__proto__":{"synthetic":true}}}'),+ ]) {+ const file = join(directory, "scan.json");+ await writeFile(file, JSON.stringify(input));+ expect(() => resolveProjectConfig(input, directory)).toThrow();+ await expect(loadProjectConfig(file)).rejects.toThrow();+ }+});diff --git a/sdk/typescript/tests-ts/sdk-scan-prompts.test.ts b/sdk/typescript/tests-ts/sdk-scan-prompts.test.tsnew file mode 100644index 000000000..2cedbb360--- /dev/null+++ b/sdk/typescript/tests-ts/sdk-scan-prompts.test.ts@@ -0,0 +1,180 @@+import { mkdir, symlink, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { afterEach, expect, test } from "bun:test";+import type { JsonObject } from "../src/index.js";+import { main } from "../src/cli.js";+import { capture, dependencies } from "./cli-fixtures.js";+import { mockWorkbench, TestClient } from "./support/api-client.js";+import {+ completedEvents,+ createApiTestFixtures,+ preparedRuntime,+} from "./support/api-events.js";++const { cleanup, copyCompletedScan, temporaryDirectory } =+ createApiTestFixtures();+afterEach(cleanup);++test.each([+ ["omitted", undefined],+ ["empty inline", ""],+ ["blank inline", " \n\t"],+ ["instructions", "Review the synthetic authorization boundary."],+ ["empty file", undefined],+] as const)(+ "SDK %s prompts require rerun instructions only when used",+ async (scenario, scanPrompt) => {+ const root = await temporaryDirectory();+ const repository = join(root, "repository");+ const codexHome = join(root, "codex-home");+ const scanDir = join(root, "scan");+ await mkdir(repository);+ await mkdir(codexHome);+ await mkdir(scanDir, { mode: 0o700 });+ const file = join(root, "empty.md");+ if (scenario === "empty file") await writeFile(file, " \n");+ let recipe: JsonObject | undefined;+ await using client = new TestClient(+ {},+ {+ environment: { CODEX_SECURITY_STATE_DIR: join(root, "state") },+ prepareRuntime: async () => preparedRuntime(codexHome),+ resolvePluginPython: async () => "/managed/python",+ prepareOutputDir: async () => scanDir,+ repositoryRevision: async () => "deadbeef",+ runWorkbench: async (_options, args, input) => {+ if (args[0] === "register-cli-scan")+ recipe = JSON.parse(input!).recipe;+ return mockWorkbench(args, input);+ },+ createCodex: () => ({+ startThread: () => ({+ id: "thread-1",+ async runStreamed() {+ await copyCompletedScan(root);+ return { events: completedEvents() };+ },+ }),+ }),+ },+ );+ await client.run(+ repository,+ scenario === "empty file" ? { scanPromptFile: file } : { scanPrompt },+ );+ expect(recipe).toBeDefined();+ const requiresInstructions = scenario === "instructions";+ let reran = false;+ const stderr = capture();+ const exit = await main(+ ["scans", "rerun", "saved", "--json"],+ capture().stream,+ stderr.stream,+ dependencies({+ currentDirectory: repository,+ onWorkbench: async () => ({ recipe: recipe! }),+ onRun: () => {+ reran = true;+ },+ }),+ );+ expect(exit).toBe(requiresInstructions ? 2 : 0);+ expect(reran).toBe(!requiresInstructions);+ expect(recipe?.["requiresScanPrompt"]).toBe(+ requiresInstructions ? true : undefined,+ );+ if (requiresInstructions)+ expect(stderr.text()).toContain("additional instructions");+ },+);++test.each([+ ["scanPromptFile", "scanPrompt"],+ ["validationPromptFile", "validationPrompt"],+ ["postScanPromptFile", "postScanPrompt"],+] as const)(+ "SDK %s uses the existing file protections and permits explicit external files",+ async (fileOption, inlineOption) => {+ const root = await temporaryDirectory();+ const repository = join(root, "repository");+ const external = join(root, "external");+ const linked = join(repository, "linked");+ await mkdir(repository);+ await mkdir(external);+ const file = join(external, "prompt.md");+ await writeFile(file, "Synthetic private instructions.");+ await symlink(+ external,+ linked,+ process.platform === "win32" ? "junction" : "dir",+ );+ await using client = new TestClient(+ {},+ {+ environment: { CODEX_SECURITY_STATE_DIR: join(root, "state") },+ prepareRuntime: async () => {+ throw new Error("Runtime must not start");+ },+ },+ );+ for (const operation of ["preflight", "run"] as const) {+ await expect(+ client[operation](repository, { [fileOption]: external }),+ ).rejects.toThrow("Input files must be regular files");+ await expect(+ client[operation](repository, {+ [fileOption]: join(linked, "prompt.md"),+ }),+ ).rejects.toThrow(+ "Input files must not follow repository directory links",+ );+ }+ const preflight = await client.preflight(repository, {+ [fileOption]: file,+ });+ expect(preflight.mode).toBe("standard");+ expect(JSON.stringify(preflight)).not.toContain(+ "Synthetic private instructions",+ );+ await expect(+ client.preflight(repository, {+ [fileOption]: join(root, "missing.md"),+ [inlineOption]: "Explicit inline instructions.",+ }),+ ).resolves.toMatchObject({ mode: "standard" });+ },+);++test("SDK prompt files retain empty-file and deep-validation behavior", async () => {+ const root = await temporaryDirectory();+ const repository = join(root, "repository");+ await mkdir(repository);+ const empty = join(root, "empty.md");+ const validation = join(root, "validation.md");+ await writeFile(empty, " \n");+ await writeFile(validation, "Validate the synthetic fixture.");+ await using client = new TestClient(+ {},+ {+ environment: {+ CODEX_HOME: join(root, "ambient"),+ CODEX_SECURITY_STATE_DIR: join(root, "state"),+ },+ },+ );+ await expect(+ client.preflight(repository, {+ scanPromptFile: empty,+ postScanPromptFile: empty,+ }),+ ).resolves.toMatchObject({ mode: "standard" });+ await expect(+ client.preflight(repository, { validationPromptFile: empty }),+ ).rejects.toThrow("The validation prompt must not be empty");+ await expect(+ client.preflight(repository, {+ mode: "deep",+ validationPromptFile: validation,+ }),+ ).rejects.toThrow("Custom validation is not supported for Deep scans");+});diff --git a/sdk/typescript/tests-ts/skeleton.test.ts b/sdk/typescript/tests-ts/skeleton.test.tsindex 5e40f2cbb..1fc4587f1 100644--- a/sdk/typescript/tests-ts/skeleton.test.ts+++ b/sdk/typescript/tests-ts/skeleton.test.ts@@ -360,8 +360,10 @@ describe("TypeScript package skeleton", () => {await readFile(new URL("../package.json", import.meta.url), "utf8"),);- expect(packageJson.scripts.build).toBe(- "node --run clean && tsc -p tsconfig.build.json && node scripts/build-dashboard.mjs",+ expect(packageJson.scripts.build).not.toMatch(/\b(?:pnpm|npm|bun)\b/u);+ expect(packageJson.scripts.build).toMatch(/^node --run clean &&/u);+ expect(packageJson.scripts.build).toContain(+ "node scripts/build-dashboard.mjs",);expect(packageJson.scripts["build:plugin"]).toBe("node scripts/build-plugin.mjs",