@openai/codex-security 0.1.0 → 0.1.2

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 (39) hide show
  1. package/README.md +106 -58
  2. package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
  3. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/scripts/config_preflight.py +1 -1
  6. package/_bundled_plugin/scripts/workbench_cli.py +5 -0
  7. package/_bundled_plugin/scripts/workbench_db.py +34 -98
  8. package/_bundled_plugin/scripts/workbench_feedback.py +96 -0
  9. package/_bundled_plugin/scripts/workbench_scan_history.py +11 -1
  10. package/_bundled_plugin/scripts/workbench_scan_start.py +76 -0
  11. package/_bundled_plugin/scripts/workbench_schema.py +8 -0
  12. package/_bundled_plugin/scripts/workbench_target.py +95 -0
  13. package/_bundled_plugin/scripts/workbench_validation.py +7 -0
  14. package/_bundled_plugin/skills/validation/SKILL.md +2 -0
  15. package/dist/api.d.ts +6 -3
  16. package/dist/api.d.ts.map +1 -1
  17. package/dist/api.js +107 -19
  18. package/dist/api.js.map +1 -1
  19. package/dist/cli.d.ts +7 -2
  20. package/dist/cli.d.ts.map +1 -1
  21. package/dist/cli.js +222 -48
  22. package/dist/cli.js.map +1 -1
  23. package/dist/index.d.ts +1 -1
  24. package/dist/index.d.ts.map +1 -1
  25. package/dist/index.js.map +1 -1
  26. package/dist/multiscan.d.ts.map +1 -1
  27. package/dist/multiscan.js +3 -1
  28. package/dist/multiscan.js.map +1 -1
  29. package/dist/runtime.d.ts.map +1 -1
  30. package/dist/runtime.js +6 -1
  31. package/dist/runtime.js.map +1 -1
  32. package/dist/scan-history-renderer.d.ts.map +1 -1
  33. package/dist/scan-history-renderer.js +8 -0
  34. package/dist/scan-history-renderer.js.map +1 -1
  35. package/dist/version.d.ts +14 -0
  36. package/dist/version.d.ts.map +1 -1
  37. package/dist/version.js +102 -0
  38. package/dist/version.js.map +1 -1
  39. package/package.json +2 -1
package/README.md CHANGED
@@ -12,7 +12,7 @@ executable, and the matching Codex runtime.
12
12
 
13
13
  ```bash
14
14
  npm install @openai/codex-security
15
- npx codex-security --version
15
+ npx @openai/codex-security --version
16
16
  ```
17
17
 
18
18
  The package supports macOS, Linux, and Windows and requires Node.js 22 or
@@ -20,9 +20,13 @@ later. Scanning and exporting findings also require Python 3.10 or later. If
20
20
  you use Python 3.10, install the `tomli` package. Select another interpreter
21
21
  with `--python`, `pythonPath`, or `PYTHON` when needed.
22
22
 
23
+ When a newer version is available, the CLI shows the update command for your
24
+ installation method. Set `CODEX_SECURITY_NO_UPDATE_NOTICE=1` to hide the
25
+ notice. Notices are also disabled in CI and when stderr is not a terminal.
26
+
23
27
  ## Run a scan from TypeScript
24
28
 
25
- Sign in with `npx codex-security login` or set `OPENAI_API_KEY` or
29
+ Sign in with `npx @openai/codex-security login` or set `OPENAI_API_KEY` or
26
30
  `CODEX_API_KEY`. Then create a client and scan a repository you own or have
27
31
  permission to assess:
28
32
 
@@ -57,73 +61,103 @@ limit access to authorized reviewers.
57
61
  For local use, sign in with ChatGPT:
58
62
 
59
63
  ```bash
60
- npx codex-security login
61
- npx codex-security scan .
64
+ npx @openai/codex-security login
65
+ npx @openai/codex-security scan .
62
66
  ```
63
67
 
64
68
  On a remote or headless machine, use device authentication:
65
69
 
