@openai/codex-security 0.1.5 → 0.1.7

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 (94) hide show
  1. package/README.md +89 -8
  2. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  3. package/_bundled_plugin/.mcp.json +24 -1
  4. package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  6. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  7. package/_bundled_plugin/preflight/capability-profiles.toml +0 -57
  8. package/_bundled_plugin/references/config-preflight.md +1 -1
  9. package/_bundled_plugin/references/final-report.md +15 -7
  10. package/_bundled_plugin/references/scan-artifacts.md +11 -9
  11. package/_bundled_plugin/references/scan-contract.md +3 -1
  12. package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +42 -0
  13. package/_bundled_plugin/schemas/definitions/discovery-candidate.schema.json +100 -0
  14. package/_bundled_plugin/schemas/tools/candidate-attack-paths.schema.json +181 -0
  15. package/_bundled_plugin/schemas/tools/candidate-validations.schema.json +166 -0
  16. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +120 -0
  17. package/_bundled_plugin/schemas/tools/discovery-candidates.schema.json +83 -0
  18. package/_bundled_plugin/schemas/tools/review-items.schema.json +80 -0
  19. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +572 -0
  20. package/_bundled_plugin/schemas/tools/worker-threat-model.schema.json +18 -0
  21. package/_bundled_plugin/scripts/deep_scan_config.py +11 -3
  22. package/_bundled_plugin/scripts/deep_scan_workbench.py +153 -133
  23. package/_bundled_plugin/scripts/finalize_scan_contract.py +21 -0
  24. package/_bundled_plugin/scripts/generate_in_scope_files.py +134 -0
  25. package/_bundled_plugin/scripts/workbench_cli.py +33 -1
  26. package/_bundled_plugin/scripts/workbench_db.py +127 -117
  27. package/_bundled_plugin/scripts/workbench_feedback.py +2 -0
  28. package/_bundled_plugin/scripts/workbench_native_indexes.py +5 -49
  29. package/_bundled_plugin/scripts/workbench_progress.py +86 -3
  30. package/_bundled_plugin/scripts/workbench_remediation.py +19 -1
  31. package/_bundled_plugin/scripts/workbench_scan_history.py +7 -1
  32. package/_bundled_plugin/scripts/workbench_scan_start.py +11 -5
  33. package/_bundled_plugin/scripts/workbench_scan_usage.py +557 -0
  34. package/_bundled_plugin/scripts/workbench_schema.py +501 -0
  35. package/_bundled_plugin/scripts/workbench_validation.py +117 -13
  36. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +4 -4
  37. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +34 -28
  38. package/_bundled_plugin/skills/finding-discovery/SKILL.md +1 -1
  39. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +11 -8
  40. package/_bundled_plugin/skills/security-scan/SKILL.md +16 -9
  41. package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +26 -14
  42. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +1 -1
  43. package/_bundled_plugin/skills/threat-model/SKILL.md +2 -2
  44. package/_bundled_plugin/skills/validation/SKILL.md +5 -5
  45. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +145 -227
  46. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +53 -68
  47. package/dist/api.d.ts +33 -7
  48. package/dist/api.d.ts.map +1 -1
  49. package/dist/api.js +361 -48
  50. package/dist/api.js.map +1 -1
  51. package/dist/auth.js +1 -1
  52. package/dist/auth.js.map +1 -1
  53. package/dist/cli.d.ts +3 -2
  54. package/dist/cli.d.ts.map +1 -1
  55. package/dist/cli.js +477 -40
  56. package/dist/cli.js.map +1 -1
  57. package/dist/config.d.ts +29 -0
  58. package/dist/config.d.ts.map +1 -1
  59. package/dist/config.js +47 -2
  60. package/dist/config.js.map +1 -1
  61. package/dist/cost.d.ts +7 -0
  62. package/dist/cost.d.ts.map +1 -1
  63. package/dist/cost.js +349 -18
  64. package/dist/cost.js.map +1 -1
  65. package/dist/index.d.ts +3 -2
  66. package/dist/index.d.ts.map +1 -1
  67. package/dist/index.js.map +1 -1
  68. package/dist/multiscan.d.ts +1 -0
  69. package/dist/multiscan.d.ts.map +1 -1
  70. package/dist/multiscan.js +3 -0
  71. package/dist/multiscan.js.map +1 -1
  72. package/dist/runtime.d.ts +16 -0
  73. package/dist/runtime.d.ts.map +1 -1
  74. package/dist/runtime.js +540 -25
  75. package/dist/runtime.js.map +1 -1
  76. package/dist/scan-activity.d.ts +13 -0
  77. package/dist/scan-activity.d.ts.map +1 -0
  78. package/dist/scan-activity.js +319 -0
  79. package/dist/scan-activity.js.map +1 -0
  80. package/dist/scan-dashboard.d.ts +47 -0
  81. package/dist/scan-dashboard.d.ts.map +1 -0
  82. package/dist/scan-dashboard.js +444 -0
  83. package/dist/scan-dashboard.js.map +1 -0
  84. package/dist/scan-history-renderer.d.ts.map +1 -1
  85. package/dist/scan-history-renderer.js +4 -1
  86. package/dist/scan-history-renderer.js.map +1 -1
  87. package/dist/version.d.ts +1 -1
  88. package/dist/version.js +1 -1
  89. package/dist/version.js.map +1 -1
  90. package/dist/worker-progress.d.ts +7 -0
  91. package/dist/worker-progress.d.ts.map +1 -1
  92. package/dist/worker-progress.js +68 -0
  93. package/dist/worker-progress.js.map +1 -1
  94. package/package.json +3 -3
package/dist/api.js CHANGED
@@ -1,17 +1,19 @@
1
1
  /// <reference lib="esnext.disposable" preserve="true" />
2
- import { chmod, lstat, mkdir, realpath, rm, writeFile } from "node:fs/promises";
2
+ import { chmod, lstat, mkdir, readFile, realpath, rm, writeFile, } from "node:fs/promises";
3
3
  import { randomUUID } from "node:crypto";
