@openai/codex-security 0.1.21 → 0.1.23

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 (157) hide show
  1. package/README.md +529 -0
  2. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  3. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/references/config-preflight.md +2 -30
  6. package/_bundled_plugin/references/core-scan.md +1 -1
  7. package/_bundled_plugin/references/final-report.md +1 -1
  8. package/_bundled_plugin/references/finding-detail-fields.md +5 -10
  9. package/_bundled_plugin/references/sarif-adapter.md +1 -1
  10. package/_bundled_plugin/scripts/config_preflight.py +2 -8
  11. package/_bundled_plugin/scripts/finalize_scan_contract.py +114 -24
  12. package/_bundled_plugin/scripts/finding_preview.py +22 -4
  13. package/_bundled_plugin/scripts/generate_in_scope_files.py +27 -1
  14. package/_bundled_plugin/scripts/windows_scan_local_files.py +101 -7
  15. package/_bundled_plugin/scripts/workbench_cli.py +21 -1
  16. package/_bundled_plugin/scripts/workbench_dashboard.py +115 -0
  17. package/_bundled_plugin/scripts/workbench_db.py +29 -2
  18. package/_bundled_plugin/scripts/workbench_finding_index.py +42 -24
  19. package/_bundled_plugin/scripts/workbench_finding_workflows.py +190 -0
  20. package/_bundled_plugin/scripts/workbench_findings.py +216 -0
  21. package/_bundled_plugin/scripts/workbench_saved_results.py +30 -5
  22. package/_bundled_plugin/scripts/workbench_schema.py +263 -58
  23. package/_bundled_plugin/scripts/workbench_target.py +22 -3
  24. package/_bundled_plugin/skills/track-findings/SKILL.md +2 -0
  25. package/dist/api.d.ts +2 -0
  26. package/dist/api.d.ts.map +1 -1
  27. package/dist/api.js +115 -27
  28. package/dist/api.js.map +1 -1
  29. package/dist/cli.d.ts +4 -0
  30. package/dist/cli.d.ts.map +1 -1
  31. package/dist/cli.js +124 -58
  32. package/dist/cli.js.map +1 -1
  33. package/dist/cloud-publish.js +5 -1
  34. package/dist/cloud-publish.js.map +1 -1
  35. package/dist/contract.d.ts +1 -0
  36. package/dist/contract.d.ts.map +1 -1
  37. package/dist/contract.js +9 -0
  38. package/dist/contract.js.map +1 -1
  39. package/dist/custom-publish.d.ts +22 -0
  40. package/dist/custom-publish.d.ts.map +1 -0
  41. package/dist/custom-publish.js +47 -0
  42. package/dist/custom-publish.js.map +1 -0
  43. package/dist/custom-validation-prompt.js +1 -1
  44. package/dist/custom-validation-prompt.js.map +1 -1
  45. package/dist/deduplication/checkpointed-review.d.ts +16 -0
  46. package/dist/deduplication/checkpointed-review.d.ts.map +1 -0
  47. package/dist/deduplication/checkpointed-review.js +76 -0
  48. package/dist/deduplication/checkpointed-review.js.map +1 -0
  49. package/dist/deduplication/codex-review.d.ts +21 -0
  50. package/dist/deduplication/codex-review.d.ts.map +1 -0
  51. package/dist/deduplication/codex-review.js +252 -0
  52. package/dist/deduplication/codex-review.js.map +1 -0
  53. package/dist/deduplication/deduplication-prompts.d.ts +8 -0
  54. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -0
  55. package/dist/deduplication/deduplication-prompts.js +35 -0
  56. package/dist/deduplication/deduplication-prompts.js.map +1 -0
  57. package/dist/deduplication/deduplication-reviewer.d.ts +46 -0
  58. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -0
  59. package/dist/deduplication/deduplication-reviewer.js +105 -0
  60. package/dist/deduplication/deduplication-reviewer.js.map +1 -0
  61. package/dist/deduplication/deduplication.d.ts +6 -0
  62. package/dist/deduplication/deduplication.d.ts.map +1 -0
  63. package/dist/deduplication/deduplication.js +85 -0
  64. package/dist/deduplication/deduplication.js.map +1 -0
  65. package/dist/deduplication/scan.d.ts +16 -0
  66. package/dist/deduplication/scan.d.ts.map +1 -0
  67. package/dist/deduplication/scan.js +101 -0
  68. package/dist/deduplication/scan.js.map +1 -0
  69. package/dist/finding-dedupe-groups.d.ts +7 -0
  70. package/dist/finding-dedupe-groups.d.ts.map +1 -0
  71. package/dist/finding-dedupe-groups.js +2 -0
  72. package/dist/finding-dedupe-groups.js.map +1 -0
  73. package/dist/finding-retrieval.d.ts +13 -0
  74. package/dist/finding-retrieval.d.ts.map +1 -0
  75. package/dist/finding-retrieval.js +2 -0
  76. package/dist/finding-retrieval.js.map +1 -0
  77. package/dist/finding-workflow.d.ts +53 -0
  78. package/dist/finding-workflow.d.ts.map +1 -0
  79. package/dist/finding-workflow.js +117 -0
  80. package/dist/finding-workflow.js.map +1 -0
  81. package/dist/findings-client.d.ts +15 -0
  82. package/dist/findings-client.d.ts.map +1 -0
  83. package/dist/findings-client.js +60 -0
  84. package/dist/findings-client.js.map +1 -0
  85. package/dist/index.d.ts +4 -0
  86. package/dist/index.d.ts.map +1 -1
  87. package/dist/index.js +2 -0
  88. package/dist/index.js.map +1 -1
  89. package/dist/publication.js +28 -40
  90. package/dist/publication.js.map +1 -1
  91. package/dist/runtime.d.ts +5 -1
  92. package/dist/runtime.d.ts.map +1 -1
  93. package/dist/runtime.js +113 -12
  94. package/dist/runtime.js.map +1 -1
  95. package/dist/saved-scan.d.ts +15 -0
  96. package/dist/saved-scan.d.ts.map +1 -0
  97. package/dist/saved-scan.js +68 -0
  98. package/dist/saved-scan.js.map +1 -0
  99. package/dist/scan-comparison.d.ts +3 -2
  100. package/dist/scan-comparison.d.ts.map +1 -1
  101. package/dist/scan-comparison.js +1 -1
  102. package/dist/scan-comparison.js.map +1 -1
  103. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +276 -0
  104. package/dist/server/dashboard/app.css +2 -0
  105. package/dist/server/dashboard/app.js +66 -0
  106. package/dist/server/dashboard/index.html +18 -0
  107. package/dist/server/dashboard-types.d.ts +45 -0
  108. package/dist/server/dashboard-types.d.ts.map +1 -0
  109. package/dist/server/dashboard-types.js +2 -0
  110. package/dist/server/dashboard-types.js.map +1 -0
  111. package/dist/server/dashboard.d.ts +6 -0
  112. package/dist/server/dashboard.d.ts.map +1 -0
  113. package/dist/server/dashboard.js +45 -0
  114. package/dist/server/dashboard.js.map +1 -0
  115. package/dist/server/embeddings.d.ts +16 -0
  116. package/dist/server/embeddings.d.ts.map +1 -0
  117. package/dist/server/embeddings.js +114 -0
  118. package/dist/server/embeddings.js.map +1 -0
  119. package/dist/server/errors.d.ts +5 -0
  120. package/dist/server/errors.d.ts.map +1 -0
  121. package/dist/server/errors.js +8 -0
  122. package/dist/server/errors.js.map +1 -0
  123. package/dist/server/findings-service.d.ts +20 -0
  124. package/dist/server/findings-service.d.ts.map +1 -0
  125. package/dist/server/findings-service.js +31 -0
  126. package/dist/server/findings-service.js.map +1 -0
  127. package/dist/server/index.d.ts +2 -0
  128. package/dist/server/index.d.ts.map +1 -0
  129. package/dist/server/index.js +32 -0
  130. package/dist/server/index.js.map +1 -0
  131. package/dist/server/routes.d.ts +6 -0
  132. package/dist/server/routes.d.ts.map +1 -0
  133. package/dist/server/routes.js +86 -0
  134. package/dist/server/routes.js.map +1 -0
  135. package/dist/server/server.d.ts +10 -0
  136. package/dist/server/server.d.ts.map +1 -0
  137. package/dist/server/server.js +17 -0
  138. package/dist/server/server.js.map +1 -0
  139. package/dist/server/sqlite-store.d.ts +22 -0
  140. package/dist/server/sqlite-store.d.ts.map +1 -0
  141. package/dist/server/sqlite-store.js +82 -0
  142. package/dist/server/sqlite-store.js.map +1 -0
  143. package/dist/server/storage.d.ts +32 -0
  144. package/dist/server/storage.d.ts.map +1 -0
  145. package/dist/server/storage.js +2 -0
  146. package/dist/server/storage.js.map +1 -0
  147. package/dist/server/validation.d.ts +17 -0
  148. package/dist/server/validation.d.ts.map +1 -0
  149. package/dist/server/validation.js +53 -0
  150. package/dist/server/validation.js.map +1 -0
  151. package/dist/trusted-executable.d.ts.map +1 -1
  152. package/dist/trusted-executable.js +2 -1
  153. package/dist/trusted-executable.js.map +1 -1
  154. package/dist/version.d.ts +1 -1
  155. package/dist/version.js +1 -1
  156. package/dist/version.js.map +1 -1
  157. package/package.json +17 -5
