@openai/codex-security 0.1.1 → 0.1.2

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
@@ -21,7 +21,7 @@ import { bundledPluginRoot, codexSecurityStateDirectory, expandHome, resolveCode
21
21
  import { matchScanFindings, } from "./scan-comparison.js";
22
22
  import { renderScanHistory, } from "./scan-history-renderer.js";
23
23
  import { DiffTarget } from "./targets.js";
24
- import { BUNDLED_PLUGIN_VERSION, CODEX_EXECUTABLE_VERSION, CODEX_SDK_VERSION, VERSION, } from "./version.js";
24
+ import { BUNDLED_PLUGIN_VERSION, checkForUpdate, CODEX_EXECUTABLE_VERSION, CODEX_SDK_VERSION, formatUpdateNotice, updateNoticeEnabled, VERSION, } from "./version.js";
25
25
  const PROGRESS_REFRESH_MILLISECONDS = 1_000;
26
26
  const MAX_CODEX_OVERRIDE_KEY_LENGTH = 1_024;
27
27
  const MAX_CODEX_OVERRIDE_VALUE_LENGTH = 64 * 1_024;
@@ -43,6 +43,14 @@ const DISPLAY_SEVERITIES = [
43
43
  ...REPORTABLE_SEVERITIES,
44
44
  "informational",
45
45
  ];
46
+ const MODEL_REASONING_EFFORTS = [
47
+ "minimal",
48
+ "low",
49
+ "medium",
50
+ "high",
51
+ "xhigh",
52
+ ];
53
+ const DEFAULT_SCAN_MODEL_CONFIGURATION = scanModelConfiguration(DEFAULT_CODEX_CONFIG);
46
54
  const EXPORT_DEFAULT_OUTPUTS = {
47
55
  csv: "findings.csv",
48
56
  json: "findings.json",
@@ -57,6 +65,7 @@ const VALUE_OPTIONS = new Set([
57
65
  "--base",
58
66
  "--mode",
59
67
  "--model",
68
+ "--effort",
60
69
  "--output-dir",
61
70
  "--plugin-path",
62
71
  "--python",
@@ -73,13 +82,23 @@ const VALUE_OPTIONS = new Set([
73
82
  "--token-limit",
74
83
  "--token-offset",
75
84
  "--scan-root",
85
+ "--reason",
76
86
  ]);
77
87
  function optionValue(flag) {
78
88
  return z.string().min(1, `${flag} must not be empty.`);
79
89
  }
90
+ function effortOption() {
91
+ return z
92
+ .enum(MODEL_REASONING_EFFORTS, {
93
+ error: "--effort must be minimal, low, medium, high, or xhigh.",
94
+ })
95
+ .optional()
96
+ .describe(`Model reasoning effort (default: ${DEFAULT_SCAN_MODEL_CONFIGURATION.reasoningEffort}).`);
97
+ }
80
98
  const DEFAULT_DEPENDENCIES = {
81
99
  createSecurity: (config) => new CodexSecurity(config),
82
100
  environment: process.env,
101
+ checkForUpdate: () => checkForUpdate({ environment: process.env }),
83
102
  hasStoredChatGPTSignIn: async () => {
84
103
  const environment = Object.fromEntries(Object.entries(process.env).filter(([name]) => name.toUpperCase() !== "OPENAI_API_KEY" &&
85
104
  name.toUpperCase() !== "CODEX_API_KEY"));
@@ -303,6 +322,21 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
303
322
  errorOutput.write(`codex-security: ${argumentError}\n`);
304
323
  return 2;
305
324
  }
325
+ const pendingUpdate = errorOutput.isTTY === true &&
326
+ argv.length > 0 &&
327
+ argv[0] !== "completions" &&
328
+ !argv.some((argument) => [
329
+ "--help",
330
+ "-h",
331
+ "--version",
332
+ "--llms",
333
+ "--llms-full",
334
+ "--schema",
335
+ "--dry-run",
336
+ ].includes(argument)) &&
337
+ updateNoticeEnabled(dependencies.environment)
338
+ ? dependencies.checkForUpdate().catch(() => undefined)
339
+ : undefined;
306
340
  let exitCode = 0;
307
341
  let frameworkExit;
308
342
  let frameworkOutput = "";
@@ -335,6 +369,43 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
335
369
  });
336
370
  return result;
337
371
  };
372
+ const findingFeedback = Cli.create("findings", {
373
+ description: "Review and manage saved Codex Security findings.",
374
+ }).command("false-positive", {
375
+ description: "Mark a finding as a false positive for future scans.",
376
+ destructive: true,
377
+ mcp: false,
378
+ args: z.object({
379
+ occurrenceId: z
380
+ .string()
381
+ .trim()
382
+ .min(1)
383
+ .max(256)
384
+ .describe("Finding occurrence identifier."),
385
+ }),
386
+ options: z.object({
387
+ reason: z
388
+ .string()
389
+ .trim()
390
+ .min(1, "--reason must not be empty.")
391
+ .max(2_400, "--reason must not exceed 2400 characters.")
392
+ .describe("Explanation for why the finding is a false positive."),
393
+ }),
394
+ output: z.record(z.string(), z.unknown()).optional(),
395
+ async run({ args, options }) {
396
+ return await history([
397
+ "set-finding-triage",
398
+ "--occurrence-id",
399
+ args.occurrenceId,
400
+ "--status",
401
+ "closed",
402
+ "--close-reason",
403
+ "false_positive",
404
+ "--note",
405
+ options.reason,
406
+ ]);
407
+ },
408
+ });
338
409
  const scanHistory = Cli.create("scans", {
339
410
  description: "List, inspect, rerun, match, and compare saved Codex Security scans.",
340
411
  })
@@ -574,7 +645,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
574
645
  .describe("Scan mode."),
575
646
  model: optionValue("--model")
576
647
  .optional()
577
- .describe("Model to use for the scan."),
648
+ .describe(`OpenAI model to use (default: ${DEFAULT_SCAN_MODEL_CONFIGURATION.model}).`),
649
+ effort: effortOption(),
578
650
  outputDir: optionValue("--output-dir")
579
651
  .optional()
580
652
  .describe("Write scan artifacts to DIR."),
@@ -591,7 +663,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
591
663
  codex: z
592
664
  .array(optionValue("--codex"))
593
665
  .default([])
594
- .describe("Override isolated Codex config with KEY=VALUE; repeat as needed."),
666
+ .describe('Override Codex settings; e.g. model_reasoning_effort="high".'),
595
667
  failOnSeverity: z
596
668
  .enum(REPORTABLE_SEVERITIES)
597
669
  .optional()
@@ -620,6 +692,10 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
620
692
  examples: [
621
693
  { args: { repository: "." } },
622
694
  { args: { repository: "." }, options: { model: "gpt-5.6-terra" } },
695
+ {
696
+ args: { repository: "." },
697
+ options: { model: "gpt-5.6-terra", effort: "high" },
698
+ },
623
699
  { args: { repository: "." }, options: { path: ["src", "tests"] } },
624
700
  { args: { repository: "." }, options: { diff: "origin/main" } },
625
701
  ],
@@ -641,6 +717,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
641
717
  base: options.base,
642
718
  mode: options.mode,
643
719
  model: options.model,
720
+ effort: options.effort,
644
721
  outputDir: options.outputDir,
645
722
  archiveExisting: options.archiveExisting,
646
723
  pluginPath: options.pluginPath,
@@ -658,6 +735,11 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
658
735
  exitCode,
659
736
  });
