@openai/codex-security 0.1.3 → 0.1.4

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.
package/dist/cli.js CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  import { execFileSync, spawn } from "node:child_process";
3
- import { accessSync, constants, lstatSync, realpathSync, writeSync, } from "node:fs";
3
+ import { accessSync, constants, existsSync, lstatSync, realpathSync, writeSync, } from "node:fs";
4
4
  import { mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
5
5
  import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep, win32, } from "node:path";
6
6
  import { cwd } from "node:process";
@@ -17,7 +17,7 @@ import { DEFAULT_CODEX_CONFIG, mergedCodexConfig, scanModelConfiguration, } from
17
17
  import { formatUsd } from "./cost.js";
18
18
  import { CodexSecurityError, OutputInsideProtectedRootError, ScanInterruptedError, } from "./errors.js";
19
19
  import { runMultiscan } from "./multiscan.js";
20
- import { bundledPluginRoot, codexSecurityStateDirectory, expandHome, resolveCodexCommand, resolvePluginPython, runWorkbench, } from "./runtime.js";
20
+ import { bundledPluginRoot, codexSecurityCredentialHome, codexSecurityStateDirectory, expandHome, prepareCodexSecurityCredentialHome, resolveCodexCommand, resolvePluginPython, runWorkbench, setCodexSecurityCredentialLogout, } from "./runtime.js";
21
21
  import { matchScanFindings, } from "./scan-comparison.js";
22
22
  import { renderScanHistory, } from "./scan-history-renderer.js";
23
23
  import { DiffTarget } from "./targets.js";
@@ -51,6 +51,9 @@ const MODEL_REASONING_EFFORTS = [
51
51
  "xhigh",
52
52
  ];
53
53
  const DEFAULT_SCAN_MODEL_CONFIGURATION = scanModelConfiguration(DEFAULT_CODEX_CONFIG);
