@openai/codex-security 0.1.16 → 0.1.17

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 (107) hide show
  1. package/README.md +184 -4
  2. package/_bundled_plugin/.app.json +1 -1
  3. package/_bundled_plugin/.mcp.json +9 -3
  4. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  6. package/_bundled_plugin/references/config-preflight.md +1 -1
  7. package/_bundled_plugin/references/sarif-adapter.md +2 -0
  8. package/_bundled_plugin/scripts/deep_scan_workbench.py +34 -6
  9. package/_bundled_plugin/scripts/finalize_scan_contract.py +54 -26
  10. package/_bundled_plugin/scripts/generate_in_scope_files.py +20 -0
  11. package/_bundled_plugin/scripts/generate_rank_input.py +23 -7
  12. package/_bundled_plugin/scripts/launch_codex_security_mcp +32 -0
  13. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +27 -0
  14. package/_bundled_plugin/scripts/workbench_cli.py +22 -15
  15. package/_bundled_plugin/scripts/workbench_db.py +35 -35
  16. package/_bundled_plugin/scripts/workbench_progress.py +6 -3
  17. package/_bundled_plugin/scripts/workbench_scan_history.py +17 -2
  18. package/_bundled_plugin/scripts/workbench_target.py +36 -5
  19. package/_bundled_plugin/scripts/workbench_validation.py +9 -0
  20. package/_bundled_plugin/skills/fix-finding/SKILL.md +17 -1
  21. package/dist/api.d.ts +16 -1
  22. package/dist/api.d.ts.map +1 -1
  23. package/dist/api.js +180 -11
  24. package/dist/api.js.map +1 -1
  25. package/dist/cli.d.ts +5 -3
  26. package/dist/cli.d.ts.map +1 -1
  27. package/dist/cli.js +335 -43
  28. package/dist/cli.js.map +1 -1
  29. package/dist/component-plan.d.ts +15 -0
  30. package/dist/component-plan.d.ts.map +1 -0
  31. package/dist/component-plan.js +145 -0
  32. package/dist/component-plan.js.map +1 -0
  33. package/dist/component-scan.d.ts +83 -0
  34. package/dist/component-scan.d.ts.map +1 -0
  35. package/dist/component-scan.js +279 -0
  36. package/dist/component-scan.js.map +1 -0
  37. package/dist/contract.d.ts +8 -2
  38. package/dist/contract.d.ts.map +1 -1
  39. package/dist/contract.js +27 -8
  40. package/dist/contract.js.map +1 -1
  41. package/dist/cost-model.d.ts +20 -0
  42. package/dist/cost-model.d.ts.map +1 -0
  43. package/dist/cost-model.js +86 -0
  44. package/dist/cost-model.js.map +1 -0
  45. package/dist/cost.d.ts +2 -11
  46. package/dist/cost.d.ts.map +1 -1
  47. package/dist/cost.js +15 -98
  48. package/dist/cost.js.map +1 -1
  49. package/dist/custom-validation-prompt.d.ts +4 -0
  50. package/dist/custom-validation-prompt.d.ts.map +1 -0
  51. package/dist/custom-validation-prompt.js +94 -0
  52. package/dist/custom-validation-prompt.js.map +1 -0
  53. package/dist/custom-validation.d.ts +45 -0
  54. package/dist/custom-validation.d.ts.map +1 -0
  55. package/dist/custom-validation.js +292 -0
  56. package/dist/custom-validation.js.map +1 -0
  57. package/dist/errors.d.ts +1 -1
  58. package/dist/errors.d.ts.map +1 -1
  59. package/dist/errors.js +1 -1
  60. package/dist/errors.js.map +1 -1
  61. package/dist/index.d.ts +6 -1
  62. package/dist/index.d.ts.map +1 -1
  63. package/dist/index.js +2 -0
  64. package/dist/index.js.map +1 -1
  65. package/dist/multiscan.d.ts +1 -0
  66. package/dist/multiscan.d.ts.map +1 -1
  67. package/dist/multiscan.js +53 -5
  68. package/dist/multiscan.js.map +1 -1
  69. package/dist/patch-tui.js +1 -1
  70. package/dist/patch-tui.js.map +1 -1
  71. package/dist/publication.d.ts.map +1 -1
  72. package/dist/publication.js +3 -4
  73. package/dist/publication.js.map +1 -1
  74. package/dist/runtime.d.ts +4 -2
  75. package/dist/runtime.d.ts.map +1 -1
  76. package/dist/runtime.js +109 -38
  77. package/dist/runtime.js.map +1 -1
  78. package/dist/scan-comparison.d.ts +12 -5
  79. package/dist/scan-comparison.d.ts.map +1 -1
  80. package/dist/scan-comparison.js +72 -28
  81. package/dist/scan-comparison.js.map +1 -1
  82. package/dist/scan-dashboard.d.ts +9 -2
  83. package/dist/scan-dashboard.d.ts.map +1 -1
  84. package/dist/scan-dashboard.js +198 -3
  85. package/dist/scan-dashboard.js.map +1 -1
  86. package/dist/scan-logs.d.ts.map +1 -1
  87. package/dist/scan-logs.js +5 -21
  88. package/dist/scan-logs.js.map +1 -1
  89. package/dist/scan-sessions.d.ts +4 -0
  90. package/dist/scan-sessions.d.ts.map +1 -0
  91. package/dist/scan-sessions.js +35 -0
  92. package/dist/scan-sessions.js.map +1 -0
  93. package/dist/targets.d.ts.map +1 -1
  94. package/dist/targets.js +16 -1
  95. package/dist/targets.js.map +1 -1
  96. package/dist/version.d.ts.map +1 -1
  97. package/dist/version.js +2 -20
  98. package/dist/version.js.map +1 -1
  99. package/dist/windows-path.d.ts +3 -0
  100. package/dist/windows-path.d.ts.map +1 -0
  101. package/dist/windows-path.js +16 -0
  102. package/dist/windows-path.js.map +1 -0
  103. package/dist/worker-progress.d.ts +1 -0
  104. package/dist/worker-progress.d.ts.map +1 -1
  105. package/dist/worker-progress.js +12 -0
  106. package/dist/worker-progress.js.map +1 -1
  107. package/package.json +8 -2