660
737
  }
738
+ if (!options.dryRun &&
739
+ format === "toon" &&
740
+ !argv.some((argument) => SCAN_HISTORY_OUTPUT_OPTION.test(argument))) {
741
+ return;
742
+ }
661
743
  return outcome.data;
662
744
  },
663
745
  })
@@ -727,6 +809,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
727
809
  },
728
810
  })
729
811
  .command(scanHistory)
812
+ .command(findingFeedback)
730
813
  .command("bulk-scan", {
731
814
  description: "Discover repositories and run resumable bulk security scans.",
732
815
  destructive: true,
@@ -748,7 +831,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
748
831
  mode: z.enum(["standard", "deep"]).default("standard"),
749
832
  model: optionValue("--model")
750
833
  .optional()
751
- .describe("Model to use for each repository."),
834
+ .describe(`OpenAI model for each repository (default: ${DEFAULT_SCAN_MODEL_CONFIGURATION.model}).`),
835
+ effort: effortOption(),
752
836
  maxAttempts: z
753
837
  .number()
754
838
  .int()
@@ -757,7 +841,10 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
757
841
  .describe("Maximum scan attempts per repository."),
758
842
  pluginPath: z.string().min(1).optional(),
759
843
  python: z.string().min(1).optional(),
760
- codex: z.array(z.string().min(1)).default([]),
844
+ codex: z
845
+ .array(z.string().min(1))
846
+ .default([])
847
+ .describe('Override Codex settings; e.g. model_reasoning_effort="high".'),
761
848
  }),
