@openai/codex-security 0.1.16 → 0.1.18

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 (125) hide show
  1. package/README.md +228 -18
  2. package/_bundled_plugin/.app.json +1 -1
  3. package/_bundled_plugin/.mcp.json +10 -3
  4. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  6. package/_bundled_plugin/references/config-preflight.md +1 -1
  7. package/_bundled_plugin/references/core-scan.md +1 -1
  8. package/_bundled_plugin/references/final-report.md +4 -2
  9. package/_bundled_plugin/references/sarif-adapter.md +2 -0
  10. package/_bundled_plugin/references/scan-artifacts.md +1 -1
  11. package/_bundled_plugin/references/scan-contract.md +18 -7
  12. package/_bundled_plugin/schemas/scan-manifest.schema.json +2 -2
  13. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +23 -0
  14. package/_bundled_plugin/scripts/deep_scan_workbench.py +122 -7
  15. package/_bundled_plugin/scripts/finalize_scan_contract.py +106 -38
  16. package/_bundled_plugin/scripts/generate_in_scope_files.py +20 -0
  17. package/_bundled_plugin/scripts/generate_rank_input.py +23 -7
  18. package/_bundled_plugin/scripts/launch_codex_security_mcp +32 -0
  19. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +27 -0
  20. package/_bundled_plugin/scripts/report_projection.py +19 -8
  21. package/_bundled_plugin/scripts/workbench_cli.py +35 -15
  22. package/_bundled_plugin/scripts/workbench_db.py +184 -202
  23. package/_bundled_plugin/scripts/workbench_finding_index.py +101 -0
  24. package/_bundled_plugin/scripts/workbench_progress.py +6 -3
  25. package/_bundled_plugin/scripts/workbench_remediation.py +19 -0
  26. package/_bundled_plugin/scripts/workbench_saved_results.py +1289 -0
  27. package/_bundled_plugin/scripts/workbench_scan_history.py +17 -2
  28. package/_bundled_plugin/scripts/workbench_schema.py +28 -0
  29. package/_bundled_plugin/scripts/workbench_target.py +36 -5
  30. package/_bundled_plugin/scripts/workbench_validation.py +9 -0
  31. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +4 -4
  32. package/_bundled_plugin/skills/fix-finding/SKILL.md +17 -1
  33. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +1 -1
  34. package/_bundled_plugin/skills/security-scan/SKILL.md +1 -1
  35. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +1 -1
  36. package/dist/api.d.ts +18 -1
  37. package/dist/api.d.ts.map +1 -1
  38. package/dist/api.js +234 -18
  39. package/dist/api.js.map +1 -1
  40. package/dist/cli.d.ts +5 -3
  41. package/dist/cli.d.ts.map +1 -1
  42. package/dist/cli.js +348 -43
  43. package/dist/cli.js.map +1 -1
  44. package/dist/component-plan.d.ts +15 -0
  45. package/dist/component-plan.d.ts.map +1 -0
  46. package/dist/component-plan.js +145 -0
  47. package/dist/component-plan.js.map +1 -0
  48. package/dist/component-scan.d.ts +83 -0
  49. package/dist/component-scan.d.ts.map +1 -0
  50. package/dist/component-scan.js +279 -0
  51. package/dist/component-scan.js.map +1 -0
  52. package/dist/contract.d.ts +8 -2
  53. package/dist/contract.d.ts.map +1 -1
  54. package/dist/contract.js +27 -8
  55. package/dist/contract.js.map +1 -1
  56. package/dist/cost-model.d.ts +20 -0
  57. package/dist/cost-model.d.ts.map +1 -0
  58. package/dist/cost-model.js +86 -0
  59. package/dist/cost-model.js.map +1 -0
  60. package/dist/cost.d.ts +2 -11
  61. package/dist/cost.d.ts.map +1 -1
  62. package/dist/cost.js +15 -98
  63. package/dist/cost.js.map +1 -1
  64. package/dist/custom-validation-prompt.d.ts +4 -0
  65. package/dist/custom-validation-prompt.d.ts.map +1 -0
  66. package/dist/custom-validation-prompt.js +94 -0
  67. package/dist/custom-validation-prompt.js.map +1 -0
  68. package/dist/custom-validation.d.ts +45 -0
  69. package/dist/custom-validation.d.ts.map +1 -0
  70. package/dist/custom-validation.js +292 -0
  71. package/dist/custom-validation.js.map +1 -0
  72. package/dist/errors.d.ts +1 -1
  73. package/dist/errors.d.ts.map +1 -1
  74. package/dist/errors.js +1 -1
  75. package/dist/errors.js.map +1 -1
  76. package/dist/index.d.ts +6 -1
  77. package/dist/index.d.ts.map +1 -1
  78. package/dist/index.js +2 -0
  79. package/dist/index.js.map +1 -1
  80. package/dist/models.d.ts +1 -1
  81. package/dist/models.d.ts.map +1 -1
  82. package/dist/models.js.map +1 -1
  83. package/dist/multiscan.d.ts +1 -0
  84. package/dist/multiscan.d.ts.map +1 -1
  85. package/dist/multiscan.js +53 -5
  86. package/dist/multiscan.js.map +1 -1
  87. package/dist/patch-tui.js +1 -1
  88. package/dist/patch-tui.js.map +1 -1
  89. package/dist/publication.d.ts.map +1 -1
  90. package/dist/publication.js +3 -4
  91. package/dist/publication.js.map +1 -1
  92. package/dist/runtime.d.ts +4 -2
  93. package/dist/runtime.d.ts.map +1 -1
  94. package/dist/runtime.js +109 -38
  95. package/dist/runtime.js.map +1 -1
  96. package/dist/scan-comparison.d.ts +12 -5
  97. package/dist/scan-comparison.d.ts.map +1 -1
  98. package/dist/scan-comparison.js +72 -28
  99. package/dist/scan-comparison.js.map +1 -1
  100. package/dist/scan-dashboard.d.ts +9 -2
  101. package/dist/scan-dashboard.d.ts.map +1 -1
  102. package/dist/scan-dashboard.js +198 -3
  103. package/dist/scan-dashboard.js.map +1 -1
  104. package/dist/scan-logs.d.ts.map +1 -1
  105. package/dist/scan-logs.js +5 -21
  106. package/dist/scan-logs.js.map +1 -1
  107. package/dist/scan-sessions.d.ts +4 -0
  108. package/dist/scan-sessions.d.ts.map +1 -0
  109. package/dist/scan-sessions.js +35 -0
  110. package/dist/scan-sessions.js.map +1 -0
  111. package/dist/targets.d.ts.map +1 -1
  112. package/dist/targets.js +16 -1
  113. package/dist/targets.js.map +1 -1
  114. package/dist/version.d.ts.map +1 -1
  115. package/dist/version.js +2 -20
  116. package/dist/version.js.map +1 -1
  117. package/dist/windows-path.d.ts +3 -0
  118. package/dist/windows-path.d.ts.map +1 -0
  119. package/dist/windows-path.js +16 -0
  120. package/dist/windows-path.js.map +1 -0
  121. package/dist/worker-progress.d.ts +1 -0
  122. package/dist/worker-progress.d.ts.map +1 -1
  123. package/dist/worker-progress.js +12 -0
  124. package/dist/worker-progress.js.map +1 -1
  125. package/package.json +8 -2
