@openai/codex-security 0.1.16 → 0.1.18

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 (125) hide show
  1. package/README.md +228 -18
  2. package/_bundled_plugin/.app.json +1 -1
  3. package/_bundled_plugin/.mcp.json +10 -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/core-scan.md +1 -1
  8. package/_bundled_plugin/references/final-report.md +4 -2
  9. package/_bundled_plugin/references/sarif-adapter.md +2 -0
  10. package/_bundled_plugin/references/scan-artifacts.md +1 -1
  11. package/_bundled_plugin/references/scan-contract.md +18 -7
  12. package/_bundled_plugin/schemas/scan-manifest.schema.json +2 -2
  13. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +23 -0
  14. package/_bundled_plugin/scripts/deep_scan_workbench.py +122 -7
  15. package/_bundled_plugin/scripts/finalize_scan_contract.py +106 -38
  16. package/_bundled_plugin/scripts/generate_in_scope_files.py +20 -0
  17. package/_bundled_plugin/scripts/generate_rank_input.py +23 -7
  18. package/_bundled_plugin/scripts/launch_codex_security_mcp +32 -0
  19. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +27 -0
  20. package/_bundled_plugin/scripts/report_projection.py +19 -8
  21. package/_bundled_plugin/scripts/workbench_cli.py +35 -15
  22. package/_bundled_plugin/scripts/workbench_db.py +184 -202
  23. package/_bundled_plugin/scripts/workbench_finding_index.py +101 -0
  24. package/_bundled_plugin/scripts/workbench_progress.py +6 -3
  25. package/_bundled_plugin/scripts/workbench_remediation.py +19 -0
  26. package/_bundled_plugin/scripts/workbench_saved_results.py +1289 -0
  27. package/_bundled_plugin/scripts/workbench_scan_history.py +17 -2
  28. package/_bundled_plugin/scripts/workbench_schema.py +28 -0
  29. package/_bundled_plugin/scripts/workbench_target.py +36 -5
  30. package/_bundled_plugin/scripts/workbench_validation.py +9 -0
  31. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +4 -4
  32. package/_bundled_plugin/skills/fix-finding/SKILL.md +17 -1
  33. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +1 -1
  34. package/_bundled_plugin/skills/security-scan/SKILL.md +1 -1
  35. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +1 -1
  36. package/dist/api.d.ts +18 -1
  37. package/dist/api.d.ts.map +1 -1
  38. package/dist/api.js +234 -18
  39. package/dist/api.js.map +1 -1
  40. package/dist/cli.d.ts +5 -3
  41. package/dist/cli.d.ts.map +1 -1
  42. package/dist/cli.js +348 -43
  43. package/dist/cli.js.map +1 -1
  44. package/dist/component-plan.d.ts +15 -0
  45. package/dist/component-plan.d.ts.map +1 -0
  46. package/dist/component-plan.js +145 -0
  47. package/dist/component-plan.js.map +1 -0
  48. package/dist/component-scan.d.ts +83 -0
  49. package/dist/component-scan.d.ts.map +1 -0
  50. package/dist/component-scan.js +279 -0
  51. package/dist/component-scan.js.map +1 -0
  52. package/dist/contract.d.ts +8 -2
  53. package/dist/contract.d.ts.map +1 -1
  54. package/dist/contract.js +27 -8
  55. package/dist/contract.js.map +1 -1
  56. package/dist/cost-model.d.ts +20 -0
  57. package/dist/cost-model.d.ts.map +1 -0
  58. package/dist/cost-model.js +86 -0
  59. package/dist/cost-model.js.map +1 -0
  60. package/dist/cost.d.ts +2 -11
  61. package/dist/cost.d.ts.map +1 -1
  62. package/dist/cost.js +15 -98
  63. package/dist/cost.js.map +1 -1
  64. package/dist/custom-validation-prompt.d.ts +4 -0
  65. package/dist/custom-validation-prompt.d.ts.map +1 -0
  66. package/dist/custom-validation-prompt.js +94 -0
  67. package/dist/custom-validation-prompt.js.map +1 -0
  68. package/dist/custom-validation.d.ts +45 -0
  69. package/dist/custom-validation.d.ts.map +1 -0
  70. package/dist/custom-validation.js +292 -0
  71. package/dist/custom-validation.js.map +1 -0
  72. package/dist/errors.d.ts +1 -1
  73. package/dist/errors.d.ts.map +1 -1
  74. package/dist/errors.js +1 -1
  75. package/dist/errors.js.map +1 -1
  76. package/dist/index.d.ts +6 -1
  77. package/dist/index.d.ts.map +1 -1
  78. package/dist/index.js +2 -0
  79. package/dist/index.js.map +1 -1
  80. package/dist/models.d.ts +1 -1
  81. package/dist/models.d.ts.map +1 -1
  82. package/dist/models.js.map +1 -1
  83. package/dist/multiscan.d.ts +1 -0
  84. package/dist/multiscan.d.ts.map +1 -1
  85. package/dist/multiscan.js +53 -5
  86. package/dist/multiscan.js.map +1 -1
  87. package/dist/patch-tui.js +1 -1
  88. package/dist/patch-tui.js.map +1 -1
  89. package/dist/publication.d.ts.map +1 -1
  90. package/dist/publication.js +3 -4
  91. package/dist/publication.js.map +1 -1
  92. package/dist/runtime.d.ts +4 -2
  93. package/dist/runtime.d.ts.map +1 -1
  94. package/dist/runtime.js +109 -38
  95. package/dist/runtime.js.map +1 -1
  96. package/dist/scan-comparison.d.ts +12 -5
  97. package/dist/scan-comparison.d.ts.map +1 -1
  98. package/dist/scan-comparison.js +72 -28
  99. package/dist/scan-comparison.js.map +1 -1
  100. package/dist/scan-dashboard.d.ts +9 -2
  101. package/dist/scan-dashboard.d.ts.map +1 -1
  102. package/dist/scan-dashboard.js +198 -3
  103. package/dist/scan-dashboard.js.map +1 -1
  104. package/dist/scan-logs.d.ts.map +1 -1
  105. package/dist/scan-logs.js +5 -21
  106. package/dist/scan-logs.js.map +1 -1
  107. package/dist/scan-sessions.d.ts +4 -0
  108. package/dist/scan-sessions.d.ts.map +1 -0
  109. package/dist/scan-sessions.js +35 -0
  110. package/dist/scan-sessions.js.map +1 -0
  111. package/dist/targets.d.ts.map +1 -1
  112. package/dist/targets.js +16 -1
  113. package/dist/targets.js.map +1 -1
  114. package/dist/version.d.ts.map +1 -1
  115. package/dist/version.js +2 -20
  116. package/dist/version.js.map +1 -1
  117. package/dist/windows-path.d.ts +3 -0
  118. package/dist/windows-path.d.ts.map +1 -0
  119. package/dist/windows-path.js +16 -0
  120. package/dist/windows-path.js.map +1 -0
  121. package/dist/worker-progress.d.ts +1 -0
  122. package/dist/worker-progress.d.ts.map +1 -1
  123. package/dist/worker-progress.js +12 -0
  124. package/dist/worker-progress.js.map +1 -1
  125. package/package.json +8 -2
