@openai/codex-security 0.8.0 → 0.8.1

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 (73) hide show
  1. package/README.md +8 -8
  2. package/_bundled_plugin/.codex-plugin/plugin.json +1 -0
  3. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  6. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  7. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  8. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  9. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  10. package/_bundled_plugin/references/scan-artifacts.md +1 -1
  11. package/_bundled_plugin/scripts/finalize_scan_contract.py +37 -1
  12. package/_bundled_plugin/scripts/servicenow_avit.py +107 -0
  13. package/_bundled_plugin/scripts/workbench_scan_start.py +4 -1
  14. package/_bundled_plugin/skills/publish-findings/SKILL.md +5 -3
  15. package/_bundled_plugin/skills/security-scan/SKILL.md +1 -1
  16. package/dist/api.d.ts.map +1 -1
  17. package/dist/api.js +33 -12
  18. package/dist/api.js.map +1 -1
  19. package/dist/artifact-export.d.ts +12 -3
  20. package/dist/artifact-export.d.ts.map +1 -1
  21. package/dist/artifact-export.js +30 -10
  22. package/dist/artifact-export.js.map +1 -1
  23. package/dist/cli-help.d.ts.map +1 -1
  24. package/dist/cli-help.js +1 -0
  25. package/dist/cli-help.js.map +1 -1
  26. package/dist/cli.d.ts +1 -1
  27. package/dist/cli.d.ts.map +1 -1
  28. package/dist/cli.js +45 -42
  29. package/dist/cli.js.map +1 -1
  30. package/dist/contract.d.ts +1 -0
  31. package/dist/contract.d.ts.map +1 -1
  32. package/dist/contract.js +12 -8
  33. package/dist/contract.js.map +1 -1
  34. package/dist/custom-validation-prompt.d.ts.map +1 -1
  35. package/dist/custom-validation-prompt.js +12 -4
  36. package/dist/custom-validation-prompt.js.map +1 -1
  37. package/dist/external-findings-local.d.ts.map +1 -1
  38. package/dist/external-findings-local.js +19 -0
  39. package/dist/external-findings-local.js.map +1 -1
  40. package/dist/external-findings-publish.d.ts.map +1 -1
  41. package/dist/external-findings-publish.js +5 -4
  42. package/dist/external-findings-publish.js.map +1 -1
  43. package/dist/github-advisories.d.ts.map +1 -1
  44. package/dist/github-advisories.js +5 -5
  45. package/dist/github-advisories.js.map +1 -1
  46. package/dist/github-dependabot-findings.d.ts +6 -0
  47. package/dist/github-dependabot-findings.d.ts.map +1 -0
  48. package/dist/github-dependabot-findings.js +247 -0
  49. package/dist/github-dependabot-findings.js.map +1 -0
  50. package/dist/github-findings.d.ts.map +1 -1
  51. package/dist/github-findings.js +11 -4
  52. package/dist/github-findings.js.map +1 -1
  53. package/dist/github-identifiers.d.ts +4 -0
  54. package/dist/github-identifiers.d.ts.map +1 -0
  55. package/dist/github-identifiers.js +9 -0
  56. package/dist/github-identifiers.js.map +1 -0
  57. package/dist/github.d.ts.map +1 -1
  58. package/dist/github.js +4 -6
  59. package/dist/github.js.map +1 -1
  60. package/dist/hosted-scan.d.ts.map +1 -1
  61. package/dist/hosted-scan.js +13 -5
  62. package/dist/hosted-scan.js.map +1 -1
  63. package/dist/index.d.ts +1 -0
  64. package/dist/index.d.ts.map +1 -1
  65. package/dist/index.js +1 -0
  66. package/dist/index.js.map +1 -1
  67. package/dist/scanner-import.d.ts +0 -1
  68. package/dist/scanner-import.d.ts.map +1 -1
  69. package/dist/scanner-import.js +9 -9
  70. package/dist/scanner-import.js.map +1 -1
  71. package/docs/cli.md +39 -7
  72. package/docs/hosted-scans.md +14 -0
  73. package/package.json +4 -4
package/dist/cli.js CHANGED
@@ -71,6 +71,7 @@ import { prepareKnowledgeBase, readKnowledgeBaseSnapshot, } from "./knowledge-ba
71
71
  import { restoreScanKnowledge, scanInputIdentity } from "./scan-inputs.js";
