@openai/codex-security 0.1.21 → 0.1.24

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 (183) hide show
  1. package/README.md +549 -1
  2. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  3. package/_bundled_plugin/.mcp.json +1 -0
  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 +2 -30
  7. package/_bundled_plugin/references/core-scan.md +1 -1
  8. package/_bundled_plugin/references/final-report.md +1 -1
  9. package/_bundled_plugin/references/finding-detail-fields.md +5 -10
  10. package/_bundled_plugin/references/sarif-adapter.md +1 -1
  11. package/_bundled_plugin/references/scan-contract.md +10 -0
  12. package/_bundled_plugin/scripts/config_preflight.py +2 -8
  13. package/_bundled_plugin/scripts/deep_scan_workbench.py +6 -1
  14. package/_bundled_plugin/scripts/finalize_scan_contract.py +115 -76
  15. package/_bundled_plugin/scripts/finding_preview.py +22 -4
  16. package/_bundled_plugin/scripts/generate_in_scope_files.py +29 -9
  17. package/_bundled_plugin/scripts/generate_rank_input.py +1 -5
  18. package/_bundled_plugin/scripts/rank_preview.py +1 -0
  19. package/_bundled_plugin/scripts/report_projection.py +8 -14
  20. package/_bundled_plugin/scripts/validate_scan_contract.py +1 -3
  21. package/_bundled_plugin/scripts/windows_scan_local_files.py +90 -6
  22. package/_bundled_plugin/scripts/workbench_cli.py +27 -1
  23. package/_bundled_plugin/scripts/workbench_dashboard.py +138 -0
  24. package/_bundled_plugin/scripts/workbench_db.py +110 -539
  25. package/_bundled_plugin/scripts/workbench_finding_index.py +42 -24
  26. package/_bundled_plugin/scripts/workbench_finding_workflows.py +208 -0
  27. package/_bundled_plugin/scripts/workbench_findings.py +221 -0
  28. package/_bundled_plugin/scripts/workbench_native_indexes.py +1 -2
  29. package/_bundled_plugin/scripts/workbench_publication.py +520 -0
  30. package/_bundled_plugin/scripts/workbench_remediation.py +37 -0
  31. package/_bundled_plugin/scripts/workbench_saved_results.py +322 -89
  32. package/_bundled_plugin/scripts/workbench_scan_history.py +1 -2
  33. package/_bundled_plugin/scripts/workbench_scan_usage.py +9 -33
  34. package/_bundled_plugin/scripts/workbench_schema.py +276 -58
  35. package/_bundled_plugin/scripts/workbench_target.py +30 -6
  36. package/_bundled_plugin/scripts/workbench_validation.py +1 -5
  37. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +1 -5
  38. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +6 -1
  39. package/_bundled_plugin/skills/track-findings/SKILL.md +2 -0
  40. package/dist/api.d.ts +5 -1
  41. package/dist/api.d.ts.map +1 -1
  42. package/dist/api.js +135 -27
  43. package/dist/api.js.map +1 -1
  44. package/dist/cli.d.ts +4 -0
  45. package/dist/cli.d.ts.map +1 -1
  46. package/dist/cli.js +158 -62
  47. package/dist/cli.js.map +1 -1
  48. package/dist/cloud-publish.js +5 -1
  49. package/dist/cloud-publish.js.map +1 -1
  50. package/dist/contract.d.ts +1 -0
  51. package/dist/contract.d.ts.map +1 -1
  52. package/dist/contract.js +9 -0
  53. package/dist/contract.js.map +1 -1
  54. package/dist/custom-publish.d.ts +22 -0
  55. package/dist/custom-publish.d.ts.map +1 -0
  56. package/dist/custom-publish.js +47 -0
  57. package/dist/custom-publish.js.map +1 -0
  58. package/dist/custom-validation-prompt.js +1 -1
  59. package/dist/custom-validation-prompt.js.map +1 -1
  60. package/dist/deduplication/checkpointed-review.d.ts +16 -0
  61. package/dist/deduplication/checkpointed-review.d.ts.map +1 -0
  62. package/dist/deduplication/checkpointed-review.js +76 -0
  63. package/dist/deduplication/checkpointed-review.js.map +1 -0
  64. package/dist/deduplication/codex-review.d.ts +21 -0
  65. package/dist/deduplication/codex-review.d.ts.map +1 -0
  66. package/dist/deduplication/codex-review.js +252 -0
  67. package/dist/deduplication/codex-review.js.map +1 -0
  68. package/dist/deduplication/deduplication-prompts.d.ts +8 -0
  69. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -0
  70. package/dist/deduplication/deduplication-prompts.js +35 -0
  71. package/dist/deduplication/deduplication-prompts.js.map +1 -0
  72. package/dist/deduplication/deduplication-reviewer.d.ts +46 -0
  73. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -0
  74. package/dist/deduplication/deduplication-reviewer.js +105 -0
  75. package/dist/deduplication/deduplication-reviewer.js.map +1 -0
  76. package/dist/deduplication/deduplication.d.ts +6 -0
  77. package/dist/deduplication/deduplication.d.ts.map +1 -0
  78. package/dist/deduplication/deduplication.js +85 -0
  79. package/dist/deduplication/deduplication.js.map +1 -0
  80. package/dist/deduplication/scan.d.ts +16 -0
  81. package/dist/deduplication/scan.d.ts.map +1 -0
  82. package/dist/deduplication/scan.js +101 -0
  83. package/dist/deduplication/scan.js.map +1 -0
  84. package/dist/deep-progress.d.ts +21 -0
  85. package/dist/deep-progress.d.ts.map +1 -0
  86. package/dist/deep-progress.js +108 -0
  87. package/dist/deep-progress.js.map +1 -0
  88. package/dist/finding-dedupe-groups.d.ts +7 -0
  89. package/dist/finding-dedupe-groups.d.ts.map +1 -0
  90. package/dist/finding-dedupe-groups.js +2 -0
  91. package/dist/finding-dedupe-groups.js.map +1 -0
  92. package/dist/finding-retrieval.d.ts +13 -0
  93. package/dist/finding-retrieval.d.ts.map +1 -0
  94. package/dist/finding-retrieval.js +2 -0
  95. package/dist/finding-retrieval.js.map +1 -0
  96. package/dist/finding-workflow.d.ts +53 -0
  97. package/dist/finding-workflow.d.ts.map +1 -0
  98. package/dist/finding-workflow.js +117 -0
  99. package/dist/finding-workflow.js.map +1 -0
  100. package/dist/findings-client.d.ts +15 -0
  101. package/dist/findings-client.d.ts.map +1 -0
  102. package/dist/findings-client.js +60 -0
  103. package/dist/findings-client.js.map +1 -0
  104. package/dist/index.d.ts +5 -0
  105. package/dist/index.d.ts.map +1 -1
  106. package/dist/index.js +2 -0
  107. package/dist/index.js.map +1 -1
  108. package/dist/publication.js +28 -40
  109. package/dist/publication.js.map +1 -1
  110. package/dist/runtime.d.ts +5 -1
  111. package/dist/runtime.d.ts.map +1 -1
  112. package/dist/runtime.js +119 -13
  113. package/dist/runtime.js.map +1 -1
  114. package/dist/saved-scan.d.ts +15 -0
  115. package/dist/saved-scan.d.ts.map +1 -0
  116. package/dist/saved-scan.js +68 -0
  117. package/dist/saved-scan.js.map +1 -0
  118. package/dist/scan-activity.d.ts.map +1 -1
  119. package/dist/scan-activity.js +12 -2
  120. package/dist/scan-activity.js.map +1 -1
  121. package/dist/scan-comparison.d.ts +3 -2
  122. package/dist/scan-comparison.d.ts.map +1 -1
  123. package/dist/scan-comparison.js +1 -1
  124. package/dist/scan-comparison.js.map +1 -1
  125. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +276 -0
  126. package/dist/server/dashboard/app.css +2 -0
  127. package/dist/server/dashboard/app.js +66 -0
  128. package/dist/server/dashboard/index.html +18 -0
  129. package/dist/server/dashboard-types.d.ts +45 -0
  130. package/dist/server/dashboard-types.d.ts.map +1 -0
  131. package/dist/server/dashboard-types.js +2 -0
  132. package/dist/server/dashboard-types.js.map +1 -0
  133. package/dist/server/dashboard.d.ts +6 -0
  134. package/dist/server/dashboard.d.ts.map +1 -0
  135. package/dist/server/dashboard.js +45 -0
  136. package/dist/server/dashboard.js.map +1 -0
  137. package/dist/server/embeddings.d.ts +16 -0
  138. package/dist/server/embeddings.d.ts.map +1 -0
  139. package/dist/server/embeddings.js +114 -0
  140. package/dist/server/embeddings.js.map +1 -0
  141. package/dist/server/errors.d.ts +5 -0
  142. package/dist/server/errors.d.ts.map +1 -0
  143. package/dist/server/errors.js +8 -0
  144. package/dist/server/errors.js.map +1 -0
  145. package/dist/server/findings-service.d.ts +20 -0
  146. package/dist/server/findings-service.d.ts.map +1 -0
  147. package/dist/server/findings-service.js +31 -0
  148. package/dist/server/findings-service.js.map +1 -0
  149. package/dist/server/index.d.ts +2 -0
  150. package/dist/server/index.d.ts.map +1 -0
  151. package/dist/server/index.js +6 -0
  152. package/dist/server/index.js.map +1 -0
  153. package/dist/server/routes.d.ts +6 -0
  154. package/dist/server/routes.d.ts.map +1 -0
  155. package/dist/server/routes.js +86 -0
  156. package/dist/server/routes.js.map +1 -0
  157. package/dist/server/serve.d.ts +2 -0
  158. package/dist/server/serve.d.ts.map +1 -0
  159. package/dist/server/serve.js +28 -0
  160. package/dist/server/serve.js.map +1 -0
  161. package/dist/server/server.d.ts +10 -0
  162. package/dist/server/server.d.ts.map +1 -0
  163. package/dist/server/server.js +17 -0
  164. package/dist/server/server.js.map +1 -0
  165. package/dist/server/sqlite-store.d.ts +22 -0
  166. package/dist/server/sqlite-store.d.ts.map +1 -0
  167. package/dist/server/sqlite-store.js +82 -0
  168. package/dist/server/sqlite-store.js.map +1 -0
  169. package/dist/server/storage.d.ts +32 -0
  170. package/dist/server/storage.d.ts.map +1 -0
  171. package/dist/server/storage.js +2 -0
  172. package/dist/server/storage.js.map +1 -0
  173. package/dist/server/validation.d.ts +17 -0
  174. package/dist/server/validation.d.ts.map +1 -0
  175. package/dist/server/validation.js +53 -0
  176. package/dist/server/validation.js.map +1 -0
  177. package/dist/trusted-executable.d.ts.map +1 -1
  178. package/dist/trusted-executable.js +2 -1
  179. package/dist/trusted-executable.js.map +1 -1
  180. package/dist/version.d.ts +1 -1
  181. package/dist/version.js +1 -1
  182. package/dist/version.js.map +1 -1
  183. package/package.json +17 -5
