@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,829 @@
1
+ """Scan history projection for the native Codex Security workbench."""
2
+
3
+ import argparse
4
+ import fnmatch
5
+ import json
6
+ import os
7
+ import sqlite3
8
+ from pathlib import Path, PurePosixPath
9
+ from typing import Any, Callable
10
+ from urllib.parse import urlsplit
11
+
12
+ from report_projection import SEVERITY_ORDER
13
+ from workbench_constants import FINDINGS_PAGE_MAX
14
+ from workbench_target import git_output
15
+
16
+
17
+ def _same_repository(
18
+ before: sqlite3.Row,
19
+ after: sqlite3.Row,
20
+ *,
21
+ after_identity: tuple[str | None, tuple[str, str] | None] | None = None,
22
+ ) -> bool:
23
+ if before["target_id"] == after["target_id"]:
24
+ return True
25
+ before_target = Path(before["target_path"])
26
+ after_target = Path(after["target_path"])
27
+ before_git_dir = git_output(
28
+ before_target, "rev-parse", "--path-format=absolute", "--git-common-dir"
29
+ )
30
+ after_git_dir = (
31
+ git_output(after_target, "rev-parse", "--path-format=absolute", "--git-common-dir")
32
+ if after_identity is None
33
+ else after_identity[0]
34
+ )
35
+ if (
36
+ before_git_dir is not None
37
+ and after_git_dir is not None
38
+ and Path(before_git_dir).resolve() == Path(after_git_dir).resolve()
39
+ ):
40
+ return True
41
+ before_origin = _repository_origin(before_target)
42
+ return before_origin is not None and before_origin == (
43
+ _repository_origin(after_target) if after_identity is None else after_identity[1]
44
+ )
45
+
46
+
47
+ def _repository_origin(target: Path) -> tuple[str, str] | None:
48
+ remote = git_output(target, "remote", "get-url", "origin")
49
+ if remote is None:
50
+ return None
51
+ if "://" in remote:
52
+ try:
53
+ parsed = urlsplit(remote)
54
+ port = parsed.port
55
+ except ValueError:
56
+ return None
57
+ if parsed.scheme not in {"https", "ssh"} or parsed.hostname is None:
58
+ return None
59
+ if parsed.query or parsed.fragment:
60
+ return None
61
+ host = parsed.hostname
62
+ if port is not None and port != {"https": 443, "ssh": 22}[parsed.scheme]:
63
+ host = f"{host}:{port}"
64
+ path = parsed.path
65
+ else:
66
+ authority, separator, path = remote.partition(":")
67
+ if not separator or "?" in path or "#" in path:
68
+ return None
69
+ host = authority.rsplit("@", 1)[-1]
70
+ path = path.strip("/").removesuffix(".git")
71
+ return (host.lower(), path) if host and path else None
72
+
73
+
74
+ def list_workspace_scans(
75
+ connection: sqlite3.Connection,
76
+ args: argparse.Namespace,
77
+ *,
78
+ require_workspace: Callable[[sqlite3.Connection, str], sqlite3.Row],
79
+ ) -> dict[str, Any]:
80
+ workspace = require_workspace(connection, args.workspace_id)
81
+ total = connection.execute(
82
+ "SELECT COUNT(*) FROM scans WHERE workspace_id = ?", (workspace["id"],)
83
+ ).fetchone()[0]
84
+ rows = connection.execute(
85
+ """
86
+ SELECT id, mode, status, phase, scope, target_revision,
87
+ seal_manifest_digest, started_at, completed_at, canceled_at,
88
+ updated_at, failure_message
89
+ FROM scans
90
+ WHERE workspace_id = ?
91
+ ORDER BY created_at DESC, id DESC
92
+ LIMIT ? OFFSET ?
93
+ """,
94
+ (workspace["id"], args.limit, args.offset),
95
+ ).fetchall()
96
+ next_offset = args.offset + len(rows)
97
+ return {
98
+ "limit": args.limit,
99
+ "nextOffset": next_offset if next_offset < total else None,
100
+ "offset": args.offset,
101
+ "scans": [
102
+ {
103
+ "canceledAt": row["canceled_at"],
104
+ "completedAt": row["completed_at"],
105
+ "failureMessage": row["failure_message"],
106
+ "mode": row["mode"],
107
+ "phase": row["phase"],
108
+ "scanId": row["id"],
109
+ "scope": row["scope"],
110
+ "sealed": row["seal_manifest_digest"] is not None,
111
+ "startedAt": row["started_at"],
112
+ "status": "canceled" if row["canceled_at"] else row["status"],
113
+ "targetRevision": row["target_revision"],
114
+ "updatedAt": row["updated_at"],
115
+ }
116
+ for row in rows
117
+ ],
118
+ "total": total,
119
+ "workspaceId": workspace["id"],
120
+ }
121
+
122
+
123
+ def list_scans(
124
+ connection: sqlite3.Connection, args: argparse.Namespace | None = None
125
+ ) -> dict[str, Any]:
126
+ clauses: list[str] = []
127
+ values: list[Any] = []
128
+ if args is not None and args.repository:
129
+ repository = Path(args.repository).expanduser().resolve()
130
+ requested_repository = connection.execute(
131
+ """
132
+ SELECT COALESCE((SELECT id FROM security_targets WHERE current_path = ?), '') AS target_id,
133
+ ? AS target_path
134
+ """,
135
+ (str(repository), str(repository)),
136
+ ).fetchone()
137
+ requested_identity = (
138
+ git_output(repository, "rev-parse", "--path-format=absolute", "--git-common-dir"),
139
+ _repository_origin(repository),
140
+ )
141
+ related_target_ids = [
142
+ target["target_id"]
143
+ for target in connection.execute(
144
+ "SELECT id AS target_id, current_path AS target_path FROM security_targets"
145
+ )
146
+ if _same_repository(target, requested_repository, after_identity=requested_identity)
147
+ ]
148
+ repository_clauses = ["scans.target_path = ?"]
149
+ values.append(str(repository))
150
+ if related_target_ids:
151
+ placeholders = ", ".join("?" for _ in related_target_ids)
152
+ repository_clauses.append(f"scans.target_id IN ({placeholders})")
153
+ values.extend(related_target_ids)
154
+ clauses.append(f"({' OR '.join(repository_clauses)})")
155
+ if args is not None and args.scan_root:
156
+ scan_root = str(Path(args.scan_root).expanduser().resolve())
157
+ prefix = scan_root.rstrip(os.sep) + os.sep
158
+ clauses.append("(scans.scan_dir = ? OR substr(scans.scan_dir, 1, ?) = ?)")
159
+ values.extend((scan_root, len(prefix), prefix))
160
+ if args is not None and args.target_id:
161
+ clauses.append("scans.target_id = ?")
162
+ values.append(args.target_id)
163
+ if args is not None and args.mode:
164
+ clauses.append("scans.mode = ?")
165
+ values.append(args.mode)
166
+ if args is not None and args.status:
167
+ if args.status == "canceled":
168
+ clauses.append("scans.canceled_at IS NOT NULL")
169
+ else:
170
+ clauses.append("scans.status = ? AND scans.canceled_at IS NULL")
171
+ values.append(args.status)
172
+ if args is not None and args.query:
173
+ query = args.query.strip().casefold()
174
+ if query:
175
+ clauses.append(
176
+ "(instr(lower(scans.target_path), ?) > 0 "
177
+ "OR instr(lower(COALESCE(scans.target_summary, '')), ?) > 0 "
178
+ "OR instr(lower(scans.scope), ?) > 0 "
179
+ "OR instr(lower(scans.mode), ?) > 0)"
180
+ )
181
+ values.extend((query, query, query, query))
182
+ where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
183
+ paginated = args is not None and (args.limit is not None or args.offset != 0)
184
+ limit = min(args.limit or FINDINGS_PAGE_MAX, FINDINGS_PAGE_MAX) if paginated else None
185
+ pagination = "LIMIT ? OFFSET ?" if paginated else ""
186
+ if limit is not None:
187
+ values.extend((limit + 1, args.offset))
188
+ rows = connection.execute(
189
+ f"""
190
+ SELECT
191
+ scans.*,
192
+ progress.reportable_findings_count,
193
+ progress.scope_file_count,
194
+ progress.review_items_completed,
195
+ progress.review_items_total,
196
+ progress.updated_at AS progress_updated_at,
197
+ (
198
+ SELECT COUNT(*)
199
+ FROM finding_occurrences AS occurrences
200
+ WHERE occurrences.scan_id = scans.id
201
+ ) AS finding_count
202
+ FROM scans
203
+ JOIN scan_progress AS progress ON progress.scan_id = scans.id
204
+ {where}
205
+ ORDER BY
206
+ CASE WHEN scans.status = 'running' AND scans.canceled_at IS NULL THEN 0 ELSE 1 END,
207
+ MAX(scans.updated_at, progress.updated_at) DESC,
208
+ scans.started_at DESC,
209
+ scans.id
210
+ {pagination}
211
+ """,
212
+ values,
213
+ ).fetchall()
214
+ result = {
215
+ "scans": [
216
+ {
217
+ "completedAt": row["completed_at"],
218
+ "continuationThreadId": row["continuation_thread_id"],
219
+ **({"cost": json.loads(row["cost_json"])} if row["cost_json"] else {}),
220
+ "findingCount": row["finding_count"],
221
+ "handoffStatus": row["handoff_status"],
222
+ "mode": row["mode"],
223
+ "parentScanId": row["parent_scan_id"],
224
+ "progress": {
225
+ "candidates": {"reportable": row["reportable_findings_count"]},
226
+ "coverage": {
227
+ "closedRows": row["review_items_completed"],
228
+ "filesTotal": row["scope_file_count"],
229
+ "worklistRows": row["review_items_total"],
230
+ },
231
+ "phase": row["phase"],
232
+ "status": "canceled" if row["canceled_at"] else row["status"],
233
+ "updatedAt": row["progress_updated_at"],
234
+ },
235
+ "recipeAvailable": row["recipe_json"] is not None,
236
+ "scanDir": row["scan_dir"],
237
+ "scanId": row["id"],
238
+ "scope": row["scope"],
239
+ "startedAt": row["started_at"],
240
+ "targetId": row["target_id"],
241
+ "targetPath": row["target_path"],
242
+ "targetRevision": row["target_revision"],
243
+ "targetSummary": row["target_summary"],
244
+ "updatedAt": max(row["updated_at"], row["progress_updated_at"]),
245
+ }
246
+ for row in rows[:limit]
247
+ ]
248
+ }
249
+ if limit is not None:
250
+ result.update(
251
+ {
252
+ "limit": limit,
253
+ "nextOffset": args.offset + limit if len(rows) > limit else None,
254
+ "offset": args.offset,
255
+ }
256
+ )
257
+ return result
258
+
259
+
260
+ def list_unmatched_scan_pairs(
261
+ connection: sqlite3.Connection,
262
+ args: argparse.Namespace,
263
+ *,
264
+ backfill_finding_details: Callable[[sqlite3.Connection, sqlite3.Row], None],
265
+ read_coverage: Callable[[sqlite3.Row], dict[str, Any]],
266
+ ) -> dict[str, Any]:
267
+ repository = Path(args.repository).expanduser().resolve()
268
+ requested = connection.execute(
269
+ """
270
+ SELECT COALESCE((SELECT id FROM security_targets WHERE current_path = ?), '') AS target_id,
271
+ ? AS target_path
272
+ """,
273
+ (str(repository), str(repository)),
274
+ ).fetchone()
275
+ selected = [
276
+ scan
277
+ for scan in connection.execute(
278
+ "SELECT * FROM scans WHERE status = 'complete' ORDER BY started_at, id"
279
+ )
280
+ if Path(scan["target_path"]).resolve() == repository or _same_repository(scan, requested)
281
+ ]
282
+
283
+ available = []
284
+ for scan in selected:
285
+ try:
286
+ read_coverage(scan)
287
+ except SystemExit:
288
+ continue
289
+ available.append(scan)
290
+
291
+ saved_pairs = {
292
+ (row["before_scan_id"], row["after_scan_id"])
293
+ for row in connection.execute("SELECT before_scan_id, after_scan_id FROM scan_comparisons")
294
+ }
295
+ batches = []
296
+ skipped = 0
297
+ backfilled: set[str] = set()
298
+ for index, after in enumerate(available):
299
+ previous = [
300
+ before
301
+ for before in available[:index]
302
+ if args.force or (before["id"], after["id"]) not in saved_pairs
303
+ ]
304
+ skipped += index - len(previous)
305
+ if not previous:
306
+ continue
307
+ for scan in (*previous, after):
308
+ if scan["id"] not in backfilled:
309
+ backfill_finding_details(connection, scan)
310
+ backfilled.add(scan["id"])
311
+ batches.append(
312
+ {
313
+ "afterFindings": [
314
+ _matching_input(row) for row in _scan_findings(connection, after["id"]).values()
315
+ ],
316
+ "afterScanId": after["id"],
317
+ "beforeScans": [
318
+ {
319
+ "findings": [
320
+ _matching_input(row)
321
+ for row in _scan_findings(connection, before["id"]).values()
322
+ ],
323
+ "scanId": before["id"],
324
+ }
325
+ for before in previous
326
+ ],
327
+ }
328
+ )
329
+ return {
330
+ "batches": batches,
331
+ "repository": str(repository),
332
+ "scanCount": len(selected),
333
+ "skippedPairs": skipped,
334
+ "unavailableScans": len(selected) - len(available),
335
+ }
336
+
337
+
338
+ def compare_scans(
339
+ connection: sqlite3.Connection,
340
+ args: argparse.Namespace,
341
+ *,
342
+ require_scan: Callable[[sqlite3.Connection, str], sqlite3.Row],
343
+ read_coverage: Callable[[sqlite3.Row], dict[str, Any]],
344
+ backfill_finding_details: Callable[[sqlite3.Connection, sqlite3.Row], None] | None = None,
345
+ include_matching_inputs: bool = False,
346
+ require_matches: bool = False,
347
+ ) -> dict[str, Any]:
348
+ before = require_scan(connection, args.before_scan_id)
349
+ after = require_scan(connection, args.after_scan_id)
350
+ if before["id"] == after["id"]:
351
+ raise SystemExit("Select two different scans to compare.")
352
+ if before["status"] != "complete" or after["status"] != "complete":
353
+ raise SystemExit("Only completed scans can be compared.")
354
+ if not _same_repository(before, after):
355
+ raise SystemExit("Semantic scan comparisons require the same repository target.")
356
+ cached = connection.execute(
357
+ "SELECT result_json FROM scan_comparisons WHERE before_scan_id = ? AND after_scan_id = ?",
358
+ (before["id"], after["id"]),
359
+ ).fetchone()
360
+ if cached is None and require_matches:
361
+ reversed_comparison = connection.execute(
362
+ "SELECT 1 FROM scan_comparisons WHERE before_scan_id = ? AND after_scan_id = ?",
363
+ (after["id"], before["id"]),
364
+ ).fetchone()
365
+ if reversed_comparison is not None:
366
+ raise SystemExit(
367
+ "These scans are in the wrong order. Run "
368
+ f"'codex-security scans compare {after['id']} {before['id']}'."
369
+ )
370
+ raise SystemExit(
371
+ "No saved matches for these scans. Run 'codex-security scans match BEFORE AFTER' first."
372
+ )
373
+ if include_matching_inputs and backfill_finding_details is not None:
374
+ backfill_finding_details(connection, before)
375
+ backfill_finding_details(connection, after)
376
+ after_coverage = read_coverage(after)
377
+ comparable = after_coverage.get("completeness") == "complete"
378
+ before_findings = _scan_findings(connection, before["id"])
379
+ after_findings = _scan_findings(connection, after["id"])
380
+ matches = json.loads(cached["result_json"]) if cached is not None else None
381
+ groups = _finding_groups(before_findings, after_findings, matches)
382
+ uncertain = (
383
+ {
384
+ (side, match[f"{side}OccurrenceId"]): match["reason"]
385
+ for match in matches.get("uncertain", [])
386
+ for side in ("before", "after")
387
+ }
388
+ if matches is not None
389
+ else {}
390
+ )
391
+ findings: list[dict[str, Any]] = []
392
+ summary = {status: 0 for status in ("new", "persisting", "resolved", "reopened", "unknown")}
393
+
394
+ for previous_rows, current_rows, match_reason in groups:
395
+ previous = previous_rows[0] if previous_rows else None
396
+ current = (
397
+ min(current_rows, key=lambda row: SEVERITY_ORDER[row["severity"]])
398
+ if current_rows
399
+ else None
400
+ )
401
+ selected = current if current is not None else previous
402
+ if selected is None:
403
+ continue
404
+ item = {
405
+ "findingId": selected["finding_id"],
406
+ "path": selected["relative_path"],
407
+ "severity": selected["severity"],
408
+ "title": selected["title"],
409
+ }
410
+ if previous is None:
411
+ uncertain_reason = uncertain.get(("after", current["id"])) if current else None
412
+ if uncertain_reason is None:
413
+ status = "new"
414
+ else:
415
+ status = "unknown"
416
+ item["reason"] = uncertain_reason
417
+ elif current is not None:
418
+ status = (
419
+ "reopened"
420
+ if any(
421
+ row["triage_status"] == "closed" and row["close_reason"] == "already_fixed"
422
+ for row in previous_rows
423
+ )
424
+ and any(row["triage_status"] == "open" for row in current_rows)
425
+ else "persisting"
426
+ )
427
+ if match_reason is not None:
428
+ item["matchReason"] = match_reason
429
+ elif (uncertain_reason := uncertain.get(("before", previous["id"]))) is not None:
430
+ status = "unknown"
431
+ item["reason"] = uncertain_reason
432
+ elif not comparable:
433
+ status = "unknown"
434
+ item["reason"] = "The later scan has incomplete coverage."
435
+ elif not scan_covers_path(
436
+ after,
437
+ target_id=after["target_id"],
438
+ path=previous["relative_path"],
439
+ coverage=after_coverage,
440
+ ):
441
+ status = "unknown"
442
+ item["reason"] = "The affected path was excluded or outside the later scope."
443
+ else:
444
+ status = "resolved"
445
+ if len(previous_rows) == 1:
446
+ item["beforeOccurrenceId"] = previous["id"]
447
+ elif previous_rows:
448
+ item["beforeOccurrenceIds"] = [row["id"] for row in previous_rows]
449
+ if len(current_rows) == 1:
450
+ item["afterOccurrenceId"] = current["id"]
451
+ elif current_rows:
452
+ item["afterOccurrenceIds"] = [row["id"] for row in current_rows]
453
+ if current is not None:
454
+ item["triage"] = {
455
+ "closeReason": current["close_reason"],
456
+ "status": current["triage_status"],
457
+ }
458
+ item["status"] = status
459
+ findings.append(item)
460
+ summary[status] += 1
461
+
462
+ result = {
463
+ "afterScanId": after["id"],
464
+ "beforeScanId": before["id"],
465
+ "comparable": comparable,
466
+ "coverage": {"afterCompleteness": after_coverage.get("completeness")},
467
+ "findings": findings,
468
+ "repository": before["target_path"],
469
+ "summary": summary,
470
+ }
471
+ if include_matching_inputs:
472
+ result["matchingCached"] = cached is not None
473
+ result["matchingInputs"] = {
474
+ "before": [_matching_input(row) for row in before_findings.values()],
475
+ "after": [_matching_input(row) for row in after_findings.values()],
476
+ }
477
+ return result
478
+
479
+
480
+ def save_scan_comparison(
481
+ connection: sqlite3.Connection,
482
+ args: argparse.Namespace,
483
+ *,
484
+ now: Callable[[], str],
485
+ require_scan: Callable[[sqlite3.Connection, str], sqlite3.Row],
486
+ read_coverage: Callable[[sqlite3.Row], dict[str, Any]],
487
+ ) -> dict[str, Any]:
488
+ before = require_scan(connection, args.before_scan_id)
489
+ after = require_scan(connection, args.after_scan_id)
490
+ if before["id"] == after["id"]:
491
+ raise SystemExit("Select two different scans to compare.")
492
+ if before["status"] != "complete" or after["status"] != "complete":
493
+ raise SystemExit("Only completed scans can be compared.")
494
+ if not _same_repository(before, after):
495
+ raise SystemExit("Semantic scan comparisons require the same repository target.")
496
+ read_coverage(after)
497
+ before_findings = _scan_findings(connection, before["id"])
498
+ after_findings = _scan_findings(connection, after["id"])
499
+ try:
500
+ payload = json.loads(args.matches_json)
501
+ except (TypeError, ValueError) as exc:
502
+ raise SystemExit("Scan comparison matches must be a valid JSON object.") from exc
503
+ if not isinstance(payload, dict) or set(payload) != {"matches", "uncertain"}:
504
+ raise SystemExit("Scan comparison matches must contain matches and uncertain arrays.")
505
+ if not isinstance(payload["matches"], list) or not isinstance(payload["uncertain"], list):
506
+ raise SystemExit("Scan comparison matches must contain matches and uncertain arrays.")
507
+ allowed = {
508
+ "before": {row["id"] for row in before_findings.values()},
509
+ "after": {row["id"] for row in after_findings.values()},
510
+ }
511
+ consumed: dict[str, set[str]] = {"before": set(), "after": set()}
512
+ for match in payload["matches"]:
513
+ for side in ("before", "after"):
514
+ occurrences = match[f"{side}OccurrenceIds"]
515
+ unique = set(occurrences)
516
+ if (
517
+ not occurrences
518
+ or len(unique) != len(occurrences)
519
+ or not unique.issubset(allowed[side])
520
+ or not consumed[side].isdisjoint(unique)
521
+ ):
522
+ raise SystemExit("Scan comparison matches must identify distinct scan findings.")
523
+ consumed[side].update(unique)
524
+ uncertain_pairs = set()
525
+ for match in payload["uncertain"]:
526
+ pair = (match["beforeOccurrenceId"], match["afterOccurrenceId"])
527
+ if (
528
+ pair[0] not in allowed["before"] - consumed["before"]
529
+ or pair[1] not in allowed["after"] - consumed["after"]
530
+ or pair in uncertain_pairs
531
+ ):
532
+ raise SystemExit("Uncertain scan comparison matches must identify distinct findings.")
533
+ uncertain_pairs.add(pair)
534
+ timestamp = now()
535
+ with connection:
536
+ connection.execute("BEGIN IMMEDIATE")
537
+ connection.execute(
538
+ "DELETE FROM scan_comparisons WHERE before_scan_id = ? AND after_scan_id = ?",
539
+ (before["id"], after["id"]),
540
+ )
541
+ connection.execute(
542
+ """
543
+ INSERT INTO scan_comparisons (
544
+ before_scan_id, after_scan_id, result_json, created_at, updated_at
545
+ ) VALUES (?, ?, ?, ?, ?)
546
+ """,
547
+ (
548
+ before["id"],
549
+ after["id"],
550
+ json.dumps(payload, allow_nan=False, sort_keys=True),
551
+ timestamp,
552
+ timestamp,
553
+ ),
554
+ )
555
+ connection.executemany(
556
+ """
557
+ INSERT INTO scan_comparison_matches (
558
+ before_scan_id, after_scan_id, before_occurrence_id, after_occurrence_id, reason
559
+ ) VALUES (?, ?, ?, ?, ?)
560
+ """,
561
+ (
562
+ (before["id"], after["id"], previous, current, match["reason"])
563
+ for match in payload["matches"]
564
+ for previous in match["beforeOccurrenceIds"]
565
+ for current in match["afterOccurrenceIds"]
566
+ ),
567
+ )
568
+ return compare_scans(connection, args, require_scan=require_scan, read_coverage=read_coverage)
569
+
570
+
571
+ def finding_matches(
572
+ connection: sqlite3.Connection, occurrence_id: str, scan_id: str, started_at: str
573
+ ) -> tuple[list[dict[str, Any]], str, list[str]]:
574
+ rows = connection.execute(
575
+ """
576
+ SELECT matches.after_scan_id AS scan_id, occurrences.id AS occurrence_id, occurrences.finding_id,
577
+ occurrences.title, matches.reason
578
+ FROM scan_comparison_matches AS matches
579
+ JOIN finding_occurrences AS occurrences ON occurrences.id = matches.after_occurrence_id
580
+ WHERE matches.before_occurrence_id = ?
581
+ UNION
582
+ SELECT matches.before_scan_id AS scan_id, occurrences.id AS occurrence_id, occurrences.finding_id,
583
+ occurrences.title, matches.reason
584
+ FROM scan_comparison_matches AS matches
585
+ JOIN finding_occurrences AS occurrences ON occurrences.id = matches.before_occurrence_id
586
+ WHERE matches.after_occurrence_id = ?
587
+ ORDER BY scan_id, occurrence_id
588
+ """,
589
+ (occurrence_id, occurrence_id),
590
+ ).fetchall()
591
+ known_scans = [(started_at, scan_id)]
592
+ if rows:
593
+ known_scans = [
594
+ (row["started_at"], row["scan_id"])
595
+ for row in connection.execute(
596
+ """
597
+ WITH RECURSIVE linked_occurrences(occurrence_id) AS (
598
+ SELECT ?
599
+ UNION
600
+ SELECT CASE
601
+ WHEN matches.before_occurrence_id = linked.occurrence_id
602
+ THEN matches.after_occurrence_id
603
+ ELSE matches.before_occurrence_id
604
+ END
605
+ FROM scan_comparison_matches AS matches
606
+ JOIN linked_occurrences AS linked
607
+ ON matches.before_occurrence_id = linked.occurrence_id
608
+ OR matches.after_occurrence_id = linked.occurrence_id
609
+ )
610
+ SELECT DISTINCT scans.started_at, scans.id AS scan_id
611
+ FROM linked_occurrences AS linked
612
+ JOIN finding_occurrences AS occurrences ON occurrences.id = linked.occurrence_id
613
+ JOIN scans ON scans.id = occurrences.scan_id
614
+ ORDER BY scans.started_at, scans.id
615
+ """,
616
+ (occurrence_id,),
617
+ )
618
+ ]
619
+ known_scan_ids = [known_scans[0][1]]
620
+ if len(known_scans) > 1:
621
+ known_scan_ids.append(known_scans[-1][1])
622
+ return (
623
+ [
624
+ {
625
+ "findingId": row["finding_id"],
626
+ "occurrenceId": row["occurrence_id"],
627
+ "reason": row["reason"],
628
+ "scanId": row["scan_id"],
629
+ "title": row["title"],
630
+ }
631
+ for row in rows
632
+ ],
633
+ known_scans[0][0],
634
+ known_scan_ids,
635
+ )
636
+
637
+
638
+ def _finding_groups(
639
+ before_findings: dict[str, sqlite3.Row],
640
+ after_findings: dict[str, sqlite3.Row],
641
+ matches: dict[str, Any] | None,
642
+ ) -> list[tuple[list[sqlite3.Row], list[sqlite3.Row], str | None]]:
643
+ rows = {
644
+ side: {row["id"]: row for row in findings.values()}
645
+ for side, findings in (("before", before_findings), ("after", after_findings))
646
+ }
647
+ consumed: dict[str, set[str]] = {"before": set(), "after": set()}
648
+ result = []
649
+ for match in matches["matches"] if matches is not None else []:
650
+ previous = [rows["before"][value] for value in match["beforeOccurrenceIds"]]
651
+ current = [rows["after"][value] for value in match["afterOccurrenceIds"]]
652
+ consumed["before"].update(match["beforeOccurrenceIds"])
653
+ consumed["after"].update(match["afterOccurrenceIds"])
654
+ result.append((previous, current, match["reason"]))
655
+ result.extend(
656
+ ([row], [], None) for key, row in rows["before"].items() if key not in consumed["before"]
657
+ )
658
+ result.extend(
659
+ ([], [row], None) for key, row in rows["after"].items() if key not in consumed["after"]
660
+ )
661
+ return sorted(
662
+ result,
663
+ key=lambda group: (
664
+ (group[1] or group[0])[0]["finding_id"],
665
+ (group[1] or group[0])[0]["id"],
666
+ ),
667
+ )
668
+
669
+
670
+ def _matching_input(row: sqlite3.Row) -> dict[str, Any]:
671
+ finding = json.loads(row["details_json"])
672
+ return {
673
+ **finding,
674
+ "findingId": row["finding_id"],
675
+ "occurrenceId": row["id"],
676
+ "remediation": row["remediation"],
677
+ "severity": {"level": row["severity"], **finding.get("severity", {})},
678
+ "summary": row["summary"],
679
+ "title": row["title"],
680
+ }
681
+
682
+
683
+ def finding_occurrence_rows(
684
+ connection: sqlite3.Connection,
685
+ scan_id: str,
686
+ *,
687
+ offset: int,
688
+ limit: int,
689
+ query: str | None = None,
690
+ severity: str | None = None,
691
+ status: str | None = None,
692
+ ) -> list[sqlite3.Row]:
693
+ conditions, values = finding_occurrence_conditions(
694
+ scan_id, query=query, severity=severity, status=status
695
+ )
696
+ return connection.execute(
697
+ f"""
698
+ SELECT
699
+ occurrences.id,
700
+ occurrences.finding_id,
701
+ occurrences.title,
702
+ occurrences.summary,
703
+ occurrences.severity,
704
+ occurrences.confidence,
705
+ occurrences.remediation,
706
+ occurrences.details_json,
707
+ occurrences.created_at
708
+ FROM finding_occurrences AS occurrences
709
+ LEFT JOIN finding_triage AS triage ON triage.occurrence_id = occurrences.id
710
+ WHERE {conditions}
711
+ ORDER BY
712
+ CASE occurrences.severity
713
+ WHEN 'critical' THEN 0
714
+ WHEN 'high' THEN 1
715
+ WHEN 'medium' THEN 2
716
+ WHEN 'low' THEN 3
717
+ WHEN 'informational' THEN 4
718
+ ELSE 5
719
+ END,
720
+ occurrences.created_at,
721
+ occurrences.id
722
+ LIMIT ? OFFSET ?
723
+ """,
724
+ (*values, limit, offset),
725
+ ).fetchall()
726
+
727
+
728
+ def finding_occurrence_conditions(
729
+ scan_id: str,
730
+ *,
731
+ query: str | None,
732
+ severity: str | None,
733
+ status: str | None,
734
+ ) -> tuple[str, list[str]]:
735
+ conditions = ["occurrences.scan_id = ?"]
736
+ values = [scan_id]
737
+ if severity is not None:
738
+ conditions.append("occurrences.severity = ?")
739
+ values.append(severity)
740
+ if status is not None:
741
+ conditions.append("COALESCE(triage.status, 'open') = ?")
742
+ values.append(status)
743
+ if query:
744
+ search = query.strip().casefold()
745
+ if search:
746
+ conditions.append(
747
+ "(instr(lower(occurrences.title), ?) > 0 "
748
+ "OR instr(lower(occurrences.summary), ?) > 0 "
749
+ "OR EXISTS ("
750
+ "SELECT 1 FROM finding_locations AS locations "
751
+ "WHERE locations.occurrence_id = occurrences.id "
752
+ "AND instr(lower(locations.relative_path), ?) > 0))"
753
+ )
754
+ values.extend((search, search, search))
755
+ return " AND ".join(conditions), values
756
+
757
+
758
+ def _scan_findings(connection: sqlite3.Connection, scan_id: str) -> dict[str, sqlite3.Row]:
759
+ rows = connection.execute(
760
+ """
761
+ SELECT occurrences.*,
762
+ COALESCE(triage.status, 'open') AS triage_status, triage.close_reason,
763
+ (
764
+ SELECT locations.relative_path
765
+ FROM finding_locations AS locations
766
+ WHERE locations.occurrence_id = occurrences.id
767
+ ORDER BY CASE WHEN locations.role = 'root_control' THEN 0 ELSE 1 END,
768
+ locations.sort_order
769
+ LIMIT 1
770
+ ) AS relative_path
771
+ FROM finding_occurrences AS occurrences
772
+ LEFT JOIN finding_triage AS triage ON triage.occurrence_id = occurrences.id
773
+ WHERE occurrences.scan_id = ?
774
+ """,
775
+ (scan_id,),
776
+ )
777
+ return {row["finding_id"]: row for row in rows}
778
+
779
+
780
+ def scan_covers_path(
781
+ scan: sqlite3.Row,
782
+ *,
783
+ target_id: str,
784
+ path: str | None,
785
+ coverage: dict[str, Any],
786
+ ) -> bool:
787
+ if (
788
+ scan["status"] != "complete"
789
+ or scan["target_id"] != target_id
790
+ or coverage.get("completeness") != "complete"
791
+ ):
792
+ return False
793
+ if not isinstance(path, str) or not path:
794
+ return False
795
+ included = coverage.get("includePaths")
796
+ if not isinstance(included, list) or not any(
797
+ isinstance(scope, str) and _path_within(path, scope) for scope in included
798
+ ):
799
+ return False
800
+ excluded = coverage.get("excludePaths")
801
+ if not isinstance(excluded, list):
802
+ return False
803
+ if any(isinstance(scope, str) and _path_matches(path, scope) for scope in excluded):
804
+ return False
805
+ exclusions = coverage.get("explicitExclusions")
806
+ if not isinstance(exclusions, list):
807
+ return False
808
+ if any(
809
+ isinstance(exclusion, dict)
810
+ and isinstance(exclusion.get("pattern"), str)
811
+ and _path_matches(path, exclusion["pattern"])
812
+ for exclusion in exclusions
813
+ ):
814
+ return False
815
+ return True
816
+
817
+
818
+ def _path_within(path: str, scope: str) -> bool:
819
+ candidate = PurePosixPath(path)
820
+ parent = PurePosixPath(scope)
821
+ return parent == PurePosixPath(".") or candidate == parent or parent in candidate.parents
822
+
823
+
824
+ def _path_matches(path: str, pattern: str) -> bool:
825
+ return _path_within(path, pattern) or fnmatch.fnmatchcase(path, pattern)
826
+
827
+
828
+ if __name__ == "__main__":
829
+ argparse.ArgumentParser(description=__doc__).parse_args()