4
4
  import { homedir, tmpdir } from "node:os";
5
5
  import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
6
6
  import { Codex } from "@openai/codex-sdk";
7
+ import { parse as parseToml, stringify as stringifyToml, } from "smol-toml";
7
8
  import { accountStatus, CodexLoginHandle, loginApiKey as persistApiKey, logout as codexLogout, } from "./auth.js";
8
- import { mergedCodexConfig, scanModelConfiguration, writeCodexConfig, } from "./config.js";
9
+ import { EXTERNAL_CODEX_PROVIDERS, isExternalModelProvider, mergedCodexConfig, scanModelConfiguration, scanModelProvider, writeCodexConfig, } from "./config.js";
9
10
  import { estimateScanCost, ScanCostTracker } from "./cost.js";
10
11
  import { loadContract, requireScanFile, } from "./contract.js";
11
12
  import { AuthenticationRequiredError, CodexSecurityError, IncompleteScanError, OutputDirectoryError, OutputInsideProtectedRootError, redactedErrorMessage, ScanCostLimitExceededError, ScanInterruptedError, } from "./errors.js";
12
13
  import { prepareKnowledgeBase, } from "./knowledge-base.js";
13
14
  import { ScanResult } from "./result.js";
14
- import { workerStatusFromEvent, } from "./worker-progress.js";
15
+ import { scanActivitiesFromEvent } from "./scan-activity.js";
16
+ import { scanProgressUpdatesFromEvent, workerStatusFromEvent, } from "./worker-progress.js";
15
17
  import { CODEX_EXECUTABLE_VERSION, CODEX_SDK_VERSION } from "./version.js";
16
18
  import { acquireCodexSecurityCredentialHomeLock, bootstrapPlugin, cleanupSdkDirectory, codexSecurityCredentialAllowsAmbientImport, codexSecurityHasStoredFileCredentials, codexSecurityStateDirectory, createIsolatedHome, importAmbientAuth, prepareCodexSecurityCredentialHome, preserveCodexSecurityPluginRegistration, pluginExecutionEnvironment, planOutputArchive, prepareOutputDir, preparePersistentScanRoot, requireModelSafeOutputDir, resolveCodexCommand, resolvePluginPath, resolvePluginPython, runWorkbench, setCodexSecurityCredentialLogout, validateOutputDir, } from "./runtime.js";
17
19
  import { enclosingGitWorktreeRoot, normalizeRepository, normalizeTarget, repositoryRevision, resolveRepositoryPath, validatedGitEnvironment, validateMode, } from "./targets.js";
@@ -20,6 +22,14 @@ const DEFAULT_DEPENDENCIES = {
20
22
  environment: process.env,
21
23
  };
22
24
  const SCAN_PERMISSION_PROFILE = "codex_security_scan";
