@openai/codex-security 0.1.1 → 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.
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,34 +61,34 @@ 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.
88
92
 
89
93
  An environment API key takes precedence over a stored sign-in by default.
90
94
  When both a stored ChatGPT sign-in and an environment API key are available, an
@@ -93,8 +97,8 @@ other noninteractive scans never prompt and retain automatic API-key
93
97
  precedence. Select the credential source explicitly with `--auth`:
94
98
 
95
99
  ```bash
96
- npx codex-security scan . --auth chatgpt
97
- npx codex-security scan . --auth api-key
100
+ npx @openai/codex-security scan . --auth chatgpt
101
+ npx @openai/codex-security scan . --auth api-key
98
102
  ```
99
103
 
100
104
  `--auth chatgpt` uses the stored sign-in and ignores `OPENAI_API_KEY` and
@@ -120,35 +124,40 @@ without printing its value, including when no stored sign-in exists.
120
124
  ## CLI
121
125
 
122
126
  ```bash
123
- npx codex-security scan /path/to/repository
124
- npx codex-security scan /path/to/repository --model gpt-5.6-terra
125
- npx codex-security scan /path/to/repository --path src --path tests
126
- npx codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
127
- npx codex-security scan /path/to/repository --diff origin/main --json
128
- npx codex-security scan /path/to/repository --output-dir /path/outside/repository/results
129
- npx codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing
130
- npx codex-security scan /path/to/repository --dry-run
131
- npx codex-security scan /path/to/repository --fail-on-severity high
132
- npx codex-security scan /path/to/repository --max-cost 5
133
- npx codex-security install-hook
134
- npx codex-security bulk-scan
135
- npx codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4
136
- npx codex-security scans list /path/to/repository
137
- npx codex-security scans list --scan-root /path/outside/repository/results
138
- npx codex-security scans show SCAN_ID
139
- npx codex-security scans rerun SCAN_ID
140
- npx codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
141
- npx codex-security scans match --all
142
- npx codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
143
- npx codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif
144
- npx codex-security export /path/outside/repository/results --export-format csv --output /path/outside/repository/findings.csv
145
- npx codex-security export /path/outside/repository/results --export-format json --output /path/outside/repository/findings.json
146
- npx codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"
147
- 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
148
157
  ```
149
158
 
150
- Run `npx codex-security --version` for the installed CLI version or
151
- `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,
152
161
  default model, reasoning effort, and first-scan command. A scan with `--dry-run`
153
162
  also reports its effective model and reasoning effort, including `--codex`
154
163
  overrides, without starting Codex or contacting the network.
@@ -182,10 +191,11 @@ for a passing policy. Incomplete scans still write the available human or JSON
182
191
  result to stdout and a coverage warning to stderr, including in report-only
183
192
  mode.
184
193
 
185
- Scans use `gpt-5.6-sol` with extra-high reasoning effort by default. Use
186
- `--model gpt-5.6-terra` to switch models. Use repeatable `--codex KEY=VALUE`
187
- options for other Codex settings, such as
188
- `--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.
189
199
 
190
200
  Scan progress identifies the requested paths and reports actual ranking,
191
201
  file-review, validation, and attack-path phases as they become available.
@@ -203,10 +213,10 @@ Use `--max-cost USD` to stop a scan, including its delegated workers, when its
203
213
  running cost exceeds the limit. Partial results are preserved. Requests
204
214
  already in progress can finish above the limit.
205
215
 
206
- 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`
207
217
  for the complete CLI references.
208
218
 
209
- 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
210
220
  GitHub repositories pushed in the last 90 days. Archived
211
221
  repositories and forks are excluded. Search the repository list, select the
212
222
  repositories to scan, and confirm before scanning.
@@ -228,7 +238,7 @@ Results remain under `--output-dir`; rerun the same command to resume.
228
238
 
229
239
  ### Scan history and reruns
230
240
 
231
- `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
232
242
  repository path to inspect another checkout, `--scan-root DIR` to list scans
233
243
  whose artifacts are under a particular root. `scans show SCAN_ID` includes the
234
244
  scan configuration, results, coverage, and artifact locations.
@@ -249,6 +259,10 @@ default directory, select a writable directory outside the scanned repository:
249
259
  export CODEX_SECURITY_STATE_DIR=/path/to/writable/codex-security-state
250
260
  ```
251
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
+
252
266
  `scans rerun SCAN_ID` repeats the original configuration against the current
253
267
  checkout so a fixed vulnerability can be checked again.
254
268
 
@@ -279,7 +293,7 @@ nonzero:
279
293
 
280
294
  ```bash
281
295
  SCAN_ROOT="$(mktemp -d)"
282
- npx codex-security scan . \
296
+ npx @openai/codex-security scan . \
283
297
  --diff origin/main \
284
298
  --output-dir "$SCAN_ROOT/results" \
285
299
  --json \
@@ -297,7 +311,7 @@ document. CSV uses the portable findings columns, marks findings as open, and
297
311
  does not include local workbench triage state. The exporter validates the seal
298
312
  before writing, accepts `--output -` for stdout, and can use
299
313
  `--source-root /path/to/repository` with SARIF to add source-line fingerprints.
300
- Run `npx codex-security export --help` for all export options.
314
+ Run `npx @openai/codex-security export --help` for all export options.
301
315
 
302
316
  Use `validate` to run the bundled validation skill on candidate findings and
303
317
  `patch` to run the bundled fix-finding skill on security issues. Each positional
@@ -305,9 +319,9 @@ input can be either a file, whose contents are read into the request, or literal
305
319
  text. Both commands operate on the current directory, use the scan model
306
320
  and reasoning defaults, ignore unrelated user configuration and plugins, and
307
321
  print the final response without the underlying Codex event stream. Override
308
- the model or reasoning effort with `--codex 'model="gpt-5.6-sol"'` or
309
- `--codex 'model_reasoning_effort="high"'`. Inputs are limited to 64 items and
310
- 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.
311
325
 
312
326
  Canonical scan documents are limited to 16 MiB for the manifest, 128 MiB for
313
327
  findings, and 32 MiB for coverage. Oversized scans are rejected before sealing.
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()
@@ -85,7 +85,7 @@ def list_workspace_scans(
85
85
  """
86
86
  SELECT id, mode, status, phase, scope, target_revision,
87
87
  seal_manifest_digest, started_at, completed_at, canceled_at,
88
- updated_at, failure_message
88
+ updated_at, failure_message, completion_warnings_json
89
89
  FROM scans
90
90
  WHERE workspace_id = ?
91
91
  ORDER BY created_at DESC, id DESC
@@ -112,6 +112,11 @@ def list_workspace_scans(
112
112
  "status": "canceled" if row["canceled_at"] else row["status"],
113
113
  "targetRevision": row["target_revision"],
114
114
  "updatedAt": row["updated_at"],
115
+ **(
116
+ {"warnings": json.loads(row["completion_warnings_json"])}
117
+ if row["completion_warnings_json"] != "[]"
118
+ else {}
119
+ ),
115
120
  }
116
121
  for row in rows
117
122
  ],
@@ -242,6 +247,11 @@ def list_scans(
242
247
  "targetRevision": row["target_revision"],
243
248
  "targetSummary": row["target_summary"],
244
249
  "updatedAt": max(row["updated_at"], row["progress_updated_at"]),
250
+ **(
251
+ {"warnings": json.loads(row["completion_warnings_json"])}
252
+ if row["completion_warnings_json"] != "[]"
253
+ else {}
254
+ ),
245
255
  }
246
256
  for row in rows[:limit]
247
257
  ]