762
849
  output: z.record(z.string(), z.unknown()).optional(),
763
850
  async run({ args, options }) {
@@ -777,11 +864,25 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
777
864
  let outputDir;
778
865
  let githubHost;
779
866
  if (args.input === undefined) {
780
- if (argv[0] !== "bulk-scan" ||
781
- !(argv.length === 1 ||
782
- (argv.length === 3 && argv[1] === "--model") ||
783
- (argv.length === 2 && argv[1] === `--model=${options.model}`))) {
784
- throw new Error("Run 'codex-security bulk-scan [--model MODEL]' to discover repositories, or provide a CSV and --output-dir.");
867
+ let optionIndex = 1;
868
+ while (optionIndex < argv.length) {
869
+ const argument = argv[optionIndex];
870
+ if (argument === "--model" ||
871
+ argument === "--effort" ||
872
+ argument === "--codex") {
873
+ optionIndex += 2;
874
+ }
875
+ else if (argument.startsWith("--model=") ||
876
+ argument.startsWith("--effort=") ||
877
+ argument.startsWith("--codex=")) {
878
+ optionIndex += 1;
879
+ }
880
+ else {
881
+ break;
882
+ }
883
+ }
884
+ if (argv[0] !== "bulk-scan" || optionIndex !== argv.length) {
885
+ throw new Error("Run 'codex-security bulk-scan [--model MODEL] [--effort EFFORT] [--codex KEY=VALUE]' to discover repositories, or provide a CSV and --output-dir.");
785
886
  }
786
887
  const wizard = await runBulkScanWizard(dependencies.bulkScan ??
787
888
  createBulkScanDiscoveryDependencies({
@@ -812,7 +913,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
812
913
  config: {
813
914
  pluginPath: options.pluginPath,
814
915
  pythonPath: options.python,
815
- codexOverrides: parseCodexOverrides(options.codex, options.model),
916
+ codexOverrides: parseCodexOverrides(options.codex, options.model, options.effort),
816
917
  },
817
918
  createSecurity: dependencies.createSecurity,
818
919
  signal: controller.signal,
@@ -893,14 +994,15 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
893
994
  .describe("Finding text or a file containing findings."),
894
995
  }),
895
996
  options: z.object({
997
+ effort: effortOption(),
896
998
  codex: z
897
999
  .array(optionValue("--codex"))
898
1000
  .default([])
899
- .describe("Override model or model_reasoning_effort with KEY=VALUE."),
1001
+ .describe('Set model="gpt-5.6-terra" or model_reasoning_effort="high".'),
900
1002
  }),
901
1003
  async run({ options }) {
902
1004
  try {
903
- exitCode = await runSkill("validation", positionals, options.codex, output, errorOutput, dependencies);
1005
+ exitCode = await runSkill("validation", positionals, options.codex, options.effort, output, errorOutput, dependencies);
904
1006
  }
905
1007
  catch (error) {
906
1008
  exitCode = 2;
@@ -919,14 +1021,15 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
919
1021
  .describe("Issue text or a file containing issues."),
920
1022
  }),
921
1023
  options: z.object({
1024
+ effort: effortOption(),
922
1025
  codex: z
923
1026
  .array(optionValue("--codex"))
924
1027
  .default([])
925
- .describe("Override model or model_reasoning_effort with KEY=VALUE."),
1028
+ .describe('Set model="gpt-5.6-terra" or model_reasoning_effort="high".'),
926
1029
  }),
927
1030
  async run({ options }) {
928
1031
  try {
929
- exitCode = await runSkill("fix-finding", positionals, options.codex, output, errorOutput, dependencies);
1032
+ exitCode = await runSkill("fix-finding", positionals, options.codex, options.effort, output, errorOutput, dependencies);
930
1033
  }
931
1034
  catch (error) {
932
1035
  exitCode = 2;
@@ -1040,7 +1143,9 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1040
1143
  };
1041
1144
  },
1042
1145
  });
1043
- await cli.serve([...argv], {
1146
+ await cli.serve(argv.flatMap((argument) => argument.startsWith("--format=")
1147
+ ? ["--format", argument.slice("--format=".length)]
1148
+ : [argument]), {
1044
1149
  stdout: (value) => {
1045
1150
  frameworkOutput += value;
1046
1151
  },
@@ -1048,6 +1153,11 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1048
1153
  frameworkExit = code;
1049
1154
  },
1050
1155
  });
1156
+ if (pendingUpdate !== undefined) {
1157
+ const notice = await pendingUpdate;
1158
+ if (notice !== undefined)
1159
+ errorOutput.write(formatUpdateNotice(notice));
1160
+ }
1051
1161
  if (frameworkExit !== undefined) {
1052
1162
  if (exitCode !== 0)
1053
1163
  return exitCode;
@@ -1174,6 +1284,7 @@ function validateCliArguments(argv, positionals) {
1174
1284
  "install-hook",
1175
1285
  "bulk-scan",
1176
1286
  "scans",
1287
+ "findings",
1177
1288
  "export",
1178
1289
  "validate",
1179
1290
  "patch",
@@ -1213,7 +1324,8 @@ function validateCliArguments(argv, positionals) {
1213
1324
  return "Markdown output is not supported for scan results.";
1214
1325
  }
1215
1326
  }
1216
- const subcommand = command === "scans" ? argv[commandIndex + 1] : undefined;
1327
+ const nestedCommand = command === "scans" || command === "findings";
1328
+ const subcommand = nestedCommand ? argv[commandIndex + 1] : undefined;
1217
1329
  if (command === "info") {
1218
1330
  const metadataFields = new Set([
1219
1331
  "sdkVersion",
@@ -1242,7 +1354,7 @@ function validateCliArguments(argv, positionals) {
1242
1354
  }
1243
1355
  }
1244
1356
  }
1245
- for (let index = commandIndex + (command === "scans" ? 2 : 1); index < argv.length; index += 1) {
1357
+ for (let index = commandIndex + (nestedCommand ? 2 : 1); index < argv.length; index += 1) {
1246
1358
  const value = argv[index];
1247
1359
  if (!value.startsWith("-")) {
1248
1360
  positionals.push(value);
@@ -1346,11 +1458,11 @@ function staysWithinWindowsDeviceRoot(input, root) {
1346
1458
  }
1347
1459
  return true;
1348
1460
  }
1349
- async function runSkill(skill, inputs, codexOverrides, stdout, stderr, dependencies) {
1461
+ async function runSkill(skill, inputs, codexOverrides, effort, stdout, stderr, dependencies) {
1350
1462
  if (inputs.length > MAX_SKILL_INPUT_COUNT) {
1351
1463
  throw new CodexSecurityError("Skill inputs exceed the 64-item limit.");
1352
1464
  }
1353
- const overrides = parseCodexOverrides(codexOverrides);
1465
+ const overrides = parseCodexOverrides(codexOverrides, undefined, effort);
1354
1466
  if (Object.keys(overrides).some((key) => key !== "model" && key !== "model_reasoning_effort")) {
1355
1467
  throw new CodexSecurityError("Validation and patching only support model and model_reasoning_effort overrides.");
1356
1468
  }
@@ -1590,7 +1702,6 @@ async function runScan(arguments_, errorOutput, dependencies, interactive = true
1590
1702
  let firstSignalAt = 0;
1591
1703
  let progress = null;
1592
1704
  let lastWorkerUpdate = "";
1593
- let workerCapacity = null;
1594
1705
  let phase = null;
1595
1706
  const preparationAbortController = new AbortController();
1596
1707
  const signalListener = (signal) => () => {
@@ -1640,7 +1751,7 @@ async function runScan(arguments_, errorOutput, dependencies, interactive = true
1640
1751
  pluginPath: arguments_.pluginPath,
1641
1752
  pythonPath: arguments_.pythonPath,
1642
1753
  codexOverrides: arguments_.codexOverrides ??
1643
- parseCodexOverrides(arguments_.codex, arguments_.model),
1754
+ parseCodexOverrides(arguments_.codex, arguments_.model, arguments_.effort),
1644
1755
  };
1645
1756
  let auth = arguments_.auth;
1646
1757
  selectedAuthentication = scanAuthentication(dependencies.environment, auth);
@@ -1742,10 +1853,8 @@ async function runScan(arguments_, errorOutput, dependencies, interactive = true
1742
1853
  if (update === lastWorkerUpdate)
1743
1854
  return;
1744
1855
  lastWorkerUpdate = update;
1745
- if (status.kind === "dispatch") {
1746
- workerCapacity = { planned: status.planned, started: status.started };
1856
+ if (status.kind === "dispatch")
1747
1857
  phase = scanPhase(status.phase);
1748
- }
1749
1858
  const message = workerStatusMessage(status);
1750
1859
  if (message === null || progress === null)
1751
1860
  return;
@@ -1753,6 +1862,9 @@ async function runScan(arguments_, errorOutput, dependencies, interactive = true
1753
1862
  progress.stage(message);
1754
1863
  progress.startTimer(runningMessage());
1755
1864
  },
1865
+ onWarning: (warning) => {
1866
+ errorOutput.write(`codex-security: warning: ${cliErrorMessage(warning)}\n`);
1867
+ },
1756
1868
  onObserverError: (observer, error) => {
1757
1869
  errorOutput.write(`codex-security: warning: ${observer} observer failed: ${cliErrorMessage(error)}\n`);
1758
1870
  },
@@ -1821,7 +1933,7 @@ async function runScan(arguments_, errorOutput, dependencies, interactive = true
1821
1933
  const blockingCount = result.findings.findings.filter(({ severity }) => blockingSeverities.has(severity.level)).length;
1822
1934
  const incomplete = result.coverage.completeness !== "complete";
1823
1935
  progress?.stage("Scan complete");
1824
- printScanSummary(result, progress, errorOutput, workerCapacity);
1936
+ printScanSummary(result, progress, errorOutput);
1825
1937
  if (incomplete) {
1826
1938
  errorOutput.write(threshold === undefined
1827
1939
  ? `codex-security: Scan coverage is ${result.coverage.completeness}; results may be incomplete.\n`
@@ -1848,9 +1960,7 @@ function scanFailureMessage(error, authentication) {
1848
1960
  case "rate_limited":
1849
1961
  return "The configured account reached its rate limit. Wait and retry.";
1850
1962
  case "network_error":
1851
- return "The model service could not be reached. Check your network connection and try again.";
1852
1963
  case "timeout":
1853
- return "The connection timed out. Check your network connection and try again.";
1854
1964
  case "unknown":
1855
1965
  return cliErrorMessage(error);
1856
1966
  }
@@ -1882,7 +1992,7 @@ function scanPhase(value) {
1882
1992
  attack_path: "analyzing attack paths",
1883
1993
  }[value];
1884
1994
  }
1885
- function printScanSummary(result, progress, errorOutput, workers) {
1995
+ function printScanSummary(result, progress, errorOutput) {
1886
1996
  const severities = new Map();
1887
1997
  for (const finding of result.findings.findings) {
1888
1998
  severities.set(finding.severity.level, (severities.get(finding.severity.level) ?? 0) + 1);
@@ -1901,7 +2011,7 @@ function printScanSummary(result, progress, errorOutput, workers) {
1901
2011
  completed >= started
1902
2012
  ? Math.floor((completed - started) / 1_000)
1903
2013
  : progress?.elapsedSeconds ?? 0;
1904
- errorOutput.write(`codex-security: Elapsed: ${elapsed}s.${workers === null ? "" : ` Workers: ${workers.started}/${workers.planned}.`}\n`);
2014
+ errorOutput.write(`codex-security: Elapsed: ${elapsed}s.\n`);
1905
2015
  const tokenSummary = formatTokenUsage(result.turnResult.usage);
1906
2016
  if (tokenSummary !== null) {
1907
2017
  errorOutput.write(`codex-security: Tokens: ${tokenSummary}.\n`);
@@ -1909,11 +2019,8 @@ function printScanSummary(result, progress, errorOutput, workers) {
1909
2019
  if (result.cost !== null) {
1910
2020
  errorOutput.write(`codex-security: Estimated cost: ${formatUsd(result.cost.estimatedUsd)} USD.\n`);
1911
2021
  }
1912
- const scanDir = cliErrorMessage(result.scanDir);
1913
- errorOutput.write(`codex-security: Results: ${scanDir}\n`);
1914
- errorOutput.write(result.sarifPath === null
1915
- ? `codex-security: Next: codex-security export ${quoteCliPath(scanDir)} --export-format sarif\n`
1916
- : `codex-security: Next: review ${cliErrorMessage(result.reportPath)}\n`);
2022
+ errorOutput.write(`codex-security: Report: ${cliErrorMessage(result.reportPath)}\n`);
2023
+ errorOutput.write(`codex-security: Results: ${cliErrorMessage(result.scanDir)}\n`);
1917
2024
  }
1918
2025
  function formatTokenUsage(usage) {
1919
2026
  if (usage === null || typeof usage !== "object")
@@ -2009,10 +2116,12 @@ function targetFromArguments(arguments_) {
2009
2116
  }
2010
2117
  return "repository";
2011
2118
  }
2012
- export function parseCodexOverrides(values, model) {
2119
+ export function parseCodexOverrides(values, model, effort) {
2013
2120
  const result = Object.create(null);
2014
2121
  if (model !== undefined)
2015
2122
  result["model"] = model;
2123
+ if (effort !== undefined)
2124
+ result["model_reasoning_effort"] = effort;
2016
2125
  for (const value of values) {
2017
2126
  const separator = value.indexOf("=");
2018
2127
  const key = separator < 0 ? "" : value.slice(0, separator);
@@ -2056,9 +2165,13 @@ export function parseCodexOverrides(values, model) {
2056
2165
  }
2057
2166
  const final = parts.at(-1);
2058
2167
  if (Object.hasOwn(cursor, final)) {
2059
- throw new CodexSecurityError(model !== undefined && key === "model"
2060
- ? "--model conflicts with --codex model"
2061
- : "Duplicate --codex key");
2168
+ if (model !== undefined && key === "model") {
2169
+ throw new CodexSecurityError("--model conflicts with --codex model");
2170
+ }
2171
+ if (effort !== undefined && key === "model_reasoning_effort") {
2172
+ throw new CodexSecurityError("--effort conflicts with --codex model_reasoning_effort");
2173
+ }
2174
+ throw new CodexSecurityError("Duplicate --codex key");
2062
2175
  }
2063
2176
  cursor[final] = parsed;
2064
2177
  }