@@ -118,7 +118,7 @@ Affected lines must include the root broken control or dangerous sink line when
118
118
  Then render these subsections under each finding:
119
119
 
120
120
  - `#### Summary`
121
- - Explain why the issue matters, what the vulnerable path is, and why the current controls are insufficient.
121
+ - Start with how to reproduce the issue and what happens in the product, then explain why the code causes that behavior.
122
122
  - Wrap code identifiers, RPC names, functions, types, fields, parameters, configuration keys, and literal values in single backticks.
123
123
  - `#### Root Cause`
124
124
  - State the violated security invariant and explain exactly how the implementation breaks it.
@@ -4,6 +4,9 @@ For every reportable finding in `findings.json`, preserve the validated reasonin
4
4
 
5
5
  ## Writing Rules
6
6
 
7
+ - Lead the title and `summary` with the user action and product impact.
8
+ - Use `attackPath.summary` to briefly explain how to reproduce the issue.
9
+ - Explain how the code causes that product behavior in `rootCause.summary`. Use plain language and avoid repetition.
7
10
  - Wrap RPC names, functions, types, fields, parameters, configuration keys, literal identifiers, and short expressions in single backticks. For example: `environment/add`, `environmentId`, `execServerUrl`, and `EnvironmentManager::upsert_environment()`.
