@openai/codex-security 0.1.9 → 0.1.10

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 (61) hide show
  1. package/README.md +16 -5
  2. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  3. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/preflight/capability-profiles.toml +1 -1
  6. package/_bundled_plugin/references/scan-contract.md +1 -1
  7. package/_bundled_plugin/scripts/deep_scan_workbench.py +22 -0
  8. package/_bundled_plugin/scripts/generate_in_scope_files.py +102 -1
  9. package/_bundled_plugin/scripts/normalize_candidates.py +20 -2
  10. package/_bundled_plugin/scripts/workbench_cli.py +4 -0
  11. package/_bundled_plugin/scripts/workbench_db.py +12 -0
  12. package/_bundled_plugin/scripts/workbench_native_indexes.py +100 -43
  13. package/_bundled_plugin/skills/finding-discovery/SKILL.md +8 -4
  14. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +21 -140
  15. package/dist/api.d.ts +42 -3
  16. package/dist/api.d.ts.map +1 -1
  17. package/dist/api.js +103 -44
  18. package/dist/api.js.map +1 -1
  19. package/dist/cli.d.ts +1 -1
  20. package/dist/cli.d.ts.map +1 -1
  21. package/dist/cli.js +93 -39
  22. package/dist/cli.js.map +1 -1
  23. package/dist/cost.d.ts +1 -0
  24. package/dist/cost.d.ts.map +1 -1
  25. package/dist/cost.js +1 -1
  26. package/dist/cost.js.map +1 -1
  27. package/dist/errors.d.ts +4 -2
  28. package/dist/errors.d.ts.map +1 -1
  29. package/dist/errors.js +10 -46
  30. package/dist/errors.js.map +1 -1
  31. package/dist/index.d.ts +2 -2
  32. package/dist/index.d.ts.map +1 -1
  33. package/dist/index.js +1 -1
  34. package/dist/index.js.map +1 -1
  35. package/dist/multiscan.js +2 -2
  36. package/dist/multiscan.js.map +1 -1
  37. package/dist/result.d.ts +13 -1
  38. package/dist/result.d.ts.map +1 -1
  39. package/dist/result.js +3 -0
  40. package/dist/result.js.map +1 -1
  41. package/dist/runtime.js +3 -3
  42. package/dist/runtime.js.map +1 -1
  43. package/dist/scan-comparison.d.ts +14 -0
  44. package/dist/scan-comparison.d.ts.map +1 -1
  45. package/dist/scan-comparison.js +89 -0
  46. package/dist/scan-comparison.js.map +1 -1
  47. package/dist/scan-dashboard.d.ts.map +1 -1
  48. package/dist/scan-dashboard.js +1 -0
  49. package/dist/scan-dashboard.js.map +1 -1
  50. package/dist/scan-history-renderer.d.ts +1 -1
  51. package/dist/scan-history-renderer.d.ts.map +1 -1
  52. package/dist/scan-history-renderer.js +10 -0
  53. package/dist/scan-history-renderer.js.map +1 -1
  54. package/dist/scan-logs.d.ts +17 -0
  55. package/dist/scan-logs.d.ts.map +1 -0
  56. package/dist/scan-logs.js +90 -0
  57. package/dist/scan-logs.js.map +1 -0
  58. package/dist/version.d.ts +1 -1
  59. package/dist/version.js +1 -1
  60. package/dist/version.js.map +1 -1
  61. package/package.json +2 -2