@@ -3,8 +3,10 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import argparse
6
+ import hashlib
6
7
  import json
7
8
  import os
9
+ import shutil
8
10
  import sqlite3
9
11
  import sys
10
12
  import tempfile
@@ -25,7 +27,7 @@ from workbench_target import (
25
27
  git_revision,
26
28
  worktree_content_digest,
27
29
  )
28
- from workbench_validation import optional_text, require_uuid, user_text
30
+ from workbench_validation import optional_text, require_uuid, user_context_argument
29
31
 
30
32
  DEEP_SCAN_WORKER_KINDS = ("setup", "discovery", "dedup")
31
33
  DEEP_SCAN_WORKER_STATUSES = ("queued", "running", "succeeded", "failed", "canceled")
@@ -38,6 +40,8 @@ DEEP_SCAN_TERMINAL_REASONS = ("saturated", "capped")
38
40
  DEEP_SCAN_WORKFLOW_VERSION = "deep-security-scan/v1"
39
41
  DEEP_SCAN_COORDINATOR_LEASE_SECONDS = 30
40
42
  DEEP_SCAN_LEGACY_COORDINATOR_GRACE_SECONDS = 120
43
+ DEEP_SCAN_MAX_ERROR_LENGTH = 2400
44
+ DEEP_SCAN_PUBLICATION_ERROR_SEPARATOR = "\nOriginal Deep Scan failure:\n"
41
45
 
42
46
 
43
47
  def register_subcommands(subparsers: Any, positive_int: Callable[[str], int]) -> None:
@@ -47,7 +51,9 @@ def register_subcommands(subparsers: Any, positive_int: Callable[[str], int]) ->
47
51
  begin_target.add_argument("--scan-id")
48
52
  begin_target.add_argument("--target-path")
49
53
  begin_deep_scan.add_argument("--scope", default=".")
