@openai/codex-security 0.3.0 → 0.4.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 (118) hide show
  1. package/_bundled_plugin/.codex-plugin/plugin.json +5 -5
  2. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  3. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  4. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  5. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +13 -20
  6. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  7. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  8. package/_bundled_plugin/references/final-report.md +1 -1
  9. package/_bundled_plugin/schemas/coverage.schema.json +45 -126
  10. package/_bundled_plugin/schemas/findings.schema.json +140 -427
  11. package/_bundled_plugin/schemas/patch-risk-assessment.schema.json +106 -119
  12. package/_bundled_plugin/schemas/scan-manifest.schema.json +73 -188
  13. package/_bundled_plugin/scripts/finalize_scan_contract.py +7 -6
  14. package/_bundled_plugin/scripts/generate_rank_input.py +25 -106
  15. package/_bundled_plugin/scripts/report_projection.py +35 -13
  16. package/_bundled_plugin/scripts/workbench_cli.py +9 -6
  17. package/_bundled_plugin/scripts/workbench_db.py +51 -16
  18. package/_bundled_plugin/scripts/workbench_publication.py +216 -247
  19. package/_bundled_plugin/scripts/workbench_scan_usage.py +173 -10
  20. package/_bundled_plugin/scripts/workbench_validation.py +15 -1
  21. package/_bundled_plugin/shared/workbench-migrations.json +17 -0
  22. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +1 -1
  23. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +1 -1
  24. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +1 -1
  25. package/_bundled_plugin/skills/security-scan/SKILL.md +1 -1
  26. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +1 -1
  27. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +1 -1
  28. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +2 -0
  29. package/_bundled_plugin/skills/track-findings/SKILL.md +8 -4
  30. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +1 -1
  31. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +1 -1
  32. package/dist/api.d.ts +3 -0
  33. package/dist/api.d.ts.map +1 -1
  34. package/dist/api.js +212 -3
  35. package/dist/api.js.map +1 -1
  36. package/dist/cli.d.ts.map +1 -1
  37. package/dist/cli.js +15 -5
  38. package/dist/cli.js.map +1 -1
  39. package/dist/component-plan.js +1 -1
  40. package/dist/component-plan.js.map +1 -1
  41. package/dist/component-scan.d.ts.map +1 -1
  42. package/dist/component-scan.js +5 -4
  43. package/dist/component-scan.js.map +1 -1
  44. package/dist/contract.d.ts +1 -0
  45. package/dist/contract.d.ts.map +1 -1
  46. package/dist/contract.js +4 -3
  47. package/dist/contract.js.map +1 -1
  48. package/dist/custom-validation-prompt.js +1 -1
  49. package/dist/custom-validation-prompt.js.map +1 -1
  50. package/dist/deduplication/codex-review.d.ts +1 -5
  51. package/dist/deduplication/codex-review.d.ts.map +1 -1
  52. package/dist/deduplication/codex-review.js +2 -2
  53. package/dist/deduplication/codex-review.js.map +1 -1
  54. package/dist/deduplication/deduplication-reviewer.d.ts +1 -1
  55. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  56. package/dist/deduplication/deduplication-reviewer.js +1 -1
  57. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  58. package/dist/deduplication/records-protocol.d.ts +3 -8
  59. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  60. package/dist/deduplication/records-protocol.js +11 -171
  61. package/dist/deduplication/records-protocol.js.map +1 -1
  62. package/dist/deep-progress.d.ts +15 -1
  63. package/dist/deep-progress.d.ts.map +1 -1
  64. package/dist/deep-progress.js +15 -16
  65. package/dist/deep-progress.js.map +1 -1
  66. package/dist/executable-path.d.ts +2 -0
  67. package/dist/executable-path.d.ts.map +1 -0
  68. package/dist/executable-path.js +12 -0
  69. package/dist/executable-path.js.map +1 -0
  70. package/dist/feedback.d.ts +1 -4
  71. package/dist/feedback.d.ts.map +1 -1
  72. package/dist/feedback.js +1 -1
  73. package/dist/feedback.js.map +1 -1
  74. package/dist/host-protocol.d.ts +19 -0
  75. package/dist/host-protocol.d.ts.map +1 -0
  76. package/dist/host-protocol.js +270 -0
  77. package/dist/host-protocol.js.map +1 -0
  78. package/dist/hosted-scan-protocol.d.ts +4 -0
  79. package/dist/hosted-scan-protocol.d.ts.map +1 -0
  80. package/dist/hosted-scan-protocol.js +25 -0
  81. package/dist/hosted-scan-protocol.js.map +1 -0
  82. package/dist/hosted-scan.d.ts +117 -0
  83. package/dist/hosted-scan.d.ts.map +1 -0
  84. package/dist/hosted-scan.js +260 -0
  85. package/dist/hosted-scan.js.map +1 -0
  86. package/dist/index.d.ts +3 -0
  87. package/dist/index.d.ts.map +1 -1
  88. package/dist/index.js +1 -0
  89. package/dist/index.js.map +1 -1
  90. package/dist/multiscan.d.ts.map +1 -1
  91. package/dist/multiscan.js +47 -9
  92. package/dist/multiscan.js.map +1 -1
  93. package/dist/publication-store.d.ts.map +1 -1
  94. package/dist/publication-store.js +73 -63
  95. package/dist/publication-store.js.map +1 -1
  96. package/dist/publication.d.ts +0 -2
  97. package/dist/publication.d.ts.map +1 -1
  98. package/dist/publication.js +0 -5
  99. package/dist/publication.js.map +1 -1
  100. package/dist/runtime.d.ts +5 -2
  101. package/dist/runtime.d.ts.map +1 -1
  102. package/dist/runtime.js +5 -38
  103. package/dist/runtime.js.map +1 -1
  104. package/dist/scan-executor.d.ts +104 -0
  105. package/dist/scan-executor.d.ts.map +1 -0
  106. package/dist/scan-executor.js +62 -0
  107. package/dist/scan-executor.js.map +1 -0
  108. package/dist/targets.d.ts.map +1 -1
  109. package/dist/targets.js +17 -25
  110. package/dist/targets.js.map +1 -1
  111. package/dist/worker-progress.d.ts +43 -11
  112. package/dist/worker-progress.d.ts.map +1 -1
  113. package/dist/worker-progress.js +21 -37
  114. package/dist/worker-progress.js.map +1 -1
  115. package/docs/cli.md +12 -2
  116. package/docs/hosted-scans.md +242 -0
  117. package/package.json +9 -7
  118. package/schemas/hosted-scan-v2.fixture.json +145 -0