package/dist/api.js CHANGED
@@ -9,13 +9,14 @@ import { accountStatus, CodexLoginHandle, loginApiKey as persistApiKey, logout a
9
9
  import { EXTERNAL_CODEX_PROVIDERS, isExternalModelProvider, mergedCodexConfig, scanModelConfiguration, scanModelProvider, writeCodexConfig, } from "./config.js";
10
10
  import { estimateScanCost, ScanCostTracker } from "./cost.js";
11
11
  import { loadContract, requireScanFile, } from "./contract.js";
12
- import { AuthenticationRequiredError, CodexSecurityError, IncompleteScanError, OutputDirectoryError, OutputInsideProtectedRootError, redactedErrorMessage, ScanCostLimitExceededError, ScanInterruptedError, } from "./errors.js";
12
+ import { AuthenticationRequiredError, CodexSecurityError, IncompleteScanError, OutputDirectoryError, OutputInsideProtectedRootError, errorMessage, safeErrorMessage, ScanCostLimitExceededError, ScanInterruptedError, } from "./errors.js";
13
13
  import { prepareKnowledgeBase, } from "./knowledge-base.js";
14
- import { ScanResult } from "./result.js";
14
+ import { ScanResult, } from "./result.js";
15
15
  import { scanActivitiesFromEvent } from "./scan-activity.js";
16
+ import { matchCompletedScan, } from "./scan-comparison.js";
16
17
  import { scanProgressUpdatesFromEvent, workerStatusFromEvent, } from "./worker-progress.js";
17
18
  import { CODEX_EXECUTABLE_VERSION, CODEX_SDK_VERSION } from "./version.js";
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";
19
+ import { acquireCodexSecurityCredentialHomeLock, bootstrapPlugin, cleanupSdkDirectory, codexSecurityCredentialAllowsAmbientImport, codexSecurityCredentialHome, codexSecurityHasStoredFileCredentials, codexSecurityStateDirectory, createIsolatedHome, importAmbientAuth, prepareCodexSecurityCredentialHome, preserveCodexSecurityPluginRegistration, pluginExecutionEnvironment, planOutputArchive, prepareOutputDir, preparePersistentScanRoot, requireModelSafeOutputDir, resolveCodexCommand, resolvePluginPath, resolvePluginPython, runWorkbench, setCodexSecurityCredentialLogout, validateOutputDir, } from "./runtime.js";
19
20
  import { enclosingGitWorktreeRoot, normalizeRepository, normalizeTarget, repositoryRevision, resolveRepositoryPath, validatedGitEnvironment, validateMode, } from "./targets.js";
20
21
  const DEFAULT_DEPENDENCIES = {
21
22
  createCodex: (options) => new Codex(options),
@@ -39,6 +40,7 @@ export class CodexSecurity {
39
40
  executableVersion: CODEX_EXECUTABLE_VERSION,
40
41
  };
41
42
  #dependencies;
43
+ #surface;
42
44
  #loginHandles = new Set();
43
45
  #abortController = new AbortController();
44
46
  #activeOperation = null;
@@ -47,9 +49,10 @@ export class CodexSecurity {
47
49
  #runtimeCredentialSource = null;
48
50
  #closed = false;
49
51
  #closePromise = null;
50
- constructor(config = {}, dependencies = DEFAULT_DEPENDENCIES) {
52
+ constructor(config = {}, dependencies = DEFAULT_DEPENDENCIES, runtimeOptions = { surface: "sdk" }) {
51
53
  this.config = structuredClone(config);
52
54
  this.#dependencies = dependencies;
55
+ this.#surface = runtimeOptions.surface;
53
56
  }
54
57
  async run(repository, options = {}) {
55
58
  return await this.#trackOperation(() => this.#run(repository, options));
@@ -145,15 +148,13 @@ export class CodexSecurity {
145
148
  throw new AuthenticationRequiredError(`Set ${externalProvider.env_key} to run a scan through ${externalProvider.name}.`);
146
149
  }
147
150
  const scanEnvironment = selectedScanEnvironment(this.#dependencies.environment, options.auth, modelProvider);
148
- if (authentication.method === "stored_credentials" &&
149
- this.#dependencies.prepareRuntime === undefined) {
151
+ if (this.#dependencies.prepareRuntime === undefined) {
150
152
  const credentialHome = await prepareCodexSecurityCredentialHome(scanEnvironment, (path) => requireOutputOutsideRepository(protectedRoot, path, "runtime"));
151
153
  releaseCredentialHome = await acquireCodexSecurityCredentialHomeLock(credentialHome, signal);
152
154
  }
153
155
  const previousRuntime = this.#runtime;
154
156
  const runtime = await this.#ensureRuntime(signal, temporaryRoot, (path) => requireOutputOutsideRepository(protectedRoot, path, "runtime"), options.auth, modelProvider);
155
157
  if (runtime === previousRuntime &&
156
- runtime.persistentCredentialHome === true &&
157
158
  this.#dependencies.prepareRuntime === undefined) {
158
159
  await this.#refreshPersistentRuntime(runtime, scanEnvironment, signal);
159
160
  }
@@ -199,6 +200,10 @@ export class CodexSecurity {
199
200
  "OPENAI_API_KEY or CODEX_API_KEY for CI.");
200
201
  }
201
202
  authentication = await runtimeScanAuthentication(this.#dependencies.environment, runtime.codexHome, options.auth, modelProvider);
203
+ if (authentication.method !== "stored_credentials") {
204
+ await releaseCredentialHome?.();
205
+ releaseCredentialHome = null;
206
+ }
202
207
  notifyObserver("onAuthentication", options.onAuthentication, options.onObserverError, authentication);
203
208
  const python = await (this.#dependencies.resolvePluginPython ?? resolvePluginPython)({
204
209
  configuredPath: this.config.pythonPath,
@@ -258,7 +263,7 @@ export class CodexSecurity {
258
263
  costAbortController.abort(error);
259
264
  return;
260
265
  }
261
- notifyObserver("onWarning", options.onWarning, options.onObserverError, `Could not track scan activity: ${redactedErrorMessage(error)}`);
266
+ notifyObserver("onWarning", options.onWarning, options.onObserverError, `Could not track scan activity: ${errorMessage(error)}`);
262
267
  };
263
268
  const tracker = new ScanCostTracker({
264
269
  codexHome: runtime.codexHome,
@@ -432,12 +437,18 @@ export class CodexSecurity {
432
437
  CODEX_HOME: runtime.codexHome,
433
438
  ...runtimePaths,
434
439
  };
440
+ const sdkCodexConfig = scanPreflightCodexConfig(effectiveConfig);
441
+ delete sdkCodexConfig["projects"];
435
442
  const codex = this.#dependencies.createCodex({
436
443
  ...(externalProvider !== null || apiKey === null ? {} : { apiKey }),
437
444
  env: definedEnvironment(selectedScanEnvironment(environment, "chatgpt")),
438
445
  config: {
446
+ ...sdkCodexConfig,
439
447
  default_permissions: SCAN_PERMISSION_PROFILE,
440
448
  allow_login_shell: false,
449
+ responses_api_metadata: {
450
+ codex_security_surface: this.#surface,
451
+ },
441
452
  },
442
453
  });
443
454
  const thread = codex.startThread({
@@ -479,7 +490,21 @@ export class CodexSecurity {
479
490
  authentication,
480
491
  workbenchValidated: true,
481
492
  model,
482
- onThreadStarted: (threadId) => tracker.start(threadId),
493
+ onThreadStarted: async (threadId) => {
494
+ tracker.start(threadId);
495
+ try {
496
+ await workbench(workbenchOptions, [
497
+ "set-scan-thread",
498
+ "--scan-id",
499
+ scanId,
500
+ "--thread-id",
501
+ threadId,
502
+ ]);
503
+ }
504
+ catch (error) {
505
+ notifyObserver("onWarning", options.onWarning, options.onObserverError, `Could not save scan session: ${safeErrorMessage(error)}`);
506
+ }
507
+ },
483
508
  onFinalize: async (usage) => {
484
509
  const snapshot = await tracker.stop(usage).catch((error) => {
485
510
  if (options.maxCostUsd !== undefined)
@@ -563,6 +588,29 @@ export class CodexSecurity {
563
588
  });
564
589
  checkOpen();
565
590
  }
591
+ try {
592
+ const runWorkbench = (args) => workbench(workbenchOptions, args);
593
+ const previousFindings = await listRepositoryFindings(runWorkbench, targetId, "all");
594
+ if (previousFindings !== undefined) {
595
+ await matchCompletedScan({
596
+ scanId,
597
+ repository: repo,
598
+ previousFindings: previousFindings.filter((finding) => finding["scanId"] !== scanId &&
599
+ finding["targetId"] === targetId),
600
+ falsePositives: falsePositiveExamples,
601
+ findings: result.findings.findings,
602
+ workbench: runWorkbench,
603
+ matchFindings: this.#dependencies.matchFindings,
604
+ environment,
605
+ model,
606
+ signal,
607
+ });
608
+ result.repositoryFindings = (await listRepositoryFindings(runWorkbench, targetId));
609
+ }
610
+ }
611
+ catch (error) {
612
+ notifyObserver("onWarning", options.onWarning, options.onObserverError, `Could not update repository findings: ${errorMessage(error)}`);
613
+ }
566
614
  return result;
567
615
  }
568
616
  catch (error) {
@@ -579,10 +627,9 @@ export class CodexSecurity {
579
627
  "fail-scan",
580
628
  "--scan-id",
581
629
  activeScan.id,
582
- // Redact before truncating: the stored message is read back by
583
- // `scans show` and travels inside the results directory.
630
+ // Scan history can be shared; never persist credential-bearing failures.
584
631
  "--message",
585
- redactedErrorMessage(failure).slice(0, 2400),
632
+ safeErrorMessage(failure).slice(0, 2400),
586
633
  ...(snapshot?.cost
587
634
  ? ["--cost-json", JSON.stringify(snapshot.cost)]
588
635
  : []),
@@ -599,7 +646,7 @@ export class CodexSecurity {
599
646
  }
600
647
  }
601
648
  catch (postScanError) {
602
- notifyObserver("onWarning", options.onWarning, options.onObserverError, `Could not run post-scan instructions: ${redactedErrorMessage(postScanError)}`);
649
+ notifyObserver("onWarning", options.onWarning, options.onObserverError, `Could not run post-scan instructions: ${errorMessage(postScanError)}`);
603
650
  }
604
651
  }
605
652
  if (this.#closed)
@@ -775,20 +822,8 @@ export class CodexSecurity {
775
822
  }
776
823
  async #ensureRuntime(signal, temporaryRoot, validateLocation, auth = "auto", modelProvider) {
777
824
  this.#requireOpen();
778
- if (this.#runtime !== null) {
779
- const usePersistentCredentials = scanAuthentication(this.#dependencies.environment, auth, modelProvider)
780
- .method === "stored_credentials";
781
- if (this.#dependencies.prepareRuntime !== undefined ||
782
- this.#runtime.persistentCredentialHome === undefined ||
783
- this.#runtime.persistentCredentialHome === usePersistentCredentials) {
784
- return this.#runtime;
785
- }
786
- await this.#cleanupRuntime(this.#runtime);
787
- this.#runtime = null;
788
- this.#runtimePromise = null;
789
- this.#runtimeCredentialSource = null;
790
- this.#requireOpen();
791
- }
825
+ if (this.#runtime !== null)
826
+ return this.#runtime;
792
827
  if (this.#runtimePromise === null) {
793
828
  const runtimePromise = this.#prepareRuntime(signal ?? this.#abortController.signal, temporaryRoot, validateLocation, auth, modelProvider);
794
829
  this.#runtimePromise = runtimePromise;
@@ -861,11 +896,9 @@ export class CodexSecurity {
861
896
  return await this.#dependencies.prepareRuntime(this.config, signal);
862
897
  }
863
898
  const processEnvironment = selectedScanEnvironment(this.#dependencies.environment, auth, modelProvider);
864
- const persistentCredentialHome = scanAuthentication(this.#dependencies.environment, auth, modelProvider)
865
- .method === "stored_credentials";
866
- const codexHome = persistentCredentialHome
867
- ? await prepareCodexSecurityCredentialHome(processEnvironment, validateLocation)
868
- : await createIsolatedHome(temporaryRoot, validateLocation);
899
+ const codexHome = validateLocation === undefined
900
+ ? await prepareCodexSecurityCredentialHome(processEnvironment)
901
+ : await realpath(codexSecurityCredentialHome(processEnvironment));
869
902
  let bootstrapWorkspace;
870
903
  try {
871
904
  throwIfAborted(signal);
@@ -875,7 +908,7 @@ export class CodexSecurity {
875
908
  const configuredAmbientHome = environmentValue(processEnvironment, "CODEX_HOME");
876
909
  const ambientHome = configuredAmbientHome ?? nodeAmbientHome;
877
910
  const mergedConfig = await mergedCodexConfig(this.config);
878
- const codexConfig = await preserveCodexSecurityPluginRegistration(codexHome, scanRuntimeCodexConfig(mergedConfig, codexSecurityStateDirectory(processEnvironment), persistentCredentialHome ? codexHome : undefined));
911
+ const codexConfig = await preserveCodexSecurityPluginRegistration(codexHome, scanRuntimeCodexConfig(mergedConfig, codexSecurityStateDirectory(processEnvironment), codexHome));
879
912
  await writeCodexConfig(join(codexHome, "config.toml"), codexConfig);
880
913
  const configPath = join(bootstrapWorkspace, "config-preflight.toml");
881
914
  await writeCodexConfig(configPath, scanPreflightCodexConfig(mergedConfig));
@@ -890,7 +923,7 @@ export class CodexSecurity {
890
923
  : await initialCredentialsAvailable(processEnvironment, ambientHome, codexHome);
891
924
  return {
892
925
  codexHome,
893
- persistentCredentialHome,
926
+ persistentCredentialHome: true,
894
927
  bootstrapWorkspace,
895
928
  configPath,
896
929
  plugin,
@@ -904,12 +937,13 @@ export class CodexSecurity {
904
937
  };
905
938
  }
906
939
  catch (error) {
907
- const cleanupResults = await Promise.allSettled([bootstrapWorkspace, persistentCredentialHome ? undefined : codexHome]
908
- .filter((path) => path !== undefined)
909
- .map((path) => cleanupSdkDirectory(path)));
910
- const cleanupFailures = cleanupResults.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
911
- if (cleanupFailures.length > 0) {
912
- throw new AggregateError([error, ...cleanupFailures], "Codex Security runtime preparation failed and its isolated runtime could not be cleaned up.", { cause: error });
940
+ if (bootstrapWorkspace !== undefined) {
941
+ try {
942
+ await cleanupSdkDirectory(bootstrapWorkspace);
943
+ }
944
+ catch (cleanupError) {
945
+ throw new AggregateError([error, cleanupError], "Codex Security runtime preparation failed and its isolated runtime could not be cleaned up.", { cause: error });
946
+ }
913
947
  }
914
948
  throw error;
915
949
  }
@@ -919,6 +953,25 @@ export class CodexSecurity {
919
953
  throw new CodexSecurityError("CodexSecurity is closed.");
920
954
  }
921
955
  }
956
+ export async function listRepositoryFindings(workbench, targetId, status = "open") {
957
+ const findings = [];
958
+ let offset;
959
+ do {
960
+ const page = await workbench([
961
+ "list-global-findings",
962
+ "--target-id",
963
+ targetId,
964
+ ...(status === "open" ? ["--status", "open"] : []),
965
+ ...(offset === undefined ? [] : ["--offset", String(offset)]),
966
+ ]);
967
+ if (!Array.isArray(page["findings"]))
968
+ return undefined;
969
+ findings.push(...page["findings"]);
970
+ offset =
971
+ typeof page["nextOffset"] === "number" ? page["nextOffset"] : undefined;
972
+ } while (offset !== undefined);
973
+ return findings;
974
+ }
922
975
  function deepScanOptions(options) {
923
976
  const selected = {};
924
977
  for (const [name, , minimum] of DEEP_SCAN_SETTINGS) {
@@ -973,6 +1026,12 @@ async function prepareDeepScanConfig(codexHome, environment, options, signal) {
973
1026
  deep_scan: { ...existing, ...overrides },
974
1027
  }), { mode: 0o600, signal });
975
1028
  }
1029
+ export function createSecurity(config = {}) {
1030
+ return createSecurityInternal(config, { surface: "sdk" });
1031
+ }
1032
+ export function createSecurityInternal(config = {}, runtimeOptions) {
1033
+ return new CodexSecurity(config, DEFAULT_DEPENDENCIES, runtimeOptions);
1034
+ }
976
1035
  export async function initialCredentialsAvailable(environment, ambientHome, isolatedHome, importer = importAmbientAuth) {
977
1036
  if (environmentApiKey(environment) !== null)
978
1037
  return false;
@@ -985,7 +1044,7 @@ export async function initialCredentialsAvailable(environment, ambientHome, isol
985
1044
  }
986
1045
  // Reports a cleanup failure without letting it decide the result of the scan. Only the
987
1046
  // message is forwarded, and it reaches the onWarning observer alone: unlike the fail-scan
988
- // path it is never written to the workbench, so it adds no persisted, unredacted text.
1047
+ // path it is never written to the workbench, so it adds no persisted warning text.
989
1048
  function warnCleanupFailed(options, reason) {
990
1049
  // This runs where a throw would replace the scan result, so every step is inside the
991
1050
  // guard: reading the reason, coercing it, and reading the observers off the options can
@@ -1048,7 +1107,7 @@ export async function runScanEvents(options) {
1048
1107
  const startedThreadId = event["thread_id"];
1049
1108
  if (typeof startedThreadId === "string") {
1050
1109
  threadId = startedThreadId;
1051
- options.onThreadStarted?.(startedThreadId);
1110
+ await options.onThreadStarted?.(startedThreadId);
1052
1111
  }
1053
1112
  if (!scanStarted) {
1054
1113
  scanStarted = true;
@@ -1469,8 +1528,8 @@ function reconnectDetails(message) {
1469
1528
  //
1470
1529
  // Only `error.message` is reused, because that is the single shape the previous
1471
1530
  // code already surfaced. No other shape is forwarded or stringified: this message
1472
- // reaches `fail-scan --message` and is stored in `scans.failure_message` without
1473
- // redaction, so widening what is copied out of the payload would add a new
1531
+ // reaches `fail-scan --message` and is stored unchanged in `scans.failure_message`,
1532
+ // so widening what is copied out of the payload would add a new
1474
1533
  // credential-disclosure path to persistent scan history.
1475
1534
  function turnFailureMessage(error) {
1476
1535
  if (isRecord(error) && typeof error["message"] === "string") {