@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,3728 @@
1
+ #!/usr/bin/env python3
2
+ """Persist Codex Security workbench state in a local SQLite database."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import csv
8
+ import errno
9
+ import hashlib
10
+ import io
11
+ import json
12
+ import os
13
+ import re
14
+ import sqlite3
15
+ import stat
16
+ import sys
17
+ import tempfile
18
+ import time
19
+ import uuid
20
+ from contextlib import closing, contextmanager
21
+ from datetime import datetime, timedelta, timezone
22
+ from pathlib import Path, PurePosixPath
23
+ from typing import Any
24
+
25
+ try:
26
+ import fcntl as posix_file_lock
27
+ except ModuleNotFoundError: # pragma: no cover - exercised through the Windows lock test.
28
+ posix_file_lock = None
29
+
30
+ try:
31
+ import msvcrt as windows_file_lock
32
+ except ModuleNotFoundError: # pragma: no cover - msvcrt is only available on Windows.
33
+ windows_file_lock = None
34
+
35
+ # Some plugin hosts launch Python with safe-path isolation enabled.
36
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
37
+ import deep_scan_workbench as deep_scan
38
+ import workbench_native_indexes as native_indexes
39
+ import workbench_progress as progress
40
+ import workbench_remediation as remediation
41
+ import workbench_scan_history as scan_history
42
+ from filesystem_identity import serialize_filesystem_identity as serialize_filesystem_identity
43
+ from filesystem_identity import stored_filesystem_identity_matches
44
+ from finalize_scan_contract import (
45
+ PRODUCER_NAME,
46
+ ContractError,
47
+ _prepare_scan_finalization,
48
+ _write_prepared_scan_finalization,
49
+ csv_cell,
50
+ finalize_scan,
51
+ finding_candidate_id,
52
+ open_scan_local_file_descriptor,
53
+ write_sarif_projection,
54
+ write_scan_local_bytes,
55
+ )
56
+ from finding_preview import bounded_finding_details
57
+ from workbench import handoff
58
+ from workbench_cli import parse_args
59
+ from workbench_constants import (
60
+ ARTIFACTS,
61
+ CLAIM_LEASE_SECONDS,
62
+ DELIVERED_ACTION_LEASE_SECONDS,
63
+ DIFF_TARGET_KINDS,
64
+ EMPTY_GIT_TREE,
65
+ FINDING_ABSOLUTE_PATH_BYTES,
66
+ FINDING_LEVEL_BYTES,
67
+ FINDING_LOCATION_PATH_BYTES,
68
+ FINDING_LOCATION_ROLE_BYTES,
69
+ FINDING_LOCATIONS_LIMIT,
70
+ FINDING_REMEDIATION_BYTES,
71
+ FINDING_SUMMARY_BYTES,
72
+ FINDING_TITLE_BYTES,
73
+ FINDINGS_PAGE_MAX,
74
+ FINDINGS_RESULT_LIMIT,
75
+ PATCH_ARTIFACT_MAX_BYTES,
76
+ PATCH_PREVIEW_BYTES,
77
+ SQLITE_RETRY_ATTEMPTS,
78
+ )
79
+ from workbench_scan_start import (
80
+ compact_timestamp,
81
+ insert_running_scan,
82
+ safe_segment,
83
+ scan_diff_identity,
84
+ scan_target_identity,
85
+ )
86
+ from workbench_schema import MIGRATIONS, normalize_pre_release_migrations, sql_statements
87
+ from workbench_source_excerpt import finding_source_excerpt
88
+ from workbench_target import (
89
+ clean_worktree_content_digest,
90
+ copy_directory_excluding,
91
+ copy_git_worktree_files,
92
+ directory_content_digest,
93
+ directory_snapshot_regular_file_count,
94
+ git_command,
95
+ git_output,
96
+ git_revision,
97
+ git_submodule_paths,
98
+ git_target_metadata,
99
+ git_worktree_context,
100
+ worktree_content_digest,
101
+ worktree_content_digest_for_context,
102
+ )
103
+ from workbench_target_state import backfill_security_targets, ensure_security_target
104
+ from workbench_validation import (
105
+ bounded_output_text,
106
+ capability_preflight_input,
107
+ capability_preflight_json,
108
+ optional_text,
109
+ parse_scan_cost,
110
+ require_occurrence,
111
+ require_uuid,
112
+ )
113
+
114
+ FINDING_ARTIFACT_DIRECTORIES_LIMIT = 80
115
+ FINDING_ARTIFACTS_LIMIT = 40
116
+ FINDING_WRITEUP_REPORT_PATH = re.compile(r"^findings/([a-z0-9][a-z0-9._-]*)/\1\.md$")
117
+ SCAN_RECIPE_MAX_BYTES = 256 * 1024
118
+
119
+
120
+ def now() -> str:
121
+ return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
122
+
123
+
124
+ def stale_claim_before(seconds: int = CLAIM_LEASE_SECONDS) -> str:
125
+ return (
126
+ (datetime.now(timezone.utc) - timedelta(seconds=seconds)).isoformat().replace("+00:00", "Z")
127
+ )
128
+
129
+
130
+ def remediation_claim_is_active(remediation: sqlite3.Row) -> bool:
131
+ if remediation["pending_action_claim_token"] is None:
132
+ return False
133
+ delivered_at = remediation["pending_action_delivered_at"]
134
+ claimed_at = delivered_at or remediation["pending_action_claimed_at"]
135
+ if not isinstance(claimed_at, str):
136
+ return True
137
+ try:
138
+ parsed = datetime.fromisoformat(claimed_at)
139
+ if parsed.tzinfo is None:
140
+ return True
141
+ except ValueError:
142
+ return True
143
+ lease_seconds = DELIVERED_ACTION_LEASE_SECONDS if delivered_at else CLAIM_LEASE_SECONDS
144
+ return parsed > datetime.now(timezone.utc) - timedelta(seconds=lease_seconds)
145
+
146
+
147
+ def state_dir() -> Path:
148
+ state_dir = os.environ.get("CODEX_SECURITY_STATE_DIR")
149
+ if state_dir:
150
+ return Path(state_dir).expanduser().resolve()
151
+ codex_home = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
152
+ return (codex_home / "state" / "plugins" / "codex-security").resolve()
153
+
154
+
155
+ def database_path() -> Path:
156
+ return state_dir() / "workbench.sqlite3"
157
+
158
+
159
+ @contextmanager
160
+ def scan_completion_lock(scan_id: str) -> Any:
161
+ lock_dir = state_dir() / "completion-locks"
162
+ lock_dir.mkdir(parents=True, exist_ok=True)
163
+ lock_path = lock_dir / f"{require_uuid(scan_id, 'scan-id')}.lock"
164
+ descriptor = os.open(
165
+ lock_path,
166
+ os.O_RDWR | os.O_CREAT | getattr(os, "O_BINARY", 0),
167
+ 0o600,
168
+ )
169
+ locked = False
170
+ try:
171
+ acquire_completion_file_lock(descriptor)
172
+ locked = True
173
+ yield
174
+ finally:
175
+ try:
176
+ if locked:
177
+ release_completion_file_lock(descriptor)
178
+ finally:
179
+ os.close(descriptor)
180
+
181
+
182
+ def is_file_lock_contention(error: OSError) -> bool:
183
+ return error.errno in {errno.EACCES, errno.EAGAIN, errno.EDEADLK}
184
+
185
+
186
+ def acquire_completion_file_lock(descriptor: int) -> None:
187
+ if posix_file_lock is not None:
188
+ posix_file_lock.flock(descriptor, posix_file_lock.LOCK_EX)
189
+ return
190
+ if windows_file_lock is None:
191
+ raise SystemExit("Scan completion requires operating-system file locking support.")
192
+
193
+ # msvcrt locks a byte range. Seed a newly-created lock file before locking its
194
+ # first byte, and retry if another process locks that byte between our checks.
195
+ while os.fstat(descriptor).st_size == 0:
196
+ os.lseek(descriptor, 0, os.SEEK_SET)
197
+ try:
198
+ os.write(descriptor, b"\0")
199
+ except OSError as exc:
200
+ if not is_file_lock_contention(exc):
201
+ raise
202
+ time.sleep(0.05)
203
+
204
+ while True:
205
+ os.lseek(descriptor, 0, os.SEEK_SET)
206
+ try:
207
+ windows_file_lock.locking(descriptor, windows_file_lock.LK_NBLCK, 1)
208
+ return
209
+ except OSError as exc:
210
+ if not is_file_lock_contention(exc):
211
+ raise
212
+ time.sleep(0.05)
213
+
214
+
215
+ def release_completion_file_lock(descriptor: int) -> None:
216
+ if posix_file_lock is not None:
217
+ posix_file_lock.flock(descriptor, posix_file_lock.LOCK_UN)
218
+ return
219
+ if windows_file_lock is None:
220
+ return
221
+ os.lseek(descriptor, 0, os.SEEK_SET)
222
+ windows_file_lock.locking(descriptor, windows_file_lock.LK_UNLCK, 1)
223
+
224
+
225
+ def connect() -> sqlite3.Connection:
226
+ path = database_path()
227
+ path.parent.mkdir(parents=True, exist_ok=True)
228
+ for attempt in range(SQLITE_RETRY_ATTEMPTS):
229
+ connection = sqlite3.connect(path, timeout=5)
230
+ try:
231
+ connection.row_factory = sqlite3.Row
232
+ connection.execute("PRAGMA foreign_keys = ON")
233
+ connection.execute("PRAGMA busy_timeout = 5000")
234
+ apply_migrations(connection)
235
+ connection.execute("PRAGMA journal_mode = WAL")
236
+ path.chmod(0o600)
237
+ return connection
238
+ except sqlite3.OperationalError as exc:
239
+ connection.close()
240
+ if attempt == SQLITE_RETRY_ATTEMPTS - 1 or not sqlite_busy(exc):
241
+ raise
242
+ time.sleep(0.05 * (2**attempt))
243
+ raise AssertionError("SQLite retry loop exhausted unexpectedly.")
244
+
245
+
246
+ def sqlite_busy(error: sqlite3.OperationalError) -> bool:
247
+ return "locked" in str(error).lower() or "busy" in str(error).lower()
248
+
249
+
250
+ def setup_preference(connection: sqlite3.Connection) -> dict[str, bool]:
251
+ row = connection.execute(
252
+ "SELECT skip_setup_ui FROM setup_preferences WHERE singleton = 1"
253
+ ).fetchone()
254
+ return {"skipSetupUi": bool(row["skip_setup_ui"]) if row is not None else False}
255
+
256
+
257
+ def record_setup_ui_disabled(connection: sqlite3.Connection, timestamp: str) -> None:
258
+ connection.execute(
259
+ """
260
+ INSERT INTO setup_preferences (singleton, skip_setup_ui, updated_at)
261
+ VALUES (1, ?, ?)
262
+ ON CONFLICT(singleton) DO UPDATE SET
263
+ skip_setup_ui = excluded.skip_setup_ui,
264
+ updated_at = excluded.updated_at
265
+ """,
266
+ (1, timestamp),
267
+ )
268
+
269
+
270
+ def disable_setup_ui(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
271
+ workspace_id = require_uuid(args.workspace_id, "workspace-id")
272
+ try:
273
+ connection.execute("BEGIN IMMEDIATE")
274
+ require_workspace(connection, workspace_id)
275
+ record_setup_ui_disabled(connection, now())
276
+ connection.commit()
277
+ except BaseException:
278
+ connection.rollback()
279
+ raise
280
+ return workspace_state(connection, workspace_id)
281
+
282
+
283
+ def apply_migrations(connection: sqlite3.Connection) -> None:
284
+ connection.commit()
285
+ connection.execute("BEGIN IMMEDIATE")
286
+ try:
287
+ connection.execute(
288
+ """
289
+ CREATE TABLE IF NOT EXISTS schema_migrations (
290
+ version INTEGER PRIMARY KEY,
291
+ name TEXT NOT NULL,
292
+ applied_at TEXT NOT NULL
293
+ )
294
+ """
295
+ )
296
+ normalize_pre_release_migrations(connection, now())
297
+ applied = {
298
+ row["version"] for row in connection.execute("SELECT version FROM schema_migrations")
299
+ }
300
+ for version, name, sql in MIGRATIONS:
301
+ if version in applied:
302
+ continue
303
+ for statement in sql_statements(sql):
304
+ connection.execute(statement)
305
+ connection.execute(
306
+ "INSERT INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)",
307
+ (version, name, now()),
308
+ )
309
+ if 16 not in applied:
310
+ backfill_security_targets(connection)
311
+ connection.commit()
312
+ except BaseException:
313
+ connection.rollback()
314
+ raise
315
+
316
+
317
+ def require_target(value: str) -> Path:
318
+ expanded = Path(value).expanduser()
319
+ if not expanded.is_absolute():
320
+ raise SystemExit("Scan target must be an absolute local directory path.")
321
+ target = expanded.resolve()
322
+ if not target.is_dir():
323
+ raise SystemExit(f"Scan target is not a readable local directory: {target}")
324
+ return target
325
+
326
+
327
+ def require_remediation_target(value: str) -> Path:
328
+ stored = Path(value).expanduser()
329
+ if not stored.is_absolute():
330
+ raise SystemExit("Remediation target must be an absolute local directory path.")
331
+ try:
332
+ resolved = stored.resolve(strict=True)
333
+ except (FileNotFoundError, OSError) as exc:
334
+ raise SystemExit(
335
+ "Remediation is unavailable because the selected checkout is no longer accessible."
336
+ ) from exc
337
+ if resolved != stored or not stored.is_dir():
338
+ raise SystemExit(
339
+ "Remediation is unavailable because the selected checkout path was replaced. Start a new scan."
340
+ )
341
+ return stored
342
+
343
+
344
+ def require_scan_target_identity(scan: sqlite3.Row) -> Path:
345
+ target = require_remediation_target(scan["target_path"])
346
+ expected_device = scan["target_device"]
347
+ expected_inode = scan["target_inode"]
348
+ if expected_device is None or expected_inode is None:
349
+ raise SystemExit(
350
+ "Remediation is unavailable because this scan does not record checkout identity. "
351
+ "Start a new scan."
352
+ )
353
+ try:
354
+ metadata = target.stat()
355
+ except OSError as exc:
356
+ raise SystemExit(
357
+ "Remediation is unavailable because the selected checkout is no longer accessible."
358
+ ) from exc
359
+ if not (
360
+ stored_filesystem_identity_matches(expected_device, metadata.st_dev)
361
+ and stored_filesystem_identity_matches(expected_inode, metadata.st_ino)
362
+ ):
363
+ raise SystemExit(
364
+ "Remediation is unavailable because the selected checkout path was replaced. "
365
+ "Start a new scan."
366
+ )
367
+ return target
368
+
369
+
370
+ def inspect_target(target_path: str) -> dict[str, Any]:
371
+ target = require_target(target_path)
372
+ return {
373
+ "displayName": target.name,
374
+ "targetMetadata": git_target_metadata(target),
375
+ "targetPath": str(target),
376
+ }
377
+
378
+
379
+ def resolve_git_commit(target: Path, revision: str, label: str) -> str:
380
+ value = optional_text(revision, maximum=512)
381
+ if not value:
382
+ raise SystemExit(f"{label} is required.")
383
+ resolved = git_output(
384
+ target,
385
+ "rev-parse",
386
+ "--verify",
387
+ "--end-of-options",
388
+ f"{value}^{{commit}}",
389
+ )
390
+ if resolved is None:
391
+ raise SystemExit(f"{label} does not resolve to a local Git commit: {value}")
392
+ return resolved
393
+
394
+
395
+ def require_diff_target(
396
+ target: Path,
397
+ kind: str | None,
398
+ base_revision: str | None,
399
+ head_revision: str | None,
400
+ content_digest: str | None,
401
+ ) -> dict[str, str]:
402
+ current_head = require_review_changes_target(target)
403
+ if kind not in DIFF_TARGET_KINDS:
404
+ raise SystemExit("Choose which Git changes to review before starting a diff scan.")
405
+ if kind == "working_tree":
406
+ base = resolve_git_commit(target, base_revision or "HEAD", "Working-tree base")
407
+ head = resolve_git_commit(target, head_revision or current_head, "Working-tree HEAD")
408
+ current_digest = worktree_content_digest(target)
409
+ if base != current_head or head != current_head:
410
+ raise SystemExit(
411
+ "Repository HEAD changed after these working-tree changes were selected. "
412
+ "Select Uncommitted changes again."
413
+ )
414
+ if content_digest and content_digest != current_digest:
415
+ raise SystemExit(
416
+ "Working-tree contents changed after they were selected. "
417
+ "Select Uncommitted changes again."
418
+ )
419
+ return {
420
+ "kind": kind,
421
+ "baseRevision": current_head,
422
+ "headRevision": current_head,
423
+ "contentDigest": current_digest,
424
+ }
425
+ if kind == "commit":
426
+ head = resolve_git_commit(target, head_revision or "", "Commit")
427
+ commit = git_output(target, "cat-file", "-p", head)
428
+ if commit is None:
429
+ raise SystemExit(f"Commit is not available in the local checkout: {head}")
430
+ parent_line = next(
431
+ (line for line in commit.splitlines() if line.startswith("parent ")),
432
+ None,
433
+ )
434
+ if parent_line is None:
435
+ parent = EMPTY_GIT_TREE
436
+ else:
437
+ parent = resolve_git_commit(
438
+ target,
439
+ parent_line.removeprefix("parent ").strip(),
440
+ "Commit parent",
441
+ )
442
+ if base_revision and base_revision != parent:
443
+ supplied_base = (
444
+ base_revision
445
+ if base_revision == EMPTY_GIT_TREE
446
+ else resolve_git_commit(target, base_revision, "Commit base")
447
+ )
448
+ if supplied_base != parent:
449
+ raise SystemExit("Commit base revision must match the selected commit's parent.")
450
+ return {"kind": kind, "baseRevision": parent, "headRevision": head}
451
+ base = resolve_git_commit(target, base_revision or "", "Base revision")
452
+ head = resolve_git_commit(target, head_revision or "", "Head revision")
453
+ if base == head:
454
+ raise SystemExit("Base and head revisions must identify different commits.")
455
+ return {"kind": kind, "baseRevision": base, "headRevision": head}
456
+
457
+
458
+ def inspect_setup_values(
459
+ target_path: str,
460
+ scope: str,
461
+ mode: str,
462
+ diff_target_kind: str | None,
463
+ diff_base_revision: str | None,
464
+ diff_head_revision: str | None,
465
+ diff_content_digest: str | None,
466
+ ) -> dict[str, Any]:
467
+ target = require_target(target_path)
468
+ require_scannable_target(target)
469
+ normalized_scope = require_scope(scope, mode, target)
470
+ if mode == "diff" and normalized_scope != ".":
471
+ raise SystemExit("Review changes requires the whole target; use scope '.'.")
472
+ if mode != "diff" and any(
473
+ value is not None
474
+ for value in (
475
+ diff_target_kind,
476
+ diff_base_revision,
477
+ diff_head_revision,
478
+ diff_content_digest,
479
+ )
480
+ ):
481
+ raise SystemExit("A Git diff target requires Review changes mode.")
482
+ diff_target = (
483
+ require_diff_target(
484
+ target,
485
+ diff_target_kind,
486
+ diff_base_revision,
487
+ diff_head_revision,
488
+ diff_content_digest,
489
+ )
490
+ if mode == "diff"
491
+ else None
492
+ )
493
+ return {
494
+ "diffTarget": diff_target,
495
+ "scope": normalized_scope,
496
+ "target": inspect_target(str(target)),
497
+ }
498
+
499
+
500
+ def inspect_setup(args: argparse.Namespace) -> dict[str, Any]:
501
+ return inspect_setup_values(
502
+ args.target_path,
503
+ args.scope,
504
+ args.mode,
505
+ args.diff_target_kind,
506
+ args.diff_base_revision,
507
+ args.diff_head_revision,
508
+ args.diff_content_digest,
509
+ )
510
+
511
+
512
+ def require_git_worktree_head(target: Path) -> str:
513
+ metadata = git_target_metadata(target)
514
+ if not metadata["isGit"] or not metadata["isWorktree"] or not metadata["hasHead"]:
515
+ raise SystemExit("Review changes requires a non-bare Git worktree with a resolvable HEAD.")
516
+ return str(metadata["revision"])
517
+
518
+
519
+ def require_review_changes_target(target: Path) -> str:
520
+ revision = require_git_worktree_head(target)
521
+ repository_root = git_output(target, "rev-parse", "--show-toplevel")
522
+ if repository_root is None or Path(repository_root).resolve() != target:
523
+ raise SystemExit(
524
+ "Review changes requires the checked-out Git repository root as the target."
525
+ )
526
+ return revision
527
+
528
+
529
+ def require_scannable_target(target: Path) -> None:
530
+ metadata = git_target_metadata(target)
531
+ if metadata["isGit"] and not metadata["isWorktree"]:
532
+ raise SystemExit(
533
+ "Codex Security requires a checked-out worktree, not a bare Git repository."
534
+ )
535
+
536
+
537
+ def expected_target_kinds(scan: sqlite3.Row) -> list[str]:
538
+ if scan["mode"] == "diff":
539
+ return ["git_diff"]
540
+ if scan["target_revision"] == "unversioned":
541
+ return ["directory_snapshot"]
542
+ if scan["target_snapshot_digest"] is None:
543
+ return ["git_worktree", "git_revision"]
544
+ if scan["target_snapshot_digest"] == clean_worktree_content_digest():
545
+ return ["git_revision"]
546
+ return ["git_worktree"]
547
+
548
+
549
+ def stored_diff_target(row: sqlite3.Row) -> dict[str, str] | None:
550
+ if not row["diff_target_kind"]:
551
+ return None
552
+ target = {
553
+ "baseRevision": row["diff_base_revision"],
554
+ "headRevision": row["diff_head_revision"],
555
+ "kind": row["diff_target_kind"],
556
+ }
557
+ if row["diff_content_digest"]:
558
+ target["contentDigest"] = row["diff_content_digest"]
559
+ return target
560
+
561
+
562
+ def requested_scan_paths(scan: sqlite3.Row) -> list[str]:
563
+ if "recipe_json" in scan.keys() and scan["recipe_json"] is not None:
564
+ recipe = json.loads(scan["recipe_json"], parse_constant=reject_non_finite_json)
565
+ target = recipe["target"]
566
+ if target["kind"] == "paths":
567
+ return target["paths"]
568
+ return [scan["scope"]]
569
+
570
+
571
+ def scan_contract(scan: sqlite3.Row) -> dict[str, Any]:
572
+ target = Path(scan["target_path"])
573
+ target_contract = {
574
+ "allowedKinds": expected_target_kinds(scan),
575
+ "displayName": target.name,
576
+ "targetId": scan["target_id"],
577
+ }
578
+ if (
579
+ scan["mode"] != "diff"
580
+ and scan["target_snapshot_digest"]
581
+ and (
582
+ scan["target_revision"] == "unversioned"
583
+ or scan["target_snapshot_digest"] != clean_worktree_content_digest()
584
+ )
585
+ ):
586
+ target_contract["requiredSnapshotDigest"] = scan["target_snapshot_digest"]
587
+ return {
588
+ "diffTarget": stored_diff_target(scan),
589
+ "scope": {
590
+ "requiredExcludePaths": [],
591
+ "requestedPath": scan["scope"],
592
+ **(
593
+ {"requiredIncludePaths": requested_scan_paths(scan)}
594
+ if scan["mode"] != "diff"
595
+ else {}
596
+ ),
597
+ },
598
+ "target": target_contract,
599
+ }
600
+
601
+
602
+ def expected_coverage_mode(scan: sqlite3.Row) -> str:
603
+ if scan["mode"] == "diff":
604
+ mode = {
605
+ "commit": "commit",
606
+ "range": "branch_diff",
607
+ "working_tree": "working_tree",
608
+ }.get(scan["diff_target_kind"])
609
+ if mode is None:
610
+ raise SystemExit("This migrated diff scan does not have a validated change set.")
611
+ return mode
612
+ if scan["scope"] != "." or (
613
+ "recipe_json" in scan.keys()
614
+ and scan["recipe_json"] is not None
615
+ and json.loads(scan["recipe_json"])["target"]["kind"] == "paths"
616
+ ):
617
+ return "scoped_path"
618
+ return "deep_repository" if scan["mode"] == "deep" else "repository"
619
+
620
+
621
+ def workbench_completion_binding(scan: sqlite3.Row, completed_at: str) -> dict[str, Any]:
622
+ """Return deterministic draft fields owned by the selected workbench scan."""
623
+
624
+ contract = scan_contract(scan)
625
+ target_contract = contract["target"]
626
+ plugin_manifest = read_json_object(
627
+ Path(__file__).resolve().parent.parent / ".codex-plugin" / "plugin.json"
628
+ )
629
+ plugin_version = plugin_manifest.get("version")
630
+ if not isinstance(plugin_version, str) or not plugin_version:
631
+ raise SystemExit("plugin.json: expected a nonempty Codex Security plugin version.")
632
+ target: dict[str, Any] = {
633
+ "targetId": target_contract["targetId"],
634
+ "displayName": target_contract["displayName"],
635
+ }
636
+ if scan["mode"] == "diff":
637
+ target["baseRevision"] = scan["diff_base_revision"]
638
+ target["headRevision"] = scan["diff_head_revision"]
639
+ if scan["diff_target_kind"] == "working_tree" and scan["diff_content_digest"]:
640
+ target["snapshotDigest"] = scan["diff_content_digest"]
641
+ else:
642
+ if scan["target_revision"] != "unversioned":
643
+ target["revision"] = scan["target_revision"]
644
+ if "requiredSnapshotDigest" in target_contract:
645
+ target["snapshotDigest"] = target_contract["requiredSnapshotDigest"]
646
+
647
+ scope: dict[str, Any] = {
648
+ "includePaths": requested_scan_paths(scan),
649
+ "excludePaths": contract["scope"]["requiredExcludePaths"],
650
+ }
651
+
652
+ return {
653
+ "scanId": scan["id"],
654
+ "startedAt": scan["started_at"],
655
+ "completedAt": completed_at,
656
+ "producer": {"name": PRODUCER_NAME, "version": plugin_version},
657
+ "target": target,
658
+ "allowedTargetKinds": target_contract["allowedKinds"],
659
+ "scope": scope,
660
+ "coverageMode": expected_coverage_mode(scan),
661
+ }
662
+
663
+
664
+ def verify_manifest_binding(scan: sqlite3.Row, manifest: dict[str, Any]) -> None:
665
+ manifest_scan = manifest.get("scan")
666
+ if not isinstance(manifest_scan, dict):
667
+ raise SystemExit("scan-manifest.json scan must be an object.")
668
+ if manifest_scan.get("id") != scan["id"]:
669
+ raise SystemExit("scan-manifest.json scan.id must match the workbench scan ID.")
670
+ target = manifest_scan.get("target")
671
+ if not isinstance(target, dict):
672
+ raise SystemExit("scan-manifest.json scan.target must be an object.")
673
+ expected_contract = scan_contract(scan)
674
+ expected_target = expected_contract["target"]
675
+ if target.get("targetId") != expected_target["targetId"]:
676
+ raise SystemExit("scan-manifest.json targetId must match the workbench target.")
677
+ if target.get("displayName") != expected_target["displayName"]:
678
+ raise SystemExit("scan-manifest.json target displayName must match the workbench target.")
679
+ if target.get("kind") not in expected_target["allowedKinds"]:
680
+ raise SystemExit("scan-manifest.json target kind must match the workbench target.")
681
+ if (
682
+ scan["target_revision"] != "unversioned"
683
+ and target.get("kind") in {"git_worktree", "git_revision"}
684
+ and target.get("revision") != scan["target_revision"]
685
+ ):
686
+ raise SystemExit("scan-manifest.json target revision must match the workbench target.")
687
+ if (
688
+ scan["mode"] != "diff"
689
+ and scan["target_snapshot_digest"] is not None
690
+ and target.get("kind") in {"directory_snapshot", "git_worktree"}
691
+ and target.get("snapshotDigest") != scan["target_snapshot_digest"]
692
+ ):
693
+ raise SystemExit(
694
+ "scan-manifest.json target snapshotDigest must match the workbench target snapshot."
695
+ )
696
+ if scan["mode"] == "diff":
697
+ if not scan["diff_target_kind"]:
698
+ raise SystemExit("This migrated diff scan does not have a validated change set.")
699
+ if target.get("baseRevision") != scan["diff_base_revision"]:
700
+ raise SystemExit(
701
+ "scan-manifest.json target baseRevision must match the workbench diff target."
702
+ )
703
+ if target.get("headRevision") != scan["diff_head_revision"]:
704
+ raise SystemExit(
705
+ "scan-manifest.json target headRevision must match the workbench diff target."
706
+ )
707
+ if (
708
+ scan["diff_target_kind"] == "working_tree"
709
+ and target.get("snapshotDigest") != scan["diff_content_digest"]
710
+ ):
711
+ raise SystemExit(
712
+ "scan-manifest.json target snapshotDigest must match the selected "
713
+ "working-tree contents."
714
+ )
715
+ scope = manifest_scan.get("scope")
716
+ if not isinstance(scope, dict):
717
+ raise SystemExit("scan-manifest.json scan.scope must be an object.")
718
+ include_paths = scope.get("includePaths")
719
+ if not isinstance(include_paths, list):
720
+ raise SystemExit("scan-manifest.json scope includePaths must be an array.")
721
+ if scope.get("excludePaths") != []:
722
+ raise SystemExit(
723
+ "scan-manifest.json scope excludePaths must match the workbench scan scope."
724
+ )
725
+ requested_scope = scan["scope"]
726
+ if scan["mode"] != "diff" and include_paths != requested_scan_paths(scan):
727
+ raise SystemExit("scan-manifest.json scope must match the workbench scan scope.")
728
+ for include_path in include_paths:
729
+ if not isinstance(include_path, str) or not path_within_scope(
730
+ include_path, requested_scope
731
+ ):
732
+ raise SystemExit("scan-manifest.json scope must stay inside the workbench scan scope.")
733
+
734
+
735
+ def path_within_scope(path: str, scope: str) -> bool:
736
+ candidate = PurePosixPath(path)
737
+ requested = PurePosixPath(scope)
738
+ if candidate.is_absolute() or ".." in candidate.parts:
739
+ return False
740
+ if requested == PurePosixPath("."):
741
+ return True
742
+ return candidate == requested or requested in candidate.parents
743
+
744
+
745
+ def require_scope(scope: str, mode: str, target: Path) -> str:
746
+ value = scope.strip() or "."
747
+ if "\\" in value:
748
+ raise SystemExit("Scan scope must use repository-relative POSIX paths.")
749
+ parsed = PurePosixPath(value)
750
+ if ".." in parsed.parts:
751
+ raise SystemExit("Scan scope must stay inside the scanned target.")
752
+ try:
753
+ resolved_scope = (
754
+ Path(parsed.as_posix()).resolve()
755
+ if parsed.is_absolute()
756
+ else (target / parsed.as_posix()).resolve()
757
+ )
758
+ relative_scope = resolved_scope.relative_to(target)
759
+ except (RuntimeError, ValueError) as exc:
760
+ raise SystemExit("Scan scope must stay inside the scanned target.") from exc
761
+ normalized = relative_scope.as_posix() or "."
762
+ if mode == "deep" and normalized != ".":
763
+ raise SystemExit("Deep Scan is repository-wide and cannot use a scoped path.")
764
+ if not resolved_scope.is_dir():
765
+ raise SystemExit("Scan scope must reference an existing directory inside the target.")
766
+ return normalized
767
+
768
+
769
+ def require_workspace(connection: sqlite3.Connection, workspace_id: str) -> sqlite3.Row:
770
+ workspace_id = require_uuid(workspace_id, "workspace-id")
771
+ row = connection.execute("SELECT * FROM workspaces WHERE id = ?", (workspace_id,)).fetchone()
772
+ if row is None:
773
+ raise SystemExit("Codex Security workspace not found. Reopen it to continue.")
774
+ return row
775
+
776
+
777
+ def require_scan(connection: sqlite3.Connection, scan_id: str) -> sqlite3.Row:
778
+ scan_id = resolve_scan_id(connection, scan_id)
779
+ row = connection.execute("SELECT * FROM scans WHERE id = ?", (scan_id,)).fetchone()
780
+ if row is None:
781
+ raise SystemExit("Codex Security scan not found.")
782
+ return row
783
+
784
+
785
+ def resolve_scan_id(connection: sqlite3.Connection, scan_id: str) -> str:
786
+ try:
787
+ return str(uuid.UUID(scan_id))
788
+ except ValueError:
789
+ if len(scan_id) < 8:
790
+ raise SystemExit("Scan ID prefixes must be at least eight characters.") from None
791
+ matches = connection.execute(
792
+ "SELECT id FROM scans WHERE substr(id, 1, ?) = ? LIMIT 2",
793
+ (len(scan_id), scan_id.lower()),
794
+ ).fetchall()
795
+ if not matches:
796
+ raise SystemExit("Codex Security scan not found.") from None
797
+ if len(matches) > 1:
798
+ raise SystemExit(
799
+ f'Scan ID prefix "{scan_id}" matches multiple scans; use a longer prefix.'
800
+ ) from None
801
+ return matches[0]["id"]
802
+
803
+
804
+ def create_workspace(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
805
+ workspace_id = require_uuid(args.workspace_id, "workspace-id")
806
+ timestamp = now()
807
+ target_path = optional_text(args.target_path, maximum=4096)
808
+ default_scope = optional_text(args.scope, maximum=4096) or "."
809
+ diff_target_kind = args.diff_target_kind if args.mode == "diff" else None
810
+ diff_base_revision = (
811
+ optional_text(args.diff_base_revision, maximum=512) if args.mode == "diff" else None
812
+ )
813
+ diff_head_revision = (
814
+ optional_text(args.diff_head_revision, maximum=512) if args.mode == "diff" else None
815
+ )
816
+ diff_content_digest = (
817
+ optional_text(args.diff_content_digest, maximum=128) if args.mode == "diff" else None
818
+ )
819
+ if target_path:
820
+ try:
821
+ inspected = inspect_setup_values(
822
+ target_path,
823
+ default_scope,
824
+ args.mode,
825
+ diff_target_kind,
826
+ diff_base_revision,
827
+ diff_head_revision,
828
+ diff_content_digest,
829
+ )
830
+ target_path = inspected["target"]["targetPath"]
831
+ default_scope = inspected["scope"]
832
+ if inspected["diffTarget"]:
833
+ diff_target_kind = inspected["diffTarget"]["kind"]
834
+ diff_base_revision = inspected["diffTarget"]["baseRevision"]
835
+ diff_head_revision = inspected["diffTarget"]["headRevision"]
836
+ diff_content_digest = inspected["diffTarget"].get("contentDigest")
837
+ except SystemExit:
838
+ pass
839
+ preflight_json = capability_preflight_json(
840
+ capability_preflight_input(
841
+ args.capability_preflight_json, args.capability_preflight_json_file
842
+ ),
843
+ checked_target_path=target_path,
844
+ checked_mode=args.mode,
845
+ )
846
+ with connection:
847
+ target_id = (
848
+ ensure_security_target(connection, target_path) if target_path is not None else None
849
+ )
850
+ connection.execute(
851
+ """
852
+ INSERT INTO workspaces (
853
+ id, thread_id, target_id, target_path, target_title, target_summary,
854
+ default_scope, default_mode,
855
+ user_context, diff_target_kind, diff_base_revision, diff_head_revision,
856
+ diff_content_digest, capability_preflight_json, created_at, updated_at
857
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
858
+ """,
859
+ (
860
+ workspace_id,
861
+ optional_text(args.thread_id, maximum=512),
862
+ target_id,
863
+ target_path,
864
+ optional_text(args.target_title, maximum=200),
865
+ optional_text(args.target_summary, maximum=2400),
866
+ default_scope,
867
+ args.mode,
868
+ optional_text(args.user_context),
869
+ diff_target_kind,
870
+ diff_base_revision,
871
+ diff_head_revision,
872
+ diff_content_digest,
873
+ preflight_json,
874
+ timestamp,
875
+ timestamp,
876
+ ),
877
+ )
878
+ return workspace_state(connection, workspace_id)
879
+
880
+
881
+ def latest_workspace(connection: sqlite3.Connection, thread_id: str) -> dict[str, Any]:
882
+ thread_id = optional_text(thread_id, maximum=512)
883
+ if thread_id is None:
884
+ raise SystemExit("thread-id is required.")
885
+ row = connection.execute(
886
+ """
887
+ SELECT workspaces.id
888
+ FROM workspaces
889
+ LEFT JOIN scans ON scans.id = workspaces.active_scan_id
890
+ WHERE workspaces.thread_id = ?
891
+ ORDER BY
892
+ CASE WHEN scans.status = 'running' THEN 0 ELSE 1 END,
893
+ CASE WHEN scans.status = 'running' THEN
894
+ MAX(
895
+ workspaces.updated_at,
896
+ scans.updated_at,
897
+ COALESCE((
898
+ SELECT MAX(progress.updated_at)
899
+ FROM scan_progress AS progress
900
+ WHERE progress.scan_id = scans.id
901
+ ), '')
902
+ )
903
+ ELSE
904
+ MAX(
905
+ workspaces.updated_at,
906
+ COALESCE((
907
+ SELECT MAX(triage.updated_at)
908
+ FROM finding_triage AS triage
909
+ JOIN finding_occurrences AS occurrences
910
+ ON occurrences.id = triage.occurrence_id
911
+ WHERE occurrences.scan_id = scans.id
912
+ ), ''),
913
+ COALESCE((
914
+ SELECT MAX(remediation.updated_at)
915
+ FROM finding_remediation_attempts AS remediation
916
+ JOIN finding_occurrences AS occurrences
917
+ ON occurrences.id = remediation.occurrence_id
918
+ WHERE occurrences.scan_id = scans.id
919
+ ), '')
920
+ )
921
+ END DESC,
922
+ workspaces.created_at DESC
923
+ LIMIT 1
924
+ """,
925
+ (thread_id,),
926
+ ).fetchone()
927
+ return {"workspace": workspace_state(connection, row["id"]) if row is not None else None}
928
+
929
+
930
+ def save_workspace(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
931
+ workspace = require_workspace(connection, args.workspace_id)
932
+ if workspace["active_scan_id"]:
933
+ raise SystemExit("This workspace already has a scan. Open a new workspace to change setup.")
934
+ inspected = inspect_setup_values(
935
+ args.target_path,
936
+ args.scope,
937
+ args.mode,
938
+ args.diff_target_kind,
939
+ args.diff_base_revision,
940
+ args.diff_head_revision,
941
+ args.diff_content_digest,
942
+ )
943
+ target = Path(inspected["target"]["targetPath"])
944
+ scope = inspected["scope"]
945
+ target_path = str(target)
946
+ target_changed = workspace["target_path"] != target_path
947
+ target_title = target.name if target_changed else workspace["target_title"]
948
+ target_summary = (
949
+ optional_text(args.target_summary, maximum=2400)
950
+ if args.target_summary is not None
951
+ else None
952
+ if target_changed
953
+ else workspace["target_summary"]
954
+ )
955
+ diff_target = inspected["diffTarget"]
956
+ if diff_target and not target_summary:
957
+ target_summary = diff_target_summary(diff_target)
958
+ timestamp = now()
959
+ with connection:
960
+ target_id = ensure_security_target(connection, target_path)
961
+ updated = connection.execute(
962
+ """
963
+ UPDATE workspaces
964
+ SET target_id = ?, target_path = ?, target_title = ?, target_summary = ?, default_scope = ?,
965
+ default_mode = ?, user_context = ?, diff_target_kind = ?,
966
+ diff_base_revision = ?, diff_head_revision = ?, diff_content_digest = ?,
967
+ diff_resolution_id = NULL, submitted = 1, updated_at = ?
968
+ WHERE id = ? AND active_scan_id IS NULL
969
+ """,
970
+ (
971
+ target_id,
972
+ target_path,
973
+ target_title,
974
+ target_summary,
975
+ scope,
976
+ args.mode,
977
+ optional_text(args.user_context),
978
+ diff_target["kind"] if diff_target else None,
979
+ diff_target["baseRevision"] if diff_target else None,
980
+ diff_target["headRevision"] if diff_target else None,
981
+ diff_target.get("contentDigest") if diff_target else None,
982
+ timestamp,
983
+ workspace["id"],
984
+ ),
985
+ )
986
+ if updated.rowcount != 1:
987
+ raise SystemExit(
988
+ "This workspace already has a scan. Open a new workspace to change setup."
989
+ )
990
+ return workspace_state(connection, workspace["id"])
991
+
992
+
993
+ def set_capability_preflight(
994
+ connection: sqlite3.Connection, args: argparse.Namespace
995
+ ) -> dict[str, Any]:
996
+ workspace = require_workspace(connection, args.workspace_id)
997
+ if workspace["active_scan_id"]:
998
+ raise SystemExit("Cannot update capability preflight after a scan has started.")
999
+ checked_target_path = str(require_target(args.checked_target_path))
1000
+ preflight_json = capability_preflight_json(
1001
+ capability_preflight_input(
1002
+ args.capability_preflight_json, args.capability_preflight_json_file
1003
+ ),
1004
+ checked_target_path=checked_target_path,
1005
+ checked_mode=args.checked_mode,
1006
+ )
1007
+ timestamp = now()
1008
+ with connection:
1009
+ updated = connection.execute(
1010
+ """
1011
+ UPDATE workspaces
1012
+ SET capability_preflight_json = ?, updated_at = ?
1013
+ WHERE id = ? AND active_scan_id IS NULL
1014
+ """,
1015
+ (preflight_json, timestamp, workspace["id"]),
1016
+ )
1017
+ if updated.rowcount != 1:
1018
+ raise SystemExit("Cannot update capability preflight after a scan has started.")
1019
+ return workspace_state(connection, workspace["id"])
1020
+
1021
+
1022
+ def begin_diff_resolution(
1023
+ connection: sqlite3.Connection, args: argparse.Namespace
1024
+ ) -> dict[str, Any]:
1025
+ workspace = require_workspace(connection, args.workspace_id)
1026
+ request_id = require_uuid(args.request_id, "request-id")
1027
+ if workspace["active_scan_id"]:
1028
+ raise SystemExit("Cannot resolve a new change set while this workspace has a scan.")
1029
+ target = require_target(args.target_path)
1030
+ require_review_changes_target(target)
1031
+ target_title = (
1032
+ workspace["target_title"] if workspace["target_path"] == str(target) else target.name
1033
+ )
1034
+ timestamp = now()
1035
+ with connection:
1036
+ target_id = ensure_security_target(connection, str(target))
1037
+ updated = connection.execute(
1038
+ """
1039
+ UPDATE workspaces
1040
+ SET target_id = ?, target_path = ?, target_title = ?, target_summary = NULL,
1041
+ default_scope = '.', default_mode = 'diff',
1042
+ user_context = ?, diff_target_kind = NULL, diff_base_revision = NULL,
1043
+ diff_head_revision = NULL, diff_content_digest = NULL,
1044
+ diff_resolution_id = ?, submitted = 0, updated_at = ?
1045
+ WHERE id = ? AND active_scan_id IS NULL
1046
+ """,
1047
+ (
1048
+ target_id,
1049
+ str(target),
1050
+ target_title,
1051
+ optional_text(args.user_context),
1052
+ request_id,
1053
+ timestamp,
1054
+ workspace["id"],
1055
+ ),
1056
+ )
1057
+ if updated.rowcount != 1:
1058
+ raise SystemExit("Cannot resolve a new change set while this workspace has a scan.")
1059
+ return workspace_state(connection, workspace["id"])
1060
+
1061
+
1062
+ def cancel_diff_resolution(
1063
+ connection: sqlite3.Connection, args: argparse.Namespace
1064
+ ) -> dict[str, Any]:
1065
+ workspace = require_workspace(connection, args.workspace_id)
1066
+ request_id = require_uuid(args.request_id, "request-id")
1067
+ timestamp = now()
1068
+ with connection:
1069
+ connection.execute(
1070
+ """
1071
+ UPDATE workspaces
1072
+ SET diff_resolution_id = NULL, updated_at = ?
1073
+ WHERE id = ? AND diff_resolution_id = ?
1074
+ """,
1075
+ (timestamp, workspace["id"], request_id),
1076
+ )
1077
+ return workspace_state(connection, workspace["id"])
1078
+
1079
+
1080
+ def set_diff_target(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
1081
+ workspace = require_workspace(connection, args.workspace_id)
1082
+ request_id = require_uuid(args.request_id, "request-id")
1083
+ if workspace["active_scan_id"]:
1084
+ raise SystemExit("Cannot resolve a new change set while this workspace has a scan.")
1085
+ if workspace["diff_resolution_id"] != request_id:
1086
+ raise SystemExit("This change-resolution request is no longer active.")
1087
+ target = require_target(workspace["target_path"])
1088
+ require_scannable_target(target)
1089
+ diff_target = require_diff_target(
1090
+ target,
1091
+ args.diff_target_kind,
1092
+ args.diff_base_revision,
1093
+ args.diff_head_revision,
1094
+ args.diff_content_digest,
1095
+ )
1096
+ timestamp = now()
1097
+ with connection:
1098
+ updated = connection.execute(
1099
+ """
1100
+ UPDATE workspaces
1101
+ SET target_summary = ?, default_scope = '.', default_mode = 'diff',
1102
+ diff_target_kind = ?, diff_base_revision = ?, diff_head_revision = ?,
1103
+ diff_content_digest = ?, diff_resolution_id = NULL,
1104
+ submitted = 0, updated_at = ?
1105
+ WHERE id = ? AND diff_resolution_id = ? AND active_scan_id IS NULL
1106
+ """,
1107
+ (
1108
+ optional_text(args.target_summary, maximum=2400),
1109
+ diff_target["kind"],
1110
+ diff_target["baseRevision"],
1111
+ diff_target["headRevision"],
1112
+ diff_target.get("contentDigest"),
1113
+ timestamp,
1114
+ workspace["id"],
1115
+ request_id,
1116
+ ),
1117
+ )
1118
+ if updated.rowcount != 1:
1119
+ raise SystemExit("This change-resolution request is no longer active.")
1120
+ return workspace_state(connection, workspace["id"])
1121
+
1122
+
1123
+ def scan_target_root(scan_root: str | None, target: Path) -> Path:
1124
+ root = Path(scan_root).expanduser().resolve() if scan_root else state_dir() / "scans"
1125
+ target_root = (root / safe_segment(target.name)).resolve()
1126
+ if target_root == target or target in target_root.parents:
1127
+ raise SystemExit("The scan artifact directory must be outside the selected target.")
1128
+ return target_root
1129
+
1130
+
1131
+ def start_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
1132
+ workspace_id = require_uuid(args.workspace_id, "workspace-id")
1133
+ manages_transaction = not connection.in_transaction
1134
+ try:
1135
+ workspace = require_workspace(connection, workspace_id)
1136
+ if not workspace["submitted"] or not workspace["target_path"]:
1137
+ raise SystemExit("Save the Codex Security setup before starting the scan.")
1138
+ active = connection.execute(
1139
+ """
1140
+ SELECT *
1141
+ FROM scans
1142
+ WHERE workspace_id = ? AND status = 'running' AND canceled_at IS NULL
1143
+ """,
1144
+ (workspace["id"],),
1145
+ ).fetchone()
1146
+ if active is not None:
1147
+ return workspace_state(connection, workspace["id"])
1148
+ workspace_version = workspace["updated_at"]
1149
+ scan_id = str(uuid.uuid4())
1150
+ timestamp = now()
1151
+ target = require_target(workspace["target_path"])
1152
+ require_scannable_target(target)
1153
+ target_metadata = target.stat()
1154
+ scope = require_scope(workspace["default_scope"], workspace["default_mode"], target)
1155
+ diff_target = None
1156
+ if workspace["default_mode"] == "diff":
1157
+ diff_target = require_diff_target(
1158
+ target,
1159
+ workspace["diff_target_kind"],
1160
+ workspace["diff_base_revision"],
1161
+ workspace["diff_head_revision"],
1162
+ workspace["diff_content_digest"],
1163
+ )
1164
+ target_summary = (
1165
+ workspace["target_summary"] if workspace["default_mode"] == "diff" else None
1166
+ )
1167
+ if diff_target is not None and not target_summary:
1168
+ target_summary = diff_target_summary(diff_target)
1169
+ scope_file_count = directory_snapshot_regular_file_count(
1170
+ target if scope == "." else target / scope
1171
+ )
1172
+ target_identity = scan_target_identity(
1173
+ target,
1174
+ diff_target,
1175
+ metadata=target_metadata,
1176
+ )
1177
+ target_root = scan_target_root(args.scan_root, target)
1178
+ target_root.mkdir(parents=True, exist_ok=True)
1179
+ if manages_transaction:
1180
+ connection.execute("BEGIN IMMEDIATE")
1181
+ workspace = require_workspace(connection, workspace_id)
1182
+ active = connection.execute(
1183
+ """
1184
+ SELECT *
1185
+ FROM scans
1186
+ WHERE workspace_id = ? AND status = 'running' AND canceled_at IS NULL
1187
+ """,
1188
+ (workspace["id"],),
1189
+ ).fetchone()
1190
+ if active is not None:
1191
+ if manages_transaction:
1192
+ connection.commit()
1193
+ return workspace_state(connection, workspace["id"])
1194
+ if workspace["updated_at"] != workspace_version:
1195
+ raise SystemExit("Codex Security setup changed while the scan was starting. Try again.")
1196
+ current_target = require_remediation_target(str(target))
1197
+ current_target_metadata = current_target.stat()
1198
+ if (current_target_metadata.st_dev, current_target_metadata.st_ino) != (
1199
+ target_metadata.st_dev,
1200
+ target_metadata.st_ino,
1201
+ ):
1202
+ raise SystemExit(
1203
+ "The selected scan target changed while the scan was starting. Try again."
1204
+ )
1205
+ if workspace["default_mode"] == "deep" and workspace["thread_id"] is not None:
1206
+ owned_active_scan = deep_scan.existing_deep_scan_for_target(
1207
+ connection,
1208
+ workspace["thread_id"],
1209
+ str(target),
1210
+ scope,
1211
+ )
1212
+ if owned_active_scan is not None:
1213
+ raise SystemExit(
1214
+ "This Codex thread already has an active Deep Scan for the selected "
1215
+ "target and scope. Rejoin that scan instead of starting another one."
1216
+ )
1217
+ insert_running_scan(
1218
+ connection,
1219
+ scan_id=scan_id,
1220
+ workspace=workspace,
1221
+ target=target,
1222
+ scope=scope,
1223
+ diff_target=diff_target,
1224
+ target_identity=target_identity,
1225
+ target_root=target_root,
1226
+ target_summary=target_summary,
1227
+ scope_file_count=scope_file_count,
1228
+ timestamp=timestamp,
1229
+ )
1230
+ if manages_transaction:
1231
+ connection.commit()
1232
+ except BaseException:
1233
+ if manages_transaction:
1234
+ connection.rollback()
1235
+ raise
1236
+ return workspace_state(connection, workspace["id"])
1237
+
1238
+
1239
+ def start_prompt_only_scan(
1240
+ connection: sqlite3.Connection, args: argparse.Namespace
1241
+ ) -> dict[str, Any]:
1242
+ thread_id = optional_text(args.thread_id, maximum=512)
1243
+ if thread_id is None:
1244
+ raise SystemExit("thread-id is required.")
1245
+ inspected = inspect_setup_values(
1246
+ args.target_path,
1247
+ args.scope,
1248
+ args.mode,
1249
+ args.diff_target_kind,
1250
+ args.diff_base_revision,
1251
+ args.diff_head_revision,
1252
+ args.diff_content_digest,
1253
+ )
1254
+ target = Path(inspected["target"]["targetPath"])
1255
+ target_path = str(target)
1256
+ scope = inspected["scope"]
1257
+ diff_target = inspected["diffTarget"]
1258
+ user_context = optional_text(args.user_context)
1259
+ target_summary = optional_text(args.target_summary, maximum=2400)
1260
+ if diff_target is not None and not target_summary:
1261
+ target_summary = diff_target_summary(diff_target)
1262
+ scope_file_count = directory_snapshot_regular_file_count(
1263
+ target if scope == "." else target / scope
1264
+ )
1265
+ diff_identity = scan_diff_identity(diff_target)
1266
+ target_identity = scan_target_identity(target, diff_target)
1267
+ target_root = scan_target_root(args.scan_root, target)
1268
+
1269
+ connection.execute("BEGIN IMMEDIATE")
1270
+ try:
1271
+ if not setup_preference(connection)["skipSetupUi"]:
1272
+ raise SystemExit(
1273
+ "Prompt-only scanning requires the persisted setup UI opt-out preference."
1274
+ )
1275
+ current_target = require_remediation_target(target_path)
1276
+ current_diff_target = (
1277
+ require_diff_target(
1278
+ current_target,
1279
+ args.diff_target_kind,
1280
+ args.diff_base_revision,
1281
+ args.diff_head_revision,
1282
+ args.diff_content_digest,
1283
+ )
1284
+ if args.mode == "diff"
1285
+ else None
1286
+ )
1287
+ if (
1288
+ scan_target_identity(current_target, current_diff_target) != target_identity
1289
+ or scan_diff_identity(current_diff_target) != diff_identity
1290
+ ):
1291
+ raise SystemExit(
1292
+ "The selected scan target changed while the scan was starting. Try again."
1293
+ )
1294
+ existing = connection.execute(
1295
+ """
1296
+ SELECT scans.* FROM scans
1297
+ JOIN workspaces ON workspaces.active_scan_id = scans.id
1298
+ WHERE workspaces.thread_id = ? AND workspaces.target_path = ?
1299
+ AND workspaces.default_scope = ? AND workspaces.default_mode = ?
1300
+ AND workspaces.user_context IS ? AND workspaces.target_summary IS ?
1301
+ AND workspaces.diff_target_kind IS ? AND workspaces.diff_base_revision IS ?
1302
+ AND workspaces.diff_head_revision IS ? AND workspaces.diff_content_digest IS ?
1303
+ AND workspaces.submitted = 1 AND scans.target_revision = ?
1304
+ AND scans.target_snapshot_digest IS ? AND scans.target_device = ?
1305
+ AND scans.target_inode = ? AND scans.status = 'running'
1306
+ AND scans.handoff_status = 'delivered'
1307
+ AND scans.handoff_claim_token IS NULL
1308
+ ORDER BY scans.updated_at DESC, scans.started_at DESC, scans.id LIMIT 1
1309
+ """,
1310
+ (
1311
+ thread_id,
1312
+ target_path,
1313
+ scope,
1314
+ args.mode,
1315
+ user_context,
1316
+ target_summary,
1317
+ *diff_identity,
1318
+ *target_identity,
1319
+ ),
1320
+ ).fetchone()
1321
+ if existing is not None:
1322
+ connection.commit()
1323
+ return {**scan_context(connection, existing["id"]), "startDisposition": "joined"}
1324
+ target_root.mkdir(parents=True, exist_ok=True)
1325
+ workspace_id = str(uuid.uuid4())
1326
+ scan_id = str(uuid.uuid4())
1327
+ timestamp = now()
1328
+ target_id = ensure_security_target(connection, target_path)
1329
+ connection.execute(
1330
+ """
1331
+ INSERT INTO workspaces (
1332
+ id, thread_id, target_id, target_path, target_title, target_summary, default_scope,
1333
+ default_mode, user_context, diff_target_kind, diff_base_revision,
1334
+ diff_head_revision, diff_content_digest, submitted, created_at, updated_at
1335
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)
1336
+ """,
1337
+ (
1338
+ workspace_id,
1339
+ thread_id,
1340
+ target_id,
1341
+ target_path,
1342
+ target.name,
1343
+ target_summary,
1344
+ scope,
1345
+ args.mode,
1346
+ user_context,
1347
+ *diff_identity,
1348
+ timestamp,
1349
+ timestamp,
1350
+ ),
1351
+ )
1352
+ workspace = require_workspace(connection, workspace_id)
1353
+ insert_running_scan(
1354
+ connection,
1355
+ scan_id=scan_id,
1356
+ workspace=workspace,
1357
+ target=target,
1358
+ scope=scope,
1359
+ diff_target=diff_target,
1360
+ target_identity=target_identity,
1361
+ target_root=target_root,
1362
+ target_summary=target_summary,
1363
+ scope_file_count=scope_file_count,
1364
+ timestamp=timestamp,
1365
+ handoff_status="delivered",
1366
+ )
1367
+ connection.commit()
1368
+ except BaseException:
1369
+ connection.rollback()
1370
+ raise
1371
+ return {**scan_context(connection, scan_id), "startDisposition": "created"}
1372
+
1373
+
1374
+ def require_unchanged_target(scan: sqlite3.Row) -> None:
1375
+ if scan["diff_target_kind"] != "working_tree" and not scan["target_snapshot_digest"]:
1376
+ return
1377
+ target = require_target(scan["target_path"])
1378
+ if scan["target_revision"] == "unversioned":
1379
+ current_digest = directory_content_digest(
1380
+ target,
1381
+ excluded=(Path(scan["scan_dir"]),),
1382
+ )
1383
+ if current_digest != scan["target_snapshot_digest"]:
1384
+ raise SystemExit(
1385
+ "Directory contents changed while the scan was running. Start a new scan."
1386
+ )
1387
+ return
1388
+ if git_revision(target) == "unversioned":
1389
+ raise SystemExit("The scan target revision no longer matches the selected target.")
1390
+ current_head = require_git_worktree_head(target)
1391
+ expected_head = (
1392
+ scan["diff_head_revision"]
1393
+ if scan["diff_target_kind"] == "working_tree"
1394
+ else scan["target_revision"]
1395
+ )
1396
+ if current_head != expected_head:
1397
+ raise SystemExit("Repository HEAD changed while the scan was running. Start a new scan.")
1398
+ current_digest = worktree_content_digest(target)
1399
+ expected_digest = (
1400
+ scan["diff_content_digest"]
1401
+ if scan["diff_target_kind"] == "working_tree"
1402
+ else scan["target_snapshot_digest"]
1403
+ )
1404
+ if current_digest != expected_digest:
1405
+ raise SystemExit(
1406
+ "Working-tree contents changed while the scan was running. Start a new scan."
1407
+ )
1408
+
1409
+
1410
+ def scan_local_file_digest(scan_dir: Path, relative_path: str) -> str:
1411
+ digest = hashlib.sha256()
1412
+ with open_scan_local_file(scan_dir, relative_path) as source:
1413
+ for chunk in iter(lambda: source.read(1024 * 1024), b""):
1414
+ digest.update(chunk)
1415
+ return f"sha256:{digest.hexdigest()}"
1416
+
1417
+
1418
+ def published_manifest_digest(scan_dir: Path, manifest: dict[str, Any]) -> str:
1419
+ canonical = (json.dumps(manifest, allow_nan=False, indent=2, sort_keys=True) + "\n").encode()
1420
+ expected = f"sha256:{hashlib.sha256(canonical).hexdigest()}"
1421
+ actual = scan_local_file_digest(scan_dir, ARTIFACTS["manifest"])
1422
+ if actual != expected:
1423
+ raise SystemExit("The sealed scan manifest changed while it was being published.")
1424
+ return expected
1425
+
1426
+
1427
+ def require_recorded_manifest_digest(scan: sqlite3.Row, scan_dir: Path) -> None:
1428
+ expected = scan["seal_manifest_digest"]
1429
+ if expected is None:
1430
+ return
1431
+ if scan_local_file_digest(scan_dir, ARTIFACTS["manifest"]) != expected:
1432
+ raise SystemExit("The sealed scan manifest changed after completion.")
1433
+
1434
+
1435
+ def pin_legacy_manifest_digest(
1436
+ connection: sqlite3.Connection, scan_id: str, manifest_digest: str
1437
+ ) -> None:
1438
+ connection.execute("BEGIN IMMEDIATE")
1439
+ try:
1440
+ scan = require_scan(connection, scan_id)
1441
+ current = scan["seal_manifest_digest"]
1442
+ if current is not None and current != manifest_digest:
1443
+ raise SystemExit("The sealed scan manifest changed after completion.")
1444
+ if current is None:
1445
+ connection.execute(
1446
+ "UPDATE scans SET seal_manifest_digest = ? WHERE id = ?",
1447
+ (manifest_digest, scan["id"]),
1448
+ )
1449
+ connection.commit()
1450
+ except BaseException:
1451
+ connection.rollback()
1452
+ raise
1453
+
1454
+
1455
+ def complete_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
1456
+ scan_id = require_uuid(args.scan_id, "scan-id")
1457
+ cost_json = parse_scan_cost(args.cost_json)
1458
+ with scan_completion_lock(scan_id):
1459
+ return complete_scan_locked(connection, scan_id, args.claim_token, cost_json)
1460
+
1461
+
1462
+ def complete_scan_locked(
1463
+ connection: sqlite3.Connection,
1464
+ scan_id: str,
1465
+ claim_token: str | None,
1466
+ cost_json: str | None,
1467
+ ) -> dict[str, Any]:
1468
+ scan = require_scan(connection, scan_id)
1469
+ if scan["status"] == "complete":
1470
+ scan_dir = require_canonical_scan_directory(Path(scan["scan_dir"]))
1471
+ require_recorded_manifest_digest(scan, scan_dir)
1472
+ verify_manifest_binding(scan, read_json_object(scan_dir / ARTIFACTS["manifest"]))
1473
+ try:
1474
+ manifest, _, _ = finalize_scan(
1475
+ scan_dir,
1476
+ expected_coverage_mode=expected_coverage_mode(scan),
1477
+ )
1478
+ except ContractError as exc:
1479
+ raise SystemExit(str(exc)) from exc
1480
+ verify_manifest_binding(scan, manifest)
1481
+ manifest_digest = published_manifest_digest(scan_dir, manifest)
1482
+ pin_legacy_manifest_digest(connection, scan["id"], manifest_digest)
1483
+ return scan_context(connection, scan["id"])
1484
+ if scan["status"] != "running":
1485
+ raise SystemExit("Only a running scan can be completed.")
1486
+ handoff.require_current_continuation(
1487
+ scan,
1488
+ claim_token,
1489
+ error_message="Scan completion is owned by another continuation.",
1490
+ )
1491
+ if scan["recipe_json"] is None:
1492
+ deep_scan.require_deep_scan_ready_for_parent_completion(connection, scan)
1493
+ require_unchanged_target(scan)
1494
+ scan_dir = require_canonical_scan_directory(Path(scan["scan_dir"]))
1495
+ completion_timestamp = now()
1496
+ completion_binding = workbench_completion_binding(scan, completion_timestamp)
1497
+ if scan["recipe_json"] is not None:
1498
+ manifest = read_json_object(artifact_path(scan_dir, ARTIFACTS["manifest"], required=True))
1499
+ manifest_scan = manifest.get("scan")
1500
+ if isinstance(manifest_scan, dict) and manifest_scan.get("sealedAt") is not None:
1501
+ completion_binding["startedAt"] = manifest_scan.get("startedAt")
1502
+ completion_binding["completedAt"] = manifest_scan.get("completedAt")
1503
+ try:
1504
+ prepared = _prepare_scan_finalization(
1505
+ scan_dir,
1506
+ expected_coverage_mode=expected_coverage_mode(scan),
1507
+ completion_binding=completion_binding,
1508
+ )
1509
+ # Keep the second target check between in-memory finalization and the first write.
1510
+ require_unchanged_target(scan)
1511
+ manifest, findings, _ = _write_prepared_scan_finalization(prepared)
1512
+ except ContractError as exc:
1513
+ raise SystemExit(str(exc)) from exc
1514
+ artifacts = {
1515
+ kind: artifact_path(scan_dir, filename, required=True)
1516
+ for kind, filename in ARTIFACTS.items()
1517
+ }
1518
+ manifest_digest = published_manifest_digest(scan_dir, manifest)
1519
+ connection.execute("BEGIN IMMEDIATE")
1520
+ try:
1521
+ timestamp = completion_timestamp
1522
+ scan = require_scan(connection, scan["id"])
1523
+ if scan["status"] == "complete":
1524
+ connection.commit()
1525
+ return scan_context(connection, scan["id"])
1526
+ if scan["status"] != "running":
1527
+ raise SystemExit("Only a running scan can be completed.")
1528
+ if scan["recipe_json"] is None:
1529
+ deep_scan.require_deep_scan_ready_for_parent_completion(connection, scan)
1530
+ handoff.require_current_continuation(
1531
+ scan,
1532
+ claim_token,
1533
+ error_message="Scan completion is owned by another continuation.",
1534
+ )
1535
+ connection.execute("DELETE FROM scan_artifacts WHERE scan_id = ?", (scan["id"],))
1536
+ for kind, path in artifacts.items():
1537
+ if path is not None:
1538
+ connection.execute(
1539
+ "INSERT INTO scan_artifacts (scan_id, kind, path, created_at) VALUES (?, ?, ?, ?)",
1540
+ (scan["id"], kind, str(path), timestamp),
1541
+ )
1542
+ connection.execute("DELETE FROM finding_occurrences WHERE scan_id = ?", (scan["id"],))
1543
+ index_findings(connection, scan["id"], findings, timestamp)
1544
+ finding_count = len(findings.get("findings", []))
1545
+ connection.execute(
1546
+ """
1547
+ UPDATE scan_progress
1548
+ SET reportable_findings_count = ?, phase_items_total = ?,
1549
+ phase_items_completed = ?, phase_progress_unit = 'report_artifacts',
1550
+ updated_at = ?
1551
+ WHERE scan_id = ?
1552
+ """,
1553
+ (finding_count, len(artifacts), len(artifacts), timestamp, scan["id"]),
1554
+ )
1555
+ updated = connection.execute(
1556
+ """
1557
+ UPDATE scans
1558
+ SET status = 'complete', phase = 'reporting', completed_at = ?, updated_at = ?,
1559
+ seal_manifest_digest = ?, cost_json = ?
1560
+ WHERE id = ? AND status = 'running'
1561
+ """,
1562
+ (timestamp, timestamp, manifest_digest, cost_json, scan["id"]),
1563
+ )
1564
+ if updated.rowcount != 1:
1565
+ raise SystemExit("Only a running scan can be completed.")
1566
+ connection.commit()
1567
+ except BaseException:
1568
+ connection.rollback()
1569
+ raise
1570
+ return scan_context(connection, scan["id"])
1571
+
1572
+
1573
+ def register_cli_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
1574
+ repository = require_target(args.repository)
1575
+ require_scannable_target(repository)
1576
+ scan_dir = require_canonical_scan_directory(Path(args.scan_dir).expanduser())
1577
+ if scan_dir == repository or repository in scan_dir.parents:
1578
+ raise SystemExit("The scan artifact directory must be outside the selected target.")
1579
+ if next(scan_dir.iterdir(), None) is not None:
1580
+ raise SystemExit("The scan artifact directory must be empty before the scan starts.")
1581
+
1582
+ recipe = parse_scan_recipe(args.recipe_json, repository)
1583
+ requested_target = recipe["target"]
1584
+ paths = requested_target["paths"]
1585
+ scope = paths[0] if len(paths) == 1 else "."
1586
+ diff_target = None
1587
+ if requested_target["kind"] in {"refs", "working_tree"}:
1588
+ current_head = require_review_changes_target(repository)
1589
+ base = resolve_git_commit(repository, requested_target["base"], "Base revision")
1590
+ head = resolve_git_commit(repository, requested_target["head"], "Head revision")
1591
+ diff_target = {
1592
+ "kind": "range" if requested_target["kind"] == "refs" else "working_tree",
1593
+ "baseRevision": base,
1594
+ "headRevision": head,
1595
+ }
1596
+ if requested_target["kind"] == "working_tree":
1597
+ if head != current_head:
1598
+ raise SystemExit("Working-tree HEAD changed before the scan started.")
1599
+ diff_target["contentDigest"] = worktree_content_digest(repository)
1600
+ mode = "diff" if diff_target is not None else recipe["mode"]
1601
+ target_identity = scan_target_identity(repository, diff_target)
1602
+ scope_file_count = (
1603
+ directory_snapshot_regular_file_count(repository)
1604
+ if not paths
1605
+ else sum(
1606
+ 1
1607
+ if (repository / path).is_file()
1608
+ else directory_snapshot_regular_file_count(repository / path)
1609
+ for path in paths
1610
+ )
1611
+ )
1612
+ parent_scan_id = (
1613
+ require_uuid(args.parent_scan_id, "parent-scan-id")
1614
+ if args.parent_scan_id is not None
1615
+ else None
1616
+ )
1617
+ timestamp = now()
1618
+ scan_id = str(uuid.uuid4())
1619
+ workspace_id = str(uuid.uuid4())
1620
+
1621
+ connection.execute("BEGIN IMMEDIATE")
1622
+ try:
1623
+ target_id = ensure_security_target(connection, str(repository))
1624
+ if parent_scan_id is not None:
1625
+ parent = require_scan(connection, parent_scan_id)
1626
+ if parent["target_id"] != target_id:
1627
+ raise SystemExit("A rerun must belong to the same repository as its parent scan.")
1628
+
1629
+ connection.execute(
1630
+ """
1631
+ INSERT INTO workspaces (
1632
+ id, target_id, target_path, target_title, default_scope, default_mode,
1633
+ diff_target_kind, diff_base_revision, diff_head_revision,
1634
+ diff_content_digest, submitted, created_at, updated_at
1635
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)
1636
+ """,
1637
+ (
1638
+ workspace_id,
1639
+ target_id,
1640
+ str(repository),
1641
+ repository.name,
1642
+ scope,
1643
+ mode,
1644
+ *scan_diff_identity(diff_target),
1645
+ timestamp,
1646
+ timestamp,
1647
+ ),
1648
+ )
1649
+ workspace = require_workspace(connection, workspace_id)
1650
+ insert_running_scan(
1651
+ connection,
1652
+ scan_id=scan_id,
1653
+ workspace=workspace,
1654
+ target=repository,
1655
+ scope=scope,
1656
+ diff_target=diff_target,
1657
+ target_identity=target_identity,
1658
+ target_root=scan_dir.parent,
1659
+ target_summary=None,
1660
+ scope_file_count=scope_file_count,
1661
+ timestamp=timestamp,
1662
+ handoff_status="delivered",
1663
+ scan_dir=scan_dir,
1664
+ )
1665
+ connection.execute(
1666
+ "UPDATE scans SET recipe_json = ?, parent_scan_id = ? WHERE id = ?",
1667
+ (
1668
+ json.dumps(recipe, allow_nan=False, separators=(",", ":"), sort_keys=True),
1669
+ parent_scan_id,
1670
+ scan_id,
1671
+ ),
1672
+ )
1673
+ connection.commit()
1674
+ except BaseException:
1675
+ connection.rollback()
1676
+ raise
1677
+ return {"scanDir": str(scan_dir), "scanId": scan_id, "targetId": target_id}
1678
+
1679
+
1680
+ def parse_scan_recipe(value: str, repository: Path) -> dict[str, Any]:
1681
+ if len(value.encode("utf-8")) > SCAN_RECIPE_MAX_BYTES:
1682
+ raise SystemExit("Scan launch recipe must be no larger than 256 KiB.")
1683
+ try:
1684
+ recipe = json.loads(value, parse_constant=reject_non_finite_json)
1685
+ except (TypeError, UnicodeError, ValueError) as exc:
1686
+ raise SystemExit("Scan launch recipe must be a valid JSON object.") from exc
1687
+ if not isinstance(recipe, dict):
1688
+ raise SystemExit("Scan launch recipe must be a JSON object.")
1689
+ requested_repository = recipe.get("repository")
1690
+ if (
1691
+ not isinstance(requested_repository, str)
1692
+ or require_target(requested_repository) != repository
1693
+ ):
1694
+ raise SystemExit("Scan launch recipe repository must match the scanned repository.")
1695
+ if recipe.get("mode") not in {"standard", "deep"}:
1696
+ raise SystemExit("Scan launch recipe mode must be standard or deep.")
1697
+ if not isinstance(recipe.get("config"), dict):
1698
+ raise SystemExit("Scan launch recipe config must be a JSON object.")
1699
+ target = recipe.get("target")
1700
+ if not isinstance(target, dict) or target.get("kind") not in {
1701
+ "repository",
1702
+ "paths",
1703
+ "refs",
1704
+ "working_tree",
1705
+ }:
1706
+ raise SystemExit("Scan launch recipe target must identify a supported scan target.")
1707
+ paths = target.get("paths")
1708
+ if not isinstance(paths, list) or not all(isinstance(path, str) for path in paths):
1709
+ raise SystemExit("Scan launch recipe target paths must be an array of strings.")
1710
+ if target["kind"] == "paths" and not paths:
1711
+ raise SystemExit("A scoped scan launch recipe must include at least one target path.")
1712
+ if target["kind"] != "paths" and paths:
1713
+ raise SystemExit("Only scoped scan launch recipes can include target paths.")
1714
+ for path in paths:
1715
+ candidate = PurePosixPath(path)
1716
+ if (
1717
+ not path
1718
+ or candidate.is_absolute()
1719
+ or ".." in candidate.parts
1720
+ or "\\" in path
1721
+ or not (repository / candidate).exists()
1722
+ or not (repository / candidate).resolve().is_relative_to(repository)
1723
+ ):
1724
+ raise SystemExit("Scan launch recipe target paths must exist inside the repository.")
1725
+ if target["kind"] in {"refs", "working_tree"}:
1726
+ if not isinstance(target.get("base"), str) or not isinstance(target.get("head"), str):
1727
+ raise SystemExit("Diff scan launch recipes require resolved base and head revisions.")
1728
+ return recipe
1729
+
1730
+
1731
+ def get_scan_recipe(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
1732
+ scan = require_scan(connection, args.scan_id)
1733
+ if scan["recipe_json"] is None:
1734
+ raise SystemExit("This scan does not have a saved launch recipe.")
1735
+ return {
1736
+ "parentScanId": scan["parent_scan_id"],
1737
+ "recipe": json.loads(scan["recipe_json"], parse_constant=reject_non_finite_json),
1738
+ "scanId": scan["id"],
1739
+ }
1740
+
1741
+
1742
+ def coverage_for_comparison(scan: sqlite3.Row) -> dict[str, Any]:
1743
+ if scan["seal_manifest_digest"] is None:
1744
+ raise SystemExit("Only sealed scans can be compared.")
1745
+ scan_dir = require_canonical_scan_directory(Path(scan["scan_dir"]))
1746
+ require_recorded_manifest_digest(scan, scan_dir)
1747
+ try:
1748
+ _, _, manifest, _, coverage, was_sealed, _ = _prepare_scan_finalization(scan_dir)
1749
+ except ContractError as exc:
1750
+ raise SystemExit(str(exc)) from exc
1751
+ if not was_sealed or manifest["scan"]["id"] != scan["id"]:
1752
+ raise SystemExit("Only sealed scans can be compared.")
1753
+ return coverage
1754
+
1755
+
1756
+ def fail_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
1757
+ scan_id = require_uuid(args.scan_id, "scan-id")
1758
+ cost_json = parse_scan_cost(args.cost_json)
1759
+ connection.execute("BEGIN IMMEDIATE")
1760
+ try:
1761
+ timestamp = now()
1762
+ scan = require_scan(connection, scan_id)
1763
+ if scan["status"] == "failed":
1764
+ connection.commit()
1765
+ return scan_context(connection, scan["id"])
1766
+ if scan["status"] == "complete":
1767
+ raise SystemExit("A completed scan cannot be marked failed.")
1768
+ handoff.require_current_continuation(
1769
+ scan,
1770
+ args.claim_token,
1771
+ error_message="Scan failure is owned by another continuation.",
1772
+ )
1773
+ updated = connection.execute(
1774
+ """
1775
+ UPDATE scans
1776
+ SET status = 'failed', failure_message = ?, completed_at = ?, updated_at = ?,
1777
+ cost_json = ?
1778
+ WHERE id = ? AND status = 'running'
1779
+ """,
1780
+ (
1781
+ optional_text(args.message, maximum=2400),
1782
+ timestamp,
1783
+ timestamp,
1784
+ cost_json,
1785
+ scan["id"],
1786
+ ),
1787
+ )
1788
+ if updated.rowcount != 1:
1789
+ raise SystemExit("Only a running scan can be marked failed.")
1790
+ deep_scan.fail_from_parent_scan(
1791
+ connection,
1792
+ scan["id"],
1793
+ optional_text(args.message, maximum=2400),
1794
+ timestamp,
1795
+ )
1796
+ progress_updated = connection.execute(
1797
+ "UPDATE scan_progress SET updated_at = ? WHERE scan_id = ?",
1798
+ (timestamp, scan["id"]),
1799
+ )
1800
+ if progress_updated.rowcount != 1:
1801
+ raise SystemExit("Codex Security scan progress not found.")
1802
+ connection.commit()
1803
+ except BaseException:
1804
+ connection.rollback()
1805
+ raise
1806
+ return scan_context(connection, scan["id"])
1807
+
1808
+
1809
+ def cancel_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
1810
+ scan_id = require_uuid(args.scan_id, "scan-id")
1811
+ thread_id = optional_text(args.thread_id, maximum=512)
1812
+ connection.execute("BEGIN IMMEDIATE")
1813
+ try:
1814
+ timestamp = now()
1815
+ scan = require_scan(connection, scan_id)
1816
+ workspace = require_workspace(connection, scan["workspace_id"])
1817
+ owning_thread_id = scan["continuation_thread_id"] or workspace["thread_id"]
1818
+ if thread_id is not None and owning_thread_id != thread_id:
1819
+ raise SystemExit("A scan can only be canceled from its owning Codex thread.")
1820
+ if scan["canceled_at"] is not None:
1821
+ connection.commit()
1822
+ return workspace_state(connection, scan["workspace_id"])
1823
+ if scan["status"] != "running":
1824
+ raise SystemExit("Only a running scan can be canceled.")
1825
+ updated = connection.execute(
1826
+ """
1827
+ UPDATE scans
1828
+ SET status = 'failed', canceled_at = ?, completed_at = ?, updated_at = ?
1829
+ WHERE id = ? AND status = 'running'
1830
+ """,
1831
+ (timestamp, timestamp, timestamp, scan["id"]),
1832
+ )
1833
+ if updated.rowcount != 1:
1834
+ raise SystemExit("Only a running scan can be canceled.")
1835
+ deep_scan.cancel_from_parent_scan(connection, scan["id"], timestamp)
1836
+ progress_updated = connection.execute(
1837
+ "UPDATE scan_progress SET updated_at = ? WHERE scan_id = ?",
1838
+ (timestamp, scan["id"]),
1839
+ )
1840
+ if progress_updated.rowcount != 1:
1841
+ raise SystemExit("Codex Security scan progress not found.")
1842
+ connection.commit()
1843
+ except BaseException:
1844
+ connection.rollback()
1845
+ raise
1846
+ return workspace_state(connection, scan["workspace_id"])
1847
+
1848
+
1849
+ def set_finding_triage(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
1850
+ close_reason = args.close_reason
1851
+ if args.status == "open" and close_reason is not None:
1852
+ raise SystemExit("An open finding cannot keep a close reason.")
1853
+ if args.status == "closed" and close_reason is None:
1854
+ raise SystemExit("Choose why this finding is being closed.")
1855
+ note = optional_text(args.note, maximum=2400)
1856
+ if close_reason == "wont_fix" and note is None:
1857
+ raise SystemExit("Explain why this finding will not be fixed.")
1858
+ connection.execute("BEGIN IMMEDIATE")
1859
+ try:
1860
+ timestamp = now()
1861
+ occurrence = require_occurrence(connection, args.occurrence_id)
1862
+ if args.status == "closed":
1863
+ remediation = connection.execute(
1864
+ """
1865
+ SELECT *
1866
+ FROM finding_remediation_attempts
1867
+ WHERE occurrence_id = ?
1868
+ ORDER BY created_at DESC, rowid DESC
1869
+ LIMIT 1
1870
+ """,
1871
+ (occurrence["id"],),
1872
+ ).fetchone()
1873
+ if (
1874
+ remediation is not None
1875
+ and remediation["pending_action"] is not None
1876
+ and not (
1877
+ remediation["state"] == "failed"
1878
+ and not remediation_claim_is_active(remediation)
1879
+ )
1880
+ ):
1881
+ raise SystemExit(
1882
+ "Wait for the pending remediation operation to finish before closing this finding."
1883
+ )
1884
+ if (
1885
+ close_reason == "already_fixed"
1886
+ and remediation is not None
1887
+ and remediation["state"] == "verified"
1888
+ ):
1889
+ scan = require_scan(connection, occurrence["scan_id"])
1890
+ require_remediation_checkout_unchanged(
1891
+ scan,
1892
+ remediation,
1893
+ require_applied_content=True,
1894
+ )
1895
+ previous_triage = connection.execute(
1896
+ "SELECT status, close_reason, note FROM finding_triage WHERE occurrence_id = ?",
1897
+ (occurrence["id"],),
1898
+ ).fetchone()
1899
+ if previous_triage is None or (
1900
+ previous_triage["status"],
1901
+ previous_triage["close_reason"],
1902
+ previous_triage["note"],
1903
+ ) != (args.status, close_reason, note):
1904
+ connection.execute(
1905
+ """
1906
+ INSERT INTO finding_decisions (
1907
+ id, occurrence_id, status, close_reason, note, created_at
1908
+ ) VALUES (?, ?, ?, ?, ?, ?)
1909
+ """,
1910
+ (str(uuid.uuid4()), occurrence["id"], args.status, close_reason, note, timestamp),
1911
+ )
1912
+ connection.execute(
1913
+ """
1914
+ INSERT INTO finding_triage (occurrence_id, status, close_reason, note, updated_at)
1915
+ VALUES (?, ?, ?, ?, ?)
1916
+ ON CONFLICT(occurrence_id) DO UPDATE SET
1917
+ status = excluded.status,
1918
+ close_reason = excluded.close_reason,
1919
+ note = excluded.note,
1920
+ updated_at = excluded.updated_at
1921
+ """,
1922
+ (occurrence["id"], args.status, close_reason, note, timestamp),
1923
+ )
1924
+ connection.commit()
1925
+ except BaseException:
1926
+ connection.rollback()
1927
+ raise
1928
+ return scan_context(connection, occurrence["scan_id"])
1929
+
1930
+
1931
+ def require_finding_open(connection: sqlite3.Connection, occurrence_id: str) -> None:
1932
+ triage = connection.execute(
1933
+ "SELECT status FROM finding_triage WHERE occurrence_id = ?",
1934
+ (occurrence_id,),
1935
+ ).fetchone()
1936
+ if triage is not None and triage["status"] == "closed":
1937
+ raise SystemExit("Reopen this finding before requesting remediation.")
1938
+
1939
+
1940
+ def request_finding_remediation(
1941
+ connection: sqlite3.Connection, args: argparse.Namespace
1942
+ ) -> dict[str, Any]:
1943
+ request_id = require_uuid(args.request_id, "request-id")
1944
+ action_token = require_uuid(args.action_token, "action-token")
1945
+ try:
1946
+ occurrence = require_occurrence(connection, args.occurrence_id)
1947
+ require_finding_open(connection, occurrence["id"])
1948
+ scan = require_scan(connection, occurrence["scan_id"])
1949
+ existing = connection.execute(
1950
+ "SELECT * FROM finding_remediation_attempts WHERE request_id = ?",
1951
+ (request_id,),
1952
+ ).fetchone()
1953
+ if existing is not None:
1954
+ if existing["occurrence_id"] != occurrence["id"]:
1955
+ raise SystemExit("This remediation request belongs to a different finding.")
1956
+ return scan_context(connection, occurrence["scan_id"])
1957
+ base_revision, base_content_digest = remediation_checkout_snapshot(scan)
1958
+ connection.execute("BEGIN IMMEDIATE")
1959
+ timestamp = now()
1960
+ occurrence = require_occurrence(connection, args.occurrence_id)
1961
+ require_finding_open(connection, occurrence["id"])
1962
+ existing = connection.execute(
1963
+ "SELECT * FROM finding_remediation_attempts WHERE request_id = ?",
1964
+ (request_id,),
1965
+ ).fetchone()
1966
+ if existing is not None:
1967
+ if existing["occurrence_id"] != occurrence["id"]:
1968
+ raise SystemExit("This remediation request belongs to a different finding.")
1969
+ connection.commit()
1970
+ return scan_context(connection, occurrence["scan_id"])
1971
+ latest = connection.execute(
1972
+ """
1973
+ SELECT *
1974
+ FROM finding_remediation_attempts
1975
+ WHERE occurrence_id = ?
1976
+ ORDER BY created_at DESC, rowid DESC
1977
+ LIMIT 1
1978
+ """,
1979
+ (occurrence["id"],),
1980
+ ).fetchone()
1981
+ if latest is not None:
1982
+ active_operation = latest["pending_action"] is not None or latest["state"] in {
1983
+ "requested",
1984
+ "verifying",
1985
+ }
1986
+ if active_operation and (
1987
+ latest["state"] != "failed" or remediation_claim_is_active(latest)
1988
+ ):
1989
+ raise SystemExit(
1990
+ "Finish or retry the active remediation operation before regenerating."
1991
+ )
1992
+ if latest["state"] == "failed" and latest["pending_action"] is not None:
1993
+ connection.execute(
1994
+ """
1995
+ UPDATE finding_remediation_attempts
1996
+ SET pending_action = NULL, pending_action_claimed_at = NULL,
1997
+ pending_action_claim_token = NULL,
1998
+ pending_action_delivered_at = NULL, updated_at = ?
1999
+ WHERE request_id = ?
2000
+ """,
2001
+ (timestamp, latest["request_id"]),
2002
+ )
2003
+ if latest["state"] in {"generated", "applied"}:
2004
+ connection.execute(
2005
+ """
2006
+ UPDATE finding_remediation_attempts
2007
+ SET state = 'superseded', version = version + 1,
2008
+ pending_action = NULL, pending_action_claimed_at = NULL,
2009
+ pending_action_claim_token = NULL,
2010
+ pending_action_delivered_at = NULL, updated_at = ?
2011
+ WHERE request_id = ?
2012
+ """,
2013
+ (timestamp, latest["request_id"]),
2014
+ )
2015
+ connection.execute(
2016
+ """
2017
+ INSERT INTO finding_remediation_attempts (
2018
+ request_id, occurrence_id, state, version, base_revision,
2019
+ base_content_digest, pending_action, pending_action_claimed_at,
2020
+ pending_action_claim_token, created_at, updated_at
2021
+ ) VALUES (?, ?, 'requested', 1, ?, ?, 'generate', ?, ?, ?, ?)
2022
+ """,
2023
+ (
2024
+ request_id,
2025
+ occurrence["id"],
2026
+ base_revision,
2027
+ base_content_digest,
2028
+ timestamp,
2029
+ action_token,
2030
+ timestamp,
2031
+ timestamp,
2032
+ ),
2033
+ )
2034
+ connection.commit()
2035
+ except BaseException:
2036
+ connection.rollback()
2037
+ raise
2038
+ return scan_context(connection, occurrence["scan_id"])
2039
+
2040
+
2041
+ def request_finding_remediation_action(
2042
+ connection: sqlite3.Connection, args: argparse.Namespace
2043
+ ) -> dict[str, Any]:
2044
+ request_id = require_uuid(args.request_id, "request-id")
2045
+ action_token = require_uuid(args.action_token, "action-token")
2046
+ try:
2047
+ occurrence = require_occurrence(connection, args.occurrence_id)
2048
+ require_finding_open(connection, occurrence["id"])
2049
+ scan = require_scan(connection, occurrence["scan_id"])
2050
+ current = connection.execute(
2051
+ "SELECT * FROM finding_remediation_attempts WHERE request_id = ?",
2052
+ (request_id,),
2053
+ ).fetchone()
2054
+ if current is None or current["occurrence_id"] != occurrence["id"]:
2055
+ raise SystemExit("Codex Security finding remediation request not found.")
2056
+ if current["pending_action"] is not None:
2057
+ if (
2058
+ current["pending_action"] == args.action
2059
+ and current["pending_action_claim_token"] == action_token
2060
+ ):
2061
+ connection.commit()
2062
+ return scan_context(connection, occurrence["scan_id"])
2063
+ raise SystemExit("Another remediation operation is already pending.")
2064
+ if current["version"] != args.expected_version:
2065
+ raise SystemExit(
2066
+ "This remediation request changed. Refresh it before recording an update."
2067
+ )
2068
+ required_state = {"apply": "generated", "verify": "applied"}[args.action]
2069
+ if current["state"] != required_state:
2070
+ raise SystemExit(
2071
+ f"Finding remediation cannot request {args.action} from {current['state']}."
2072
+ )
2073
+ if current["patch_path"] is None or current["patch_digest"] is None:
2074
+ raise SystemExit(
2075
+ "Generated remediation states require a scan-local patch path and digest."
2076
+ )
2077
+ require_matching_patch_digest(scan, current["patch_path"], current["patch_digest"])
2078
+ require_remediation_checkout_unchanged(
2079
+ scan,
2080
+ current,
2081
+ require_base_content=args.action == "apply",
2082
+ require_applied_content=args.action == "verify",
2083
+ )
2084
+ connection.execute("BEGIN IMMEDIATE")
2085
+ timestamp = now()
2086
+ occurrence = require_occurrence(connection, args.occurrence_id)
2087
+ require_finding_open(connection, occurrence["id"])
2088
+ updated = connection.execute(
2089
+ """
2090
+ UPDATE finding_remediation_attempts
2091
+ SET pending_action = ?, pending_action_claimed_at = ?,
2092
+ pending_action_claim_token = ?, pending_action_delivered_at = NULL,
2093
+ version = version + 1, updated_at = ?
2094
+ WHERE request_id = ? AND occurrence_id = ? AND version = ? AND pending_action IS NULL
2095
+ """,
2096
+ (
2097
+ args.action,
2098
+ timestamp,
2099
+ action_token,
2100
+ timestamp,
2101
+ request_id,
2102
+ occurrence["id"],
2103
+ args.expected_version,
2104
+ ),
2105
+ )
2106
+ if updated.rowcount != 1:
2107
+ raise SystemExit(
2108
+ "This remediation request changed. Refresh it before recording an update."
2109
+ )
2110
+ connection.commit()
2111
+ except BaseException:
2112
+ connection.rollback()
2113
+ raise
2114
+ return scan_context(connection, occurrence["scan_id"])
2115
+
2116
+
2117
+ def claim_finding_remediation_resend(
2118
+ connection: sqlite3.Connection, args: argparse.Namespace
2119
+ ) -> dict[str, Any]:
2120
+ request_id = require_uuid(args.request_id, "request-id")
2121
+ action_token = require_uuid(args.action_token, "action-token")
2122
+ connection.execute("BEGIN IMMEDIATE")
2123
+ try:
2124
+ timestamp = now()
2125
+ occurrence = require_occurrence(connection, args.occurrence_id)
2126
+ require_finding_open(connection, occurrence["id"])
2127
+ current = connection.execute(
2128
+ "SELECT * FROM finding_remediation_attempts WHERE request_id = ?",
2129
+ (request_id,),
2130
+ ).fetchone()
2131
+ if current is None or current["occurrence_id"] != occurrence["id"]:
2132
+ raise SystemExit("Codex Security finding remediation request not found.")
2133
+ if current["pending_action"] is None:
2134
+ raise SystemExit("This remediation attempt does not have a pending host request.")
2135
+ if current["pending_action_claim_token"] == action_token:
2136
+ connection.commit()
2137
+ result = scan_context(connection, occurrence["scan_id"])
2138
+ result["actionToken"] = action_token
2139
+ return result
2140
+ delivered_at = current["pending_action_delivered_at"]
2141
+ if delivered_at is not None:
2142
+ claimed_token = action_token
2143
+ updated = connection.execute(
2144
+ """
2145
+ UPDATE finding_remediation_attempts
2146
+ SET pending_action_claimed_at = ?, pending_action_claim_token = ?,
2147
+ pending_action_delivered_at = NULL, updated_at = ?
2148
+ WHERE request_id = ? AND occurrence_id = ? AND pending_action IS NOT NULL
2149
+ AND pending_action_claim_token = ? AND pending_action_delivered_at <= ?
2150
+ """,
2151
+ (
2152
+ timestamp,
2153
+ action_token,
2154
+ timestamp,
2155
+ request_id,
2156
+ occurrence["id"],
2157
+ current["pending_action_claim_token"],
2158
+ stale_claim_before(DELIVERED_ACTION_LEASE_SECONDS),
2159
+ ),
2160
+ )
2161
+ unavailable = (
2162
+ "This remediation worker is still within its execution lease. Retry later."
2163
+ )
2164
+ else:
2165
+ claimed_token = action_token
2166
+ updated = connection.execute(
2167
+ """
2168
+ UPDATE finding_remediation_attempts
2169
+ SET pending_action_claimed_at = ?, pending_action_claim_token = ?,
2170
+ pending_action_delivered_at = NULL, updated_at = ?
2171
+ WHERE request_id = ? AND occurrence_id = ? AND pending_action IS NOT NULL
2172
+ AND (
2173
+ pending_action_claim_token IS NULL
2174
+ OR pending_action_claimed_at IS NULL
2175
+ OR pending_action_claimed_at <= ?
2176
+ )
2177
+ """,
2178
+ (
2179
+ timestamp,
2180
+ action_token,
2181
+ timestamp,
2182
+ request_id,
2183
+ occurrence["id"],
2184
+ stale_claim_before(),
2185
+ ),
2186
+ )
2187
+ unavailable = "This remediation host request is still owned by another panel. Retry after its lease expires."
2188
+ if updated.rowcount != 1:
2189
+ raise SystemExit(unavailable)
2190
+ connection.commit()
2191
+ except BaseException:
2192
+ connection.rollback()
2193
+ raise
2194
+ result = scan_context(connection, occurrence["scan_id"])
2195
+ result["actionToken"] = claimed_token
2196
+ return result
2197
+
2198
+
2199
+ def mark_finding_remediation_delivered(
2200
+ connection: sqlite3.Connection, args: argparse.Namespace
2201
+ ) -> dict[str, Any]:
2202
+ request_id = require_uuid(args.request_id, "request-id")
2203
+ action_token = require_uuid(args.action_token, "action-token")
2204
+ timestamp = now()
2205
+ with connection:
2206
+ occurrence = require_occurrence(connection, args.occurrence_id)
2207
+ updated = connection.execute(
2208
+ """
2209
+ UPDATE finding_remediation_attempts
2210
+ SET pending_action_delivered_at = ?, updated_at = ?
2211
+ WHERE request_id = ? AND occurrence_id = ? AND pending_action IS NOT NULL
2212
+ AND pending_action_claim_token = ?
2213
+ """,
2214
+ (timestamp, timestamp, request_id, occurrence["id"], action_token),
2215
+ )
2216
+ if updated.rowcount != 1:
2217
+ raise SystemExit(
2218
+ "This remediation host request is no longer owned by this action token."
2219
+ )
2220
+ return scan_context(connection, occurrence["scan_id"])
2221
+
2222
+
2223
+ def release_finding_remediation_claim(
2224
+ connection: sqlite3.Connection, args: argparse.Namespace
2225
+ ) -> dict[str, Any]:
2226
+ request_id = require_uuid(args.request_id, "request-id")
2227
+ action_token = require_uuid(args.action_token, "action-token")
2228
+ timestamp = now()
2229
+ with connection:
2230
+ occurrence = require_occurrence(connection, args.occurrence_id)
2231
+ connection.execute(
2232
+ """
2233
+ UPDATE finding_remediation_attempts
2234
+ SET pending_action_claimed_at = NULL, pending_action_claim_token = NULL,
2235
+ pending_action_delivered_at = NULL, updated_at = ?
2236
+ WHERE request_id = ? AND occurrence_id = ? AND pending_action IS NOT NULL
2237
+ AND pending_action_claim_token = ?
2238
+ """,
2239
+ (timestamp, request_id, occurrence["id"], action_token),
2240
+ )
2241
+ return scan_context(connection, occurrence["scan_id"])
2242
+
2243
+
2244
+ def set_finding_remediation(
2245
+ connection: sqlite3.Connection, args: argparse.Namespace
2246
+ ) -> dict[str, Any]:
2247
+ request_id = require_uuid(args.request_id, "request-id")
2248
+ action_token = require_uuid(args.action_token, "action-token")
2249
+ summary = optional_text(args.summary, maximum=2400)
2250
+ verification_summary = optional_text(args.verification_summary, maximum=2400)
2251
+ try:
2252
+ occurrence = require_occurrence(connection, args.occurrence_id)
2253
+ require_finding_open(connection, occurrence["id"])
2254
+ scan = require_scan(connection, occurrence["scan_id"])
2255
+ current = connection.execute(
2256
+ "SELECT * FROM finding_remediation_attempts WHERE request_id = ?",
2257
+ (request_id,),
2258
+ ).fetchone()
2259
+ if current is None or current["occurrence_id"] != occurrence["id"]:
2260
+ raise SystemExit("Codex Security finding remediation request not found.")
2261
+ if current["version"] != args.expected_version:
2262
+ raise SystemExit(
2263
+ "This remediation request changed. Refresh it before recording an update."
2264
+ )
2265
+ if current["pending_action_claim_token"] is None:
2266
+ raise SystemExit(
2267
+ "This remediation attempt does not have an owned pending host request."
2268
+ )
2269
+ if current["pending_action_claim_token"] != action_token:
2270
+ raise SystemExit("This remediation host request is owned by a different action token.")
2271
+ require_remediation_transition(current["state"], args.state)
2272
+ require_pending_remediation_action(current, args.state)
2273
+ patch_path = current["patch_path"]
2274
+ if args.patch_path is not None:
2275
+ requested_patch_path = require_scan_relative_file(scan, args.patch_path)
2276
+ if patch_path is not None and requested_patch_path != patch_path:
2277
+ raise SystemExit("A remediation attempt cannot replace its reviewed patch path.")
2278
+ patch_path = requested_patch_path
2279
+ patch_digest = current["patch_digest"]
2280
+ if args.patch_digest is not None:
2281
+ requested_patch_digest = require_sha256_digest(args.patch_digest, "patch-digest")
2282
+ if patch_digest is not None and requested_patch_digest != patch_digest:
2283
+ raise SystemExit("A remediation attempt cannot replace its reviewed patch digest.")
2284
+ patch_digest = requested_patch_digest
2285
+ base_revision = optional_text(args.base_revision, maximum=512)
2286
+ if args.state in {"generated", "applied", "verifying", "verified"}:
2287
+ if patch_path is None or patch_digest is None:
2288
+ raise SystemExit(
2289
+ "Generated remediation states require a scan-local patch path and digest."
2290
+ )
2291
+ require_matching_patch_digest(scan, patch_path, patch_digest)
2292
+ if args.state == "generated":
2293
+ require_remediation_checkout_unchanged(scan, current, require_base_content=True)
2294
+ if args.state in {"applied", "verifying", "verified"}:
2295
+ if base_revision != current["base_revision"]:
2296
+ raise SystemExit(
2297
+ "The remediation base revision changed. Regenerate the patch before applying it."
2298
+ )
2299
+ if args.state in {"verifying", "verified"}:
2300
+ require_remediation_checkout_unchanged(
2301
+ scan,
2302
+ current,
2303
+ require_applied_content=True,
2304
+ )
2305
+ if args.state == "verified" and verification_summary is None:
2306
+ raise SystemExit("Verified remediation requires a verification summary.")
2307
+ applied_content_digest = current["applied_content_digest"]
2308
+ if args.state == "applied":
2309
+ applied_content_digest = require_reviewed_patch_applied(
2310
+ scan,
2311
+ current,
2312
+ patch_path,
2313
+ )
2314
+ connection.execute("BEGIN IMMEDIATE")
2315
+ timestamp = now()
2316
+ occurrence = require_occurrence(connection, args.occurrence_id)
2317
+ require_finding_open(connection, occurrence["id"])
2318
+ replace_failure_summary = current["state"] == "failed" and args.state != "failed"
2319
+ updated = connection.execute(
2320
+ """
2321
+ UPDATE finding_remediation_attempts
2322
+ SET state = ?, version = version + 1, patch_path = ?, patch_digest = ?,
2323
+ applied_content_digest = ?,
2324
+ pending_action = CASE
2325
+ WHEN ? IN ('verifying', 'failed') THEN pending_action ELSE NULL
2326
+ END,
2327
+ pending_action_claimed_at = CASE
2328
+ WHEN ? = 'verifying' THEN pending_action_claimed_at ELSE NULL
2329
+ END,
2330
+ pending_action_claim_token = CASE
2331
+ WHEN ? = 'verifying' THEN pending_action_claim_token ELSE NULL
2332
+ END,
2333
+ pending_action_delivered_at = CASE
2334
+ WHEN ? = 'verifying' THEN pending_action_delivered_at ELSE NULL
2335
+ END,
2336
+ summary = CASE WHEN ? THEN ? ELSE COALESCE(?, summary) END,
2337
+ verification_summary = COALESCE(?, verification_summary),
2338
+ updated_at = ?
2339
+ WHERE request_id = ? AND occurrence_id = ? AND version = ?
2340
+ AND pending_action_claim_token = ?
2341
+ """,
2342
+ (
2343
+ args.state,
2344
+ patch_path,
2345
+ patch_digest,
2346
+ applied_content_digest,
2347
+ args.state,
2348
+ args.state,
2349
+ args.state,
2350
+ args.state,
2351
+ replace_failure_summary,
2352
+ summary,
2353
+ summary,
2354
+ verification_summary,
2355
+ timestamp,
2356
+ request_id,
2357
+ occurrence["id"],
2358
+ args.expected_version,
2359
+ action_token,
2360
+ ),
2361
+ )
2362
+ if updated.rowcount != 1:
2363
+ raise SystemExit(
2364
+ "This remediation request changed. Refresh it before recording an update."
2365
+ )
2366
+ connection.commit()
2367
+ except BaseException:
2368
+ connection.rollback()
2369
+ raise
2370
+ return scan_context(connection, occurrence["scan_id"])
2371
+
2372
+
2373
+ def export_findings(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
2374
+ scan = require_scan(connection, args.scan_id)
2375
+ if scan["status"] != "complete":
2376
+ raise SystemExit("Findings can be exported after the scan completes.")
2377
+ scan_dir = require_canonical_scan_directory(Path(scan["scan_dir"]))
2378
+ require_recorded_manifest_digest(scan, scan_dir)
2379
+ verify_manifest_binding(scan, read_json_object(scan_dir / ARTIFACTS["manifest"]))
2380
+ try:
2381
+ manifest, _, _ = finalize_scan(
2382
+ scan_dir,
2383
+ expected_coverage_mode=expected_coverage_mode(scan),
2384
+ )
2385
+ except ContractError as exc:
2386
+ raise SystemExit(str(exc)) from exc
2387
+ verify_manifest_binding(scan, manifest)
2388
+ manifest_digest = published_manifest_digest(scan_dir, manifest)
2389
+ pin_legacy_manifest_digest(connection, scan["id"], manifest_digest)
2390
+ if args.format == "json":
2391
+ path = artifact_path(scan_dir, ARTIFACTS["findings"], required=True)
2392
+ elif args.format == "sarif":
2393
+ try:
2394
+ write_sarif_projection(scan_dir)
2395
+ except ContractError as exc:
2396
+ raise SystemExit(str(exc)) from exc
2397
+ path = artifact_path(scan_dir, "exports/results.sarif", required=True)
2398
+ else:
2399
+ path = write_csv_export(connection, scan)
2400
+ if path is None:
2401
+ raise SystemExit(f"Could not export Codex Security findings as {args.format.upper()}.")
2402
+ return {
2403
+ "export": {"format": args.format, "path": str(path)},
2404
+ "scan": scan_result(connection, scan),
2405
+ "workspace": workspace_state(connection, scan["workspace_id"]),
2406
+ }
2407
+
2408
+
2409
+ def write_csv_export(connection: sqlite3.Connection, scan: sqlite3.Row) -> Path:
2410
+ scan_dir = require_canonical_scan_directory(Path(scan["scan_dir"]))
2411
+ output = io.StringIO(newline="")
2412
+ writer = csv.writer(output)
2413
+ deep_scan = scan["mode"] == "deep"
2414
+ candidate_ids_by_occurrence: dict[str, str] = {}
2415
+ if deep_scan:
2416
+ findings_document = read_json_object(scan_dir / ARTIFACTS["findings"])
2417
+ findings = findings_document.get("findings")
2418
+ if not isinstance(findings, list):
2419
+ raise SystemExit("findings.json must contain a findings array.")
2420
+ for finding in findings:
2421
+ if not isinstance(finding, dict):
2422
+ raise SystemExit("findings.json entries must be objects.")
2423
+ occurrence_id = finding.get("occurrenceId")
2424
+ candidate_id = finding_candidate_id(finding)
2425
+ if isinstance(occurrence_id, str) and isinstance(candidate_id, str):
2426
+ candidate_ids_by_occurrence[occurrence_id] = candidate_id
2427
+ columns = (
2428
+ "occurrence_id",
2429
+ "finding_id",
2430
+ *(("candidate_id",) if deep_scan else ()),
2431
+ "title",
2432
+ "summary",
2433
+ "severity",
2434
+ "confidence",
2435
+ "status",
2436
+ "close_reason",
2437
+ "note",
2438
+ "remediation",
2439
+ "path",
2440
+ "start_line",
2441
+ "end_line",
2442
+ )
2443
+ writer.writerow(columns)
2444
+ for row in finding_export_rows(connection, scan["id"]):
2445
+ writer.writerow(
2446
+ (
2447
+ csv_cell(row["occurrence_id"]),
2448
+ csv_cell(row["finding_id"]),
2449
+ *(
2450
+ (csv_cell(candidate_ids_by_occurrence.get(row["occurrence_id"])),)
2451
+ if deep_scan
2452
+ else ()
2453
+ ),
2454
+ csv_cell(row["title"]),
2455
+ csv_cell(row["summary"]),
2456
+ csv_cell(row["severity"]),
2457
+ csv_cell(row["confidence"]),
2458
+ csv_cell(row["status"]),
2459
+ csv_cell(row["close_reason"]),
2460
+ csv_cell(row["note"]),
2461
+ csv_cell(row["remediation"]),
2462
+ csv_cell(row["relative_path"]),
2463
+ row["start_line"],
2464
+ row["end_line"],
2465
+ )
2466
+ )
2467
+ try:
2468
+ write_scan_local_bytes(
2469
+ scan_dir,
2470
+ "exports/findings.csv",
2471
+ output.getvalue().encode("utf-8"),
2472
+ )
2473
+ except ContractError as exc:
2474
+ raise SystemExit(
2475
+ "exports: expected a regular directory inside the scan directory."
2476
+ ) from exc
2477
+ destination = scan_dir / "exports" / "findings.csv"
2478
+ path = available_artifact_path(scan_dir, destination)
2479
+ if path is None:
2480
+ raise SystemExit("findings.csv: expected a regular file inside the scan directory.")
2481
+ return path
2482
+
2483
+
2484
+ def finding_export_rows(connection: sqlite3.Connection, scan_id: str) -> sqlite3.Cursor:
2485
+ return connection.execute(
2486
+ """
2487
+ SELECT
2488
+ occurrences.id AS occurrence_id,
2489
+ occurrences.finding_id,
2490
+ occurrences.title,
2491
+ occurrences.summary,
2492
+ occurrences.severity,
2493
+ occurrences.confidence,
2494
+ occurrences.remediation,
2495
+ COALESCE(triage.status, 'open') AS status,
2496
+ triage.close_reason,
2497
+ triage.note,
2498
+ locations.relative_path,
2499
+ locations.start_line,
2500
+ locations.end_line
2501
+ FROM finding_occurrences AS occurrences
2502
+ LEFT JOIN finding_triage AS triage ON triage.occurrence_id = occurrences.id
2503
+ LEFT JOIN finding_locations AS locations
2504
+ ON locations.occurrence_id = occurrences.id
2505
+ AND locations.sort_order = (
2506
+ SELECT primary_location.sort_order
2507
+ FROM finding_locations AS primary_location
2508
+ WHERE primary_location.occurrence_id = occurrences.id
2509
+ ORDER BY
2510
+ CASE WHEN primary_location.role = 'root_control' THEN 0 ELSE 1 END,
2511
+ primary_location.sort_order
2512
+ LIMIT 1
2513
+ )
2514
+ WHERE occurrences.scan_id = ?
2515
+ ORDER BY occurrences.created_at, occurrences.id
2516
+ """,
2517
+ (scan_id,),
2518
+ )
2519
+
2520
+
2521
+ def require_remediation_transition(current: str, requested: str) -> None:
2522
+ allowed = {
2523
+ "requested": {"requested", "generated", "failed"},
2524
+ "generated": {"generated", "applied", "failed"},
2525
+ "applied": {"applied", "verifying", "failed"},
2526
+ "verifying": {"verifying", "verified", "failed"},
2527
+ "verified": {"verifying", "verified"},
2528
+ "failed": {"generated", "applied", "verifying", "verified", "failed"},
2529
+ }
2530
+ if requested not in allowed.get(current, set()):
2531
+ raise SystemExit(f"Finding remediation cannot move from {current} to {requested}.")
2532
+
2533
+
2534
+ def require_pending_remediation_action(current: sqlite3.Row, requested: str) -> None:
2535
+ pending_action = current["pending_action"]
2536
+ if pending_action is not None:
2537
+ allowed = {
2538
+ "generate": {"generated", "failed"},
2539
+ "apply": {"applied", "failed"},
2540
+ "verify": {"verifying", "verified", "failed"},
2541
+ }
2542
+ if requested not in allowed[pending_action]:
2543
+ raise SystemExit(
2544
+ f"Pending remediation action {pending_action} cannot record state {requested}."
2545
+ )
2546
+ return
2547
+ required_action = {
2548
+ ("requested", "generated"): "generate",
2549
+ ("generated", "applied"): "apply",
2550
+ ("applied", "verifying"): "verify",
2551
+ }.get((current["state"], requested))
2552
+ if required_action is not None:
2553
+ raise SystemExit(
2554
+ f"Request {required_action} before recording remediation state {requested}."
2555
+ )
2556
+
2557
+
2558
+ def remediation_checkout_snapshot(
2559
+ scan: sqlite3.Row, *, expected_revision: str | None = None
2560
+ ) -> tuple[str, str | None]:
2561
+ target = require_scan_target_identity(scan)
2562
+ revision = git_revision(target)
2563
+ required_revision = expected_revision or scan["target_revision"]
2564
+ if revision != required_revision:
2565
+ raise SystemExit(
2566
+ "Repository HEAD changed. Regenerate the remediation patch against the current checkout."
2567
+ )
2568
+ content_digest = (
2569
+ worktree_content_digest(target)
2570
+ if revision != "unversioned"
2571
+ else directory_content_digest(target, excluded=(Path(scan["scan_dir"]),))
2572
+ )
2573
+ return revision, content_digest
2574
+
2575
+
2576
+ def require_reviewed_patch_applied(
2577
+ scan: sqlite3.Row, remediation: sqlite3.Row, patch_path: str
2578
+ ) -> str | None:
2579
+ target = require_scan_target_identity(scan)
2580
+ _, content_digest = remediation_checkout_snapshot(
2581
+ scan, expected_revision=remediation["base_revision"]
2582
+ )
2583
+ if content_digest == remediation["base_content_digest"]:
2584
+ raise SystemExit(
2585
+ "The selected checkout is unchanged; apply the reviewed patch before recording it as applied."
2586
+ )
2587
+ unversioned = remediation["base_revision"] == "unversioned"
2588
+ excluded = (Path(scan["scan_dir"]),)
2589
+ git_dir = None
2590
+ pathspec = None
2591
+ if not unversioned:
2592
+ _, pathspec = git_worktree_context(target)
2593
+ git_dir = git_output(target, "rev-parse", "--absolute-git-dir")
2594
+ if git_dir is None:
2595
+ raise SystemExit("Could not inspect the selected Git working tree.")
2596
+ excluded += git_submodule_paths(target)
2597
+ with tempfile.TemporaryDirectory(prefix="codex-security-remediation-") as temporary:
2598
+ reviewed_patch = Path(temporary) / "reviewed.patch"
2599
+ digest = hashlib.sha256()
2600
+ with open_scan_local_file(Path(scan["scan_dir"]), patch_path) as source:
2601
+ with reviewed_patch.open("xb") as destination:
2602
+ for chunk in iter(lambda: source.read(1024 * 1024), b""):
2603
+ digest.update(chunk)
2604
+ destination.write(chunk)
2605
+ if f"sha256:{digest.hexdigest()}" != remediation["patch_digest"]:
2606
+ raise SystemExit("Patch digest does not match the scan-local patch file.")
2607
+ checkout_root = Path(temporary) / "checkout"
2608
+ if unversioned:
2609
+ checkout = checkout_root
2610
+ copy_directory_excluding(target, checkout, excluded)
2611
+ else:
2612
+ checkout = copy_git_worktree_files(target, checkout_root, excluded)
2613
+ arguments = ["apply", "--reverse", "--whitespace=nowarn"]
2614
+ if unversioned:
2615
+ arguments.append("--no-index")
2616
+ elif pathspec != ".":
2617
+ arguments.append(f"--directory={pathspec}")
2618
+ arguments.append(str(reviewed_patch))
2619
+ applied = git_command(
2620
+ checkout if unversioned else checkout_root,
2621
+ *arguments,
2622
+ text=True,
2623
+ git_dir=Path(git_dir) if git_dir is not None else None,
2624
+ work_tree=checkout_root if git_dir is not None else None,
2625
+ )
2626
+ if applied.returncode != 0:
2627
+ raise SystemExit(
2628
+ "The selected checkout does not contain the reviewed remediation patch. Apply exactly that patch before recording it as applied."
2629
+ )
2630
+ reverted_digest = (
2631
+ directory_content_digest(checkout)
2632
+ if unversioned
2633
+ else worktree_content_digest_for_context(
2634
+ checkout_root,
2635
+ pathspec or ".",
2636
+ git_dir=Path(git_dir),
2637
+ work_tree=checkout_root,
2638
+ )
2639
+ )
2640
+ if reverted_digest != remediation["base_content_digest"]:
2641
+ raise SystemExit(
2642
+ "The selected checkout contains changes outside the reviewed patch. Remove them before recording the patch as applied."
2643
+ )
2644
+ return content_digest
2645
+
2646
+
2647
+ def require_remediation_checkout_unchanged(
2648
+ scan: sqlite3.Row,
2649
+ remediation: sqlite3.Row,
2650
+ *,
2651
+ require_applied_content: bool = False,
2652
+ require_base_content: bool = False,
2653
+ ) -> None:
2654
+ _, content_digest = remediation_checkout_snapshot(
2655
+ scan, expected_revision=remediation["base_revision"]
2656
+ )
2657
+ expected_digest = (
2658
+ remediation["applied_content_digest"]
2659
+ if require_applied_content
2660
+ else remediation["base_content_digest"]
2661
+ if require_base_content
2662
+ else None
2663
+ )
2664
+ if expected_digest is not None and content_digest != expected_digest:
2665
+ raise SystemExit(
2666
+ "Working-tree contents changed. Regenerate the remediation patch against the current checkout."
2667
+ )
2668
+
2669
+
2670
+ def require_sha256_digest(value: str, label: str) -> str:
2671
+ normalized = optional_text(value, maximum=71)
2672
+ if (
2673
+ normalized is None
2674
+ or not normalized.startswith("sha256:")
2675
+ or len(normalized) != 71
2676
+ or any(
2677
+ character not in "0123456789abcdef" for character in normalized.removeprefix("sha256:")
2678
+ )
2679
+ ):
2680
+ raise SystemExit(f"{label} must use sha256:<64 lowercase hex characters>.")
2681
+ return normalized
2682
+
2683
+
2684
+ def require_scan_relative_file(scan: sqlite3.Row, value: str) -> str:
2685
+ normalized = optional_text(value, maximum=4096)
2686
+ if normalized is None or "\\" in normalized:
2687
+ raise SystemExit("Patch path must identify a scan-local regular file.")
2688
+ parsed = PurePosixPath(normalized)
2689
+ if parsed.is_absolute() or ".." in parsed.parts:
2690
+ raise SystemExit("Patch path must identify a scan-local regular file.")
2691
+ path = artifact_path(Path(scan["scan_dir"]), parsed.as_posix(), required=True)
2692
+ if path is None:
2693
+ raise SystemExit("Patch path must identify a scan-local regular file.")
2694
+ return parsed.as_posix()
2695
+
2696
+
2697
+ def require_matching_patch_digest(scan: sqlite3.Row, patch_path: str, patch_digest: str) -> None:
2698
+ digest = hashlib.sha256()
2699
+ with open_scan_local_file(Path(scan["scan_dir"]), patch_path) as patch:
2700
+ require_bounded_patch_artifact(patch)
2701
+ while chunk := patch.read(1024 * 1024):
2702
+ digest.update(chunk)
2703
+ if f"sha256:{digest.hexdigest()}" != patch_digest:
2704
+ raise SystemExit("Patch digest does not match the scan-local patch file.")
2705
+
2706
+
2707
+ def require_bounded_patch_artifact(patch: Any) -> None:
2708
+ if os.fstat(patch.fileno()).st_size > PATCH_ARTIFACT_MAX_BYTES:
2709
+ raise SystemExit("Patch artifact must be no larger than 2 MiB.")
2710
+
2711
+
2712
+ def open_scan_local_file(scan_dir: Path, relative_path: str) -> Any:
2713
+ parsed = PurePosixPath(relative_path)
2714
+ if parsed.is_absolute() or not parsed.parts or ".." in parsed.parts:
2715
+ raise SystemExit("Patch path must identify a scan-local regular file.")
2716
+ scan_dir = require_canonical_scan_directory(scan_dir)
2717
+ try:
2718
+ file_fd = open_scan_local_file_descriptor(
2719
+ scan_dir,
2720
+ parsed.as_posix(),
2721
+ "Patch path",
2722
+ )
2723
+ return os.fdopen(file_fd, "rb")
2724
+ except (ContractError, OSError) as exc:
2725
+ raise SystemExit("Patch path must identify a scan-local regular file.") from exc
2726
+
2727
+
2728
+ def index_findings(
2729
+ connection: sqlite3.Connection,
2730
+ scan_id: str,
2731
+ document: dict[str, Any],
2732
+ timestamp: str,
2733
+ ) -> None:
2734
+ findings = document.get("findings")
2735
+ if not isinstance(findings, list):
2736
+ raise SystemExit("findings.json must contain a findings array.")
2737
+ for finding in findings:
2738
+ if not isinstance(finding, dict):
2739
+ raise SystemExit("findings.json entries must be objects.")
2740
+ identity = finding["identity"]
2741
+ fingerprints = finding["fingerprints"]
2742
+ severity = finding["severity"]
2743
+ confidence = finding["confidence"]
2744
+ connection.execute(
2745
+ """
2746
+ INSERT INTO findings (
2747
+ id, fingerprint, rule_id, identity_anchor, identity_instance, created_at, updated_at
2748
+ ) VALUES (?, ?, ?, ?, ?, ?, ?)
2749
+ ON CONFLICT(id) DO UPDATE SET
2750
+ fingerprint = excluded.fingerprint,
2751
+ rule_id = excluded.rule_id,
2752
+ identity_anchor = excluded.identity_anchor,
2753
+ identity_instance = excluded.identity_instance,
2754
+ updated_at = excluded.updated_at
2755
+ """,
2756
+ (
2757
+ finding["findingId"],
2758
+ fingerprints["primary"],
2759
+ finding["ruleId"],
2760
+ identity["anchor"],
2761
+ identity.get("instance"),
2762
+ timestamp,
2763
+ timestamp,
2764
+ ),
2765
+ )
2766
+ connection.execute(
2767
+ """
2768
+ INSERT INTO finding_occurrences (
2769
+ id, finding_id, scan_id, title, summary, severity, confidence, remediation,
2770
+ details_json, created_at
2771
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
2772
+ """,
2773
+ (
2774
+ finding["occurrenceId"],
2775
+ finding["findingId"],
2776
+ scan_id,
2777
+ finding["title"],
2778
+ finding["summary"],
2779
+ severity["level"],
2780
+ confidence["level"],
2781
+ finding["remediation"],
2782
+ json.dumps(finding, allow_nan=False, sort_keys=True),
2783
+ timestamp,
2784
+ ),
2785
+ )
2786
+ for index, location in enumerate(finding["locations"]):
2787
+ connection.execute(
2788
+ """
2789
+ INSERT INTO finding_locations (
2790
+ occurrence_id, relative_path, start_line, end_line, role, sort_order
2791
+ ) VALUES (?, ?, ?, ?, ?, ?)
2792
+ """,
2793
+ (
2794
+ finding["occurrenceId"],
2795
+ location["path"],
2796
+ location["startLine"],
2797
+ location.get("endLine", location["startLine"]),
2798
+ location.get("role"),
2799
+ index,
2800
+ ),
2801
+ )
2802
+
2803
+
2804
+ def diff_target_summary(diff_target: dict[str, str]) -> str:
2805
+ kind = diff_target["kind"]
2806
+ if kind == "working_tree":
2807
+ return "Uncommitted changes"
2808
+ if kind == "commit":
2809
+ return f"Commit {diff_target['headRevision'][:7]}"
2810
+ return f"{diff_target['baseRevision'][:7]}…{diff_target['headRevision'][:7]}"
2811
+
2812
+
2813
+ def workspace_state(
2814
+ connection: sqlite3.Connection,
2815
+ workspace_id: str,
2816
+ *,
2817
+ result_scan_id: str | None = None,
2818
+ thread_id: str | None = None,
2819
+ ) -> dict[str, Any]:
2820
+ workspace = require_workspace(connection, workspace_id)
2821
+ if thread_id is not None and workspace["thread_id"] != optional_text(thread_id, maximum=512):
2822
+ raise SystemExit("Codex Security workspace not found in this thread.")
2823
+ persisted_diff_target = stored_diff_target(workspace)
2824
+ result: dict[str, Any] = {
2825
+ "id": workspace["id"],
2826
+ "diffTarget": persisted_diff_target,
2827
+ "diffResolutionId": workspace["diff_resolution_id"],
2828
+ "mode": workspace["default_mode"],
2829
+ "recentTargets": [],
2830
+ "scope": workspace["default_scope"],
2831
+ "setup": {"submitted": bool(workspace["submitted"])},
2832
+ "setupValidation": {"error": None, "valid": bool(workspace["submitted"])},
2833
+ "targetPath": workspace["target_path"],
2834
+ "targetSummary": workspace["target_summary"],
2835
+ "targetTitle": workspace["target_title"],
2836
+ "updatedAt": workspace["updated_at"],
2837
+ "userContext": workspace["user_context"],
2838
+ }
2839
+ if workspace["capability_preflight_json"]:
2840
+ result["capabilityPreflight"] = json.loads(workspace["capability_preflight_json"])
2841
+ selected_scan_id = result_scan_id or workspace["active_scan_id"]
2842
+ if selected_scan_id:
2843
+ result["results"] = scan_result(connection, require_scan(connection, selected_scan_id))
2844
+ return result
2845
+
2846
+ target_metadata = None
2847
+ setup_error = None
2848
+ validated_diff_target = None
2849
+ if workspace["target_path"]:
2850
+ try:
2851
+ inspected = inspect_setup_values(
2852
+ workspace["target_path"],
2853
+ workspace["default_scope"],
2854
+ workspace["default_mode"],
2855
+ workspace["diff_target_kind"],
2856
+ workspace["diff_base_revision"],
2857
+ workspace["diff_head_revision"],
2858
+ workspace["diff_content_digest"],
2859
+ )
2860
+ target_metadata = inspected["target"]["targetMetadata"]
2861
+ validated_diff_target = inspected["diffTarget"]
2862
+ except SystemExit as exc:
2863
+ setup_error = str(exc)
2864
+ try:
2865
+ target = require_target(workspace["target_path"])
2866
+ target_metadata = git_target_metadata(target)
2867
+ except SystemExit:
2868
+ pass
2869
+ result["diffTarget"] = validated_diff_target or persisted_diff_target
2870
+ result["recentTargets"] = recent_targets(connection)
2871
+ result["setupValidation"] = {
2872
+ "error": setup_error,
2873
+ "valid": setup_error is None and bool(target_metadata),
2874
+ }
2875
+ if target_metadata:
2876
+ result["targetMetadata"] = target_metadata
2877
+ return result
2878
+
2879
+
2880
+ def recent_targets(connection: sqlite3.Connection) -> list[dict[str, Any]]:
2881
+ targets: list[dict[str, Any]] = []
2882
+ rows = connection.execute(
2883
+ """
2884
+ SELECT target_path, MAX(updated_at) AS last_used_at
2885
+ FROM workspaces
2886
+ WHERE submitted = 1 AND target_path IS NOT NULL
2887
+ GROUP BY target_path
2888
+ ORDER BY last_used_at DESC
2889
+ """
2890
+ )
2891
+ for row in rows:
2892
+ try:
2893
+ inspected = inspect_target(row["target_path"])
2894
+ except SystemExit:
2895
+ continue
2896
+ targets.append(inspected)
2897
+ if len(targets) == 5:
2898
+ break
2899
+ return targets
2900
+
2901
+
2902
+ def scan_context(
2903
+ connection: sqlite3.Connection,
2904
+ scan_id: str,
2905
+ occurrence_id: str | None = None,
2906
+ ) -> dict[str, Any]:
2907
+ scan = require_scan(connection, scan_id)
2908
+ context = {
2909
+ "otherRunningDeepScans": deep_scan.other_running_deep_scans(connection, scan["id"]),
2910
+ "scan": scan_result(connection, scan, occurrence_id=occurrence_id),
2911
+ "workspace": workspace_state(connection, scan["workspace_id"], result_scan_id=scan["id"]),
2912
+ }
2913
+ if scan["recipe_json"] is not None:
2914
+ context["parentScanId"] = scan["parent_scan_id"]
2915
+ context["recipe"] = json.loads(scan["recipe_json"], parse_constant=reject_non_finite_json)
2916
+ return context
2917
+
2918
+
2919
+ def list_findings(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
2920
+ scan = require_scan(connection, args.scan_id)
2921
+ backfill_legacy_finding_details(connection, scan)
2922
+ limit = min(args.limit, FINDINGS_PAGE_MAX)
2923
+ rows = scan_history.finding_occurrence_rows(
2924
+ connection,
2925
+ scan["id"],
2926
+ offset=args.offset,
2927
+ limit=limit,
2928
+ query=args.query,
2929
+ severity=args.severity,
2930
+ status=args.status,
2931
+ )
2932
+ conditions, values = scan_history.finding_occurrence_conditions(
2933
+ scan["id"], query=args.query, severity=args.severity, status=args.status
2934
+ )
2935
+ total = connection.execute(
2936
+ f"""
2937
+ SELECT COUNT(*)
2938
+ FROM finding_occurrences AS occurrences
2939
+ LEFT JOIN finding_triage AS triage ON triage.occurrence_id = occurrences.id
2940
+ WHERE {conditions}
2941
+ """,
2942
+ values,
2943
+ ).fetchone()[0]
2944
+ next_offset = args.offset + len(rows)
2945
+ return {
2946
+ "findingsPage": {
2947
+ "findings": [finding_result(connection, scan, row) for row in rows],
2948
+ "limit": limit,
2949
+ "nextOffset": next_offset if next_offset < total else None,
2950
+ "offset": args.offset,
2951
+ "scanId": scan["id"],
2952
+ "total": total,
2953
+ }
2954
+ }
2955
+
2956
+
2957
+ def scan_result(
2958
+ connection: sqlite3.Connection,
2959
+ scan: sqlite3.Row,
2960
+ *,
2961
+ occurrence_id: str | None = None,
2962
+ ) -> dict[str, Any]:
2963
+ backfill_legacy_finding_details(connection, scan)
2964
+ progress = connection.execute(
2965
+ "SELECT * FROM scan_progress WHERE scan_id = ?", (scan["id"],)
2966
+ ).fetchone()
2967
+ artifact_rows = connection.execute(
2968
+ "SELECT kind, path FROM scan_artifacts WHERE scan_id = ?", (scan["id"],)
2969
+ )
2970
+ artifacts = {}
2971
+ for row in artifact_rows:
2972
+ if row["kind"] not in ARTIFACTS:
2973
+ continue
2974
+ path = available_artifact_path(Path(scan["scan_dir"]), Path(row["path"]))
2975
+ if path is not None:
2976
+ artifacts[row["kind"]] = str(path)
2977
+ sarif_path = available_artifact_path(
2978
+ Path(scan["scan_dir"]), Path(scan["scan_dir"]) / "exports" / "results.sarif"
2979
+ )
2980
+ if sarif_path is not None:
2981
+ artifacts["sarifReport"] = str(sarif_path)
2982
+ occurrence_rows = scan_history.finding_occurrence_rows(
2983
+ connection, scan["id"], offset=0, limit=FINDINGS_RESULT_LIMIT
2984
+ )
2985
+ if occurrence_id is not None and all(row["id"] != occurrence_id for row in occurrence_rows):
2986
+ occurrence = require_occurrence(connection, occurrence_id)
2987
+ if occurrence["scan_id"] != scan["id"]:
2988
+ raise SystemExit("This finding does not belong to the selected scan.")
2989
+ occurrence_rows.append(occurrence)
2990
+ finding_count = connection.execute(
2991
+ "SELECT COUNT(*) FROM finding_occurrences WHERE scan_id = ?", (scan["id"],)
2992
+ ).fetchone()[0]
2993
+ severity_counts = {
2994
+ row["severity"]: row["count"]
2995
+ for row in connection.execute(
2996
+ """
2997
+ SELECT severity, COUNT(*) AS count
2998
+ FROM finding_occurrences
2999
+ WHERE scan_id = ?
3000
+ GROUP BY severity
3001
+ """,
3002
+ (scan["id"],),
3003
+ )
3004
+ }
3005
+ remediation_available, remediation_unavailable_reason = remediation_availability(scan)
3006
+ independent_reviews = (
3007
+ deep_scan.independent_review_progress(connection, scan["id"])
3008
+ if scan["mode"] == "deep"
3009
+ else None
3010
+ )
3011
+ progress_result = {
3012
+ "candidates": {"reportable": progress["reportable_findings_count"]},
3013
+ "coverage": {
3014
+ "closedRows": progress["review_items_completed"],
3015
+ "filesTotal": progress["scope_file_count"],
3016
+ "worklistRows": progress["review_items_total"],
3017
+ },
3018
+ "phase": scan["phase"],
3019
+ "phaseProgress": {
3020
+ "completed": progress["phase_items_completed"],
3021
+ "total": progress["phase_items_total"],
3022
+ "unit": progress["phase_progress_unit"],
3023
+ },
3024
+ "preflightProgress": {
3025
+ "completed": progress["preflight_checks_completed"],
3026
+ "total": progress["preflight_checks_total"],
3027
+ },
3028
+ "preflightIssues": json.loads(progress["preflight_issues_json"]),
3029
+ "reviewPass": progress["deep_review_pass"],
3030
+ "status": "canceled" if scan["canceled_at"] else scan["status"],
3031
+ "updatedAt": progress["updated_at"],
3032
+ }
3033
+ if independent_reviews is not None:
3034
+ progress_result["independentReviews"] = {
3035
+ "active": independent_reviews["active"],
3036
+ "completed": independent_reviews["completed"],
3037
+ }
3038
+ return {
3039
+ "artifacts": artifacts,
3040
+ "canceledAt": scan["canceled_at"],
3041
+ **(
3042
+ {"cost": json.loads(scan["cost_json"], parse_constant=reject_non_finite_json)}
3043
+ if scan["cost_json"] is not None
3044
+ else {}
3045
+ ),
3046
+ "contract": scan_contract(scan),
3047
+ "continuationThreadId": scan["continuation_thread_id"],
3048
+ "failureMessage": scan["failure_message"],
3049
+ "findings": [finding_result(connection, scan, row) for row in occurrence_rows],
3050
+ "findingCount": finding_count,
3051
+ "findingsTruncated": finding_count > len(occurrence_rows),
3052
+ "severityCounts": severity_counts,
3053
+ "handoffClaimedAt": scan["handoff_claimed_at"],
3054
+ "handoffClaimToken": scan["handoff_claim_token"],
3055
+ "handoffStatus": scan["handoff_status"],
3056
+ "mode": scan["mode"],
3057
+ "diffTarget": stored_diff_target(scan),
3058
+ "progress": progress_result,
3059
+ "remediationAvailable": remediation_available,
3060
+ "remediationUnavailableReason": remediation_unavailable_reason,
3061
+ "reportAvailable": "markdownReport" in artifacts,
3062
+ "scanDir": scan["scan_dir"],
3063
+ "scanId": scan["id"],
3064
+ "scope": scan["scope"],
3065
+ "targetPath": scan["target_path"],
3066
+ "targetRevision": scan["target_revision"],
3067
+ "targetSummary": scan["target_summary"],
3068
+ "updatedAt": max(
3069
+ scan["updated_at"],
3070
+ progress["updated_at"],
3071
+ str(independent_reviews["updatedAt"]) if independent_reviews is not None else "",
3072
+ finding_management_updated_at(connection, scan["id"]) or "",
3073
+ ),
3074
+ "userContext": scan["user_context"],
3075
+ }
3076
+
3077
+
3078
+ def remediation_availability(scan: sqlite3.Row) -> tuple[bool, str | None]:
3079
+ try:
3080
+ current_revision = git_revision(require_scan_target_identity(scan))
3081
+ except SystemExit as exc:
3082
+ return False, str(exc)
3083
+ expected_revision = scan["target_revision"]
3084
+ if current_revision == expected_revision:
3085
+ return True, None
3086
+ return (
3087
+ False,
3088
+ (
3089
+ "Remediation is unavailable because the selected checkout is not at the revision "
3090
+ "that was scanned. Check out the scanned revision or start a new scan."
3091
+ ),
3092
+ )
3093
+
3094
+
3095
+ def backfill_legacy_finding_details(connection: sqlite3.Connection, scan: sqlite3.Row) -> None:
3096
+ if scan["status"] != "complete" or connection.in_transaction:
3097
+ return
3098
+ legacy_rows = connection.execute(
3099
+ """
3100
+ SELECT id, finding_id, title, summary, severity, confidence, remediation
3101
+ FROM finding_occurrences
3102
+ WHERE scan_id = ? AND details_json = '{}'
3103
+ """,
3104
+ (scan["id"],),
3105
+ ).fetchall()
3106
+ if not legacy_rows:
3107
+ return
3108
+
3109
+ try:
3110
+ scan_dir = require_canonical_scan_directory(Path(scan["scan_dir"]))
3111
+ require_recorded_manifest_digest(scan, scan_dir)
3112
+ verify_manifest_binding(scan, read_json_object(scan_dir / ARTIFACTS["manifest"]))
3113
+ manifest, findings_document, _ = finalize_scan(
3114
+ scan_dir,
3115
+ expected_coverage_mode=expected_coverage_mode(scan),
3116
+ )
3117
+ verify_manifest_binding(scan, manifest)
3118
+ manifest_digest = published_manifest_digest(scan_dir, manifest)
3119
+ except (ContractError, OSError, SystemExit, ValueError):
3120
+ return
3121
+
3122
+ findings = findings_document.get("findings")
3123
+ if not isinstance(findings, list):
3124
+ return
3125
+ by_occurrence = {
3126
+ finding.get("occurrenceId"): finding
3127
+ for finding in findings
3128
+ if isinstance(finding, dict) and isinstance(finding.get("occurrenceId"), str)
3129
+ }
3130
+ updates = []
3131
+ for row in legacy_rows:
3132
+ finding = by_occurrence.get(row["id"])
3133
+ if not legacy_finding_matches(row, finding):
3134
+ continue
3135
+ updates.append(
3136
+ (
3137
+ json.dumps(finding, allow_nan=False, sort_keys=True),
3138
+ scan["id"],
3139
+ row["id"],
3140
+ )
3141
+ )
3142
+ if not updates:
3143
+ return
3144
+
3145
+ connection.execute("BEGIN IMMEDIATE")
3146
+ try:
3147
+ current = require_scan(connection, scan["id"])
3148
+ recorded_digest = current["seal_manifest_digest"]
3149
+ if recorded_digest is not None and recorded_digest != manifest_digest:
3150
+ raise SystemExit("The sealed scan manifest changed after completion.")
3151
+ connection.executemany(
3152
+ """
3153
+ UPDATE finding_occurrences
3154
+ SET details_json = ?
3155
+ WHERE scan_id = ? AND id = ? AND details_json = '{}'
3156
+ """,
3157
+ updates,
3158
+ )
3159
+ if recorded_digest is None:
3160
+ connection.execute(
3161
+ "UPDATE scans SET seal_manifest_digest = ? WHERE id = ?",
3162
+ (manifest_digest, scan["id"]),
3163
+ )
3164
+ connection.commit()
3165
+ except BaseException:
3166
+ connection.rollback()
3167
+ raise
3168
+
3169
+
3170
+ def legacy_finding_matches(row: sqlite3.Row, finding: Any) -> bool:
3171
+ if not isinstance(finding, dict):
3172
+ return False
3173
+ severity = finding.get("severity")
3174
+ confidence = finding.get("confidence")
3175
+ return (
3176
+ finding.get("findingId") == row["finding_id"]
3177
+ and finding.get("title") == row["title"]
3178
+ and finding.get("summary") == row["summary"]
3179
+ and finding.get("remediation") == row["remediation"]
3180
+ and isinstance(severity, dict)
3181
+ and severity.get("level") == row["severity"]
3182
+ and isinstance(confidence, dict)
3183
+ and confidence.get("level") == row["confidence"]
3184
+ )
3185
+
3186
+
3187
+ def finding_result(
3188
+ connection: sqlite3.Connection,
3189
+ scan: sqlite3.Row,
3190
+ occurrence: sqlite3.Row,
3191
+ ) -> dict[str, Any]:
3192
+ details = bounded_finding_details(read_finding_details(occurrence["details_json"]))
3193
+ confidence = details.get("confidence")
3194
+ confidence = confidence if isinstance(confidence, dict) else {}
3195
+ severity = details.get("severity")
3196
+ severity = severity if isinstance(severity, dict) else {}
3197
+ locations = []
3198
+ try:
3199
+ target = require_scan_target_identity(scan)
3200
+ except SystemExit:
3201
+ target = None
3202
+ for row in connection.execute(
3203
+ """
3204
+ SELECT relative_path, start_line, end_line, role
3205
+ FROM finding_locations
3206
+ WHERE occurrence_id = ?
3207
+ ORDER BY CASE WHEN role = 'root_control' THEN 0 ELSE 1 END, sort_order
3208
+ LIMIT ?
3209
+ """,
3210
+ (occurrence["id"], FINDING_LOCATIONS_LIMIT),
3211
+ ):
3212
+ absolute_path = safe_source_path(target, row["relative_path"]) if target else None
3213
+ location = {
3214
+ "endLine": row["end_line"],
3215
+ "path": bounded_output_text(row["relative_path"], FINDING_LOCATION_PATH_BYTES),
3216
+ "role": (
3217
+ bounded_output_text(row["role"], FINDING_LOCATION_ROLE_BYTES)
3218
+ if row["role"] is not None
3219
+ else None
3220
+ ),
3221
+ "startLine": row["start_line"],
3222
+ }
3223
+ if absolute_path is not None:
3224
+ location["absolutePath"] = bounded_output_text(
3225
+ absolute_path, FINDING_ABSOLUTE_PATH_BYTES
3226
+ )
3227
+ locations.append(location)
3228
+ result = {
3229
+ **details,
3230
+ "confidence": {
3231
+ **confidence,
3232
+ "level": bounded_output_text(occurrence["confidence"], FINDING_LEVEL_BYTES),
3233
+ },
3234
+ "createdAt": occurrence["created_at"],
3235
+ "findingId": occurrence["finding_id"],
3236
+ "locations": locations,
3237
+ "occurrenceId": occurrence["id"],
3238
+ "remediationState": finding_remediation_result(connection, occurrence["id"]),
3239
+ "remediation": bounded_output_text(occurrence["remediation"], FINDING_REMEDIATION_BYTES),
3240
+ "severity": {
3241
+ **severity,
3242
+ "level": bounded_output_text(occurrence["severity"], FINDING_LEVEL_BYTES),
3243
+ },
3244
+ "summary": bounded_output_text(occurrence["summary"], FINDING_SUMMARY_BYTES),
3245
+ "title": bounded_output_text(occurrence["title"], FINDING_TITLE_BYTES),
3246
+ "triage": finding_triage_result(connection, occurrence["id"]),
3247
+ }
3248
+ matches, known_since, known_scan_ids = scan_history.finding_matches(
3249
+ connection, occurrence["id"], scan["id"], scan["started_at"]
3250
+ )
3251
+ if matches:
3252
+ result["matches"] = matches
3253
+ result["knownSince"] = known_since
3254
+ result["knownScanIds"] = known_scan_ids
3255
+ result.pop("artifactPaths", None)
3256
+ source_excerpt = finding_source_excerpt(scan, target, locations)
3257
+ if source_excerpt:
3258
+ result["sourceExcerpt"] = source_excerpt
3259
+ artifact_paths = finding_artifact_paths(Path(scan["scan_dir"]), details)
3260
+ result["artifactPaths"] = artifact_paths
3261
+ return result
3262
+
3263
+
3264
+ def finding_artifact_paths(scan_dir: Path, details: dict[str, Any]) -> list[str]:
3265
+ writeup = details.get("writeup")
3266
+ if not isinstance(writeup, dict):
3267
+ return []
3268
+ report_path = writeup.get("reportPath")
3269
+ if (
3270
+ not isinstance(report_path, str)
3271
+ or FINDING_WRITEUP_REPORT_PATH.fullmatch(report_path) is None
3272
+ ):
3273
+ return []
3274
+ report_relative = PurePosixPath(report_path)
3275
+ artifacts = []
3276
+ if scan_local_regular_file(scan_dir, report_path):
3277
+ artifacts.append(report_path)
3278
+
3279
+ poc_relative = report_relative.parent / "poc"
3280
+ poc_root = scan_dir.joinpath(*poc_relative.parts)
3281
+ try:
3282
+ if not stat.S_ISDIR(poc_root.stat(follow_symlinks=False).st_mode):
3283
+ return artifacts
3284
+ except OSError:
3285
+ return artifacts
3286
+
3287
+ directories_seen = 0
3288
+ for current_directory, directory_names, file_names in os.walk(
3289
+ poc_root, topdown=True, followlinks=False
3290
+ ):
3291
+ directories_seen += 1
3292
+ if directories_seen > FINDING_ARTIFACT_DIRECTORIES_LIMIT:
3293
+ directory_names[:] = []
3294
+ break
3295
+ current_path = Path(current_directory)
3296
+ directory_names[:] = [
3297
+ name for name in sorted(directory_names) if not (current_path / name).is_symlink()
3298
+ ]
3299
+ for file_name in sorted(file_names):
3300
+ candidate = current_path / file_name
3301
+ try:
3302
+ relative_path = candidate.relative_to(scan_dir).as_posix()
3303
+ except ValueError:
3304
+ continue
3305
+ if not scan_local_regular_file(scan_dir, relative_path):
3306
+ continue
3307
+ artifacts.append(relative_path)
3308
+ if len(artifacts) >= FINDING_ARTIFACTS_LIMIT:
3309
+ return artifacts
3310
+ return artifacts
3311
+
3312
+
3313
+ def scan_local_regular_file(scan_dir: Path, relative_path: str) -> bool:
3314
+ if len(relative_path.encode("utf-8")) > FINDING_LOCATION_PATH_BYTES:
3315
+ return False
3316
+ try:
3317
+ descriptor = open_scan_local_file_descriptor(
3318
+ scan_dir,
3319
+ relative_path,
3320
+ f"finding artifact {relative_path}",
3321
+ )
3322
+ except (ContractError, OSError):
3323
+ return False
3324
+ try:
3325
+ return stat.S_ISREG(os.fstat(descriptor).st_mode)
3326
+ finally:
3327
+ os.close(descriptor)
3328
+
3329
+
3330
+ def read_finding_details(value: str) -> dict[str, Any]:
3331
+ try:
3332
+ details = json.loads(value, parse_constant=reject_non_finite_json)
3333
+ except (TypeError, ValueError):
3334
+ return {}
3335
+ return details if isinstance(details, dict) else {}
3336
+
3337
+
3338
+ def finding_management_updated_at(connection: sqlite3.Connection, scan_id: str) -> str | None:
3339
+ return connection.execute(
3340
+ """
3341
+ SELECT MAX(updated_at)
3342
+ FROM (
3343
+ SELECT triage.updated_at
3344
+ FROM finding_triage AS triage
3345
+ JOIN finding_occurrences AS occurrences ON occurrences.id = triage.occurrence_id
3346
+ WHERE occurrences.scan_id = ?
3347
+ UNION ALL
3348
+ SELECT remediation.updated_at
3349
+ FROM finding_remediation_attempts AS remediation
3350
+ JOIN finding_occurrences AS occurrences ON occurrences.id = remediation.occurrence_id
3351
+ WHERE occurrences.scan_id = ?
3352
+ )
3353
+ """,
3354
+ (scan_id, scan_id),
3355
+ ).fetchone()[0]
3356
+
3357
+
3358
+ def finding_triage_result(connection: sqlite3.Connection, occurrence_id: str) -> dict[str, Any]:
3359
+ row = connection.execute(
3360
+ "SELECT status, close_reason, note, updated_at FROM finding_triage WHERE occurrence_id = ?",
3361
+ (occurrence_id,),
3362
+ ).fetchone()
3363
+ if row is None:
3364
+ return {"status": "open"}
3365
+ return {
3366
+ "closeReason": row["close_reason"],
3367
+ "note": row["note"],
3368
+ "status": row["status"],
3369
+ "updatedAt": row["updated_at"],
3370
+ }
3371
+
3372
+
3373
+ def finding_remediation_result(
3374
+ connection: sqlite3.Connection, occurrence_id: str
3375
+ ) -> dict[str, Any]:
3376
+ row = connection.execute(
3377
+ """
3378
+ SELECT remediation.request_id, remediation.state, remediation.version,
3379
+ remediation.base_revision, remediation.base_content_digest,
3380
+ remediation.applied_content_digest, remediation.pending_action,
3381
+ remediation.pending_action_claimed_at, remediation.pending_action_claim_token,
3382
+ remediation.pending_action_delivered_at,
3383
+ remediation.patch_path, remediation.patch_digest, remediation.summary,
3384
+ remediation.verification_summary, remediation.updated_at, scans.scan_dir
3385
+ FROM finding_remediation_attempts AS remediation
3386
+ JOIN finding_occurrences AS occurrences ON occurrences.id = remediation.occurrence_id
3387
+ JOIN scans ON scans.id = occurrences.scan_id
3388
+ WHERE remediation.occurrence_id = ?
3389
+ ORDER BY remediation.created_at DESC, remediation.rowid DESC
3390
+ LIMIT 1
3391
+ """,
3392
+ (occurrence_id,),
3393
+ ).fetchone()
3394
+ if row is None:
3395
+ return {"state": "idle"}
3396
+ patch, patch_stats = patch_artifact_preview(
3397
+ Path(row["scan_dir"]), row["patch_path"], row["patch_digest"]
3398
+ )
3399
+ return {
3400
+ "baseRevision": row["base_revision"],
3401
+ "actionClaimedAt": row["pending_action_claimed_at"],
3402
+ "actionClaimToken": row["pending_action_claim_token"],
3403
+ "actionDeliveredAt": row["pending_action_delivered_at"],
3404
+ "pendingAction": row["pending_action"],
3405
+ "patchDigest": row["patch_digest"],
3406
+ "patchPath": row["patch_path"],
3407
+ "patch": patch,
3408
+ "patchStats": patch_stats,
3409
+ "requestId": row["request_id"],
3410
+ "state": row["state"],
3411
+ "summary": row["summary"],
3412
+ "updatedAt": row["updated_at"],
3413
+ "verificationSummary": row["verification_summary"],
3414
+ "version": row["version"],
3415
+ }
3416
+
3417
+
3418
+ def patch_artifact_preview(
3419
+ scan_dir: Path, relative_path: str | None, expected_digest: str | None
3420
+ ) -> tuple[str | None, dict[str, int | bool] | None]:
3421
+ if relative_path is None or expected_digest is None:
3422
+ return None, None
3423
+ digest = hashlib.sha256()
3424
+ preview = bytearray()
3425
+ additions = 0
3426
+ deletions = 0
3427
+ file_count = 0
3428
+ old_headers = 0
3429
+ new_headers = 0
3430
+ at_line_start = True
3431
+ try:
3432
+ with open_scan_local_file(scan_dir, relative_path) as patch:
3433
+ require_bounded_patch_artifact(patch)
3434
+ while chunk := patch.readline(1024 * 1024):
3435
+ digest.update(chunk)
3436
+ if len(preview) <= PATCH_PREVIEW_BYTES:
3437
+ preview.extend(chunk[: PATCH_PREVIEW_BYTES + 1 - len(preview)])
3438
+ if at_line_start:
3439
+ if chunk.startswith(b"diff --git "):
3440
+ file_count += 1
3441
+ elif chunk.startswith(b"+++ "):
3442
+ new_headers += 1
3443
+ elif chunk.startswith(b"--- "):
3444
+ old_headers += 1
3445
+ elif chunk.startswith(b"+"):
3446
+ additions += 1
3447
+ elif chunk.startswith(b"-"):
3448
+ deletions += 1
3449
+ at_line_start = chunk.endswith(b"\n")
3450
+ except SystemExit:
3451
+ return None, None
3452
+ if f"sha256:{digest.hexdigest()}" != expected_digest:
3453
+ return None, None
3454
+ preview_truncated = len(preview) > PATCH_PREVIEW_BYTES
3455
+ preview_text = preview[:PATCH_PREVIEW_BYTES].decode("utf-8", errors="replace")
3456
+ if preview_truncated:
3457
+ preview_text = f"{preview_text}\n... patch preview truncated ..."
3458
+ return preview_text, {
3459
+ "additions": additions,
3460
+ "deletions": deletions,
3461
+ "fileCount": file_count or min(old_headers, new_headers),
3462
+ "previewTruncated": preview_truncated,
3463
+ }
3464
+
3465
+
3466
+ def safe_source_path(target: Path, relative_path: str) -> Path | None:
3467
+ if "\\" in relative_path:
3468
+ return None
3469
+ parsed = PurePosixPath(relative_path)
3470
+ if parsed.is_absolute() or ".." in parsed.parts:
3471
+ return None
3472
+ try:
3473
+ path = (target / parsed.as_posix()).resolve()
3474
+ path.relative_to(target)
3475
+ except (OSError, RuntimeError, ValueError):
3476
+ return None
3477
+ return path
3478
+
3479
+
3480
+ def available_artifact_path(scan_dir: Path, candidate: Path) -> Path | None:
3481
+ try:
3482
+ resolved_scan_dir = require_canonical_scan_directory(scan_dir)
3483
+ resolved = candidate.resolve(strict=True)
3484
+ resolved.relative_to(resolved_scan_dir)
3485
+ except (FileNotFoundError, RuntimeError, SystemExit, ValueError):
3486
+ return None
3487
+ if resolved != candidate or not candidate.is_file():
3488
+ return None
3489
+ return resolved
3490
+
3491
+
3492
+ def artifact_path(scan_dir: Path, file_name: str, *, required: bool) -> Path | None:
3493
+ scan_dir = require_canonical_scan_directory(scan_dir)
3494
+ candidate = scan_dir / file_name
3495
+ try:
3496
+ resolved = candidate.resolve(strict=True)
3497
+ resolved.relative_to(scan_dir.resolve())
3498
+ except (FileNotFoundError, RuntimeError, ValueError) as exc:
3499
+ if not required and isinstance(exc, FileNotFoundError):
3500
+ return None
3501
+ raise SystemExit(
3502
+ f"{file_name}: expected a regular file inside the scan directory."
3503
+ ) from exc
3504
+ if resolved != candidate or not candidate.is_file():
3505
+ raise SystemExit(f"{file_name}: expected a regular non-symlink file.")
3506
+ return resolved
3507
+
3508
+
3509
+ def require_canonical_scan_directory(scan_dir: Path) -> Path:
3510
+ scan_dir = scan_dir.absolute()
3511
+ try:
3512
+ metadata = scan_dir.lstat()
3513
+ resolved = scan_dir.resolve(strict=True)
3514
+ except OSError as exc:
3515
+ raise SystemExit(
3516
+ "Scan directory must be an existing canonical non-symlink directory."
3517
+ ) from exc
3518
+ if not stat.S_ISDIR(metadata.st_mode) or resolved != scan_dir:
3519
+ raise SystemExit("Scan directory must be an existing canonical non-symlink directory.")
3520
+ return scan_dir
3521
+
3522
+
3523
+ def read_json_object(path: Path) -> dict[str, Any]:
3524
+ try:
3525
+ payload = json.loads(
3526
+ path.read_text(encoding="utf-8"),
3527
+ parse_constant=reject_non_finite_json,
3528
+ )
3529
+ except (OSError, ValueError) as exc:
3530
+ raise SystemExit(f"{path.name}: invalid JSON: {exc}") from exc
3531
+ if not isinstance(payload, dict):
3532
+ raise SystemExit(f"{path.name}: expected a JSON object.")
3533
+ return payload
3534
+
3535
+
3536
+ def reject_non_finite_json(value: str) -> None:
3537
+ raise ValueError(f"non-finite JSON number {value!r} is not supported")
3538
+
3539
+
3540
+ def main() -> None:
3541
+ args = parse_args(__doc__)
3542
+ deep_scan.configure(
3543
+ deep_scan.DeepScanDependencies(
3544
+ now=now,
3545
+ state_dir=state_dir,
3546
+ require_scan=require_scan,
3547
+ require_workspace=require_workspace,
3548
+ require_target=require_target,
3549
+ require_remediation_target=require_remediation_target,
3550
+ require_scannable_target=require_scannable_target,
3551
+ require_scope=require_scope,
3552
+ ensure_security_target=ensure_security_target,
3553
+ require_canonical_scan_directory=require_canonical_scan_directory,
3554
+ safe_segment=safe_segment,
3555
+ compact_timestamp=compact_timestamp,
3556
+ )
3557
+ )
3558
+ if args.command == "inspect-target":
3559
+ result = inspect_target(args.target_path)
3560
+ print(json.dumps(result, allow_nan=False, sort_keys=True))
3561
+ return
3562
+ if args.command == "inspect-setup":
3563
+ result = inspect_setup(args)
3564
+ print(json.dumps(result, allow_nan=False, sort_keys=True))
3565
+ return
3566
+ with closing(connect()) as connection:
3567
+ if args.command == "get-setup-preference":
3568
+ result = setup_preference(connection)
3569
+ elif args.command == "disable-setup-ui":
3570
+ result = disable_setup_ui(connection, args)
3571
+ elif args.command == "create-workspace":
3572
+ result = create_workspace(connection, args)
3573
+ elif args.command == "get-workspace":
3574
+ result = workspace_state(connection, args.workspace_id, thread_id=args.thread_id)
3575
+ elif args.command == "get-latest-workspace":
3576
+ result = latest_workspace(connection, args.thread_id)
3577
+ elif args.command == "list-workspace-scans":
3578
+ result = scan_history.list_workspace_scans(
3579
+ connection, args, require_workspace=require_workspace
3580
+ )
3581
+ elif args.command == "begin-diff-resolution":
3582
+ result = begin_diff_resolution(connection, args)
3583
+ elif args.command == "cancel-diff-resolution":
3584
+ result = cancel_diff_resolution(connection, args)
3585
+ elif args.command == "set-diff-target":
3586
+ result = set_diff_target(connection, args)
3587
+ elif args.command == "save-workspace":
3588
+ result = save_workspace(connection, args)
3589
+ elif args.command == "set-capability-preflight":
3590
+ result = set_capability_preflight(connection, args)
3591
+ elif args.command == "start-scan":
3592
+ result = start_scan(connection, args)
3593
+ elif args.command == "start-prompt-only-scan":
3594
+ result = start_prompt_only_scan(connection, args)
3595
+ elif args.command == "begin-deep-scan":
3596
+ result = deep_scan.begin_deep_scan(connection, args)
3597
+ elif args.command == "get-deep-scan":
3598
+ result = deep_scan.get_deep_scan(connection, args)
3599
+ elif args.command == "upsert-deep-scan-worker":
3600
+ result = deep_scan.upsert_deep_scan_worker(connection, args)
3601
+ elif args.command == "claim-deep-scan-dedup":
3602
+ result = deep_scan.claim_deep_scan_dedup(connection, args)
3603
+ elif args.command == "commit-deep-scan-dedup":
3604
+ result = deep_scan.commit_deep_scan_dedup(connection, args)
3605
+ elif args.command == "finish-deep-scan":
3606
+ result = deep_scan.finish_deep_scan(connection, args)
3607
+ elif args.command == "fail-deep-scan":
3608
+ result = deep_scan.fail_deep_scan(connection, args)
3609
+ elif args.command == "get-scan":
3610
+ result = scan_context(connection, args.scan_id, args.occurrence_id)
3611
+ elif args.command == "list-scans":
3612
+ result = scan_history.list_scans(connection, args)
3613
+ elif args.command == "list-unmatched-scan-pairs":
3614
+ result = scan_history.list_unmatched_scan_pairs(
3615
+ connection,
3616
+ args,
3617
+ backfill_finding_details=backfill_legacy_finding_details,
3618
+ read_coverage=coverage_for_comparison,
3619
+ )
3620
+ elif args.command == "register-cli-scan":
3621
+ result = register_cli_scan(connection, args)
3622
+ elif args.command == "get-scan-recipe":
3623
+ result = get_scan_recipe(connection, args)
3624
+ elif args.command == "compare-scans":
3625
+ result = scan_history.compare_scans(
3626
+ connection,
3627
+ args,
3628
+ require_scan=require_scan,
3629
+ read_coverage=coverage_for_comparison,
3630
+ backfill_finding_details=backfill_legacy_finding_details,
3631
+ include_matching_inputs=args.include_matching_inputs,
3632
+ require_matches=args.require_matches,
3633
+ )
3634
+ elif args.command == "save-scan-comparison":
3635
+ result = scan_history.save_scan_comparison(
3636
+ connection,
3637
+ args,
3638
+ now=now,
3639
+ require_scan=require_scan,
3640
+ read_coverage=coverage_for_comparison,
3641
+ )
3642
+ elif args.command == "list-global-findings":
3643
+ result = native_indexes.list_global_findings(
3644
+ connection, args, read_coverage=coverage_for_comparison
3645
+ )
3646
+ elif args.command == "list-repositories":
3647
+ result = native_indexes.list_repositories(
3648
+ connection, args, read_coverage=coverage_for_comparison
3649
+ )
3650
+ elif args.command == "list-findings":
3651
+ result = list_findings(connection, args)
3652
+ elif args.command == "update-progress":
3653
+ result = progress.update_progress(
3654
+ connection,
3655
+ args,
3656
+ now=now,
3657
+ require_scan=require_scan,
3658
+ scan_context=scan_context,
3659
+ )
3660
+ elif args.command == "complete-scan":
3661
+ result = complete_scan(connection, args)
3662
+ elif args.command == "cancel-scan":
3663
+ result = cancel_scan(connection, args)
3664
+ elif args.command == "fail-scan":
3665
+ result = fail_scan(connection, args)
3666
+ elif args.command == "mark-handoff-delivered":
3667
+ result = handoff.mark_handoff_delivered(
3668
+ connection,
3669
+ args,
3670
+ now=now,
3671
+ require_scan=require_scan,
3672
+ require_workspace=require_workspace,
3673
+ workspace_state=workspace_state,
3674
+ )
3675
+ elif args.command == "claim-handoff-delivery":
3676
+ result = handoff.claim_handoff_delivery(
3677
+ connection,
3678
+ args,
3679
+ now=now,
3680
+ require_scan=require_scan,
3681
+ stale_claim_before=stale_claim_before,
3682
+ workspace_state=workspace_state,
3683
+ )
3684
+ elif args.command == "release-handoff-delivery":
3685
+ result = handoff.release_handoff_delivery(
3686
+ connection,
3687
+ args,
3688
+ now=now,
3689
+ require_scan=require_scan,
3690
+ workspace_state=workspace_state,
3691
+ )
3692
+ elif args.command == "attach-scan-continuation-thread":
3693
+ result = handoff.attach_scan_continuation_thread(
3694
+ connection,
3695
+ args,
3696
+ now=now,
3697
+ require_scan=require_scan,
3698
+ workspace_state=workspace_state,
3699
+ )
3700
+ elif args.command == "set-finding-triage":
3701
+ result = set_finding_triage(connection, args)
3702
+ elif args.command == "request-finding-remediation":
3703
+ result = request_finding_remediation(connection, args)
3704
+ elif args.command == "request-finding-remediation-action":
3705
+ result = request_finding_remediation_action(connection, args)
3706
+ elif args.command == "claim-finding-remediation-resend":
3707
+ result = claim_finding_remediation_resend(connection, args)
3708
+ elif args.command == "mark-finding-remediation-delivered":
3709
+ result = mark_finding_remediation_delivered(connection, args)
3710
+ elif args.command == "release-finding-remediation-claim":
3711
+ result = release_finding_remediation_claim(connection, args)
3712
+ elif args.command == "cancel-finding-remediation-request":
3713
+ result = scan_context(
3714
+ connection, remediation.cancel_finding_remediation_request(connection, args)
3715
+ )
3716
+ elif args.command == "set-finding-remediation":
3717
+ result = set_finding_remediation(connection, args)
3718
+ elif args.command == "export-findings":
3719
+ result = export_findings(connection, args)
3720
+ elif args.command == "database-info":
3721
+ result = {"databasePath": str(database_path())}
3722
+ else:
3723
+ raise SystemExit(f"Unknown command: {args.command}")
3724
+ print(json.dumps(result, allow_nan=False, sort_keys=True))
3725
+
3726
+
3727
+ if __name__ == "__main__":
3728
+ main()