Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

5.6 KB
Raw Blame
export type Inputs = ReturnType<typeof parseInputs>;

export function parseInputs(read: (name: string) => string, workspace: string) {
  const str = (name: string, fallback = '') => read(name).trim() || fallback;
  const choice = <T extends string>(name: string, values: readonly T[], fallback: T): T => {
    const value = str(name, fallback);
    if (!values.includes(value as T)) throw new Error(`${name} must be one of: ${values.join(', ')}.`);
    return value as T;
  };
  const bool = (name: string, fallback: boolean) => choice(name, ['true', 'false'], String(fallback) as 'true' | 'false') === 'true';
  const num = (name: string, integer: boolean, min = 0, max = Infinity) => {
    const value = str(name);
    if (!value) return undefined;
    const n = Number(value);
    if (!Number.isFinite(n) || (integer && !Number.isSafeInteger(n)) || n < min || n > max) {
      const bounds = min === Number.MIN_VALUE
        ? `a positive number${max < Infinity ? ` no greater than ${max}` : ''}`
        : `${integer ? 'an integer' : 'a number'} between ${min} and ${max}`;
      throw new Error(`${name} must be ${bounds}.`);
    }
    return n;
  };
  const safeRelative = (name: string, value: string) => {
    if (value.startsWith('/') || /^[A-Za-z]:/.test(value) || value.includes('\\') || value.split('/').includes('..') || /[\x00-\x1f\x7f]/.test(value))
      throw new Error(`${name} must contain literal repository-relative paths without '..', backslashes or control characters.`);
    return value;
  };
  // Match the CLI's scope spelling before constructing arguments or checking reports.
  const paths = [...new Set(read('paths').split(/\r?\n/).filter(Boolean).map(v =>
    safeRelative('paths', v).split('/').filter(part => part && part !== '.').join('/') || '.'))];
  const scope = choice('scope', ['repository', 'diff'], 'repository');
  if (scope !== 'repository' && paths.length)
    throw new Error(`paths cannot be combined with scope: ${scope}. Remove paths to scan changes, or use scope: repository to scan selected paths.`);
  const diffBase = str('diff-base') || undefined;
  if (diffBase && scope !== 'diff') throw new Error('diff-base requires scope: diff.');
  const mode = choice('mode', ['standard', 'deep'], 'standard');
  if (mode === 'deep' && scope !== 'repository') throw new Error('mode: deep requires scope: repository.');
  const maxTimeHours = num('max-time-hours', false, Number.MIN_VALUE, 96);
  if (maxTimeHours !== undefined && mode !== 'deep') throw new Error('max-time-hours requires mode: deep.');
  const dryRun = bool('dry-run', false);
  const failOnSeverity = choice('fail-on-severity', ['none','low','medium','high','critical'], 'none');
  if (dryRun && failOnSeverity !== 'none')
    throw new Error('dry-run requires fail-on-severity: none. Configuration validation cannot satisfy a required security review.');
  const provider = choice('provider', ['openai', 'openrouter', 'fireworks', 'amazon-bedrock'], 'openai');
  const model = str('model', provider === 'openai' ? 'gpt-5.6-sol' : '');
  const cyberAccessProgram = str('cyber-access-program')
    ? choice('cyber-access-program', ['standard', 'daybreak_blue', 'daybreak_red'], 'standard')
    : undefined;
  return {
    repository: str('repository', workspace), scope, paths, diffBase, mode, cyberAccessProgram,
    provider, model, effort: str('effort', 'xhigh'),
    maxCost: num('max-cost', false, Number.MIN_VALUE), maxTimeHours, failOnSeverity,
    verbose: bool('verbose', true), dryRun,
    summary: bool('summary', true), annotations: bool('annotations', true),
    uploadArtifacts: bool('upload-artifacts', false), artifactName: str('artifact-name', 'codex-security'), retentionDays: num('retention-days', true, 1, 90) ?? 7,
  };
}

export function scanArguments(inputs: Inputs, target: {repository: string; diffBase?: string; diffHead?: string}, resultsDirectory: string): string[] {
  // The pinned CLI checks API-key presence even during local preflight. Its
  // dry-run branch never starts a model session; auto allows keyless preflight
  // with our empty private credential home. Bedrock selects native AWS auth.
  const auth = inputs.dryRun || inputs.provider === 'amazon-bedrock' ? 'auto' : 'api-key';
  const args = ['scan', target.repository, '--auth', auth, '--provider', inputs.provider, '--mode', inputs.mode,
    ...(inputs.model ? [`--model=${inputs.model}`] : []), `--effort=${inputs.effort}`, '--headless',
    '--output-dir', resultsDirectory, '--format', 'json'];
  // Preserve the pinned CLI's sandbox and automatic approval-review defaults.
  // Forcing approval_policy="never" prevents recovery from hosted Linux sandbox errors.
  args.push('--codex', 'analytics.enabled=false',
    '--codex', 'responses_api_metadata.codex_security_integration="github_action"',
    '--codex', `responses_api_metadata.codex_security_provider=${JSON.stringify(inputs.provider)}`);
  // Bind the option value and keep it explicitly relative so the CLI treats
  // leading '-' and '~' as literal repository filenames.
  for (const path of inputs.paths) args.push(`--path=./${path}`);
  const options: Array<[string, string | number | undefined]> = [
    ['--cyber-access-program', inputs.cyberAccessProgram],
    ['--diff', target.diffBase], ['--head', target.diffHead], ['--max-cost', inputs.maxCost],
    ['--max-time', inputs.maxTimeHours === undefined ? undefined : inputs.maxTimeHours * 60],
  ];
  for (const [name, value] of options) if (value !== undefined) args.push(name, String(value));
  if (inputs.failOnSeverity !== 'none') args.push('--fail-on-severity', inputs.failOnSeverity);
  if (inputs.verbose) args.push('--verbose');
  if (inputs.dryRun) args.push('--dry-run');
  return args;
}