@openai/codex-security 0.1.10 → 0.1.11

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 (55) hide show
  1. package/README.md +27 -13
  2. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  3. package/_bundled_plugin/.mcp.json +3 -1
  4. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  6. package/_bundled_plugin/scripts/deep_scan_config.py +21 -1
  7. package/_bundled_plugin/scripts/deep_scan_workbench.py +44 -14
  8. package/_bundled_plugin/scripts/finalize_scan_contract.py +15 -207
  9. package/_bundled_plugin/scripts/generate_in_scope_files.py +40 -16
  10. package/_bundled_plugin/scripts/generate_rank_input.py +38 -5
  11. package/_bundled_plugin/scripts/rank_preview.py +4 -0
  12. package/_bundled_plugin/scripts/report_projection.py +39 -1
  13. package/_bundled_plugin/scripts/workbench_cli.py +5 -0
  14. package/_bundled_plugin/scripts/workbench_db.py +283 -4
  15. package/_bundled_plugin/scripts/workbench_schema.py +15 -0
  16. package/_bundled_plugin/scripts/workbench_source_excerpt.py +1 -5
  17. package/_bundled_plugin/scripts/workbench_target.py +82 -0
  18. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +5 -3
  19. package/dist/api.d.ts +1 -0
  20. package/dist/api.d.ts.map +1 -1
  21. package/dist/api.js +217 -92
  22. package/dist/api.js.map +1 -1
  23. package/dist/auth.d.ts +2 -3
  24. package/dist/auth.d.ts.map +1 -1
  25. package/dist/auth.js +59 -270
  26. package/dist/auth.js.map +1 -1
  27. package/dist/cli.d.ts.map +1 -1
  28. package/dist/cli.js +14 -4
  29. package/dist/cli.js.map +1 -1
  30. package/dist/contract.js +7 -5
  31. package/dist/contract.js.map +1 -1
  32. package/dist/cost.d.ts +1 -0
  33. package/dist/cost.d.ts.map +1 -1
  34. package/dist/cost.js +23 -1
  35. package/dist/cost.js.map +1 -1
  36. package/dist/knowledge-base.d.ts.map +1 -1
  37. package/dist/knowledge-base.js +2 -1
  38. package/dist/knowledge-base.js.map +1 -1
  39. package/dist/multiscan.d.ts.map +1 -1
  40. package/dist/multiscan.js +1 -0
  41. package/dist/multiscan.js.map +1 -1
  42. package/dist/runtime.d.ts +9 -6
  43. package/dist/runtime.d.ts.map +1 -1
  44. package/dist/runtime.js +127 -284
  45. package/dist/runtime.js.map +1 -1
  46. package/dist/scan-comparison.js +1 -1
  47. package/dist/scan-comparison.js.map +1 -1
  48. package/dist/targets.d.ts +1 -0
  49. package/dist/targets.d.ts.map +1 -1
  50. package/dist/targets.js +22 -0
  51. package/dist/targets.js.map +1 -1
  52. package/dist/version.d.ts +1 -1
  53. package/dist/version.js +1 -1
  54. package/dist/version.js.map +1 -1
  55. package/package.json +2 -2
package/README.md CHANGED
@@ -83,6 +83,7 @@ Pass scan configuration to `security.run(repository, options)` or
83
83
  | `outputDir` | Choose an artifact directory outside the enclosing Git worktree. |
84
84
  | `archiveExisting` | Archive results already in `outputDir` before starting a scan. |
85
85
  | `maxCostUsd` | Stop after the estimated model cost exceeds a positive USD amount. |
86
+ | `maxTimeHours` | Limit deep-scan discovery to a positive number of hours, up to 96. |
86
87
  | `failureSeverity` | Record a finding-severity policy in the saved scan recipe. |
87
88
  | `parentScanId` | Link a rerun to an existing parent scan. |
88
89
  | `expectedPluginVersion` | Require the original plugin version when replaying a scan. |
@@ -212,7 +213,7 @@ npx @openai/codex-security scan /path/to/repository --verbose
212
213
  npx @openai/codex-security scan /path/to/repository --dry-run
213
214
  npx @openai/codex-security scan /path/to/repository --fail-on-severity high
214
215
  npx @openai/codex-security scan /path/to/repository --max-cost 5
