@openai/codex-security 0.1.17 → 0.1.19

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 (55) hide show
  1. package/README.md +127 -18
  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/core-scan.md +1 -1
  6. package/_bundled_plugin/references/final-report.md +4 -2
  7. package/_bundled_plugin/references/scan-artifacts.md +1 -1
  8. package/_bundled_plugin/references/scan-contract.md +18 -7
  9. package/_bundled_plugin/schemas/scan-manifest.schema.json +2 -2
  10. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +23 -0
  11. package/_bundled_plugin/scripts/deep_scan_workbench.py +88 -1
  12. package/_bundled_plugin/scripts/finalize_scan_contract.py +58 -18
  13. package/_bundled_plugin/scripts/report_projection.py +19 -8
  14. package/_bundled_plugin/scripts/workbench_cli.py +13 -0
  15. package/_bundled_plugin/scripts/workbench_db.py +149 -167
  16. package/_bundled_plugin/scripts/workbench_finding_index.py +101 -0
  17. package/_bundled_plugin/scripts/workbench_remediation.py +19 -0
  18. package/_bundled_plugin/scripts/workbench_saved_results.py +1289 -0
  19. package/_bundled_plugin/scripts/workbench_schema.py +28 -0
  20. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +4 -4
  21. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +1 -1
  22. package/_bundled_plugin/skills/security-scan/SKILL.md +1 -1
  23. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +1 -1
  24. package/dist/api.d.ts +2 -0
  25. package/dist/api.d.ts.map +1 -1
  26. package/dist/api.js +54 -7
  27. package/dist/api.js.map +1 -1
  28. package/dist/cli.d.ts +2 -0
  29. package/dist/cli.d.ts.map +1 -1
  30. package/dist/cli.js +247 -25
  31. package/dist/cli.js.map +1 -1
  32. package/dist/cloud-publish.d.ts +16 -0
  33. package/dist/cloud-publish.d.ts.map +1 -0
  34. package/dist/cloud-publish.js +138 -0
  35. package/dist/cloud-publish.js.map +1 -0
  36. package/dist/contract.d.ts +1 -0
  37. package/dist/contract.d.ts.map +1 -1
  38. package/dist/contract.js +4 -0
  39. package/dist/contract.js.map +1 -1
  40. package/dist/custom-validation-prompt.js +3 -3
  41. package/dist/custom-validation-prompt.js.map +1 -1
  42. package/dist/linear.d.ts.map +1 -1
  43. package/dist/linear.js +17 -6
  44. package/dist/linear.js.map +1 -1
  45. package/dist/models.d.ts +1 -1
  46. package/dist/models.d.ts.map +1 -1
  47. package/dist/models.js.map +1 -1
  48. package/dist/publication.d.ts +1 -0
  49. package/dist/publication.d.ts.map +1 -1
  50. package/dist/publication.js +1 -0
  51. package/dist/publication.js.map +1 -1
  52. package/dist/publish.d.ts +1 -0
  53. package/dist/publish.d.ts.map +1 -1
  54. package/dist/publish.js.map +1 -1
  55. package/package.json +2 -2