@@ -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
 
@@ -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
 
@@ -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):
@@ -312,7 +320,7 @@ _WINDOWS_SCAN_LOCAL_FILES: Any | None = None
312
320
 
313
321
 
314
322
  def _windows_scan_local_files() -> Any:
315
- """Load the Win32 backend only on runtimes that need it."""
323
+ """Load the Win32 backend and shared stream comparison lazily."""
316
324
 
317
325
  global _WINDOWS_SCAN_LOCAL_FILES
318
326
  if _WINDOWS_SCAN_LOCAL_FILES is None:
@@ -326,24 +334,56 @@ def _windows_scan_local_files() -> Any:
326
334
  return _WINDOWS_SCAN_LOCAL_FILES
327
335
 
328
336
 
329
- def _open_verified_scan_directory(scan_dir: Path) -> int:
337
+ def _open_verified_scan_directory(
338
+ scan_dir: Path, expected_root_identity: tuple[int, int] | None = None
339
+ ) -> int:
330
340
  scan_dir = scan_dir.absolute()
331
341
  try:
332
342
  expected = scan_dir.lstat()
343
+ observed_identity = (expected.st_dev, expected.st_ino)
344
+ if (
345
+ expected_root_identity is not None
346
+ and observed_identity != expected_root_identity
347
+ ):
348
+ raise ContractError("scan directory: changed after artifact restoration setup")
333
349
  canonical = _require_scan_directory(scan_dir)