54
+ const CODEX_OVERRIDE_DESCRIPTION = 'Repeat TOML KEY=VALUE; e.g. model_reasoning_effort="high" or features.multi_agent_v2.max_concurrent_threads_per_session=4.';
55
+ const PLUGIN_PATH_DESCRIPTION = "Codex Security plugin directory or ZIP (default: bundled plugin).";
56
+ const PYTHON_PATH_DESCRIPTION = "Python interpreter (default: PYTHON or automatic discovery).";
54
57
  const EXPORT_DEFAULT_OUTPUTS = {
55
58
  csv: "findings.csv",
56
59
  json: "findings.json",
@@ -98,12 +101,24 @@ function effortOption() {
98
101
  const DEFAULT_DEPENDENCIES = {
99
102
  createSecurity: (config) => new CodexSecurity(config),
100
103
  environment: process.env,
104
+ prepareAuthenticationHome: prepareCodexSecurityCredentialHome,
101
105
  checkForUpdate: () => checkForUpdate({ environment: process.env }),
102
106
  hasStoredChatGPTSignIn: async () => {
103
107
  const environment = Object.fromEntries(Object.entries(process.env).filter(([name]) => name.toUpperCase() !== "OPENAI_API_KEY" &&
104
108
  name.toUpperCase() !== "CODEX_API_KEY"));
105
- const status = await accountStatus(resolveCodexCommand(), environment);
106
- return status.authenticated && /\bchatgpt\b/iu.test(status.details);
109
+ const command = resolveCodexCommand();
110
+ if (existsSync(codexSecurityCredentialHome(process.env))) {
111
+ const dedicatedStatus = await accountStatus(command, {
112
+ ...environment,
113
+ CODEX_HOME: await prepareCodexSecurityCredentialHome(process.env),
114
+ });
115
+ if (dedicatedStatus.authenticated &&
116
+ /\bchatgpt\b/iu.test(dedicatedStatus.details)) {
117
+ return true;
118
+ }
119
+ }
120
+ const ambientStatus = await accountStatus(command, environment);
121
+ return (ambientStatus.authenticated && /\bchatgpt\b/iu.test(ambientStatus.details));
107
122
  },
108
123
  currentDirectory: cwd,
109
124
  now: Date.now,
@@ -118,7 +133,7 @@ const DEFAULT_DEPENDENCIES = {
118
133
  writeSync(stream.fd, value);
119
134
  },
120
135
  forceExit: (signal) => process.kill(process.pid, signal),
121
- runCodex: runCodexSkillCommand,
136
+ runCodex: (args, output, environment) => runCodexSkillCommand(args, output, resolveCodexCommand(), environment),
122
137
  exportFindings: async (arguments_, output) => {
123
138
  const environment = exportEnvironment();
124
139
  const python = await resolvePluginPython({
@@ -188,9 +203,9 @@ const DEFAULT_DEPENDENCIES = {
188
203
  },
189
204
  matchFindings: matchScanFindings,
190
205
  };
191
- export async function runCodexSkillCommand(args, output, command = resolveCodexCommand()) {
192
- const configuredHome = process.env["CODEX_HOME"];
193
- const environment = { ...process.env };
206
+ export async function runCodexSkillCommand(args, output, command = resolveCodexCommand(), processEnvironment = process.env) {
207
+ const configuredHome = processEnvironment["CODEX_HOME"];
208
+ const environment = { ...processEnvironment };
194
209
  for (const name of Object.keys(environment)) {
195
210
  if (name.toUpperCase() === "CODEX_HOME")
196
211
  delete environment[name];
@@ -617,53 +632,53 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
617
632
  auth: z
618
633
  .enum(["auto", "chatgpt", "api-key"])
619
634
  .default("auto")
620
- .describe("Select automatic, ChatGPT, or API-key authentication."),
635
+ .describe("Select ChatGPT, OPENAI_API_KEY/CODEX_API_KEY, or automatic authentication."),
621
636
  path: z
622
637
  .array(optionValue("--path"))
623
638
  .default([])
624
- .describe("Scan only PATH; repeat for multiple paths."),
639
+ .describe("Scan only PATH; repeat for multiple repository-relative paths."),
625
640
  knowledgeBase: z
626
641
  .array(optionValue("--knowledge-base"))
627
642
  .default([])
628
- .describe("Read security docs; repeat for multiple paths."),
643
+ .describe("Add security-context files or directories; repeat for multiple paths."),
629
644
  diff: optionValue("--diff")
630
645
  .optional()
631
- .describe("Scan Git changes from BASE to --head."),
646
+ .describe("Scan committed Git changes from BASE to --head."),
632
647
  workingTree: z
633
648
  .boolean()
634
649
  .default(false)
635
- .describe("Scan staged and unstaged changes."),
650
+ .describe("Scan staged and unstaged changes against --base."),
636
651
  head: optionValue("--head")
637
652
  .optional()
638
- .describe("Git head ref for --diff."),
653
+ .describe("Git head ref for --diff (default: HEAD)."),
639
654
  base: optionValue("--base")
640
655
  .optional()
641
- .describe("Git base ref for --working-tree."),
656
+ .describe("Git base ref for --working-tree (default: HEAD)."),
642
657
  mode: z
643
658
  .enum(["standard", "deep"])
644
659
  .default("standard")
645
- .describe("Scan mode."),
660
+ .describe("Scan mode; deep supports repository and path targets."),
646
661
  model: optionValue("--model")
647
662
  .optional()
648
663
  .describe(`OpenAI model to use (default: ${DEFAULT_SCAN_MODEL_CONFIGURATION.model}).`),
649
664
  effort: effortOption(),
650
665
  outputDir: optionValue("--output-dir")
651
666
  .optional()
652
- .describe("Write scan artifacts to DIR."),
667
+ .describe("Artifact directory outside the repository (default: Codex Security state; CODEX_SECURITY_STATE_DIR)."),
653
668
  archiveExisting: z
654
669
  .boolean()
655
670
  .default(false)
656
- .describe("Archive existing results before scanning."),
671
+ .describe("Archive existing results; requires --output-dir."),
657
672
  pluginPath: optionValue("--plugin-path")
658
673
  .optional()
659
- .describe("Use a Codex Security plugin directory or ZIP."),
674
+ .describe(PLUGIN_PATH_DESCRIPTION),
660
675
  python: optionValue("--python")
661
676
  .optional()
662
- .describe("Python interpreter for the bundled plugin runtime."),
677
+ .describe(PYTHON_PATH_DESCRIPTION),
663
678
  codex: z
664
679
  .array(optionValue("--codex"))
665
680
  .default([])
666
- .describe('Override Codex settings; e.g. model_reasoning_effort="high".'),
681
+ .describe(CODEX_OVERRIDE_DESCRIPTION),
667
682
  failOnSeverity: z
668
683
  .enum(REPORTABLE_SEVERITIES)
669
684
  .optional()
@@ -696,8 +711,16 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
696
711
  args: { repository: "." },
697
712
  options: { model: "gpt-5.6-terra", effort: "high" },
698
713
  },
699
- { args: { repository: "." }, options: { path: ["src", "tests"] } },
714
+ { args: { repository: "." }, options: { path: ["src"] } },
700
715
  { args: { repository: "." }, options: { diff: "origin/main" } },
716
+ {
717
+ args: { repository: "." },
718
+ options: {
719
+ codex: [
720
+ "features.multi_agent_v2.max_concurrent_threads_per_session=4",
721
+ ],
722
+ },
723
+ },
701
724
  ],
702
725
  output: z.record(z.string(), z.unknown()).optional(),
703
726
  async run({ args, error: incurError, format, options }) {
@@ -819,16 +842,24 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
819
842
  .string()
820
843
  .min(1)
821
844
  .optional()
822
- .describe("CSV repository list; omit to discover repositories."),
845
+ .describe("CSV repository list; omit to discover repositories interactively."),
823
846
  }),
824
847
  options: z.object({
825
848
  outputDir: z
826
849
  .string()
827
850
  .min(1, "--output-dir must not be empty.")
828
851
  .optional()
829
- .describe("Directory for scan artifacts and resumable results."),
830
- workers: z.number().int().positive().default(4),
831
- mode: z.enum(["standard", "deep"]).default("standard"),
852
+ .describe("Resumable results directory; required with a repository CSV."),
853
+ workers: z
854
+ .number()
855
+ .int()
856
+ .positive()
857
+ .default(4)
858
+ .describe("Concurrent repository scans. Per-scan Codex workers are separate."),
859
+ mode: z
860
+ .enum(["standard", "deep"])
861
+ .default("standard")
862
+ .describe("Default scan mode for repositories without a CSV mode."),
832
863
  model: optionValue("--model")
833
864
  .optional()
834
865
  .describe(`OpenAI model for each repository (default: ${DEFAULT_SCAN_MODEL_CONFIGURATION.model}).`),
@@ -839,13 +870,27 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
839
870
  .positive()
840
871
  .default(1)
841
872
  .describe("Maximum scan attempts per repository."),
842
- pluginPath: z.string().min(1).optional(),
843
- python: z.string().min(1).optional(),
873
+ pluginPath: z
874
+ .string()
875
+ .min(1)
876
+ .optional()
877
+ .describe(PLUGIN_PATH_DESCRIPTION),
878
+ python: z.string().min(1).optional().describe(PYTHON_PATH_DESCRIPTION),
844
879
  codex: z
845
880
  .array(z.string().min(1))
846
881
  .default([])
847
- .describe('Override Codex settings; e.g. model_reasoning_effort="high".'),
882
+ .describe(CODEX_OVERRIDE_DESCRIPTION),
848
883
  }),
884
+ examples: [
885
+ {
886
+ args: {},
887
+ options: { model: "gpt-5.6-terra", effort: "high" },
888
+ },
889
+ ],
890
+ hint: "CSV example:\n" +
891
+ " codex-security bulk-scan repositories.csv " +
892
+ "--output-dir /path/outside/repositories/results " +
893
+ "--workers 4 --max-attempts 3",
849
894
  output: z.record(z.string(), z.unknown()).optional(),
850
895
  async run({ args, options }) {
851
896
  const controller = new AbortController();
@@ -952,10 +997,10 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
952
997
  exportFormat: z
953
998
  .enum(["csv", "json", "sarif"])
954
999
  .default("sarif")
955
- .describe("Export format (default: sarif)."),
1000
+ .describe("Artifact format to export from the completed scan."),
956
1001
  output: optionValue("--output")
957
1002
  .optional()
958
- .describe("Write the selected format to FILE or stdout with '-'."),
1003
+ .describe("FILE or '-' for stdout (default: results.sarif, findings.json, or findings.csv)."),
959
1004
  sourceRoot: optionValue("--source-root")
960
1005
  .optional()
961
1006
  .describe("Repository checkout used for SARIF source-line fingerprints."),
@@ -998,7 +1043,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
998
1043
  codex: z
999
1044
  .array(optionValue("--codex"))
1000
1045
  .default([])
1001
- .describe('Set model="gpt-5.6-terra" or model_reasoning_effort="high".'),
1046
+ .describe('Repeat TOML model="gpt-5.6-terra" or model_reasoning_effort="high" only.'),
1002
1047
  }),
1003
1048
  async run({ options }) {
1004
1049
  try {
@@ -1025,7 +1070,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1025
1070
  codex: z
1026
1071
  .array(optionValue("--codex"))
1027
1072
  .default([])
1028
- .describe('Set model="gpt-5.6-terra" or model_reasoning_effort="high".'),
1073
+ .describe('Repeat TOML model="gpt-5.6-terra" or model_reasoning_effort="high" only.'),
1029
1074
  }),
1030
1075
  async run({ options }) {
1031
1076
  try {
@@ -1059,15 +1104,25 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1059
1104
  .describe("Read an access token from stdin."),
1060
1105
  }),
1061
1106
  async run({ args, options }) {
1107
+ const credentialHome = dependencies.prepareAuthenticationHome !== undefined
1108
+ ? await dependencies.prepareAuthenticationHome(dependencies.environment)
1109
+ : codexSecurityCredentialHome(dependencies.environment);
1110
+ const authenticationEnvironment = {
1111
+ ...dependencies.environment,
1112
+ CODEX_HOME: credentialHome,
1113
+ };
1062
1114
  exitCode = await dependencies.runCodex([
1063
1115
  "login",
1064
1116
  ...(args.action === undefined ? [] : [args.action]),
1065
1117
  ...(options.deviceAuth ? ["--device-auth"] : []),
1066
1118
  ...(options.withApiKey ? ["--with-api-key"] : []),
1067
1119
  ...(options.withAccessToken ? ["--with-access-token"] : []),
1068
- "-c",
1069
- 'cli_auth_credentials_store="file"',
1070
- ]);
1120
+ ], undefined, authenticationEnvironment);
1121
+ if (args.action === undefined &&
1122
+ exitCode === 0 &&
1123
+ dependencies.prepareAuthenticationHome !== undefined) {
1124
+ await setCodexSecurityCredentialLogout(credentialHome, false);
1125
+ }
1071
1126
  if (args.action === "status") {
1072
1127
  const authentication = scanAuthentication(dependencies.environment);
1073
1128
  if (authentication.method === "api_key" &&
@@ -1104,11 +1159,18 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1104
1159
  destructive: true,
1105
1160
  mcp: false,
1106
1161
  async run() {
1107
- exitCode = await dependencies.runCodex([
1108
- "logout",
1109
- "-c",
1110
- 'cli_auth_credentials_store="file"',
1111
- ]);
1162
+ const credentialHome = dependencies.prepareAuthenticationHome !== undefined
1163
+ ? await dependencies.prepareAuthenticationHome(dependencies.environment)
1164
+ : codexSecurityCredentialHome(dependencies.environment);
1165
+ const authenticationEnvironment = {
1166
+ ...dependencies.environment,
1167
+ CODEX_HOME: credentialHome,
1168
+ };
1169
+ exitCode = await dependencies.runCodex(["logout"], undefined, authenticationEnvironment);
1170
+ if (exitCode === 0 &&
1171
+ dependencies.prepareAuthenticationHome !== undefined) {
1172
+ await setCodexSecurityCredentialLogout(credentialHome, true);
1173
+ }
1112
1174
  },
1113
1175
  })
1114
1176
  .command("info", {
@@ -1308,8 +1370,9 @@ function validateCliArguments(argv, positionals) {
1308
1370
  argv[index + 1] === "json" ||
1309
1371
  argv[index + 1] === "jsonl")));
1310
1372
  if (structuredOutput &&
1311
- ["validate", "patch", "login", "logout"].includes(command)) {
1312
- return `${command} does not support noninteractive JSON output; run it without --json or --format json.`;
1373
+ ["validate", "patch", "login", "logout"].includes(command) &&
1374
+ !argv.includes("--schema")) {
1375
+ return `${command} does not support noninteractive JSON output; run it without --json, --format json, or --format jsonl.`;
1313
1376
  }
1314
1377
  if (command === "export" &&
1315
1378
  structuredOutput &&