@openai/codex-security 0.6.0 → 0.7.0

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 (243) hide show
  1. package/README.md +68 -37
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +1 -1
  6. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  7. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  8. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  9. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  10. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  11. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  12. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  14. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  15. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  16. package/_bundled_plugin/references/access-advisory.md +11 -0
  17. package/_bundled_plugin/references/core-scan.md +30 -77
  18. package/_bundled_plugin/references/final-report.md +45 -189
  19. package/_bundled_plugin/references/scan-contract.md +2 -0
  20. package/_bundled_plugin/references/scan-prologue.md +1 -1
  21. package/_bundled_plugin/references/scan-runtime.md +1 -5
  22. package/_bundled_plugin/references/threat-model.md +33 -41
  23. package/_bundled_plugin/schemas/coverage.schema.json +12 -1
  24. package/_bundled_plugin/schemas/scan-manifest.schema.json +1 -0
  25. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
  26. package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
  27. package/_bundled_plugin/scripts/deep_scan_workbench.py +145 -85
  28. package/_bundled_plugin/scripts/finalize_scan_contract.py +189 -57
  29. package/_bundled_plugin/scripts/report_projection.py +44 -15
  30. package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
  31. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
  32. package/_bundled_plugin/scripts/workbench/retained_coverage.py +3218 -0
  33. package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
  34. package/_bundled_plugin/scripts/workbench/saved_coverage.py +644 -1
  35. package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
  36. package/_bundled_plugin/scripts/workbench/saved_sources.py +712 -0
  37. package/_bundled_plugin/scripts/workbench_cli.py +3 -0
  38. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
  39. package/_bundled_plugin/scripts/workbench_db.py +51 -22
  40. package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
  41. package/_bundled_plugin/scripts/workbench_finding_workflows.py +51 -9
  42. package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
  43. package/_bundled_plugin/scripts/workbench_saved_results.py +641 -2387
  44. package/_bundled_plugin/scripts/workbench_scan_history.py +72 -7
  45. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  46. package/_bundled_plugin/scripts/workbench_source_scopes.py +4 -1
  47. package/_bundled_plugin/scripts/workbench_target.py +142 -17
  48. package/_bundled_plugin/scripts/workbench_validation.py +9 -2
  49. package/_bundled_plugin/shared/workbench-history-repairs.json +21 -0
  50. package/_bundled_plugin/shared/workbench-migrations.json +28 -0
  51. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +3 -14
  52. package/_bundled_plugin/skills/assess-patch-risk/references/windows-validation.md +14 -0
  53. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +38 -103
  54. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +11 -73
  55. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +57 -116
  56. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +28 -51
  57. package/_bundled_plugin/skills/define-security-policy/SKILL.md +9 -9
  58. package/_bundled_plugin/skills/finding-discovery/SKILL.md +26 -140
  59. package/_bundled_plugin/skills/fix-finding/SKILL.md +9 -28
  60. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +28 -218
  61. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +29 -424
  62. package/_bundled_plugin/skills/publish-findings/SKILL.md +28 -24
  63. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +64 -0
  64. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +12 -12
  65. package/_bundled_plugin/skills/security-scan/SKILL.md +28 -16
  66. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +11 -17
  67. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +52 -69
  68. package/_bundled_plugin/skills/threat-model/SKILL.md +16 -9
  69. package/_bundled_plugin/skills/triage-finding/SKILL.md +5 -15
  70. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -6
  71. package/_bundled_plugin/skills/validation/SKILL.md +42 -104
  72. package/_bundled_plugin/skills/validation/references/validation-guidance.md +21 -106
  73. package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
  74. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +21 -159
  75. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +18 -60
  76. package/dist/api.d.ts +5 -3
  77. package/dist/api.d.ts.map +1 -1
  78. package/dist/api.js +341 -37
  79. package/dist/api.js.map +1 -1
  80. package/dist/auth.d.ts.map +1 -1
  81. package/dist/auth.js +4 -1
  82. package/dist/auth.js.map +1 -1
  83. package/dist/cli.d.ts +2 -2
  84. package/dist/cli.d.ts.map +1 -1
  85. package/dist/cli.js +674 -419
  86. package/dist/cli.js.map +1 -1
  87. package/dist/component-scan.d.ts +8 -2
  88. package/dist/component-scan.d.ts.map +1 -1
  89. package/dist/component-scan.js +2 -0
  90. package/dist/component-scan.js.map +1 -1
  91. package/dist/contract.d.ts +2 -0
  92. package/dist/contract.d.ts.map +1 -1
  93. package/dist/contract.js +67 -33
  94. package/dist/contract.js.map +1 -1
  95. package/dist/cost.d.ts +18 -0
  96. package/dist/cost.d.ts.map +1 -1
  97. package/dist/cost.js +107 -12
  98. package/dist/cost.js.map +1 -1
  99. package/dist/coverage-presentation.d.ts +6 -0
  100. package/dist/coverage-presentation.d.ts.map +1 -0
  101. package/dist/coverage-presentation.js +34 -0
  102. package/dist/coverage-presentation.js.map +1 -0
  103. package/dist/custom-validation-prompt.js +3 -3
  104. package/dist/custom-validation-prompt.js.map +1 -1
  105. package/dist/custom-validation.d.ts.map +1 -1
  106. package/dist/custom-validation.js +30 -4
  107. package/dist/custom-validation.js.map +1 -1
  108. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  109. package/dist/deduplication/checkpointed-review.js +3 -1
  110. package/dist/deduplication/checkpointed-review.js.map +1 -1
  111. package/dist/deduplication/scan.d.ts.map +1 -1
  112. package/dist/deduplication/scan.js +7 -5
  113. package/dist/deduplication/scan.js.map +1 -1
  114. package/dist/endor-findings.d.ts +4 -3
  115. package/dist/endor-findings.d.ts.map +1 -1
  116. package/dist/endor-findings.js +16 -11
  117. package/dist/endor-findings.js.map +1 -1
  118. package/dist/external-findings-import.d.ts.map +1 -1
  119. package/dist/external-findings-import.js +13 -5
  120. package/dist/external-findings-import.js.map +1 -1
  121. package/dist/external-findings-local.d.ts.map +1 -1
  122. package/dist/external-findings-local.js +8 -1
  123. package/dist/external-findings-local.js.map +1 -1
  124. package/dist/external-findings-publish.d.ts +1 -1
  125. package/dist/external-findings-publish.d.ts.map +1 -1
  126. package/dist/external-findings-publish.js +11 -3
  127. package/dist/external-findings-publish.js.map +1 -1
  128. package/dist/external-findings-read.d.ts +11 -1
  129. package/dist/external-findings-read.d.ts.map +1 -1
  130. package/dist/external-findings-read.js +15 -6
  131. package/dist/external-findings-read.js.map +1 -1
  132. package/dist/external-import-contract.d.ts +3 -1
  133. package/dist/external-import-contract.d.ts.map +1 -1
  134. package/dist/external-import-contract.js +33 -25
  135. package/dist/external-import-contract.js.map +1 -1
  136. package/dist/external-imports-feature.d.ts +6 -0
  137. package/dist/external-imports-feature.d.ts.map +1 -0
  138. package/dist/external-imports-feature.js +51 -0
  139. package/dist/external-imports-feature.js.map +1 -0
  140. package/dist/finding-workflow.d.ts +22 -5
  141. package/dist/finding-workflow.d.ts.map +1 -1
  142. package/dist/finding-workflow.js +21 -9
  143. package/dist/finding-workflow.js.map +1 -1
  144. package/dist/github-advisories.d.ts.map +1 -1
  145. package/dist/github-advisories.js +3 -1
  146. package/dist/github-advisories.js.map +1 -1
  147. package/dist/github-findings.d.ts +4 -3
  148. package/dist/github-findings.d.ts.map +1 -1
  149. package/dist/github-findings.js +16 -14
  150. package/dist/github-findings.js.map +1 -1
  151. package/dist/hosted-remediation.d.ts.map +1 -1
  152. package/dist/hosted-remediation.js +19 -2
  153. package/dist/hosted-remediation.js.map +1 -1
  154. package/dist/hosted-scan.d.ts +1 -1
  155. package/dist/hosted-scan.d.ts.map +1 -1
  156. package/dist/hosted-scan.js +0 -5
  157. package/dist/hosted-scan.js.map +1 -1
  158. package/dist/import-scan.js +1 -1
  159. package/dist/import-scan.js.map +1 -1
  160. package/dist/index.d.ts +3 -3
  161. package/dist/index.d.ts.map +1 -1
  162. package/dist/index.js +1 -1
  163. package/dist/index.js.map +1 -1
  164. package/dist/knowledge-base.d.ts +1 -0
  165. package/dist/knowledge-base.d.ts.map +1 -1
  166. package/dist/knowledge-base.js +17 -8
  167. package/dist/knowledge-base.js.map +1 -1
  168. package/dist/models.d.ts +1 -0
  169. package/dist/models.d.ts.map +1 -1
  170. package/dist/models.js.map +1 -1
  171. package/dist/owner-evidence.d.ts +2 -0
  172. package/dist/owner-evidence.d.ts.map +1 -1
  173. package/dist/owner-evidence.js +2 -1
  174. package/dist/owner-evidence.js.map +1 -1
  175. package/dist/publish.d.ts +2 -0
  176. package/dist/publish.d.ts.map +1 -1
  177. package/dist/publish.js +1 -1
  178. package/dist/publish.js.map +1 -1
  179. package/dist/remediation.d.ts +1 -25
  180. package/dist/remediation.d.ts.map +1 -1
  181. package/dist/remediation.js +3 -24
  182. package/dist/remediation.js.map +1 -1
  183. package/dist/runtime.d.ts.map +1 -1
  184. package/dist/runtime.js +7 -7
  185. package/dist/runtime.js.map +1 -1
  186. package/dist/scan-dashboard.d.ts +5 -3
  187. package/dist/scan-dashboard.d.ts.map +1 -1
  188. package/dist/scan-dashboard.js +79 -26
  189. package/dist/scan-dashboard.js.map +1 -1
  190. package/dist/scan-history-renderer.d.ts.map +1 -1
  191. package/dist/scan-history-renderer.js +8 -2
  192. package/dist/scan-history-renderer.js.map +1 -1
  193. package/dist/scan-owner-suggestions.d.ts +1 -1
  194. package/dist/scan-owner-suggestions.d.ts.map +1 -1
  195. package/dist/scan-owner-suggestions.js +4 -4
  196. package/dist/scan-owner-suggestions.js.map +1 -1
  197. package/dist/scan-usage-display.d.ts +8 -0
  198. package/dist/scan-usage-display.d.ts.map +1 -0
  199. package/dist/scan-usage-display.js +46 -0
  200. package/dist/scan-usage-display.js.map +1 -0
  201. package/dist/scanner-import.d.ts +1 -1
  202. package/dist/scanner-import.d.ts.map +1 -1
  203. package/dist/scanner-import.js +7 -3
  204. package/dist/scanner-import.js.map +1 -1
  205. package/dist/security-policy.d.ts.map +1 -1
  206. package/dist/security-policy.js +1 -20
  207. package/dist/security-policy.js.map +1 -1
  208. package/dist/semgrep-findings.d.ts +4 -3
  209. package/dist/semgrep-findings.d.ts.map +1 -1
  210. package/dist/semgrep-findings.js +9 -9
  211. package/dist/semgrep-findings.js.map +1 -1
  212. package/dist/skill-authentication.d.ts +18 -0
  213. package/dist/skill-authentication.d.ts.map +1 -0
  214. package/dist/skill-authentication.js +82 -0
  215. package/dist/skill-authentication.js.map +1 -0
  216. package/dist/snyk-findings.d.ts +5 -4
  217. package/dist/snyk-findings.d.ts.map +1 -1
  218. package/dist/snyk-findings.js +18 -17
  219. package/dist/snyk-findings.js.map +1 -1
  220. package/dist/suggest-owners.d.ts +4 -1
  221. package/dist/suggest-owners.d.ts.map +1 -1
  222. package/dist/suggest-owners.js +53 -21
  223. package/dist/suggest-owners.js.map +1 -1
  224. package/dist/targets.d.ts.map +1 -1
  225. package/dist/targets.js +4 -1
  226. package/dist/targets.js.map +1 -1
  227. package/dist/wiz-csv.d.ts +2 -1
  228. package/dist/wiz-csv.d.ts.map +1 -1
  229. package/dist/wiz-csv.js +3 -3
  230. package/dist/wiz-csv.js.map +1 -1
  231. package/dist/wiz-findings.d.ts +2 -1
  232. package/dist/wiz-findings.d.ts.map +1 -1
  233. package/dist/wiz-findings.js +27 -23
  234. package/dist/wiz-findings.js.map +1 -1
  235. package/docs/classify-severity-records.md +3 -4
  236. package/docs/cli.md +155 -38
  237. package/docs/findings-service.md +119 -118
  238. package/docs/hosted-remediation.md +19 -17
  239. package/docs/hosted-scans.md +37 -11
  240. package/package.json +8 -8
  241. package/_bundled_plugin/scripts/generate_in_scope_files.py +0 -277
  242. package/_bundled_plugin/scripts/generate_rank_input.py +0 -350
  243. package/_bundled_plugin/scripts/rank_preview.py +0 -129