215
- npx @openai/codex-security scan /path/to/repository --mode deep --workers 2 --subagents 0 --stop-after-no-new 3 --max-discovery-runs 10
216
+ npx @openai/codex-security scan /path/to/repository --mode deep --workers 2 --subagents 0 --stop-after-no-new 3 --max-discovery-runs 10 --max-time-hours 1.5
216
217
  npx @openai/codex-security install-hook
217
218
  npx @openai/codex-security bulk-scan
218
219
  npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high
@@ -263,8 +264,9 @@ Markdown, text, PDF, and Word (`.docx`) files.
263
264
 
264
265
  For `scan --mode deep`, `--workers` limits concurrent discovery workers,
265
266
  `--subagents` controls each worker's subagents, `--stop-after-no-new` stops after
266
- that many runs find no new issues, and `--max-discovery-runs` limits total runs.
267
- These options are also available on SDK scans:
267
+ that many runs find no new issues, `--max-discovery-runs` limits total runs, and
268
+ `--max-time-hours` limits discovery duration. These options are also available
269
+ on SDK scans:
268
270
 
269
271
  ```ts
270
272
  await security.run("/path/to/repository", {
@@ -273,6 +275,7 @@ await security.run("/path/to/repository", {
273
275
  subagents: 0,
274
276
  stopAfterNoNew: 3,
275
277
  maxDiscoveryRuns: 10,
278
+ maxTimeHours: 1.5,
276
279
  });
277
280
  ```
278
281
 
@@ -285,8 +288,15 @@ workers = 2
285
288
  subagents = 0
286
289
  stop_after_no_new = 3
287
290
  max_discovery_runs = 10
291
+ max_time_hours = 1.5
288
292
  ```
289
293
 
294
+ The discovery deadline defaults to 96 hours. The configured value may be any
295
+ positive number, including fractional hours, up to 96. At the deadline,
296
+ in-flight discovery stops and completed findings are reduced and returned.
297
+ The 97-hour outer tool-call timeout reserves approximately one hour for final
298
+ reduction and result delivery, including at the 96-hour maximum.
299
+
290
300
  `scan --workers` controls discovery workers within one deep scan;
291
301
  `bulk-scan --workers` controls how many repositories are scanned concurrently.
292
302
 
@@ -382,22 +392,22 @@ workers = "auto"
382
392
  subagents = 3
383
393
  stop_after_no_new = 6
384
394
  max_discovery_runs = 60
395
+ max_time_hours = 96
385
396
  ```
386
397
 
387
398
  `workers = "auto"` uses half the available parallelism, with a minimum of one
388
399
  and a maximum of six discovery workers. Set `workers` to a positive integer to
389
400
  choose an explicit count. `subagents` must be a nonnegative integer;
390
- `stop_after_no_new` and `max_discovery_runs` must be positive integers. Unknown
391
- `[deep_scan]` keys are rejected.
401
+ `stop_after_no_new` and `max_discovery_runs` must be positive integers.
402
+ `max_time_hours` must be a positive finite number no greater than 96; fractional
403
+ hours are supported. Unknown `[deep_scan]` keys are rejected.
392
404
 
393
405
  These settings are separate from Codex's
394
406
  `features.multi_agent_v2.max_concurrent_threads_per_session` and
395
- `bulk-scan --workers`. Importantly, standalone CLI and SDK scans create an
396
- isolated `CODEX_HOME` and do not import the ambient deep-scan configuration
397
- file. Consequently, `scan --mode deep` currently uses the deep engine's
398
- defaults; there are no standalone CLI flags for these four settings. Use
399
- `--codex` to adjust the Codex session thread limit, not to set `[deep_scan]`
400
- values.
407
+ `bulk-scan --workers`. Standalone CLI and SDK scans create an isolated
408
+ `CODEX_HOME`, import the ambient `[deep_scan]` configuration, and apply explicit
409
+ CLI or SDK options on top. Use `--codex` to adjust the Codex session thread
410
+ limit, not to set `[deep_scan]` values.
401
411
 
402
412
  ### Environment variables
403
413
 