66
70
  ```bash
67
- npx codex-security login --device-auth
71
+ npx @openai/codex-security login --device-auth
68
72
  ```
69
73
 
70
74
  For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To store an API key instead,
71
75
  pass it on stdin:
72
76
 
73
77
  ```bash
74
- printenv OPENAI_API_KEY | npx codex-security login --with-api-key
78
+ printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
75
79
  ```
76
80
 
77
81
  On Windows, set the API key in PowerShell:
78
82
 
79
83
  ```powershell
80
84
  $env:OPENAI_API_KEY = "<your-api-key>"
81
- npx codex-security scan C:\code\repository
85
+ npx @openai/codex-security scan C:\code\repository
82
86
  ```
83
87
 
84
- Check or remove the stored sign-in with `npx codex-security login status` and
85
- `npx codex-security logout`. Codex Security reuses an existing file-based Codex
88
+ Check or remove the stored sign-in with `npx @openai/codex-security login status` and
89
+ `npx @openai/codex-security logout`. Codex Security reuses an existing file-based Codex
86
90
  sign-in. If Codex stores credentials in the system keyring, run
87
- `npx codex-security login` once before scanning.
91
+ `npx @openai/codex-security login` once before scanning.
92
+
93
+ An environment API key takes precedence over a stored sign-in by default.
94
+ When both a stored ChatGPT sign-in and an environment API key are available, an
95
+ interactive scan asks which credential to use. JSON output, dry runs, CI, and
96
+ other noninteractive scans never prompt and retain automatic API-key
97
+ precedence. Select the credential source explicitly with `--auth`:
98
+
99
+ ```bash
100
+ npx @openai/codex-security scan . --auth chatgpt
101
+ npx @openai/codex-security scan . --auth api-key
102
+ ```
103
+
104
+ `--auth chatgpt` uses the stored sign-in and ignores `OPENAI_API_KEY` and
105
+ `CODEX_API_KEY`. `--auth api-key` requires one of those environment variables.
106
+ Omit `--auth`, or pass `--auth auto`, to preserve automatic API-key precedence
107
+ for existing CI and unattended scans. The SDK accepts the same selection as
108
+ `security.run(repository, { auth: "chatgpt" })` and
109
+ `security.preflight(repository, { auth: "chatgpt" })`.
110
+
111
+ To make the stored ChatGPT sign-in the automatic default instead, unset any
112
+ configured API-key variables:
113
+
114
+ ```bash
115
+ unset OPENAI_API_KEY CODEX_API_KEY
116
+ ```
88
117
 
89
- An environment API key takes precedence over a stored sign-in. Unset both
90
- `OPENAI_API_KEY` and `CODEX_API_KEY` to use your ChatGPT sign-in. When an
91
- environment key is configured, `codex-security login status` identifies the
92
- effective credential source without printing its value, including when no
93
- stored sign-in exists.
118
+ The interactive choice applies only to the current scan and is not persisted.
119
+
120
+ When an environment key is configured, ChatGPT login and
121
+ `codex-security login status` identify the effective scan credential source
122
+ without printing its value, including when no stored sign-in exists.
94
123
 
95
124
  ## CLI
96
125
 