@@ -857,6 +857,20 @@ def _recover_unsealed_findings(
857
857
 
858
858
  if previous_position is not None:
859
859
  previous = recovered[previous_position]
860
+ strongest, earlier = (
861
+ (previous, finding)
862
+ if _finding_strength(finding) <= _finding_strength(previous)
863
+ else (finding, previous)
864
+ )
865
+ if strongest != earlier:
866
+ original = copy.deepcopy(earlier)
867
+ older = original["provenance"].pop("previousFindings", [])
868
+ if not isinstance(strongest["provenance"].get("previousFindings"), list):
869
+ strongest["provenance"]["previousFindings"] = []
870
+ history = strongest["provenance"]["previousFindings"]
871
+ for record in [*(older if isinstance(older, list) else []), original]:
872
+ if record not in history:
873
+ history.append(record)
860
874
  if _finding_strength(finding) <= _finding_strength(previous):
861
875
  warnings.append(
862
876
  f"Skipped malformed finding {index + 1}: duplicate logical finding."
@@ -1060,7 +1074,9 @@ def _populate_unsealed_manifest_envelope(
1060
1074
 
1061
1075
  manifest["documentType"] = "codex-security.scan-manifest"
1062
1076
  manifest["schemaVersion"] = SCHEMA_VERSION
1063
- scan["status"] = "completed"
1077
+ scan["status"] = (
1078
+ completion_binding.get("status", "completed") if completion_binding else "completed"
1079
+ )
1064
1080
  scan["coverageRef"] = "coverage.json"
1065
1081
  scan["findingsRef"] = "findings.json"
1066
1082
  if completion_binding is None:
@@ -1188,6 +1204,8 @@ def _validate_completion_binding(
1188
1204
  scan = _require_dict(manifest, "scan", "manifest")
1189
1205
  if scan.get("id") != completion_binding["scanId"]:
1190
1206
  raise ContractError("manifest.scan.id: must match the workbench scan")
1207
+ if scan.get("status") != completion_binding.get("status", "completed"):
1208
+ raise ContractError("manifest.scan.status: must match the workbench outcome")
1191
1209
  if scan.get("startedAt") != completion_binding["startedAt"]:
1192
1210
  raise ContractError("manifest.scan.startedAt: must match the workbench scan")
1193
1211
  if scan.get("completedAt") != completion_binding["completedAt"]:
@@ -1370,8 +1388,8 @@ def _validate_manifest(manifest: dict[str, Any]) -> None:
1370
1388
  scan = _require_dict(manifest, "scan", "manifest")
1371
1389
  for key in ("id", "startedAt", "completedAt", "sealedAt"):
1372
1390
  _require_str(scan, key, "manifest.scan")
1373
- if scan.get("status") != "completed":
1374
- raise ContractError("manifest.scan.status: expected completed")
1391
+ if scan.get("status") not in {"completed", "failed", "canceled", "interrupted"}:
1392
+ raise ContractError("manifest.scan.status: expected a terminal scan outcome")
1375
1393
  producer = _require_dict(scan, "producer", "manifest.scan")
1376
1394
  _require_str(producer, "name", "manifest.scan.producer")
1377
1395
  _require_str(producer, "version", "manifest.scan.producer")
@@ -2175,7 +2193,7 @@ def _artifact_record(
2175
2193
  ) -> dict[str, str]:
2176
2194
  relative_path = _require_portable_relative_path(relative_path, "artifact path")
2177
2195
  if contents is not None:
2178
- _require_scan_local_file(scan_dir, relative_path, relative_path)
2196
+ _validate_scan_local_output_path(scan_dir, scan_dir / relative_path, relative_path)
2179
2197
  return {
2180
2198
  "mediaType": media_type,
2181
2199
  "path": relative_path,
@@ -2292,12 +2310,18 @@ def build_sarif_projection(
2292
2310
  sarif = build_sarif(manifest, findings, source_root)
2293
2311
  run = sarif["runs"][0]
2294
2312
  completeness = coverage["completeness"]
2295
- run["invocations"] = [{"executionSuccessful": completeness == "complete"}]
2296
- if completeness != "complete":
2313
+ scan_status = manifest["scan"]["status"]
2314
+ execution_successful = scan_status == "completed" and completeness == "complete"
2315
+ run["invocations"] = [{"executionSuccessful": execution_successful}]
2316
+ if not execution_successful:
2297
2317
  run["properties"]["codexSecurityCoverageCompleteness"] = completeness
2298
- reasons = [item["reason"] for item in coverage["deferred"]] or [
2299
- f"Scan coverage is {completeness}; results may be incomplete."
2300
- ]
2318
+ reasons = [item["reason"] for item in coverage["deferred"]]
2319
+ if not reasons:
2320
+ reasons = [
2321
+ f"Scan status is {scan_status}; results may be incomplete."
2322
+ if scan_status != "completed"
2323
+ else f"Scan coverage is {completeness}; results may be incomplete."
2324
+ ]
2301
2325
  run["invocations"][0]["toolExecutionNotifications"] = [
2302
2326
  {"level": "warning", "message": {"text": reason}} for reason in reasons
2303
2327
  ]
@@ -2326,6 +2350,13 @@ def csv_cell(value: Any) -> Any:
2326
2350
 
2327
2351
 
2328
2352
  def finding_candidate_id(finding: dict[str, Any]) -> str | None:
2353
+ provenance = finding.get("provenance")
2354
+ if (
2355
+ isinstance(provenance, dict)
2356
+ and isinstance(value := provenance.get("candidateId"), str)
2357
+ and value.strip()
2358
+ ):
2359
+ return value
2329
2360
  extensions = finding.get("extensions")
2330
2361
  if not isinstance(extensions, dict):
2331
2362
  return None
@@ -2517,23 +2548,32 @@ def _prepare_scan_finalization(
2517
2548
  expected_coverage_mode: str | None = None,
2518
2549
  completion_binding: dict[str, Any] | None = None,
2519
2550
  completion_warnings: list[str] | None = None,
2551
+ draft_documents: tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None = None,
2520
2552
  ) -> PreparedScanFinalization:
2521
2553
  """Read, populate, and validate a scan without writing any output files."""
2522
2554
 
2523
2555
  scan_dir = _require_scan_directory(scan_dir)
2524
2556
  schema_dir = schema_dir or Path(__file__).resolve().parent.parent / "schemas"
2525
- manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2557
+ manifest = (
2558
+ copy.deepcopy(draft_documents[0])
2559
+ if draft_documents is not None
2560
+ else _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2561
+ )
2526
2562
  scan = _require_dict(manifest, "scan", "manifest")
2527
2563
  was_sealed = scan.get("sealedAt") is not None or scan.get("artifacts") is not None
2528
2564
  if not was_sealed:
2529
2565
  _populate_unsealed_manifest_envelope(manifest, scan, completion_binding)
2530
2566
  _validate_contract_refs(scan)
2531
- findings, findings_input_bytes = _read_scan_local_json_bytes(
2532
- scan_dir, scan["findingsRef"], scan["findingsRef"]
2533
- )
2534
- coverage, coverage_input_bytes = _read_scan_local_json_bytes(
2535
- scan_dir, scan["coverageRef"], scan["coverageRef"]
2536
- )
2567
+ if draft_documents is None:
2568
+ findings, findings_input_bytes = _read_scan_local_json_bytes(
2569
+ scan_dir, scan["findingsRef"], scan["findingsRef"]
2570
+ )
2571
+ coverage, coverage_input_bytes = _read_scan_local_json_bytes(
2572
+ scan_dir, scan["coverageRef"], scan["coverageRef"]
2573
+ )
2574
+ else:
2575
+ findings, coverage = copy.deepcopy(draft_documents[1:])
2576
+ findings_input_bytes, coverage_input_bytes = _json_bytes(findings), _json_bytes(coverage)
2537
2577
  if not was_sealed:
2538
2578
  _populate_unsealed_artifact_envelope(manifest, findings, coverage, completion_binding)
2539
2579
  _normalize_unsealed_deep_repository_inventory_strategy(
@@ -2544,8 +2584,8 @@ def _prepare_scan_finalization(
2544
2584
 
2545
2585
  if manifest.get("schemaVersion") != SCHEMA_VERSION:
2546
2586
  raise ContractError(f"manifest.schemaVersion: expected {SCHEMA_VERSION}")
2547
- if scan.get("status") != "completed":
2548
- raise ContractError("manifest.scan.status: expected completed before sealing")
2587
+ if scan.get("status") not in {"completed", "failed", "canceled", "interrupted"}:
2588
+ raise ContractError("manifest.scan.status: expected a terminal scan outcome before sealing")
2549
2589
  if (
2550
2590
  expected_coverage_mode is not None
2551
2591
  and completion_binding is not None
@@ -865,6 +865,7 @@ def build_report_markdown(
865
865
  "",
866
866
  "| Field | Value |",
867
867
  "| --- | --- |",
868
+ f"| Scan outcome | {scan.get('status', 'completed')} |",
868
869
  *summary_count_lines,
869
870
  f"| Coverage | {coverage['completeness']} |",
870
871
  f"| Validation mode | {_cell(scope.get('validationMode', 'not recorded'))} |",
@@ -973,20 +974,30 @@ def build_report_markdown(
973
974
  for item in deferred
974
975
  )
975
976
  )
977
+ stopped = manifest.get("scan", {}).get("status") in {
978
+ "failed",
979
+ "canceled",
980
+ "interrupted",
981
+ }
976
982
  lines.extend(
977
983
  [
978
984
  "### No findings",
979
985
  "",
980
986
  (
981
- "No source review completed before the configured time limit. "
982
- "No vulnerability conclusion can be drawn."
983
- if no_source_review
987
+ "No findings were retained before the scan stopped. "
988
+ "The scan did not complete. No vulnerability conclusion can be drawn."
989
+ if stopped
984
990
  else (
985
- "No findings were validated before the scan reached its cost limit. "
986
- "Review the deferred candidates in Open Questions And Follow Up."
987
- if budget_exhausted
988
- else "No reportable findings survived the canonical discovery, validation, "
989
- "and reportability gates."
991
+ "No source review completed before the configured time limit. "
992
+ "No vulnerability conclusion can be drawn."
993
+ if no_source_review
994
+ else (
995
+ "No findings were validated before the scan reached its cost limit. "
996
+ "Review the deferred candidates in Open Questions And Follow Up."
997
+ if budget_exhausted
998
+ else "No reportable findings survived the canonical discovery, validation, "
999
+ "and reportability gates."
1000
+ )
990
1001
  )
991
1002
  ),
992
1003
  ]
@@ -241,6 +241,19 @@ def parse_args(description: str) -> argparse.Namespace:
241
241
  fail_scan.add_argument("--claim-token")
242
242
  fail_scan.add_argument("--cost-json")
243
243
 
244
+ preserve_scan = subparsers.add_parser("preserve-scan-results")
245
+ preserve_scan.add_argument("--scan-id", required=True)
246
+ preserve_scan.add_argument("--thread-id")
247
+ preserve_scan.add_argument("--claim-token")
248
+ preserve_scan.add_argument("--coordinator-generation", type=positive_int)
249
+
250
+ write_scan_draft = subparsers.add_parser("write-scan-draft")
251
+ write_scan_draft.add_argument("--scan-id", required=True)
252
+ write_scan_draft.add_argument("--draft-path", required=True)
253
+ write_scan_draft.add_argument("--checkpoint-path")
254
+ write_scan_draft.add_argument("--expected-draft-digest")
255
+ write_scan_draft.add_argument("--claim-token")
256
+
244
257
  mark_handoff_delivered = subparsers.add_parser("mark-handoff-delivered")
245
258
  mark_handoff_delivered.add_argument("--scan-id", required=True)
246
259
  mark_handoff_delivered.add_argument("--claim-token", required=True)