@@ -97,6 +97,10 @@ class ContractError(ValueError):
97
97
  """Raised when a completed scan does not satisfy the additive contract."""
98
98
 
99
99
 
100
+ class ScanLocalIOError(ContractError):
101
+ """Raised when scan-local storage I/O fails, distinct from path validation."""
102
+
103
+
100
104
  class MissingScanLocalFileError(ContractError):
101
105
  """Raised when a scan-local file or its containing directory is absent."""
102
106
 
@@ -199,11 +203,7 @@ def _read_saved_threat_model(
199
203
  if filename == "scan-manifest.json"
200
204
  else manifest
201
205
  )
202
- if (
203
- validate_seal
204
- and filename == "scan-manifest.json"
205
- and (scan.get("sealedAt") is not None or scan.get("artifacts"))
206
- ):
206
+ if validate_seal and filename == "scan-manifest.json" and manifest_is_sealed(scan):
207
207
  if "threatModel" not in scan:
208
208
  _validate_manifest(manifest)
209
209
  recorded_paths = {
@@ -428,7 +428,7 @@ def _require_safe_relative_path(value: object, context: str, *, allow_dot: bool
428
428
  normalized = path.as_posix()
429
429
  if (
430
430
  (normalized == "." and not allow_dot)
431
- or (len(value) >= 2 and value[0].isalpha() and value[1] == ":")
431
+ or re.match(r"^[A-Za-z]:", value)
432
432
  or "\\" in value
433
433
  or "\0" in value
434
434
  or any(ord(character) < 32 for character in value)
@@ -452,18 +452,28 @@ def _windows_unsafe_path_component(value: str) -> bool:
452
452
  return WINDOWS_UNSAFE_PATH_COMPONENT_RE.search(value) is not None
453
453
 
454
454
 
455
+ def _scan_local_directory_error(message: str, error: OSError) -> ContractError:
456
+ if error.errno in {errno.ENOENT, errno.ENOTDIR, errno.ELOOP}:
457
+ return ContractError(message)
458
+ return ScanLocalIOError(message)
459
+
460
+
455
461
  def _require_scan_directory(scan_dir: Path) -> Path:
456
462
  scan_dir = scan_dir.absolute()
457
463
  try:
458
464
  metadata = scan_dir.lstat()
459
465
  except OSError as exc:
460
- raise ContractError("scan directory: expected an existing non-symlink directory") from exc
466
+ raise _scan_local_directory_error(
467
+ "scan directory: expected an existing non-symlink directory", exc
468
+ ) from exc
461
469
  if not stat.S_ISDIR(metadata.st_mode):
462
470
  raise ContractError("scan directory: expected an existing non-symlink directory")
463
471
  try:
464
472
  resolved = scan_dir.resolve(strict=True)
465
473
  except OSError as exc:
466
- raise ContractError("scan directory: expected an existing non-symlink directory") from exc
474
+ raise _scan_local_directory_error(
475
+ "scan directory: expected an existing non-symlink directory", exc
476
+ ) from exc
467
477
  if os.path.normcase(resolved) != os.path.normcase(scan_dir):
468
478
  raise ContractError("scan directory: expected a canonical non-symlink directory")
469
479
  return resolved
@@ -518,7 +528,9 @@ def _open_verified_scan_directory(
518
528
  os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
519
529
  )
520
530
  except OSError as exc:
521
- raise ContractError("scan directory: expected an existing non-symlink directory") from exc
531
+ raise _scan_local_directory_error(
532
+ "scan directory: expected an existing non-symlink directory", exc
533
+ ) from exc
522
534
  opened = os.fstat(descriptor)
523
535
  opened_identity = (opened.st_dev, opened.st_ino)
524
536
  if opened_identity != observed_identity or (
@@ -770,15 +782,18 @@ def write_scan_local_bytes(
770
782
  if not _descriptor_relative_writes_available():
771
783
  if not _is_windows():
772
784
  raise ContractError("scan-local output requires descriptor-relative file operations")
785
+ backend = _windows_scan_local_files()
773
786
  try:
774
- _windows_scan_local_files().atomic_write(
787
+ backend.atomic_write(
775
788
  scan_dir,
776
789
  relative_path,
777
790
  payload,
778
791
  expected_root_identity=expected_root_identity,
779
792
  )
780
- except OSError as exc:
793
+ except backend.WindowsScanLocalPathError as exc:
781
794
  raise ContractError(f"{relative_path}: {exc}") from exc
795
+ except OSError as exc:
796
+ raise ScanLocalIOError(f"{relative_path}: {exc}") from exc
782
797
  return
783
798
  root_fd: int | None = None
784
799
  parent_fd: int | None = None
@@ -789,8 +804,8 @@ def write_scan_local_bytes(
789
804
  try:
790
805
  parent_fd = _open_scan_local_directory(root_fd, parts[:-1], create=True)
791
806
  except OSError as exc:
792
- raise ContractError(
793
- f"{relative_path}: expected a path inside the scan directory"
807
+ raise _scan_local_directory_error(
808
+ f"{relative_path}: expected a path inside the scan directory", exc
794
809
  ) from exc
795
810
  # The held descriptor is the authority for the validated parent. A
796
811
  # concurrent rename cannot redirect later operations through a
@@ -1075,6 +1090,8 @@ def _recover_unsealed_findings(
1075
1090
  schema_dir: Path,
1076
1091
  scan_dir: Path,
1077
1092
  warnings: list[str],
1093
+ *,
1094
+ current_contract: bool = False,
1078
1095
  ) -> list[str]:
1079
1096
  schema = _read_json(schema_dir / "findings.schema.json")
1080
1097
  properties = _require_dict(schema, "properties", "findings.schema")
@@ -1190,6 +1207,9 @@ def _recover_unsealed_findings(
1190
1207
  f"Skipped malformed {auxiliary} for finding {index + 1}: {exc}."
1191
1208
  )
1192
1209
  _validate_schema_node(finding, finding_schema, context, schema)
1210
+ _require_safe_json_value(finding, context)
1211
+ if current_contract:
1212
+ _validate_current_findings({"findings": [finding]}, schema_dir)
1193
1213
  except ContractError as exc:
1194
1214
  warning = f"Skipped malformed finding {index + 1}: {exc}."
1195
1215
  warnings.append(warning)
@@ -1245,9 +1265,12 @@ def _recover_unsealed_coverage(
1245
1265
  scan_dir: Path,
1246
1266
  warnings: list[str],
1247
1267
  discarded_findings: list[str],
1248
- ) -> None:
1268
+ *,
1269
+ worker_draft: bool = False,
1270
+ ) -> set[str]:
1249
1271
  schema = _read_json(schema_dir / "coverage.schema.json")
1250
1272
  properties = _require_dict(schema, "properties", "coverage.schema")
1273
+ discarded_fields: set[str] = set()
1251
1274
  if (
1252
1275
  coverage.get("mode") == "deep_repository"
1253
1276
  and coverage.get("inventoryStrategy") != "repository"
@@ -1257,16 +1280,24 @@ def _recover_unsealed_coverage(
1257
1280
 
1258
1281
  surface_ids: set[str] = set()
1259
1282
  receipt_paths: dict[str, str] = {}
1260
- for field, label in (
1283
+ fields = [
1261
1284
  ("surfaces", "coverage surface"),
1262
1285
  ("explicitExclusions", "coverage exclusion"),
1263
1286
  ("deferred", "deferred coverage item"),
1264
- ):
1287
+ ]
1288
+ if worker_draft:
1289
+ if "openQuestions" in coverage:
1290
+ _normalize_unsealed_open_questions(coverage)
1291
+ fields.append(("openQuestions", "coverage open question"))
1292
+ if "resolvedDeferred" in coverage:
1293
+ fields.append(("resolvedDeferred", "resolved deferred item"))
1294
+ for field, label in fields:
1265
1295
  array_schema = _require_dict(properties, field, "coverage.schema.properties")
1266
1296
  item_schema = _require_dict(array_schema, "items", f"coverage.schema.properties.{field}")
1267
1297
  items = coverage.get(field)
1268
1298
  if not isinstance(items, list):
1269
1299
  warnings.append(f"Skipped malformed {label} records: expected an array.")
1300
+ discarded_fields.add(field)
1270
1301
  coverage[field] = []
1271
1302
  continue
1272
1303
 
@@ -1279,7 +1310,9 @@ def _recover_unsealed_coverage(
1279
1310
  if field == "surfaces":
1280
1311
  surface_receipt_paths = dict(receipt_paths)
1281
1312
  surface_id = _require_str(item, "id", context)
1282
- if surface_id in surface_ids:
1313
+ if worker_draft:
1314
+ _require_str(item, "label", context)
1315
+ if surface_id in surface_ids and not worker_draft:
1283
1316
  raise ContractError(f"{context}.id: duplicate surface id")
1284
1317
  disposition = item.get("disposition")
1285
1318
  surface_recovered = False
@@ -1329,12 +1362,18 @@ def _recover_unsealed_coverage(
1329
1362
  item["receiptRefs"] = recovered_receipts
1330
1363
  if surface_recovered:
1331
1364
  item["disposition"] = "needs_follow_up"
1365
+ discarded_fields.add(field)
1332
1366
 
1333
1367
  if field == "deferred":
1334
1368
  _validate_deferred_paths(item, context)
1335
1369
  _validate_schema_node(item, item_schema, context)
1370
+ if field == "resolvedDeferred":
1371
+ _validate_resolved_deferred({"resolvedDeferred": [item]})
1372
+ if worker_draft:
1373
+ _require_safe_json_value(item, context)
1336
1374
  except ContractError as exc:
1337
1375
  warnings.append(f"Skipped malformed {label} {index + 1}: {exc}.")
1376
+ discarded_fields.add(field)
1338
1377
  continue
1339
1378
 
1340
1379
  if field == "surfaces":
@@ -1346,6 +1385,13 @@ def _recover_unsealed_coverage(
1346
1385
 
1347
1386
  if discarded_findings:
1348
1387
  for surface in coverage["surfaces"]:
1388
+ if (
1389
+ worker_draft
1390
+ and surface.get("candidateId")
1391
+ and surface["disposition"] in {"rejected", "not_applicable"}
1392
+ ):
1393
+ # A valid explicit outcome can still resolve that worker's history.
1394
+ continue
1349
1395
  surface["disposition"] = "needs_follow_up"
1350
1396
  coverage["deferred"].extend(
1351
1397
  {"id": f"discarded-finding-{index}", "reason": warning}
@@ -1360,9 +1406,13 @@ def _recover_unsealed_coverage(
1360
1406
  "coverage.resolvedDeferred",
1361
1407
  )
1362
1408
  _validate_resolved_deferred(coverage)
1409
+ if worker_draft:
1410
+ _require_safe_json_value(coverage["resolvedDeferred"], "coverage.resolvedDeferred")
1363
1411
  except ContractError as exc:
1364
1412
  coverage.pop("resolvedDeferred")
1365
1413
  warnings.append(f"Skipped malformed resolved deferred work: {exc}.")
1414
+ discarded_fields.add("resolvedDeferred")
1415
+ return discarded_fields
1366
1416
 
1367
1417
 
1368
1418
  def _recover_unsealed_hardening(
@@ -1921,6 +1971,21 @@ def _resolve_schema_reference(
1921
1971
  return target
1922
1972
 
1923
1973
 
1974
+ def _matches_sealed_path_exclusion(value: str, one_of: Any) -> bool:
1975
+ # The empty alternative always matches, so a path must not match the second one.
1976
+ if not isinstance(one_of, list) or len(one_of) != 2 or one_of[0] != {}:
1977
+ return False
1978
+ excluded = one_of[1]
1979
+ return (
1980
+ isinstance(excluded, dict)
1981
+ and excluded.keys() == {"$comment", "type", "pattern"}
1982
+ and excluded["$comment"] == "invalidSealedDeferredPath"
1983
+ and excluded["type"] == "string"
1984
+ and isinstance(excluded["pattern"], str)
1985
+ and re.search(excluded["pattern"], value) is not None
1986
+ )
1987
+
1988
+
1924
1989
  def _validate_schema_node(
1925
1990
  value: Any,
1926
1991
  schema: dict[str, Any],
@@ -1970,6 +2035,8 @@ def _validate_schema_node(
1970
2035
  raise ContractError(f"{context}: string is too long")
1971
2036
  if "pattern" in schema and not re.search(schema["pattern"], value):
1972
2037
  raise ContractError(f"{context}: string does not match schema pattern")
2038
+ if _matches_sealed_path_exclusion(value, schema.get("oneOf")):
2039
+ raise ContractError(f"{context}: string matches excluded schema pattern")
1973
2040
  if schema.get("format") == "date-time":
1974
2041
  _validate_date_time(value, context)
1975
2042
  if isinstance(value, (int, float)) and not isinstance(value, bool):
@@ -2505,7 +2572,7 @@ def _sarif_locations(finding: dict[str, Any]) -> list[dict[str, Any]]:
2505
2572
  unique: dict[tuple[str, int, int], dict[str, Any]] = {}
2506
2573
  for location in locations:
2507
2574
  key = (
2508
- location["path"],
2575
+ PurePosixPath(location["path"]).as_posix(),
2509
2576
  location["startLine"],
2510
2577
  location.get("endLine", location["startLine"]),
2511
2578
  )
@@ -2777,14 +2844,17 @@ def build_sarif_projection(
2777
2844
  manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
2778
2845
  sarif = build_sarif(manifest, findings, source_root)
2779
2846
  execution_successful = manifest["scan"]["status"] == "completed"
2780
- if not execution_successful or coverage["deferred"]:
2847
+ messages = [item["reason"] for item in coverage["deferred"]]
2848
+ for warning in manifest["scan"].get("warnings", []):
2849
+ if warning not in messages:
2850
+ messages.append(warning)
2851
+ if not execution_successful or messages:
2781
2852
  run = sarif["runs"][0]
2782
2853
  run["invocations"] = [
2783
2854
  {
2784
2855
  "executionSuccessful": execution_successful,
2785
2856
  "toolExecutionNotifications": [
2786
- {"level": "warning", "message": {"text": item["reason"]}}
2787
- for item in coverage["deferred"]
2857
+ {"level": "warning", "message": {"text": message}} for message in messages
2788
2858
  ],
2789
2859
  }
2790
2860
  ]
@@ -2810,13 +2880,20 @@ def csv_cell(value: Any) -> Any:
2810
2880
  return value
2811
2881
 
2812
2882
 
2883
+ def _has_identity_text(value: Any) -> bool:
2884
+ # Match JavaScript String.trim when selecting optional identity metadata.
2885
+ return isinstance(value, str) and bool(
2886
+ value.strip(
2887
+ "\u0009\u000a\u000b\u000c\u000d\u0020\u00a0\u1680"
2888
+ "\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a"
2889
+ "\u2028\u2029\u202f\u205f\u3000\ufeff"
2890
+ )
2891
+ )
2892
+
2893
+
2813
2894
  def finding_candidate_id(finding: dict[str, Any]) -> str | None:
2814
2895
  provenance = finding.get("provenance")
2815
- if (
2816
- isinstance(provenance, dict)
2817
- and isinstance(value := provenance.get("candidateId"), str)
2818
- and value.strip()
2819
- ):
2896
+ if isinstance(provenance, dict) and _has_identity_text(value := provenance.get("candidateId")):
2820
2897
  return value
2821
2898
  extensions = finding.get("extensions")
2822
2899
  if not isinstance(extensions, dict):
@@ -2825,12 +2902,29 @@ def finding_candidate_id(finding: dict[str, Any]) -> str | None:
2825
2902
  (
2826
2903
  value
2827
2904
  for field in ("candidateId", "reportId", "ledgerRowId")
2828
- if isinstance(value := extensions.get(field), str) and value.strip()
2905
+ if _has_identity_text(value := extensions.get(field))
2829
2906
  ),
2830
2907
  None,
2831
2908
  )
2832
2909
 
2833
2910
 
2911
+ def _csv_candidate_id(finding: dict[str, Any]) -> str | None:
2912
+ candidate_id = finding_candidate_id(finding)
2913
+ if candidate_id is not None:
2914
+ return candidate_id
2915
+ # Preserve literal CSV metadata, such as FEFF, that is not a canonical identity.
2916
+ for metadata, fields in (
2917
+ (finding.get("provenance"), ("candidateId",)),
2918
+ (finding.get("extensions"), ("candidateId", "reportId", "ledgerRowId")),
2919
+ ):
2920
+ if isinstance(metadata, dict):
2921
+ for field in fields:
2922
+ value = metadata.get(field)
2923
+ if isinstance(value, str) and value.strip():
2924
+ return value
2925
+ return None
2926
+
2927
+
2834
2928
  def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:
2835
2929
  return (
2836
2930
  "occurrence_id",
@@ -2861,7 +2955,7 @@ def build_csv_projection(findings: dict[str, Any], coverage: dict[str, Any]) ->
2861
2955
  (
2862
2956
  csv_cell(finding["occurrenceId"]),
2863
2957
  csv_cell(finding["findingId"]),
2864
- *((csv_cell(finding_candidate_id(finding)),) if deep_scan else ()),
2958
+ *((csv_cell(_csv_candidate_id(finding)),) if deep_scan else ()),
2865
2959
  csv_cell(finding["title"]),
2866
2960
  csv_cell(finding["summary"]),
2867
2961
  csv_cell(finding["severity"]["level"]),
@@ -2898,6 +2992,30 @@ def build_findings_export(
2898
2992
  return build_csv_projection(findings, coverage)
2899
2993
 
2900
2994
 
2995
+ def _is_sealed_artifact(scan_dir: Path, relative_output: str, artifact_paths: list[str]) -> bool:
2996
+ try:
2997
+ output_metadata = (scan_dir / relative_output).stat(follow_symlinks=False)
2998
+ except FileNotFoundError:
2999
+ output_metadata = None
3000
+ except OSError as exc:
3001
+ raise ContractError(f"{relative_output}: unable to inspect export output") from exc
3002
+ for artifact_path in artifact_paths:
3003
+ if artifact_path == relative_output:
3004
+ return True
3005
+ if output_metadata is None:
3006
+ continue
3007
+ descriptor = open_scan_local_file_descriptor(
3008
+ scan_dir, artifact_path, f"sealed artifact {artifact_path}"
3009
+ )
3010
+ try:
3011
+ artifact_metadata = os.fstat(descriptor)
3012
+ finally:
3013
+ os.close(descriptor)
3014
+ if os.path.samestat(output_metadata, artifact_metadata):
3015
+ return True
3016
+ return False
3017
+
3018
+
2901
3019
  def write_export_output(scan_dir: Path, output: Path, export_format: str, contents: bytes) -> None:
2902
3020
  output_paths = {**EXPORT_PATHS, "md": THREAT_MODEL_EXPORT_PATH}
2903
3021
  if export_format not in output_paths:
@@ -2948,40 +3066,25 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
2948
3066
  for index, artifact in enumerate(artifacts)
2949
3067
  if isinstance(artifact, dict)
2950
3068
  ]
2951
- try:
2952
- output_metadata = output.stat(follow_symlinks=False)
2953
- except FileNotFoundError:
2954
- output_metadata = None
2955
- except OSError as exc:
2956
- raise ContractError(f"{relative_output}: unable to inspect export output") from exc
2957
- for artifact_path in artifact_paths:
2958
- if artifact_path == relative_output:
2959
- raise SealedArtifactError(
2960
- f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
2961
- )
2962
- if output_metadata is None:
2963
- continue
2964
- descriptor = open_scan_local_file_descriptor(
2965
- scan_dir, artifact_path, f"sealed artifact {artifact_path}"
3069
+ if _is_sealed_artifact(scan_dir, relative_output, artifact_paths):
3070
+ raise SealedArtifactError(
3071
+ f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
2966
3072
  )
2967
- try:
2968
- artifact_metadata = os.fstat(descriptor)
2969
- finally:
2970
- os.close(descriptor)
2971
- if os.path.samestat(output_metadata, artifact_metadata):
2972
- raise SealedArtifactError(
2973
- f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
2974
- )
2975
3073
  write_scan_local_bytes(
2976
3074
  scan_dir, relative_output, contents, owner_read_write=export_format == "md"
2977
3075
  )
2978
3076
 
2979
3077
 
2980
3078
  def _write_sarif_projection_if_possible(
2981
- scan_dir: Path, source_root: Path | None = None, schema_dir: Path | None = None
3079
+ scan_dir: Path,
3080
+ source_root: Path | None = None,
3081
+ schema_dir: Path | None = None,
3082
+ *,
3083
+ sealed_paths: list[str],
2982
3084
  ) -> None:
2983
3085
  try:
2984
- write_sarif_projection(scan_dir, source_root, schema_dir)
3086
+ if not _is_sealed_artifact(scan_dir, "exports/results.sarif", sealed_paths):
3087
+ write_sarif_projection(scan_dir, source_root, schema_dir)
2985
3088
  except (ContractError, OSError) as error:
2986
3089
  print(
2987
3090
  f"codex-security: warning: automatic SARIF export failed: {error}. "
@@ -3001,6 +3104,10 @@ class PreparedScanFinalization(NamedTuple):
3001
3104
  warnings: list[str]
3002
3105
 
3003
3106
 
3107
+ def manifest_is_sealed(scan: dict[str, Any]) -> bool:
3108
+ return scan.get("sealedAt") is not None or scan.get("artifacts") not in (None, [])
3109
+
3110
+
3004
3111
  def _prepare_scan_finalization(
3005
3112
  scan_dir: Path,
3006
3113
  schema_dir: Path | None = None,
@@ -3025,7 +3132,7 @@ def _prepare_scan_finalization(
3025
3132
  scan = _require_dict(manifest, "scan", "manifest")
3026
3133
  if scan.get("sealedAt") is None and scan.get("artifacts") == []:
3027
3134
  del scan["artifacts"]
3028
- was_sealed = scan.get("sealedAt") is not None or scan.get("artifacts") is not None
3135
+ was_sealed = manifest_is_sealed(scan)
3029
3136
  if not was_sealed:
3030
3137
  _populate_unsealed_manifest_envelope(manifest, scan, completion_binding)
3031
3138
  _validate_contract_refs(scan)
@@ -3185,14 +3292,39 @@ def _write_prepared_scan_finalization(
3185
3292
  scan_dir = prepared.scan_dir
3186
3293
  scan = _require_dict(prepared.manifest, "scan", "manifest")
3187
3294
  if not prepared.was_sealed:
3295
+ # Capture warnings before the first seal; later operation diagnostics must
3296
+ # not change an existing scan's portable results.
3297
+ # Escape surrogate-escaped filesystem bytes for the Unicode JSON contract.
3298
+ warnings = list(
3299
+ dict.fromkeys(
3300
+ warning.encode("utf-8", errors="backslashreplace").decode("utf-8")
3301
+ for warning in [
3302
+ *scan.get("warnings", []),
3303
+ *(projection_warnings or []),
3304
+ *prepared.warnings,
3305
+ ]
3306
+ )
3307
+ )
3308
+ if warnings:
3309
+ scan["warnings"] = warnings
3310
+ validate_against_schema(
3311
+ prepared.manifest, prepared.schema_dir / "scan-manifest.schema.json"
3312
+ )
3188
3313
  _write_scan_local_json(scan_dir, "findings.json", prepared.findings)
3189
3314
  _write_scan_local_json(scan_dir, "coverage.json", prepared.coverage)
3190
- write_scan_local_bytes(scan_dir, "report.md", prepared.report_markdown_bytes)
3191
- _remove_scan_local_file_if_exists(scan_dir, "report.html")
3315
+ sealed_paths = (
3316
+ [artifact["path"] for artifact in scan["artifacts"]] if prepared.was_sealed else []
3317
+ )
3318
+ if not _is_sealed_artifact(scan_dir, "report.md", sealed_paths):
3319
+ write_scan_local_bytes(scan_dir, "report.md", prepared.report_markdown_bytes)
3320
+ if not _is_sealed_artifact(scan_dir, "report.html", sealed_paths):
3321
+ _remove_scan_local_file_if_exists(scan_dir, "report.html")
3192
3322
  if not prepared.was_sealed:
3193
3323
  _write_scan_local_json(scan_dir, "scan-manifest.json", prepared.manifest)
3194
3324
  _validate_existing_seal(scan_dir, scan)
3195
- _write_sarif_projection_if_possible(scan_dir, source_root, prepared.schema_dir)
3325
+ _write_sarif_projection_if_possible(
3326
+ scan_dir, source_root, prepared.schema_dir, sealed_paths=sealed_paths
3327
+ )
3196
3328
  warning = write_threat_model_projection_if_possible(scan_dir, prepared.manifest)
3197
3329
  if (
3198
3330
  warning is not None
@@ -20,21 +20,44 @@ DISPOSITION_LABELS = {
20
20
  "needs_follow_up": "Needs follow-up",
21
21
  }
22
22
  WRITEUP_REPORT_PATH_RE = re.compile(r"^findings/([a-z0-9][a-z0-9._-]*)/\1\.md$")
23
+ INLINE_CODE_RE = r"(?<!`)`[^`\n]+`(?!`)"
24
+ ENTITY_AMP_RE = r"&(?=(?:#[0-9]+|#[xX][0-9A-Fa-f]+|[A-Za-z][A-Za-z0-9]*);)"
25
+ WWW_LINK_RE = r"(?<![^\s*_~(])(?i:www)\.[^\s<>]+"
23
26
 
24
27
 
25
28
  class ReportProjectionError(ValueError):
26
29
  """Raised when a canonical scan cannot be projected into a valid report."""
27
30
 
28
31
 
32
+ def _escape_markdown(value: str) -> str:
33
+ # Locate whole URLs before matching code spans: a URL can contain backticks.
34
+ urls = [match.span() for match in re.finditer(WWW_LINK_RE, value)]
35
+ # Preserve protocol-relative and fuzzy links without a domain/TLD table.
36
+ for match in re.finditer(r"[^\s<>]+", value):
37
+ token = match[0]
38
+ dot = token.split("/", 1)[0].find(".")
39
+ if "//" in token or (dot >= 0 and re.search(r"[/?#]", token[dot + 1 :])):
40
+ urls.append(match.span())
41
+ punctuation = r"[\\`*_\[\]<>]|" + ENTITY_AMP_RE
42
+ pattern = f"(?P<code>{INLINE_CODE_RE})|{punctuation}"
43
+
44
+ def escape(match: re.Match[str]) -> str:
45
+ if match.lastgroup == "code":
46
+ return match[0]
47
+ # GFM autolinks retain backslashes literally, including in query strings.
48
+ if match[0] == "&" and any(start <= match.start() < end for start, end in urls):
49
+ return "&"
50
+ return "\\" + match[0]
51
+
52
+ return re.sub(pattern, escape, value)
53
+
54
+
29
55
  def _text(value: Any, fallback: str) -> str:
30
56
  candidate = value if isinstance(value, str) and value.strip() else fallback
31
57
  normalized = " ".join(candidate.split())
32
58
  if re.match(r"^(?:#{1,6}\s|[-*+]\s|>\s|```|~~~|\d+[.)]\s|\|)", normalized):
33
59
  normalized = f"Text: {normalized}"
34
- return "".join(
35
- part if index % 2 else re.sub(r"([\\`*_\[\]<>])", r"\\\1", part)
36
- for index, part in enumerate(re.split(r"((?<!`)`[^`\n]+`(?!`))", normalized))
37
- )
60
+ return _escape_markdown(normalized)
38
61
 
39
62
 
40
63
  def _strings(value: Any) -> list[str]:
@@ -45,18 +68,19 @@ def _strings(value: Any) -> list[str]:
45
68
  return [text for item in value if (text := _text(item, ""))]
46
69
 
47
70
 
48
- def _path_label(value: str) -> str:
71
+ def _path_label(value: str, *, ensure_ascii: bool = False) -> str:
49
72
  if "," in value or value != " ".join(value.split()) or any(ord(c) < 32 for c in value):
50
- quoted = json.dumps(value, ensure_ascii=False)
73
+ quoted = json.dumps(value, ensure_ascii=ensure_ascii)
51
74
  return "".join(c if c.isprintable() else json.dumps(c)[1:-1] for c in quoted)
52
75
  return value
53
76
 
54
77
 
55
- def _path_text(value: str) -> str:
56
- label = _path_label(value)
57
- if label != value:
78
+ def _path_text(value: str, *, ensure_ascii: bool = False) -> str:
79
+ label = _path_label(value, ensure_ascii=ensure_ascii)
80
+ if label != value or re.search(ENTITY_AMP_RE, value):
58
81
  marker = _code_fence(label, minimum=1)
59
- return f"{marker}{label}{marker}"
82
+ padding = " " if label.startswith("`") or label.endswith("`") else ""
83
+ return f"{marker}{padding}{label}{padding}{marker}"
60
84
  return re.sub(r"([\\`*_\[\]<>])", r"\\\1", value)
61
85
 
62
86
 
@@ -988,10 +1012,10 @@ def build_report_markdown(
988
1012
  + " |"
989
1013
  )
990
1014
  open_questions = coverage.get("openQuestions", [])
991
- questions = list(open_questions) if isinstance(open_questions, list) else []
1015
+ deferred_questions = []
992
1016
  deferred = coverage.get("deferred", [])
993
1017
  if isinstance(deferred, list):
994
- questions.extend(
1018
+ deferred_questions = [
995
1019
  {
996
1020
  "question": item.get("reason", "Deferred review requires follow-up."),
997
1021
  "followUpPrompt": " ".join(
@@ -1008,9 +1032,14 @@ def build_report_markdown(
1008
1032
  }
1009
1033
  for item in deferred
1010
1034
  if isinstance(item, dict)
1011
- )
1012
- if questions:
1013
- lines.extend(["", "## Open Questions And Follow Up", ""])
1035
+ ]
1036
+ for heading, questions in (
1037
+ ("Deferred Requested Work", deferred_questions),
1038
+ ("Open Questions And Follow Up", open_questions),
1039
+ ):
1040
+ if not isinstance(questions, list) or not questions:
1041
+ continue
1042
+ lines.extend(["", f"## {heading}", ""])
1014
1043
  for question in questions:
1015
1044
  if not isinstance(question, dict):
1016
1045
  continue
@@ -101,10 +101,12 @@ def _scope_lines(scope: Any, label: str, text: Callable[[Any, str], str]) -> lis
101
101
  included = scope.get("includePaths") if isinstance(scope, dict) else None
102
102
  if not isinstance(included, list) or not all(isinstance(path, str) for path in included):
103
103
  return [f"- {label}: not recorded"]
104
- lines = [f"- {label}: {text(', '.join(included), 'none')}"]
104
+ included_text = ", ".join(report._path_text(path, ensure_ascii=True) for path in included)
105
+ lines = [f"- {label}: {included_text or 'none'}"]
105
106
  excluded = scope.get("excludePaths")
106
107
  if isinstance(excluded, list) and excluded and all(isinstance(path, str) for path in excluded):
107
- lines.append(f"- {label} exclusions: {text(', '.join(excluded), 'none')}")
108
+ excluded_text = ", ".join(report._path_text(path, ensure_ascii=True) for path in excluded)
109
+ lines.append(f"- {label} exclusions: {excluded_text or 'none'}")
108
110
  summary = scope.get("summary")
109
111
  if isinstance(summary, str) and summary:
110
112
  lines.append(f"- {label} description: {text(summary, 'not recorded')}")