@openai/codex-security 0.3.0 → 0.5.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 (244) hide show
  1. package/README.md +45 -9
  2. package/_bundled_plugin/.codex-plugin/plugin.json +5 -5
  3. package/_bundled_plugin/.mcp.json +1 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  6. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  7. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +13 -20
  8. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  9. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  10. package/_bundled_plugin/references/core-scan.md +2 -0
  11. package/_bundled_plugin/references/final-report.md +5 -1
  12. package/_bundled_plugin/references/investigation-time-budget.md +11 -0
  13. package/_bundled_plugin/references/sarif-adapter.md +1 -0
  14. package/_bundled_plugin/references/scan-prologue.md +2 -6
  15. package/_bundled_plugin/references/scan-runtime.md +15 -0
  16. package/_bundled_plugin/references/threat-model.md +2 -0
  17. package/_bundled_plugin/schemas/coverage.schema.json +45 -126
  18. package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +5 -1
  19. package/_bundled_plugin/schemas/findings.schema.json +140 -427
  20. package/_bundled_plugin/schemas/patch-risk-assessment.schema.json +106 -119
  21. package/_bundled_plugin/schemas/scan-manifest.schema.json +73 -188
  22. package/_bundled_plugin/scripts/deep_scan_workbench.py +7 -0
  23. package/_bundled_plugin/scripts/finalize_scan_contract.py +87 -49
  24. package/_bundled_plugin/scripts/finding_preview.py +5 -3
  25. package/_bundled_plugin/scripts/generate_rank_input.py +26 -106
  26. package/_bundled_plugin/scripts/launch_codex_security_mcp +39 -4
  27. package/_bundled_plugin/scripts/report_projection.py +35 -13
  28. package/_bundled_plugin/scripts/snapshot_sqlite.py +7 -0
  29. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -1
  30. package/_bundled_plugin/scripts/workbench_cli.py +9 -9
  31. package/_bundled_plugin/scripts/workbench_constants.py +4 -0
  32. package/_bundled_plugin/scripts/workbench_db.py +103 -45
  33. package/_bundled_plugin/scripts/workbench_progress.py +0 -50
  34. package/_bundled_plugin/scripts/workbench_publication.py +216 -247
  35. package/_bundled_plugin/scripts/workbench_scan_history.py +3 -2
  36. package/_bundled_plugin/scripts/workbench_scan_start.py +12 -4
  37. package/_bundled_plugin/scripts/workbench_scan_usage.py +360 -37
  38. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  39. package/_bundled_plugin/scripts/workbench_source_excerpt.py +74 -51
  40. package/_bundled_plugin/scripts/workbench_source_scopes.py +388 -0
  41. package/_bundled_plugin/scripts/workbench_target.py +7 -5
  42. package/_bundled_plugin/scripts/workbench_validation.py +52 -2
  43. package/_bundled_plugin/shared/workbench-history-repairs.json +19 -0
  44. package/_bundled_plugin/shared/workbench-migrations.json +22 -0
  45. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +1 -1
  46. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +1 -1
  47. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +4 -2
  48. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +1 -1
  49. package/_bundled_plugin/skills/security-scan/SKILL.md +4 -2
  50. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +1 -1
  51. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -3
  52. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +2 -0
  53. package/_bundled_plugin/skills/track-findings/SKILL.md +8 -4
  54. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +1 -1
  55. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +1 -1
  56. package/dist/api.d.ts +6 -2
  57. package/dist/api.d.ts.map +1 -1
  58. package/dist/api.js +266 -39
  59. package/dist/api.js.map +1 -1
  60. package/dist/artifact-export.d.ts +2 -1
  61. package/dist/artifact-export.d.ts.map +1 -1
  62. package/dist/artifact-export.js +38 -23
  63. package/dist/artifact-export.js.map +1 -1
  64. package/dist/classify-severity-records.d.ts +76 -0
  65. package/dist/classify-severity-records.d.ts.map +1 -0
  66. package/dist/classify-severity-records.js +141 -0
  67. package/dist/classify-severity-records.js.map +1 -0
  68. package/dist/classify-severity.d.ts +1 -23
  69. package/dist/classify-severity.d.ts.map +1 -1
  70. package/dist/classify-severity.js +3 -24
  71. package/dist/classify-severity.js.map +1 -1
  72. package/dist/cli-help.d.ts.map +1 -1
  73. package/dist/cli-help.js +2 -0
  74. package/dist/cli-help.js.map +1 -1
  75. package/dist/cli.d.ts +4 -2
  76. package/dist/cli.d.ts.map +1 -1
  77. package/dist/cli.js +148 -149
  78. package/dist/cli.js.map +1 -1
  79. package/dist/cloud-publish.js +1 -1
  80. package/dist/cloud-publish.js.map +1 -1
  81. package/dist/codex-sdk-environment.js +1 -1
  82. package/dist/codex-sdk-environment.js.map +1 -1
  83. package/dist/component-plan.js +1 -1
  84. package/dist/component-plan.js.map +1 -1
  85. package/dist/component-scan.d.ts.map +1 -1
  86. package/dist/component-scan.js +5 -4
  87. package/dist/component-scan.js.map +1 -1
  88. package/dist/config.d.ts +12 -0
  89. package/dist/config.d.ts.map +1 -1
  90. package/dist/config.js +10 -4
  91. package/dist/config.js.map +1 -1
  92. package/dist/contract.d.ts +6 -0
  93. package/dist/contract.d.ts.map +1 -1
  94. package/dist/contract.js +69 -20
  95. package/dist/contract.js.map +1 -1
  96. package/dist/cost-model.d.ts.map +1 -1
  97. package/dist/cost-model.js +7 -2
  98. package/dist/cost-model.js.map +1 -1
  99. package/dist/custom-validation-prompt.js +3 -3
  100. package/dist/custom-validation-prompt.js.map +1 -1
  101. package/dist/deduplication/codex-review.d.ts +1 -5
  102. package/dist/deduplication/codex-review.d.ts.map +1 -1
  103. package/dist/deduplication/codex-review.js +2 -2
  104. package/dist/deduplication/codex-review.js.map +1 -1
  105. package/dist/deduplication/deduplication-prompts.d.ts +1 -1
  106. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  107. package/dist/deduplication/deduplication-prompts.js +2 -2
  108. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  109. package/dist/deduplication/deduplication-reviewer.d.ts +1 -1
  110. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  111. package/dist/deduplication/deduplication-reviewer.js +1 -1
  112. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  113. package/dist/deduplication/records-protocol.d.ts +3 -8
  114. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  115. package/dist/deduplication/records-protocol.js +11 -171
  116. package/dist/deduplication/records-protocol.js.map +1 -1
  117. package/dist/deduplication/records.js +1 -1
  118. package/dist/deduplication/records.js.map +1 -1
  119. package/dist/deduplication/scan.d.ts.map +1 -1
  120. package/dist/deduplication/scan.js +10 -9
  121. package/dist/deduplication/scan.js.map +1 -1
  122. package/dist/deep-config.d.ts +4 -1
  123. package/dist/deep-config.d.ts.map +1 -1
  124. package/dist/deep-config.js +21 -1
  125. package/dist/deep-config.js.map +1 -1
  126. package/dist/deep-progress.d.ts +15 -1
  127. package/dist/deep-progress.d.ts.map +1 -1
  128. package/dist/deep-progress.js +15 -16
  129. package/dist/deep-progress.js.map +1 -1
  130. package/dist/executable-path.d.ts +2 -0
  131. package/dist/executable-path.d.ts.map +1 -0
  132. package/dist/executable-path.js +12 -0
  133. package/dist/executable-path.js.map +1 -0
  134. package/dist/feedback.d.ts +1 -4
  135. package/dist/feedback.d.ts.map +1 -1
  136. package/dist/feedback.js +1 -1
  137. package/dist/feedback.js.map +1 -1
  138. package/dist/findings-import.d.ts +1 -1
  139. package/dist/findings-import.d.ts.map +1 -1
  140. package/dist/findings-import.js +3 -3
  141. package/dist/findings-import.js.map +1 -1
  142. package/dist/git-remote.d.ts +10 -0
  143. package/dist/git-remote.d.ts.map +1 -0
  144. package/dist/git-remote.js +24 -0
  145. package/dist/git-remote.js.map +1 -0
  146. package/dist/github.d.ts.map +1 -1
  147. package/dist/github.js +5 -7
  148. package/dist/github.js.map +1 -1
  149. package/dist/host-protocol.d.ts +19 -0
  150. package/dist/host-protocol.d.ts.map +1 -0
  151. package/dist/host-protocol.js +270 -0
  152. package/dist/host-protocol.js.map +1 -0
  153. package/dist/host-records-protocol.d.ts +15 -0
  154. package/dist/host-records-protocol.d.ts.map +1 -0
  155. package/dist/host-records-protocol.js +15 -0
  156. package/dist/host-records-protocol.js.map +1 -0
  157. package/dist/hosted-scan-protocol.d.ts +4 -0
  158. package/dist/hosted-scan-protocol.d.ts.map +1 -0
  159. package/dist/hosted-scan-protocol.js +25 -0
  160. package/dist/hosted-scan-protocol.js.map +1 -0
  161. package/dist/hosted-scan.d.ts +112 -0
  162. package/dist/hosted-scan.d.ts.map +1 -0
  163. package/dist/hosted-scan.js +260 -0
  164. package/dist/hosted-scan.js.map +1 -0
  165. package/dist/index.d.ts +7 -0
  166. package/dist/index.d.ts.map +1 -1
  167. package/dist/index.js +3 -0
  168. package/dist/index.js.map +1 -1
  169. package/dist/knowledge-base.d.ts.map +1 -1
  170. package/dist/knowledge-base.js +87 -7
  171. package/dist/knowledge-base.js.map +1 -1
  172. package/dist/multiscan.d.ts.map +1 -1
  173. package/dist/multiscan.js +108 -36
  174. package/dist/multiscan.js.map +1 -1
  175. package/dist/patch-publication.d.ts +26 -0
  176. package/dist/patch-publication.d.ts.map +1 -0
  177. package/dist/patch-publication.js +105 -0
  178. package/dist/patch-publication.js.map +1 -0
  179. package/dist/patch-tui.d.ts.map +1 -1
  180. package/dist/patch-tui.js +4 -1
  181. package/dist/patch-tui.js.map +1 -1
  182. package/dist/project-config-schema.d.ts +2 -0
  183. package/dist/project-config-schema.d.ts.map +1 -1
  184. package/dist/project-config-schema.js +1 -0
  185. package/dist/project-config-schema.js.map +1 -1
  186. package/dist/project-config.d.ts +1 -0
  187. package/dist/project-config.d.ts.map +1 -1
  188. package/dist/project-config.js +16 -6
  189. package/dist/project-config.js.map +1 -1
  190. package/dist/publication-store.d.ts.map +1 -1
  191. package/dist/publication-store.js +73 -63
  192. package/dist/publication-store.js.map +1 -1
  193. package/dist/publication.d.ts +0 -2
  194. package/dist/publication.d.ts.map +1 -1
  195. package/dist/publication.js +135 -24
  196. package/dist/publication.js.map +1 -1
  197. package/dist/publish.d.ts.map +1 -1
  198. package/dist/publish.js +39 -25
  199. package/dist/publish.js.map +1 -1
  200. package/dist/runtime.d.ts +5 -2
  201. package/dist/runtime.d.ts.map +1 -1
  202. package/dist/runtime.js +86 -58
  203. package/dist/runtime.js.map +1 -1
  204. package/dist/scan-executor.d.ts +104 -0
  205. package/dist/scan-executor.d.ts.map +1 -0
  206. package/dist/scan-executor.js +62 -0
  207. package/dist/scan-executor.js.map +1 -0
  208. package/dist/scan-settings.d.ts +1 -0
  209. package/dist/scan-settings.d.ts.map +1 -1
  210. package/dist/scan-settings.js +7 -1
  211. package/dist/scan-settings.js.map +1 -1
  212. package/dist/scan-time-budget.d.ts +9 -0
  213. package/dist/scan-time-budget.d.ts.map +1 -0
  214. package/dist/scan-time-budget.js +16 -0
  215. package/dist/scan-time-budget.js.map +1 -0
  216. package/dist/severity-review.d.ts +29 -0
  217. package/dist/severity-review.d.ts.map +1 -0
  218. package/dist/severity-review.js +47 -0
  219. package/dist/severity-review.js.map +1 -0
  220. package/dist/targets.d.ts.map +1 -1
  221. package/dist/targets.js +17 -25
  222. package/dist/targets.js.map +1 -1
  223. package/dist/validation-records.d.ts +38 -0
  224. package/dist/validation-records.d.ts.map +1 -0
  225. package/dist/validation-records.js +76 -0
  226. package/dist/validation-records.js.map +1 -0
  227. package/dist/version.d.ts.map +1 -1
  228. package/dist/version.js +4 -2
  229. package/dist/version.js.map +1 -1
  230. package/dist/worker-progress.d.ts +43 -15
  231. package/dist/worker-progress.d.ts.map +1 -1
  232. package/dist/worker-progress.js +22 -80
  233. package/dist/worker-progress.js.map +1 -1
  234. package/docs/classify-severity-records.md +89 -0
  235. package/docs/cli.md +281 -35
  236. package/docs/hosted-scans.md +242 -0
  237. package/docs/validate-records.md +69 -0
  238. package/package.json +18 -14
  239. package/schemas/hosted-scan-v2.fixture.json +145 -0
  240. package/schemas/project-config.schema.json +7 -1
  241. package/_bundled_plugin/preflight/capability-profiles.toml +0 -76
  242. package/_bundled_plugin/references/config-preflight.md +0 -93
  243. package/_bundled_plugin/references/desktop-config-preflight.md +0 -11
  244. package/_bundled_plugin/scripts/config_preflight.py +0 -911