package/dist/runtime.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { execFile as execFileCallback, spawn } from "node:child_process";
2
2
  import { randomUUID } from "node:crypto";
3
3
  import { constants, existsSync, readdirSync, } from "node:fs";
4
- import { chmod, cp, copyFile, link, lstat, mkdir, mkdtemp, open, opendir, readFile, readdir, realpath, rename, rm, rmdir, stat, writeFile, } from "node:fs/promises";
4
+ import { chmod, cp, copyFile, link, lstat, mkdir, mkdtemp, open, opendir, readFile, readdir, realpath, rename, rm, rmdir, stat, utimes, writeFile, } from "node:fs/promises";
5
5
  import { homedir, tmpdir } from "node:os";
6
6
  import { createRequire } from "node:module";
7
7
  import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep, } from "node:path";
@@ -14,6 +14,7 @@ import extractZip from "extract-zip";
14
14
  import { parse } from "smol-toml";
15
15
  import { CodexSecurityError, OutputDirectoryError, OutputDirectoryNotEmptyError, OutputInsideProtectedRootError, PluginBootstrapError, PluginPythonUnavailableError, errorMessage, } from "./errors.js";
16
16
  import { resolveTrustedExecutable } from "./trusted-executable.js";
17
+ import { isWindowsUnsafePathComponent, windowsUnsafePathComponent, } from "./windows-path.js";
17
18
  const execFile = promisify(execFileCallback);