package/README.md CHANGED
@@ -54,6 +54,11 @@ Use `security.preflight()` to validate local inputs, `onWorkerStatus` and
54
54
  `onReconnect` to observe long-running scans, and an `AbortSignal` to cancel a
55
55
  scan.
56
56
 
57
+ For separate standard scans under one project, the SDK also exports
58
+ `runComponentScans({ repository, outputDir, components })`. Each component has
59
+ a `name` and `paths` array. Use `auto: true` instead of `components` for
60
+ model-assisted planning, and `planOnly: true` to save the plan without scanning.
61
+
57
62
  Successful results include open repository findings in `repositoryFindings`,
58
63
  when available; `findings` remains the current scan. Matching earlier findings
59
64
  can make one additional model call, including with a scan cost limit.
@@ -62,6 +67,44 @@ Results can contain source excerpts, vulnerability details, and reproduction
62
67
  steps. Keep result directories and saved reports outside the repository and
63
68
  limit access to authorized reviewers.
64
69
 
70
+ ### Validate an existing finding
71
+
72
+ Use `security.validate()` to assess one finding without running a repository
73
+ scan or invoking the Codex Security CLI:
74
+
75
+ ```ts
76
+ const security = new CodexSecurity();
77
+ try {
78
+ const result = await security.validate({
79
+ repositoryPath: "/path/to/repository",
80
+ finding: {
81
+ title: "Possible SQL injection",
82
+ location: "src/query.ts:42",
83
+ },
84
+ outputDir: "/path/outside/repository/validation",
85
+ });
86
+ console.log(result.disposition);
87
+ console.log(result.report);
88
+ } finally {
89
+ await security.close();
90
+ }
91
+ ```
92
+
93
+ `finding` accepts literal text or a JSON-serializable object, never a file
94
+ path. Read files explicitly. Validation uses the CLI's validation skill and
95
+ the client's settings and authentication. It leaves repository files unchanged
96
+ and does not add a scan to scan history.
97
+
98
+ The result contains `disposition` (`reportable`, `suppressed`, `not_applicable`,
99
+ or `deferred`), a Markdown `report`, `threadId`, and `outputDir` for evidence.
100
+ The report explains root cause, exploitability, evidence, and proof gaps.
101
+ `reportable` can rely on static analysis; `deferred` means insufficient evidence.
102
+
103
+ `outputDir` must be empty and outside the enclosing Git worktree. It defaults
104
+ to the Codex Security state directory's `validations/` folder. Pass `auth` to
105
+ select authentication or `signal` to cancel. Failed, incomplete, or malformed
106
+ responses reject the promise.
107
+
65
108
  ### SDK configuration and scan options
66
109
 
67
110
  Pass runtime configuration to the `CodexSecurity` constructor:
@@ -211,6 +254,8 @@ npx @openai/codex-security scan /path/to/repository --patch --patch-severity hig
211
254
  npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra
212
255
  npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra --effort high
213
256
  npx @openai/codex-security scan /path/to/repository --path src --path tests
257
+ npx @openai/codex-security scan-components /path/to/repository --component apps/api --component apps/web --output-dir /path/outside/repository/results
258
+ npx @openai/codex-security scan-components /path/to/repository --auto --output-dir /path/outside/repository/results
214
259
  npx @openai/codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
215
260
  npx @openai/codex-security scan /path/to/repository --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
216
261
  npx @openai/codex-security scan /path/to/repository --diff origin/main --json
@@ -290,6 +335,75 @@ Repeat `--knowledge-base PATH` for multiple files or directories; `bulk-scan`
290
335
  shares them with every repository. Directories are searched recursively for
291
336
  Markdown, text, PDF, and Word (`.docx`) files.
292
337
 