25
+ const PERSONAL_TRUSTED_ACCESS_URL = "https://chatgpt.com/cyber";
26
+ const ORGANIZATIONAL_TRUSTED_ACCESS_URL = "https://openai.com/form/enterprise-trusted-access-for-cyber/";
27
+ const DEEP_SCAN_SETTINGS = [
28
+ ["workers", "workers", 1],
29
+ ["subagents", "subagents", 0],
30
+ ["stopAfterNoNew", "stop_after_no_new", 1],
31
+ ["maxDiscoveryRuns", "max_discovery_runs", 1],
32
+ ];
23
33
  export class CodexSecurity {
24
34
  config;
25
35
  metadata = {
@@ -50,6 +60,7 @@ export class CodexSecurity {
50
60
  requireOutputOutsideRepository(inputs.protectedRoot, await realpath(tmpdir()), "temporary");
51
61
  const configuration = await mergedCodexConfig(this.config);
52
62
  const model = scanModelConfiguration(configuration);
63
+ const modelProvider = scanModelProvider(configuration);
53
64
  validateScanCostLimit(options.maxCostUsd, model.model);
54
65
  const archiveDir = options.archiveExisting === true
55
66
  ? await planOutputArchive(inputs.outputDir)
@@ -59,13 +70,15 @@ export class CodexSecurity {
59
70
  repository: inputs.repository,
60
71
  target: inputs.target,
61
72
  mode: inputs.mode,
73
+ ...deepScanOptions(options),
62
74
  ...(options.knowledgeBasePaths?.length
63
75
  ? { knowledgeBasePaths: options.knowledgeBasePaths }
64
76
  : {}),
65
77
  outputDir: inputs.outputDir,
66
78
  ...(archiveDir === null ? {} : { archiveDir }),
67
- authentication: scanAuthentication(this.#dependencies.environment, options.auth),
79
+ authentication: scanAuthentication(this.#dependencies.environment, options.auth, modelProvider),
68
80
  ...model,
81
+ ...(typeof modelProvider === "string" ? { modelProvider } : {}),
69
82
  ...(options.maxCostUsd === undefined
70
83
  ? {}
71
84
  : { maxCostUsd: options.maxCostUsd }),
@@ -87,6 +100,7 @@ export class CodexSecurity {
87
100
  let releaseCredentialHome = null;
88
101
  let scanFailure = false;
89
102
  let completionCost = null;
103
+ let preparedTargetWarnings = [];
90
104
  let activeScan = null;
91
105
  const workbench = this.#dependencies.runWorkbench ?? runWorkbench;
92
106
  try {
@@ -113,26 +127,40 @@ export class CodexSecurity {
113
127
  knowledgeBase = await prepareKnowledgeBase(options.knowledgeBasePaths, signal);
114
128
  }
115
129
  checkOpen();
116
- const authentication = scanAuthentication(this.#dependencies.environment, options.auth);
117
- const scanEnvironment = selectedScanEnvironment(this.#dependencies.environment, options.auth);
130
+ const requestedConfig = await mergedCodexConfig(this.config);
131
+ const modelProvider = scanModelProvider(requestedConfig);
132
+ const externalProvider = isExternalModelProvider(modelProvider)
133
+ ? EXTERNAL_CODEX_PROVIDERS[modelProvider]
134
+ : null;
135
+ let authentication = scanAuthentication(this.#dependencies.environment, options.auth, modelProvider);
136
+ const apiKey = authentication.method === "api_key"
137
+ ? environmentApiKey(this.#dependencies.environment, modelProvider)
138
+ : null;
139
+ if (externalProvider !== null && apiKey === null) {
140
+ throw new AuthenticationRequiredError(`Set ${externalProvider.env_key} to run a scan through ${externalProvider.name}.`);
141
+ }
142
+ const scanEnvironment = selectedScanEnvironment(this.#dependencies.environment, options.auth, modelProvider);
118
143
  if (authentication.method === "stored_credentials" &&
119
144
  this.#dependencies.prepareRuntime === undefined) {
120
145
  const credentialHome = await prepareCodexSecurityCredentialHome(scanEnvironment, (path) => requireOutputOutsideRepository(protectedRoot, path, "runtime"));
121
146
  releaseCredentialHome = await acquireCodexSecurityCredentialHomeLock(credentialHome, signal);
122
147
  }
123
148
  const previousRuntime = this.#runtime;
124
- const runtime = await this.#ensureRuntime(signal, temporaryRoot, (path) => requireOutputOutsideRepository(protectedRoot, path, "runtime"), options.auth);
149
+ const runtime = await this.#ensureRuntime(signal, temporaryRoot, (path) => requireOutputOutsideRepository(protectedRoot, path, "runtime"), options.auth, modelProvider);
125
150
  if (runtime === previousRuntime &&
126
151
  runtime.persistentCredentialHome === true &&
127
152
  this.#dependencies.prepareRuntime === undefined) {
128
153
  await this.#refreshPersistentRuntime(runtime, scanEnvironment, signal);
129
154
  }
130
- const effectiveConfig = runtime.effectiveConfig ?? (await mergedCodexConfig(this.config));
155
+ const effectiveConfig = runtime.effectiveConfig ?? requestedConfig;
131
156
  if (runtime.configPath !== undefined) {
132
157
  await writeCodexConfig(runtime.configPath, scanPreflightCodexConfig(effectiveConfig, repo));
133
158
  }
134
159
  const runtimeHome = await realpath(runtime.codexHome);
135
160
  requireOutputOutsideRepository(protectedRoot, runtimeHome, "runtime");
161
+ if (mode === "deep") {
162
+ await prepareDeepScanConfig(runtimeHome, this.#dependencies.environment, options, signal);
163
+ }
136
164
  if (options.expectedPluginVersion !== undefined &&
137
165
  runtime.plugin.version !== options.expectedPluginVersion) {
138
166
  throw new CodexSecurityError(`The original scan used plugin version ${options.expectedPluginVersion}, but the installed version is ${runtime.plugin.version}.`);
@@ -147,10 +175,7 @@ export class CodexSecurity {
147
175
  ? "stored_credentials"
148
176
  : null;
149
177
  }
150
- const apiKey = authentication.method === "api_key"
151
- ? environmentApiKey(this.#dependencies.environment)
152
- : null;
153
- if (apiKey !== null) {
178
+ if (externalProvider === null && apiKey !== null) {
154
179
  this.#runtimeCredentialSource = "api_key";
155
180
  }
156
181
  if (!runtime.credentialsAvailable &&
@@ -161,11 +186,14 @@ export class CodexSecurity {
161
186
  ? "stored_credentials"
162
187
  : null;
163
188
  }
164
- if (!runtime.credentialsAvailable && apiKey === null) {
189
+ if (!runtime.credentialsAvailable &&
190
+ apiKey === null &&
191
+ authentication.method !== "aws_credentials") {
165
192
  throw new AuthenticationRequiredError("No credentials were found. Run 'codex-security login', use " +
166
193
  "'codex-security login --device-auth' on a remote or headless machine, or set " +
167
194
  "OPENAI_API_KEY or CODEX_API_KEY for CI.");
168
195
  }
196
+ authentication = await runtimeScanAuthentication(this.#dependencies.environment, runtime.codexHome, options.auth, modelProvider);
169
197
  notifyObserver("onAuthentication", options.onAuthentication, options.onObserverError, authentication);
170
198
  const python = await (this.#dependencies.resolvePluginPython ?? resolvePluginPython)({
171
199
  configuredPath: this.config.pythonPath,
@@ -209,10 +237,26 @@ export class CodexSecurity {
209
237
  };
210
238
  const { model } = scanModelConfiguration(effectiveConfig);
211
239
  validateScanCostLimit(options.maxCostUsd, model);
240
+ let scopeFileCount = null;
241
+ let reviewedFileCount = 0;
242
+ const reportProgress = (progress) => {
243
+ if (scopeFileCount === null ||
244
+ progress.filesTotal > scopeFileCount ||
245
+ progress.filesCompleted < reviewedFileCount) {
246
+ return;
247
+ }
248
+ reviewedFileCount = progress.filesCompleted;
249
+ notifyObserver("onProgress", options.onProgress, options.onObserverError, { ...progress, filesTotal: scopeFileCount });
250
+ };
212
251
  const tracker = new ScanCostTracker({
213
252
  codexHome: runtime.codexHome,
214
253
  model,
254
+ repository: repo,
215
255
  maxCostUsd: options.maxCostUsd,
256
+ onActivity: (activity) => {
257
+ notifyObserver("onActivity", options.onActivity, options.onObserverError, activity);
258
+ },
259
+ onProgress: reportProgress,
216
260
  onCost: (cost) => {
217
261
  notifyObserver("onCost", options.onCost, options.onObserverError, cost);
218
262
  if (options.maxCostUsd !== undefined &&
@@ -223,12 +267,12 @@ export class CodexSecurity {
223
267
  onError: (error) => costAbortController.abort(error),
224
268
  });
225
269
  costTracker = tracker;
226
- const recipe = scanRecipe(repo, protectedRoot, normalized, mode, expectation.repositoryRevision, runtime.plugin.version, effectiveConfig, options.failureSeverity, knowledgeBase?.sources, options.maxCostUsd);
270
+ const recipe = scanRecipe(repo, protectedRoot, normalized, mode, expectation.repositoryRevision, runtime.plugin.version, effectiveConfig, options.failureSeverity, knowledgeBase?.sources, options.maxCostUsd, deepScanOptions(options));
227
271
  const workbenchOptions = {
228
272
  python,
229
273
  pluginRoot: runtime.plugin.pluginRoot,
230
274
  environment: {
231
- ...selectedScanEnvironment(runtime.environment, options.auth),
275
+ ...selectedScanEnvironment(runtime.environment, options.auth, modelProvider),
232
276
  CODEX_SECURITY_STATE_DIR: stateDirectory,
233
277
  },
234
278
  signal,
@@ -289,6 +333,21 @@ export class CodexSecurity {
289
333
  throw new CodexSecurityError("The Codex Security workbench returned an invalid scan registration.");
290
334
  }
291
335
  const targetRevision = registeredRevision === "unversioned" ? null : registeredRevision;
336
+ const registeredFileCount = registration["scopeFileCount"];
337
+ scopeFileCount =
338
+ typeof registeredFileCount === "number" &&
339
+ Number.isSafeInteger(registeredFileCount) &&
340
+ registeredFileCount >= 0
341
+ ? registeredFileCount
342
+ : null;
343
+ if (scopeFileCount !== null) {
344
+ tracker.setExpectedFilesTotal(scopeFileCount);
345
+ notifyObserver("onProgress", options.onProgress, options.onObserverError, {
346
+ phase: "preflight",
347
+ filesCompleted: 0,
348
+ filesTotal: scopeFileCount,
349
+ });
350
+ }
292
351
  activeScan = { id: scanId, options: workbenchOptions };
293
352
  checkOpen();
294
353
  const feedback = await workbench({
@@ -350,12 +409,15 @@ export class CodexSecurity {
350
409
  : { CODEX_SECURITY_TARGET_PATHS_FILE: targetPathsFile }),
351
410
  };
352
411
  const environment = {
353
- ...pluginExecutionEnvironment(python, withoutCodexHome(selectedScanEnvironment(runtime.environment, options.auth))),
412
+ ...pluginExecutionEnvironment(python, withoutCodexHome(selectedScanEnvironment(runtime.environment, options.auth, modelProvider))),
413
+ ...(externalProvider === null
414
+ ? {}
415
+ : { [externalProvider.env_key]: apiKey }),
354
416
  CODEX_HOME: runtime.codexHome,
355
417
  ...runtimePaths,
356
418
  };
357
419
  const codex = this.#dependencies.createCodex({
358
- ...(apiKey === null ? {} : { apiKey }),
420
+ ...(externalProvider !== null || apiKey === null ? {} : { apiKey }),
359
421
  env: definedEnvironment(selectedScanEnvironment(environment, "chatgpt")),
360
422
  config: {
361
423
  default_permissions: SCAN_PERMISSION_PROFILE,
@@ -394,6 +456,7 @@ export class CodexSecurity {
394
456
  scanDir,
395
457
  pluginRoot: runtime.plugin.installedRoot,
396
458
  expectation,
459
+ authentication,
397
460
  workbenchValidated: true,
398
461
  model,
399
462
  onThreadStarted: (threadId) => tracker.start(threadId),
@@ -404,16 +467,32 @@ export class CodexSecurity {
404
467
  notifyObserver("onWarning", options.onWarning, options.onObserverError, "Scan completed, but its cost limit could not be verified because model pricing or token usage is unavailable.");
405
468
  }
406
469
  completionCost = snapshot.cost;
407
- await workbench(workbenchOptions, [
470
+ const preparation = await workbench(workbenchOptions, [
408
471
  "prepare-scan-completion",
409
472
  "--scan-id",
410
473
  scanId,
411
474
  ]);
475
+ preparedTargetWarnings = Array.isArray(preparation["targetWarnings"])
476
+ ? preparation["targetWarnings"].filter((warning) => typeof warning === "string")
477
+ : [];
412
478
  return snapshot.usage;
413
479
  },
414
480
  onScanStarted: options.onScanStarted,
481
+ onTrustedAccessStatus: options.onTrustedAccessStatus,
415
482
  onReconnect: options.onReconnect,
483
+ onActivity: options.onActivity,
484
+ onProgress: (progress) => {
485
+ if (progress.phase === "discovery" &&
486
+ progress.filesCompleted === 0 &&
487
+ reviewedFileCount === 0 &&
488
+ progress.filesTotal !== scopeFileCount) {
489
+ scopeFileCount = progress.filesTotal;
490
+ tracker.setExpectedFilesTotal(scopeFileCount);
491
+ }
492
+ reportProgress(progress);
493
+ },
416
494
  onWorkerStatus: options.onWorkerStatus,
495
+ onWarning: options.onWarning,
417
496
  onObserverError: options.onObserverError,
418
497
  });
419
498
  checkOpen();
@@ -428,9 +507,17 @@ export class CodexSecurity {
428
507
  activeScan = null;
429
508
  const completedScan = completion["scan"];
430
509
  if (isRecord(completedScan) && Array.isArray(completedScan["warnings"])) {
510
+ const targetWarnings = new Set([
511
+ ...preparedTargetWarnings,
512
+ ...(Array.isArray(completion["targetWarnings"])
513
+ ? completion["targetWarnings"].filter((warning) => typeof warning === "string")
514
+ : []),
515
+ ]);
431
516
  for (const warning of completedScan["warnings"]) {
432
517
  if (typeof warning === "string") {
433
- notifyObserver("onWarning", options.onWarning, options.onObserverError, warning);
518
+ notifyObserver("onWarning", options.onWarning, options.onObserverError, warning, targetWarnings.has(warning)
519
+ ? { kind: "target_changed" }
520
+ : undefined);
434
521
  }
435
522
  }
436
523
  }
@@ -632,11 +719,11 @@ export class CodexSecurity {
632
719
  }
633
720
  }
634
721
  }
635
- async #ensureRuntime(signal, temporaryRoot, validateLocation, auth = "auto") {
722
+ async #ensureRuntime(signal, temporaryRoot, validateLocation, auth = "auto", modelProvider) {
636
723
  this.#requireOpen();
637
724
  if (this.#runtime !== null) {
638
- const usePersistentCredentials = scanAuthentication(this.#dependencies.environment, auth).method ===
639
- "stored_credentials";
725
+ const usePersistentCredentials = scanAuthentication(this.#dependencies.environment, auth, modelProvider)
726
+ .method === "stored_credentials";
640
727
  if (this.#dependencies.prepareRuntime !== undefined ||
641
728
  this.#runtime.persistentCredentialHome === undefined ||
642
729
  this.#runtime.persistentCredentialHome === usePersistentCredentials) {
@@ -649,7 +736,7 @@ export class CodexSecurity {
649
736
  this.#requireOpen();
650
737
  }
651
738
  if (this.#runtimePromise === null) {
652
- const runtimePromise = this.#prepareRuntime(signal ?? this.#abortController.signal, temporaryRoot, validateLocation, auth);
739
+ const runtimePromise = this.#prepareRuntime(signal ?? this.#abortController.signal, temporaryRoot, validateLocation, auth, modelProvider);
653
740
  this.#runtimePromise = runtimePromise;
654
741
  void runtimePromise.catch(() => {
655
742
  if (this.#runtimePromise === runtimePromise) {
@@ -688,6 +775,7 @@ export class CodexSecurity {
688
775
  runtime.effectiveConfig = mergedConfig;
689
776
  }
690
777
  async #validateLocalInputs(repository, options, signal) {
778
+ deepScanOptions(options);
691
779
  if (options.maxCostUsd !== undefined &&
692
780
  (!Number.isFinite(options.maxCostUsd) || options.maxCostUsd <= 0)) {
693
781
  throw new CodexSecurityError("The scan cost limit must be a positive USD amount.");
@@ -714,13 +802,13 @@ export class CodexSecurity {
714
802
  protectedRoot,
715
803
  };
716
804
  }
717
- async #prepareRuntime(signal, temporaryRoot, validateLocation, auth = "auto") {
805
+ async #prepareRuntime(signal, temporaryRoot, validateLocation, auth = "auto", modelProvider) {
718
806
  if (this.#dependencies.prepareRuntime !== undefined) {
719
807
  return await this.#dependencies.prepareRuntime(this.config, signal);
720
808
  }
721
- const processEnvironment = selectedScanEnvironment(this.#dependencies.environment, auth);
722
- const persistentCredentialHome = scanAuthentication(this.#dependencies.environment, auth).method ===
723
- "stored_credentials";
809
+ const processEnvironment = selectedScanEnvironment(this.#dependencies.environment, auth, modelProvider);
810
+ const persistentCredentialHome = scanAuthentication(this.#dependencies.environment, auth, modelProvider)
811
+ .method === "stored_credentials";
724
812
  const codexHome = persistentCredentialHome
725
813
  ? await prepareCodexSecurityCredentialHome(processEnvironment, validateLocation)
726
814
  : await createIsolatedHome(temporaryRoot, validateLocation);
@@ -742,7 +830,10 @@ export class CodexSecurity {
742
830
  environment: withoutCodexHome(processEnvironment),
743
831
  signal,
744
832
  });
745
- const credentialsAvailable = await initialCredentialsAvailable(processEnvironment, ambientHome, codexHome);
833
+ const credentialsAvailable = isExternalModelProvider(modelProvider) ||
834
+ modelProvider === "amazon-bedrock"
835
+ ? false
836
+ : await initialCredentialsAvailable(processEnvironment, ambientHome, codexHome);
746
837
  return {
747
838
  codexHome,
748
839
  persistentCredentialHome,
@@ -774,6 +865,60 @@ export class CodexSecurity {
774
865
  throw new CodexSecurityError("CodexSecurity is closed.");
775
866
  }
776
867
  }
868
+ function deepScanOptions(options) {
869
+ const selected = {};
870
+ for (const [name, , minimum] of DEEP_SCAN_SETTINGS) {
871
+ const value = options[name];
872
+ if (value === undefined)
873
+ continue;
874
+ if ((options.mode ?? "standard") !== "deep") {
875
+ throw new CodexSecurityError("Deep scan settings require deep mode.");
876
+ }
877
+ if (!Number.isSafeInteger(value) || value < minimum) {
878
+ throw new CodexSecurityError(`Deep scan ${name} must be ${minimum === 0 ? "a non-negative" : "a positive"} integer.`);
879
+ }
880
+ selected[name] = value;
881
+ }
882
+ return selected;
883
+ }
884
+ async function prepareDeepScanConfig(codexHome, environment, options, signal) {
885
+ const ambientHome = environmentValue(environment, "CODEX_HOME") ?? join(homedir(), ".codex");
886
+ const source = join(ambientHome, "codex-security", "config.toml");
887
+ let configured = {};
888
+ try {
889
+ configured = parseToml(await readFile(source, { encoding: "utf8", signal }));
890
+ }
891
+ catch (error) {
892
+ if (!isRecord(error) || error["code"] !== "ENOENT") {
893
+ throw new CodexSecurityError(`Cannot read Codex Security configuration at ${source}.`, { cause: error });
894
+ }
895
+ }
896
+ const existing = configured["deep_scan"];
897
+ if (existing !== undefined && !isRecord(existing)) {
898
+ throw new CodexSecurityError(`Codex Security configuration [deep_scan] at ${source} must be a TOML table.`);
899
+ }
900
+ const overrides = {};
901
+ for (const [name, key] of DEEP_SCAN_SETTINGS) {
902
+ const value = options[name];
903
+ if (value !== undefined)
904
+ overrides[key] = value;
905
+ }
906
+ const destination = join(codexHome, "codex-security", "config.toml");
907
+ const hasOverrides = Object.keys(overrides).length > 0;
908
+ if (existing === undefined && !hasOverrides) {
909
+ if (destination !== source) {
910
+ await rm(destination, { force: true });
911
+ }
912
+ return;
913
+ }
914
+ if (destination === source && !hasOverrides)
915
+ return;
916
+ await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
917
+ await writeFile(destination, stringifyToml({
918
+ ...configured,
919
+ deep_scan: { ...existing, ...overrides },
920
+ }), { mode: 0o600, signal });
921
+ }
777
922
  export async function initialCredentialsAvailable(environment, ambientHome, isolatedHome, importer = importAmbientAuth) {
778
923
  if (environmentApiKey(environment) !== null)
779
924
  return false;
@@ -818,8 +963,29 @@ export async function runScanEvents(options) {
818
963
  let finalResponse = "";
819
964
  let usage = null;
820
965
  let lastStreamError = null;
966
+ let tacStatusReported = false;
821
967
  try {
822
968
  for await (const event of options.events) {
969
+ if (!tacStatusReported) {
970
+ const tacStatus = trustedAccessStatusFromEvent(event);
971
+ if (tacStatus !== null) {
972
+ tacStatusReported = true;
973
+ notifyObserver("onTrustedAccessStatus", options.onTrustedAccessStatus, options.onObserverError, tacStatus);
974
+ if (tacStatus !== "granted") {
975
+ notifyObserver("onWarning", options.onWarning, options.onObserverError, trustedAccessWarning(tacStatus, options.authentication));
976
+ }
977
+ }
978
+ }
979
+ for (const activity of scanActivitiesFromEvent(event, options.expectation.repository)) {
980
+ notifyObserver("onActivity", options.onActivity, options.onObserverError, activity);
981
+ }
982
+ for (const progress of scanProgressUpdatesFromEvent(event)) {
983
+ if (options.expectedFilesTotal !== undefined &&
984
+ progress.filesTotal !== options.expectedFilesTotal) {
985
+ continue;
986
+ }
987
+ notifyObserver("onProgress", options.onProgress, options.onObserverError, progress);
988
+ }
823
989
  const workerStatus = workerStatusFromEvent(event);
824
990
  if (workerStatus !== null) {
825
991
  notifyObserver("onWorkerStatus", options.onWorkerStatus, options.onObserverError, workerStatus);
@@ -897,6 +1063,68 @@ export async function runScanEvents(options) {
897
1063
  throw error;
898
1064
  }
899
1065
  }
1066
+ function trustedAccessStatusFromEvent(event) {
1067
+ if (event.type !== "item.completed" || !isRecord(event["item"])) {
1068
+ return null;
1069
+ }
1070
+ const item = event["item"];
1071
+ if (item["type"] !== "mcp_tool_call" ||
1072
+ item["server"] !== "codex_apps" ||
1073
+ item["tool"] !== "get_tac_status") {
1074
+ return null;
1075
+ }
1076
+ if (item["status"] !== "completed" || !isRecord(item["result"])) {
1077
+ return "unknown";
1078
+ }
1079
+ const result = item["result"]["structured_content"];
1080
+ if (!isRecord(result) ||
1081
+ result["schemaVersion"] !== 1 ||
1082
+ !Array.isArray(result["grants"]) ||
1083
+ typeof result["checkedAt"] !== "string" ||
1084
+ Number.isNaN(Date.parse(result["checkedAt"])) ||
1085
+ result["stale"] !== false) {
1086
+ return "unknown";
1087
+ }
1088
+ const status = result["status"];
1089
+ if (status !== "granted" &&
1090
+ status !== "not_granted" &&
1091
+ status !== "unknown") {
1092
+ return "unknown";
1093
+ }
1094
+ if (result["grants"].some((grant) => !isTrustedAccessGrant(grant)) ||
1095
+ (status === "granted") !== result["grants"].length > 0) {
1096
+ return "unknown";
1097
+ }
1098
+ return status;
1099
+ }
1100
+ function isTrustedAccessGrant(grant) {
1101
+ if (!isRecord(grant))
1102
+ return false;
1103
+ const level = grant["level"];
1104
+ const source = grant["source"];
1105
+ return ((source === "user" && (level === "tac1" || level === "tac2")) ||
1106
+ (source === "current_account" &&
1107
+ (level === "tac1" || level === "tac3" || level === "government")));
1108
+ }
1109
+ function trustedAccessWarning(status, authentication) {
1110
+ const apiOrganization = (authentication?.method === "api_key" &&
1111
+ (authentication.source === "OPENAI_API_KEY" ||
1112
+ authentication.source === "CODEX_API_KEY")) ||
1113
+ (authentication?.method === "stored_credentials" &&
1114
+ authentication.credentialType === "api_key");
1115
+ const applicationUrl = apiOrganization
1116
+ ? ORGANIZATIONAL_TRUSTED_ACCESS_URL
1117
+ : PERSONAL_TRUSTED_ACCESS_URL;
1118
+ if (status === "not_granted") {
1119
+ const account = apiOrganization ? "your API organization" : "your account";
1120
+ return `Some cybersecurity requests or findings may be refused because ${account} does not have Trusted Access for Cyber. Apply at ${applicationUrl}.`;
1121
+ }
1122
+ const access = apiOrganization
1123
+ ? "Trusted Access for Cyber for your API organization"
1124
+ : "your Trusted Access for Cyber status";
1125
+ const action = apiOrganization ? "your organization's access" : "your access";
1126
+ return `Some cybersecurity requests or findings may be refused because ${access} could not be verified. Check ${action} or apply at ${applicationUrl}.`;
1127
+ }
900
1128
  async function scanPrompt(pluginRoot, target, mode, hasConfigPath = false, hasKnowledgeBase = false) {
901
1129
  const skillName = skillNameFor(target, mode);
902
1130
  const skillPath = join(pluginRoot, "skills", skillName, "SKILL.md");
@@ -907,6 +1135,11 @@ async function scanPrompt(pluginRoot, target, mode, hasConfigPath = false, hasKn
907
1135
  return [
908
1136
  `Use the installed $codex-security:${skillName} skill at "$CODEX_SECURITY_PLUGIN_ROOT/skills/${skillName}/SKILL.md".`,
909
1137
  "Run this Codex Security scan non-interactively.",
1138
+ ...(mode === "deep"
1139
+ ? [
1140
+ 'The SDK has already registered this scan. Call start_codex_security_deep_scan with { scanId: "$CODEX_SECURITY_SCAN_ID" }; never pass targetPath or create another scan.',
1141
+ ]
1142
+ : []),
910
1143
  ...(skillName === "deep-security-scan"
911
1144
  ? []
912
1145
  : [
@@ -923,6 +1156,8 @@ async function scanPrompt(pluginRoot, target, mode, hasConfigPath = false, hasKn
923
1156
  'When "$CODEX_SECURITY_TARGET_REVISION" is set, use its exact value as scan.target.revision.',
924
1157
  'When "$CODEX_SECURITY_TARGET_SNAPSHOT_DIGEST" is set, use its exact value as scan.target.snapshotDigest. For git_revision, omit scan.target.snapshotDigest.',
925
1158
  'Use exactly "codex-security-plugin" as scan.producer.name.',
1159
+ 'After the file inventory, after each fully reviewed file batch, and when entering each later phase, emit one standalone CODEX_SECURITY_SCAN_PROGRESS {"phase":"discovery","filesCompleted":3,"filesTotal":8} line in a completed command output or agent message. Use the actual phase and file counts. Never count unread or partially reviewed files.',
1160
+ 'Every delegated review assignment must say: After each completed batch, emit CODEX_SECURITY_SCAN_PROGRESS {"phase":"discovery","filesCompleted":3,"filesTotal":8} on its own line using your worker-local reviewed and assigned file counts.',
926
1161
  ...(hasConfigPath
927
1162
  ? [
928
1163
  'For normal config-preflight helper calls, append --config "$CODEX_SECURITY_CONFIG_PATH" so preflight reads the sanitized active runtime config. Preserve the documented runtime and --effective-config arguments for session-only values.',
@@ -959,7 +1194,7 @@ function targetInstruction(target) {
959
1194
  }
960
1195
  return `Scan target: staged and unstaged working-tree changes against ${target.base}.`;
961
1196
  }
962
- function scanRecipe(repository, activeProjectPath, target, mode, repositoryRevision, pluginVersion, effectiveConfig, failOnSeverity, knowledgeBasePaths, maxCostUsd) {
1197
+ function scanRecipe(repository, activeProjectPath, target, mode, repositoryRevision, pluginVersion, effectiveConfig, failOnSeverity, knowledgeBasePaths, maxCostUsd, deepScan) {
963
1198
  return {
964
1199
  repository,
965
1200
  target: {
@@ -977,6 +1212,9 @@ function scanRecipe(repository, activeProjectPath, target, mode, repositoryRevis
977
1212
  ...(failOnSeverity === undefined ? {} : { failOnSeverity }),
978
1213
  ...(knowledgeBasePaths === undefined ? {} : { knowledgeBasePaths }),
979
1214
  ...(maxCostUsd === undefined ? {} : { maxCostUsd }),
1215
+ ...(deepScan === undefined || Object.keys(deepScan).length === 0
1216
+ ? {}
1217
+ : { deepScan: { ...deepScan } }),
980
1218
  };
981
1219
  }
982
1220
  function validateScanCostLimit(maxCostUsd, model) {
@@ -1031,12 +1269,30 @@ async function collectResult(turnResult, threadId, scanDir, pluginRoot, expectat
1031
1269
  sarifPath,
1032
1270
  });
1033
1271
  }
1034
- export function scanAuthentication(environment, auth = "auto") {
1035
- if (auth === "chatgpt") {
1272
+ export function scanAuthentication(environment, auth = "auto", modelProvider) {
1273
+ if (modelProvider === "amazon-bedrock") {
1274
+ const sources = [
1275
+ "AWS_BEARER_TOKEN_BEDROCK",
1276
+ "AWS_ACCESS_KEY_ID",
1277
+ "AWS_PROFILE",
1278
+ "AWS_WEB_IDENTITY_TOKEN_FILE",
1279
+ "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI",
1280
+ "AWS_CONTAINER_CREDENTIALS_FULL_URI",
1281
+ ];
1282
+ const source = sources.find((name) => environmentValue(environment, name));
1283
+ return {
1284
+ method: "aws_credentials",
1285
+ source: source ?? "default_credential_chain",
1286
+ verified: false,
1287
+ };
1288
+ }
1289
+ if (auth === "chatgpt" && !isExternalModelProvider(modelProvider)) {
1036
1290
  return { method: "stored_credentials", verified: false };
1037
1291
  }
1038
- const key = environmentApiKeyEntry(environment);
1039
- if (auth === "api-key" && key === null) {
1292
+ const key = environmentApiKeyEntry(environment, modelProvider);
1293
+ if (auth === "api-key" &&
1294
+ key === null &&
1295
+ !isExternalModelProvider(modelProvider)) {
1040
1296
  throw new AuthenticationRequiredError("API-key authentication requires OPENAI_API_KEY or CODEX_API_KEY. " +
1041
1297
  "Set a valid API key or use '--auth chatgpt'.");
1042
1298
  }
@@ -1044,11 +1300,45 @@ export function scanAuthentication(environment, auth = "auto") {
1044
1300
  ? { method: "stored_credentials", verified: false }
1045
1301
  : { method: "api_key", source: key.source, verified: false };
1046
1302
  }
1047
- function selectedScanEnvironment(environment, auth = "auto") {
1048
- if (auth !== "chatgpt")
1303
+ async function runtimeScanAuthentication(environment, codexHome, auth = "auto", modelProvider) {
1304
+ const authentication = scanAuthentication(environment, auth, modelProvider);
1305
+ if (authentication.method !== "stored_credentials")
1306
+ return authentication;
1307
+ try {
1308
+ const stored = JSON.parse(await readFile(join(codexHome, "auth.json"), "utf8"));
1309
+ if (!isRecord(stored))
1310
+ return authentication;
1311
+ const mode = stored["auth_mode"];
1312
+ if (mode === "apikey" || mode === "api_key") {
1313
+ return { ...authentication, credentialType: "api_key" };
1314
+ }
1315
+ if (mode === "chatgpt") {
1316
+ return { ...authentication, credentialType: "chatgpt" };
1317
+ }
1318
+ }
1319
+ catch {
1320
+ return authentication;
1321
+ }
1322
+ return authentication;
1323
+ }
1324
+ function selectedScanEnvironment(environment, auth = "auto", modelProvider) {
1325
+ const selectedProviderKey = isExternalModelProvider(modelProvider)
1326
+ ? EXTERNAL_CODEX_PROVIDERS[modelProvider].env_key
1327
+ : null;
1328
+ const bedrockProvider = modelProvider === "amazon-bedrock";
1329
+ if (auth !== "chatgpt" && selectedProviderKey === null && !bedrockProvider) {
1049
1330
  return environment;
1050
- return Object.fromEntries(Object.entries(environment).filter(([name]) => name.toUpperCase() !== "OPENAI_API_KEY" &&
1051
- name.toUpperCase() !== "CODEX_API_KEY"));
1331
+ }
1332
+ return Object.fromEntries(Object.entries(environment).filter(([name]) => {
1333
+ const key = name.toUpperCase();
1334
+ if (key === "OPENAI_API_KEY" || key === "CODEX_API_KEY")
1335
+ return false;
1336
+ if (key === "OPENROUTER_API_KEY" || key === "FIREWORKS_API_KEY") {
1337
+ return (!bedrockProvider &&
1338
+ (selectedProviderKey === null || key === selectedProviderKey));
1339
+ }
1340
+ return true;
1341
+ }));
1052
1342
  }
1053
1343
  function notifyObserver(observerName, observer, onObserverError, ...args) {
1054
1344
  void Promise.resolve()
@@ -1056,18 +1346,17 @@ function notifyObserver(observerName, observer, onObserverError, ...args) {
1056
1346
  .catch((error) => onObserverError?.(observerName, error))
1057
1347
  .catch(() => { });
1058
1348
  }
1059
- function environmentApiKey(environment) {
1060
- return environmentApiKeyEntry(environment)?.value ?? null;
1349
+ function environmentApiKey(environment, modelProvider) {
1350
+ return environmentApiKeyEntry(environment, modelProvider)?.value ?? null;
1061
1351
  }
1062
- function environmentApiKeyEntry(environment) {
1063
- for (const requested of ["OPENAI_API_KEY", "CODEX_API_KEY"]) {
1064
- const canonical = environment[requested]?.trim();
1065
- if (canonical)
1066
- return { source: requested, value: canonical };
1067
- for (const [name, value] of Object.entries(environment)) {
1068
- if (name.toUpperCase() === requested && value?.trim())
1069
- return { source: requested, value: value.trim() };
1070
- }
1352
+ function environmentApiKeyEntry(environment, modelProvider) {
1353
+ const keys = isExternalModelProvider(modelProvider)
1354
+ ? [EXTERNAL_CODEX_PROVIDERS[modelProvider].env_key]
1355
+ : ["OPENAI_API_KEY", "CODEX_API_KEY"];
1356
+ for (const requested of keys) {
1357
+ const value = environmentValue(environment, requested)?.trim();
1358
+ if (value)
1359
+ return { source: requested, value };
1071
1360
  }
1072
1361
  return null;
1073
1362
  }
@@ -1272,6 +1561,30 @@ export function scanPreflightCodexConfig(config, activeProjectPath) {
1272
1561
  if (Object.keys(sanitized).length > 0)
1273
1562
  result["profiles"] = sanitized;
1274
1563
  }
1564
+ const modelProvider = scanModelProvider(result);
1565
+ if (isExternalModelProvider(modelProvider)) {
1566
+ result["model_providers"] = {
1567
+ [modelProvider]: { ...EXTERNAL_CODEX_PROVIDERS[modelProvider] },
1568
+ };
1569
+ }
1570
+ else if (modelProvider === "amazon-bedrock") {
1571
+ const providers = config["model_providers"];
1572
+ const provider = isRecord(providers) ? providers[modelProvider] : undefined;
1573
+ const aws = isRecord(provider) ? provider["aws"] : undefined;
1574
+ if (isRecord(aws)) {
1575
+ const sanitized = {};
1576
+ for (const key of ["region", "profile"]) {
1577
+ const value = aws[key];
1578
+ if (safeString(value, 512))
1579
+ sanitized[key] = value;
1580
+ }
1581
+ if (Object.keys(sanitized).length > 0) {
1582
+ result["model_providers"] = {
1583
+ [modelProvider]: { aws: sanitized },
1584
+ };
1585
+ }
1586
+ }
1587
+ }
1275
1588
  const rootMarkers = config["project_root_markers"];
1276
1589
  if (Array.isArray(rootMarkers)) {
1277
1590
  result["project_root_markers"] = rootMarkers