50
- begin_deep_scan.add_argument("--user-context")
54
+ begin_user_context = begin_deep_scan.add_mutually_exclusive_group()
55
+ begin_user_context.add_argument("--user-context")
56
+ begin_user_context.add_argument("--user-context-stdin", action="store_true")
51
57
  begin_deep_scan.add_argument("--scan-root")
52
58
  begin_deep_scan.add_argument("--claim-token")
53
59
  begin_deep_scan.add_argument("--model")
@@ -117,6 +123,11 @@ def register_subcommands(subparsers: Any, positive_int: Callable[[str], int]) ->
117
123
  )
118
124
  fail_deep_scan.add_argument("--coordinator-generation", type=positive_int)
119
125
 
126
+ publication_failure = subparsers.add_parser("record-deep-scan-publication-failure")
127
+ publication_failure.add_argument("--scan-id", required=True)
128
+ publication_failure.add_argument("--message", required=True)
129
+ publication_failure.add_argument("--coordinator-generation", type=positive_int)
130
+
120
131
 
121
132
  def non_negative_int(value: str) -> int:
122
133
  parsed = int(value)
@@ -140,6 +151,7 @@ class DeepScanDependencies:
140
151
  safe_segment: Callable[[str], str]
141
152
  compact_timestamp: Callable[[], str]
142
153
  scan_completion_lock: Callable[[str], Any]
154
+ preserve_stopped_results: Callable[[sqlite3.Connection, str], None]
143
155
 
144
156
 
145
157
  _dependencies: DeepScanDependencies | None = None
@@ -160,6 +172,34 @@ def now() -> str:
160
172
  return dependencies().now()
161
173
 
162
174
 
