@openai/codex-security 0.1.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 (178) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +306 -0
  3. package/_bundled_plugin/.app.json +20 -0
  4. package/_bundled_plugin/.codex-plugin/plugin.json +41 -0
  5. package/_bundled_plugin/.mcp.json +20 -0
  6. package/_bundled_plugin/assets/logo.png +0 -0
  7. package/_bundled_plugin/examples/completed-scan/coverage.json +22 -0
  8. package/_bundled_plugin/examples/completed-scan/findings.json +51 -0
  9. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +43 -0
  10. package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
  11. package/_bundled_plugin/mcp/server.mjs +24 -0
  12. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  14. package/_bundled_plugin/preflight/capability-profiles.toml +179 -0
  15. package/_bundled_plugin/references/config-preflight.md +115 -0
  16. package/_bundled_plugin/references/final-report.md +205 -0
  17. package/_bundled_plugin/references/finding-detail-fields.md +162 -0
  18. package/_bundled_plugin/references/sarif-adapter.md +26 -0
  19. package/_bundled_plugin/references/scan-artifacts.md +116 -0
  20. package/_bundled_plugin/references/scan-contract.md +164 -0
  21. package/_bundled_plugin/references/security-guidance.md +15 -0
  22. package/_bundled_plugin/references/shared-hard-rules.md +15 -0
  23. package/_bundled_plugin/references/static-finding-assessment.md +75 -0
  24. package/_bundled_plugin/schemas/coverage.schema.json +228 -0
  25. package/_bundled_plugin/schemas/findings.schema.json +359 -0
  26. package/_bundled_plugin/schemas/scan-manifest.schema.json +332 -0
  27. package/_bundled_plugin/scripts/config_preflight.py +901 -0
  28. package/_bundled_plugin/scripts/deep_scan_config.py +108 -0
  29. package/_bundled_plugin/scripts/deep_scan_workbench.py +1547 -0
  30. package/_bundled_plugin/scripts/filesystem_identity.py +30 -0
  31. package/_bundled_plugin/scripts/finalize_scan_contract.py +2208 -0
  32. package/_bundled_plugin/scripts/finding_preview.py +270 -0
  33. package/_bundled_plugin/scripts/generate_rank_input.py +1013 -0
  34. package/_bundled_plugin/scripts/normalize_candidates.py +320 -0
  35. package/_bundled_plugin/scripts/rank_preview.py +968 -0
  36. package/_bundled_plugin/scripts/report_projection.py +844 -0
  37. package/_bundled_plugin/scripts/resolve_security_md.py +158 -0
  38. package/_bundled_plugin/scripts/snapshot_sqlite.py +26 -0
  39. package/_bundled_plugin/scripts/validate_report_format.py +138 -0
  40. package/_bundled_plugin/scripts/validate_scan_contract.py +108 -0
  41. package/_bundled_plugin/scripts/validate_tracking_source.py +92 -0
  42. package/_bundled_plugin/scripts/windows_scan_local_files.py +612 -0
  43. package/_bundled_plugin/scripts/workbench/__init__.py +1 -0
  44. package/_bundled_plugin/scripts/workbench/handoff.py +238 -0
  45. package/_bundled_plugin/scripts/workbench_cli.py +325 -0
  46. package/_bundled_plugin/scripts/workbench_constants.py +81 -0
  47. package/_bundled_plugin/scripts/workbench_db.py +3728 -0
  48. package/_bundled_plugin/scripts/workbench_native_indexes.py +242 -0
  49. package/_bundled_plugin/scripts/workbench_progress.py +226 -0
  50. package/_bundled_plugin/scripts/workbench_remediation.py +125 -0
  51. package/_bundled_plugin/scripts/workbench_scan_history.py +829 -0
  52. package/_bundled_plugin/scripts/workbench_scan_start.py +149 -0
  53. package/_bundled_plugin/scripts/workbench_schema.py +714 -0
  54. package/_bundled_plugin/scripts/workbench_source_excerpt.py +99 -0
  55. package/_bundled_plugin/scripts/workbench_target.py +469 -0
  56. package/_bundled_plugin/scripts/workbench_target_state.py +63 -0
  57. package/_bundled_plugin/scripts/workbench_validation.py +294 -0
  58. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +117 -0
  59. package/_bundled_plugin/skills/attack-path-analysis/agents/openai.yaml +4 -0
  60. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +76 -0
  61. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +153 -0
  62. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +166 -0
  63. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +4 -0
  64. package/_bundled_plugin/skills/define-security-policy/SKILL.md +93 -0
  65. package/_bundled_plugin/skills/define-security-policy/agents/openai.yaml +4 -0
  66. package/_bundled_plugin/skills/finding-discovery/SKILL.md +155 -0
  67. package/_bundled_plugin/skills/finding-discovery/agents/openai.yaml +4 -0
  68. package/_bundled_plugin/skills/fix-finding/SKILL.md +112 -0
  69. package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +4 -0
  70. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +240 -0
  71. package/_bundled_plugin/skills/propose-security-hardening/agents/openai.yaml +4 -0
  72. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +424 -0
  73. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +167 -0
  74. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +4 -0
  75. package/_bundled_plugin/skills/security-scan/SKILL.md +42 -0
  76. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +4 -0
  77. package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +48 -0
  78. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +85 -0
  79. package/_bundled_plugin/skills/threat-model/SKILL.md +59 -0
  80. package/_bundled_plugin/skills/threat-model/agents/openai.yaml +4 -0
  81. package/_bundled_plugin/skills/threat-model/references/threat-model-guidance.md +48 -0
  82. package/_bundled_plugin/skills/track-findings/SKILL.md +222 -0
  83. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +6 -0
  84. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +54 -0
  85. package/_bundled_plugin/skills/track-findings/references/jira.md +77 -0
  86. package/_bundled_plugin/skills/triage-finding/SKILL.md +342 -0
  87. package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +4 -0
  88. package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +168 -0
  89. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +62 -0
  90. package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +108 -0
  91. package/_bundled_plugin/skills/validation/SKILL.md +110 -0
  92. package/_bundled_plugin/skills/validation/agents/openai.yaml +4 -0
  93. package/_bundled_plugin/skills/validation/references/validation-guidance.md +122 -0
  94. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +263 -0
  95. package/_bundled_plugin/skills/vulnerability-writeup/agents/openai.yaml +4 -0
  96. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +104 -0
  97. package/bin/codex-security.mjs +26 -0
  98. package/dist/api.d.ts +112 -0
  99. package/dist/api.d.ts.map +1 -0
  100. package/dist/api.js +1051 -0
  101. package/dist/api.js.map +1 -0
  102. package/dist/auth.d.ts +29 -0
  103. package/dist/auth.d.ts.map +1 -0
  104. package/dist/auth.js +246 -0
  105. package/dist/auth.js.map +1 -0
  106. package/dist/bulk-scan-discovery.d.ts +35 -0
  107. package/dist/bulk-scan-discovery.d.ts.map +1 -0
  108. package/dist/bulk-scan-discovery.js +217 -0
  109. package/dist/bulk-scan-discovery.js.map +1 -0
  110. package/dist/cli.d.ts +67 -0
  111. package/dist/cli.d.ts.map +1 -0
  112. package/dist/cli.js +2128 -0
  113. package/dist/cli.js.map +1 -0
  114. package/dist/config.d.ts +19 -0
  115. package/dist/config.d.ts.map +1 -0
  116. package/dist/config.js +199 -0
  117. package/dist/config.js.map +1 -0
  118. package/dist/contract.d.ts +21 -0
  119. package/dist/contract.d.ts.map +1 -0
  120. package/dist/contract.js +848 -0
  121. package/dist/contract.js.map +1 -0
  122. package/dist/cost.d.ts +30 -0
  123. package/dist/cost.d.ts.map +1 -0
  124. package/dist/cost.js +280 -0
  125. package/dist/cost.js.map +1 -0
  126. package/dist/errors.d.ts +38 -0
  127. package/dist/errors.d.ts.map +1 -0
  128. package/dist/errors.js +52 -0
  129. package/dist/errors.js.map +1 -0
  130. package/dist/index.d.ts +22 -0
  131. package/dist/index.d.ts.map +1 -0
  132. package/dist/index.js +11 -0
  133. package/dist/index.js.map +1 -0
  134. package/dist/knowledge-base.d.ts +7 -0
  135. package/dist/knowledge-base.d.ts.map +1 -0
  136. package/dist/knowledge-base.js +181 -0
  137. package/dist/knowledge-base.js.map +1 -0
  138. package/dist/models.d.ts +231 -0
  139. package/dist/models.d.ts.map +1 -0
  140. package/dist/models.js +3 -0
  141. package/dist/models.js.map +1 -0
  142. package/dist/multiscan.d.ts +30 -0
  143. package/dist/multiscan.d.ts.map +1 -0
  144. package/dist/multiscan.js +397 -0
  145. package/dist/multiscan.js.map +1 -0
  146. package/dist/result.d.ts +39 -0
  147. package/dist/result.d.ts.map +1 -0
  148. package/dist/result.js +71 -0
  149. package/dist/result.js.map +1 -0
  150. package/dist/runtime.d.ts +69 -0
  151. package/dist/runtime.d.ts.map +1 -0
  152. package/dist/runtime.js +997 -0
  153. package/dist/runtime.js.map +1 -0
  154. package/dist/scan-comparison.d.ts +42 -0
  155. package/dist/scan-comparison.d.ts.map +1 -0
  156. package/dist/scan-comparison.js +153 -0
  157. package/dist/scan-comparison.js.map +1 -0
  158. package/dist/scan-history-renderer.d.ts +13 -0
  159. package/dist/scan-history-renderer.d.ts.map +1 -0
  160. package/dist/scan-history-renderer.js +297 -0
  161. package/dist/scan-history-renderer.js.map +1 -0
  162. package/dist/targets.d.ts +39 -0
  163. package/dist/targets.d.ts.map +1 -0
  164. package/dist/targets.js +295 -0
  165. package/dist/targets.js.map +1 -0
  166. package/dist/trusted-executable.d.ts +6 -0
  167. package/dist/trusted-executable.d.ts.map +1 -0
  168. package/dist/trusted-executable.js +77 -0
  169. package/dist/trusted-executable.js.map +1 -0
  170. package/dist/version.d.ts +6 -0
  171. package/dist/version.d.ts.map +1 -0
  172. package/dist/version.js +42 -0
  173. package/dist/version.js.map +1 -0
  174. package/dist/worker-progress.d.ts +13 -0
  175. package/dist/worker-progress.d.ts.map +1 -0
  176. package/dist/worker-progress.js +113 -0
  177. package/dist/worker-progress.js.map +1 -0
  178. package/package.json +74 -0
@@ -0,0 +1,242 @@
1
+ """Read-only native findings and repository indexes for the Security workbench."""
2
+
3
+ import argparse
4
+ import sqlite3
5
+ import sys
6
+ from collections import Counter
7
+ from collections.abc import Callable, Iterator
8
+ from itertools import islice
9
+ from pathlib import Path
10
+ from typing import Any
11
+
12
+ # Some plugin hosts launch Python with safe-path isolation enabled.
13
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
14
+ import workbench_scan_history as scan_history
15
+ from workbench_constants import FINDING_SUMMARY_BYTES, FINDING_TITLE_BYTES, FINDINGS_PAGE_MAX
16
+ from workbench_validation import bounded_output_text
17
+
18
+
19
+ def list_global_findings(
20
+ connection: sqlite3.Connection,
21
+ args: argparse.Namespace,
22
+ *,
23
+ read_coverage: Callable[[sqlite3.Row], dict[str, Any]],
24
+ ) -> dict[str, Any]:
25
+ limit = min(args.limit, FINDINGS_PAGE_MAX)
26
+ query = args.query.strip().casefold() if args.query else ""
27
+ findings = (
28
+ row
29
+ for row in _active_findings(connection, read_coverage)
30
+ if (args.target_id is None or row["target_id"] == args.target_id)
31
+ and (args.severity is None or row["severity"] == args.severity)
32
+ and (args.status is None or row["status"] == args.status)
33
+ and (
34
+ not query
35
+ or any(
36
+ query in value.casefold()
37
+ for value in (
38
+ row["title"],
39
+ row["summary"],
40
+ row["target_path"],
41
+ row["location_path"],
42
+ )
43
+ if value is not None
44
+ )
45
+ )
46
+ )
47
+ rows = list(islice(findings, args.offset, args.offset + limit + 1))
48
+ has_more = len(rows) > limit
49
+ return {
50
+ "findings": [
51
+ {
52
+ "createdAt": row["created_at"],
53
+ "findingId": row["finding_id"],
54
+ "locationPath": row["location_path"],
55
+ "occurrenceCount": row["occurrence_count"],
56
+ "occurrenceId": row["occurrence_id"],
57
+ "scanId": row["scan_id"],
58
+ "scope": row["scope"],
59
+ "severity": {"level": row["severity"]},
60
+ "status": row["status"],
61
+ "summary": bounded_output_text(row["summary"], FINDING_SUMMARY_BYTES),
62
+ "targetId": row["target_id"],
63
+ "targetPath": row["target_path"],
64
+ "title": bounded_output_text(row["title"], FINDING_TITLE_BYTES),
65
+ "updatedAt": row["updated_at"],
66
+ }
67
+ for row in rows[:limit]
68
+ ],
69
+ "limit": limit,
70
+ "nextOffset": args.offset + limit if has_more else None,
71
+ "offset": args.offset,
72
+ }
73
+
74
+
75
+ def _active_findings(
76
+ connection: sqlite3.Connection,
77
+ read_coverage: Callable[[sqlite3.Row], dict[str, Any]],
78
+ ) -> Iterator[sqlite3.Row]:
79
+ completed_scans_by_target: dict[str, list[sqlite3.Row]] = {}
80
+ for scan in connection.execute(
81
+ """
82
+ SELECT *
83
+ FROM scans
84
+ WHERE status = 'complete' AND seal_manifest_digest IS NOT NULL
85
+ ORDER BY started_at DESC, id DESC
86
+ """
87
+ ):
88
+ completed_scans_by_target.setdefault(scan["target_id"], []).append(scan)
89
+
90
+ coverage_by_scan_id: dict[str, dict[str, Any]] = {}
91
+ rows = connection.execute(
92
+ """
93
+ WITH ranked_findings AS (
94
+ SELECT
95
+ occurrences.id AS occurrence_id,
96
+ occurrences.finding_id,
97
+ occurrences.severity,
98
+ occurrences.created_at,
99
+ scans.id AS scan_id,
100
+ scans.started_at AS scan_started_at,
101
+ scans.target_id,
102
+ targets.current_path AS target_path,
103
+ scans.scope,
104
+ MAX(scans.updated_at, COALESCE(triage.updated_at, '')) AS updated_at,
105
+ COALESCE(triage.status, 'open') AS status,
106
+ COUNT(*) OVER (
107
+ PARTITION BY scans.target_id, occurrences.finding_id
108
+ ) AS occurrence_count,
109
+ ROW_NUMBER() OVER (
110
+ PARTITION BY scans.target_id, occurrences.finding_id
111
+ ORDER BY occurrences.created_at DESC, occurrences.id DESC
112
+ ) AS occurrence_rank
113
+ FROM finding_occurrences AS occurrences
114
+ JOIN scans ON scans.id = occurrences.scan_id
115
+ JOIN security_targets AS targets ON targets.id = scans.target_id
116
+ LEFT JOIN finding_triage AS triage ON triage.occurrence_id = occurrences.id
117
+ )
118
+ SELECT
119
+ selected_findings.*,
120
+ occurrences.title,
121
+ occurrences.summary,
122
+ (
123
+ SELECT locations.relative_path
124
+ FROM finding_locations AS locations
125
+ WHERE locations.occurrence_id = selected_findings.occurrence_id
126
+ ORDER BY
127
+ CASE WHEN locations.role = 'root_control' THEN 0 ELSE 1 END,
128
+ locations.sort_order
129
+ LIMIT 1
130
+ ) AS location_path
131
+ FROM ranked_findings AS selected_findings
132
+ JOIN finding_occurrences AS occurrences
133
+ ON occurrences.id = selected_findings.occurrence_id
134
+ WHERE selected_findings.occurrence_rank = 1
135
+ ORDER BY
136
+ CASE selected_findings.status WHEN 'open' THEN 0 ELSE 1 END,
137
+ CASE selected_findings.severity
138
+ WHEN 'critical' THEN 0
139
+ WHEN 'high' THEN 1
140
+ WHEN 'medium' THEN 2
141
+ WHEN 'low' THEN 3
142
+ WHEN 'informational' THEN 4
143
+ ELSE 5
144
+ END,
145
+ selected_findings.created_at DESC,
146
+ selected_findings.occurrence_id
147
+ """,
148
+ )
149
+ for row in rows:
150
+ resolved = False
151
+ for scan in completed_scans_by_target.get(row["target_id"], ()):
152
+ if (scan["started_at"], scan["id"]) <= (
153
+ row["scan_started_at"],
154
+ row["scan_id"],
155
+ ):
156
+ break
157
+ coverage = coverage_by_scan_id.get(scan["id"])
158
+ if coverage is None:
159
+ coverage = read_coverage(scan)
160
+ coverage_by_scan_id[scan["id"]] = coverage
161
+ if scan_history.scan_covers_path(
162
+ scan,
163
+ target_id=row["target_id"],
164
+ path=row["location_path"],
165
+ coverage=coverage,
166
+ ):
167
+ resolved = True
168
+ break
169
+ if not resolved:
170
+ yield row
171
+
172
+
173
+ def list_repositories(
174
+ connection: sqlite3.Connection,
175
+ args: argparse.Namespace | None = None,
176
+ *,
177
+ read_coverage: Callable[[sqlite3.Row], dict[str, Any]],
178
+ ) -> dict[str, Any]:
179
+ scans = scan_history.list_scans(connection)["scans"]
180
+ scans_by_id = {scan["scanId"]: scan for scan in scans}
181
+ scan_count_by_target: dict[str, int] = {}
182
+ for scan in scans:
183
+ target_id = scan["targetId"]
184
+ scan_count_by_target[target_id] = scan_count_by_target.get(target_id, 0) + 1
185
+
186
+ latest_scan_by_target: dict[str, dict[str, Any]] = {}
187
+ for row in connection.execute(
188
+ "SELECT id, target_id FROM scans ORDER BY started_at DESC, id DESC"
189
+ ):
190
+ latest_scan_by_target.setdefault(row["target_id"], scans_by_id[row["id"]])
191
+
192
+ open_findings_by_target = Counter(
193
+ row["target_id"]
194
+ for row in _active_findings(connection, read_coverage)
195
+ if row["status"] == "open"
196
+ )
197
+ targets = {row["id"]: row for row in connection.execute("SELECT * FROM security_targets")}
198
+ repositories = [
199
+ {
200
+ "checkoutAvailable": Path(target["current_path"]).is_dir(),
201
+ "displayName": target["display_name"],
202
+ "latestScan": latest_scan,
203
+ "openFindingsCount": open_findings_by_target.get(target_id, 0),
204
+ "scanCount": scan_count_by_target[target_id],
205
+ "targetId": target_id,
206
+ "targetPath": target["current_path"],
207
+ }
208
+ for target_id, latest_scan in latest_scan_by_target.items()
209
+ if (target := targets.get(target_id)) is not None
210
+ ]
211
+ if args is None:
212
+ return {"repositories": repositories}
213
+
214
+ query = args.query.strip().casefold() if args.query else ""
215
+ repositories = [
216
+ repository
217
+ for repository in repositories
218
+ if (args.target_id is None or repository["targetId"] == args.target_id)
219
+ and args.status != "not_scanned"
220
+ and (args.status != "open_findings" or repository["openFindingsCount"] > 0)
221
+ and (
222
+ not query
223
+ or query in repository["displayName"].casefold()
224
+ or query in repository["targetPath"].casefold()
225
+ )
226
+ ]
227
+ if args.limit is None and args.offset == 0:
228
+ return {"repositories": repositories}
229
+
230
+ limit = min(args.limit or FINDINGS_PAGE_MAX, FINDINGS_PAGE_MAX)
231
+ page = repositories[args.offset : args.offset + limit]
232
+ next_offset = args.offset + len(page)
233
+ return {
234
+ "repositories": page,
235
+ "limit": limit,
236
+ "nextOffset": next_offset if next_offset < len(repositories) else None,
237
+ "offset": args.offset,
238
+ }
239
+
240
+
241
+ if __name__ == "__main__":
242
+ argparse.ArgumentParser(description=__doc__).parse_args()
@@ -0,0 +1,226 @@
1
+ """Progress transition helpers for the Codex Security workbench."""
2
+
3
+ import argparse
4
+ import json
5
+ import sqlite3
6
+ import sys
7
+ from pathlib import Path
8
+ from typing import Any, Callable
9
+
10
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
11
+ from workbench.handoff import require_current_continuation
12
+ from workbench_constants import PHASES
13
+ from workbench_validation import require_uuid
14
+
15
+ MAX_PREFLIGHT_ISSUES_JSON_BYTES = 64 * 1024
16
+ MAX_PREFLIGHT_ISSUES = 32
17
+
18
+
19
+ def _javascript_string_length(value: str) -> int:
20
+ return len(value.encode("utf-16-le", errors="surrogatepass")) // 2
21
+
22
+
23
+ def _preflight_issue_text(value: Any, maximum: int, label: str) -> str:
24
+ if not isinstance(value, str):
25
+ raise SystemExit(f"Preflight issue {label} must be text.")
26
+ normalized = value.strip()
27
+ if not normalized or _javascript_string_length(normalized) > maximum:
28
+ raise SystemExit(f"Preflight issue {label} must contain 1 to {maximum} characters.")
29
+ return normalized
30
+
31
+
32
+ def preflight_issues_json(value: str | None) -> str | None:
33
+ if value is None:
34
+ return None
35
+ if len(value.encode("utf-8")) > MAX_PREFLIGHT_ISSUES_JSON_BYTES:
36
+ raise SystemExit(
37
+ f"Preflight issues must be no larger than {MAX_PREFLIGHT_ISSUES_JSON_BYTES} bytes."
38
+ )
39
+ try:
40
+ payload = json.loads(value)
41
+ except json.JSONDecodeError as exc:
42
+ raise SystemExit("Preflight issues must be valid JSON.") from exc
43
+ if not isinstance(payload, list) or len(payload) > MAX_PREFLIGHT_ISSUES:
44
+ raise SystemExit(
45
+ f"Preflight issues must be an array of at most {MAX_PREFLIGHT_ISSUES} objects."
46
+ )
47
+ normalized: list[dict[str, str]] = []
48
+ expected_keys = {"capability", "reason", "severity", "status"}
49
+ for index, issue in enumerate(payload):
50
+ label = f"{index + 1}"
51
+ if not isinstance(issue, dict) or set(issue) != expected_keys:
52
+ raise SystemExit(
53
+ f"Preflight issue {label} must contain capability, reason, severity, and status."
54
+ )
55
+ severity = issue.get("severity")
56
+ status = issue.get("status")
57
+ if severity not in {"block", "warn"} or status not in {"fail", "unknown"}:
58
+ raise SystemExit(f"Preflight issue {label} has an invalid severity or status.")
59
+ normalized.append(
60
+ {
61
+ "capability": _preflight_issue_text(
62
+ issue.get("capability"), 128, f"{label} capability"
63
+ ),
64
+ "reason": _preflight_issue_text(issue.get("reason"), 1200, f"{label} reason"),
65
+ "severity": severity,
66
+ "status": status,
67
+ }
68
+ )
69
+ return json.dumps(normalized, ensure_ascii=True, separators=(",", ":"), sort_keys=True)
70
+
71
+
72
+ def reportable_count(
73
+ current_phase: str, requested_phase: str | None, count: int | None
74
+ ) -> int | None:
75
+ if count is None and requested_phase in PHASES[3:] and current_phase in PHASES[:3]:
76
+ return 0
77
+ return count
78
+
79
+
80
+ def update_progress(
81
+ connection: sqlite3.Connection,
82
+ args: argparse.Namespace,
83
+ *,
84
+ now: Callable[[], str],
85
+ require_scan: Callable[[sqlite3.Connection, str], sqlite3.Row],
86
+ scan_context: Callable[[sqlite3.Connection, str], dict[str, Any]],
87
+ ) -> dict[str, Any]:
88
+ scan_id = require_uuid(args.scan_id, "scan-id")
89
+ serialized_preflight_issues = preflight_issues_json(args.preflight_issues_json)
90
+ connection.execute("BEGIN IMMEDIATE")
91
+ try:
92
+ timestamp = now()
93
+ scan = require_scan(connection, scan_id)
94
+ if scan["status"] != "running":
95
+ raise SystemExit("Only a running scan can update progress.")
96
+ require_current_continuation(
97
+ scan,
98
+ args.claim_token,
99
+ error_message="Scan updates are owned by another continuation.",
100
+ )
101
+ if args.deep_review_pass is not None and scan["mode"] != "deep":
102
+ raise SystemExit("Only Deep Scan can record a deep review pass.")
103
+ if serialized_preflight_issues is not None:
104
+ if scan["mode"] == "deep":
105
+ raise SystemExit("Deep Scan preflight progress is owned by its coordinator.")
106
+ if scan["phase"] != "preflight" or args.phase not in {None, "preflight"}:
107
+ raise SystemExit("Preflight issues can only be updated during preflight.")
108
+ progress = connection.execute(
109
+ "SELECT * FROM scan_progress WHERE scan_id = ?", (scan["id"],)
110
+ ).fetchone()
111
+ if args.phase is not None and PHASES.index(args.phase) < PHASES.index(scan["phase"]):
112
+ raise SystemExit("Scan progress cannot move to an earlier phase.")
113
+ next_phase = args.phase or scan["phase"]
114
+ phase_changed = next_phase != scan["phase"]
115
+ phase_total = 0 if phase_changed else progress["phase_items_total"]
116
+ phase_completed = 0 if phase_changed else progress["phase_items_completed"]
117
+ phase_unit = None if phase_changed else progress["phase_progress_unit"]
118
+ if args.phase_items_total is not None:
119
+ phase_total = args.phase_items_total
120
+ if args.phase_items_completed is not None:
121
+ phase_completed = args.phase_items_completed
122
+ if args.phase_progress_unit is not None:
123
+ phase_unit = args.phase_progress_unit
124
+ if phase_completed > phase_total:
125
+ raise SystemExit("Completed phase items cannot exceed total phase items.")
126
+ if phase_total > 0 and phase_unit is None:
127
+ raise SystemExit("Phase progress with a nonzero total requires a progress unit.")
128
+ if not phase_changed:
129
+ if (
130
+ args.phase_items_total is not None
131
+ and args.phase_items_total < progress["phase_items_total"]
132
+ ):
133
+ raise SystemExit("Phase item total cannot decrease within a phase.")
134
+ if (
135
+ args.phase_items_completed is not None
136
+ and args.phase_items_completed < progress["phase_items_completed"]
137
+ ):
138
+ raise SystemExit("Completed phase items cannot decrease within a phase.")
139
+ if (
140
+ args.phase_progress_unit is not None
141
+ and progress["phase_progress_unit"] is not None
142
+ and args.phase_progress_unit != progress["phase_progress_unit"]
143
+ ):
144
+ raise SystemExit("Phase progress unit cannot change within a phase.")
145
+ updates: list[str] = []
146
+ values: list[Any] = []
147
+ if next_phase == "preflight" and scan["mode"] != "deep":
148
+ updates.extend(["preflight_checks_total = ?", "preflight_checks_completed = ?"])
149
+ values.extend([phase_total, phase_completed])
150
+ for column, value in (
151
+ ("preflight_issues_json", serialized_preflight_issues),
152
+ ("review_items_total", args.review_items_total),
153
+ ("review_items_completed", args.review_items_completed),
154
+ (
155
+ "reportable_findings_count",
156
+ reportable_count(scan["phase"], args.phase, args.reportable_findings_count),
157
+ ),
158
+ ("deep_review_pass", args.deep_review_pass),
159
+ ):
160
+ if value is not None:
161
+ updates.append(f"{column} = ?")
162
+ values.append(value)
163
+ current_pass = progress["deep_review_pass"] or 0
164
+ requested_pass = args.deep_review_pass or current_pass
165
+ if requested_pass < current_pass:
166
+ raise SystemExit("Deep Scan progress cannot move to an earlier review pass.")
167
+ advancing_pass = requested_pass > current_pass
168
+ if advancing_pass and args.review_items_completed != 0:
169
+ raise SystemExit("A new Deep Scan review pass must start with zero completed items.")
170
+ if not advancing_pass:
171
+ if (
172
+ args.review_items_total is not None
173
+ and args.review_items_total < progress["review_items_total"]
174
+ ):
175
+ raise SystemExit("Review item total cannot decrease within a review pass.")
176
+ if (
177
+ args.review_items_completed is not None
178
+ and args.review_items_completed < progress["review_items_completed"]
179
+ ):
180
+ raise SystemExit("Completed review items cannot decrease within a review pass.")
181
+ total = args.review_items_total
182
+ if total is None:
183
+ total = progress["review_items_total"]
184
+ completed = args.review_items_completed
185
+ if completed is None:
186
+ completed = progress["review_items_completed"]
187
+ if completed > total:
188
+ raise SystemExit("Completed review items cannot exceed total review items.")
189
+ updated = connection.execute(
190
+ """
191
+ UPDATE scans
192
+ SET phase = COALESCE(?, phase), updated_at = ?
193
+ WHERE id = ? AND status = 'running'
194
+ """,
195
+ (args.phase, timestamp, scan["id"]),
196
+ )
197
+ if updated.rowcount != 1:
198
+ raise SystemExit("Only a running scan can update progress.")
199
+ if updates:
200
+ connection.execute(
201
+ f"UPDATE scan_progress SET {', '.join(updates)}, updated_at = ? WHERE scan_id = ?",
202
+ (*values, timestamp, scan["id"]),
203
+ )
204
+ else:
205
+ connection.execute(
206
+ "UPDATE scan_progress SET updated_at = ? WHERE scan_id = ?",
207
+ (timestamp, scan["id"]),
208
+ )
209
+ connection.execute(
210
+ """
211
+ UPDATE scan_progress
212
+ SET phase_items_total = ?, phase_items_completed = ?,
213
+ phase_progress_unit = ?, updated_at = ?
214
+ WHERE scan_id = ?
215
+ """,
216
+ (phase_total, phase_completed, phase_unit, timestamp, scan["id"]),
217
+ )
218
+ connection.commit()
219
+ except BaseException:
220
+ connection.rollback()
221
+ raise
222
+ return scan_context(connection, scan["id"])
223
+
224
+
225
+ if __name__ == "__main__":
226
+ argparse.ArgumentParser(description=__doc__).parse_args()
@@ -0,0 +1,125 @@
1
+ """Durable remediation state transitions for the Codex Security workbench."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import sqlite3
7
+ import sys
8
+ from datetime import datetime, timezone
9
+ from pathlib import Path
10
+ from typing import Any
11
+
12
+ # Some plugin hosts launch Python with safe-path isolation enabled.
13
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
14
+ from workbench_validation import require_occurrence, require_uuid
15
+
16
+
17
+ def register_cancel_finding_remediation_request(subparsers: Any) -> None:
18
+ parser = subparsers.add_parser("cancel-finding-remediation-request")
19
+ parser.add_argument("--occurrence-id", required=True)
20
+ parser.add_argument("--request-id", required=True)
21
+ parser.add_argument("--action-token", required=True)
22
+
23
+
24
+ def cancel_finding_remediation_request(
25
+ connection: sqlite3.Connection, args: argparse.Namespace
26
+ ) -> str:
27
+ request_id = require_uuid(args.request_id, "request-id")
28
+ action_token = require_uuid(args.action_token, "action-token")
29
+ connection.execute("BEGIN IMMEDIATE")
30
+ try:
31
+ occurrence = require_occurrence(connection, args.occurrence_id)
32
+ current = connection.execute(
33
+ "SELECT * FROM finding_remediation_attempts WHERE request_id = ?",
34
+ (request_id,),
35
+ ).fetchone()
36
+ if current is None:
37
+ connection.commit()
38
+ return str(occurrence["scan_id"])
39
+ if current["occurrence_id"] != occurrence["id"]:
40
+ raise SystemExit("This remediation request belongs to a different finding.")
41
+ if current["pending_action"] is None:
42
+ connection.commit()
43
+ return str(occurrence["scan_id"])
44
+ if current["state"] == "failed" and current["pending_action_claim_token"] is None:
45
+ connection.commit()
46
+ return str(occurrence["scan_id"])
47
+ if current["pending_action_claim_token"] != action_token:
48
+ raise SystemExit("This remediation host request is owned by a different action token.")
49
+ timestamp = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
50
+ if current["state"] == "failed":
51
+ connection.execute(
52
+ """
53
+ UPDATE finding_remediation_attempts
54
+ SET pending_action_claimed_at = NULL, pending_action_claim_token = NULL,
55
+ pending_action_delivered_at = NULL, updated_at = ?
56
+ WHERE request_id = ? AND pending_action_claim_token = ?
57
+ """,
58
+ (timestamp, request_id, action_token),
59
+ )
60
+ elif current["pending_action"] == "generate":
61
+ _cancel_generation(
62
+ connection, occurrence["id"], request_id, timestamp, current["state"]
63
+ )
64
+ connection.execute(
65
+ "UPDATE scans SET updated_at = ? WHERE id = ?",
66
+ (timestamp, occurrence["scan_id"]),
67
+ )
68
+ else:
69
+ connection.execute(
70
+ """
71
+ UPDATE finding_remediation_attempts
72
+ SET pending_action = NULL, pending_action_claimed_at = NULL,
73
+ pending_action_claim_token = NULL, pending_action_delivered_at = NULL,
74
+ version = version + 1, updated_at = ?
75
+ WHERE request_id = ? AND pending_action_claim_token = ?
76
+ """,
77
+ (timestamp, request_id, action_token),
78
+ )
79
+ connection.commit()
80
+ except BaseException:
81
+ connection.rollback()
82
+ raise
83
+ return str(occurrence["scan_id"])
84
+
85
+
86
+ def _cancel_generation(
87
+ connection: sqlite3.Connection,
88
+ occurrence_id: str,
89
+ request_id: str,
90
+ timestamp: str,
91
+ state: str,
92
+ ) -> None:
93
+ if state != "requested":
94
+ raise SystemExit("Only a requested patch generation can be canceled.")
95
+ connection.execute(
96
+ "DELETE FROM finding_remediation_attempts WHERE request_id = ?", (request_id,)
97
+ )
98
+ previous = connection.execute(
99
+ """
100
+ SELECT * FROM finding_remediation_attempts
101
+ WHERE occurrence_id = ?
102
+ ORDER BY created_at DESC, rowid DESC
103
+ LIMIT 1
104
+ """,
105
+ (occurrence_id,),
106
+ ).fetchone()
107
+ if previous is None or previous["state"] != "superseded":
108
+ return
109
+ restored_state = "applied" if previous["applied_content_digest"] is not None else "generated"
110
+ connection.execute(
111
+ """
112
+ UPDATE finding_remediation_attempts
113
+ SET state = ?, version = version + 1, updated_at = ?
114
+ WHERE request_id = ? AND state = 'superseded'
115
+ """,
116
+ (restored_state, timestamp, previous["request_id"]),
117
+ )
118
+
119
+
120
+ def main() -> None:
121
+ argparse.ArgumentParser(description=__doc__).parse_args()
122
+
123
+
124
+ if __name__ == "__main__":
125
+ main()