@openai/codex-security 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +224 -14
  2. package/_bundled_plugin/examples/completed-scan/findings.json +6 -0
  3. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +1 -1
  4. package/_bundled_plugin/references/finding-detail-fields.md +10 -2
  5. package/_bundled_plugin/references/scan-contract.md +2 -0
  6. package/_bundled_plugin/scripts/finalize_scan_contract.py +18 -0
  7. package/_bundled_plugin/scripts/workbench_cli.py +4 -0
  8. package/_bundled_plugin/scripts/workbench_db.py +93 -23
  9. package/_bundled_plugin/scripts/workbench_scan_start.py +13 -0
  10. package/_bundled_plugin/scripts/workbench_target.py +14 -1
  11. package/dist/api.d.ts +3 -2
  12. package/dist/api.d.ts.map +1 -1
  13. package/dist/api.js +288 -70
  14. package/dist/api.js.map +1 -1
  15. package/dist/auth.d.ts.map +1 -1
  16. package/dist/auth.js +262 -44
  17. package/dist/auth.js.map +1 -1
  18. package/dist/cli.d.ts +4 -3
  19. package/dist/cli.d.ts.map +1 -1
  20. package/dist/cli.js +364 -154
  21. package/dist/cli.js.map +1 -1
  22. package/dist/config.d.ts.map +1 -1
  23. package/dist/config.js +29 -1
  24. package/dist/config.js.map +1 -1
  25. package/dist/contract.d.ts +1 -0
  26. package/dist/contract.d.ts.map +1 -1
  27. package/dist/contract.js +33 -22
  28. package/dist/contract.js.map +1 -1
  29. package/dist/cost.d.ts.map +1 -1
  30. package/dist/cost.js +57 -14
  31. package/dist/cost.js.map +1 -1
  32. package/dist/errors.d.ts +2 -0
  33. package/dist/errors.d.ts.map +1 -1
  34. package/dist/errors.js +48 -0
  35. package/dist/errors.js.map +1 -1
  36. package/dist/multiscan.d.ts.map +1 -1
  37. package/dist/multiscan.js +2 -7
  38. package/dist/multiscan.js.map +1 -1
  39. package/dist/runtime.d.ts +34 -0
  40. package/dist/runtime.d.ts.map +1 -1
  41. package/dist/runtime.js +655 -20
  42. package/dist/runtime.js.map +1 -1
  43. package/dist/scan-comparison.d.ts +2 -0
  44. package/dist/scan-comparison.d.ts.map +1 -1
  45. package/dist/scan-comparison.js +26 -2
  46. package/dist/scan-comparison.js.map +1 -1
  47. package/dist/trusted-executable.js +1 -1
  48. package/dist/trusted-executable.js.map +1 -1
  49. package/package.json +5 -4
package/README.md CHANGED
@@ -15,10 +15,11 @@ npm install @openai/codex-security
15
15
  npx @openai/codex-security --version
16
16
  ```
17
17
 
18
- The package supports macOS, Linux, and Windows and requires Node.js 22 or
19
- later. Scanning and exporting findings also require Python 3.10 or later. If
20
- you use Python 3.10, install the `tomli` package. Select another interpreter
21
- with `--python`, `pythonPath`, or `PYTHON` when needed.
18
+ The package supports macOS, Linux, and Windows and requires Node.js 22.13.0 or
19
+ later in the 22.x release line, Node.js 24.x, or Node.js 26.x. Scanning and
20
+ exporting findings also require Python 3.10 or later. If you use Python 3.10,
21
+ install the `tomli` package. Select another interpreter with `--python`,
22
+ `pythonPath`, or `PYTHON` when needed.
22
23
 
23
24
  When a newer version is available, the CLI shows the update command for your
24
25
  installation method. Set `CODEX_SECURITY_NO_UPDATE_NOTICE=1` to hide the
@@ -56,6 +57,39 @@ Results can contain source excerpts, vulnerability details, and reproduction
56
57
  steps. Keep result directories and saved reports outside the repository and
57
58
  limit access to authorized reviewers.
58
59
 
60
+ ### SDK configuration and scan options
61
+
62
+ Pass runtime configuration to the `CodexSecurity` constructor:
63
+
64
+ | Option | Description |
65
+ | ---------------- | --------------------------------------------------------------------------- |
66
+ | `pluginPath` | Use a Codex Security plugin directory or ZIP instead of the bundled plugin. |
67
+ | `pythonPath` | Select the Python interpreter before consulting `PYTHON`. |
68
+ | `codexOverrides` | Deep-merge supported settings into the isolated Codex configuration. |
69
+
70
+ Pass scan configuration to `security.run(repository, options)` or
71
+ `security.preflight(repository, options)`:
72
+
73
+ | Option | Description |
74
+ | ----------------------- | ------------------------------------------------------------------------------------- |
75
+ | `auth` | Select `"auto"`, `"chatgpt"`, or `"api-key"`. |
76
+ | `target` | Select a repository, repository-relative paths, committed diff, or working-tree diff. |
77
+ | `mode` | Select `"standard"` or `"deep"`; deep mode supports repositories and paths. |
78
+ | `knowledgeBasePaths` | Add architecture documents, security policies, threat models, or directories. |
79
+ | `outputDir` | Choose an artifact directory outside the enclosing Git worktree. |
80
+ | `archiveExisting` | Archive results already in `outputDir` before starting a scan. |
81
+ | `maxCostUsd` | Stop after the estimated model cost exceeds a positive USD amount. |
82
+ | `failureSeverity` | Record a finding-severity policy in the saved scan recipe. |
83
+ | `parentScanId` | Link a rerun to an existing parent scan. |
84
+ | `expectedPluginVersion` | Require the original plugin version when replaying a scan. |
85
+ | `signal` | Cancel a scan with an `AbortSignal`. |
86
+
87
+ Progress and lifecycle callbacks are `onAuthentication`, `onCost`,
88
+ `onOutputArchived`, `onOutputDirReady`, `onScanStarted`, `onReconnect`,
89
+ `onWorkerStatus`, `onWarning`, and `onObserverError`. Preflight does not start
90
+ the runtime, authenticate, resolve Python, inspect the plugin, or run those
91
+ scan-lifecycle callbacks.
92
+
59
93
  ## Authentication
60
94
 
61
95
  For local use, sign in with ChatGPT:
@@ -78,6 +112,14 @@ pass it on stdin:
78
112
  printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
79
113
  ```