338
+ ### Scan project components
339
+
340
+ `scan --path` runs one scan across the selected paths. Use `scan-components`
341
+ to run a separate standard scan for each component of one local project:
342
+
343
+ ```bash
344
+ npx @openai/codex-security scan-components /path/to/project \
345
+ --component apps/api --component apps/web --component packages/shared \
346
+ --workers 4 --output-dir /path/outside/project/results
347
+ ```
348
+
349
+ Use `--auth chatgpt` or `--auth api-key` to select credentials for planning,
350
+ component scans, and matching. The default is `--auth auto`, as with `scan`.
351
+ The SDK accepts the same choice through `scanOptions.auth`.
352
+
353
+ Use `--auto` instead of `--component` to let Codex propose the split. To review
354
+ or edit it first, save a plan, then run that plan into a new output directory:
355
+
356
+ ```bash
357
+ npx @openai/codex-security scan-components /path/to/project \
358
+ --auto --plan-only --output-dir /path/outside/project/plan
359
+ npx @openai/codex-security scan-components /path/to/project \
360
+ --components-file /path/outside/project/plan/components.json \
361
+ --output-dir /path/outside/project/results
362
+ ```
363
+
364
+ A component can contain several repository-relative paths:
365
+
366
+ ```json
367
+ {
368
+ "components": [
369
+ { "name": "API", "paths": ["apps/api", "packages/auth"] },
370
+ { "name": "Web", "paths": ["apps/web"] }
371
+ ]
372
+ }
373
+ ```
374
+
375
+ Automatic planning uses a local file inventory. In Git repositories it follows
376
+ Git's ignore rules. Each automatic path must cover at least one inventoried file.
377
+ Explicit `--component` and `--components-file` selections keep their existing behavior.
378
+ Inventoried files omitted by the model are added to an
379
+ `Other files` component. No source files are changed during planning.
380
+
381
+ In an interactive terminal, one dashboard shows all components and their scan
382
+ progress. Use the arrow keys to select a component, Enter to view its activity,
383
+ and Esc to return. Other scans continue while you inspect one. Finding counts
384
+ are preliminary until cross-component matching finishes. Use `--headless` for
385
+ plain status lines; CI and redirected output use those automatically.
386
+ Failed or incomplete components are also saved in `retry-components.json`.
387
+ Pass that file to `--components-file` with a new output directory to retry them.
388
+
389
+ Each component keeps its normal scan artifacts under `component-N/`.
390
+ The combined `findings.json` uses the same root-cause matcher as `scans match`.
391
+ It merges high-confidence matches even when their titles, locations, or
392
+ fingerprints differ. Each group keeps its highest-severity finding and all
393
+ original scan and occurrence IDs. Match reasons and uncertain pairs are saved;
394
+ uncertain findings stay separate. `summary.json` records scan coverage and
395
+ whether matching finished. `report.md` links to the component reports.
396
+ These combined files are a project summary, not a new sealed scan. Use the
397
+ individual scan folders with `export` and `publish`.
398
+
399
+ The output directory must be empty and outside the project. Failed components
400
+ do not stop the others. The command saves the available results and exits with
401
+ code `2` if a component fails, coverage is incomplete, or cross-component
402
+ matching fails. `--max-cost` applies to each component scan, not planning,
403
+ cross-component matching, or the whole project. `--model` and `--effort` also
404
+ apply to matching. `--knowledge-base`,
405
+ `--scan-prompt-file`, and `--post-scan-prompt-file` work as they do for bulk scans.
406
+
293
407
  ### Configure deep scans
294
408
 
295
409
  For `scan --mode deep`, `--workers` limits concurrent discovery workers,
@@ -352,11 +466,11 @@ ask whether to open a color-coded finding browser with complete finding details
352
466
  and a separate patch-instructions panel. Use the arrow keys to
353
467
  browse, `Tab` to inspect details, `Space` to select individual findings, `i` to
354
468
  edit instructions for the focused finding, `1`–`4` to select by severity, and
355
- `r` to optionally create a GitHub pull request after patching. Press `Enter` to
356
- patch or `q` to keep the checkout unchanged. Each selected finding runs in its
357
- own saved Codex desktop task. Add `--create-pr` to `scan --patch` or a
469
+ `r` to optionally create a draft GitHub pull request after patching. Press
470
+ `Enter` to patch or `q` to keep the checkout unchanged. Each selected finding
471
+ runs in its own saved Codex desktop task. Add `--create-pr` to `scan --patch` or a
358
472
  saved-finding `patch` command to commit only verified patch files and open a
359
- pull request with `gh`. If the push or pull request fails, run the printed
473
+ draft pull request with `gh`. If the push or pull request fails, run the printed
360
474
  `patch --resume-pr BRANCH` command from the same repository. It uses the saved
361
475
  commit without running Codex again and refuses to publish if the branch changed.
362
476
  JSON scan results include `patchSeverity`. Scan and
@@ -586,6 +700,72 @@ and scans stopped at their configured cost limit do not start another turn.
586
700
  invocation and defaults to `1`. Results remain under `--output-dir`; rerun the
587
701
  same command to resume.
588
702
 