package/dist/cli.js CHANGED
@@ -28,10 +28,15 @@ import { isRecord as isJsonObject } from "./record.js";
28
28
  import { suggestOwnersInternal } from "./suggest-owners.js";
29
29
  import { parseImportedFindings } from "./findings-import.js";
30
30
  import { publishScanToCustom } from "./custom-publish.js";
31
+ import { publishPatchReview, resolvePatchReviewPublisher, } from "./patch-publication.js";
31
32
  import { DEFAULT_DEDUPE_CONCURRENCY } from "./deduplication/deduplication.js";
32
33
  import { savedScanWorkbench } from "./saved-scan-bootstrap.js";
33
34
  import { deduplicateScanInternal } from "./deduplication/scan.js";
34
35
  import { runRecordsProtocol } from "./deduplication/records-protocol.js";
36
+ import { runHostRecordsProtocol } from "./host-records-protocol.js";
37
+ import { classifySeverityRecords, } from "./classify-severity-records.js";
38
+ import { runHostedScanProtocol } from "./hosted-scan-protocol.js";
39
+ import { runValidationRecordsProtocol } from "./validation-records.js";
35
40
  import { classifyScanSeverityInternal, classifyScanDirectorySeverityInternal, } from "./classify-scan-severity.js";
36
41
  import { resolveCompletedScan, resolveWorkflowScan, } from "./saved-scan.js";