80
114
 
115
+ Environment API keys are supplied directly to the current scan and are never
116
+ saved to the Codex credential home or system keyring. Only an explicit
117
+ `login --with-api-key` stores an API key.
118
+
119
+ To pass a Codex access token explicitly, use
120
+ `login --with-access-token` and provide the token on stdin. An access token
121
+ environment variable is not automatically used as a scan API key.
122
+
81
123
  On Windows, set the API key in PowerShell:
82
124
 
83
125
  ```powershell
@@ -85,10 +127,16 @@ $env:OPENAI_API_KEY = "<your-api-key>"
85
127
  npx @openai/codex-security scan C:\code\repository
86
128
  ```
87
129
 
88
- Check or remove the stored sign-in with `npx @openai/codex-security login status` and
89
- `npx @openai/codex-security logout`. Codex Security reuses an existing file-based Codex
90
- sign-in. If Codex stores credentials in the system keyring, run
91
- `npx @openai/codex-security login` once before scanning.
130
+ Check or remove the stored sign-in with `npx @openai/codex-security login status`
131
+ and `npx @openai/codex-security logout`. Codex Security keeps its sign-in in a
132
+ private, stable Codex home at `$CODEX_SECURITY_STATE_DIR/codex-home`, or at
133
+ `$CODEX_HOME/state/plugins/codex-security/codex-home` when no state directory is
134
+ configured. Login, status, logout, and scans use the same home. Codex manages
135
+ credentials using its configured file or system-keyring backend and honors
136
+ managed-device policies. An existing file-based Codex sign-in is imported only
137
+ when the dedicated home does not already contain stored credentials. Logging
138
+ out prevents later scans from automatically reimporting that ambient sign-in
139
+ until you explicitly log in again.
92
140
 
93
141
  An environment API key takes precedence over a stored sign-in by default.
94
142
  When both a stored ChatGPT sign-in and an environment API key are available, an
@@ -197,9 +245,127 @@ the implied provider. Use `--model gpt-5.6-terra` to switch models and
197
245
  `--codex KEY=VALUE` for other Codex settings; existing
198
246
  `--codex 'model_reasoning_effort="high"'` overrides remain supported.
199
247
 