334
350
  descriptor = os.open(
335
351
  canonical,
336
352
  os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
337
353
  )
338
354
  except OSError as exc:
339
- raise ContractError("scan directory: expected an existing non-symlink directory") from exc
355
+ raise ContractError(
356
+ "scan directory: expected an existing non-symlink directory"
357
+ ) from exc
340
358
  opened = os.fstat(descriptor)
341
- if (opened.st_dev, opened.st_ino) != (expected.st_dev, expected.st_ino):
359
+ opened_identity = (opened.st_dev, opened.st_ino)
360
+ if opened_identity != observed_identity or (
361
+ expected_root_identity is not None
362
+ and opened_identity != expected_root_identity
363
+ ):
342
364
  os.close(descriptor)
343
365
  raise ContractError("scan directory: changed while it was being opened")
344
366
  return descriptor
345
367
 
346
368
 
369
+ def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
370
+ """Return a canonical scan root and its identity from a held handle."""
371
+
372
+ scan_dir = _require_scan_directory(scan_dir)
373
+ if not _descriptor_relative_writes_available():
374
+ if not _is_windows():
375
+ raise ContractError(
376
+ "scan-local output requires descriptor-relative file operations"
377
+ )
378
+ return _windows_scan_local_files().scan_root_identity(scan_dir)
379
+ descriptor = _open_verified_scan_directory(scan_dir)
380
+ try:
381
+ metadata = os.fstat(descriptor)
382
+ return scan_dir, (metadata.st_dev, metadata.st_ino)
383
+ finally:
384
+ os.close(descriptor)
385
+
386
+
347
387
  def _open_scan_local_directory(root_fd: int, parts: tuple[str, ...], *, create: bool) -> int:
348
388
  descriptor = os.dup(root_fd)
349
389
  try:
@@ -492,7 +532,12 @@ def _sha256_scan_local_file(scan_dir: Path, relative_path: str, context: str) ->
492
532
 
493
533
 
494
534
  def write_scan_local_bytes(
495
- scan_dir: Path, relative_path: str, payload: bytes, *, external_name: bool = False
535
+ scan_dir: Path,
536
+ relative_path: str,
537
+ payload: bytes,
538
+ *,
539
+ external_name: bool = False,
540
+ expected_root_identity: tuple[int, int] | None = None,
496
541
  ) -> None:
497
542
  scan_dir = _require_scan_directory(scan_dir)
498
543
  if external_name:
@@ -505,7 +550,12 @@ def write_scan_local_bytes(
505
550
  if not _is_windows():
506
551
  raise ContractError("scan-local output requires descriptor-relative file operations")
507
552
  try:
508
- _windows_scan_local_files().atomic_write(scan_dir, relative_path, payload)
553
+ _windows_scan_local_files().atomic_write(
554
+ scan_dir,
555
+ relative_path,
556
+ payload,
557
+ expected_root_identity=expected_root_identity,
558
+ )
509
559
  except OSError as exc:
510
560
  raise ContractError(f"{relative_path}: {exc}") from exc
511
561
  return
@@ -513,7 +563,7 @@ def write_scan_local_bytes(
513
563
  parent_fd: int | None = None
514
564
  temp_name: str | None = None
515
565
  try:
516
- root_fd = _open_verified_scan_directory(scan_dir)
566
+ root_fd = _open_verified_scan_directory(scan_dir, expected_root_identity)
517
567
  parts = PurePosixPath(relative_path).parts
518
568
  try:
519
569
  parent_fd = _open_scan_local_directory(root_fd, parts[:-1], create=True)
@@ -521,6 +571,9 @@ def write_scan_local_bytes(
521
571
  raise ContractError(
522
572
  f"{relative_path}: expected a path inside the scan directory"
523
573
  ) from exc
574
+ # The held descriptor is the authority for the validated parent. A
575
+ # concurrent rename cannot redirect later operations through a
576
+ # replacement path or link.
524
577
  try:
525
578
  metadata = os.stat(parts[-1], dir_fd=parent_fd, follow_symlinks=False)
526
579
  except FileNotFoundError:
@@ -528,6 +581,47 @@ def write_scan_local_bytes(
528
581
  else:
529
582
  if not stat.S_ISREG(metadata.st_mode):
530
583
  raise ContractError(f"{relative_path}: expected a regular non-symlink file")
584
+ try:
585
+ existing_fd = os.open(
586
+ parts[-1],
587
+ os.O_RDONLY
588
+ | getattr(os, "O_NOFOLLOW", 0)
589
+ | getattr(os, "O_NONBLOCK", 0),
590
+ dir_fd=parent_fd,
591
+ )
592
+ except OSError as exc:
593
+ if exc.errno not in {errno.ENOENT, errno.EACCES, errno.EPERM}:
594
+ raise
595
+ else:
596
+ try:
597
+ opened = os.fstat(existing_fd)
598
+ if not stat.S_ISREG(opened.st_mode):
599
+ raise ContractError(
600
+ f"{relative_path}: expected a regular non-symlink file"
601
+ )
602
+ if (opened.st_dev, opened.st_ino) != (
603
+ metadata.st_dev,
604
+ metadata.st_ino,
605
+ ):
606
+ raise ContractError(
607
+ f"{relative_path}: changed while it was being opened"
608
+ )
609
+ if (
610
+ expected_root_identity is not None
611
+ and opened.st_size == len(payload)
612
+ ):
613
+ try:
614
+ with os.fdopen(existing_fd, "rb") as handle:
615
+ existing_fd = -1
616
+ if _windows_scan_local_files().stream_matches_payload(
617
+ handle, payload
618
+ ):
619
+ return
620
+ except OSError:
621
+ pass
622
+ finally:
623
+ if existing_fd >= 0:
624
+ os.close(existing_fd)
531
625
  temp_name = f".{path.name}.{secrets.token_hex(8)}.tmp"
532
626
  temp_fd = os.open(temp_name, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=parent_fd)
533
627
  with os.fdopen(temp_fd, "wb") as handle:
@@ -2389,22 +2483,18 @@ def build_sarif_projection(
2389
2483
  raise ContractError("source root: expected an existing directory")
2390
2484
  manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
2391
2485
  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
2486
+ execution_successful = manifest["scan"]["status"] == "completed"
2487
+ if not execution_successful or coverage["completeness"] != "complete":
2488
+ run = sarif["runs"][0]
2489
+ run["properties"]["codexSecurityCoverageCompleteness"] = coverage["completeness"]
2490
+ run["invocations"] = [
2491
+ {
2492
+ "executionSuccessful": execution_successful,
2493
+ "toolExecutionNotifications": [
2494
+ {"level": "warning", "message": {"text": item["reason"]}}
2495
+ for item in coverage["deferred"]
2496
+ ],
2497
+ }
2408
2498
  ]
2409
2499
  _validate_sarif(sarif)
2410
2500
  return sarif
@@ -2746,7 +2836,7 @@ def _prepare_scan_finalization(
2746
2836
  _validate_sealed_coverage_receipts(scan, coverage)
2747
2837
  _validate_manifest(manifest)
2748
2838
  validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
2749
- validate_against_schema(findings, schema_dir / "findings.schema.json")
2839
+ validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
2750
2840
  validate_against_schema(coverage, schema_dir / "coverage.schema.json")
2751
2841
  _contract_json_bytes("scan-manifest.json", manifest)
2752
2842
  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
@@ -93,7 +93,6 @@ def generate_in_scope_files(repository: Path, scope: str, output: Path) -> int:
93
93
  "rg",
94
94
  "--files",
95
95
  "--hidden",
96
- "--no-ignore",
97
96
  "--path-separator",
98
97
  "/",
99
98
  "--glob",
@@ -120,6 +119,33 @@ def generate_in_scope_files(repository: Path, scope: str, output: Path) -> int:
120
119
  message = f"{message}: {detail}"
121
120
  raise InventoryError(message)
122
121
 
122
+ if (repository / ".git").exists():
123
+ try:
124
+ tracked = subprocess.run(
125
+ [
126
+ "git",
127
+ "ls-files",
128
+ "--cached",
129
+ "--ignored",
130
+ "--exclude-standard",
131
+ "-z",
132
+ "--",
133
+ scope,
134
+ ],
135
+ cwd=repository,
136
+ stdout=subprocess.PIPE,
137
+ stderr=subprocess.DEVNULL,
138
+ check=False,
139
+ )
140
+ except OSError:
141
+ tracked = None
142
+ if tracked is not None and tracked.returncode == 0:
143
+ prefix = b"./" if scope == "." or scope.startswith("./") else b""
144
+ for path in tracked.stdout.split(b"\0"):
145
+ candidate = repository / os.fsdecode(path)
146
+ if path and candidate.is_file() and not candidate.is_symlink():
147
+ inventory.write(prefix + path + b"\n")
148
+
123
149
  inventory.seek(0)
124
150
  rows = sorted(inventory)
125
151
 
@@ -11,8 +11,8 @@ already-validated ancestor from being renamed or replaced during a read,
11
11
  write, or delete. Writes rename the exact temporary-file handle into place so
12
12
  an attacker cannot substitute another file at the temporary name.
13
13
 
14
- Importing this module is safe on non-Windows hosts. Its public operations
15
- raise ``WindowsScanLocalFileError`` when called anywhere other than Windows.
14
+ Importing this module and comparing streams work on every platform. Filesystem
15
+ operations raise ``WindowsScanLocalFileError`` outside Windows.
16
16
  """
17
17
 
18
18
  from __future__ import annotations
@@ -28,6 +28,7 @@ import secrets
28
28
  from collections.abc import Iterator
29
29
  from ctypes import wintypes
30
30
  from pathlib import Path, PurePosixPath
31
+ from typing import BinaryIO
31
32
 
32
33
  _msvcrt = importlib.import_module("msvcrt") if os.name == "nt" else None
33
34
 
@@ -63,11 +64,15 @@ _FILE_TYPE_DISK = 0x0001
63
64
  _FILE_NAME_OPENED = 0x00000008
64
65
  _ERROR_FILE_NOT_FOUND = 2
65
66
  _ERROR_PATH_NOT_FOUND = 3
67
+ _ERROR_ACCESS_DENIED = 5
68
+ _ERROR_SHARING_VIOLATION = 32
69
+ _ERROR_LOCK_VIOLATION = 33
66
70
  _ERROR_FILE_EXISTS = 80
67
71
  _ERROR_ALREADY_EXISTS = 183
68
72
  _MISSING_ERRORS = {_ERROR_FILE_NOT_FOUND, _ERROR_PATH_NOT_FOUND}
69
73
  _COLLISION_ERRORS = {_ERROR_FILE_EXISTS, _ERROR_ALREADY_EXISTS}
70
74
  _INVALID_HANDLE_VALUE = ctypes.c_void_p(-1).value
75
+ _MAX_COMPARE_CHUNK = 64 * 1024
71
76
  _MAX_WRITE_CHUNK = 1024 * 1024
72
77
 
73
78
  _INVALID_COMPONENT_CHARACTERS = frozenset('<>:"|?*')
@@ -398,12 +403,20 @@ def _locked_parent(
398
403
  relative_path: str,
399
404
  *,
400
405
  create: bool,
406
+ expected_root_identity: tuple[int, int] | None = None,
401
407
  ) -> Iterator[tuple[Path, str]]:
402
408
  """Hold non-deletable handles for every directory in the absolute target path."""
403
409
 
404
410
  _require_windows()
405
411
  parts = _validated_parts(relative_path)
406
- root_path, expected_root_identity = _canonical_scan_directory(scan_dir)
412
+ root_path, observed_root_identity = _canonical_scan_directory(scan_dir)
413
+ if (
414
+ expected_root_identity is not None
415
+ and observed_root_identity != expected_root_identity
416
+ ):
417
+ raise _invalid_path(
418
+ scan_dir, "scan directory changed after artifact restoration setup"
419
+ )
407
420
  handles: list[_OwnedHandle] = []
408
421
  try:
409
422
  # Absolute-path Win32 calls remain safe only while every ancestor is
@@ -414,8 +427,14 @@ def _locked_parent(
414
427
  assert directory_handle is not None
415
428
  handles.append(directory_handle)
416
429
  current_root = root_path.lstat()
417
- if (current_root.st_dev, current_root.st_ino) != expected_root_identity:
418
- raise _invalid_path(scan_dir, "scan directory changed while it was being opened")
430
+ current_root_identity = (current_root.st_dev, current_root.st_ino)
431
+ if current_root_identity != observed_root_identity or (
432
+ expected_root_identity is not None
433
+ and current_root_identity != expected_root_identity
434
+ ):
435
+ raise _invalid_path(
436
+ scan_dir, "scan directory changed while it was being opened"
437
+ )
419
438
  current_path = root_path
420
439
  for component in parts[:-1]:
421
440
  current_path /= component
@@ -431,6 +450,14 @@ def _locked_parent(
431
450
  handle.close()
432
451
 
433
452
 
453
+ def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
454
+ """Return a canonical scan root and its identity while holding it fixed."""
455
+
456
+ with _locked_parent(scan_dir, ".identity", create=False) as (root_path, _):
457
+ metadata = root_path.lstat()
458
+ return root_path, (metadata.st_dev, metadata.st_ino)
459
+
460
+
434
461
  def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
435
462
  """Open a verified regular file and return an owned binary read descriptor."""
436
463
 
@@ -465,6 +492,16 @@ def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
465
492
  ) from exc
466
493
 
467
494
 
495
+ def stream_matches_payload(stream: BinaryIO, payload: bytes) -> bool:
496
+ offset = 0
497
+ while offset < len(payload):
498
+ chunk = stream.read(min(_MAX_COMPARE_CHUNK, len(payload) - offset))
499
+ if not chunk or chunk != payload[offset : offset + len(chunk)]:
500
+ return False
501
+ offset += len(chunk)
502
+ return stream.read(1) == b""
503
+
504
+
468
505
  def _write_all(handle: int, payload: bytes) -> None:
469
506
  view = memoryview(payload)
470
507
  offset = 0
@@ -532,12 +569,69 @@ def _validate_existing_output(path: Path) -> None:
532
569
  _verify_regular_file(handle.value, path)
533
570
 
534
571
 
535
- def atomic_write(scan_dir: Path, relative_path: str, payload: bytes) -> None:
572
+ def _existing_output_matches(path: Path, payload: bytes) -> bool:
573
+ try:
574
+ handle = _create_file(
575
+ path,
576
+ access=_GENERIC_READ | _FILE_READ_ATTRIBUTES,
577
+ # Deny write and delete sharing while comparing the opened contents.
578
+ share=_FILE_SHARE_READ,
579
+ disposition=_OPEN_EXISTING,
580
+ flags=_FILE_FLAG_OPEN_REPARSE_POINT | _FILE_FLAG_BACKUP_SEMANTICS,
581
+ missing_ok=True,
582
+ )
583
+ except WindowsScanLocalFileError as exc:
584
+ if exc.errno in {
585
+ _ERROR_ACCESS_DENIED,
586
+ _ERROR_SHARING_VIOLATION,
587
+ _ERROR_LOCK_VIOLATION,
588
+ }:
589
+ return False
590
+ raise
591
+ if handle is None:
592
+ return False
593
+ with handle:
594
+ assert handle.value is not None
595
+ _verify_regular_file(handle.value, path)
596
+ raw_handle = handle.detach()
597
+ try:
598
+ assert _msvcrt is not None
599
+ descriptor = _msvcrt.open_osfhandle(
600
+ raw_handle, os.O_RDONLY | os.O_BINARY
601
+ )
602
+ except BaseException:
603
+ _close_handle(raw_handle)
604
+ raise
605
+ try:
606
+ with os.fdopen(descriptor, "rb") as stream:
607
+ if os.fstat(stream.fileno()).st_size != len(payload):
608
+ return False
609
+ return stream_matches_payload(stream, payload)
610
+ except OSError:
611
+ return False
612
+
613
+
614
+ def atomic_write(
615
+ scan_dir: Path,
616
+ relative_path: str,
617
+ payload: bytes,
618
+ *,
619
+ expected_root_identity: tuple[int, int] | None = None,
620
+ ) -> None:
536
621
  """Atomically replace a scan-local regular file with ``payload``."""
537
622
 
538
- with _locked_parent(scan_dir, relative_path, create=True) as (parent_path, leaf_name):
623
+ with _locked_parent(
624
+ scan_dir,
625
+ relative_path,
626
+ create=True,
627
+ expected_root_identity=expected_root_identity,
628
+ ) as (parent_path, leaf_name):
539
629
  destination_path = parent_path / leaf_name
540
630
  _validate_existing_output(destination_path)
631
+ if expected_root_identity is not None and _existing_output_matches(
632
+ destination_path, payload
633
+ ):
634
+ return
541
635
 
542
636
  temp_handle: _OwnedHandle | None = None
543
637
  temp_path: Path | None = None
@@ -339,7 +339,27 @@ def parse_args(description: str) -> argparse.Namespace:
339
339
  publication.add_argument("--input-file", required=True)
340
340
 
341
341
  subparsers.add_parser("database-info")
342
- return parser.parse_args()
342
+ subparsers.add_parser("dashboard")
343
+ subparsers.add_parser("finding-workflow")
344
+ subparsers.add_parser("store-findings")
345
+ subparsers.add_parser("store-dedupe-groups")
346
+ dedupe_groups = subparsers.add_parser("list-dedupe-groups")
347
+ dedupe_groups.add_argument("--finding-id", required=True)
348
+ potential_duplicates = subparsers.add_parser("find-potential-duplicates")
349
+ potential_duplicates.add_argument("--finding-id", required=True)
350
+ scope = potential_duplicates.add_mutually_exclusive_group(required=True)
351
+ scope.add_argument("--repository-id")
352
+ scope.add_argument("--all-repositories", action="store_true")
353
+ stored_findings = subparsers.add_parser("list-stored-findings")
354
+ stored_findings.add_argument("--limit", type=positive_int, required=True)
355
+ stored_findings.add_argument("--offset", type=non_negative_int, required=True)
356
+ arguments = sys.argv[1:]
357
+ if "--user-context-stdin" in arguments:
358
+ if arguments.count("--user-context-stdin") != 1 or "--user-context" in arguments:
359
+ parser.error("pass exactly one user-context transport")
360
+ index = arguments.index("--user-context-stdin")
361
+ arguments[index] = "--user-context=" + sys.stdin.buffer.read().decode("utf-8")
362
+ return parser.parse_args(arguments)
343
363
 
344
364
 
345
365
  def non_negative_int(value: str) -> int: