@openai/codex-security 0.1.23 → 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 (56) hide show
  1. package/README.md +24 -5
  2. package/_bundled_plugin/.mcp.json +1 -0
  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/scan-contract.md +10 -0
  6. package/_bundled_plugin/scripts/deep_scan_workbench.py +6 -1
  7. package/_bundled_plugin/scripts/finalize_scan_contract.py +27 -78
  8. package/_bundled_plugin/scripts/generate_in_scope_files.py +2 -8
  9. package/_bundled_plugin/scripts/generate_rank_input.py +1 -5
  10. package/_bundled_plugin/scripts/rank_preview.py +1 -0
  11. package/_bundled_plugin/scripts/report_projection.py +8 -14
  12. package/_bundled_plugin/scripts/validate_scan_contract.py +1 -3
  13. package/_bundled_plugin/scripts/windows_scan_local_files.py +5 -15
  14. package/_bundled_plugin/scripts/workbench_cli.py +6 -0
  15. package/_bundled_plugin/scripts/workbench_dashboard.py +41 -18
  16. package/_bundled_plugin/scripts/workbench_db.py +83 -539
  17. package/_bundled_plugin/scripts/workbench_finding_workflows.py +31 -13
  18. package/_bundled_plugin/scripts/workbench_findings.py +8 -3
  19. package/_bundled_plugin/scripts/workbench_native_indexes.py +1 -2
  20. package/_bundled_plugin/scripts/workbench_publication.py +520 -0
  21. package/_bundled_plugin/scripts/workbench_remediation.py +37 -0
  22. package/_bundled_plugin/scripts/workbench_saved_results.py +298 -90
  23. package/_bundled_plugin/scripts/workbench_scan_history.py +1 -2
  24. package/_bundled_plugin/scripts/workbench_scan_usage.py +9 -33
  25. package/_bundled_plugin/scripts/workbench_schema.py +34 -21
  26. package/_bundled_plugin/scripts/workbench_target.py +10 -5
  27. package/_bundled_plugin/scripts/workbench_validation.py +1 -5
  28. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +1 -5
  29. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +6 -1
  30. package/dist/api.d.ts +3 -1
  31. package/dist/api.d.ts.map +1 -1
  32. package/dist/api.js +20 -0
  33. package/dist/api.js.map +1 -1
  34. package/dist/cli.d.ts.map +1 -1
  35. package/dist/cli.js +34 -4
  36. package/dist/cli.js.map +1 -1
  37. package/dist/deep-progress.d.ts +21 -0
  38. package/dist/deep-progress.d.ts.map +1 -0
  39. package/dist/deep-progress.js +108 -0
  40. package/dist/deep-progress.js.map +1 -0
  41. package/dist/index.d.ts +1 -0
  42. package/dist/index.d.ts.map +1 -1
  43. package/dist/index.js.map +1 -1
  44. package/dist/runtime.d.ts.map +1 -1
  45. package/dist/runtime.js +6 -1
  46. package/dist/runtime.js.map +1 -1
  47. package/dist/scan-activity.d.ts.map +1 -1
  48. package/dist/scan-activity.js +12 -2
  49. package/dist/scan-activity.js.map +1 -1
  50. package/dist/server/index.js +2 -28
  51. package/dist/server/index.js.map +1 -1
  52. package/dist/server/serve.d.ts +2 -0
  53. package/dist/server/serve.d.ts.map +1 -0
  54. package/dist/server/serve.js +28 -0
  55. package/dist/server/serve.js.map +1 -0
  56. package/package.json +3 -3
package/README.md CHANGED
@@ -152,7 +152,10 @@ Options for `security.run(repository, options)` and
152
152
  | `signal` | `AbortSignal` to cancel a scan. |
153
153
 
154
154
  Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receives
155
- saved events with thread IDs and worker numbers; `ScanOptions` lists all callbacks.
155
+ saved events with thread IDs and worker numbers. Deep scans can additionally use
156
+ `onDeepProgress` for durable independent-review counts: `completed`, `active`,
157
+ and `maximum`. The maximum is a configured cap, not a percentage denominator.
158
+ `ScanOptions` lists all callbacks.
156
159
 
157
160
  `preflight` and CLI `--dry-run` check local inputs without starting Codex or
158
161
  using the network. They don't authenticate, verify model access, resolve Python,
@@ -1402,16 +1405,32 @@ migrated database.
1402
1405
 
1403
1406
  ### Running without Docker
1404
1407
 
1405
- To run locally, use Node.js and Python 3 as described in the prerequisites.
1406
- Export the API key in your shell; the server does not load `.env` automatically.
1407
- From `sdk/typescript`, install dependencies, build, and start:
1408
+ With Node.js and Python 3 installed:
1409
+
1410
+ ```bash
1411
+ npm install -g @openai/codex-security
1412
+ CODEX_SECURITY_STATE_DIR="$HOME/.codex-security-findings" codex-security serve --port 3000
1413
+ ```
1414
+
1415
+ `--port` overrides `PORT` (default: `3000`). Open
1416
+ `http://127.0.0.1:3000/dashboard`. Stop with Ctrl+C or SIGTERM.
1417
+
1418
+ Export `OPENAI_API_KEY` or `CODEX_API_KEY` to import findings with embeddings.
1419
+ Startup and listing need no key. The service does not load `.env` or authenticate
1420
+ requests; keep it on loopback or behind an authenticated TLS proxy.
1421
+
1422
+ From a source checkout's `sdk/typescript` directory:
1408
1423
 
1409
1424
  ```bash
1410
1425
  pnpm install --frozen-lockfile
1426
+ npm ci --prefix ../../plugins/codex-security/mcp-app
1427
+ pnpm run build:plugin
1411
1428
  pnpm run build
1412
- pnpm run start:server
1429
+ node bin/codex-security.mjs serve --port 3000
1413
1430
  ```
1414
1431
 
1432
+ `pnpm run start:server` and `node dist/server/index.js` still work.
1433
+
1415
1434
  Local defaults are `HOST=127.0.0.1` and `PORT=3000`. The existing
1416
1435
  `CODEX_SECURITY_STATE_DIR` and `PYTHON` settings select storage and Python;
1417
1436
  without a state override, the service uses the same default state directory as
@@ -14,6 +14,7 @@
14
14
  "CODEX_ELECTRON_RESOURCES_PATH",
15
15
  "CODEX_MANAGED_PACKAGE_ROOT",
16
16
  "CODEX_MCP_NODE_PATH",
17
+ "OPENAI_API_KEY",
17
18
  "OPENROUTER_API_KEY",
18
19
  "FIREWORKS_API_KEY",
19
20
  "AWS_BEARER_TOKEN_BEDROCK",
@@ -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:
@@ -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
  }