248
+ ### Runtime configuration and worker limits
249
+
250
+ The standalone CLI and SDK do not load an unrelated user or repository Codex
251
+ configuration. Each scan starts with a private runtime and these Codex
252
+ defaults:
253
+
254
+ ```toml
255
+ cli_auth_credentials_store = "file"
256
+ model = "gpt-5.6-sol"
257
+ model_reasoning_effort = "xhigh"
258
+
259
+ [features]
260
+ plugins = true
261
+ goals = true
262
+
263
+ [features.multi_agent_v2]
264
+ enabled = true
265
+ max_concurrent_threads_per_session = 9
266
+
267
+ [windows]
268
+ sandbox = "unelevated"
269
+ ```
270
+
271
+ Use `--model` and `--effort` for model selection. Repeat
272
+ `--codex KEY=VALUE` to deep-merge other TOML values into this isolated
273
+ configuration:
274
+
275
+ ```bash
276
+ npx @openai/codex-security scan . \
277
+ --model gpt-5.6-terra \
278
+ --effort high \
279
+ --codex features.multi_agent_v2.max_concurrent_threads_per_session=4
280
+ ```
281
+
282
+ The session thread limit includes the parent agent: the default of `9`
283
+ provides up to eight delegated worker slots. This limit is separate from
284
+ `bulk-scan --workers`, which controls how many repositories run concurrently.
285
+ A configured limit is a maximum, not evidence that every worker started.
286
+
287
+ Quote string values as TOML, for example
288
+ `--codex 'model_reasoning_effort="high"'`. Do not pass both `--model` and
289
+ `--codex 'model="..."'`, or both `--effort` and
290
+ `--codex 'model_reasoning_effort="..."'`: conflicting or repeated keys are
291
+ rejected.
292
+
293
+ Plugin and marketplace loading belong to Codex Security. Overrides of
294
+ `plugins`, `marketplaces`, or `features.plugins`, including profile-specific
295
+ plugin overrides, are rejected; choose `--plugin-path` instead. Native
296
+ multi-agent v2 must remain enabled. The legacy `agents.max_threads` setting
297
+ and `features.multi_agent_v2.enabled=false` are incompatible and rejected.
298
+ `validate` and `patch` accept `--effort` and only the `model` and
299
+ `model_reasoning_effort` `--codex` keys; they do not accept general scan
300
+ runtime overrides.
301
+
200
302
  These overrides do not change the scan's approval policy or filesystem