37
42
  import { publishFindingsCsvToCloud, publishScanToCloud, } from "./cloud-publish.js";
@@ -68,7 +73,7 @@ import { resolveTrustedExecutable } from "./trusted-executable.js";
68
73
  import { BUNDLED_PLUGIN_VERSION, checkForUpdate, CODEX_EXECUTABLE_VERSION, CODEX_SDK_VERSION, formatUpdateNotice, updateNoticeEnabled, VERSION, } from "./version.js";
69
74
  import { readProjectConfig, resolveScanSettings, projectScopeTarget, configurationSources, projectConfigStarter, } from "./project-config.js";
70
75
  import { resolveConfigPath } from "./config-path.js";
71
- import { resolveDeepScanConfig } from "./deep-config.js";
76
+ import { deepScanOptions, resolveDeepScanConfig } from "./deep-config.js";
72
77
  import { SCAN_MODES } from "./scan-modes.js";
73
78
  import { DEEP_SCAN_SETTINGS, DeepScanSettingsSchema, DEFAULT_SCAN_AUTH, FailureSeveritySchema, REPORTABLE_SEVERITIES, SCAN_SEVERITIES, ScanSettingsSchema, pickScanSettings, meetsSeverity, } from "./scan-settings.js";
74
79
  const PROGRESS_REFRESH_MILLISECONDS = 1_000;
@@ -115,7 +120,13 @@ const PROJECT_CONFIG_OPTION = optionValue("--config")
115
120
  .describe("Load a trusted YAML/JSON file (default: CODEX_SECURITY_PROJECT_CONFIG, otherwise no file).");
116
121
  const EXPORT_DEFAULT_OUTPUTS = ARTIFACT_EXPORT_FILENAMES;
