@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,238 @@
1
+ """Scan handoff state transitions for the Codex Security workbench."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import sqlite3
7
+ from collections.abc import Callable
8
+ from typing import Any
9
+
10
+ from workbench_validation import optional_text, require_uuid
11
+
12
+ RECOVERY_HANDOFF_TOKEN_PREFIX = "recovery_"
13
+
14
+
15
+ def require_handoff_claim_token(value: str) -> str:
16
+ recovery_token = value.startswith(RECOVERY_HANDOFF_TOKEN_PREFIX)
17
+ token = value.removeprefix(RECOVERY_HANDOFF_TOKEN_PREFIX) if recovery_token else value
18
+ normalized = require_uuid(token, "claim-token")
19
+ return f"{RECOVERY_HANDOFF_TOKEN_PREFIX}{normalized}" if recovery_token else normalized
20
+
21
+
22
+ def require_current_continuation(
23
+ scan: sqlite3.Row,
24
+ claim_token: str | None,
25
+ *,
26
+ error_message: str,
27
+ ) -> None:
28
+ if (
29
+ scan["handoff_status"] == "delivered"
30
+ and scan["handoff_claim_token"] is None
31
+ and claim_token is None
32
+ ):
33
+ return
34
+ if claim_token is None:
35
+ raise SystemExit(error_message)
36
+ if scan["handoff_claim_token"] != require_handoff_claim_token(claim_token):
37
+ raise SystemExit(error_message)
38
+
39
+
40
+ def validate_handoff_delivery_thread(
41
+ owning_thread_id: str | None,
42
+ requesting_thread_id: str,
43
+ claim_token: str,
44
+ ) -> None:
45
+ if owning_thread_id != requesting_thread_id and not claim_token.startswith(
46
+ RECOVERY_HANDOFF_TOKEN_PREFIX
47
+ ):
48
+ raise SystemExit(
49
+ "A scan handoff can only be marked delivered from its owning Codex thread."
50
+ )
51
+
52
+
53
+ def claim_handoff_delivery(
54
+ connection: sqlite3.Connection,
55
+ args: argparse.Namespace,
56
+ *,
57
+ now: Callable[[], str],
58
+ require_scan: Callable[[sqlite3.Connection, str], sqlite3.Row],
59
+ stale_claim_before: Callable[[], str],
60
+ workspace_state: Callable[[sqlite3.Connection, str], dict[str, Any]],
61
+ ) -> dict[str, Any]:
62
+ scan_id = require_uuid(args.scan_id, "scan-id")
63
+ claim_token = require_handoff_claim_token(args.claim_token)
64
+ timestamp = now()
65
+ with connection:
66
+ scan = require_scan(connection, scan_id)
67
+ if scan["handoff_status"] != "pending" or scan["handoff_claim_token"] == claim_token:
68
+ return workspace_state(connection, scan["workspace_id"])
69
+ updated = connection.execute(
70
+ """
71
+ UPDATE scans
72
+ SET handoff_claimed_at = ?, handoff_claim_token = ?,
73
+ continuation_thread_id = CASE
74
+ WHEN handoff_claim_token IS NULL THEN continuation_thread_id
75
+ ELSE NULL
76
+ END,
77
+ deep_scan_owner_thread_id = CASE
78
+ WHEN handoff_claim_token IS NULL THEN deep_scan_owner_thread_id
79
+ ELSE NULL
80
+ END,
81
+ updated_at = ?
82
+ WHERE id = ? AND handoff_status = 'pending'
83
+ AND (
84
+ handoff_claim_token IS NULL
85
+ OR (
86
+ ? = 1
87
+ AND (handoff_claimed_at IS NULL OR handoff_claimed_at <= ?)
88
+ )
89
+ )
90
+ """,
91
+ (
92
+ timestamp,
93
+ claim_token,
94
+ timestamp,
95
+ scan["id"],
96
+ int(args.take_over_stale),
97
+ stale_claim_before(),
98
+ ),
99
+ )
100
+ if updated.rowcount != 1:
101
+ return workspace_state(connection, scan["workspace_id"])
102
+ return workspace_state(connection, scan["workspace_id"])
103
+
104
+
105
+ def release_handoff_delivery(
106
+ connection: sqlite3.Connection,
107
+ args: argparse.Namespace,
108
+ *,
109
+ now: Callable[[], str],
110
+ require_scan: Callable[[sqlite3.Connection, str], sqlite3.Row],
111
+ workspace_state: Callable[[sqlite3.Connection, str], dict[str, Any]],
112
+ ) -> dict[str, Any]:
113
+ scan_id = require_uuid(args.scan_id, "scan-id")
114
+ claim_token = require_handoff_claim_token(args.claim_token)
115
+ timestamp = now()
116
+ with connection:
117
+ scan = require_scan(connection, scan_id)
118
+ connection.execute(
119
+ """
120
+ UPDATE scans
121
+ SET handoff_claimed_at = NULL, handoff_claim_token = NULL,
122
+ continuation_thread_id = NULL, deep_scan_owner_thread_id = NULL,
123
+ updated_at = ?
124
+ WHERE id = ? AND handoff_status = 'pending'
125
+ AND handoff_claim_token = ?
126
+ """,
127
+ (timestamp, scan["id"], claim_token),
128
+ )
129
+ return workspace_state(connection, scan["workspace_id"])
130
+
131
+
132
+ def attach_scan_continuation_thread(
133
+ connection: sqlite3.Connection,
134
+ args: argparse.Namespace,
135
+ *,
136
+ now: Callable[[], str],
137
+ require_scan: Callable[[sqlite3.Connection, str], sqlite3.Row],
138
+ workspace_state: Callable[[sqlite3.Connection, str], dict[str, Any]],
139
+ ) -> dict[str, Any]:
140
+ scan_id = require_uuid(args.scan_id, "scan-id")
141
+ claim_token = require_handoff_claim_token(args.claim_token)
142
+ thread_id = optional_text(args.thread_id, maximum=512)
143
+ if thread_id is None:
144
+ raise SystemExit("Codex Security continuation thread ID is required.")
145
+ connection.execute("BEGIN IMMEDIATE")
146
+ try:
147
+ timestamp = now()
148
+ scan = require_scan(connection, scan_id)
149
+ if scan["handoff_claim_token"] != claim_token:
150
+ raise SystemExit("Codex Security continuation thread claim token does not match.")
151
+ if scan["continuation_thread_id"] is not None:
152
+ if scan["continuation_thread_id"] != thread_id:
153
+ raise SystemExit(
154
+ "Codex Security scan continuation is owned by another continuation."
155
+ )
156
+ connection.commit()
157
+ return workspace_state(connection, scan["workspace_id"])
158
+ updated = connection.execute(
159
+ """
160
+ UPDATE scans
161
+ SET continuation_thread_id = ?,
162
+ deep_scan_owner_thread_id = CASE
163
+ WHEN mode = 'deep' THEN ? ELSE deep_scan_owner_thread_id
164
+ END,
165
+ updated_at = ?
166
+ WHERE id = ? AND continuation_thread_id IS NULL
167
+ AND handoff_claim_token = ?
168
+ """,
169
+ (thread_id, thread_id, timestamp, scan["id"], claim_token),
170
+ )
171
+ if updated.rowcount != 1:
172
+ raise SystemExit("Codex Security continuation thread could not be attached.")
173
+ connection.commit()
174
+ except BaseException:
175
+ connection.rollback()
176
+ raise
177
+ return workspace_state(connection, scan["workspace_id"])
178
+
179
+
180
+ def mark_handoff_delivered(
181
+ connection: sqlite3.Connection,
182
+ args: argparse.Namespace,
183
+ *,
184
+ now: Callable[[], str],
185
+ require_scan: Callable[[sqlite3.Connection, str], sqlite3.Row],
186
+ require_workspace: Callable[[sqlite3.Connection, str], sqlite3.Row],
187
+ workspace_state: Callable[[sqlite3.Connection, str], dict[str, Any]],
188
+ ) -> dict[str, Any]:
189
+ scan_id = require_uuid(args.scan_id, "scan-id")
190
+ claim_token = require_handoff_claim_token(args.claim_token)
191
+ thread_id = optional_text(args.thread_id, maximum=512)
192
+ connection.execute("BEGIN IMMEDIATE")
193
+ try:
194
+ timestamp = now()
195
+ scan = require_scan(connection, scan_id)
196
+ if thread_id is not None:
197
+ workspace = require_workspace(connection, scan["workspace_id"])
198
+ validate_handoff_delivery_thread(
199
+ scan["continuation_thread_id"] or workspace["thread_id"],
200
+ thread_id,
201
+ claim_token,
202
+ )
203
+ if scan["handoff_status"] == "delivered":
204
+ if scan["handoff_claim_token"] != claim_token:
205
+ raise SystemExit(
206
+ "Codex Security handoff delivery is owned by another continuation."
207
+ )
208
+ connection.commit()
209
+ return workspace_state(connection, scan["workspace_id"])
210
+ updated = connection.execute(
211
+ """
212
+ UPDATE scans
213
+ SET handoff_status = 'delivered', handoff_claimed_at = NULL,
214
+ updated_at = ?
215
+ WHERE id = ? AND handoff_status = 'pending'
216
+ AND handoff_claim_token = ?
217
+ """,
218
+ (timestamp, scan["id"], claim_token),
219
+ )
220
+ if updated.rowcount != 1:
221
+ raise SystemExit("Codex Security handoff delivery could not be recorded.")
222
+ if scan["mode"] != "deep":
223
+ connection.execute(
224
+ """
225
+ UPDATE scan_progress
226
+ SET phase_items_total = 0, phase_items_completed = 0,
227
+ phase_progress_unit = 'checks',
228
+ preflight_checks_total = 0, preflight_checks_completed = 0,
229
+ updated_at = ?
230
+ WHERE scan_id = ?
231
+ """,
232
+ (timestamp, scan["id"]),
233
+ )
234
+ connection.commit()
235
+ except BaseException:
236
+ connection.rollback()
237
+ raise
238
+ return workspace_state(connection, scan["workspace_id"])
@@ -0,0 +1,325 @@
1
+ """Command-line argument parsing for the Codex Security workbench."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import sys
7
+ from pathlib import Path
8
+
9
+ # Some plugin hosts launch Python with safe-path isolation enabled.
10
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
11
+ import deep_scan_workbench as deep_scan
12
+ import workbench_remediation as remediation
13
+ from workbench_constants import (
14
+ DIFF_TARGET_KINDS,
15
+ EXPORT_FORMATS,
16
+ FINDING_CLOSE_REASONS,
17
+ FINDING_SEVERITIES,
18
+ FINDING_STATUSES,
19
+ FINDINGS_PAGE_MAX,
20
+ MODES,
21
+ PHASE_PROGRESS_UNITS,
22
+ PHASES,
23
+ REMEDIATION_UPDATE_STATES,
24
+ )
25
+
26
+
27
+ def parse_args(description: str) -> argparse.Namespace:
28
+ parser = argparse.ArgumentParser(description=description)
29
+ subparsers = parser.add_subparsers(dest="command", required=True)
30
+
31
+ subparsers.add_parser("get-setup-preference")
32
+
33
+ create_workspace = subparsers.add_parser("create-workspace")
34
+ create_workspace.add_argument("--workspace-id", required=True)
35
+ create_workspace.add_argument("--thread-id")
36
+ create_workspace.add_argument("--target-path")
37
+ create_workspace.add_argument("--target-title")
38
+ create_workspace.add_argument("--target-summary")
39
+ create_workspace.add_argument("--user-context")
40
+ create_preflight = create_workspace.add_mutually_exclusive_group()
41
+ create_preflight.add_argument("--capability-preflight-json")
42
+ create_preflight.add_argument("--capability-preflight-json-file", type=Path)
43
+ create_workspace.add_argument("--scope")
44
+ create_workspace.add_argument("--mode", choices=MODES, default="standard")
45
+ create_workspace.add_argument("--diff-target-kind", choices=DIFF_TARGET_KINDS)
46
+ create_workspace.add_argument("--diff-base-revision")
47
+ create_workspace.add_argument("--diff-head-revision")
48
+ create_workspace.add_argument("--diff-content-digest")
49
+
50
+ get_workspace = subparsers.add_parser("get-workspace")
51
+ get_workspace.add_argument("--workspace-id", required=True)
52
+ get_workspace.add_argument("--thread-id")
53
+
54
+ get_latest_workspace = subparsers.add_parser("get-latest-workspace")
55
+ get_latest_workspace.add_argument("--thread-id", required=True)
56
+
57
+ list_workspace_scans = subparsers.add_parser("list-workspace-scans")
58
+ list_workspace_scans.add_argument("--workspace-id", required=True)
59
+ list_workspace_scans.add_argument("--offset", type=non_negative_int, default=0)
60
+ list_workspace_scans.add_argument("--limit", type=workspace_scan_limit, default=20)
61
+
62
+ inspect_target = subparsers.add_parser("inspect-target")
63
+ inspect_target.add_argument("--target-path", required=True)
64
+
65
+ inspect_setup = subparsers.add_parser("inspect-setup")
66
+ inspect_setup.add_argument("--target-path", required=True)
67
+ inspect_setup.add_argument("--scope", required=True)
68
+ inspect_setup.add_argument("--mode", choices=MODES, required=True)
69
+ inspect_setup.add_argument("--diff-target-kind", choices=DIFF_TARGET_KINDS)
70
+ inspect_setup.add_argument("--diff-base-revision")
71
+ inspect_setup.add_argument("--diff-head-revision")
72
+ inspect_setup.add_argument("--diff-content-digest")
73
+
74
+ begin_diff_resolution = subparsers.add_parser("begin-diff-resolution")
75
+ begin_diff_resolution.add_argument("--workspace-id", required=True)
76
+ begin_diff_resolution.add_argument("--request-id", required=True)
77
+ begin_diff_resolution.add_argument("--target-path", required=True)
78
+ begin_diff_resolution.add_argument("--user-context", required=True)
79
+
80
+ cancel_diff_resolution = subparsers.add_parser("cancel-diff-resolution")
81
+ cancel_diff_resolution.add_argument("--workspace-id", required=True)
82
+ cancel_diff_resolution.add_argument("--request-id", required=True)
83
+
84
+ set_diff_target = subparsers.add_parser("set-diff-target")
85
+ set_diff_target.add_argument("--workspace-id", required=True)
86
+ set_diff_target.add_argument("--request-id", required=True)
87
+ set_diff_target.add_argument("--target-summary", required=True)
88
+ set_diff_target.add_argument("--diff-target-kind", choices=DIFF_TARGET_KINDS, required=True)
89
+ set_diff_target.add_argument("--diff-base-revision")
90
+ set_diff_target.add_argument("--diff-head-revision")
91
+ set_diff_target.add_argument("--diff-content-digest")
92
+
93
+ save_workspace = subparsers.add_parser("save-workspace")
94
+ save_workspace.add_argument("--workspace-id", required=True)
95
+ save_workspace.add_argument("--target-path", required=True)
96
+ save_workspace.add_argument("--scope", required=True)
97
+ save_workspace.add_argument("--mode", choices=MODES, required=True)
98
+ save_workspace.add_argument("--target-summary")
99
+ save_workspace.add_argument("--user-context")
100
+ save_workspace.add_argument("--diff-target-kind", choices=DIFF_TARGET_KINDS)
101
+ save_workspace.add_argument("--diff-base-revision")
102
+ save_workspace.add_argument("--diff-head-revision")
103
+ save_workspace.add_argument("--diff-content-digest")
104
+
105
+ set_capability_preflight = subparsers.add_parser("set-capability-preflight")
106
+ set_capability_preflight.add_argument("--workspace-id", required=True)
107
+ set_capability_preflight.add_argument("--checked-target-path", required=True)
108
+ set_capability_preflight.add_argument("--checked-mode", choices=MODES, required=True)
109
+ set_preflight = set_capability_preflight.add_mutually_exclusive_group(required=True)
110
+ set_preflight.add_argument("--capability-preflight-json")
111
+ set_preflight.add_argument("--capability-preflight-json-file", type=Path)
112
+
113
+ start_scan = subparsers.add_parser("start-scan")
114
+ start_scan.add_argument("--workspace-id", required=True)
115
+ start_scan.add_argument("--scan-root")
116
+
117
+ disable_setup_ui = subparsers.add_parser("disable-setup-ui")
118
+ disable_setup_ui.add_argument("--workspace-id", required=True)
119
+
120
+ start_prompt_only_scan = subparsers.add_parser("start-prompt-only-scan")
121
+ start_prompt_only_scan.add_argument("--thread-id", required=True)
122
+ start_prompt_only_scan.add_argument("--target-path", required=True)
123
+ start_prompt_only_scan.add_argument("--scope", required=True)
124
+ start_prompt_only_scan.add_argument("--mode", choices=("diff", "standard"), required=True)
125
+ start_prompt_only_scan.add_argument("--target-summary")
126
+ start_prompt_only_scan.add_argument("--user-context")
127
+ start_prompt_only_scan.add_argument("--diff-target-kind", choices=DIFF_TARGET_KINDS)
128
+ start_prompt_only_scan.add_argument("--diff-base-revision")
129
+ start_prompt_only_scan.add_argument("--diff-head-revision")
130
+ start_prompt_only_scan.add_argument("--diff-content-digest")
131
+ start_prompt_only_scan.add_argument("--scan-root")
132
+
133
+ deep_scan.register_subcommands(subparsers, positive_int)
134
+
135
+ get_scan = subparsers.add_parser("get-scan")
136
+ get_scan.add_argument("--scan-id", required=True)
137
+ get_scan.add_argument("--occurrence-id")
138
+
139
+ list_scans = subparsers.add_parser("list-scans")
140
+ list_scans.add_argument("--query")
141
+ list_scans.add_argument("--target-id")
142
+ list_scans.add_argument("--status", choices=("running", "complete", "failed", "canceled"))
143
+ list_scans.add_argument("--mode", choices=MODES)
144
+ list_scans.add_argument("--repository")
145
+ list_scans.add_argument("--scan-root")
146
+ list_scans.add_argument("--offset", type=non_negative_int, default=0)
147
+ list_scans.add_argument("--limit", type=positive_int)
148
+
149
+ list_unmatched_scan_pairs = subparsers.add_parser("list-unmatched-scan-pairs")
150
+ list_unmatched_scan_pairs.add_argument("--repository", required=True)
151
+ list_unmatched_scan_pairs.add_argument("--force", action="store_true")
152
+
153
+ register_cli_scan = subparsers.add_parser("register-cli-scan")
154
+ register_cli_scan.add_argument("--scan-dir", required=True)
155
+ register_cli_scan.add_argument("--repository", required=True)
156
+ register_cli_scan.add_argument("--recipe-json", required=True)
157
+ register_cli_scan.add_argument("--parent-scan-id")
158
+
159
+ get_scan_recipe = subparsers.add_parser("get-scan-recipe")
160
+ get_scan_recipe.add_argument("--scan-id", required=True)
161
+
162
+ compare_scans = subparsers.add_parser("compare-scans")
163
+ compare_scans.add_argument("--before-scan-id", required=True)
164
+ compare_scans.add_argument("--after-scan-id", required=True)
165
+ compare_scans.add_argument("--include-matching-inputs", action="store_true")
166
+ compare_scans.add_argument("--require-matches", action="store_true")
167
+
168
+ save_scan_comparison = subparsers.add_parser("save-scan-comparison")
169
+ save_scan_comparison.add_argument("--before-scan-id", required=True)
170
+ save_scan_comparison.add_argument("--after-scan-id", required=True)
171
+ save_scan_comparison.add_argument("--matches-json", required=True)
172
+
173
+ list_global_findings = subparsers.add_parser("list-global-findings")
174
+ list_global_findings.add_argument("--query")
175
+ list_global_findings.add_argument("--severity", choices=FINDING_SEVERITIES)
176
+ list_global_findings.add_argument("--status", choices=FINDING_STATUSES)
177
+ list_global_findings.add_argument("--target-id")
178
+ list_global_findings.add_argument("--offset", type=non_negative_int, default=0)
179
+ list_global_findings.add_argument("--limit", type=positive_int, default=FINDINGS_PAGE_MAX)
180
+ list_repositories = subparsers.add_parser("list-repositories")
181
+ list_repositories.add_argument("--query")
182
+ list_repositories.add_argument("--target-id")
183
+ list_repositories.add_argument("--status", choices=("scanned", "not_scanned", "open_findings"))
184
+ list_repositories.add_argument("--offset", type=non_negative_int, default=0)
185
+ list_repositories.add_argument("--limit", type=positive_int)
186
+
187
+ list_findings = subparsers.add_parser("list-findings")
188
+ list_findings.add_argument("--scan-id", required=True)
189
+ list_findings.add_argument("--query")
190
+ list_findings.add_argument("--severity", choices=FINDING_SEVERITIES)
191
+ list_findings.add_argument("--status", choices=FINDING_STATUSES)
192
+ list_findings.add_argument("--offset", type=non_negative_int, default=0)
193
+ list_findings.add_argument("--limit", type=positive_int, default=FINDINGS_PAGE_MAX)
194
+
195
+ update_progress = subparsers.add_parser("update-progress")
196
+ update_progress.add_argument("--scan-id", required=True)
197
+ update_progress.add_argument("--phase", choices=PHASES)
198
+ update_progress.add_argument("--phase-items-total", type=non_negative_int)
199
+ update_progress.add_argument("--phase-items-completed", type=non_negative_int)
200
+ update_progress.add_argument("--phase-progress-unit", choices=PHASE_PROGRESS_UNITS)
201
+ update_progress.add_argument("--preflight-issues-json")
202
+ update_progress.add_argument("--review-items-total", type=non_negative_int)
203
+ update_progress.add_argument("--review-items-completed", type=non_negative_int)
204
+ update_progress.add_argument("--reportable-findings-count", type=non_negative_int)
205
+ update_progress.add_argument("--deep-review-pass", type=positive_int)
206
+ update_progress.add_argument("--claim-token")
207
+
208
+ complete_scan = subparsers.add_parser("complete-scan")
209
+ complete_scan.add_argument("--scan-id", required=True)
210
+ complete_scan.add_argument("--claim-token")
211
+ complete_scan.add_argument("--cost-json")
212
+
213
+ cancel_scan = subparsers.add_parser("cancel-scan")
214
+ cancel_scan.add_argument("--scan-id", required=True)
215
+ cancel_scan.add_argument("--thread-id")
216
+
217
+ fail_scan = subparsers.add_parser("fail-scan")
218
+ fail_scan.add_argument("--scan-id", required=True)
219
+ fail_scan.add_argument("--message", required=True)
220
+ fail_scan.add_argument("--claim-token")
221
+ fail_scan.add_argument("--cost-json")
222
+
223
+ mark_handoff_delivered = subparsers.add_parser("mark-handoff-delivered")
224
+ mark_handoff_delivered.add_argument("--scan-id", required=True)
225
+ mark_handoff_delivered.add_argument("--claim-token", required=True)
226
+ mark_handoff_delivered.add_argument("--thread-id")
227
+
228
+ claim_handoff_delivery = subparsers.add_parser("claim-handoff-delivery")
229
+ claim_handoff_delivery.add_argument("--scan-id", required=True)
230
+ claim_handoff_delivery.add_argument("--claim-token", required=True)
231
+ claim_handoff_delivery.add_argument("--take-over-stale", action="store_true")
232
+
233
+ release_handoff_delivery = subparsers.add_parser("release-handoff-delivery")
234
+ release_handoff_delivery.add_argument("--scan-id", required=True)
235
+ release_handoff_delivery.add_argument("--claim-token", required=True)
236
+
237
+ attach_scan_continuation_thread = subparsers.add_parser("attach-scan-continuation-thread")
238
+ attach_scan_continuation_thread.add_argument("--scan-id", required=True)
239
+ attach_scan_continuation_thread.add_argument("--claim-token", required=True)
240
+ attach_scan_continuation_thread.add_argument("--thread-id", required=True)
241
+
242
+ set_finding_triage = subparsers.add_parser("set-finding-triage")
243
+ set_finding_triage.add_argument("--occurrence-id", required=True)
244
+ set_finding_triage.add_argument("--status", choices=FINDING_STATUSES, required=True)
245
+ set_finding_triage.add_argument("--close-reason", choices=FINDING_CLOSE_REASONS)
246
+ set_finding_triage.add_argument("--note")
247
+
248
+ request_finding_remediation = subparsers.add_parser("request-finding-remediation")
249
+ request_finding_remediation.add_argument("--occurrence-id", required=True)
250
+ request_finding_remediation.add_argument("--request-id", required=True)
251
+ request_finding_remediation.add_argument("--action-token", required=True)
252
+
253
+ request_finding_remediation_action = subparsers.add_parser("request-finding-remediation-action")
254
+ request_finding_remediation_action.add_argument("--occurrence-id", required=True)
255
+ request_finding_remediation_action.add_argument("--request-id", required=True)
256
+ request_finding_remediation_action.add_argument(
257
+ "--expected-version", type=positive_int, required=True
258
+ )
259
+ request_finding_remediation_action.add_argument(
260
+ "--action", choices=("apply", "verify"), required=True
261
+ )
262
+ request_finding_remediation_action.add_argument("--action-token", required=True)
263
+
264
+ claim_finding_remediation_resend = subparsers.add_parser("claim-finding-remediation-resend")
265
+ claim_finding_remediation_resend.add_argument("--occurrence-id", required=True)
266
+ claim_finding_remediation_resend.add_argument("--request-id", required=True)
267
+ claim_finding_remediation_resend.add_argument("--action-token", required=True)
268
+
269
+ mark_finding_remediation_delivered = subparsers.add_parser("mark-finding-remediation-delivered")
270
+ mark_finding_remediation_delivered.add_argument("--occurrence-id", required=True)
271
+ mark_finding_remediation_delivered.add_argument("--request-id", required=True)
272
+ mark_finding_remediation_delivered.add_argument("--action-token", required=True)
273
+
274
+ release_finding_remediation_claim = subparsers.add_parser("release-finding-remediation-claim")
275
+ release_finding_remediation_claim.add_argument("--occurrence-id", required=True)
276
+ release_finding_remediation_claim.add_argument("--request-id", required=True)
277
+ release_finding_remediation_claim.add_argument("--action-token", required=True)
278
+
279
+ remediation.register_cancel_finding_remediation_request(subparsers)
280
+
281
+ set_finding_remediation = subparsers.add_parser("set-finding-remediation")
282
+ set_finding_remediation.add_argument("--occurrence-id", required=True)
283
+ set_finding_remediation.add_argument("--request-id", required=True)
284
+ set_finding_remediation.add_argument("--action-token", required=True)
285
+ set_finding_remediation.add_argument("--expected-version", type=positive_int, required=True)
286
+ set_finding_remediation.add_argument(
287
+ "--state", choices=REMEDIATION_UPDATE_STATES, required=True
288
+ )
289
+ set_finding_remediation.add_argument("--summary")
290
+ set_finding_remediation.add_argument("--patch-path")
291
+ set_finding_remediation.add_argument("--patch-digest")
292
+ set_finding_remediation.add_argument("--base-revision")
293
+ set_finding_remediation.add_argument("--verification-summary")
294
+
295
+ export_findings = subparsers.add_parser("export-findings")
296
+ export_findings.add_argument("--scan-id", required=True)
297
+ export_findings.add_argument("--format", choices=EXPORT_FORMATS, required=True)
298
+
299
+ subparsers.add_parser("database-info")
300
+ return parser.parse_args()
301
+
302
+
303
+ def non_negative_int(value: str) -> int:
304
+ parsed = int(value)
305
+ if parsed < 0:
306
+ raise argparse.ArgumentTypeError("expected a non-negative integer")
307
+ return parsed
308
+
309
+
310
+ def positive_int(value: str) -> int:
311
+ parsed = int(value)
312
+ if parsed < 1:
313
+ raise argparse.ArgumentTypeError("expected a positive integer")
314
+ return parsed
315
+
316
+
317
+ def workspace_scan_limit(value: str) -> int:
318
+ parsed = positive_int(value)
319
+ if parsed > 100:
320
+ raise argparse.ArgumentTypeError("expected an integer between 1 and 100")
321
+ return parsed
322
+
323
+
324
+ if __name__ == "__main__":
325
+ parse_args(__doc__)
@@ -0,0 +1,81 @@
1
+ """Shared constants for the Codex Security workbench."""
2
+
3
+ import argparse
4
+
5
+ MODES = ("diff", "standard", "deep")
6
+ DIFF_TARGET_KINDS = ("working_tree", "commit", "range")
7
+ PHASES = ("preflight", "threat_model", "discovery", "validation", "attack_path", "reporting")
8
+ PHASE_PROGRESS_UNITS = (
9
+ "checks",
10
+ "threat_surfaces",
11
+ "review_receipts",
12
+ "candidate_findings",
13
+ "validated_findings",
14
+ "report_artifacts",
15
+ )
16
+ FINDING_SEVERITIES = ("critical", "high", "medium", "low", "informational")
17
+ FINDING_STATUSES = ("open", "closed")
18
+ FINDING_CLOSE_REASONS = ("already_fixed", "wont_fix", "false_positive")
19
+ REMEDIATION_STATES = (
20
+ "idle",
21
+ "requested",
22
+ "generated",
23
+ "applied",
24
+ "verifying",
25
+ "verified",
26
+ "failed",
27
+ "superseded",
28
+ )
29
+ REMEDIATION_UPDATE_STATES = ("generated", "applied", "verifying", "verified", "failed")
30
+ REMEDIATION_PENDING_ACTIONS = ("generate", "apply", "verify")
31
+ EXPORT_FORMATS = ("csv", "json", "sarif")
32
+ ARTIFACTS = {
33
+ "coverage": "coverage.json",
34
+ "findings": "findings.json",
35
+ "manifest": "scan-manifest.json",
36
+ "markdownReport": "report.md",
37
+ }
38
+ SQLITE_RETRY_ATTEMPTS = 5
39
+ CLAIM_LEASE_SECONDS = 120
40
+ DELIVERED_ACTION_LEASE_SECONDS = 900
41
+ PATCH_PREVIEW_BYTES = 16_000
42
+ PATCH_ARTIFACT_MAX_BYTES = 2 * 1024 * 1024
43
+ FINDINGS_RESULT_LIMIT = 20
44
+ FINDINGS_PAGE_MAX = 20
45
+ FINDING_DETAILS_PREVIEW_BYTES = 16_000
46
+ FINDING_ROOT_CAUSE_PREVIEW_BYTES = 2_000
47
+ FINDING_VALIDATION_PREVIEW_BYTES = 3_000
48
+ FINDING_ATTACK_PATH_PREVIEW_BYTES = 4_000
49
+ FINDING_CODE_EVIDENCE_LIMIT = 4
50
+ FINDING_CODE_EVIDENCE_SNIPPET_BYTES = 1_500
51
+ FINDING_EVIDENCE_EXCERPT_BYTES = 8_000
52
+ FINDING_LOCATIONS_LIMIT = 8
53
+ FINDING_TITLE_BYTES = 512
54
+ FINDING_SUMMARY_BYTES = 2_000
55
+ FINDING_REMEDIATION_BYTES = 2_000
56
+ FINDING_LOCATION_PATH_BYTES = 2_048
57
+ FINDING_LOCATION_ROLE_BYTES = 128
58
+ FINDING_ABSOLUTE_PATH_BYTES = 4_096
59
+ FINDING_LEVEL_BYTES = 128
60
+ MAX_CAPABILITY_PREFLIGHT_INPUT_JSON_BYTES = 160_000
61
+ MAX_CAPABILITY_PREFLIGHT_PERSISTED_JSON_BYTES = 180_000
62
+ GIT_REPOSITORY_ENVIRONMENT = (
63
+ "GIT_ALTERNATE_OBJECT_DIRECTORIES",
64
+ "GIT_CEILING_DIRECTORIES",
65
+ "GIT_COMMON_DIR",
66
+ "GIT_DIR",
67
+ "GIT_DISCOVERY_ACROSS_FILESYSTEM",
68
+ "GIT_INDEX_FILE",
69
+ "GIT_NAMESPACE",
70
+ "GIT_OBJECT_DIRECTORY",
71
+ "GIT_WORK_TREE",
72
+ )
73
+ EMPTY_GIT_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
74
+
75
+
76
+ def main() -> None:
77
+ argparse.ArgumentParser(description=__doc__).parse_args()
78
+
79
+
80
+ if __name__ == "__main__":
81
+ main()