72
72
  import { workflowDigest } from "./finding-workflow.js";
73
73
  import { CodexSecurityError, AuthenticationRequiredError, ConfigurationError, InvalidTargetError, IncompleteScanError, LocalPluginBootstrapError, OutputDirectoryError, OutputInsideProtectedRootError, PluginPythonUnavailableError, errorMessage, ScanCostLimitExceededError, ScanInterruptedError, } from "./errors.js";
74
+ import { GHSA_ID } from "./github-identifiers.js";
74
75
  import { GITHUB_ADVISORY_STATES, importGitHubAdvisories, } from "./github-advisories.js";
75
76
  import { GITHUB_ALERT_STATES, importGitHubCodeScanningAlerts, } from "./github.js";
76
77
  import { importLinearIssues, isLinearIssueIdentifier, resolveLinearApiKey, } from "./linear.js";
@@ -2297,14 +2298,14 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2297
2298
  let disabledImportInvocation = false;
2298
2299
  function registerFindingPublication() {
2299
2300
  publication.command("findings", {
2300
- description: "Preview and import selected Wiz, Snyk, Semgrep Code, OpenGrep, Endor, or GitHub findings locally or to Cloud.",
2301
- hint: "For Snyk Open Source SCA vulnerabilities only, prefer native snyk test JSON or an official plugin snyk-findings-export/v1 bundle; Open Source SARIF 2.1.0 is also supported. Snyk licenses, Code, Container, IaC and platform backlogs are unsupported. For Semgrep Code, supply native JSON or SARIF and --source-repository-url. For OpenGrep, supply native JSON and --source-repository-url; imports use the semgrep storage provider and preserve OpenGrep as the scanner origin. For Endor, supply native Finding JSON or endorctl SARIF 2.1.0. For GitHub, supply complete JSON/JSONL saved by import github or import github-advisories. GHSA advisories do not establish an installed dependency or applicability. For Wiz, prefer a native package vulnerability JSON report or named SAST/repository-secret/IaC JSON collections with repository metadata. Normalized JSONL and repository package-vulnerability CSV (SCA only, GitHub repositories) are also supported. Gzip is supported for each format; Wiz CSV does not cover SAST or cloud posture. Other Wiz CSV profiles, scan events, workload secrets, and cloud configuration exports are not supported. --to local stores unassessed evidence for a local repository path without Cloud login. --full-output requires --format json or --format jsonl.\nExample: codex-security publish findings selected-wiz.json --to local --repository ./project --provider wiz --source-key TENANT_ID/vulnerability-finding --dry-run --format json",
2301
+ description: "Preview and import a saved scanner report locally or to Cloud.",
2302
+ hint: "Choose the reader with --provider and keep --source-key stable for reimports. See the scanner import guide for accepted formats, repository requirements and export examples: https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md. Gzip is supported. --to local stores unassessed evidence without Cloud login. --full-output requires --format json or --format jsonl.\nExample: codex-security publish findings selected-wiz.json --to local --repository ./project --provider wiz --source-key TENANT_ID/vulnerability-finding --dry-run --format json",
2302
2303
  destructive: true,
2303
2304
  mcp: false,
2304
2305
  args: z.object({
2305
2306
  file: z
2306
2307
  .string()
2307
- .describe("Snyk native test JSON, plugin SCA bundle or Open Source SARIF; Semgrep Code JSON/SARIF; OpenGrep native JSON; Endor Finding JSON/endorctl SARIF; saved GitHub import output; native Wiz JSON, normalized JSONL, or repository package-vulnerability CSV."),
2308
+ .describe("Saved report in a format accepted by the selected reader."),
2308
2309
  }),
2309
2310
  options: z.object({
2310
2311
  to: z
@@ -2313,7 +2314,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2313
2314
  repository: optionValue("--repository").describe("Local repository path for --to local; authorized repository ID or URL for --to cloud."),
2314
2315
  provider: z
2315
2316
  .enum(EXTERNAL_FINDINGS_READERS)
2316
- .describe("Report reader; OpenGrep uses the semgrep storage provider."),
2317
+ .describe("Select the file reader for this report. OpenGrep findings use the semgrep storage provider."),
2317
2318
  sourceRepositoryUrl: optionValue("--source-repository-url")
2318
2319
  .optional()
2319
2320
  .describe("Required for Semgrep and OpenGrep: source repository URL, checked against the Cloud destination or configured local Git remotes."),
@@ -2626,7 +2627,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2626
2627
  }),
2627
2628
  options: z.object({
2628
2629
  githubAdvisory: z
2629
- .array(optionValue("--github-advisory").regex(/^GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}$/iu, "GitHub advisory IDs must use GHSA-xxxx-xxxx-xxxx form."))
2630
+ .array(optionValue("--github-advisory").regex(GHSA_ID, "GitHub advisory IDs must use GHSA-xxxx-xxxx-xxxx form."))
2630
2631
  .default([])
2631
2632
  .describe("Exact GHSA ID; repeat to select a subset. Required for global advisories."),
2632
2633
  githubAdvisorySource: z
@@ -3859,14 +3860,17 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3859
3860
  .describe("Saved artifact to export."),
3860
3861
  scan: optionValue("--scan")
3861
3862
  .optional()
3862
- .describe("Saved scan ID or unique prefix; cannot be combined with a result directory."),
3863
+ .describe("Saved scan ID, unique prefix, or latest completed scan ('latest')."),
3863
3864
  exportFormat: z
3864
- .enum(["csv", "json", "sarif", "md"])
3865
+ .enum(["csv", "json", "sarif", "md", "servicenow-avit"])
3865
3866
  .optional()
3866
- .describe("Findings: csv, json, or sarif (default); threat-model: md (default)."),
3867
+ .describe("Findings: csv, json, servicenow-avit, or sarif (default). Threat models use md."),
3868
+ avitTemplate: optionValue("--avit-template")
3869
+ .optional()
3870
+ .describe("Per-application CSV template required for servicenow-avit exports."),
3867
3871
  output: optionValue("--output")
3868
3872
  .optional()
3869
- .describe("FILE or '-' for stdout (default: results.sarif, findings.json, findings.csv, or threatmodel.md)."),
3873
+ .describe("FILE or '-' for stdout (default: results.sarif, findings.json, findings.csv, servicenow-avit.csv, or threatmodel.md)."),
3870
3874
  sourceRoot: optionValue("--source-root")
3871
3875
  .optional()
3872
3876
  .describe("Repository checkout used for SARIF source-line fingerprints."),
@@ -3887,7 +3891,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3887
3891
  if (args.scanDir !== undefined && options.scan !== undefined) {
3888
3892
  throw new CodexSecurityError("--scan cannot be combined with a result directory.");
3889
3893
  }
3890
- const format = resolveArtifactFormat(options.artifact, options.exportFormat);
3894
+ const format = resolveArtifactFormat(options.artifact, options.exportFormat, options.avitTemplate);
3891
3895
  const sourceRoot = options.sourceRoot === undefined
3892
3896
  ? undefined
3893
3897
  : resolveCliPath(currentDirectory, options.sourceRoot);
@@ -3896,31 +3900,36 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3896
3900
  : [currentDirectory, sourceRoot];
3897
3901
  let scanDir = args.scanDir;
3898
3902
  if (scanDir === undefined) {
3899
- const scanId = options.scan ??
3900
- (await latestScans(1, "complete", options.python, protectedRoot))?.[0]?.scanId;
3903
+ let scanId = options.scan;
3904
+ if (!scanId || scanId === "latest") {
3905
+ const scans = await latestScans(1, "complete", options.python, protectedRoot);
3906
+ scanId = scans?.[0]?.scanId;
3907
+ }
3901
3908
  if (scanId === undefined)
3902
3909
  return;
3903
- scanDir = await resolveSavedArtifactDirectory(scanId, options.artifact, format, (args) => dependencies.runWorkbench(args, undefined, undefined, options.python, protectedRoot));
3910
+ scanDir = await resolveSavedArtifactDirectory(scanId, options.artifact, (args) => dependencies.runWorkbench(args, undefined, undefined, options.python, protectedRoot));
3904
3911
  }
3905
- const arguments_ = {
3912
+ const destination = options.output ?? EXPORT_DEFAULT_OUTPUTS[format];
3913
+ const outputPath = destination === "-"
3914
+ ? "-"
3915
+ : resolveCliPath(currentDirectory, destination);
3916
+ const prepared = await resolveArtifactExportOutput({
3906
3917
  scanDir: resolveCliPath(currentDirectory, scanDir),
3907
3918
  artifact: options.artifact,
3908
3919
  format,
3909
- output: options.output === "-"
3910
- ? "-"
3911
- : resolveCliPath(currentDirectory, options.output ?? EXPORT_DEFAULT_OUTPUTS[format]),
3920
+ output: outputPath,
3912
3921
  sourceRoot,
3922
+ avitTemplate: options.avitTemplate,
3913
3923
  pythonPath: options.python,
3914
- };
3915
- const prepared = await resolveArtifactExportOutput(arguments_, dependencies.currentDirectory());
3916
- const contents = await dependencies.exportFindings(prepared, output);
3917
- if (arguments_.output === "-") {
3924
+ }, currentDirectory);
3925
+ const contents = await dependencies.exportFindings(prepared, output, errorOutput);
3926
+ if (outputPath === "-") {
3918
3927
  if (contents !== undefined) {
3919
3928
  await writeCliOutput(output, Buffer.from(contents));
3920
3929
  }
3921
3930
  }
3922
3931
  else {
3923
- errorOutput.write(`${arguments_.format.toUpperCase()}: ${arguments_.output}\n`);
3932
+ errorOutput.write(`${format.toUpperCase()}: ${outputPath}\n`);
3924
3933
  }
3925
3934
  exitCode = 0;
3926
3935
  }
@@ -4747,25 +4756,19 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4747
4756
  !argv.includes("--schema")) {
4748
4757
  return `${command} does not support noninteractive JSON output; run it without --json, --format json, or --format jsonl.`;
4749
4758
  }
4750
- if (command === "export" &&
4751
- structuredOutput &&
4752
- argv.some((value, index) => value === "--output=-" ||
4753
- (value === "--output" && argv[index + 1] === "-")) &&
4754
- argv.some((value, index) => value === "--export-format=csv" ||
4755
- value === "--exportFormat=csv" ||
4756
- ((value === "--export-format" || value === "--exportFormat") &&
4757
- argv[index + 1] === "csv"))) {
4758
- return "CSV stdout cannot be combined with JSON output; write CSV to a file or omit --json.";
4759
- }
4760
- if (command === "export" &&
4761
- structuredOutput &&
4762
- argv.some((value, index) => value === "--output=-" ||
4763
- (value === "--output" && argv[index + 1] === "-")) &&
4764
- argv.some((value, index) => value === "--artifact=threat-model" ||
4765
- (value === "--artifact" && argv[index + 1] === "threat-model") ||
4766
- value === "--export-format=md" ||
4767
- (value === "--export-format" && argv[index + 1] === "md"))) {
4768
- return "Markdown stdout cannot be combined with JSON output; write Markdown to a file or omit --json.";
4759
+ if (command === "export" && structuredOutput) {
4760
+ const hasValue = (flag, value) => argv.some((arg, index) => arg === `${flag}=${value}` ||
4761
+ (arg === flag && argv[index + 1] === value));
4762
+ if (hasValue("--output", "-")) {
4763
+ if (["csv", "servicenow-avit"].some((format) => hasValue("--export-format", format) ||
4764
+ hasValue("--exportFormat", format))) {
4765
+ return "CSV stdout cannot be combined with JSON output; write CSV to a file or omit --json.";
4766
+ }
4767
+ if (hasValue("--artifact", "threat-model") ||
4768
+ hasValue("--export-format", "md")) {
4769
+ return "Markdown stdout cannot be combined with JSON output; write Markdown to a file or omit --json.";
4770
+ }
4771
+ }
4769
4772
  }
4770
4773
  if (command === "scan" && !argv.includes("--schema")) {
4771
4774
  if (argv.some((value) => value === "--filter-output" || value.startsWith("--filter-output="))) {
@@ -5479,7 +5482,7 @@ async function selectSavedFindings(identifiers, requestedScanId, severity, depen
5479
5482
  };
5480
5483
  }
5481
5484
  async function readSavedFindings(scanId, workbench) {
5482
- const directory = await resolveSavedArtifactDirectory(scanId, "findings", "json", workbench);
5485
+ const directory = await resolveSavedArtifactDirectory(scanId, "findings", workbench);
5483
5486
  const { findings } = await loadContract(directory, {
5484
5487
  pluginRoot: await bundledPluginRoot(),
5485
5488
  expectedScanId: scanId,