8
11
  - Keep code out of prose. Put source snippets in `codeEvidence[].code`, then reference them from the section that explains why the snippet matters. The workspace consolidates those referenced snippets under **Root cause** so the violated invariant and its source proof stay together.
9
12
  - Root cause must be a source-backed walkthrough, not a verdict paragraph. Start with the code where user-controlled data is declared, decoded, or read; follow each meaningful call, transformation, or state transition; then show the missing control, dangerous operation, and later consumer when it affects impact.
@@ -106,11 +109,7 @@ The following shape shows how to encode the `environment/add` reserved-environme
106
109
  "validation": {
107
110
  "method": "static source trace",
108
111
  "summary": "The source trace confirms that an `environment/add` caller controls both inputs, the RPC forwards them unchanged, and runtime insertion accepts `local`.",
109
- "evidenceRefs": [
110
- "rpc-input",
111
- "rpc-forward",
112
- "runtime-upsert"
113
- ],
112
+ "evidenceRefs": ["rpc-input", "rpc-forward", "runtime-upsert"],
114
113
  "assertions": [
115
114
  "The runtime path lacks the reserved-ID check present during startup.",
116
115
  "Inserting `local` replaces the existing `HashMap` entry."
@@ -139,11 +138,7 @@ The following shape shows how to encode the `environment/add` reserved-environme
139
138
  "entrypoint": "experimental `environment/add` RPC",
140
139
  "outcome": "future operations selected for `local` are routed to the remote executor"
141
140
  },
142
- "evidenceRefs": [
143
- "rpc-forward",
144
- "runtime-upsert",
145
- "default-lookup"
146
- ],
141
+ "evidenceRefs": ["rpc-forward", "runtime-upsert", "default-lookup"],
147
142
  "impact": {
148
143
  "level": "medium",
149
144
  "why": "Later commands and filesystem requests selected for `local` can be routed to the attacker-controlled remote executor."
@@ -20,7 +20,7 @@ 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.
23
+ SARIF `executionSuccessful` reflects whether the scan reached a successful terminal status, not whether coverage is complete. Incomplete scans retain findings, set `codexSecurityCoverageCompleteness`, and include warnings. Integrations must read the coverage file referenced by `scan.coverageRef` before treating the results as exhaustive.
24
24
 
25
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.
26
26
 
@@ -37,6 +37,16 @@ A sealed manifest records the terminal timestamp and hashes for the canonical do
37
37
 
38
38
  Only `completed` supports a completed-scan conclusion. For every stopped outcome, consumers must preserve retained findings and coverage while treating absence of findings as inconclusive.
39
39
 
40
+ ### Stopped Result Recovery
41
+
42
+ To validate and republish retained checkpoints for a failed, non-canceled workbench scan, run:
43
+
44
+ ```text
45
+ <python_command> <plugin_dir>/scripts/workbench_db.py recover-scan-results --scan-id <scan_id>
46
+ ```
47
+
48
+ Recovery can add only checkpoints that pass the stopped-scan source-integrity checks. It is not available for running, completed, or canceled scans. After cancellation, the owning continuation may retry publication only from the source set frozen at cancellation through `preserve-scan-results`; it cannot admit later checkpoints.
49
+
40
50
  ## Target Snapshots
41
51
 
42
52
  Choose the target kind based on the reviewed content, not the scan invocation:
@@ -538,12 +538,7 @@ def resolve_multi_agent_context(
538
538
  effective_config=effective_config,
539
539
  config_profile=config_profile,
540
540
  )
541
- if (
542
- owner != "codex-bridge"
543
- and ((feature_found and enabled) or (owner == "native" and version == "v2"))
544
- and agent_threads_found
545
- and (validate_multi_agent_config or runtime_facts_supplied)
546
- ):
541
+ if owner != "codex-bridge" and feature_found and enabled and agent_threads_found:
547
542
  raise ValueError("agents.max_threads cannot be set when multi_agent_v2 is enabled")
548
543
 
549
544
  if version == "v1":
@@ -806,8 +801,7 @@ def profile_requires_multi_agent_config(
806
801
  return True
807
802
  remediation = profile.get("remediation", {})
808
803
  return bool(remediation.get("variants")) or any(
809
- is_runtime_path(patch.get("path"))
810
- for patch in remediation.get("patches", [])
804
+ is_runtime_path(patch.get("path")) for patch in remediation.get("patches", [])
811
805
  )
812
806
 
813
807
 
@@ -496,7 +496,11 @@ def independent_review_progress(
496
496
  connection: sqlite3.Connection, scan_id: str
497
497
  ) -> dict[str, int | str] | None:
498
498
  run = connection.execute(
499
- "SELECT completion_sequence, phase, updated_at FROM deep_scan_runs WHERE scan_id = ?",
499
+ """
500
+ SELECT completion_sequence, phase, updated_at, max_discovery_runs
501
+ FROM deep_scan_runs
502
+ WHERE scan_id = ?
503
+ """,
500
504
  (scan_id,),
501
505
  ).fetchone()
502
506
  if run is None:
@@ -514,6 +518,7 @@ def independent_review_progress(
514
518
  return {
515
519
  "active": int(active),
516
520
  "completed": int(run["completion_sequence"]),
521
+ "maximum": int(run["max_discovery_runs"]),
517
522
  "consolidating": run["phase"] == "reducing",
518
523
  "updatedAt": str(run["updated_at"]),
519
524
  }
@@ -200,6 +200,14 @@ def _sha256_bytes(value: bytes) -> str:
200
200
  return hashlib.sha256(value).hexdigest()
201
201
 
202
202
 
203
+ def _sha256_file(path: Path) -> str:
204
+ digest = hashlib.sha256()
205
+ with path.open("rb") as handle:
206
+ for chunk in iter(lambda: handle.read(1024 * 1024), b""):
207
+ digest.update(chunk)
208
+ return digest.hexdigest()
209
+
210
+
203
211
  def _require_dict(payload: dict[str, Any], key: str, context: str) -> dict[str, Any]:
204
212
  value = payload.get(key)
205
213
  if not isinstance(value, dict):
@@ -242,9 +250,7 @@ def _require_safe_relative_path(value: str, context: str, *, allow_dot: bool = F
242
250
  return normalized
243
251
 
244
252
 
245
- def _require_portable_relative_path(
246
- value: str, context: str, *, allow_dot: bool = False
247
- ) -> str:
253
+ def _require_portable_relative_path(value: str, context: str, *, allow_dot: bool = False) -> str:
248
254
  normalized = _require_safe_relative_path(value, context, allow_dot=allow_dot)
249
255
  if any(_windows_unsafe_path_component(part) for part in value.split("/")):
250
256
  raise ContractError(f"{context}: expected a safe scan-relative POSIX path")
@@ -280,10 +286,7 @@ def _validate_scan_local_output_path(scan_dir: Path, path: Path, relative_path:
280
286
  resolved_parent.relative_to(scan_dir)
281
287
  except (OSError, RuntimeError, ValueError) as exc:
282
288
  raise ContractError(f"{relative_path}: expected a path inside the scan directory") from exc
283
- if (
284
- os.path.normcase(resolved_parent) != os.path.normcase(path.parent)
285
- or path.is_symlink()
286
- ):
289
+ if os.path.normcase(resolved_parent) != os.path.normcase(path.parent) or path.is_symlink():
287
290
  raise ContractError(
288
291
  f"{relative_path}: expected a non-symlink path inside the scan directory"
289
292
  )
@@ -312,7 +315,7 @@ _WINDOWS_SCAN_LOCAL_FILES: Any | None = None
312
315
 
313
316
 
314
317
  def _windows_scan_local_files() -> Any:
315
- """Load the Win32 backend only on runtimes that need it."""
318
+ """Load the Win32 backend and shared stream comparison lazily."""
316
319
 
317
320
  global _WINDOWS_SCAN_LOCAL_FILES
318
321
  if _WINDOWS_SCAN_LOCAL_FILES is None:
@@ -326,10 +329,15 @@ def _windows_scan_local_files() -> Any:
326
329
  return _WINDOWS_SCAN_LOCAL_FILES
327
330
 
328
331
 
329
- def _open_verified_scan_directory(scan_dir: Path) -> int:
332
+ def _open_verified_scan_directory(
333
+ scan_dir: Path, expected_root_identity: tuple[int, int] | None = None
334
+ ) -> int:
330
335
  scan_dir = scan_dir.absolute()
331
336
  try:
332
337
  expected = scan_dir.lstat()
338
+ observed_identity = (expected.st_dev, expected.st_ino)
339
+ if expected_root_identity is not None and observed_identity != expected_root_identity:
340
+ raise ContractError("scan directory: changed after artifact restoration setup")
333
341
  canonical = _require_scan_directory(scan_dir)
334
342
  descriptor = os.open(
335
343
  canonical,
@@ -338,12 +346,31 @@ def _open_verified_scan_directory(scan_dir: Path) -> int:
338
346
  except OSError as exc:
339
347
  raise ContractError("scan directory: expected an existing non-symlink directory") from exc
340
348
  opened = os.fstat(descriptor)
341
- if (opened.st_dev, opened.st_ino) != (expected.st_dev, expected.st_ino):
349
+ opened_identity = (opened.st_dev, opened.st_ino)
350
+ if opened_identity != observed_identity or (
351
+ expected_root_identity is not None and opened_identity != expected_root_identity
352
+ ):
342
353
  os.close(descriptor)
343
354
  raise ContractError("scan directory: changed while it was being opened")
344
355
  return descriptor
345
356
 
346
357
 
358
+ def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
359
+ """Return a canonical scan root and its identity from a held handle."""
360
+
361
+ scan_dir = _require_scan_directory(scan_dir)
362
+ if not _descriptor_relative_writes_available():
363
+ if not _is_windows():
364
+ raise ContractError("scan-local output requires descriptor-relative file operations")
365
+ return _windows_scan_local_files().scan_root_identity(scan_dir)
366
+ descriptor = _open_verified_scan_directory(scan_dir)
367
+ try:
368
+ metadata = os.fstat(descriptor)
369
+ return scan_dir, (metadata.st_dev, metadata.st_ino)
370
+ finally:
371
+ os.close(descriptor)
372
+
373
+
347
374
  def _open_scan_local_directory(root_fd: int, parts: tuple[str, ...], *, create: bool) -> int:
348
375
  descriptor = os.dup(root_fd)
349
376
  try:
@@ -492,7 +519,12 @@ def _sha256_scan_local_file(scan_dir: Path, relative_path: str, context: str) ->
492
519
 
493
520
 
494
521
  def write_scan_local_bytes(
495
- scan_dir: Path, relative_path: str, payload: bytes, *, external_name: bool = False
522
+ scan_dir: Path,
523
+ relative_path: str,
524
+ payload: bytes,
525
+ *,
526
+ external_name: bool = False,
527
+ expected_root_identity: tuple[int, int] | None = None,
496
528
  ) -> None:
497
529
  scan_dir = _require_scan_directory(scan_dir)
498
530
  if external_name:
@@ -505,7 +537,12 @@ def write_scan_local_bytes(
505
537
  if not _is_windows():
506
538
  raise ContractError("scan-local output requires descriptor-relative file operations")
507
539
  try:
508
- _windows_scan_local_files().atomic_write(scan_dir, relative_path, payload)
540
+ _windows_scan_local_files().atomic_write(
541
+ scan_dir,
542
+ relative_path,
543
+ payload,
544
+ expected_root_identity=expected_root_identity,
545
+ )
509
546
  except OSError as exc:
510
547
  raise ContractError(f"{relative_path}: {exc}") from exc
511
548
  return
@@ -513,7 +550,7 @@ def write_scan_local_bytes(
513
550
  parent_fd: int | None = None
514
551
  temp_name: str | None = None
515
552
  try:
516
- root_fd = _open_verified_scan_directory(scan_dir)
553
+ root_fd = _open_verified_scan_directory(scan_dir, expected_root_identity)
517
554
  parts = PurePosixPath(relative_path).parts
518
555
  try:
519
556
  parent_fd = _open_scan_local_directory(root_fd, parts[:-1], create=True)
@@ -521,6 +558,9 @@ def write_scan_local_bytes(
521
558
  raise ContractError(
522
559
  f"{relative_path}: expected a path inside the scan directory"
523
560
  ) from exc
561
+ # The held descriptor is the authority for the validated parent. A
562
+ # concurrent rename cannot redirect later operations through a
563
+ # replacement path or link.
524
564
  try:
525
565
  metadata = os.stat(parts[-1], dir_fd=parent_fd, follow_symlinks=False)
526
566
  except FileNotFoundError:
@@ -528,6 +568,38 @@ def write_scan_local_bytes(
528
568
  else:
529
569
  if not stat.S_ISREG(metadata.st_mode):
530
570
  raise ContractError(f"{relative_path}: expected a regular non-symlink file")
571
+ try:
572
+ existing_fd = os.open(
573
+ parts[-1],
574
+ os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0),
575
+ dir_fd=parent_fd,
576
+ )
577
+ except OSError as exc:
578
+ if exc.errno not in {errno.ENOENT, errno.EACCES, errno.EPERM}:
579
+ raise
580
+ else:
581
+ try:
582
+ opened = os.fstat(existing_fd)
583
+ if not stat.S_ISREG(opened.st_mode):
584
+ raise ContractError(f"{relative_path}: expected a regular non-symlink file")
585
+ if (opened.st_dev, opened.st_ino) != (
586
+ metadata.st_dev,
587
+ metadata.st_ino,
588
+ ):
589
+ raise ContractError(f"{relative_path}: changed while it was being opened")
590
+ if expected_root_identity is not None and opened.st_size == len(payload):
591
+ try:
592
+ with os.fdopen(existing_fd, "rb") as handle:
593
+ existing_fd = -1
594
+ if _windows_scan_local_files().stream_matches_payload(
595
+ handle, payload
596
+ ):
597
+ return
598
+ except OSError:
599
+ pass
600
+ finally:
601
+ if existing_fd >= 0:
602
+ os.close(existing_fd)
531
603
  temp_name = f".{path.name}.{secrets.token_hex(8)}.tmp"
532
604
  temp_fd = os.open(temp_name, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=parent_fd)
533
605
  with os.fdopen(temp_fd, "wb") as handle:
@@ -763,9 +835,9 @@ def _recover_unsealed_findings(
763
835
  try:
764
836
  if not isinstance(finding, dict):
765
837
  raise ContractError(f"{context}: expected an object")
766
- compatible_findings = _legacy_sealed_findings_for_validation(
767
- {"findings": [finding]}
768
- )["findings"]
838
+ compatible_findings = _legacy_sealed_findings_for_validation({"findings": [finding]})[
839
+ "findings"
840
+ ]
769
841
  compatible_finding = compatible_findings[0]
770
842
  normalized_legacy_details = compatible_finding != finding
771
843
  finding = compatible_finding
@@ -776,9 +848,7 @@ def _recover_unsealed_findings(
776
848
  ]
777
849
  if "instance" in identity:
778
850
  fields.append((identity, "instance", f"{context}.identity", "instance"))
779
- normalized_fields = (
780
- ["legacy finding details"] if normalized_legacy_details else []
781
- )
851
+ normalized_fields = ["legacy finding details"] if normalized_legacy_details else []
782
852
  for parent, field, field_context, label in fields:
783
853
  value = _require_str(parent, field, field_context)
784
854
  if SLUG_RE.fullmatch(value):
@@ -1555,10 +1625,7 @@ def _validate_schema_node(
1555
1625
  raise ContractError(f"{context}: array has too many items")
1556
1626
  if schema.get("uniqueItems") is True:
1557
1627
  for index, item in enumerate(value):
1558
- if any(
1559
- _schema_values_equal(item, candidate)
1560
- for candidate in value[:index]
1561
- ):
1628
+ if any(_schema_values_equal(item, candidate) for candidate in value[:index]):
1562
1629
  raise ContractError(f"{context}: array items must be unique")
1563
1630
  contains = schema.get("contains")
1564
1631
  if isinstance(contains, dict):
@@ -1577,9 +1644,7 @@ def _validate_schema_node(
1577
1644
  item_schema = schema.get("items")
1578
1645
  if isinstance(item_schema, dict):
1579
1646
  for index, item in enumerate(value):
1580
- _validate_schema_node(
1581
- item, item_schema, f"{context}[{index}]", root_schema
1582
- )
1647
+ _validate_schema_node(item, item_schema, f"{context}[{index}]", root_schema)
1583
1648
  if isinstance(value, dict):
1584
1649
  for item_schema in schema.get("allOf", []):
1585
1650
  _validate_schema_node(value, item_schema, context, root_schema)
@@ -1603,9 +1668,7 @@ def _validate_schema_node(
1603
1668
  for key, item in value.items():
1604
1669
  item_schema = properties.get(key)
1605
1670
  if isinstance(item_schema, dict):
1606
- _validate_schema_node(
1607
- item, item_schema, f"{context}.{key}", root_schema
1608
- )
1671
+ _validate_schema_node(item, item_schema, f"{context}.{key}", root_schema)
1609
1672
  elif additional_properties is False:
1610
1673
  raise ContractError(f"{context}.{key}: unexpected schema property")
1611
1674
  elif isinstance(additional_properties, dict):
@@ -1622,22 +1685,16 @@ def validate_against_schema(payload: dict[str, Any], schema_path: Path) -> None:
1622
1685
  _validate_schema_node(payload, schema, schema_path.stem, schema)
1623
1686
 
1624
1687
 
1625
- def _filter_unknown_legacy_evidence_refs(
1626
- section: dict[str, Any], evidence_ids: set[str]
1627
- ) -> None:
1688
+ def _filter_unknown_legacy_evidence_refs(section: dict[str, Any], evidence_ids: set[str]) -> None:
1628
1689
  for refs_field in ("evidenceRefs", "evidence_refs"):
1629
1690
  refs = section.get(refs_field)
1630
1691
  if isinstance(refs, list):
1631
1692
  section[refs_field] = [
1632
- ref
1633
- for ref in refs
1634
- if isinstance(ref, str) and ref.strip() and ref in evidence_ids
1693
+ ref for ref in refs if isinstance(ref, str) and ref.strip() and ref in evidence_ids
1635
1694
  ]
1636
1695
 
1637
1696
 
1638
- def _normalize_legacy_string_list_fields(
1639
- section: dict[str, Any], fields: tuple[str, ...]
1640
- ) -> None:
1697
+ def _normalize_legacy_string_list_fields(section: dict[str, Any], fields: tuple[str, ...]) -> None:
1641
1698
  for field in fields:
1642
1699
  if field not in section:
1643
1700
  continue
@@ -1645,9 +1702,7 @@ def _normalize_legacy_string_list_fields(
1645
1702
  if isinstance(value, str):
1646
1703
  normalized = [value] if value.strip() else []
1647
1704
  elif isinstance(value, list):
1648
- normalized = [
1649
- item for item in value if isinstance(item, str) and item.strip()
1650
- ]
1705
+ normalized = [item for item in value if isinstance(item, str) and item.strip()]
1651
1706
  else:
1652
1707
  normalized = []
1653
1708
  if normalized:
@@ -1660,9 +1715,7 @@ def _remove_unsupported_legacy_scalar_fields(
1660
1715
  section: dict[str, Any], fields: tuple[str, ...]
1661
1716
  ) -> None:
1662
1717
  for field in fields:
1663
- if field in section and (
1664
- not isinstance(section[field], str) or section[field] == ""
1665
- ):
1718
+ if field in section and (not isinstance(section[field], str) or section[field] == ""):
1666
1719
  section.pop(field)
1667
1720
 
1668
1721
 
@@ -1679,9 +1732,7 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1679
1732
  canonical_evidence_ids = {
1680
1733
  evidence["id"]
1681
1734
  for evidence in canonical_evidence
1682
- if isinstance(evidence, dict)
1683
- and isinstance(evidence.get("id"), str)
1684
- and evidence["id"]
1735
+ if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
1685
1736
  }
1686
1737
  legacy_evidence = finding.get("code_evidence")
1687
1738
  if isinstance(legacy_evidence, list):
@@ -1713,9 +1764,7 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1713
1764
  evidence_ids = canonical_evidence_ids | {
1714
1765
  evidence["id"]
1715
1766
  for evidence in compatible_legacy_evidence
1716
- if isinstance(evidence, dict)
1717
- and isinstance(evidence.get("id"), str)
1718
- and evidence["id"]
1767
+ if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
1719
1768
  }
1720
1769
  for section_name, list_fields in (
1721
1770
  ("rootCause", ("evidenceRefs", "evidence_refs")),
@@ -1797,12 +1846,8 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1797
1846
  for field in ("impact", "likelihood"):
1798
1847
  detail = attack_path.get(field)
1799
1848
  if isinstance(detail, dict):
1800
- _remove_unsupported_legacy_scalar_fields(
1801
- detail, ("level", "rationale", "why")
1802
- )
1803
- elif detail is not None and (
1804
- not isinstance(detail, str) or detail == ""
1805
- ):
1849
+ _remove_unsupported_legacy_scalar_fields(detail, ("level", "rationale", "why"))
1850
+ elif detail is not None and (not isinstance(detail, str) or detail == ""):
1806
1851
  attack_path.pop(field)
1807
1852
  return compatible
1808
1853
 
@@ -2389,22 +2434,18 @@ def build_sarif_projection(
2389
2434
  raise ContractError("source root: expected an existing directory")
2390
2435
  manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
2391
2436
  sarif = build_sarif(manifest, findings, source_root)
2392
- run = sarif["runs"][0]
2393
- completeness = coverage["completeness"]
2394
- scan_status = manifest["scan"]["status"]
2395
- execution_successful = scan_status == "completed" and completeness == "complete"
2396
- run["invocations"] = [{"executionSuccessful": execution_successful}]
2397
- if not execution_successful:
2398
- run["properties"]["codexSecurityCoverageCompleteness"] = completeness
2399
- reasons = [item["reason"] for item in coverage["deferred"]]
2400
- if not reasons:
2401
- reasons = [
2402
- f"Scan status is {scan_status}; results may be incomplete."
2403
- if scan_status != "completed"
2404
- else f"Scan coverage is {completeness}; results may be incomplete."
2405
- ]
2406
- run["invocations"][0]["toolExecutionNotifications"] = [
2407
- {"level": "warning", "message": {"text": reason}} for reason in reasons
2437
+ execution_successful = manifest["scan"]["status"] == "completed"
2438
+ if not execution_successful or coverage["completeness"] != "complete":
2439
+ run = sarif["runs"][0]
2440
+ run["properties"]["codexSecurityCoverageCompleteness"] = coverage["completeness"]
2441
+ run["invocations"] = [
2442
+ {
2443
+ "executionSuccessful": execution_successful,
2444
+ "toolExecutionNotifications": [
2445
+ {"level": "warning", "message": {"text": item["reason"]}}
2446
+ for item in coverage["deferred"]
2447
+ ],
2448
+ }
2408
2449
  ]
2409
2450
  _validate_sarif(sarif)
2410
2451
  return sarif
@@ -2715,9 +2756,7 @@ def _prepare_scan_finalization(
2715
2756
  _validate_sealed_coverage_receipts(scan, coverage)
2716
2757
  _validate_manifest(manifest)
2717
2758
  validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
2718
- validate_against_schema(
2719
- findings_for_validation, schema_dir / "findings.schema.json"
2720
- )
2759
+ validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
2721
2760
  validate_against_schema(coverage, schema_dir / "coverage.schema.json")
2722
2761
  report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
2723
2762
  _validate_report_output_paths(scan_dir)
@@ -2746,7 +2785,7 @@ def _prepare_scan_finalization(
2746
2785
  _validate_sealed_coverage_receipts(scan, coverage)
2747
2786
  _validate_manifest(manifest)
2748
2787
  validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
2749
- validate_against_schema(findings, schema_dir / "findings.schema.json")
2788
+ validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
2750
2789
  validate_against_schema(coverage, schema_dir / "coverage.schema.json")
2751
2790
  _contract_json_bytes("scan-manifest.json", manifest)
2752
2791
  return (
@@ -218,6 +218,7 @@ def bounded_finding_details(value: Any) -> dict[str, Any]:
218
218
  projected_core = bounded_json_value(
219
219
  core,
220
220
  [FINDING_DETAILS_PREVIEW_BYTES - reserved],
221
+ max_depth=5,
221
222
  )
222
223
  if all(key in projected_core for key in core):
223
224
  break
@@ -225,6 +226,7 @@ def bounded_finding_details(value: Any) -> dict[str, Any]:
225
226
  bounded = bounded_json_value(
226
227
  {**projected_core, **ordered_guidance, **extras},
227
228
  [FINDING_DETAILS_PREVIEW_BYTES],
229
+ max_depth=5,
228
230
  )
229
231
  return bounded if isinstance(bounded, dict) else {}
230
232
 
@@ -324,10 +326,16 @@ def bounded_code_evidence(value: Any) -> Any:
324
326
  return bounded
325
327
 
326
328
 
327
- def bounded_json_value(value: Any, budget: list[int], *, depth: int = 0) -> Any:
329
+ def bounded_json_value(
330
+ value: Any,
331
+ budget: list[int],
332
+ *,
333
+ depth: int = 0,
334
+ max_depth: int = 4,
335
+ ) -> Any:
328
336
  if budget[0] <= 0:
329
337
  return None
330
- if depth >= 4:
338
+ if depth >= max_depth:
331
339
  consume_json_budget(budget, 4)
332
340
  return None
333
341
  if isinstance(value, str):
@@ -346,7 +354,12 @@ def bounded_json_value(value: Any, budget: list[int], *, depth: int = 0) -> Any:
346
354
  separator = 0 if not result else 1
347
355
  if not consume_json_budget(budget, separator):
348
356
  break
349
- bounded_item = bounded_json_value(item, budget, depth=depth + 1)
357
+ bounded_item = bounded_json_value(
358
+ item,
359
+ budget,
360
+ depth=depth + 1,
361
+ max_depth=max_depth,
362
+ )
350
363
  size = len(json.dumps(bounded_item, separators=(",", ":")).encode("utf-8"))
351
364
  if separator + size > remaining or (
352
365
  isinstance(item, str) and item and bounded_item == ""
@@ -401,7 +414,12 @@ def bounded_json_value(value: Any, budget: list[int], *, depth: int = 0) -> Any:
401
414
  if budget[0] >= minimum_tests + reserved:
402
415
  item_budget = [budget[0] - reserved]
403
416
  break
404
- bounded_item = bounded_json_value(item, item_budget, depth=depth + 1)
417
+ bounded_item = bounded_json_value(
418
+ item,
419
+ item_budget,
420
+ depth=depth + 1,
421
+ max_depth=max_depth,
422
+ )
405
423
  size = (
406
424
  separator
407
425
  + key_size
@@ -21,11 +21,7 @@ def windows_stream_component(path: Path) -> str | None:
21
21
  if os.name != "nt":
22
22
  return None
23
23
  return next(
24
- (
25
- component
26
- for component in path.parts
27
- if component != path.anchor and ":" in component
28
- ),
24
+ (component for component in path.parts if component != path.anchor and ":" in component),
29
25
  None,
30
26
  )
31
27
 
@@ -49,9 +45,7 @@ def resolve_scope(repository: Path, value: str) -> str:
49
45
  requested = Path(value).expanduser()
50
46
  stream = windows_stream_component(requested)
51
47
  if stream is not None:
52
- raise InventoryError(
53
- f"--scope: NTFS alternate data streams are not supported: {stream}"
54
- )
48
+ raise InventoryError(f"--scope: NTFS alternate data streams are not supported: {stream}")
55
49
  scope = requested if requested.is_absolute() else repository / requested
56
50
  try:
57
51
  resolved = scope.resolve(strict=True)
@@ -93,7 +87,6 @@ def generate_in_scope_files(repository: Path, scope: str, output: Path) -> int:
93
87
  "rg",
94
88
  "--files",
95
89
  "--hidden",
96
- "--no-ignore",
97
90
  "--path-separator",
98
91
  "/",
99
92
  "--glob",
@@ -120,6 +113,33 @@ def generate_in_scope_files(repository: Path, scope: str, output: Path) -> int:
120
113
  message = f"{message}: {detail}"
121
114
  raise InventoryError(message)
122
115
 
116
+ if (repository / ".git").exists():
117
+ try:
118
+ tracked = subprocess.run(
119
+ [
120
+ "git",
121
+ "ls-files",
122
+ "--cached",
123
+ "--ignored",
124
+ "--exclude-standard",
125
+ "-z",
126
+ "--",
127
+ scope,
128
+ ],
129
+ cwd=repository,
130
+ stdout=subprocess.PIPE,
131
+ stderr=subprocess.DEVNULL,
132
+ check=False,
133
+ )
134
+ except OSError:
135
+ tracked = None
136
+ if tracked is not None and tracked.returncode == 0:
137
+ prefix = b"./" if scope == "." or scope.startswith("./") else b""
138
+ for path in tracked.stdout.split(b"\0"):
139
+ candidate = repository / os.fsdecode(path)
140
+ if path and candidate.is_file() and not candidate.is_symlink():
141
+ inventory.write(prefix + path + b"\n")
142
+
123
143
  inventory.seek(0)
124
144
  rows = sorted(inventory)
125
145
 
@@ -299,11 +299,7 @@ def windows_stream_component(path: Path) -> str | None:
299
299
  if os.name != "nt":
300
300
  return None
301
301
  return next(
302
- (
303
- component
304
- for component in path.parts
305
- if component != path.anchor and ":" in component
306
- ),
302
+ (component for component in path.parts if component != path.anchor and ":" in component),
307
303
  None,
308
304
  )
309
305
 
@@ -42,6 +42,7 @@ TEXT_CODE_EXTENSIONS = {
42
42
  ".mm",
43
43
  ".php",
44
44
  ".proto",
45
+ ".ps1",
45
46
  ".py",
46
47
  ".rb",
47
48
  ".rs",