97
126
  ```bash
98
- npx codex-security scan /path/to/repository
99
- npx codex-security scan /path/to/repository --model gpt-5.6-terra
100
- npx codex-security scan /path/to/repository --path src --path tests
101
- npx codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
102
- npx codex-security scan /path/to/repository --diff origin/main --json
103
- npx codex-security scan /path/to/repository --output-dir /path/outside/repository/results
104
- npx codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing
105
- npx codex-security scan /path/to/repository --dry-run
106
- npx codex-security scan /path/to/repository --fail-on-severity high
107
- npx codex-security scan /path/to/repository --max-cost 5
108
- npx codex-security install-hook
109
- npx codex-security bulk-scan
110
- npx codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4
111
- npx codex-security scans list /path/to/repository
112
- npx codex-security scans list --scan-root /path/outside/repository/results
113
- npx codex-security scans show SCAN_ID
114
- npx codex-security scans rerun SCAN_ID
115
- npx codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
116
- npx codex-security scans match --all
117
- npx codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
118
- npx codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif
119
- npx codex-security export /path/outside/repository/results --export-format csv --output /path/outside/repository/findings.csv
120
- npx codex-security export /path/outside/repository/results --export-format json --output /path/outside/repository/findings.json
121
- npx codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"
122
- npx codex-security patch /path/outside/repository/findings.json "Missing authorization check in src/routes.ts:18"
127
+ npx @openai/codex-security scan /path/to/repository
128
+ npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra
129
+ npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra --effort high
130
+ npx @openai/codex-security scan /path/to/repository --path src --path tests
131
+ npx @openai/codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
132
+ npx @openai/codex-security scan /path/to/repository --diff origin/main --json
133
+ npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results
134
+ npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing
135
+ npx @openai/codex-security scan /path/to/repository --dry-run
136
+ npx @openai/codex-security scan /path/to/repository --fail-on-severity high
137
+ npx @openai/codex-security scan /path/to/repository --max-cost 5
138
+ npx @openai/codex-security install-hook
139
+ npx @openai/codex-security bulk-scan
140
+ npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high
141
+ npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4
142
+ npx @openai/codex-security scans list /path/to/repository
143
+ npx @openai/codex-security scans list --scan-root /path/outside/repository/results
144
+ npx @openai/codex-security scans show SCAN_ID
145
+ npx @openai/codex-security scans rerun SCAN_ID
146
+ npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
147
+ npx @openai/codex-security scans match --all
148
+ npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
149
+ npx @openai/codex-security findings false-positive OCCURRENCE_ID --reason "The route already checks permissions"
150
+ npx @openai/codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif
151
+ npx @openai/codex-security export /path/outside/repository/results --export-format csv --output /path/outside/repository/findings.csv
152
+ npx @openai/codex-security export /path/outside/repository/results --export-format json --output /path/outside/repository/findings.json
153
+ npx @openai/codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"
154
+ npx @openai/codex-security validate "Possible SQL injection" --effort high
155
+ npx @openai/codex-security patch /path/outside/repository/findings.json "Missing authorization check in src/routes.ts:18"
156
+ npx @openai/codex-security patch "Missing authorization check" --effort high
123
157
  ```
124
158
 
125
- Run `npx codex-security --version` for the installed CLI version or
126
- `npx codex-security info --json` for the package, bundled plugin, Codex runtime,
159
+ Run `npx @openai/codex-security --version` for the installed CLI version or
160
+ `npx @openai/codex-security info --json` for the package, bundled plugin, Codex runtime,
127
161
  default model, reasoning effort, and first-scan command. A scan with `--dry-run`
128
162
  also reports its effective model and reasoning effort, including `--codex`
129
163
  overrides, without starting Codex or contacting the network.
@@ -157,10 +191,11 @@ for a passing policy. Incomplete scans still write the available human or JSON
157
191
  result to stdout and a coverage warning to stderr, including in report-only
158
192
  mode.
159
193
 
160
- Scans use `gpt-5.6-sol` with extra-high reasoning effort by default. Use
161
- `--model gpt-5.6-terra` to switch models. Use repeatable `--codex KEY=VALUE`
162
- options for other Codex settings, such as
163
- `--codex 'model_reasoning_effort="high"'`.
194
+ Scans use `gpt-5.6-sol` with extra-high reasoning effort by default. OpenAI is
195
+ the implied provider. Use `--model gpt-5.6-terra` to switch models and
196
+ `--effort minimal|low|medium|high|xhigh` to set reasoning effort. Repeat
197
+ `--codex KEY=VALUE` for other Codex settings; existing
198
+ `--codex 'model_reasoning_effort="high"'` overrides remain supported.
164
199
 
165
200
  Scan progress identifies the requested paths and reports actual ranking,