18
19
  export const MARKETPLACE_NAME = "codex-security-sdk";
19
20
  export const PLUGIN_NAME = "codex-security";
@@ -24,8 +25,10 @@ const MAX_ZIP_EXPANDED_SIZE = 512 * 1024 * 1024;
24
25
  const MODEL_UNSAFE_PATH = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u;
25
26
  const CREDENTIAL_LOCK_NAME = ".codex-security-scan.lock";
26
27
  const CREDENTIAL_LOGOUT_MARKER = ".codex-security-logged-out";
28
+ const CREDENTIAL_LOCK_HEARTBEAT_MILLISECONDS = 5_000;
27
29
  const CREDENTIAL_LOCK_POLL_MILLISECONDS = 25;
28
30
  const INCOMPLETE_CREDENTIAL_LOCK_MILLISECONDS = 30_000;
31
+ const MAX_PROCESS_ID = 2_147_483_647;
29
32
  const MAX_WINDOWS_CREDENTIAL_ACL_STDERR = 64 * 1024;
30
33
  function environmentValue(environment, requested) {
31
34
  const exact = environment[requested]?.trim();
@@ -37,11 +40,12 @@ function environmentValue(environment, requested) {
37
40
  }
38
41
  export function codexSecurityStateDirectory(environment = process.env) {
39
42
  const configured = environmentValue(environment, "CODEX_SECURITY_STATE_DIR");
40
- if (configured !== undefined) {
41
- return resolve(expandHome(configured, environment));
42
- }
43
- const codexHome = environmentValue(environment, "CODEX_HOME") ?? join(homedir(), ".codex");
44
- return resolve(expandHome(codexHome, environment), "state", "plugins", "codex-security");
43
+ const path = configured !== undefined
44
+ ? resolve(expandHome(configured, environment))
45
+ : resolve(expandHome(environmentValue(environment, "CODEX_HOME") ??
46
+ join(homedir(), ".codex"), environment), "state", "plugins", "codex-security");
47
+ requireModelSafeOutputDir(path);
48
+ return path;
45
49
  }
46
50
  export function codexSecurityCredentialHome(environment = process.env) {
47
51
  return join(codexSecurityStateDirectory(environment), "codex-home");
@@ -569,7 +573,9 @@ async function secureWindowsCredentialHome(path) {
569
573
  "$path = $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH",
570
574
  "while ($true) { $parent = Microsoft.PowerShell.Management\\Split-Path -Path $path -Parent; if (-not $parent -or $parent -eq $path) { break }; Microsoft.PowerShell.Security\\Get-Acl -LiteralPath $parent | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty Sddl; $path = $parent }",
571
575
  "Microsoft.PowerShell.Security\\Get-Acl -LiteralPath $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty Sddl",
572
- "Microsoft.PowerShell.Management\\Get-ChildItem -LiteralPath $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH -Recurse -Force | Microsoft.PowerShell.Security\\Get-Acl | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty Sddl",
576
+ // A temporary descendant can disappear after enumeration. Its missing
577
+ // descriptor reduces the count and retries the stable snapshot.
578
+ "Microsoft.PowerShell.Management\\Get-ChildItem -LiteralPath $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH -Recurse -Force | Microsoft.PowerShell.Core\\ForEach-Object { try { Microsoft.PowerShell.Security\\Get-Acl -LiteralPath $_.FullName | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty Sddl } catch { if ($_.FullyQualifiedErrorId -notlike 'GetAcl_PathNotFound,*') { throw } } }",
573
579
  ].join("; ");
574
580
  const resolvePrincipalScript = [
575
581
  "$ErrorActionPreference = 'Stop'",
@@ -726,7 +732,7 @@ export async function acquireCodexSecurityCredentialHomeLock(codexHome, signal,
726
732
  throw error;
727
733
  });
728
734
  if (existingLock !== null) {
729
- if (await recoverStaleCredentialHomeLock(lock))
735
+ if (await recoverStaleCredentialHomeLock(lock, signal))
730
736
  continue;
731
737
  await delay(CREDENTIAL_LOCK_POLL_MILLISECONDS, undefined, { signal });
732
738
  continue;
@@ -742,7 +748,7 @@ export async function acquireCodexSecurityCredentialHomeLock(codexHome, signal,
742
748
  catch (error) {
743
749
  if (nodeErrorCode(error) !== "EEXIST")
744
750
  throw error;
745
- if (await recoverStaleCredentialHomeLock(lock))
751
+ if (await recoverStaleCredentialHomeLock(lock, signal))
746
752
  continue;
747
753
  await delay(CREDENTIAL_LOCK_POLL_MILLISECONDS, undefined, { signal });
748
754
  continue;
@@ -754,10 +760,19 @@ export async function acquireCodexSecurityCredentialHomeLock(codexHome, signal,
754
760
  await rm(lock, { recursive: true, force: true }).catch(() => undefined);
755
761
  throw error;
756
762
  }
763
+ const heartbeat = setInterval(async () => {
764
+ try {
765
+ const now = new Date();
766
+ await utimes(lock, now, now);
767
+ }
768
+ catch { }
769
+ }, CREDENTIAL_LOCK_HEARTBEAT_MILLISECONDS);
770
+ heartbeat.unref();
757
771
  let released = false;
758
772
  return async () => {
759
773
  if (released)
760
774
  return;
775
+ clearInterval(heartbeat);
761
776
  await requireSecureCredentialHome(codexHome, {
762
777
  ...securityOptions,
763
778
  expectedDevice,
@@ -772,7 +787,7 @@ export async function acquireCodexSecurityCredentialHomeLock(codexHome, signal,
772
787
  };
773
788
  }
774
789
  }
775
- async function recoverStaleCredentialHomeLock(lock) {
790
+ async function recoverStaleCredentialHomeLock(lock, signal) {
776
791
  const metadata = await lstat(lock).catch((error) => {
777
792
  if (nodeErrorCode(error) === "ENOENT")
778
793
  return null;
@@ -791,28 +806,49 @@ async function recoverStaleCredentialHomeLock(lock) {
791
806
  if (nodeErrorCode(error) !== "ENOENT" && !(error instanceof SyntaxError)) {
792
807
  throw error;
793
808
  }
794
- if (Date.now() - metadata.mtimeMs <
795
- INCOMPLETE_CREDENTIAL_LOCK_MILLISECONDS) {
796
- return false;
797
- }
798
809
  }
799
- if (isRecord(owner) && typeof owner["pid"] === "number") {
810
+ // Only positive signed-32-bit PIDs identify an owner. Other values can name
811
+ // process groups or fail argument validation, so use the stale-age check.
812
+ const ownerPid = isRecord(owner) ? owner["pid"] : undefined;
813
+ let ownerExited = false;
814
+ let ownerIsAlive = false;
815
+ if (typeof ownerPid === "number" &&
816
+ Number.isInteger(ownerPid) &&
817
+ ownerPid > 0 &&
818
+ ownerPid <= MAX_PROCESS_ID) {
800
819
  try {
801
- process.kill(owner["pid"], 0);
802
- return false;
820
+ process.kill(ownerPid, 0);
821
+ ownerIsAlive = true;
803
822
  }
804
823
  catch (error) {
805
- if (nodeErrorCode(error) !== "ESRCH") {
806
- if (nodeErrorCode(error) === "EPERM")
807
- return false;
824
+ if (nodeErrorCode(error) === "ESRCH")
825
+ ownerExited = true;
826
+ else if (nodeErrorCode(error) === "EPERM")
827
+ ownerIsAlive = true;
828
+ else
808
829
  throw error;
809
- }
810
830
  }
811
831
  }
812
- else if (Date.now() - metadata.mtimeMs <
813
- INCOMPLETE_CREDENTIAL_LOCK_MILLISECONDS) {
832
+ if (!ownerExited &&
833
+ Date.now() - metadata.mtimeMs < INCOMPLETE_CREDENTIAL_LOCK_MILLISECONDS) {
814
834
  return false;
815
835
  }
836
+ if (ownerIsAlive) {
837
+ await delay(CREDENTIAL_LOCK_HEARTBEAT_MILLISECONDS, undefined, { signal });
838
+ const refreshedMetadata = await lstat(lock).catch((error) => {
839
+ if (nodeErrorCode(error) === "ENOENT")
840
+ return null;
841
+ throw error;
842
+ });
843
+ if (refreshedMetadata === null)
844
+ return true;
845
+ if (!refreshedMetadata.isDirectory() ||
846
+ refreshedMetadata.isSymbolicLink()) {
847
+ throw new OutputDirectoryError(`Codex Security credential-home lock is not a directory: ${lock}`);
848
+ }
849
+ if (refreshedMetadata.mtimeMs > metadata.mtimeMs)
850
+ return false;
851
+ }
816
852
  const quarantine = `${lock}.stale-${randomUUID()}`;
817
853
  try {
818
854
  await rename(lock, quarantine);
@@ -950,35 +986,39 @@ export function requireOutputOutsideRepositories(repositories, outputDirectory,
950
986
  requireOutputOutsideRepository(repository, outputDirectory, pathKind);
951
987
  }
952
988
  export async function preparePersistentOutputRoot(stateDirectory, category, repositoryName) {
989
+ requireModelSafeOutputDir(stateDirectory);
953
990
  await mkdir(stateDirectory, { recursive: true, mode: 0o700 });
954
991
  let root = await realpath(stateDirectory);
955
992
  for (const directory of [category, safePrefix(repositoryName)]) {
956
993
  root = join(root, directory);
957
994
  await mkdir(root, { recursive: true, mode: 0o700 });
958
995
  if (!(await lstat(root)).isDirectory()) {
959
- throw new OutputDirectoryError(`Persistent ${category === "scans" ? "scan" : "policy"} output must use real directories: ${root}`);
996
+ throw new OutputDirectoryError(`Persistent ${category === "scans" ? "scan" : category === "policies" ? "policy" : "validation"} output must use real directories: ${root}`);
960
997
  }
961
998
  }
962
999
  return root;
963
1000
  }
964
- export async function runWorkbench(options, args) {
1001
+ export async function runWorkbench(options, args, input) {
965
1002
  let stdout;
966
1003
  try {
967
- ({ stdout } = await execFile(options.python, [
1004
+ const environment = Object.fromEntries(Object.entries(options.environment).filter(([name]) => name.toUpperCase() !== "OPENAI_API_KEY" &&
1005
+ name.toUpperCase() !== "CODEX_API_KEY" &&
1006
+ name.toUpperCase() !== "OPENROUTER_API_KEY" &&
1007
+ name.toUpperCase() !== "FIREWORKS_API_KEY"));
1008
+ const result = await runCodexCommand({ command: options.python }, [
968
1009
  "-I",
1010
+ "-X",
1011
+ "utf8",
969
1012
  "-B",
970
1013
  join(options.pluginRoot, "scripts", "workbench_db.py"),
971
1014
  ...args,
972
- ], {
973
- env: Object.fromEntries(Object.entries(options.environment).filter(([name]) => name.toUpperCase() !== "OPENAI_API_KEY" &&
974
- name.toUpperCase() !== "CODEX_API_KEY" &&
975
- name.toUpperCase() !== "OPENROUTER_API_KEY" &&
976
- name.toUpperCase() !== "FIREWORKS_API_KEY")),
977
- encoding: "utf8",
978
- maxBuffer: Infinity,
979
- windowsHide: true,
980
- signal: options.signal,
981
- }));
1015
+ ], pythonUtf8Environment(environment), input, options.signal);
1016
+ if (!result.success) {
1017
+ throw new Error(result.stderr.trim() ||
1018
+ result.stdout.trim() ||
1019
+ `Workbench exited with status ${result.exitCode}.`);
1020
+ }
1021
+ stdout = result.stdout;
982
1022
  }
983
1023
  catch (error) {
984
1024
  if (options.signal?.aborted)
@@ -1096,6 +1136,28 @@ export function requireModelSafeOutputDir(path) {
1096
1136
  if (MODEL_UNSAFE_PATH.test(path)) {
1097
1137
  throw new OutputDirectoryError("Scan output directory must not contain control or line-separator characters.");
1098
1138
  }
1139
+ const ambiguous = process.platform === "win32" ? windowsUnsafePathComponent(path) : undefined;
1140
+ if (ambiguous !== undefined) {
1141
+ throw new OutputDirectoryError(`Codex Security paths must not contain Windows-ambiguous components: ${ambiguous}`);
1142
+ }
1143
+ }
1144
+ export async function canonicalizeModelSafePath(input) {
1145
+ const path = resolve(expandHome(input));
1146
+ requireModelSafeOutputDir(path);
1147
+ for (let ancestor = path;; ancestor = dirname(ancestor)) {
1148
+ try {
1149
+ const canonicalAncestor = resolve(ancestor, await realpath(ancestor));
1150
+ const canonical = resolve(canonicalAncestor, relative(ancestor, path));
1151
+ requireModelSafeOutputDir(canonical);
1152
+ return canonical;
1153
+ }
1154
+ catch (error) {
1155
+ if (nodeErrorCode(error) !== "ENOENT")
1156
+ throw error;
1157
+ if (dirname(ancestor) === ancestor)
1158
+ throw error;
1159
+ }
1160
+ }
1099
1161
  }
1100
1162
  export async function prepareOutputDir(outputDirectory, repositoryName, temporaryRoot = tmpdir(), validateLocation, archiveExisting = false, onOutputArchived) {
1101
1163
  if (outputDirectory === undefined) {
@@ -1644,11 +1706,20 @@ export async function resolvePluginPython(options = {}) {
1644
1706
  }
1645
1707
  export function pluginExecutionEnvironment(python, environment = process.env) {
1646
1708
  return {
1647
- ...environment,
1709
+ ...pythonUtf8Environment(environment),
1648
1710
  PYTHON: python,
1649
1711
  CODEX_CLI_PATH: resolveCodexCommand(environment).command,
1650
1712
  };
1651
1713
  }
1714
+ export function pythonUtf8Environment(environment) {
1715
+ const normalized = { ...environment };
1716
+ for (const name of Object.keys(normalized)) {
1717
+ if (name.toUpperCase() === "PYTHONUTF8")
1718
+ delete normalized[name];
1719
+ }
1720
+ normalized["PYTHONUTF8"] = "1";
1721
+ return normalized;
1722
+ }
1652
1723
  export async function cleanupSdkDirectory(path) {
1653
1724
  await rm(path, { recursive: true, force: true });
1654
1725
  }
@@ -1764,7 +1835,7 @@ function safeArchivePath(value) {
1764
1835
  parts.includes("..") ||
1765
1836
  value.includes("\\") ||
1766
1837
  value.includes("\0") ||
1767
- parts.some((part) => part.includes(":")) ||
1838
+ parts.some(isWindowsUnsafePathComponent) ||
1768
1839
  normalized.length === 0) {
1769
1840
  throw new PluginBootstrapError(`Plugin ZIP contains an unsafe path: ${value}`);
1770
1841
  }