201
303
  permissions. See [Local security model](#local-security-model).
202
304
 
305
+ ### Deep-scan engine configuration
306
+
307
+ When the bundled plugin runs in a normal Codex host, its repeated-discovery
308
+ engine reads `$CODEX_HOME/codex-security/config.toml`, defaulting to
309
+ `~/.codex/codex-security/config.toml`:
310
+
311
+ ```toml
312
+ [deep_scan]
313
+ workers = "auto"
314
+ subagents = 3
315
+ stop_after_no_new = 6
316
+ max_discovery_runs = 60
317
+ ```
318
+
319
+ `workers = "auto"` uses half the available parallelism, with a minimum of one
320
+ and a maximum of six discovery workers. Set `workers` to a positive integer to
321
+ choose an explicit count. `subagents` must be a nonnegative integer;
322
+ `stop_after_no_new` and `max_discovery_runs` must be positive integers. Unknown
323
+ `[deep_scan]` keys are rejected.
324
+
325
+ These settings are separate from Codex's
326
+ `features.multi_agent_v2.max_concurrent_threads_per_session` and
327
+ `bulk-scan --workers`. Importantly, standalone CLI and SDK scans create an
328
+ isolated `CODEX_HOME` and do not import the ambient deep-scan configuration
329
+ file. Consequently, `scan --mode deep` currently uses the deep engine's
330
+ defaults; there are no standalone CLI flags for these four settings. Use
331
+ `--codex` to adjust the Codex session thread limit, not to set `[deep_scan]`
332
+ values.
333
+
334
+ ### Environment variables
335
+
336
+ The CLI and SDK recognize the following user-configurable environment:
337
+
338
+ | Variable | Effect |
339
+ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
340
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan authentication; `OPENAI_API_KEY` wins when both are present. |
341
+ | `CODEX_SECURITY_STATE_DIR` | Override the private scan-history, workbench, and default artifact directory. |
342
+ | `CODEX_HOME` | Set the ambient Codex home for file-backed sign-in and default state; defaults to `~/.codex`. |
343
+ | `PYTHON` | Select a Python interpreter when `--python` or SDK `pythonPath` is not set. |
344
+ | `GH_HOST` | Select a GitHub Enterprise host during interactive `bulk-scan` discovery. |
345
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices when either variable is defined. |
346
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Select the update-check registry, in the listed precedence order. |
347
+ | `CI` | Disable interactive update notices in automated environments. |
348
+ | `NO_COLOR`, `TERM` | Disable colored scan-history output when `NO_COLOR` is defined or `TERM=dumb`. |
349
+
350
+ Interpreter discovery uses `--python` or `pythonPath` first, then `PYTHON`,
351
+ the managed Codex runtime, and finally `python3` or `python` from `PATH`.
352
+ `CODEX_SECURITY_STATE_DIR` takes precedence over `CODEX_HOME`; keep both
353
+ state and result paths outside the scanned repository.
354
+
355
+ The repository's Docker Compose workflow additionally recognizes
356
+ `CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`, `CODEX_SECURITY_SECCOMP`,
357
+ `CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and `CODEX_SECURITY_STATE` for
358
+ its image, runtime user, seccomp profile, input, results, and state mounts.
359
+ Provide `GH_TOKEN` or `GITHUB_TOKEN` for private GitHub checkouts and
360
+ `CODEX_SECURITY_GIT_HOST` for a GitHub Enterprise host in the container.
361
+ These container settings are distinct from standalone CLI flags and
362
+ interactive discovery's `GH_HOST`.
363
+
364
+ Variables such as `CODEX_SECURITY_SCAN_ID`, `CODEX_SECURITY_SCAN_DIR`,
365
+ `CODEX_SECURITY_PLUGIN_ROOT`, `CODEX_SECURITY_CONFIG_PATH`, and
366
+ `CODEX_SECURITY_TARGET_PATHS_FILE` are generated by an active scan. They are
367
+ internal runtime data, not supported user configuration.
368
+
203
369
  Scan progress identifies the requested paths and reports actual ranking,
204
370
  file-review, validation, and attack-path phases as they become available.
205
371
  Completion summarizes findings, severity, coverage, elapsed time, available
@@ -214,7 +380,9 @@ including cached input and cache writes; fees and surcharges are not included.
214
380
 
215
381
  Use `--max-cost USD` to stop a scan, including its delegated workers, when its
216
382
  running cost exceeds the limit. Partial results are preserved. Requests
217
- already in progress can finish above the limit.
383
+ already in progress can finish above the limit. Cost tracking accepts Codex
384
+ session events up to 1 MiB; an oversized event stops the scan because its
385
+ running cost can no longer be verified safely.
218
386
 
219
387
  Run `npx @openai/codex-security scan --help` or `npx @openai/codex-security bulk-scan --help`
220
388
  for the complete CLI references.
@@ -244,7 +412,8 @@ Results remain under `--output-dir`; rerun the same command to resume.
244
412
  `npx @openai/codex-security scans list` lists scans for the current repository. Pass a
245
413
  repository path to inspect another checkout, `--scan-root DIR` to list scans
246
414
  whose artifacts are under a particular root. `scans show SCAN_ID` includes the
247
- scan configuration, results, coverage, and artifact locations.
415
+ scan configuration, results, coverage, and artifact locations. Add
416
+ `--show-linked-findings` to include finding links from previous scans.
248
417
 
249
418
  Every scan history command accepts a full scan ID or a unique prefix of at
250
419
  least eight characters.
@@ -274,10 +443,10 @@ cause; `scans match --all` matches all completed scans of the current repository
274
443
  including other worktrees and clones. Saved matches appear in `scans show` and
275
444
  are reused unless `--force` is passed. Scans without sealed artifacts are skipped.
276
445
 
277
- `scans compare BEFORE_SCAN_ID AFTER_SCAN_ID` reads saved matches and reports
278
- findings as new, persisting, reopened, resolved, or unknown. Missing findings
279
- are not treated as resolved when the later scan is incomplete or does not cover
280
- their original scope.
446
+ `scans compare BEFORE_SCAN_ID AFTER_SCAN_ID` automatically matches findings by
447
+ root cause, reuses saved matches, and reports findings as new, persisting,
448
+ reopened, resolved, or unknown. Missing findings are not treated as resolved when
449
+ the later scan is incomplete or does not cover their original scope.
281
450
 
282
451
  The CLI uses [Incur](https://github.com/wevm/incur) for agent-friendly discovery
283
452
  and structured output. Inspect the command manifest with `--llms`, inspect a
@@ -347,6 +516,47 @@ Progress remains on stderr so JSON output stays machine readable. Network
347
516
  failures and rate limits remain retryable; definitive authentication and model
348
517
  authorization failures stop immediately.
349
518
 
519
+ ## Containerized bulk scans
520
+
521
+ Create `repositories.csv` with one full, immutable Git commit per repository:
522
+
523
+ ```csv
524
+ id,repository,revision
525
+ payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567
526
+ ```
527
+
528
+ Once the approved image has been published, prepare private results and
529
+ authentication directories, sign in, and run the Docker Compose configuration
530
+ from the root of the Codex Security repository:
531
+
532
+ ```bash
533
+ mkdir -p results state
534
+ chmod 700 results state
535
+ export CODEX_SECURITY_USER="$(id -u):$(id -g)"
536
+ export CODEX_SECURITY_IMAGE=ghcr.io/openai/codex-security:0.1.4
537
+ docker compose pull codex-security
538
+ docker compose run --rm codex-security login --device-auth
539
+ docker compose run --rm codex-security
540
+ ```
541
+
542
+ Reports and resumable scan results are written to `results/`; the reusable
543
+ device login remains in `state/`. For unattended scans, set `OPENAI_API_KEY`
544
+ or `CODEX_API_KEY` instead. Set `GH_TOKEN` or `GITHUB_TOKEN` for private
545
+ GitHub repositories.
546
+
547
+ On Ubuntu hosts that restrict unprivileged user namespaces, an administrator
548
+ can install the optional, narrowly scoped AppArmor profile once:
549
+
550
+ ```bash
551
+ sudo install -m 0644 docker/codex-security.apparmor /etc/apparmor.d/codex-security-container
552
+ sudo apparmor_parser -r -W /etc/apparmor.d/codex-security-container
553
+ docker compose -f compose.yaml -f compose.apparmor.yaml run --rm codex-security
554
+ ```
555
+
556
+ The override preserves the nonroot user, dropped capabilities,
557
+ no-new-privileges, and hardened seccomp policy. Other Docker hosts do not need
558
+ the profile or override.
559
+
350
560
  ## Local security model
351
561
 
352
562
  Codex Security runs with your local operating-system permissions. Scan only
@@ -42,6 +42,12 @@
42
42
  "remediation": "Normalize destinations and reject entries that escape the extraction root.",
43
43
  "validation": null,
44
44
  "attackPath": null,
45
+ "remediationTests": [
46
+ "Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root."
47
+ ],
48
+ "preventiveControls": [
49
+ "Route all archive extraction through one helper that normalizes and validates destination paths."
50
+ ],
45
51
  "provenance": {
46
52
  "source": "local_plugin"
47
53
  },
@@ -30,7 +30,7 @@
30
30
  "artifacts": [
31
31
  {
32
32
  "path": "findings.json",
33
- "sha256": "db5ce8533c1b6cd9131f9e12e8bb705f63474caa2a3f7dd21207666b3a8da777",
33
+ "sha256": "a6dc4521d6478828224fbafc33585401a47bfeb0e56e07b5d2886e8a29937f2f",
34
34
  "mediaType": "application/json"
35
35
  },
36
36
  {
@@ -23,7 +23,7 @@ The finding detail view is a decision-focused projection of the canonical findin
23
23
  - dataflow source, meaningful transformations, dangerous sink, and concrete outcome;
24
24
  - realistic attacker, entry point, access requirements, preconditions, and attacker outcome;
25
25
  - severity rationale plus the specific evidence that would raise or lower the rating;
26
- - the minimal remediation invariant, regression tests, and preventive controls.
26
+ - the minimal remediation invariant (`remediation`, a single string), plus `remediationTests` and `preventiveControls`, each an array of short strings with one regression test or preventive control per entry.
27
27
 
28
28
  Keep background exposition, alternate exploit research, full PoC instructions, representative command output, and long source walkthroughs in the detailed write-up. Do not copy them into canonical fields merely to make the workspace report longer. The workspace should stay self-contained enough to support triage while avoiding duplicated or speculative prose.
29
29
 
@@ -155,7 +155,15 @@ The following shape shows how to encode the `environment/add` reserved-environme
155
155
  "limitations": [
156
156
  "This overwrite does not directly execute code on the victim host."
157
157
  ]
158
- }
158
+ },
159
+ "remediation": "Reuse the startup reserved-ID check inside `EnvironmentManager::upsert_environment()` so the runtime mutation path rejects the reserved `local` identifier.",
160
+ "remediationTests": [
161
+ "Assert that `environment/add` with `environmentId: \"local\"` returns a protocol error.",
162
+ "Assert that `default_environment()` still resolves the manager-owned local runtime after a rejected upsert."
163
+ ],
164
+ "preventiveControls": [
165
+ "Centralize reserved-identifier validation so every environment mutation path shares one guard."
166
+ ]
159
167
  }
160
168
  ```
161
169
 
@@ -31,6 +31,8 @@ A sealed manifest records the completed timestamp and hashes for the canonical d
31
31
  Choose the target kind based on the reviewed content, not the scan invocation:
32
32
  `git_worktree` for a checked-out Git workspace, `directory_snapshot` for a non-Git directory, `git_diff` for a Git-backed change set, and `git_revision` for an exact immutable Git tree.
33
33
 
34
+ For a workbench-backed scan, use the recorded target contract instead of inferring the kind from the checkout. A clean Git checkout has `allowedKinds: ["git_revision"]`: use its recorded revision and omit `snapshotDigest`. A dirty checkout has `allowedKinds: ["git_worktree"]`: copy `requiredSnapshotDigest` exactly.
35
+
34
36
  | Kind | Required snapshot fields |
35
37
  | --- | --- |
36
38
  | `git_revision` | `revision` |
@@ -796,6 +796,12 @@ def _recover_unsealed_findings(
796
796
  writeup_schema = _require_dict(
797
797
  finding_properties, "writeup", "findings.schema.properties.findings.items.properties"
798
798
  )
799
+ auxiliary_schemas = {
800
+ name: _require_dict(
801
+ finding_properties, name, "findings.schema.properties.findings.items.properties"
802
+ )
803
+ for name in ("remediationTests", "preventiveControls")
804
+ }
799
805
  scan = _require_dict(manifest, "scan", "manifest")
800
806
  scan_id = _require_str(scan, "id", "manifest.scan")
801
807
  if findings.get("scanId") != scan_id:
@@ -854,6 +860,18 @@ def _recover_unsealed_findings(
854
860
  except ContractError as exc:
855
861
  finding.pop("writeup")
856
862
  warnings.append(f"Skipped malformed writeup for finding {index + 1}: {exc}.")
863
+ for auxiliary, auxiliary_schema in auxiliary_schemas.items():
864
+ if auxiliary not in finding:
865
+ continue
866
+ try:
867
+ _validate_schema_node(
868
+ finding[auxiliary], auxiliary_schema, f"{context}.{auxiliary}"
869
+ )
870
+ except ContractError as exc:
871
+ finding.pop(auxiliary)
872
+ warnings.append(
873
+ f"Skipped malformed {auxiliary} for finding {index + 1}: {exc}."
874
+ )
857
875
  _validate_schema_node(finding, finding_schema, context)
858
876
  except ContractError as exc:
859
877
  warning = f"Skipped malformed finding {index + 1}: {exc}."
@@ -210,6 +210,10 @@ def parse_args(description: str) -> argparse.Namespace:
210
210
  update_progress.add_argument("--deep-review-pass", type=positive_int)
211
211
  update_progress.add_argument("--claim-token")
212
212
 
213
+ prepare_scan_completion = subparsers.add_parser("prepare-scan-completion")
214
+ prepare_scan_completion.add_argument("--scan-id", required=True)
215
+ prepare_scan_completion.add_argument("--claim-token")
216
+
213
217
  complete_scan = subparsers.add_parser("complete-scan")
214
218
  complete_scan.add_argument("--scan-id", required=True)
215
219
  complete_scan.add_argument("--claim-token")
@@ -86,6 +86,7 @@ from workbench_scan_start import (
86
86
  safe_segment,
87
87
  scan_diff_identity,
88
88
  scan_target_identity,
89
+ stored_diff_target,
89
90
  )
90
91
  from workbench_schema import MIGRATIONS, normalize_pre_release_migrations, sql_statements
91
92
  from workbench_source_excerpt import finding_source_excerpt
@@ -504,19 +505,6 @@ def expected_target_kinds(scan: sqlite3.Row) -> list[str]:
504
505
  return ["git_worktree"]
505
506
 
506
507
 
507
- def stored_diff_target(row: sqlite3.Row) -> dict[str, str] | None:
508
- if not row["diff_target_kind"]:
509
- return None
510
- target = {
511
- "baseRevision": row["diff_base_revision"],
512
- "headRevision": row["diff_head_revision"],
513
- "kind": row["diff_target_kind"],
514
- }
515
- if row["diff_content_digest"]:
516
- target["contentDigest"] = row["diff_content_digest"]
517
- return target
518
-
519
-
520
508
  def requested_scan_paths(scan: sqlite3.Row) -> list[str]:
521
509
  if "recipe_json" in scan.keys() and scan["recipe_json"] is not None:
522
510
  recipe = json.loads(scan["recipe_json"], parse_constant=reject_non_finite_json)
@@ -1374,11 +1362,15 @@ def pin_legacy_manifest_digest(
1374
1362
  raise
1375
1363
 
1376
1364
 
1377
- def complete_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
1365
+ def complete_scan(
1366
+ connection: sqlite3.Connection, args: argparse.Namespace, *, prepare_only: bool = False
1367
+ ) -> dict[str, Any]:
1378
1368
  scan_id = require_uuid(args.scan_id, "scan-id")
1379
- cost_json = parse_scan_cost(args.cost_json)
1369
+ cost_json = None if prepare_only else parse_scan_cost(args.cost_json)
1380
1370
  with scan_completion_lock(scan_id):
1381
- return complete_scan_locked(connection, scan_id, args.claim_token, cost_json)
1371
+ return complete_scan_locked(
1372
+ connection, scan_id, args.claim_token, cost_json, prepare_only=prepare_only
1373
+ )
1382
1374
 
1383
1375
 
1384
1376
  def complete_scan_locked(
@@ -1386,6 +1378,8 @@ def complete_scan_locked(
1386
1378
  scan_id: str,
1387
1379
  claim_token: str | None,
1388
1380
  cost_json: str | None,
1381
+ *,
1382
+ prepare_only: bool = False,
1389
1383
  ) -> dict[str, Any]:
1390
1384
  scan = require_scan(connection, scan_id)
1391
1385
  if scan["status"] == "complete":
@@ -1412,15 +1406,36 @@ def complete_scan_locked(
1412
1406
  )
1413
1407
  if scan["recipe_json"] is None:
1414
1408
  deep_scan.require_deep_scan_ready_for_parent_completion(connection, scan)
1415
- warnings = []
1409
+ warnings = json.loads(scan["completion_warnings_json"])
1416
1410
  warning = scan_target_warning(scan)
1417
- if warning is not None:
1411
+ if warning is not None and warning not in warnings:
1418
1412
  warnings.append(warning)
1419
1413
  scan_dir = require_canonical_scan_directory(Path(scan["scan_dir"]))
1420
1414
  completion_timestamp = now()
1421
1415
  completion_binding = workbench_completion_binding(scan, completion_timestamp)
1422
1416
  if scan["recipe_json"] is not None:
1423
- manifest = read_json_object(artifact_path(scan_dir, ARTIFACTS["manifest"], required=True))
1417
+ draft_artifacts: dict[str, Path] = {}
1418
+ missing_drafts = []
1419
+ for file_name in (
1420
+ ARTIFACTS["manifest"],
1421
+ ARTIFACTS["findings"],
1422
+ ARTIFACTS["coverage"],
1423
+ ):
1424
+ try:
1425
+ (scan_dir / file_name).lstat()
1426
+ except FileNotFoundError:
1427
+ missing_drafts.append(file_name)
1428
+ continue
1429
+ draft_path = artifact_path(scan_dir, file_name, required=True)
1430
+ if draft_path is not None:
1431
+ draft_artifacts[file_name] = draft_path
1432
+ if missing_drafts:
1433
+ raise SystemExit(
1434
+ "Scan agent did not create required draft artifacts: "
1435
+ f"{', '.join(missing_drafts)}. Check that the scan agent can run shell "
1436
+ "commands and write to the scan directory before retrying."
1437
+ )
1438
+ manifest = read_json_object(draft_artifacts[ARTIFACTS["manifest"]])
1424
1439
  manifest_scan = manifest.get("scan")
1425
1440
  if isinstance(manifest_scan, dict) and manifest_scan.get("sealedAt") is not None:
1426
1441
  completion_binding["startedAt"] = manifest_scan.get("startedAt")
@@ -1443,9 +1458,23 @@ def complete_scan_locked(
1443
1458
  for kind, filename in ARTIFACTS.items()
1444
1459
  }
1445
1460
  manifest_digest = published_manifest_digest(scan_dir, manifest)
1461
+ if prepare_only:
1462
+ connection.execute("BEGIN IMMEDIATE")
1463
+ try:
1464
+ updated = connection.execute(
1465
+ "UPDATE scans SET completion_warnings_json = ? WHERE id = ? AND status = 'running'",
1466
+ (json.dumps(warnings), scan["id"]),
1467
+ )
1468
+ if updated.rowcount != 1:
1469
+ raise SystemExit("Only a running scan can be prepared for completion.")
1470
+ connection.commit()
1471
+ except BaseException:
1472
+ connection.rollback()
1473
+ raise
1474
+ return scan_context(connection, scan["id"])
1446
1475
  connection.execute("BEGIN IMMEDIATE")
1447
1476
  try:
1448
- timestamp = completion_timestamp
1477
+ timestamp = manifest["scan"]["completedAt"]
1449
1478
  scan = require_scan(connection, scan["id"])
1450
1479
  if scan["status"] == "complete":
1451
1480
  connection.commit()
@@ -1609,7 +1638,14 @@ def register_cli_scan(connection: sqlite3.Connection, args: argparse.Namespace)
1609
1638
  except BaseException:
1610
1639
  connection.rollback()
1611
1640
  raise
1612
- return {"scanDir": str(scan_dir), "scanId": scan_id, "targetId": target_id}
1641
+ scan = require_scan(connection, scan_id)
1642
+ return {
1643
+ "contract": scan_contract(scan),
1644
+ "scanDir": str(scan_dir),
1645
+ "scanId": scan_id,
1646
+ "targetId": target_id,
1647
+ "targetRevision": scan["target_revision"],
1648
+ }
1613
1649
 
1614
1650
 
1615
1651
  def parse_scan_recipe(value: str, repository: Path) -> dict[str, Any]:
@@ -3454,6 +3490,38 @@ def require_canonical_scan_directory(scan_dir: Path) -> Path:
3454
3490
  scan_dir
3455
3491
  ):
3456
3492
  raise SystemExit("Scan directory must be an existing canonical non-symlink directory.")
3493
+ # Re-check privacy on every resolution so a mid-scan rename/replace under a
3494
+ # shared parent cannot substitute another user's forged artifact tree.
3495
+ if os.name != "nt":
3496
+ if stat.S_IMODE(metadata.st_mode) & 0o077:
3497
+ raise SystemExit(
3498
+ "Scan directory must not be accessible to other users (chmod 700)."
3499
+ )
3500
+ geteuid = getattr(os, "geteuid", None)
3501
+ effective_uid = geteuid() if geteuid is not None else None
3502
+ if effective_uid is not None and metadata.st_uid != effective_uid:
3503
+ raise SystemExit("Scan directory must be owned by the current user.")
3504
+ for parent in scan_dir.parents:
3505
+ try:
3506
+ parent_metadata = parent.lstat()
3507
+ except OSError as exc:
3508
+ raise SystemExit("Scan output parent could not be inspected.") from exc
3509
+ if not stat.S_ISDIR(parent_metadata.st_mode) or stat.S_ISLNK(
3510
+ parent_metadata.st_mode
3511
+ ):
3512
+ raise SystemExit("Scan output parent must be a non-symlink directory.")
3513
+ if effective_uid is not None and parent_metadata.st_uid not in {
3514
+ 0,
3515
+ effective_uid,
3516
+ }:
3517
+ raise SystemExit("Scan output parent must have a trusted owner.")
3518
+ if (
3519
+ stat.S_IMODE(parent_metadata.st_mode) & 0o022
3520
+ and not parent_metadata.st_mode & stat.S_ISVTX
3521
+ ):
3522
+ raise SystemExit(
3523
+ "Scan output parent must not be group- or world-writable without the sticky bit."
3524
+ )
3457
3525
  return scan_dir
3458
3526
 
3459
3527
 
@@ -3596,8 +3664,10 @@ def main() -> None:
3596
3664
  require_scan=require_scan,
3597
3665
  scan_context=scan_context,
3598
3666
  )
3599
- elif args.command == "complete-scan":
3600
- result = complete_scan(connection, args)
3667
+ elif args.command in {"prepare-scan-completion", "complete-scan"}:
3668
+ result = complete_scan(
3669
+ connection, args, prepare_only=args.command == "prepare-scan-completion"
3670
+ )
3601
3671
  elif args.command == "cancel-scan":
3602
3672
  result = cancel_scan(connection, args)
3603
3673
  elif args.command == "fail-scan":
@@ -72,6 +72,19 @@ def scan_diff_identity(
72
72
  )
73
73
 
74
74
 
75
+ def stored_diff_target(row: sqlite3.Row) -> dict[str, str] | None:
76
+ if not row["diff_target_kind"]:
77
+ return None
78
+ target = {
79
+ "baseRevision": row["diff_base_revision"],
80
+ "headRevision": row["diff_head_revision"],
81
+ "kind": row["diff_target_kind"],
82
+ }
83
+ if row["diff_content_digest"]:
84
+ target["contentDigest"] = row["diff_content_digest"]
85
+ return target
86
+
87
+
75
88
  def archive_scan(
76
89
  connection: sqlite3.Connection,
77
90
  args: argparse.Namespace,
@@ -143,6 +143,13 @@ def worktree_content_digest_for_context(
143
143
  b"untracked-content",
144
144
  os.fsencode(os.readlink(path)),
145
145
  )
146
+ elif stat.S_ISDIR(metadata.st_mode):
147
+ update_digest_field(digest, b"untracked-kind", b"directory")
148
+ update_digest_field(
149
+ digest,
150
+ b"untracked-content",
151
+ directory_content_digest(path.resolve()).encode(),
152
+ )
146
153
  elif stat.S_ISREG(metadata.st_mode):
147
154
  content_digest = hashlib.sha256()
148
155
  content_size = 0
@@ -419,7 +426,13 @@ def copy_git_worktree_files(source: Path, destination: Path, excluded: tuple[Pat
419
426
  destination_path.symlink_to(os.readlink(source_path))
420
427
  elif stat.S_ISREG(metadata.st_mode):
421
428
  shutil.copy2(source_path, destination_path, follow_symlinks=False)
422
- elif not stat.S_ISDIR(metadata.st_mode):
429
+ elif stat.S_ISDIR(metadata.st_mode):
430
+ nested_git_dir = git_output(source_path, "rev-parse", "--absolute-git-dir")
431
+ if nested_git_dir is None:
432
+ raise SystemExit(f"Could not inspect nested Git working tree: {relative}")
433
+ copy_git_worktree_files(source_path, destination_path, excluded)
434
+ (destination_path / ".git").write_text(f"gitdir: {nested_git_dir}\n")
435
+ else:
423
436
  raise SystemExit(f"Unsupported Git working-tree file type: {relative}")
424
437
  copied_target = destination if pathspec == "." else destination / pathspec
425
438
  copied_target.mkdir(parents=True, exist_ok=True)