166
201
  file-review, validation, and attack-path phases as they become available.
@@ -178,10 +213,10 @@ Use `--max-cost USD` to stop a scan, including its delegated workers, when its
178
213
  running cost exceeds the limit. Partial results are preserved. Requests
179
214
  already in progress can finish above the limit.
180
215
 
181
- Run `npx codex-security scan --help` or `npx codex-security bulk-scan --help`
216
+ Run `npx @openai/codex-security scan --help` or `npx @openai/codex-security bulk-scan --help`
182
217
  for the complete CLI references.
183
218
 
184
- Sign in with `gh auth login`, then run `npx codex-security bulk-scan` to discover
219
+ Sign in with `gh auth login`, then run `npx @openai/codex-security bulk-scan` to discover
185
220
  GitHub repositories pushed in the last 90 days. Archived
186
221
  repositories and forks are excluded. Search the repository list, select the
187
222
  repositories to scan, and confirm before scanning.
@@ -203,7 +238,7 @@ Results remain under `--output-dir`; rerun the same command to resume.
203
238
 
204
239
  ### Scan history and reruns
205
240
 
206
- `npx codex-security scans list` lists scans for the current repository. Pass a
241
+ `npx @openai/codex-security scans list` lists scans for the current repository. Pass a
207
242
  repository path to inspect another checkout, `--scan-root DIR` to list scans
208
243
  whose artifacts are under a particular root. `scans show SCAN_ID` includes the
209
244
  scan configuration, results, coverage, and artifact locations.
@@ -216,6 +251,18 @@ Scan history uses the existing Codex Security workbench database at
216
251
  `CODEX_SECURITY_STATE_DIR` to place the database elsewhere. Scan credentials
217
252
  are never stored in the scan configuration.
218
253
 
254
+ The scan sandbox permits writes to the selected state directory so SQLite can
255
+ maintain its database and journal files. If the host itself cannot write to the
256
+ default directory, select a writable directory outside the scanned repository:
257
+
258
+ ```bash
259
+ export CODEX_SECURITY_STATE_DIR=/path/to/writable/codex-security-state
260
+ ```
261
+
262
+ Use `findings false-positive OCCURRENCE_ID --reason TEXT` to mark a finding as
263
+ a false positive and explain why. Later scans dismiss a matching finding only
264
+ when the same reason still applies.
265
+
219
266
  `scans rerun SCAN_ID` repeats the original configuration against the current
220
267
  checkout so a fixed vulnerability can be checked again.
221
268
 
@@ -246,7 +293,7 @@ nonzero:
246
293
 