@@ -410,6 +420,7 @@ The CLI and SDK recognize the following user-configurable environment:
410
420
  | `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
411
421
  | `CODEX_SECURITY_STATE_DIR` | Override the private scan-history, workbench, and default artifact directory. |
412
422
  | `CODEX_HOME` | Set the ambient Codex home for file-backed sign-in and default state; defaults to `~/.codex`. |
423
+ | `CODEX_CLI_PATH` | Use another Codex executable for authentication, plugin setup, scans, and nested workers. |
413
424
  | `PYTHON` | Select a Python interpreter when `--python` or SDK `pythonPath` is not set. |
414
425
  | `GH_HOST` | Select a GitHub Enterprise host during interactive `bulk-scan` discovery. |
415
426
  | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices when either variable is defined. |
@@ -470,8 +481,11 @@ scan history, and bulk-scan receipt. Estimates use
470
481
  including cached input and cache writes; fees and surcharges are not included.
471
482
 
472
483
  Use `--max-cost USD` to stop a scan, including its delegated workers, when its
473
- running cost exceeds the limit. Partial results are preserved. Requests
474
- already in progress can finish above the limit.
484
+ running cost exceeds the limit. If a Deep Scan has already finished discovery,
485
+ it returns a sealed partial report with any completed findings and lists
486
+ unvalidated candidates as follow-up work. Requests already in progress can
487
+ finish above the limit; preparing the partial report makes no additional model
488
+ requests. Incomplete coverage retains its existing exit code.
475
489
 
476
490
  Run `npx @openai/codex-security scan --help` or `npx @openai/codex-security bulk-scan --help`
477
491
  for the complete CLI references.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-security",
3
- "version": "0.1.17",
3
+ "version": "0.1.19",
4
4
  "description": "Codex Security workflows for security scans, analysis, and investigation.",
5
5
  "author": {
6
6
  "name": "OpenAI"
@@ -9,6 +9,8 @@
9
9
  "CODEX_SQLITE_HOME",
10
10
  "CODEX_API_KEY",
11
11
  "CODEX_CLI_PATH",
12
+ "OPENROUTER_API_KEY",
13
+ "FIREWORKS_API_KEY",
12
14
  "AWS_BEARER_TOKEN_BEDROCK",
13
15
  "AWS_ACCESS_KEY_ID",
14
16
  "AWS_SECRET_ACCESS_KEY",
@@ -37,7 +39,7 @@
37
39
  "REQUESTS_CA_BUNDLE",
38
40
  "NODE_EXTRA_CA_CERTS"
39
41
  ],
40
- "tool_timeout_sec": 86400
42
+ "tool_timeout_sec": 349200
41
43
  }
42
44
  }
43
45
  }
@@ -3,6 +3,7 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import argparse
6
+ import math
6
7
  import os
7
8
  from pathlib import Path
8
9
  from typing import Any
@@ -16,6 +17,8 @@ DEFAULT_SUBAGENTS = 3
16
17
  DEFAULT_STOP_AFTER_NO_NEW = 6
17
18
  DEFAULT_STOP_AFTER_CONSECUTIVE_ERRORS = 3
18
19
  DEFAULT_MAX_DISCOVERY_RUNS = 60
20
+ DEFAULT_MAX_TIME_HOURS = 96
21
+ MAX_TIME_HOURS = 96
19
22
  MAX_AUTOMATIC_WORKERS = 6
20
23
  CONFIG_KEYS = {
21
24
  "workers",
@@ -23,6 +26,7 @@ CONFIG_KEYS = {
23
26
  "stop_after_no_new",
24
27
  "stop_after_consecutive_errors",
25
28
  "max_discovery_runs",
29
+ "max_time_hours",
26
30
  }
27
31
 
28
32
 
@@ -34,7 +38,7 @@ def config_path() -> Path:
34
38
  return codex_home() / "codex-security" / "config.toml"
35
39
 
36
40
 
37
- def resolve_deep_scan_config(available_parallelism: int) -> dict[str, int]:
41
+ def resolve_deep_scan_config(available_parallelism: int) -> dict[str, int | float]:
38
42
  if isinstance(available_parallelism, bool) or available_parallelism < 1:
39
43
  raise SystemExit("Available parallelism must be a positive integer.")
40
44
  path = config_path()
@@ -87,6 +91,10 @@ def resolve_deep_scan_config(available_parallelism: int) -> dict[str, int]:
87
91
  "deep_scan.max_discovery_runs",
88
92
  minimum=1,
89
93
  ),
94
+ "maxTimeHours": require_positive_number(
95
+ configured.get("max_time_hours", DEFAULT_MAX_TIME_HOURS),
96
+ "deep_scan.max_time_hours",
97
+ ),
90
98
  }
91
99
 
92
100
 
@@ -103,6 +111,18 @@ def require_integer(value: object, label: str, *, minimum: int) -> int:
103
111
  return value
104
112
 
105
113
 
114
+ def require_positive_number(value: object, label: str) -> int | float:
115
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
116
+ raise SystemExit(f"{label} must be a positive finite number no greater than 96.")
117
+ try:
118
+ finite = math.isfinite(value)
119
+ except OverflowError:
120
+ finite = False
121
+ if not finite or value <= 0 or value > MAX_TIME_HOURS:
122
+ raise SystemExit(f"{label} must be a positive finite number no greater than 96.")
123
+ return value
124
+
125
+
106
126
  def main() -> None:
107
127
  parser = argparse.ArgumentParser(description=__doc__)
108
128
  parser.add_argument("--available-parallelism", type=int, required=True)
@@ -217,6 +217,11 @@ def require_deep_scan_run(connection: sqlite3.Connection, scan_id: str) -> sqlit
217
217
  return row
218
218
 
219
219
 
220
+ def deep_scan_deadline_reached(run: sqlite3.Row) -> bool:
221
+ elapsed = datetime.fromisoformat(now()) - datetime.fromisoformat(str(run["created_at"]))
222
+ return elapsed.total_seconds() / 3600 >= run["max_time_hours"]
223
+
224
+
220
225
  def require_deep_scan_ready_for_parent_completion(
221
226
  connection: sqlite3.Connection, scan: sqlite3.Row
222
227
  ) -> None:
@@ -361,6 +366,23 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, A
361
366
  """,
362
367
  (run["scan_id"],),
363
368
  ).fetchone()
369
+ canonical_artifacts = None
370
+ if run["canonical_inventory_path"] is None:
371
+ if successful_reducer is not None:
372
+ canonical_artifacts = canonical_discovery_artifacts(scan)
373
+ elif (
374
+ run["status"] == "succeeded"
375
+ and run["terminal_reason"] == "capped"
376
+ and run["completion_sequence"] == 0
377
+ and deep_scan_deadline_reached(run)
378
+ ):
379
+ candidate_artifacts = canonical_discovery_artifacts(scan)
380
+ if Path(candidate_artifacts["candidateLedgerPath"]).stat().st_size != 0:
381
+ raise SystemExit(
382
+ "A capped Deep Scan without completed discoveries requires an empty "
383
+ "candidate ledger."
384
+ )
385
+ canonical_artifacts = candidate_artifacts
364
386
  return {
365
387
  "scanId": run["scan_id"],
366
388
  "targetPath": scan["target_path"],
@@ -378,17 +400,14 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, A
378
400
  "stopAfterNoNew": run["stop_after_no_new"],
379
401
  "stopAfterConsecutiveErrors": run["stop_after_consecutive_errors"],
380
402
  "maxDiscoveryRuns": run["max_discovery_runs"],
403
+ "maxTimeHours": run["max_time_hours"],
381
404
  },
382
405
  "dispatchedCount": run["discovery_runs_dispatched"],
383
406
  "completionSequence": run["completion_sequence"],
384
407
  "noNewStreak": run["consecutive_no_new"],
385
408
  "consecutiveErrors": run["consecutive_errors"],
386
409
  "cancelRequested": bool(run["cancel_requested"]),
387
- "canonicalArtifacts": (
388
- canonical_discovery_artifacts(scan)
389
- if successful_reducer is not None and run["canonical_inventory_path"] is None
390
- else None
391
- ),
410
+ "canonicalArtifacts": canonical_artifacts,
392
411
  "manifestPath": run["manifest_path"],
393
412
  "terminalReason": run["terminal_reason"],
394
413
  "error": run["error_message"],
@@ -466,7 +485,7 @@ def deep_scan_result(
466
485
  return result
467
486
 
468
487
 
469
- def effective_deep_scan_config(args: argparse.Namespace) -> dict[str, int]:
488
+ def effective_deep_scan_config(args: argparse.Namespace) -> dict[str, int | float]:
470
489
  available_parallelism = args.available_parallelism or os.cpu_count() or 1
471
490
  return resolve_deep_scan_config(available_parallelism)
472
491
 
@@ -474,7 +493,7 @@ def effective_deep_scan_config(args: argparse.Namespace) -> dict[str, int]:
474
493
  def ensure_deep_scan_run(
475
494
  connection: sqlite3.Connection,
476
495
  scan: sqlite3.Row,
477
- config: dict[str, int],
496
+ config: dict[str, int | float],
478
497
  workflow_version: str,
479
498
  timestamp: str,
480
499
  ) -> sqlite3.Row:
@@ -492,9 +511,9 @@ def ensure_deep_scan_run(
492
511
  INSERT INTO deep_scan_runs (
493
512
  scan_id, schema_version, workflow_version, status, phase,
494
513
  workers, subagents, stop_after_no_new, stop_after_consecutive_errors,
495
- max_discovery_runs,
514
+ max_discovery_runs, max_time_hours,
496
515
  created_at, updated_at
497
- ) VALUES (?, 1, ?, 'running', 'setup', ?, ?, ?, ?, ?, ?, ?)
516
+ ) VALUES (?, 1, ?, 'running', 'setup', ?, ?, ?, ?, ?, ?, ?, ?)
498
517
  """,
499
518
  (
500
519
  scan["id"],
@@ -504,6 +523,7 @@ def ensure_deep_scan_run(
504
523
  config["stopAfterNoNew"],
505
524
  config["stopAfterConsecutiveErrors"],
506
525
  config["maxDiscoveryRuns"],
526
+ config["maxTimeHours"],
507
527
  timestamp,
508
528
  timestamp,
509
529
  ),
@@ -1404,9 +1424,12 @@ def claim_deep_scan_dedup(
1404
1424
  "A Deep Scan dedup worker must claim an ordered prefix of buffered discovery "
1405
1425
  "results in completion order."
1406
1426
  )
1407
- hard_cap_singleton = (
1427
+ capped_singleton = (
1408
1428
  len(input_ids) == 1
1409
- and run["discovery_runs_dispatched"] >= run["max_discovery_runs"]
1429
+ and (
1430
+ run["discovery_runs_dispatched"] >= run["max_discovery_runs"]
1431
+ or deep_scan_deadline_reached(run)
1432
+ )
1410
1433
  and connection.execute(
1411
1434
  """
1412
1435
  SELECT 1 FROM deep_scan_workers
@@ -1425,7 +1448,7 @@ def claim_deep_scan_dedup(
1425
1448
  """,
1426
1449
  (scan_id,),
1427
1450
  ).fetchone()
1428
- minimum_inputs = 1 if successful_reducer is not None or hard_cap_singleton else 2
1451
+ minimum_inputs = 1 if successful_reducer is not None or capped_singleton else 2
1429
1452
  if len(input_ids) < minimum_inputs:
1430
1453
  raise SystemExit(
1431
1454
  "The first Deep Scan dedup requires two buffered discovery results."
@@ -1679,12 +1702,13 @@ def finish_deep_scan_locked(
1679
1702
  if (
1680
1703
  args.terminal_reason == "capped"
1681
1704
  and run["discovery_runs_dispatched"] < run["max_discovery_runs"]
1705
+ and not deep_scan_deadline_reached(run)
1682
1706
  ):
1683
1707
  raise SystemExit(
1684
1708
  "Deep Scan cannot finish capped before reaching its configured maximum."
1685
1709
  )
1686
1710
  try:
1687
- canonical_discovery_artifacts(scan)
1711
+ canonical_artifacts = canonical_discovery_artifacts(scan)
1688
1712
  except SystemExit as exc:
1689
1713
  raise SystemExit(
1690
1714
  f"Deep Scan cannot finish without canonical discovery artifacts: {exc}"
@@ -1697,7 +1721,13 @@ def finish_deep_scan_locked(
1697
1721
  """,
1698
1722
  (scan_id,),
1699
1723
  ).fetchone()
1700
- if successful_reducer is None:
1724
+ zero_discovery_deadline = (
1725
+ args.terminal_reason == "capped"
1726
+ and deep_scan_deadline_reached(run)
1727
+ and run["completion_sequence"] == 0
1728
+ and Path(canonical_artifacts["candidateLedgerPath"]).stat().st_size == 0
1729
+ )
1730
+ if successful_reducer is None and not zero_discovery_deadline:
1701
1731
  raise SystemExit("Deep Scan cannot finish without a successful dedup worker.")
1702
1732
  failed_worker = connection.execute(
1703
1733
  """