package/dist/api.js CHANGED
@@ -9,6 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
9
9
  /// <reference lib="esnext.disposable" preserve="true" />
10
10
  import { workbenchArgs } from "./workbench-arguments.js";
11
11
  import { isSafeNonNegativeInteger as safeInteger } from "./value.js";
12
+ import { ScanExecutionError, ScanExecutionResultSchema, } from "./scan-executor.js";
12
13
  import { chmod, lstat, mkdir, mkdtemp, readFile, realpath, rm, writeFile, } from "node:fs/promises";
13
14
  import { randomUUID } from "node:crypto";
14
15
  import { tmpdir } from "node:os";
@@ -113,7 +114,8 @@ function patchOutcomeFromResponse(response) {
113
114
  };
114
115
  }
115
116
  }
116
- const DEFAULT_DEPENDENCIES = {
117
+ /** @internal */
118
+ export const DEFAULT_DEPENDENCIES = {
117
119
  createCodex: ({ nativeProfile, ...options }) => nativeProfile === undefined
118
120
  ? new Codex(options)
119
121
  : createProfileCodex(options, nativeProfile),
@@ -148,6 +150,9 @@ export class CodexSecurity {
148
150
  this.#surface = runtimeOptions.surface;
149
151
  }
150
152
  async run(repository, options = {}) {
153
+ // Reject the removed experimental option rather than starting local inference.
154
+ if ("hosted" in options)
155
+ throw new CodexSecurityError("Use runHostedScan with an executor for hosted execution.");
151
156
  return await this.#trackOperation(() => options.workflowId === undefined
152
157
  ? this.#run(repository, { ...options })
153
158
  : this.#runWorkflow(repository, { ...options }, options.workflowId));
@@ -773,6 +778,7 @@ export class CodexSecurity {
773
778
  let artifactRestorationFailure = null;
774
779
  let customValidationComplete = false;
775
780
  let completionCost = null;
781
+ let scanTurnStatus = null;
776
782
  let budgetRecovery = null;
777
783
  let preparedTargetWarnings = [];
778
784
  let runPostScan = null;
@@ -780,6 +786,35 @@ export class CodexSecurity {
780
786
  const prepareArtifactRestorer = this.#dependencies.prepareScanArtifactRestorer ??
781
787
  prepareScanArtifactRestorer;
782
788
  const workbench = this.#dependencies.runWorkbench ?? runWorkbench;
789
+ const terminalScanTurnStatus = () => scanTurnStatus === "completed" || scanTurnStatus === "failed"
790
+ ? scanTurnStatus
791
+ : signal.aborted
792
+ ? "interrupted"
793
+ : null;
794
+ const finalizeScanUsage = async (scanId, workbenchOptions, completedScan, turnStatus) => {
795
+ const measuredUsage = isRecord(completedScan)
796
+ ? completedScan["usage"]
797
+ : undefined;
798
+ const usageCompletion = isRecord(measuredUsage)
799
+ ? measuredUsage["completion"]
800
+ : undefined;
801
+ if (isRecord(usageCompletion) &&
802
+ usageCompletion["finalized"] === false &&
803
+ typeof usageCompletion["threadId"] === "string" &&
804
+ typeof usageCompletion["turnId"] === "string") {
805
+ try {
806
+ await workbench({ ...workbenchOptions, signal: undefined }, workbenchArgs("finalize-scan-usage", {
807
+ scanId,
808
+ threadId: usageCompletion["threadId"],
809
+ turnId: usageCompletion["turnId"],
810
+ turnStatus,
811
+ }));
812
+ }
813
+ catch (error) {
814
+ notifyObserver(options, "onWarning")(`Could not finalize scan token usage: ${errorMessage(error)}`);
815
+ }
816
+ }
817
+ };
783
818
  try {
784
819
  const checkOpen = () => {
785
820
  this.#requireOpen();
@@ -827,6 +862,14 @@ export class CodexSecurity {
827
862
  ...(knowledgeBase?.protectedRoots ?? []),
828
863
  ]) {
829
864
  git = await inspectTrustedExecutable("git", git.environment, root);
865
+ if (this.#dependencies.hostedScan !== undefined) {
866
+ // Match the hosted MCP launchers' PATH-based tool lookups.
867
+ for (const command of process.platform === "win32"
868
+ ? ["node"]
869
+ : ["dirname", "node"]) {
870
+ git.environment = (await inspectTrustedExecutable(command, git.environment, root)).environment;
871
+ }
872
+ }
830
873
  }
831
874
  checkOpen();
832
875
  const scanOutputRoot = requestedOutput === null &&
@@ -1334,6 +1377,7 @@ export class CodexSecurity {
1334
1377
  signal,
1335
1378
  })
1336
1379
  : (await thread.runStreamed(prompt, turnOptions)).events;
1380
+ scanTurnStatus = "in_progress";
1337
1381
  checkOpen();
1338
1382
  let result = await runScanEvents({
1339
1383
  thread,
@@ -1349,6 +1393,9 @@ export class CodexSecurity {
1349
1393
  modelProvider,
1350
1394
  workbenchValidated: true,
1351
1395
  model,
1396
+ onTurnStatus: (status) => {
1397
+ scanTurnStatus = status;
1398
+ },
1352
1399
  onThreadStarted: async (threadId) => {
1353
1400
  if (resumeThreadId !== undefined && threadId !== resumeThreadId) {
1354
1401
  throw new CodexSecurityError("Codex did not resume the original scan session.");
@@ -1489,6 +1536,8 @@ export class CodexSecurity {
1489
1536
  : ["--cost-json", JSON.stringify(completionCost)]),
1490
1537
  ]);
1491
1538
  activeScan = null;
1539
+ const completedScan = completion["scan"];
1540
+ await finalizeScanUsage(scanId, workbenchOptions, completedScan, "completed");
1492
1541
  if (directDeepScan) {
1493
1542
  result = new ScanResult({
1494
1543
  ...result,
@@ -1498,7 +1547,6 @@ export class CodexSecurity {
1498
1547
  },
1499
1548
  });
1500
1549
  }
1501
- const completedScan = completion["scan"];
1502
1550
  if (isRecord(completedScan) && Array.isArray(completedScan["warnings"])) {
1503
1551
  const targetWarnings = new Set([
1504
1552
  ...preparedTargetWarnings,
@@ -1580,6 +1628,8 @@ export class CodexSecurity {
1580
1628
  notifyObserver(options, "onWarning")(`Could not run post-scan instructions: ${errorMessage(error)}`);
1581
1629
  }
1582
1630
  }
1631
+ if (this.#dependencies.hostedScan !== undefined)
1632
+ return result;
1583
1633
  try {
1584
1634
  const runWorkbench = (args, input) => workbench(workbenchOptions, args, input);
1585
1635
  const previousFindings = await listRepositoryFindings(runWorkbench, targetId, "all");
@@ -1624,6 +1674,7 @@ export class CodexSecurity {
1624
1674
  const snapshot = await costTracker?.stop().catch(() => null);
1625
1675
  if (artifactRestorationFailure !== null)
1626
1676
  throw artifactRestorationFailure;
1677
+ const terminalTurnStatus = terminalScanTurnStatus();
1627
1678
  let failure = signal.reason instanceof ScanCostLimitExceededError
1628
1679
  ? signal.reason
1629
1680
  : error;
@@ -1647,6 +1698,8 @@ export class CodexSecurity {
1647
1698
  JSON.stringify(snapshot?.cost ?? failure.cost),
1648
1699
  `--message=${failure.message.slice(0, 2400)}`,
1649
1700
  ]);
1701
+ if (terminalTurnStatus !== null)
1702
+ await finalizeScanUsage(activeScan.id, activeScan.options, completion["scan"], terminalTurnStatus);
1650
1703
  activeScan = null;
1651
1704
  runPostScan = null;
1652
1705
  const result = await collectResult({
@@ -1675,6 +1728,25 @@ export class CodexSecurity {
1675
1728
  }
1676
1729
  catch { }
1677
1730
  }
1731
+ if (activeScan !== null && scanTurnStatus !== null) {
1732
+ try {
1733
+ const cleanupOptions = { ...activeScan.options, signal: undefined };
1734
+ const saved = await workbench(cleanupOptions, workbenchArgs("get-scan", { scanId: activeScan.id }));
1735
+ const completedScan = saved["scan"];
1736
+ const progress = isRecord(completedScan)
1737
+ ? completedScan["progress"]
1738
+ : undefined;
1739
+ if (isRecord(progress) && progress["status"] === "complete") {
1740
+ const scanId = activeScan.id;
1741
+ activeScan = null;
1742
+ if (terminalTurnStatus !== null)
1743
+ await finalizeScanUsage(scanId, cleanupOptions, completedScan, terminalTurnStatus);
1744
+ }
1745
+ }
1746
+ catch (cleanupError) {
1747
+ notifyObserver(options, "onWarning")(`Could not finalize scan token usage: ${errorMessage(cleanupError)}`);
1748
+ }
1749
+ }
1678
1750
  // A failed attachment must not turn a resumable coordinator into a terminal failure.
1679
1751
  // Deep Scan orchestration persists its own terminal failures and cancellations.
1680
1752
  if (activeScan !== null && options.resumeScanId === undefined) {
@@ -1713,7 +1785,9 @@ export class CodexSecurity {
1713
1785
  }
1714
1786
  if (this.#closed)
1715
1787
  this.#requireOpen();
1716
- if (signal.aborted && !(failure instanceof ScanInterruptedError)) {
1788
+ if (signal.aborted &&
1789
+ !(failure instanceof ScanInterruptedError) &&
1790
+ !(failure instanceof ScanExecutionError)) {
1717
1791
  throwIfAborted(signal, scanDir);
1718
1792
  }
1719
1793
  throw failure;
@@ -1878,6 +1952,86 @@ export class CodexSecurity {
1878
1952
  }
1879
1953
  }
1880
1954
  async #createSessionCodex(session, command, runtimePaths, auth = "auto", git, config, configOverrides = []) {
1955
+ const hosted = this.#dependencies.hostedScan;
1956
+ if (hosted !== undefined) {
1957
+ const environment = {
1958
+ ...definedEnvironment(environmentWithGit(session.runtime.environment, git)),
1959
+ ...runtimePaths,
1960
+ };
1961
+ const model = scanModelConfiguration(session.effectiveConfig);
1962
+ return {
1963
+ environment,
1964
+ // Hosted Standard scans do not launch a local Codex process.
1965
+ codexOptions: {},
1966
+ codex: {
1967
+ startThread: () => {
1968
+ let id = null;
1969
+ return {
1970
+ get id() {
1971
+ return id;
1972
+ },
1973
+ async runStreamed(prompt, { signal }) {
1974
+ const request = {
1975
+ version: 2,
1976
+ requestId: randomUUID(),
1977
+ ...hosted.context,
1978
+ scanId: runtimePaths["CODEX_SECURITY_SCAN_ID"],
1979
+ prompt,
1980
+ ...model,
1981
+ runtime: {
1982
+ pluginRoot: session.runtime.plugin.pluginRoot,
1983
+ pluginVersion: session.runtime.plugin.version,
1984
+ stateDirectory: runtimePaths["CODEX_SECURITY_STATE_DIR"],
1985
+ outputDirectory: runtimePaths["CODEX_SECURITY_SCAN_DIR"],
1986
+ environment,
1987
+ },
1988
+ };
1989
+ // A transport failure is terminal; only the host can reconcile
1990
+ // whether remote execution was accepted.
1991
+ let result;
1992
+ try {
1993
+ result = ScanExecutionResultSchema.parse(await hosted.executor.run(request, {
1994
+ signal: signal ?? new AbortController().signal,
1995
+ onEvent: hosted.onEvent,
1996
+ }));
1997
+ }
1998
+ catch (error) {
1999
+ // Transport failure does not prove non-acceptance. Never resubmit.
2000
+ throw new ScanExecutionError({
2001
+ requestId: request.requestId,
2002
+ status: "acceptance_unknown",
2003
+ message: errorMessage(error),
2004
+ });
2005
+ }
2006
+ if (result.requestId !== request.requestId)
2007
+ throw new ScanExecutionError({
2008
+ ...result,
2009
+ requestId: request.requestId,
2010
+ status: "acceptance_unknown",
2011
+ message: "Execution response does not match the active request.",
2012
+ });
2013
+ if (result.status !== "completed")
2014
+ throw new ScanExecutionError(result);
2015
+ id = result.sessionId;
2016
+ return {
2017
+ events: (async function* () {
2018
+ yield { type: "thread.started", thread_id: id };
2019
+ yield {
2020
+ type: "item.completed",
2021
+ item: {
2022
+ type: "agent_message",
2023
+ text: result.finalResponse ?? "",
2024
+ },
2025
+ };
2026
+ yield { type: "turn.completed", usage: result.usage };
2027
+ })(),
2028
+ };
2029
+ },
2030
+ };
2031
+ },
2032
+ },
2033
+ };
2034
+ }
1881
2035
  const { runtime, runtimeHome, python, modelProvider, externalProvider, apiKey, sessionConfig, } = session;
1882
2036
  const commandAuth = hasCommandAuth(sessionConfig);
1883
2037
  const environment = {
@@ -1952,6 +2106,57 @@ export class CodexSecurity {
1952
2106
  return { codex, environment, codexOptions };
1953
2107
  }
1954
2108
  async #prepareSession({ protectedRoot, protectedRoots = [protectedRoot], }, options, signal, temporaryRoot, deepScan = false) {
2109
+ if (this.#dependencies.hostedScan !== undefined) {
2110
+ // Hosted scans use only the explicitly selected bundle and configuration.
2111
+ // No local auth, Codex subprocess, provider profile, or ambient config.
2112
+ const environment = this.#dependencies.environment;
2113
+ const pluginRoot = await bundledPluginRoot();
2114
+ const metadata = await pluginMetadata(pluginRoot);
2115
+ const effectiveConfig = {
2116
+ // The executor supplies its actual tools and capacity. Local Codex
2117
+ // defaults must not masquerade as hosted runtime capabilities.
2118
+ approval_policy: "never",
2119
+ ...this.config.codexOverrides,
2120
+ };
2121
+ const preflightConfig = scanPreflightCodexConfig(effectiveConfig);
2122
+ const runtimeHome = await createIsolatedHome(temporaryRoot, (path) => requireOutputOutsideRepositories(protectedRoots, path, "runtime"));
2123
+ const configPath = join(runtimeHome, "config-preflight.toml");
2124
+ const runtime = {
2125
+ codexHome: runtimeHome,
2126
+ bootstrapWorkspace: runtimeHome,
2127
+ configPath,
2128
+ credentialsAvailable: false,
2129
+ environment: definedEnvironment(environment),
2130
+ plugin: {
2131
+ ...metadata,
2132
+ pluginRoot,
2133
+ installedRoot: pluginRoot,
2134
+ marketplaceRoot: pluginRoot,
2135
+ marketplaceName: "codex-security-sdk",
2136
+ },
2137
+ };
2138
+ this.#runtime = runtime;
2139
+ await writeCodexConfig(configPath, preflightConfig);
2140
+ const python = await resolvePluginPython({
2141
+ environment,
2142
+ protectedRoot,
2143
+ signal,
2144
+ });
2145
+ return {
2146
+ runtime,
2147
+ runtimeHome,
2148
+ effectiveConfig,
2149
+ preflightConfig,
2150
+ sessionConfig: preflightConfig,
2151
+ modelProvider: "host",
2152
+ externalProvider: null,
2153
+ apiKey: null,
2154
+ scanEnvironment: environment,
2155
+ authentication: { method: "host", verified: false },
2156
+ approvalPolicy: "never",
2157
+ python,
2158
+ };
2159
+ }
1955
2160
  let releaseCredentialHome = null;
1956
2161
  const checkOpen = () => {
1957
2162
  this.#requireOpen();
@@ -2541,6 +2746,10 @@ export async function runScanEvents(options) {
2541
2746
  thread: options.thread,
2542
2747
  events: options.events,
2543
2748
  onEvent: async (event) => {
2749
+ if (event.type === "turn.completed")
2750
+ options.onTurnStatus?.("completed");
2751
+ if (event.type === "turn.failed")
2752
+ options.onTurnStatus?.("failed");
2544
2753
  if (!tacStatusReported &&
2545
2754
  options.modelProvider !== "amazon-bedrock" &&
2546
2755
  options.authentication?.method !== "aws_credentials") {