247
294
  ```bash
248
295
  SCAN_ROOT="$(mktemp -d)"
249
- npx codex-security scan . \
296
+ npx @openai/codex-security scan . \
250
297
  --diff origin/main \
251
298
  --output-dir "$SCAN_ROOT/results" \
252
299
  --json \
@@ -264,7 +311,7 @@ document. CSV uses the portable findings columns, marks findings as open, and
264
311
  does not include local workbench triage state. The exporter validates the seal
265
312
  before writing, accepts `--output -` for stdout, and can use
266
313
  `--source-root /path/to/repository` with SARIF to add source-line fingerprints.
267
- Run `npx codex-security export --help` for all export options.
314
+ Run `npx @openai/codex-security export --help` for all export options.
268
315
 
269
316
  Use `validate` to run the bundled validation skill on candidate findings and
270
317
  `patch` to run the bundled fix-finding skill on security issues. Each positional
@@ -272,9 +319,9 @@ input can be either a file, whose contents are read into the request, or literal
272
319
  text. Both commands operate on the current directory, use the scan model
273
320
  and reasoning defaults, ignore unrelated user configuration and plugins, and
274
321
  print the final response without the underlying Codex event stream. Override
275
- the model or reasoning effort with `--codex 'model="gpt-5.6-sol"'` or
276
- `--codex 'model_reasoning_effort="high"'`. Inputs are limited to 64 items and
277
- 1 MiB total.
322
+ the model with `--codex 'model="gpt-5.6-sol"'` and the reasoning effort with
323
+ `--effort high` or `--codex 'model_reasoning_effort="high"'`. Inputs are
324
+ limited to 64 items and 1 MiB total.
278
325
 
279
326
  Canonical scan documents are limited to 16 MiB for the manifest, 128 MiB for
280
327
  findings, and 32 MiB for coverage. Oversized scans are rejected before sealing.
@@ -291,10 +338,11 @@ method and, for an environment API key, its variable name. Authentication and
291
338
  model access remain unverified until a real scan starts.
292
339
 
293
340
  Scan progress identifies the selected credential source before Codex starts.
294
- Interactive terminals also show how to retry with ChatGPT when an environment
295
- API key overrides the stored sign-in. Progress remains on stderr so JSON output
296
- stays machine readable. Recoverable failures include safe retry causes and,
297
- when available, the server-provided retry delay.
341
+ Terminals and noninteractive CI logs also show how to retry with
342
+ `--auth chatgpt` when an environment API key overrides the stored sign-in.
343
+ Progress remains on stderr so JSON output stays machine readable. Network
344
+ failures and rate limits remain retryable; definitive authentication and model
345
+ authorization failures stop immediately.
298
346
 
299
347
  ## Documentation and security
300
348
 
Binary file
@@ -19,7 +19,7 @@ except ModuleNotFoundError: # pragma: no cover - Python 3.10 only
19
19
 
20
20
  PLUGIN_ROOT = Path(__file__).resolve().parents[1]
21
21
  DEFAULT_REGISTRY = PLUGIN_ROOT / "preflight" / "capability-profiles.toml"
22
- DEFAULT_CODEX_HOME = Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
22
+ DEFAULT_CODEX_HOME = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
23
23
  SYSTEM_CONFIG = Path("/etc/codex/config.toml")
24
24
  DEFAULT_CONFIG = DEFAULT_CODEX_HOME / "config.toml"
25
25
  VALID_SEVERITIES = {"block", "warn", "suggest"}
@@ -136,6 +136,9 @@ def parse_args(description: str) -> argparse.Namespace:
136
136
  get_scan.add_argument("--scan-id", required=True)
137
137
  get_scan.add_argument("--occurrence-id")
138
138
 
139
+ get_scan_feedback = subparsers.add_parser("get-scan-feedback")
140
+ get_scan_feedback.add_argument("--scan-id", required=True)
141
+
139
142
  list_scans = subparsers.add_parser("list-scans")
140
143
  list_scans.add_argument("--query")
141
144
  list_scans.add_argument("--target-id")
@@ -155,6 +158,8 @@ def parse_args(description: str) -> argparse.Namespace:
155
158
  register_cli_scan.add_argument("--repository", required=True)
156
159
  register_cli_scan.add_argument("--recipe-json", required=True)
157
160
  register_cli_scan.add_argument("--parent-scan-id")
161
+ register_cli_scan.add_argument("--archive-existing", action="store_true")
162
+ register_cli_scan.add_argument("--archived-scan-dir")
158
163
 
159
164
  get_scan_recipe = subparsers.add_parser("get-scan-recipe")
160
165
  get_scan_recipe.add_argument("--scan-id", required=True)
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env python3
2
- """Persist Codex Security workbench state in a local SQLite database."""
2
+ """Codex Security workbench persistence."""
3
3
 
4
4
  from __future__ import annotations
5
5
 
@@ -32,7 +32,7 @@ try:
32
32
  except ModuleNotFoundError: # pragma: no cover - msvcrt is only available on Windows.
33
33
  windows_file_lock = None
34
34
 
35
- # Some plugin hosts launch Python with safe-path isolation enabled.
35
+ # Plugin hosts may enable safe-path isolation.
36
36
  sys.path.insert(0, str(Path(__file__).resolve().parent))
37
37
  import deep_scan_workbench as deep_scan
38
38
  import workbench_native_indexes as native_indexes
@@ -40,7 +40,9 @@ import workbench_progress as progress
40
40
  import workbench_remediation as remediation
41
41
  import workbench_scan_history as scan_history
42
42
  from filesystem_identity import serialize_filesystem_identity as serialize_filesystem_identity
43
- from filesystem_identity import stored_filesystem_identity_matches
43
+ from filesystem_identity import (
44
+ stored_filesystem_identity_matches as stored_filesystem_identity_matches,
45
+ )
44
46
  from finalize_scan_contract import (
45
47
  PRODUCER_NAME,
46
48
  ContractError,
@@ -76,7 +78,9 @@ from workbench_constants import (
76
78
  PATCH_PREVIEW_BYTES,
77
79
  SQLITE_RETRY_ATTEMPTS,
78
80
  )
81
+ from workbench_feedback import get_scan_feedback
79
82
  from workbench_scan_start import (
83
+ archive_scan,
80
84
  compact_timestamp,
81
85
  insert_running_scan,
82
86
  safe_segment,
@@ -97,6 +101,10 @@ from workbench_target import (
97
101
  git_submodule_paths,
98
102
  git_target_metadata,
99
103
  git_worktree_context,
104
+ require_git_worktree_head,
105
+ require_remediation_target,
106
+ require_scan_target_identity,
107
+ scan_target_warning,
100
108
  worktree_content_digest,
101
109
  worktree_content_digest_for_context,
102
110
  )
@@ -107,6 +115,7 @@ from workbench_validation import (
107
115
  capability_preflight_json,
108
116
  optional_text,
109
117
  parse_scan_cost,
118
+ require_close_reason,
110
119
  require_occurrence,
111
120
  require_uuid,
112
121
  )
@@ -190,8 +199,7 @@ def acquire_completion_file_lock(descriptor: int) -> None:
190
199
  if windows_file_lock is None:
191
200
  raise SystemExit("Scan completion requires operating-system file locking support.")
192
201
 
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.
202
+ # Retry seeding and locking the first byte.
195
203
  while os.fstat(descriptor).st_size == 0:
196
204
  os.lseek(descriptor, 0, os.SEEK_SET)
197
205
  try:
@@ -324,49 +332,6 @@ def require_target(value: str) -> Path:
324
332
  return target
325
333
 
326
334
 
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
335
  def inspect_target(target_path: str) -> dict[str, Any]:
371
336
  target = require_target(target_path)
372
337
  return {
@@ -509,13 +474,6 @@ def inspect_setup(args: argparse.Namespace) -> dict[str, Any]:
509
474
  )
510
475
 
511
476
 
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
477
  def require_review_changes_target(target: Path) -> str:
520
478
  revision = require_git_worktree_head(target)
521
479
  repository_root = git_output(target, "rev-parse", "--show-toplevel")
@@ -1371,42 +1329,6 @@ def start_prompt_only_scan(
1371
1329
  return {**scan_context(connection, scan_id), "startDisposition": "created"}
1372
1330
 
1373
1331
 
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
1332
  def scan_local_file_digest(scan_dir: Path, relative_path: str) -> str:
1411
1333
  digest = hashlib.sha256()
1412
1334
  with open_scan_local_file(scan_dir, relative_path) as source:
@@ -1490,7 +1412,10 @@ def complete_scan_locked(
1490
1412
  )
1491
1413
  if scan["recipe_json"] is None:
1492
1414
  deep_scan.require_deep_scan_ready_for_parent_completion(connection, scan)
1493
- require_unchanged_target(scan)
1415
+ warnings = []
1416
+ warning = scan_target_warning(scan)
1417
+ if warning is not None:
1418
+ warnings.append(warning)
1494
1419
  scan_dir = require_canonical_scan_directory(Path(scan["scan_dir"]))
1495
1420
  completion_timestamp = now()
1496
1421
  completion_binding = workbench_completion_binding(scan, completion_timestamp)
@@ -1506,8 +1431,9 @@ def complete_scan_locked(
1506
1431
  expected_coverage_mode=expected_coverage_mode(scan),
1507
1432
  completion_binding=completion_binding,
1508
1433
  )
1509
- # Keep the second target check between in-memory finalization and the first write.
1510
- require_unchanged_target(scan)
1434
+ warning = scan_target_warning(scan)
1435
+ if warning is not None and warning not in warnings:
1436
+ warnings.append(warning)
1511
1437
  manifest, findings, _ = _write_prepared_scan_finalization(prepared)
1512
1438
  except ContractError as exc:
1513
1439
  raise SystemExit(str(exc)) from exc
@@ -1556,10 +1482,17 @@ def complete_scan_locked(
1556
1482
  """
1557
1483
  UPDATE scans
1558
1484
  SET status = 'complete', phase = 'reporting', completed_at = ?, updated_at = ?,
1559
- seal_manifest_digest = ?, cost_json = ?
1485
+ seal_manifest_digest = ?, cost_json = ?, completion_warnings_json = ?
1560
1486
  WHERE id = ? AND status = 'running'
1561
1487
  """,
1562
- (timestamp, timestamp, manifest_digest, cost_json, scan["id"]),
1488
+ (
1489
+ timestamp,
1490
+ timestamp,
1491
+ manifest_digest,
1492
+ cost_json,
1493
+ json.dumps(warnings),
1494
+ scan["id"],
1495
+ ),
1563
1496
  )
1564
1497
  if updated.rowcount != 1:
1565
1498
  raise SystemExit("Only a running scan can be completed.")
@@ -1620,6 +1553,7 @@ def register_cli_scan(connection: sqlite3.Connection, args: argparse.Namespace)
1620
1553
 
1621
1554
  connection.execute("BEGIN IMMEDIATE")
1622
1555
  try:
1556
+ archive_scan(connection, args, scan_dir, timestamp, require_canonical_scan_directory)
1623
1557
  target_id = ensure_security_target(connection, str(repository))
1624
1558
  if parent_scan_id is not None:
1625
1559
  parent = require_scan(connection, parent_scan_id)
@@ -1853,8 +1787,7 @@ def set_finding_triage(connection: sqlite3.Connection, args: argparse.Namespace)
1853
1787
  if args.status == "closed" and close_reason is None:
1854
1788
  raise SystemExit("Choose why this finding is being closed.")
1855
1789
  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.")
1790
+ require_close_reason(close_reason, note)
1858
1791
  connection.execute("BEGIN IMMEDIATE")
1859
1792
  try:
1860
1793
  timestamp = now()
@@ -3072,6 +3005,7 @@ def scan_result(
3072
3005
  finding_management_updated_at(connection, scan["id"]) or "",
3073
3006
  ),
3074
3007
  "userContext": scan["user_context"],
3008
+ "warnings": json.loads(scan["completion_warnings_json"]),
3075
3009
  }
3076
3010
 
3077
3011
 
@@ -3608,6 +3542,8 @@ def main() -> None:
3608
3542
  result = deep_scan.fail_deep_scan(connection, args)
3609
3543
  elif args.command == "get-scan":
3610
3544
  result = scan_context(connection, args.scan_id, args.occurrence_id)
3545
+ elif args.command == "get-scan-feedback":
3546
+ result = get_scan_feedback(connection, require_scan(connection, args.scan_id))
3611
3547
  elif args.command == "list-scans":
3612
3548
  result = scan_history.list_scans(connection, args)
3613
3549
  elif args.command == "list-unmatched-scan-pairs":
@@ -0,0 +1,96 @@
1
+ """Load reviewed false-positive feedback for a security scan."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import sqlite3
7
+ import sys
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
12
+ from workbench_constants import (
13
+ FINDING_LOCATION_PATH_BYTES,
14
+ FINDING_SUMMARY_BYTES,
15
+ FINDING_TITLE_BYTES,
16
+ )
17
+ from workbench_validation import bounded_output_text
18
+
19
+
20
+ def get_scan_feedback(connection: sqlite3.Connection, scan: sqlite3.Row) -> dict[str, Any]:
21
+ rows = connection.execute(
22
+ """
23
+ WITH ranked_decisions AS (
24
+ SELECT findings.id AS finding_id, findings.fingerprint, findings.rule_id,
25
+ findings.identity_anchor, findings.identity_instance, occurrences.title,
26
+ occurrences.summary, COALESCE(triage.status, 'open') AS triage_status,
27
+ triage.close_reason, triage.note,
28
+ COALESCE(triage.updated_at, source_scans.completed_at) AS updated_at,
29
+ source_scans.id AS source_scan_id,
30
+ source_scans.completed_at AS source_completed_at,
31
+ locations.relative_path, locations.start_line, locations.end_line, locations.role,
32
+ ROW_NUMBER() OVER (
33
+ PARTITION BY findings.id
34
+ ORDER BY COALESCE(triage.updated_at, source_scans.completed_at) DESC,
35
+ source_scans.completed_at DESC,
36
+ source_scans.id DESC, occurrences.id DESC
37
+ ) AS decision_rank
38
+ FROM finding_occurrences AS occurrences
39
+ JOIN findings ON findings.id = occurrences.finding_id
40
+ JOIN scans AS source_scans ON source_scans.id = occurrences.scan_id
41
+ LEFT JOIN finding_triage AS triage ON triage.occurrence_id = occurrences.id
42
+ JOIN finding_locations AS locations ON locations.id = (
43
+ SELECT candidate.id
44
+ FROM finding_locations AS candidate
45
+ WHERE candidate.occurrence_id = occurrences.id
46
+ ORDER BY CASE WHEN candidate.role = 'root_control' THEN 0 ELSE 1 END,
47
+ candidate.sort_order
48
+ LIMIT 1
49
+ )
50
+ WHERE source_scans.target_id = ?
51
+ AND source_scans.id != ?
52
+ AND source_scans.status = 'complete'
53
+ )
54
+ SELECT *
55
+ FROM ranked_decisions
56
+ WHERE decision_rank = 1
57
+ AND triage_status = 'closed'
58
+ AND close_reason = 'false_positive'
59
+ AND note IS NOT NULL
60
+ AND trim(note) != ''
61
+ ORDER BY updated_at DESC, source_completed_at DESC, source_scan_id DESC, finding_id DESC
62
+ LIMIT 50
63
+ """,
64
+ (scan["target_id"], scan["id"]),
65
+ )
66
+ false_positives = []
67
+ for row in rows:
68
+ identity = {"anchor": row["identity_anchor"]}
69
+ if row["identity_instance"] is not None:
70
+ identity["instance"] = row["identity_instance"]
71
+ location = {
72
+ "path": bounded_output_text(row["relative_path"], FINDING_LOCATION_PATH_BYTES),
73
+ "startLine": row["start_line"],
74
+ "endLine": row["end_line"],
75
+ }
76
+ if row["role"] is not None:
77
+ location["role"] = row["role"]
78
+ false_positives.append(
79
+ {
80
+ "findingId": row["finding_id"],
81
+ "fingerprint": row["fingerprint"],
82
+ "ruleId": row["rule_id"],
83
+ "identity": identity,
84
+ "title": bounded_output_text(row["title"], FINDING_TITLE_BYTES),
85
+ "summary": bounded_output_text(row["summary"], FINDING_SUMMARY_BYTES),
86
+ "reason": row["note"],
87
+ "locations": [location],
88
+ "sourceScanId": row["source_scan_id"],
89
+ "updatedAt": row["updated_at"],
90
+ }
91
+ )
92
+ return {"scanId": scan["id"], "targetId": scan["target_id"], "falsePositives": false_positives}
93
+
94
+
95
+ if __name__ == "__main__":
96
+ argparse.ArgumentParser(description=__doc__).parse_args()