117
122
  const PROVIDER_OPTION = z
118
- .enum(["openai", "openrouter", "fireworks", "amazon-bedrock"])
123
+ .enum([
124
+ "openai",
125
+ "openrouter",
126
+ "fireworks",
127
+ "cheaperinference",
128
+ "amazon-bedrock",
129
+ ])
119
130
  .default("openai")
120
131
  .describe("Inference provider for scans.");
121
132
  const positiveInteger = z.number().int().positive();
@@ -655,7 +666,7 @@ const DEFAULT_DEPENDENCIES = {
655
666
  return options?.trim === false ? stdout : stdout.trim();
656
667
  },
657
668
  exportFindings: runArtifactExport,
658
- runWorkbench: async (args, input, signal, pythonPath) => {
669
+ runWorkbench: async (args, input, signal, pythonPath, protectedRoot) => {
659
670
  const environment = {
660
671
  ...exportEnvironment(),
661
672
  CODEX_SECURITY_STATE_DIR: codexSecurityStateDirectory(),
@@ -664,6 +675,7 @@ const DEFAULT_DEPENDENCIES = {
664
675
  python: await resolvePluginPython({
665
676
  configuredPath: pythonPath,
666
677
  environment,
678
+ protectedRoot,
667
679
  signal,
668
680
  }),
669
681
  pluginRoot: await bundledPluginRoot(),
@@ -999,20 +1011,33 @@ export async function runCodexSkillCommand(args, output, command = resolveCodexC
999
1011
  }
1000
1012
  }
1001
1013
  export async function main(argv = process.argv.slice(2), output = process.stdout, errorOutput = process.stderr, dependencies = DEFAULT_DEPENDENCIES) {
1002
- if (argv[0] === "dedupe" &&
1003
- argv.includes("--records") &&
1014
+ if ((((argv[0] === "dedupe" ||
1015
+ argv[0] === "validate" ||
1016
+ argv[0] === "classify-severity") &&
1017
+ argv.includes("--records")) ||
1018
+ (argv[0] === "scan" &&
1019
+ argv.some((arg) => arg === "--host" || arg.startsWith("--host=")))) &&
1004
1020
  !argv.includes("--help") &&
1005
1021
  !argv.includes("-h") &&
1006
1022
  !argv.includes("--schema")) {
1007
- if (argv.length !== 2) {
1008
- errorOutput.write("codex-security: --records must be used alone with dedupe.\n");
1023
+ if (argv.length !== 2 || (argv[0] === "scan" && argv[1] !== "--host")) {
1024
+ errorOutput.write(argv[0] === "scan"
1025
+ ? "codex-security: --host must be used alone with scan.\n"
1026
+ : `codex-security: --records must be used alone with ${argv[0]}.\n`);
1009
1027
  return 2;
1010
1028
  }
1011
1029
  const controller = new AbortController();
1012
1030
  const removeSignals = listenForAbort(dependencies, controller);
1013
1031
  let exitCode;
1014
1032
  try {
1015
- const code = await runRecordsProtocol(dependencies.recordsInput ?? process.stdin, output, controller.signal);
1033
+ const runProtocol = argv[0] === "scan"
1034
+ ? runHostedScanProtocol
1035
+ : argv[0] === "validate"
1036
+ ? runValidationRecordsProtocol
1037
+ : runRecordsProtocol;
1038
+ const code = argv[0] === "classify-severity"
1039
+ ? await runHostRecordsProtocol(dependencies.recordsInput ?? process.stdin, output, (value, options) => classifySeverityRecords(value, options), controller.signal)
1040
+ : await runProtocol(dependencies.recordsInput ?? process.stdin, output, controller.signal);
1016
1041
  exitCode =
1017
1042
  controller.signal.reason === "SIGINT"
1018
1043
  ? 130
@@ -1063,9 +1088,9 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1063
1088
  return incurError({ code, message: outcome.error, exitCode });
1064
1089
  };
1065
1090
  const runImport = (options) => runScanImport(options, errorOutput, dependencies);
1066
- const history = async (args, select = (value) => value, pythonPath) => {
1091
+ const history = async (args, select = (value) => value, pythonPath, protectedRoot) => {
1067
1092
  try {
1068
- return await select(await dependencies.runWorkbench(args, undefined, undefined, pythonPath));
1093
+ return await select(await dependencies.runWorkbench(args, undefined, undefined, pythonPath, protectedRoot));
1069
1094
  }
1070
1095
  catch (error) {
1071
1096
  errorOutput.write(`codex-security: ${diagnosticLines(error)}\n`);
@@ -1073,7 +1098,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1073
1098
  throw error;
1074
1099
  }
1075
1100
  };
1076
- const latestScans = async (count = 1, status = "complete", pythonPath) => {
1101
+ const latestScans = async (count = 1, status = "complete", pythonPath, protectedRoot) => {
1077
1102
  const result = await history(workbenchArgs("list-scans", {
1078
1103
  repository: dependencies.currentDirectory(),
1079
1104
  status: status === "complete" ? "complete" : undefined,
@@ -1086,7 +1111,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1086
1111
  : `At least ${count} ${kind} scans are required for the current repository.`);
1087
1112
  }
1088
1113
  return value;
1089
- }, pythonPath);
1114
+ }, pythonPath, protectedRoot);
1090
1115
  return result?.["scans"];
1091
1116
  };
1092
1117
  const runMatching = async (operation, selection) => {
@@ -2370,6 +2395,10 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2370
2395
  options: z
2371
2396
  .object({
2372
2397
  config: PROJECT_CONFIG_OPTION,
2398
+ host: z
2399
+ .boolean()
2400
+ .default(false)
2401
+ .describe("Run one hosted Standard scan over JSON-RPC stdin/stdout; use alone."),
2373
2402
  workflowId: optionValue("--workflow-id")
2374
2403
  .optional()
2375
2404
  .describe("Reuse completed work in the named local findings workflow."),
@@ -2416,6 +2445,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2416
2445
  .optional()
2417
2446
  .describe("Git base ref for --working-tree (default: HEAD)."),
2418
2447
  mode: ScanSettingsSchema.shape.mode.describe("Scan mode (default: standard); deep supports repository and path targets."),
2448
+ maxTime: ScanSettingsSchema.shape.maxTimeMinutes,
2419
2449
  ...DEEP_SCAN_OPTION_SCHEMAS,
2420
2450
  ...modelOptions(`OpenAI model to use (default: ${DEFAULT_SCAN_MODEL_CONFIGURATION.model}).`).shape,
2421
2451
  provider: PROVIDER_OPTION,
@@ -2466,6 +2496,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2466
2496
  }),
2467
2497
  output: scanOutputSchema("SCAN_FAILED"),
2468
2498
  async run({ args, error: incurError, format, options }) {
2499
+ if (options.host)
2500
+ throw new CodexSecurityError("Use scan --host alone.");
2469
2501
  if (format === "md") {
2470
2502
  errorOutput.write("codex-security: Markdown output is not supported for scan results.\n");
2471
2503
  exitCode = 2;
@@ -2488,6 +2520,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2488
2520
  knowledgeBasePaths: options.knowledgeBase,
2489
2521
  failureSeverity: options.failOnSeverity,
2490
2522
  maxCostUsd: options.maxCost,
2523
+ maxTimeMinutes: options.maxTime,
2491
2524
  codexOverrides: parseCodexOverrides(options.codex, options.model, options.effort, options.provider, project?.input.codex),
2492
2525
  }, directory, scope.sources);
2493
2526
  if (options.archiveExisting && settings.outputDir === undefined) {
@@ -2650,11 +2683,15 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2650
2683
  },
2651
2684
  })
2652
2685
  .command("classify-severity", {
2653
- description: "Assess severity for saved findings.",
2654
- hint: "Use --rubric to classify findings with a policy. The assessment is saved separately.",
2686
+ description: "Assess severity for saved findings or canonical records.",
2687
+ hint: "Use --rubric for saved findings or --records alone for host-provided classification.",
2655
2688
  destructive: true,
2656
2689
  mcp: false,
2657
2690
  options: z.object({
2691
+ records: z
2692
+ .boolean()
2693
+ .default(false)
2694
+ .describe("Classify canonical records through host-provided reviews over version 1 JSON-RPC; use alone."),
2658
2695
  reprocess: z
2659
2696
  .boolean()
2660
2697
  .default(false)
@@ -2680,6 +2717,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2680
2717
  }),
2681
2718
  output: z.record(z.string(), z.unknown()).optional(),
2682
2719
  async run({ options }) {
2720
+ if (options.records)
2721
+ throw new CodexSecurityError("Use classify-severity --records alone.");
2683
2722
  const controller = new AbortController();
2684
2723
  const removeSignals = listenForAbort(dependencies, controller);
2685
2724
  try {
@@ -2858,7 +2897,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2858
2897
  : "Deduplication canceled. Findings are unchanged."
2859
2898
  : diagnosticValue(error)}\n`);
2860
2899
  exitCode = interruptedExitCode(controller.signal) ?? 2;
2861
- return undefined;
2900
+ throw error;
2862
2901
  }
2863
2902
  finally {
2864
2903
  removeSignals();
@@ -2957,6 +2996,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2957
2996
  codexOverrides: parseCodexOverrides(options.codex, options.model, options.effort, options.provider, project?.input.codex),
2958
2997
  }, directory);
2959
2998
  const settings = resolved.options;
2999
+ deepScanOptions(settings);
2960
3000
  if (settings.outputDir === undefined)
2961
3001
  throw new ConfigurationError("--output-dir or output.directory is required for component scans.");
2962
3002
  const config = {
@@ -3147,14 +3187,6 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3147
3187
  };
3148
3188
  const resolved = resolveScanSettings(project, overrides, currentDirectory);
3149
3189
  const settings = resolved.options;
3150
- // A CSV row may choose a different mode; resolve the same file for both
3151
- // modes so inactive deep defaults remain available to deep rows.
3152
- const scanOptionsByMode = project === undefined
3153
- ? undefined
3154
- : Object.fromEntries(SCAN_MODES.map((mode) => [
3155
- mode,
3156
- resolveScanSettings(project, { ...overrides, mode }, currentDirectory).options,
3157
- ]));
3158
3190
  let inputPath;
3159
3191
  let outputDir;
3160
3192
  let githubHost;
@@ -3181,6 +3213,12 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3181
3213
  inputPath = resolveCliPath(currentDirectory, args.input);
3182
3214
  outputDir = settings.outputDir;
3183
3215
  }
3216
+ const scanOptionsByMode = project === undefined
3217
+ ? undefined
3218
+ : Object.fromEntries(SCAN_MODES.map((mode) => [
3219
+ mode,
3220
+ resolveScanSettings(project, { ...overrides, mode }, currentDirectory).options,
3221
+ ]));
3184
3222
  const result = await runMultiscan({
3185
3223
  inputPath,
3186
3224
  outputDir,
@@ -3345,13 +3383,19 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3345
3383
  throw new CodexSecurityError("--scan cannot be combined with a result directory.");
3346
3384
  }
3347
3385
  const format = resolveArtifactFormat(options.artifact, options.exportFormat);
3386
+ const sourceRoot = options.sourceRoot === undefined
3387
+ ? undefined
3388
+ : resolveCliPath(currentDirectory, options.sourceRoot);
3389
+ const protectedRoot = sourceRoot === undefined
3390
+ ? undefined
3391
+ : [currentDirectory, sourceRoot];
3348
3392
  let scanDir = args.scanDir;
3349
3393
  if (scanDir === undefined) {
3350
3394
  const scanId = options.scan ??
3351
- (await latestScans(1, "complete", options.python))?.[0]?.scanId;
3395
+ (await latestScans(1, "complete", options.python, protectedRoot))?.[0]?.scanId;
3352
3396
  if (scanId === undefined)
3353
3397
  return;
3354
- scanDir = await resolveSavedArtifactDirectory(scanId, options.artifact, format, (args) => dependencies.runWorkbench(args, undefined, undefined, options.python));
3398
+ scanDir = await resolveSavedArtifactDirectory(scanId, options.artifact, format, (args) => dependencies.runWorkbench(args, undefined, undefined, options.python, protectedRoot));
3355
3399
  }
3356
3400
  const arguments_ = {
3357
3401
  scanDir: resolveCliPath(currentDirectory, scanDir),
@@ -3360,9 +3404,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3360
3404
  output: options.output === "-"
3361
3405
  ? "-"
3362
3406
  : resolveCliPath(currentDirectory, options.output ?? EXPORT_DEFAULT_OUTPUTS[format]),
3363
- sourceRoot: options.sourceRoot === undefined
3364
- ? undefined
3365
- : resolveCliPath(currentDirectory, options.sourceRoot),
3407
+ sourceRoot,
3366
3408
  pythonPath: options.python,
3367
3409
  };
3368
3410
  try {
@@ -3392,6 +3434,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3392
3434
  },
3393
3435
  })
3394
3436
  .command("validate", {
3437
+ hint: "Use --records alone for host-provided reviews over JSON-RPC.",
3395
3438
  description: "Assess candidate security findings using source evidence only.",
3396
3439
  destructive: false,
3397
3440
  mcp: false,
@@ -3402,6 +3445,10 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3402
3445
  .describe("Finding text or a file containing findings."),
3403
3446
  }),
3404
3447
  options: z.object({
3448
+ records: z
3449
+ .boolean()
3450
+ .default(false)
3451
+ .describe("Run the versioned validation JSON-RPC protocol on stdin/stdout; use alone."),
3405
3452
  auth: SKILL_AUTH_OPTION,
3406
3453
  ...SKILL_CONFIG_OPTIONS.shape,
3407
3454
  context: optionValue("--context")
@@ -3421,6 +3468,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3421
3468
  async run({ options }) {
3422
3469
  let knowledgeBase;
3423
3470
  try {
3471
+ if (options.records)
3472
+ throw new CodexSecurityError("Use validate --records alone.");
3424
3473
  if (options.knowledgeBase.length > 0) {
3425
3474
  knowledgeBase = await prepareKnowledgeBase(options.knowledgeBase.map((path) => resolveCliPath(dependencies.currentDirectory(), path)));
3426
3475
  }
@@ -4073,6 +4122,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4073
4122
  const directory = dependencies.currentDirectory();
4074
4123
  const project = await selectedProjectConfig(options.config, dependencies);
4075
4124
  const resolved = resolveScanSettings(project, {}, directory);
4125
+ deepScanOptions(resolved.options);
4076
4126
  const codex = await mergedCodexConfig(resolved.config);
4077
4127
  const deep = resolved.options.mode === "deep"
4078
4128
  ? await resolveDeepScanConfig(resolved.options, join(scanCodexHome(dependencies.environment), "codex-security", "config.toml"))
@@ -4544,6 +4594,10 @@ async function prepareScanArgumentsFromRecipe(recipe, parentScanId, { scanPrompt
4544
4594
  throw new CodexSecurityError("The saved scan recipe contains an invalid cost limit.");
4545
4595
  }
4546
4596
  const deepScan = DeepScanSettingsSchema.optional().safeParse(recipe["deepScan"]);
4597
+ const maxTimeMinutes = ScanSettingsSchema.shape.maxTimeMinutes.safeParse(recipe["maxTimeMinutes"]);
4598
+ if (!maxTimeMinutes.success) {
4599
+ throw new CodexSecurityError("The saved scan recipe contains an invalid investigation time limit.");
4600
+ }
4547
4601
  if (!deepScan.success) {
4548
4602
  throw new CodexSecurityError("The saved scan recipe contains invalid deep scan settings.");
4549
4603
  }
@@ -4596,6 +4650,7 @@ async function prepareScanArgumentsFromRecipe(recipe, parentScanId, { scanPrompt
4596
4650
  : { ...config, approval_policy: "never" },
4597
4651
  failureSeverity: threshold.data,
4598
4652
  maxCostUsd,
4653
+ maxTimeMinutes: maxTimeMinutes.data,
4599
4654
  dryRun: false,
4600
4655
  parentScanId,
4601
4656
  ...(recipe["mock"] === true ? { mock: true } : {}),
@@ -4786,12 +4841,48 @@ async function selectSavedFindings(identifiers, requestedScanId, severity, depen
4786
4841
  finding.findingId === identifier))) {
4787
4842
  throw new CodexSecurityError("The requested finding does not belong to the selected scan.");
4788
4843
  }
4844
+ const fullFindings = selected.length === 0
4845
+ ? []
4846
+ : await (dependencies.readSavedFindings ?? readSavedFindings)(scan.scanId, dependencies.runWorkbench);
4847
+ const byOccurrence = new Map(fullFindings.map((finding) => [finding.occurrenceId, finding]));
4789
4848
  return {
4790
4849
  repository: scan.targetPath,
4791
4850
  scanId: scan.scanId,
4792
- findings: selected,
4851
+ findings: selected.map((finding) => {
4852
+ const full = byOccurrence.get(finding.occurrenceId);
4853
+ if (full === undefined || full.findingId !== finding.findingId) {
4854
+ throw new CodexSecurityError(`Finding ${finding.occurrenceId} is missing from the saved scan artifacts.`);
4855
+ }
4856
+ const hydrated = { ...finding, ...full };
4857
+ // Sealed artifacts supply evidence; the workbench owns live and derived state.
4858
+ for (const key of [
4859
+ "createdAt",
4860
+ "triage",
4861
+ "remediationState",
4862
+ "matches",
4863
+ "knownSince",
4864
+ "knownScanIds",
4865
+ "related",
4866
+ "sourceExcerpt",
4867
+ "artifactPaths",
4868
+ ]) {
4869
+ if (Object.hasOwn(finding, key))
4870
+ hydrated[key] = finding[key];
4871
+ else
4872
+ delete hydrated[key];
4873
+ }
4874
+ return hydrated;
4875
+ }),
4793
4876
  };
4794
4877
  }
4878
+ async function readSavedFindings(scanId, workbench) {
4879
+ const directory = await resolveSavedArtifactDirectory(scanId, "findings", "json", workbench);
4880
+ const { findings } = await loadContract(directory, {
4881
+ pluginRoot: await bundledPluginRoot(),
4882
+ expectedScanId: scanId,
4883
+ });
4884
+ return findings.findings;
4885
+ }
4795
4886
  function patchExitCode(patches) {
4796
4887
  if (patches.some(({ status }) => status === "failed"))
4797
4888
  return 2;
@@ -4831,77 +4922,17 @@ async function publishPatchBranch(repository, branch, body, stderr, dependencies
4831
4922
  const run = (command, args) => dependencies.runRepositoryCommand(command, args, repository);
4832
4923
  try {
4833
4924
  const remote = await run("git", ["remote", "get-url", "--push", "origin"]);
4834
- const host = patchRemoteHost(remote);
4835
- const gitlabHost = dependencies.environment["GITLAB_HOST"] ||
4836
- dependencies.environment["GITLAB_URI"] ||
4837
- dependencies.environment["GL_HOST"];
4838
- const gitlab = host === "gitlab.com" ||
4839
- (host !== undefined &&
4840
- gitlabHost !== undefined &&
4841
- host ===
4842
- patchRemoteHost(gitlabHost.includes("://") ? gitlabHost : `https://${gitlabHost}`));
4843
- const command = gitlab ? "glab" : "gh";
4844
- const gitlabRepository = remote.includes("://")
4845
- ? remote
4846
- : `ssh://${remote.replace(":", "/")}`;
4847
- let url = await run(command, gitlab
4848
- ? [
4849
- "mr",
4850
- "list",
4851
- "--all",
4852
- "--source-branch",
4853
- branch,
4854
- "--output",
4855
- "json",
4856
- "--jq",
4857
- "map(select(.source_project_id == .target_project_id))[0].web_url // empty",
4858
- "--repo",
4859
- gitlabRepository,
4860
- ]
4861
- : [
4862
- "pr",
4863
- "list",
4864
- "--head",
4865
- branch,
4866
- "--state",
4867
- "all",
4868
- "--json",
4869
- "url",
4870
- "--jq",
4871
- ".[0].url // empty",
4872
- ]);
4873
- if (!url) {
4874
- await run("git", ["push", "--set-upstream", "origin", branch]);
4875
- url = await run(command, gitlab
4876
- ? [
4877
- "mr",
4878
- "create",
4879
- "--draft",
4880
- "--head",
4881
- gitlabRepository,
4882
- "--source-branch",
4883
- branch,
4884
- "--title",
4885
- PATCH_PR_TITLE,
4886
- "--description",
4887
- gitlabPatchDescription(body),
4888
- "--yes",
4889
- "--repo",
4890
- gitlabRepository,
4891
- ]
4892
- : [
4893
- "pr",
4894
- "create",
4895
- "--draft",
4896
- "--head",
4897
- branch,
4898
- "--title",
4899
- PATCH_PR_TITLE,
4900
- "--body",
4901
- body,
4902
- ]);
4903
- }
4904
- stderr.write(`${gitlab ? "Merge" : "Pull"} request: ${safePatchText(url)}\n`);
4925
+ const publisher = resolvePatchReviewPublisher(remote, dependencies.environment, run);
4926
+ const url = await publishPatchReview({
4927
+ branch,
4928
+ title: PATCH_PR_TITLE,
4929
+ body,
4930
+ publisher,
4931
+ pushBranch: async (branch) => {
4932
+ await run("git", ["push", "--set-upstream", "origin", branch]);
4933
+ },
4934
+ });
4935
+ stderr.write(`${publisher.label}: ${safePatchText(url)}\n`);
4905
4936
  return { branch, url };
4906
4937
  }
4907
4938
  catch (error) {
@@ -4909,20 +4940,6 @@ async function publishPatchBranch(repository, branch, body, stderr, dependencies
4909
4940
  throw error;
4910
4941
  }
4911
4942
  }
4912
- function gitlabPatchDescription(body) {
4913
- // GitLab ignores quick actions inside its native fenced blockquotes. Choose
4914
- // a fence the report cannot close after quick-action CR removal; preserve its
4915
- // original bytes and end the outer quote at EOF.
4916
- let fenceLength = 3;
4917
- for (const match of body.replaceAll("\r", "").matchAll(/^[ \t]*(>+)/gmu))
4918
- fenceLength = Math.max(fenceLength, match[1].length + 1);
4919
- return `${">".repeat(fenceLength)}\n${body}`;
4920
- }
4921
- function patchRemoteHost(remote) {
4922
- if (remote.includes("://"))
4923
- return new URL(remote).hostname.toLowerCase();
4924
- return /^(?:[^@/]+@)?([^:/]+):[^/]/u.exec(remote)?.[1]?.toLowerCase();
4925
- }
4926
4943
  async function resumePatchPullRequest(repository, branch, stderr, dependencies) {
4927
4944
  const run = (args) => dependencies.runRepositoryCommand("git", args, repository);
4928
4945
  const commit = await run([
@@ -5973,6 +5990,7 @@ async function executeScan(arguments_, errorOutput, dependencies, interactive =
5973
5990
  let failed = false;
5974
5991
  let failure;
5975
5992
  try {
5993
+ deepScanOptions(arguments_);
5976
5994
  const directory = dependencies.currentDirectory();
5977
5995
  repository = arguments_.repository ?? directory;
5978
5996
  const target = arguments_.target;
@@ -6016,7 +6034,7 @@ async function executeScan(arguments_, errorOutput, dependencies, interactive =
6016
6034
  }
6017
6035
  selectedAuthentication = arguments_.mock
6018
6036
  ? null
6019
- : scanAuthentication(dependencies.environment, auth, provider, hasCommandAuth(effectiveConfiguration));
6037
+ : scanAuthentication(dependencies.environment, auth, provider, hasCommandAuth(effectiveConfiguration), arguments_.dryRun);
6020
6038
  diagnostic("scan.configuration", {
6021
6039
  cli_version: VERSION,
6022
6040
  bundled_plugin_version: BUNDLED_PLUGIN_VERSION,
@@ -6324,32 +6342,20 @@ async function executeScan(arguments_, errorOutput, dependencies, interactive =
6324
6342
  progress.startTimer(runningMessage());
6325
6343
  },
6326
6344
  onWorkerStatus: (status) => {
6327
- const update = status.kind === "preflight"
6328
- ? `preflight:${status.delegation}:${status.configuredSlots}`
6329
- : `dispatch:${status.phase}:${status.planned}:${status.started}`;
6345
+ const update = `dispatch:${status.phase}:${status.planned}:${status.started}`;
6330
6346
  if (update === lastWorkerUpdate)
6331
6347
  return;
6332
6348
  lastWorkerUpdate = update;
6333
- if (status.kind === "preflight") {
6334
- diagnostic("worker.preflight", {
6335
- delegation: status.delegation,
6336
- configured_slots: status.configuredSlots,
6337
- });
6338
- }
6339
- else {
6340
- diagnostic("worker.phase", {
6341
- phase: status.phase,
6342
- planned: status.planned,
6343
- started: status.started,
6344
- });
6345
- workerCapacity = { planned: status.planned, started: status.started };
6346
- phase = scanPhase(status.phase);
6347
- }
6349
+ diagnostic("worker.phase", {
6350
+ phase: status.phase,
6351
+ planned: status.planned,
6352
+ started: status.started,
6353
+ });
6354
+ workerCapacity = { planned: status.planned, started: status.started };
6355
+ phase = scanPhase(status.phase);
6348
6356
  const message = workerStatusMessage(status);
6349
6357
  if (dashboard !== null) {
6350
- if (status.kind === "dispatch") {
6351
- dashboard.setStage(scanPhase(status.phase));
6352
- }
6358
+ dashboard.setStage(scanPhase(status.phase));
6353
6359
  dashboard.note(message);
6354
6360
  return;
6355
6361
  }
@@ -6852,10 +6858,14 @@ async function readDeepScanStop(result, maxCostUsd, runWorkbench) {
6852
6858
  }
6853
6859
  const elapsedHours = (Date.parse(state.completedAt) - Date.parse(state.createdAt)) / 3_600_000;
6854
6860
  if (elapsedHours >= maxTimeHours) {
6861
+ let maxTimeMinutes = maxTimeHours * 60;
6862
+ const roundedMinutes = Number(maxTimeMinutes.toPrecision(15));
6863
+ if (roundedMinutes / 60 === maxTimeHours)
6864
+ maxTimeMinutes = roundedMinutes;
6855
6865
  return {
6856
- reason: `Reached the ${maxTimeHours}-hour time limit. More issues may remain.`,
6866
+ reason: `Reached the ${maxTimeMinutes}-minute time limit. More issues may remain.`,
6857
6867
  nextStep: maxTimeHours < 96
6858
- ? "To scan further, rerun with a higher --max-time-hours."
6868
+ ? `To scan further, rerun with --max-time greater than ${maxTimeMinutes}.`
6859
6869
  : "To scan a smaller part of the repository, rerun with --path.",
6860
6870
  };
6861
6871
  }
@@ -7189,17 +7199,6 @@ export function parseCodexOverrides(values, model, effort, provider, defaults) {
7189
7199
  return result;
7190
7200
  }
7191
7201
  function workerStatusMessage(status) {
7192
- if (status.kind === "preflight") {
7193
- if (status.delegation === "unavailable") {
7194
- return "Preflight: worker delegation unavailable; continuing without delegated workers.";
7195
- }
7196
- if (status.delegation === "unknown") {
7197
- return "Preflight: worker delegation could not be confirmed; continuing scan.";
7198
- }
7199
- return status.configuredSlots === null
7200
- ? "Preflight: worker delegation supported."
7201
- : `Preflight: worker delegation supported (up to ${status.configuredSlots} worker slots).`;
7202
- }
7203
7202
  if (status.started === status.planned) {
7204
7203
  return `Scan phase: ${scanPhase(status.phase)} (${status.started} ${status.started === 1 ? "worker" : "workers"}).`;
7205
7204
  }