175
+ def _bounded_error_text(message: str, maximum: int) -> str:
176
+ if len(message) <= maximum:
177
+ return message
178
+ digest = hashlib.sha256(message.encode()).hexdigest()
179
+ suffix = f"\n...[truncated; sha256:{digest}]"
180
+ if len(suffix) >= maximum:
181
+ return message[:maximum]
182
+ return f"{message[: maximum - len(suffix)]}{suffix}"
183
+
184
+
185
+ def deep_scan_error(run: sqlite3.Row) -> str | None:
186
+ original = run["error_message"]
187
+ publication = run["publication_error_message"]
188
+ if not isinstance(publication, str):
189
+ return original if isinstance(original, str) else None
190
+ if not isinstance(original, str):
191
+ return publication
192
+ available = DEEP_SCAN_MAX_ERROR_LENGTH - len(DEEP_SCAN_PUBLICATION_ERROR_SEPARATOR)
193
+ publication_budget = min(len(publication), available // 2)
194
+ original_budget = min(len(original), available - publication_budget)
195
+ publication_budget = min(len(publication), available - original_budget)
196
+ return (
197
+ _bounded_error_text(publication, publication_budget)
198
+ + DEEP_SCAN_PUBLICATION_ERROR_SEPARATOR
199
+ + _bounded_error_text(original, original_budget)
200
+ )
201
+
202
+
163
203
  def _parse_timestamp(value: str) -> datetime:
164
204
  if isinstance(value, str) and value.endswith(("Z", "z")):
165
205
  value = value[:-1] + "+00:00"
@@ -328,6 +368,31 @@ def finish_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:
328
368
  backup.unlink(missing_ok=True)
329
369
 
330
370
 
371
+ def create_publication_copy(source: str | Path, destination: str | Path) -> None:
372
+ try:
373
+ os.link(source, destination)
374
+ except OSError:
375
+ shutil.copy2(source, destination)
376
+
377
+
378
+ def publication_matches_snapshot(publication: Path, snapshot: Path) -> bool:
379
+ try:
380
+ if publication.samefile(snapshot):
381
+ return True
382
+ if publication.stat().st_size != snapshot.stat().st_size:
383
+ return False
384
+ with publication.open("rb") as published, snapshot.open("rb") as source:
385
+ while True:
386
+ published_chunk = published.read(1024 * 1024)
387
+ source_chunk = source.read(1024 * 1024)
388
+ if published_chunk != source_chunk:
389
+ return False
390
+ if not published_chunk:
391
+ return True
392
+ except OSError:
393
+ return False
394
+
395
+
331
396
  def canonical_discovery_artifacts(scan: sqlite3.Row) -> dict[str, str]:
332
397
  discovery_dir = Path(scan["scan_dir"]) / "artifacts" / "02_discovery"
333
398
  artifacts = {
@@ -411,7 +476,7 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, A
411
476
  "canonicalArtifacts": canonical_artifacts,
412
477
  "manifestPath": run["manifest_path"],
413
478
  "terminalReason": run["terminal_reason"],
414
- "error": run["error_message"],
479
+ "error": deep_scan_error(run),
415
480
  "createdAt": run["created_at"],
416
481
  "updatedAt": run["updated_at"],
417
482
  "completedAt": run["completed_at"],
@@ -769,7 +834,7 @@ def begin_deep_scan_for_target(
769
834
  if target_root == target or target in target_root.parents:
770
835
  raise SystemExit("The scan artifact directory must be outside the selected target.")
771
836
  target_root.mkdir(parents=True, exist_ok=True)
772
- user_context = user_text(args.user_context)
837
+ user_context = user_context_argument(args)
773
838
  model = optional_text(args.model, maximum=200)
774
839
  reasoning_effort = optional_text(args.reasoning_effort, maximum=32)
775
840
  workspace_id = str(uuid.uuid4())
@@ -858,7 +923,7 @@ def begin_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) ->
858
923
  if thread_id is None:
859
924
  raise SystemExit("thread-id is required.")
860
925
  if args.scan_id:
861
- if args.user_context is not None or args.scope != ".":
926
+ if args.user_context is not None or args.user_context_stdin or args.scope != ".":
862
927
  raise SystemExit("scan-id cannot be combined with target setup fields.")
863
928
  return begin_deep_scan_for_scan(connection, args.scan_id, thread_id, args)
864
929
  if args.claim_token is not None:
@@ -1075,7 +1140,7 @@ def recover_candidate_ledger_publication(connection: sqlite3.Connection, scan_id
1075
1140
  snapshot = Path(reducer["artifact_dir"]) / "canonical" / ledger.name
1076
1141
  if not snapshot.exists():
1077
1142
  continue
1078
- published = ledger.exists() and ledger.samefile(snapshot)
1143
+ published = publication_matches_snapshot(ledger, snapshot)
1079
1144
  interrupted = reducer["status"] != "succeeded"
1080
1145
  if not published and not (interrupted and backups and not ledger.exists()):
1081
1146
  continue
@@ -1577,7 +1642,7 @@ def commit_deep_scan_dedup_locked(
1577
1642
  publication_copy = canonical_path.with_name(
1578
1643
  f".{canonical_path.name}.{uuid.uuid4()}.publish"
1579
1644
  )
1580
- os.link(candidate_ledger_path, publication_copy)
1645
+ create_publication_copy(candidate_ledger_path, publication_copy)
1581
1646
  promotion = promote_staged_file(
1582
1647
  str(publication_copy),
1583
1648
  canonical_candidate_ledger_path,
@@ -1994,9 +2059,59 @@ def fail_deep_scan_locked(
1994
2059
  raise
1995
2060
  if promotion is not None:
1996
2061
  finish_staged_file(promotion)
2062
+ dependencies().preserve_stopped_results(connection, scan_id)
2063
+ return deep_scan_result(connection, scan_id)
2064
+
2065
+
2066
+ def record_deep_scan_publication_failure(
2067
+ connection: sqlite3.Connection, args: argparse.Namespace
2068
+ ) -> dict[str, Any]:
2069
+ scan_id = require_uuid(args.scan_id, "scan-id")
2070
+ message = optional_text(args.message, maximum=2400)
2071
+ if message is None:
2072
+ raise SystemExit("message is required.")
2073
+ with scan_completion_lock(scan_id):
2074
+ connection.execute("BEGIN IMMEDIATE")
2075
+ try:
2076
+ run = require_deep_scan_run(connection, scan_id)
2077
+ require_current_coordinator(run, args)
2078
+ scan = require_scan(connection, scan_id)
2079
+ if (
2080
+ run["status"] not in {"failed", "canceled", "interrupted"}
2081
+ or scan["status"] != "failed"
2082
+ ):
2083
+ raise SystemExit(
2084
+ "Saved result publication failures can only update a stopped Deep Scan."
2085
+ )
2086
+ if scan["seal_manifest_digest"] is not None:
2087
+ connection.commit()
2088
+ return deep_scan_result(connection, scan_id)
2089
+ if run["publication_error_message"] != message:
2090
+ timestamp = now()
2091
+ connection.execute(
2092
+ """
2093
+ UPDATE deep_scan_runs
2094
+ SET publication_error_message = ?, updated_at = ?
2095
+ WHERE scan_id = ?
2096
+ """,
2097
+ (message, timestamp, scan_id),
2098
+ )
2099
+ connection.commit()
2100
+ except BaseException:
2101
+ connection.rollback()
2102
+ raise
1997
2103
  return deep_scan_result(connection, scan_id)
1998
2104
 
1999
2105
 
2106
+ def clear_deep_scan_publication_failure(connection: sqlite3.Connection, scan_id: str) -> None:
2107
+ with connection:
2108
+ connection.execute(
2109
+ "UPDATE deep_scan_runs SET publication_error_message = NULL, updated_at = ? "
2110
+ "WHERE scan_id = ? AND publication_error_message IS NOT NULL",
2111
+ (now(), scan_id),
2112
+ )
2113
+
2114
+
2000
2115
  def fail_from_parent_scan(
2001
2116
  connection: sqlite3.Connection,
2002
2117
  scan_id: str,
@@ -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")
@@ -836,6 +857,20 @@ def _recover_unsealed_findings(
836
857
 
837
858
  if previous_position is not None:
838
859
  previous = recovered[previous_position]
860
+ strongest, earlier = (
861
+ (previous, finding)
862
+ if _finding_strength(finding) <= _finding_strength(previous)
863
+ else (finding, previous)
864
+ )
865
+ if strongest != earlier:
866
+ original = copy.deepcopy(earlier)
867
+ older = original["provenance"].pop("previousFindings", [])
868
+ if not isinstance(strongest["provenance"].get("previousFindings"), list):
869
+ strongest["provenance"]["previousFindings"] = []
870
+ history = strongest["provenance"]["previousFindings"]
871
+ for record in [*(older if isinstance(older, list) else []), original]:
872
+ if record not in history:
873
+ history.append(record)
839
874
  if _finding_strength(finding) <= _finding_strength(previous):
840
875
  warnings.append(
841
876
  f"Skipped malformed finding {index + 1}: duplicate logical finding."
@@ -936,7 +971,7 @@ def _recover_unsealed_coverage(
936
971
  try:
937
972
  if not isinstance(ref, str):
938
973
  raise ContractError(f"{ref_context}: expected a string")
939
- normalized_ref = _require_safe_relative_path(ref, ref_context)
974
+ normalized_ref = _require_portable_relative_path(ref, ref_context)
940
975
  if not normalized_ref.startswith("artifacts/"):
941
976
  raise ContractError(
942
977
  f"{ref_context}: expected a file under artifacts/"
@@ -1039,7 +1074,9 @@ def _populate_unsealed_manifest_envelope(
1039
1074
 
1040
1075
  manifest["documentType"] = "codex-security.scan-manifest"
1041
1076
  manifest["schemaVersion"] = SCHEMA_VERSION
1042
- scan["status"] = "completed"
1077
+ scan["status"] = (
1078
+ completion_binding.get("status", "completed") if completion_binding else "completed"
1079
+ )
1043
1080
  scan["coverageRef"] = "coverage.json"
1044
1081
  scan["findingsRef"] = "findings.json"
1045
1082
  if completion_binding is None:
@@ -1167,6 +1204,8 @@ def _validate_completion_binding(
1167
1204
  scan = _require_dict(manifest, "scan", "manifest")
1168
1205
  if scan.get("id") != completion_binding["scanId"]:
1169
1206
  raise ContractError("manifest.scan.id: must match the workbench scan")
1207
+ if scan.get("status") != completion_binding.get("status", "completed"):
1208
+ raise ContractError("manifest.scan.status: must match the workbench outcome")
1170
1209
  if scan.get("startedAt") != completion_binding["startedAt"]:
1171
1210
  raise ContractError("manifest.scan.startedAt: must match the workbench scan")
1172
1211
  if scan.get("completedAt") != completion_binding["completedAt"]:
@@ -1322,7 +1361,9 @@ def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_
1322
1361
  for ref_index, ref in enumerate(receipt_refs):
1323
1362
  if not isinstance(ref, str):
1324
1363
  raise ContractError(f"{context}.receiptRefs[{ref_index}]: expected a string")
1325
- normalized_ref = _require_safe_relative_path(ref, f"{context}.receiptRefs[{ref_index}]")
1364
+ normalized_ref = _require_portable_relative_path(
1365
+ ref, f"{context}.receiptRefs[{ref_index}]"
1366
+ )
1326
1367
  if not normalized_ref.startswith("artifacts/"):
1327
1368
  raise ContractError(
1328
1369
  f"{context}.receiptRefs[{ref_index}]: expected a file under artifacts/"
@@ -1347,8 +1388,8 @@ def _validate_manifest(manifest: dict[str, Any]) -> None:
1347
1388
  scan = _require_dict(manifest, "scan", "manifest")
1348
1389
  for key in ("id", "startedAt", "completedAt", "sealedAt"):
1349
1390
  _require_str(scan, key, "manifest.scan")
1350
- if scan.get("status") != "completed":
1351
- raise ContractError("manifest.scan.status: expected completed")
1391
+ if scan.get("status") not in {"completed", "failed", "canceled", "interrupted"}:
1392
+ raise ContractError("manifest.scan.status: expected a terminal scan outcome")
1352
1393
  producer = _require_dict(scan, "producer", "manifest.scan")
1353
1394
  _require_str(producer, "name", "manifest.scan.producer")
1354
1395
  _require_str(producer, "version", "manifest.scan.producer")
@@ -1367,16 +1408,19 @@ def _validate_manifest(manifest: dict[str, Any]) -> None:
1367
1408
  if not artifacts:
1368
1409
  raise ContractError("manifest.scan.artifacts: expected generated artifact records")
1369
1410
  artifact_paths: set[str] = set()
1411
+ artifact_collision_keys: set[str] = set()
1370
1412
  for index, artifact in enumerate(artifacts):
1371
1413
  context = f"manifest.scan.artifacts[{index}]"
1372
1414
  if not isinstance(artifact, dict):
1373
1415
  raise ContractError(f"{context}: expected an object")
1374
- path = _require_safe_relative_path(
1416
+ path = _require_portable_relative_path(
1375
1417
  _require_str(artifact, "path", context), f"{context}.path"
1376
1418
  )
1377
- if path in artifact_paths:
1419
+ collision_key = path.lower()
1420
+ if collision_key in artifact_collision_keys:
1378
1421
  raise ContractError(f"{context}.path: duplicate artifact path")
1379
1422
  artifact_paths.add(path)
1423
+ artifact_collision_keys.add(collision_key)
1380
1424
  _require_str(artifact, "sha256", context)
1381
1425
  _require_str(artifact, "mediaType", context)
1382
1426
  for required_path in ("findings.json", "coverage.json"):
@@ -1593,6 +1637,7 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1593
1637
  and evidence["id"]
1594
1638
  }
1595
1639
  for section_name, list_fields in (
1640
+ ("rootCause", ("evidenceRefs", "evidence_refs")),
1596
1641
  ("root_cause", ("evidenceRefs", "evidence_refs")),
1597
1642
  (
1598
1643
  "validation",
@@ -2146,9 +2191,9 @@ def _validate_sarif(sarif: dict[str, Any]) -> None:
2146
2191
  def _artifact_record(
2147
2192
  scan_dir: Path, relative_path: str, media_type: str, contents: bytes | None = None
2148
2193
  ) -> dict[str, str]:
2149
- relative_path = _require_safe_relative_path(relative_path, "artifact path")
2194
+ relative_path = _require_portable_relative_path(relative_path, "artifact path")
2150
2195
  if contents is not None:
2151
- _require_scan_local_file(scan_dir, relative_path, relative_path)
2196
+ _validate_scan_local_output_path(scan_dir, scan_dir / relative_path, relative_path)
2152
2197
  return {
2153
2198
  "mediaType": media_type,
2154
2199
  "path": relative_path,
@@ -2167,7 +2212,7 @@ def _coverage_receipt_refs(coverage: dict[str, Any]) -> list[str]:
2167
2212
 
2168
2213
  def _validate_sealed_coverage_receipts(scan: dict[str, Any], coverage: dict[str, Any]) -> None:
2169
2214
  artifact_paths = {
2170
- _require_safe_relative_path(artifact["path"], "sealed artifact path")
2215
+ _require_portable_relative_path(artifact["path"], "sealed artifact path")
2171
2216
  for artifact in scan["artifacts"]
2172
2217
  }
2173
2218
  for ref in _coverage_receipt_refs(coverage):
@@ -2190,16 +2235,19 @@ def _validate_existing_seal(
2190
2235
  if not isinstance(artifacts, list) or not artifacts:
2191
2236
  raise ContractError("manifest.scan.artifacts: sealed manifest requires artifact records")
2192
2237
  artifact_paths: set[str] = set()
2238
+ artifact_collision_keys: set[str] = set()
2193
2239
  for index, artifact in enumerate(artifacts):
2194
2240
  context = f"manifest.scan.artifacts[{index}]"
2195
2241
  if not isinstance(artifact, dict):
2196
2242
  raise ContractError(f"{context}: expected an object")
2197
- path = _require_safe_relative_path(
2243
+ path = _require_portable_relative_path(
2198
2244
  _require_str(artifact, "path", context), f"{context}.path"
2199
2245
  )
2200
- if path in artifact_paths:
2246
+ collision_key = path.lower()
2247
+ if collision_key in artifact_collision_keys:
2201
2248
  raise ContractError(f"{context}.path: duplicate artifact path")
2202
2249
  artifact_paths.add(path)
2250
+ artifact_collision_keys.add(collision_key)
2203
2251
  expected_sha256 = _require_str(artifact, "sha256", context)
2204
2252
  contents = (artifact_contents or {}).get(path)
2205
2253
  actual_sha256 = (
@@ -2260,19 +2308,23 @@ def build_sarif_projection(
2260
2308
  raise ContractError("source root: expected an existing directory")
2261
2309
  manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
2262
2310
  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
- }
2311
+ run = sarif["runs"][0]
2312
+ completeness = coverage["completeness"]
2313
+ scan_status = manifest["scan"]["status"]
2314
+ execution_successful = scan_status == "completed" and completeness == "complete"
2315
+ run["invocations"] = [{"executionSuccessful": execution_successful}]
2316
+ if not execution_successful:
2317
+ run["properties"]["codexSecurityCoverageCompleteness"] = completeness
2318
+ reasons = [item["reason"] for item in coverage["deferred"]]
2319
+ if not reasons:
2320
+ reasons = [
2321
+ f"Scan status is {scan_status}; results may be incomplete."
2322
+ if scan_status != "completed"
2323
+ else f"Scan coverage is {completeness}; results may be incomplete."
2275
2324
  ]
2325
+ run["invocations"][0]["toolExecutionNotifications"] = [
2326
+ {"level": "warning", "message": {"text": reason}} for reason in reasons
2327
+ ]
2276
2328
  _validate_sarif(sarif)
2277
2329
  return sarif
2278
2330
 
@@ -2298,6 +2350,13 @@ def csv_cell(value: Any) -> Any:
2298
2350
 
2299
2351
 
2300
2352
  def finding_candidate_id(finding: dict[str, Any]) -> str | None:
2353
+ provenance = finding.get("provenance")
2354
+ if (
2355
+ isinstance(provenance, dict)
2356
+ and isinstance(value := provenance.get("candidateId"), str)
2357
+ and value.strip()
2358
+ ):
2359
+ return value
2301
2360
  extensions = finding.get("extensions")
2302
2361
  if not isinstance(extensions, dict):
2303
2362
  return None
@@ -2424,7 +2483,7 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
2424
2483
  scan = _require_dict(manifest, "scan", "manifest")
2425
2484
  artifacts = _require_list(scan, "artifacts", "manifest.scan")
2426
2485
  artifact_paths = [
2427
- _require_safe_relative_path(
2486
+ _require_portable_relative_path(
2428
2487
  _require_str(artifact, "path", f"manifest.scan.artifacts[{index}]"),
2429
2488
  f"manifest.scan.artifacts[{index}].path",
2430
2489
  )
@@ -2489,23 +2548,32 @@ def _prepare_scan_finalization(
2489
2548
  expected_coverage_mode: str | None = None,
2490
2549
  completion_binding: dict[str, Any] | None = None,
2491
2550
  completion_warnings: list[str] | None = None,
2551
+ draft_documents: tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None = None,
2492
2552
  ) -> PreparedScanFinalization:
2493
2553
  """Read, populate, and validate a scan without writing any output files."""
2494
2554
 
2495
2555
  scan_dir = _require_scan_directory(scan_dir)
2496
2556
  schema_dir = schema_dir or Path(__file__).resolve().parent.parent / "schemas"
2497
- manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2557
+ manifest = (
2558
+ copy.deepcopy(draft_documents[0])
2559
+ if draft_documents is not None
2560
+ else _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2561
+ )
2498
2562
  scan = _require_dict(manifest, "scan", "manifest")
2499
2563
  was_sealed = scan.get("sealedAt") is not None or scan.get("artifacts") is not None
2500
2564
  if not was_sealed:
2501
2565
  _populate_unsealed_manifest_envelope(manifest, scan, completion_binding)
2502
2566
  _validate_contract_refs(scan)
2503
- findings, findings_input_bytes = _read_scan_local_json_bytes(
2504
- scan_dir, scan["findingsRef"], scan["findingsRef"]
2505
- )
2506
- coverage, coverage_input_bytes = _read_scan_local_json_bytes(
2507
- scan_dir, scan["coverageRef"], scan["coverageRef"]
2508
- )
2567
+ if draft_documents is None:
2568
+ findings, findings_input_bytes = _read_scan_local_json_bytes(
2569
+ scan_dir, scan["findingsRef"], scan["findingsRef"]
2570
+ )
2571
+ coverage, coverage_input_bytes = _read_scan_local_json_bytes(
2572
+ scan_dir, scan["coverageRef"], scan["coverageRef"]
2573
+ )
2574
+ else:
2575
+ findings, coverage = copy.deepcopy(draft_documents[1:])
2576
+ findings_input_bytes, coverage_input_bytes = _json_bytes(findings), _json_bytes(coverage)
2509
2577
  if not was_sealed:
2510
2578
  _populate_unsealed_artifact_envelope(manifest, findings, coverage, completion_binding)
2511
2579
  _normalize_unsealed_deep_repository_inventory_strategy(
@@ -2516,8 +2584,8 @@ def _prepare_scan_finalization(
2516
2584
 
2517
2585
  if manifest.get("schemaVersion") != SCHEMA_VERSION:
2518
2586
  raise ContractError(f"manifest.schemaVersion: expected {SCHEMA_VERSION}")
2519
- if scan.get("status") != "completed":
2520
- raise ContractError("manifest.scan.status: expected completed before sealing")
2587
+ if scan.get("status") not in {"completed", "failed", "canceled", "interrupted"}:
2588
+ raise ContractError("manifest.scan.status: expected a terminal scan outcome before sealing")
2521
2589
  if (
2522
2590
  expected_coverage_mode is not None
2523
2591
  and completion_binding is not None
@@ -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)
@@ -293,6 +293,21 @@ def path_is_excluded(path: Path) -> bool:
293
293
  return path.name.endswith((".min.js", ".map"))
294
294
 
295
295
 
296
+ def windows_stream_component(path: Path) -> str | None:
297
+ """Return the first NTFS alternate-data-stream component."""
298
+
299
+ if os.name != "nt":
300
+ return None
301
+ return next(
302
+ (
303
+ component
304
+ for component in path.parts
305
+ if component != path.anchor and ":" in component
306
+ ),
307
+ None,
308
+ )
309
+
310
+
296
311
  def resolve_scope(
297
312
  repo: Path,
298
313
  scope: str,
@@ -301,6 +316,9 @@ def resolve_scope(
301
316
  reject_symlinks: bool = False,
302
317
  ) -> Path:
303
318
  scope_path = Path(scope).expanduser() if expand_user else Path(scope)
319
+ stream = windows_stream_component(scope_path)
320
+ if stream is not None:
321
+ raise SystemExit(f"Scope must not use an NTFS alternate data stream: {stream}")
304
322
  if not scope_path.is_absolute():
305
323
  scope_path = repo / scope_path
306
324
  if reject_symlinks:
@@ -621,20 +639,19 @@ def run_git_changed_paths(repo: Path, diff_args: list[str]) -> list[tuple[Path,
621
639
  ],
622
640
  check=True,
623
641
  capture_output=True,
624
- text=True,
625
642
  )
626
- fields = result.stdout.split("\0")
643
+ fields = result.stdout.split(b"\0")
627
644
  if fields and not fields[-1]:
628
645
  fields.pop()
629
646
 
630
647
  changed: list[tuple[Path, str]] = []
631
648
  index = 0
632
649
  while index < len(fields):
633
- status = fields[index][0]
650
+ status = chr(fields[index][0])
634
651
  index += 1
635
652
  if status in {"C", "R"}:
636
653
  index += 1
637
- path = repo / fields[index]
654
+ path = repo / os.fsdecode(fields[index])
638
655
  index += 1
639
656
  changed.append((path, status))
640
657
  return changed
@@ -649,14 +666,13 @@ def git_changed_paths(repo: Path, base: str, head: str, mode: str) -> list[tuple
649
666
  untracked = subprocess.run(
650
667
  ["git", "-C", str(repo), "ls-files", "--others", "--exclude-standard", "-z"],
651
668
  capture_output=True,
652
- text=True,
653
669
  check=True,
654
670
  )
655
671
  combined = dict(staged)
656
672
  combined.update(unstaged)
657
673
  combined.update(
658
- (repo / relative, "A")
659
- for relative in untracked.stdout.split("\0")
674
+ (repo / os.fsdecode(relative), "A")
675
+ for relative in untracked.stdout.split(b"\0")
660
676
  if relative
661
677
  )
662
678
  return sorted(combined.items())