@@ -250,9 +250,7 @@ def _require_safe_relative_path(value: str, context: str, *, allow_dot: bool = F
250
250
  return normalized
251
251
 
252
252
 
253
- def _require_portable_relative_path(
254
- value: str, context: str, *, allow_dot: bool = False
255
- ) -> str:
253
+ def _require_portable_relative_path(value: str, context: str, *, allow_dot: bool = False) -> str:
256
254
  normalized = _require_safe_relative_path(value, context, allow_dot=allow_dot)
257
255
  if any(_windows_unsafe_path_component(part) for part in value.split("/")):
258
256
  raise ContractError(f"{context}: expected a safe scan-relative POSIX path")
@@ -288,10 +286,7 @@ def _validate_scan_local_output_path(scan_dir: Path, path: Path, relative_path:
288
286
  resolved_parent.relative_to(scan_dir)
289
287
  except (OSError, RuntimeError, ValueError) as exc:
290
288
  raise ContractError(f"{relative_path}: expected a path inside the scan directory") from exc
291
- if (
292
- os.path.normcase(resolved_parent) != os.path.normcase(path.parent)
293
- or path.is_symlink()
294
- ):
289
+ if os.path.normcase(resolved_parent) != os.path.normcase(path.parent) or path.is_symlink():
295
290
  raise ContractError(
296
291
  f"{relative_path}: expected a non-symlink path inside the scan directory"
297
292
  )
@@ -341,10 +336,7 @@ def _open_verified_scan_directory(
341
336
  try:
342
337
  expected = scan_dir.lstat()
343
338
  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
- ):
339
+ if expected_root_identity is not None and observed_identity != expected_root_identity:
348
340
  raise ContractError("scan directory: changed after artifact restoration setup")
349
341
  canonical = _require_scan_directory(scan_dir)
350
342
  descriptor = os.open(
@@ -352,14 +344,11 @@ def _open_verified_scan_directory(
352
344
  os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
353
345
  )
354
346
  except OSError as exc:
355
- raise ContractError(
356
- "scan directory: expected an existing non-symlink directory"
357
- ) from exc
347
+ raise ContractError("scan directory: expected an existing non-symlink directory") from exc
358
348
  opened = os.fstat(descriptor)
359
349
  opened_identity = (opened.st_dev, opened.st_ino)
360
350
  if opened_identity != observed_identity or (
361
- expected_root_identity is not None
362
- and opened_identity != expected_root_identity
351
+ expected_root_identity is not None and opened_identity != expected_root_identity
363
352
  ):
364
353
  os.close(descriptor)
365
354
  raise ContractError("scan directory: changed while it was being opened")
@@ -372,9 +361,7 @@ def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
372
361
  scan_dir = _require_scan_directory(scan_dir)
373
362
  if not _descriptor_relative_writes_available():
374
363
  if not _is_windows():
375
- raise ContractError(
376
- "scan-local output requires descriptor-relative file operations"
377
- )
364
+ raise ContractError("scan-local output requires descriptor-relative file operations")
378
365
  return _windows_scan_local_files().scan_root_identity(scan_dir)
379
366
  descriptor = _open_verified_scan_directory(scan_dir)
380
367
  try:
@@ -584,9 +571,7 @@ def write_scan_local_bytes(
584
571
  try:
585
572
  existing_fd = os.open(
586
573
  parts[-1],
587
- os.O_RDONLY
588
- | getattr(os, "O_NOFOLLOW", 0)
589
- | getattr(os, "O_NONBLOCK", 0),
574
+ os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0),
590
575
  dir_fd=parent_fd,
591
576
  )
592
577
  except OSError as exc:
@@ -596,20 +581,13 @@ def write_scan_local_bytes(
596
581
  try:
597
582
  opened = os.fstat(existing_fd)
598
583
  if not stat.S_ISREG(opened.st_mode):
599
- raise ContractError(
600
- f"{relative_path}: expected a regular non-symlink file"
601
- )
584
+ raise ContractError(f"{relative_path}: expected a regular non-symlink file")
602
585
  if (opened.st_dev, opened.st_ino) != (
603
586
  metadata.st_dev,
604
587
  metadata.st_ino,
605
588
  ):
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
- ):
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):
613
591
  try:
614
592
  with os.fdopen(existing_fd, "rb") as handle:
615
593
  existing_fd = -1
@@ -857,9 +835,9 @@ def _recover_unsealed_findings(
857
835
  try:
858
836
  if not isinstance(finding, dict):
859
837
  raise ContractError(f"{context}: expected an object")
860
- compatible_findings = _legacy_sealed_findings_for_validation(
861
- {"findings": [finding]}
862
- )["findings"]
838
+ compatible_findings = _legacy_sealed_findings_for_validation({"findings": [finding]})[
839
+ "findings"
840
+ ]
863
841
  compatible_finding = compatible_findings[0]
864
842
  normalized_legacy_details = compatible_finding != finding
865
843
  finding = compatible_finding
@@ -870,9 +848,7 @@ def _recover_unsealed_findings(
870
848
  ]
871
849
  if "instance" in identity:
872
850
  fields.append((identity, "instance", f"{context}.identity", "instance"))
873
- normalized_fields = (
874
- ["legacy finding details"] if normalized_legacy_details else []
875
- )
851
+ normalized_fields = ["legacy finding details"] if normalized_legacy_details else []
876
852
  for parent, field, field_context, label in fields:
877
853
  value = _require_str(parent, field, field_context)
878
854
  if SLUG_RE.fullmatch(value):
@@ -1649,10 +1625,7 @@ def _validate_schema_node(
1649
1625
  raise ContractError(f"{context}: array has too many items")
1650
1626
  if schema.get("uniqueItems") is True:
1651
1627
  for index, item in enumerate(value):
1652
- if any(
1653
- _schema_values_equal(item, candidate)
1654
- for candidate in value[:index]
1655
- ):
1628
+ if any(_schema_values_equal(item, candidate) for candidate in value[:index]):
1656
1629
  raise ContractError(f"{context}: array items must be unique")
1657
1630
  contains = schema.get("contains")
1658
1631
  if isinstance(contains, dict):
@@ -1671,9 +1644,7 @@ def _validate_schema_node(
1671
1644
  item_schema = schema.get("items")
1672
1645
  if isinstance(item_schema, dict):
1673
1646
  for index, item in enumerate(value):
1674
- _validate_schema_node(
1675
- item, item_schema, f"{context}[{index}]", root_schema
1676
- )
1647
+ _validate_schema_node(item, item_schema, f"{context}[{index}]", root_schema)
1677
1648
  if isinstance(value, dict):
1678
1649
  for item_schema in schema.get("allOf", []):
1679
1650
  _validate_schema_node(value, item_schema, context, root_schema)
@@ -1697,9 +1668,7 @@ def _validate_schema_node(
1697
1668
  for key, item in value.items():
1698
1669
  item_schema = properties.get(key)
1699
1670
  if isinstance(item_schema, dict):
1700
- _validate_schema_node(
1701
- item, item_schema, f"{context}.{key}", root_schema
1702
- )
1671
+ _validate_schema_node(item, item_schema, f"{context}.{key}", root_schema)
1703
1672
  elif additional_properties is False:
1704
1673
  raise ContractError(f"{context}.{key}: unexpected schema property")
1705
1674
  elif isinstance(additional_properties, dict):
@@ -1716,22 +1685,16 @@ def validate_against_schema(payload: dict[str, Any], schema_path: Path) -> None:
1716
1685
  _validate_schema_node(payload, schema, schema_path.stem, schema)
1717
1686
 
1718
1687
 
1719
- def _filter_unknown_legacy_evidence_refs(
1720
- section: dict[str, Any], evidence_ids: set[str]
1721
- ) -> None:
1688
+ def _filter_unknown_legacy_evidence_refs(section: dict[str, Any], evidence_ids: set[str]) -> None:
1722
1689
  for refs_field in ("evidenceRefs", "evidence_refs"):
1723
1690
  refs = section.get(refs_field)
1724
1691
  if isinstance(refs, list):
1725
1692
  section[refs_field] = [
1726
- ref
1727
- for ref in refs
1728
- 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
1729
1694
  ]
1730
1695
 
1731
1696
 
1732
- def _normalize_legacy_string_list_fields(
1733
- section: dict[str, Any], fields: tuple[str, ...]
1734
- ) -> None:
1697
+ def _normalize_legacy_string_list_fields(section: dict[str, Any], fields: tuple[str, ...]) -> None:
1735
1698
  for field in fields:
1736
1699
  if field not in section:
1737
1700
  continue
@@ -1739,9 +1702,7 @@ def _normalize_legacy_string_list_fields(
1739
1702
  if isinstance(value, str):
1740
1703
  normalized = [value] if value.strip() else []
1741
1704
  elif isinstance(value, list):
1742
- normalized = [
1743
- item for item in value if isinstance(item, str) and item.strip()
1744
- ]
1705
+ normalized = [item for item in value if isinstance(item, str) and item.strip()]
1745
1706
  else:
1746
1707
  normalized = []
1747
1708
  if normalized:
@@ -1754,9 +1715,7 @@ def _remove_unsupported_legacy_scalar_fields(
1754
1715
  section: dict[str, Any], fields: tuple[str, ...]
1755
1716
  ) -> None:
1756
1717
  for field in fields:
1757
- if field in section and (
1758
- not isinstance(section[field], str) or section[field] == ""
1759
- ):
1718
+ if field in section and (not isinstance(section[field], str) or section[field] == ""):
1760
1719
  section.pop(field)
1761
1720
 
1762
1721
 
@@ -1773,9 +1732,7 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1773
1732
  canonical_evidence_ids = {
1774
1733
  evidence["id"]
1775
1734
  for evidence in canonical_evidence
1776
- if isinstance(evidence, dict)
1777
- and isinstance(evidence.get("id"), str)
1778
- and evidence["id"]
1735
+ if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
1779
1736
  }
1780
1737
  legacy_evidence = finding.get("code_evidence")
1781
1738
  if isinstance(legacy_evidence, list):
@@ -1807,9 +1764,7 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1807
1764
  evidence_ids = canonical_evidence_ids | {
1808
1765
  evidence["id"]
1809
1766
  for evidence in compatible_legacy_evidence
1810
- if isinstance(evidence, dict)
1811
- and isinstance(evidence.get("id"), str)
1812
- and evidence["id"]
1767
+ if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
1813
1768
  }
1814
1769
  for section_name, list_fields in (
1815
1770
  ("rootCause", ("evidenceRefs", "evidence_refs")),
@@ -1891,12 +1846,8 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1891
1846
  for field in ("impact", "likelihood"):
1892
1847
  detail = attack_path.get(field)
1893
1848
  if isinstance(detail, dict):
1894
- _remove_unsupported_legacy_scalar_fields(
1895
- detail, ("level", "rationale", "why")
1896
- )
1897
- elif detail is not None and (
1898
- not isinstance(detail, str) or detail == ""
1899
- ):
1849
+ _remove_unsupported_legacy_scalar_fields(detail, ("level", "rationale", "why"))
1850
+ elif detail is not None and (not isinstance(detail, str) or detail == ""):
1900
1851
  attack_path.pop(field)
1901
1852
  return compatible
1902
1853
 
@@ -2805,9 +2756,7 @@ def _prepare_scan_finalization(
2805
2756
  _validate_sealed_coverage_receipts(scan, coverage)
2806
2757
  _validate_manifest(manifest)
2807
2758
  validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
2808
- validate_against_schema(
2809
- findings_for_validation, schema_dir / "findings.schema.json"
2810
- )
2759
+ validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
2811
2760
  validate_against_schema(coverage, schema_dir / "coverage.schema.json")
2812
2761
  report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
2813
2762
  _validate_report_output_paths(scan_dir)
@@ -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)
@@ -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",
@@ -333,13 +333,13 @@ def merged_root_cause(value: dict[str, Any]) -> tuple[str | None, Any]:
333
333
  "language",
334
334
  ):
335
335
  continue
336
- if field in text_fields and (
337
- not isinstance(item, str) or not item.strip()
338
- ):
336
+ if field in text_fields and (not isinstance(item, str) or not item.strip()):
339
337
  continue
340
338
  current = merged.get(field)
341
- if field not in merged or current in (None, "", [], {}) or (
342
- isinstance(current, str) and not current.strip()
339
+ if (
340
+ field not in merged
341
+ or current in (None, "", [], {})
342
+ or (isinstance(current, str) and not current.strip())
343
343
  ):
344
344
  merged[field] = item
345
345
 
@@ -363,9 +363,7 @@ def merged_root_cause(value: dict[str, Any]) -> tuple[str | None, Any]:
363
363
  item
364
364
  for detail in details
365
365
  for field in ("codeEvidence", "code_evidence")
366
- for item in (
367
- detail.get(field, []) if isinstance(detail.get(field), list) else []
368
- )
366
+ for item in (detail.get(field, []) if isinstance(detail.get(field), list) else [])
369
367
  ]
370
368
  if embedded_evidence:
371
369
  merged["codeEvidence"] = embedded_evidence
@@ -541,9 +539,7 @@ def _finding_section(number: int, finding: dict[str, Any]) -> list[str]:
541
539
  (
542
540
  section[key]
543
541
  for section in dataflow_sections
544
- if key in section
545
- and isinstance(section[key], str)
546
- and section[key].strip()
542
+ if key in section and isinstance(section[key], str) and section[key].strip()
547
543
  ),
548
544
  None,
549
545
  )
@@ -652,9 +648,7 @@ def _finding_section(number: int, finding: dict[str, Any]) -> list[str]:
652
648
  if validation.get("method"):
653
649
  lines.extend(["", f"Validation method: {_text(validation['method'], 'not recorded')}"])
654
650
  if validation_outcomes:
655
- lines.extend(
656
- ["", *(f"- **{label}:** {value}" for label, value in validation_outcomes)]
657
- )
651
+ lines.extend(["", *(f"- **{label}:** {value}" for label, value in validation_outcomes)])
658
652
  lines.extend(_code_evidence_lines(validation_code_evidence))
659
653
  if validation_assertions:
660
654
  lines.extend(["", "Assertions:", *_bullets(validation_assertions, "None recorded.")])
@@ -64,9 +64,7 @@ def validate_contract(scan_dir: Path) -> dict[str, Any]:
64
64
  FINALIZER._validate_derived_finding_identities(manifest, findings)
65
65
  FINALIZER._validate_coverage(manifest, coverage, scan_dir)
66
66
  FINALIZER._validate_sealed_coverage_receipts(scan, coverage)
67
- FINALIZER.validate_against_schema(
68
- findings_for_validation, schema_dir / "findings.schema.json"
69
- )
67
+ FINALIZER.validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
70
68
  FINALIZER.validate_against_schema(coverage, schema_dir / "coverage.schema.json")
71
69
  FINALIZER._require_scan_local_file(scan_dir, "report.md", "report.md")
72
70
  return {
@@ -410,13 +410,8 @@ def _locked_parent(
410
410
  _require_windows()
411
411
  parts = _validated_parts(relative_path)
412
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
- )
413
+ if expected_root_identity is not None and observed_root_identity != expected_root_identity:
414
+ raise _invalid_path(scan_dir, "scan directory changed after artifact restoration setup")
420
415
  handles: list[_OwnedHandle] = []
421
416
  try:
422
417
  # Absolute-path Win32 calls remain safe only while every ancestor is
@@ -429,12 +424,9 @@ def _locked_parent(
429
424
  current_root = root_path.lstat()
430
425
  current_root_identity = (current_root.st_dev, current_root.st_ino)
431
426
  if current_root_identity != observed_root_identity or (
432
- expected_root_identity is not None
433
- and current_root_identity != expected_root_identity
427
+ expected_root_identity is not None and current_root_identity != expected_root_identity
434
428
  ):
435
- raise _invalid_path(
436
- scan_dir, "scan directory changed while it was being opened"
437
- )
429
+ raise _invalid_path(scan_dir, "scan directory changed while it was being opened")
438
430
  current_path = root_path
439
431
  for component in parts[:-1]:
440
432
  current_path /= component
@@ -596,9 +588,7 @@ def _existing_output_matches(path: Path, payload: bytes) -> bool:
596
588
  raw_handle = handle.detach()
597
589
  try:
598
590
  assert _msvcrt is not None
599
- descriptor = _msvcrt.open_osfhandle(
600
- raw_handle, os.O_RDONLY | os.O_BINARY
601
- )
591
+ descriptor = _msvcrt.open_osfhandle(raw_handle, os.O_RDONLY | os.O_BINARY)
602
592
  except BaseException:
603
593
  _close_handle(raw_handle)
604
594
  raise
@@ -247,6 +247,12 @@ def parse_args(description: str) -> argparse.Namespace:
247
247
  preserve_scan.add_argument("--claim-token")
248
248
  preserve_scan.add_argument("--coordinator-generation", type=positive_int)
249
249
 
250
+ recovery_help = "Validate and republish retained checkpoints for a failed, non-canceled scan."
251
+ recover_scan = subparsers.add_parser(
252
+ "recover-scan-results", help=recovery_help, description=recovery_help
253
+ )
254
+ recover_scan.add_argument("--scan-id", required=True, help="ID of the stopped scan to recover.")
255
+
250
256
  write_scan_draft = subparsers.add_parser("write-scan-draft")
251
257
  write_scan_draft.add_argument("--scan-id", required=True)
252
258
  write_scan_draft.add_argument("--draft-path", required=True)
@@ -12,7 +12,6 @@ from typing import Any
12
12
  sys.path.insert(0, str(Path(__file__).resolve().parent))
13
13
  from workbench_findings import list_dedupe_groups
14
14
 
15
-
16
15
  FINDING_RECORDS = """
17
16
  SELECT findings.id, json_extract(details_json, '$.title') AS title,
18
17
  COALESCE(repositories.ids, '[]') AS repositoryIds,
@@ -52,17 +51,24 @@ def detail(connection: sqlite3.Connection, view: str, selected: dict[str, Any])
52
51
  result: dict[str, Any] = {"item": selected}
53
52
  selected_id = selected["id"]
54
53
  if view == "findings":
55
- result["finding"] = json.loads(connection.execute(
56
- "SELECT details_json FROM findings WHERE id = ?", (selected_id,),
57
- ).fetchone()[0])
54
+ result["finding"] = json.loads(
55
+ connection.execute(
56
+ "SELECT details_json FROM findings WHERE id = ?",
57
+ (selected_id,),
58
+ ).fetchone()[0]
59
+ )
58
60
  result["groups"] = list_dedupe_groups(connection, selected_id)["groups"]
59
61
  else:
60
62
  result["group"] = {
61
- "groupId": selected_id, "createdAt": selected["createdAt"],
62
- "findingIds": [r[0] for r in connection.execute(
63
- "SELECT finding_id FROM finding_dedupe_group_members WHERE group_id = ? ORDER BY finding_id",
64
- (selected_id,),
65
- )],
63
+ "groupId": selected_id,
64
+ "createdAt": selected["createdAt"],
65
+ "findingIds": [
66
+ r[0]
67
+ for r in connection.execute(
68
+ "SELECT finding_id FROM finding_dedupe_group_members WHERE group_id = ? ORDER BY finding_id",
69
+ (selected_id,),
70
+ )
71
+ ],
66
72
  }
67
73
  return result
68
74
 
@@ -76,7 +82,11 @@ def dashboard(connection: sqlite3.Connection, query: dict[str, Any]) -> dict[str
76
82
  if query.get("query"):
77
83
  connection.create_function("casefold", 1, str.casefold, deterministic=True)
78
84
  columns = ["id", "title", "repositoryIds"]
79
- clauses.append("(" + " OR ".join(f"instr(casefold(COALESCE({c}, '')), casefold(?)) > 0" for c in columns) + ")")
85
+ clauses.append(
86
+ "("
87
+ + " OR ".join(f"instr(casefold(COALESCE({c}, '')), casefold(?)) > 0" for c in columns)
88
+ + ")"
89
+ )
80
90
  values.extend([query["query"]] * len(columns))
81
91
  if query.get("repository"):
82
92
  clauses.append("EXISTS (SELECT 1 FROM json_each(repositoryIds) WHERE value = ?)")
@@ -89,23 +99,36 @@ def dashboard(connection: sqlite3.Connection, query: dict[str, Any]) -> dict[str
89
99
  SELECT DISTINCT repository_id AS id, repository_id AS label
90
100
  FROM finding_repositories ORDER BY repository_id
91
101
  """).fetchall()
92
- total = connection.execute(f"SELECT COUNT(*) FROM ({records}) {where}", values).fetchone()[0]
102
+ total = connection.execute(f"SELECT COUNT(*) FROM ({records}) {where}", values).fetchone()[
103
+ 0
104
+ ]
93
105
  rows = connection.execute(
94
106
  f"SELECT * FROM ({records}) {where} ORDER BY {order} LIMIT ? OFFSET ?",
95
107
  (*values, query["limit"], query["offset"]),
96
108
  ).fetchall()
97
- selected = connection.execute(
98
- f"SELECT * FROM ({records}) WHERE id = ?", (query["id"],),
99
- ).fetchone() if query.get("id") else None
109
+ selected = (
110
+ connection.execute(
111
+ f"SELECT * FROM ({records}) WHERE id = ?",
112
+ (query["id"],),
113
+ ).fetchone()
114
+ if query.get("id")
115
+ else None
116
+ )
100
117
  next_offset = query["offset"] + len(rows)
101
118
  return {
102
119
  "overview": {
103
- "findings": connection.execute("SELECT COUNT(*) FROM findings WHERE details_json IS NOT NULL").fetchone()[0],
104
- "groups": connection.execute("SELECT COUNT(*) FROM finding_dedupe_groups").fetchone()[0],
120
+ "findings": connection.execute(
121
+ "SELECT COUNT(*) FROM findings WHERE details_json IS NOT NULL"
122
+ ).fetchone()[0],
123
+ "groups": connection.execute(
124
+ "SELECT COUNT(*) FROM finding_dedupe_groups"
125
+ ).fetchone()[0],
105
126
  },
106
127
  "repositories": [dict(row) for row in repositories],
107
- "items": [item(row) for row in rows], "total": total,
108
- "limit": query["limit"], "offset": query["offset"],
128
+ "items": [item(row) for row in rows],
129
+ "total": total,
130
+ "limit": query["limit"],
131
+ "offset": query["offset"],
109
132
  "nextOffset": next_offset if next_offset < total else None,
110
133
  "detail": detail(connection, view, item(selected)) if selected is not None else None,
111
134
  }