703
+ ### Custom validation
704
+
705
+ Use a prompt file to replace the final validation step in a standard or diff
706
+ scan. The ordinary source review still runs. The supplied text goes directly
707
+ into a separate validation turn and is not sent to discovery workers.
708
+ The SDK adapts the bundled discovery workflow without changing the plugin.
709
+ An incompatible plugin workflow stops the scan instead of using default validation.
710
+
711
+ ```bash
712
+ npx @openai/codex-security scan . --validation-prompt-file validation.md
713
+ ```
714
+
715
+ The SDK accepts the same text as `validationPrompt`:
716
+
717
+ ```ts
718
+ const result = await security.run(repository, {
719
+ validationPrompt:
720
+ "Run scripts/validate.sh, test each candidate through the local API, and stop the test environment when finished.",
721
+ });
722
+ ```
723
+
724
+ Describe setup, allowed test targets, expected evidence, and cleanup in the
725
+ prompt. Refer to credentials through environment variables; do not put secrets
726
+ in the prompt or validation output. There are no separate setup or teardown
727
+ hooks. Deep scans reject this option. Empty candidate sets skip the custom turn.
728
+
729
+ The SDK supplies the candidate IDs and requires a `CustomValidationResult`:
730
+
731
+ ```json
732
+ {
733
+ "status": "complete",
734
+ "reason": null,
735
+ "validations": [
736
+ {
737
+ "candidateId": "candidate-1",
738
+ "validation": {
739
+ "disposition": "reportable",
740
+ "method": "integration test",
741
+ "confidence": "high",
742
+ "confidence_rationale": "The test reproduced the reported behavior.",
743
+ "rubric": "Check the protected operation.",
744
+ "evidence": ["The unauthorized request succeeded."],
745
+ "counterevidence_or_proof_gap": "",
746
+ "remaining_uncertainty": "",
747
+ "artifact_paths": []
748
+ },
749
+ "severity": null,
750
+ "impact": null
751
+ }
752
+ ]
753
+ }
754
+ ```
755
+
756
+ Each candidate needs exactly one result. The disposition is `reportable`,
757
+ `suppressed`, `not_applicable`, or `deferred`. Optional assessment changes use
758
+ `{ "level": "medium", "rationale": "..." }` in `severity` or `impact`; use
759
+ `null` to retain the original assessment. Finding identity and source locations
760
+ do not change. Deferred candidates make coverage partial. Suppressed and
761
+ deferred candidates remain in the saved validation artifacts.
762
+
763
+ The scan directory contains `artifacts/custom-validation/candidates.json` and
764
+ `results.json`. Setup failure, incomplete output, or invalid output leaves the
765
+ scan incomplete. There is no automatic fallback to default validation. When
766
+ rerunning a saved custom-validation scan, supply
767
+ `scans rerun SCAN_ID --validation-prompt-file validation.md` again.
768
+
589
769
  ### Publish completed scans to Linear
590
770
 
591
771
  Publish every finding from a completed standard, deep, or scoped scan to one
@@ -3,7 +3,7 @@
3
3
  "codex-security-access": {
4
4
  "id": "connector_openai_codex_security_access",
5
5
  "category": "Security",
6
- "required": true
6
+ "required": false
7
7
  },
8
8
  "linear": {
9
9
  "id": "asdk_app_69a089a326dc8191b32a3f2553f5be2c",
@@ -1,14 +1,18 @@
1
1
  {
2
2
  "mcpServers": {
3
3
  "codex-security": {
4
- "command": "node",
5
- "args": ["./mcp/server.mjs", "--stdio"],
4
+ "command": "./scripts/launch_codex_security_mcp",
5
+ "args": ["--stdio"],
6
6
  "cwd": ".",
7
7
  "env_vars": [
8
8
  "CODEX_HOME",
9
9
  "CODEX_SQLITE_HOME",
10
10
  "CODEX_API_KEY",
11
+ "CODEX_BROWSER_USE_NODE_PATH",
11
12
  "CODEX_CLI_PATH",
13
+ "CODEX_ELECTRON_RESOURCES_PATH",
14
+ "CODEX_MANAGED_PACKAGE_ROOT",
15
+ "CODEX_MCP_NODE_PATH",
12
16
  "OPENROUTER_API_KEY",
13
17
  "FIREWORKS_API_KEY",
14
18
  "AWS_BEARER_TOKEN_BEDROCK",
@@ -28,6 +32,7 @@
28
32
  "AWS_CONTAINER_AUTHORIZATION_TOKEN",
29
33
  "AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE",
30
34
  "PYTHON",
35
+ "PYTHONUTF8",
31
36
  "CODEX_SECURITY_KNOWLEDGE_BASE",
32
37
  "CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH",
33
38
  "CODEX_SECURITY_SCAN_ROOT",
@@ -39,7 +44,8 @@
39
44
  "NO_PROXY",
40
45
  "SSL_CERT_FILE",
41
46
  "REQUESTS_CA_BUNDLE",
42
- "NODE_EXTRA_CA_CERTS"
47
+ "NODE_EXTRA_CA_CERTS",
48
+ "XDG_CACHE_HOME"
43
49
  ],
44
50
  "tool_timeout_sec": 349200
45
51
  }
@@ -60,7 +60,7 @@ When the profile includes remediation patches, present the concrete config delta
60
60
 
61
61
  Some remediation patches have `kind = "host_setting"`. Present those as host-level setup guidance, not as edits to persistent Codex config.
62
62
 
63
- Deep Security Scan uses MCP-owned SDK sessions rather than the parent thread's worker pool. Its preflight does not require a particular parent delegation runtime, ownership, capacity, or depth. Discovery workers inherit the scan's model and run under the verified read-only worker sandbox.
63
+ Deep Security Scan uses MCP-owned SDK sessions rather than the parent thread's worker pool. Its preflight does not require a particular parent delegation runtime, ownership, capacity, or depth. Discovery workers inherit the scan's model and use the reserved `codex_security_deep_scan_worker` permission profile with the parent's supported filesystem denials. The selected Codex executable must support permission-profile configuration and allowance checks. If that command fails to start or exits early, report its path and the tool's diagnostic; do not infer that its version is unsupported. If the tool identifies a missing API, ask the user to update the Codex installation at the reported path: the desktop app for an app-bundled executable, or the selected CLI otherwise. If Codex policy rejects the profile, report the tool's administrator guidance. Do not remove deny rules or select a broader sandbox to work around the error.
64
64
 
65
65
  Do not warn merely because a user's value differs from the profile's suggested patch. Warn or block only when the evaluated capability requirement is unmet.
66
66
 
@@ -20,6 +20,8 @@ The adapter:
20
20
 
21
21
  Lifecycle, rich validation evidence, attack-path context, and coverage are lossy or omitted in SARIF. Preserve them in semantic JSON.
22
22
 
23
+ SARIF `executionSuccessful` is true only for complete coverage. Incomplete scans retain findings and warnings. Integrations must read the coverage file referenced by `scan.coverageRef`; manifest status `completed` alone does not mean success.
24
+
23
25
  Automatic SARIF export during finalization is best-effort so projection errors cannot invalidate a canonical seal. Use the strict adapter entry point when a consumer requires SARIF and should surface export errors.
24
26
 
25
27
  References:
@@ -5,6 +5,7 @@ from __future__ import annotations
5
5
  import argparse
6
6
  import json
7
7
  import os
8
+ import shutil
8
9
  import sqlite3
9
10
  import sys
10
11
  import tempfile
@@ -25,7 +26,7 @@ from workbench_target import (
25
26
  git_revision,
26
27
  worktree_content_digest,
27
28
  )
28
- from workbench_validation import optional_text, require_uuid, user_text
29
+ from workbench_validation import optional_text, require_uuid, user_context_argument
29
30
 
30
31
  DEEP_SCAN_WORKER_KINDS = ("setup", "discovery", "dedup")
31
32
  DEEP_SCAN_WORKER_STATUSES = ("queued", "running", "succeeded", "failed", "canceled")
@@ -47,7 +48,9 @@ def register_subcommands(subparsers: Any, positive_int: Callable[[str], int]) ->
47
48
  begin_target.add_argument("--scan-id")
48
49
  begin_target.add_argument("--target-path")
49
50
  begin_deep_scan.add_argument("--scope", default=".")
50
- begin_deep_scan.add_argument("--user-context")
51
+ begin_user_context = begin_deep_scan.add_mutually_exclusive_group()
52
+ begin_user_context.add_argument("--user-context")
53
+ begin_user_context.add_argument("--user-context-stdin", action="store_true")
51
54
  begin_deep_scan.add_argument("--scan-root")
52
55
  begin_deep_scan.add_argument("--claim-token")
53
56
  begin_deep_scan.add_argument("--model")
@@ -328,6 +331,31 @@ def finish_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:
328
331
  backup.unlink(missing_ok=True)
329
332
 
330
333
 
334
+ def create_publication_copy(source: str | Path, destination: str | Path) -> None:
335
+ try:
336
+ os.link(source, destination)
337
+ except OSError:
338
+ shutil.copy2(source, destination)
339
+
340
+
341
+ def publication_matches_snapshot(publication: Path, snapshot: Path) -> bool:
342
+ try:
343
+ if publication.samefile(snapshot):
344
+ return True
345
+ if publication.stat().st_size != snapshot.stat().st_size:
346
+ return False
347
+ with publication.open("rb") as published, snapshot.open("rb") as source:
348
+ while True:
349
+ published_chunk = published.read(1024 * 1024)
350
+ source_chunk = source.read(1024 * 1024)
351
+ if published_chunk != source_chunk:
352
+ return False
353
+ if not published_chunk:
354
+ return True
355
+ except OSError:
356
+ return False
357
+
358
+
331
359
  def canonical_discovery_artifacts(scan: sqlite3.Row) -> dict[str, str]:
332
360
  discovery_dir = Path(scan["scan_dir"]) / "artifacts" / "02_discovery"
333
361
  artifacts = {
@@ -769,7 +797,7 @@ def begin_deep_scan_for_target(
769
797
  if target_root == target or target in target_root.parents:
770
798
  raise SystemExit("The scan artifact directory must be outside the selected target.")
771
799
  target_root.mkdir(parents=True, exist_ok=True)
772
- user_context = user_text(args.user_context)
800
+ user_context = user_context_argument(args)
773
801
  model = optional_text(args.model, maximum=200)
774
802
  reasoning_effort = optional_text(args.reasoning_effort, maximum=32)
775
803
  workspace_id = str(uuid.uuid4())
@@ -858,7 +886,7 @@ def begin_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) ->
858
886
  if thread_id is None:
859
887
  raise SystemExit("thread-id is required.")
860
888
  if args.scan_id:
861
- if args.user_context is not None or args.scope != ".":
889
+ if args.user_context is not None or args.user_context_stdin or args.scope != ".":
862
890
  raise SystemExit("scan-id cannot be combined with target setup fields.")
863
891
  return begin_deep_scan_for_scan(connection, args.scan_id, thread_id, args)
864
892
  if args.claim_token is not None:
@@ -1075,7 +1103,7 @@ def recover_candidate_ledger_publication(connection: sqlite3.Connection, scan_id
1075
1103
  snapshot = Path(reducer["artifact_dir"]) / "canonical" / ledger.name
1076
1104
  if not snapshot.exists():
1077
1105
  continue
1078
- published = ledger.exists() and ledger.samefile(snapshot)
1106
+ published = publication_matches_snapshot(ledger, snapshot)
1079
1107
  interrupted = reducer["status"] != "succeeded"
1080
1108
  if not published and not (interrupted and backups and not ledger.exists()):
1081
1109
  continue
@@ -1577,7 +1605,7 @@ def commit_deep_scan_dedup_locked(
1577
1605
  publication_copy = canonical_path.with_name(
1578
1606
  f".{canonical_path.name}.{uuid.uuid4()}.publish"
1579
1607
  )
1580
- os.link(candidate_ledger_path, publication_copy)
1608
+ create_publication_copy(candidate_ledger_path, publication_copy)
1581
1609
  promotion = promote_staged_file(
1582
1610
  str(publication_copy),
1583
1611
  canonical_candidate_ledger_path,
@@ -73,6 +73,10 @@ EXPORT_PATHS = {
73
73
  "json": "exports/findings.json",
74
74
  "sarif": "exports/results.sarif",
75
75
  }
76
+ WINDOWS_UNSAFE_PATH_COMPONENT_RE = re.compile(
77
+ r'[<>:"|?*\x00-\x1f]|[ .]$|^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³])(?:\..*)?$',
78
+ re.IGNORECASE,
79
+ )
76
80
 
77
81
 
78
82
  class ContractError(ValueError):
@@ -225,10 +229,12 @@ def _require_safe_relative_path(value: str, context: str, *, allow_dot: bool = F
225
229
  path = PurePosixPath(value)
226
230
  normalized = path.as_posix()
227
231
  if (
228
- not value
232
+ not value.strip()
229
233
  or (normalized == "." and not allow_dot)
234
+ or (len(value) >= 2 and value[0].isalpha() and value[1] == ":")
230
235
  or "\\" in value
231
236
  or "\0" in value
237
+ or any(ord(character) < 32 for character in value)
232
238
  or path.is_absolute()
233
239
  or ".." in path.parts
234
240
  ):
@@ -236,6 +242,21 @@ def _require_safe_relative_path(value: str, context: str, *, allow_dot: bool = F
236
242
  return normalized
237
243
 
238
244
 
245
+ def _require_portable_relative_path(
246
+ value: str, context: str, *, allow_dot: bool = False
247
+ ) -> str:
248
+ normalized = _require_safe_relative_path(value, context, allow_dot=allow_dot)
249
+ if any(_windows_unsafe_path_component(part) for part in value.split("/")):
250
+ raise ContractError(f"{context}: expected a safe scan-relative POSIX path")
251
+ return normalized
252
+
253
+
254
+ def _windows_unsafe_path_component(value: str) -> bool:
255
+ if not value or value == ".":
256
+ return False
257
+ return WINDOWS_UNSAFE_PATH_COMPONENT_RE.search(value) is not None
258
+
259
+
239
260
  def _require_scan_directory(scan_dir: Path) -> Path:
240
261
  scan_dir = scan_dir.absolute()
241
262
  try:
@@ -347,7 +368,7 @@ def _open_scan_local_directory(root_fd: int, parts: tuple[str, ...], *, create:
347
368
 
348
369
  def open_scan_local_file_descriptor(scan_dir: Path, relative_path: str, context: str) -> int:
349
370
  scan_dir = _require_scan_directory(scan_dir)
350
- relative_path = _require_safe_relative_path(relative_path, context)
371
+ relative_path = _require_portable_relative_path(relative_path, context)
351
372
  if not _descriptor_relative_reads_available():
352
373
  if not _is_windows():
353
374
  raise ContractError("scan-local input requires descriptor-relative file operations")
@@ -478,7 +499,7 @@ def write_scan_local_bytes(
478
499
  if relative_path in {"", ".", ".."} or "/" in relative_path or "\0" in relative_path:
479
500
  raise ContractError("external output path: expected a safe file name")
480
501
  else:
481
- relative_path = _require_safe_relative_path(relative_path, "scan-local output path")
502
+ relative_path = _require_portable_relative_path(relative_path, "scan-local output path")
482
503
  path = scan_dir / relative_path
483
504
  if not _descriptor_relative_writes_available():
484
505
  if not _is_windows():
@@ -529,7 +550,7 @@ def write_scan_local_bytes(
529
550
 
530
551
  def _remove_scan_local_file_if_exists(scan_dir: Path, relative_path: str) -> None:
531
552
  scan_dir = _require_scan_directory(scan_dir)
532
- relative_path = _require_safe_relative_path(relative_path, "scan-local cleanup path")
553
+ relative_path = _require_portable_relative_path(relative_path, "scan-local cleanup path")
533
554
  if not _descriptor_relative_writes_available():
534
555
  if not _is_windows():
535
556
  raise ContractError("scan-local cleanup requires descriptor-relative file operations")
@@ -936,7 +957,7 @@ def _recover_unsealed_coverage(
936
957
  try:
937
958
  if not isinstance(ref, str):
938
959
  raise ContractError(f"{ref_context}: expected a string")
939
- normalized_ref = _require_safe_relative_path(ref, ref_context)
960
+ normalized_ref = _require_portable_relative_path(ref, ref_context)
940
961
  if not normalized_ref.startswith("artifacts/"):
941
962
  raise ContractError(
942
963
  f"{ref_context}: expected a file under artifacts/"
@@ -1322,7 +1343,9 @@ def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_
1322
1343
  for ref_index, ref in enumerate(receipt_refs):
1323
1344
  if not isinstance(ref, str):
1324
1345
  raise ContractError(f"{context}.receiptRefs[{ref_index}]: expected a string")
1325
- normalized_ref = _require_safe_relative_path(ref, f"{context}.receiptRefs[{ref_index}]")
1346
+ normalized_ref = _require_portable_relative_path(
1347
+ ref, f"{context}.receiptRefs[{ref_index}]"
1348
+ )
1326
1349
  if not normalized_ref.startswith("artifacts/"):
1327
1350
  raise ContractError(
1328
1351
  f"{context}.receiptRefs[{ref_index}]: expected a file under artifacts/"
@@ -1367,16 +1390,19 @@ def _validate_manifest(manifest: dict[str, Any]) -> None:
1367
1390
  if not artifacts:
1368
1391
  raise ContractError("manifest.scan.artifacts: expected generated artifact records")
1369
1392
  artifact_paths: set[str] = set()
1393
+ artifact_collision_keys: set[str] = set()
1370
1394
  for index, artifact in enumerate(artifacts):
1371
1395
  context = f"manifest.scan.artifacts[{index}]"
1372
1396
  if not isinstance(artifact, dict):
1373
1397
  raise ContractError(f"{context}: expected an object")
1374
- path = _require_safe_relative_path(
1398
+ path = _require_portable_relative_path(
1375
1399
  _require_str(artifact, "path", context), f"{context}.path"
1376
1400
  )
1377
- if path in artifact_paths:
1401
+ collision_key = path.lower()
1402
+ if collision_key in artifact_collision_keys:
1378
1403
  raise ContractError(f"{context}.path: duplicate artifact path")
1379
1404
  artifact_paths.add(path)
1405
+ artifact_collision_keys.add(collision_key)
1380
1406
  _require_str(artifact, "sha256", context)
1381
1407
  _require_str(artifact, "mediaType", context)
1382
1408
  for required_path in ("findings.json", "coverage.json"):
@@ -1593,6 +1619,7 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1593
1619
  and evidence["id"]
1594
1620
  }
1595
1621
  for section_name, list_fields in (
1622
+ ("rootCause", ("evidenceRefs", "evidence_refs")),
1596
1623
  ("root_cause", ("evidenceRefs", "evidence_refs")),
1597
1624
  (
1598
1625
  "validation",
@@ -2146,7 +2173,7 @@ def _validate_sarif(sarif: dict[str, Any]) -> None:
2146
2173
  def _artifact_record(
2147
2174
  scan_dir: Path, relative_path: str, media_type: str, contents: bytes | None = None
2148
2175
  ) -> dict[str, str]:
2149
- relative_path = _require_safe_relative_path(relative_path, "artifact path")
2176
+ relative_path = _require_portable_relative_path(relative_path, "artifact path")
2150
2177
  if contents is not None:
2151
2178
  _require_scan_local_file(scan_dir, relative_path, relative_path)
2152
2179
  return {
@@ -2167,7 +2194,7 @@ def _coverage_receipt_refs(coverage: dict[str, Any]) -> list[str]:
2167
2194
 
2168
2195
  def _validate_sealed_coverage_receipts(scan: dict[str, Any], coverage: dict[str, Any]) -> None:
2169
2196
  artifact_paths = {
2170
- _require_safe_relative_path(artifact["path"], "sealed artifact path")
2197
+ _require_portable_relative_path(artifact["path"], "sealed artifact path")
2171
2198
  for artifact in scan["artifacts"]
2172
2199
  }
2173
2200
  for ref in _coverage_receipt_refs(coverage):
@@ -2190,16 +2217,19 @@ def _validate_existing_seal(
2190
2217
  if not isinstance(artifacts, list) or not artifacts:
2191
2218
  raise ContractError("manifest.scan.artifacts: sealed manifest requires artifact records")
2192
2219
  artifact_paths: set[str] = set()
2220
+ artifact_collision_keys: set[str] = set()
2193
2221
  for index, artifact in enumerate(artifacts):
2194
2222
  context = f"manifest.scan.artifacts[{index}]"
2195
2223
  if not isinstance(artifact, dict):
2196
2224
  raise ContractError(f"{context}: expected an object")
2197
- path = _require_safe_relative_path(
2225
+ path = _require_portable_relative_path(
2198
2226
  _require_str(artifact, "path", context), f"{context}.path"
2199
2227
  )
2200
- if path in artifact_paths:
2228
+ collision_key = path.lower()
2229
+ if collision_key in artifact_collision_keys:
2201
2230
  raise ContractError(f"{context}.path: duplicate artifact path")
2202
2231
  artifact_paths.add(path)
2232
+ artifact_collision_keys.add(collision_key)
2203
2233
  expected_sha256 = _require_str(artifact, "sha256", context)
2204
2234
  contents = (artifact_contents or {}).get(path)
2205
2235
  actual_sha256 = (
@@ -2260,19 +2290,17 @@ def build_sarif_projection(
2260
2290
  raise ContractError("source root: expected an existing directory")
2261
2291
  manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
2262
2292
  sarif = build_sarif(manifest, findings, source_root)
2263
- if coverage["completeness"] != "complete":
2264
- run = sarif["runs"][0]
2265
- run["properties"]["codexSecurityCoverageCompleteness"] = coverage["completeness"]
2266
- if coverage["deferred"]:
2267
- run["invocations"] = [
2268
- {
2269
- "executionSuccessful": True,
2270
- "toolExecutionNotifications": [
2271
- {"level": "warning", "message": {"text": item["reason"]}}
2272
- for item in coverage["deferred"]
2273
- ],
2274
- }
2275
- ]
2293
+ run = sarif["runs"][0]
2294
+ completeness = coverage["completeness"]
2295
+ run["invocations"] = [{"executionSuccessful": completeness == "complete"}]
2296
+ if completeness != "complete":
2297
+ run["properties"]["codexSecurityCoverageCompleteness"] = completeness
2298
+ reasons = [item["reason"] for item in coverage["deferred"]] or [
2299
+ f"Scan coverage is {completeness}; results may be incomplete."
2300
+ ]
2301
+ run["invocations"][0]["toolExecutionNotifications"] = [
2302
+ {"level": "warning", "message": {"text": reason}} for reason in reasons
2303
+ ]
2276
2304
  _validate_sarif(sarif)
2277
2305
  return sarif
2278
2306
 
@@ -2424,7 +2452,7 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
2424
2452
  scan = _require_dict(manifest, "scan", "manifest")
2425
2453
  artifacts = _require_list(scan, "artifacts", "manifest.scan")
2426
2454
  artifact_paths = [
2427
- _require_safe_relative_path(
2455
+ _require_portable_relative_path(
2428
2456
  _require_str(artifact, "path", f"manifest.scan.artifacts[{index}]"),
2429
2457
  f"manifest.scan.artifacts[{index}].path",
2430
2458
  )
@@ -15,6 +15,21 @@ class InventoryError(ValueError):
15
15
  """Raised when the repository, scope, or inventory cannot be used safely."""
16
16
 
17
17
 
18
+ def windows_stream_component(path: Path) -> str | None:
19
+ """Return the first NTFS alternate-data-stream component."""
20
+
21
+ if os.name != "nt":
22
+ return None
23
+ return next(
24
+ (
25
+ component
26
+ for component in path.parts
27
+ if component != path.anchor and ":" in component
28
+ ),
29
+ None,
30
+ )
31
+
32
+
18
33
  def resolve_repository(value: str) -> Path:
19
34
  """Resolve the repository once so every scope is bound to its real root."""
20
35
  try:
@@ -32,6 +47,11 @@ def resolve_scope(repository: Path, value: str) -> str:
32
47
  raise InventoryError("--scope: expected a non-empty file or directory")
33
48
 
34
49
  requested = Path(value).expanduser()
50
+ stream = windows_stream_component(requested)
51
+ if stream is not None:
52
+ raise InventoryError(
53
+ f"--scope: NTFS alternate data streams are not supported: {stream}"
54
+ )
35
55
  scope = requested if requested.is_absolute() else repository / requested
36
56
  try:
37
57
  resolved = scope.resolve(strict=True)