Skip to content

Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base

17.2 KB
Raw Blame
import path from 'node:path'

/** How a command's bare operands are interpreted, which decides what gets path-checked. */
type OperandKind = 'paths' | 'literal-then-paths' | 'literals'

interface CommandPolicy {
  /** Options accepted as-is, without a value. */
  options?: readonly string[]
  /** Options taking a value, either attached (`-n5`, `--include=*.md`) or as the next token. */
  valueOptions?: readonly string[]
  operands?: OperandKind
  /** Accepts the legacy numeric form, as in `head -20`. */
  numericOption?: boolean
  /** Options are whole words behind a single dash (`find -maxdepth`), never clusters. */
  singleDashWords?: boolean
}

const GREP_OPTIONS = [
  '-r',
  '-R',
  '-l',
  '-L',
  '-n',
  '-i',
  '-I',
  '-w',
  '-x',
  '-c',
  '-v',
  '-o',
  '-h',
  '-H',
  '-s',
  '-a',
  '-q',
  '-E',
  '-F',
  '-G',
  '-P',
  '--recursive',
  '--dereference-recursive',
  '--files-with-matches',
  '--files-without-match',
  '--line-number',
  '--ignore-case',
  '--word-regexp',
  '--line-regexp',
  '--count',
  '--invert-match',
  '--only-matching',
  '--no-filename',
  '--with-filename',
  '--fixed-strings',
  '--basic-regexp',
  '--extended-regexp',
  '--perl-regexp',
  '--quiet',
  '--silent',
  '--no-messages',
  '--text',
  '--null-data',
] as const

const GREP_VALUE_OPTIONS = [
  '-m',
  '-A',
  '-B',
  '-C',
  '-e',
  '-d',
  '--max-count',
  '--after-context',
  '--before-context',
  '--context',
  '--regexp',
  '--include',
  '--exclude',
  '--exclude-dir',
  '--color',
  '--colour',
  '--devices',
  '--directories',
  '--binary-files',
] as const

/** Options carrying the search pattern, so the first operand is a path rather than a regex. */
const PATTERN_OPTIONS = new Set(['-e', '--regexp'])

/**
 * The sandbox command surface. Every entry must be free of write and exec
 * primitives: anything able to spawn a process (`awk`, `sed -e`, `xargs`,
 * `find -exec`) or create a file (`tee`, `sort -o`) escapes the policy, since
 * the command name is all a name-only allowlist can pin down.
 */
const COMMAND_POLICIES: Record<string, CommandPolicy> = {
  // File discovery
  find: {
    options: ['-empty', '-not', '-o', '-a', '-and', '-or', '-print', '-print0', '-follow', '-depth', '-prune', '-readable', '-nowarn'],
    valueOptions: ['-name', '-iname', '-path', '-ipath', '-regex', '-iregex', '-type', '-maxdepth', '-mindepth', '-size', '-links'],
    singleDashWords: true,
  },
  ls: {
    options: ['-l', '-a', '-A', '-h', '-R', '-t', '-r', '-S', '-1', '-d', '-F', '-i', '-p', '-X', '-U', '-n', '-G', '-o', '-g', '-s', '-c', '-u', '--all', '--almost-all', '--human-readable', '--recursive', '--reverse', '--size', '--classify', '--directory', '--inode', '--numeric-uid-gid'],
    valueOptions: ['--sort', '--time-style', '--color', '--format', '--block-size'],
  },
  tree: {
    options: ['-d', '-a', '-f', '-F', '-i', '-l', '-x', '-r', '-t', '--noreport', '--dirsfirst'],
    valueOptions: ['-L', '-I', '-P', '--filelimit'],
  },
  // Content search
  grep: { options: GREP_OPTIONS, valueOptions: GREP_VALUE_OPTIONS, operands: 'literal-then-paths' },
  egrep: { options: GREP_OPTIONS, valueOptions: GREP_VALUE_OPTIONS, operands: 'literal-then-paths' },
  fgrep: { options: GREP_OPTIONS, valueOptions: GREP_VALUE_OPTIONS, operands: 'literal-then-paths' },
  // File reading
  cat: { options: ['-n', '-b', '-s', '-E', '-T', '-A', '-v', '-e', '-t', '--number', '--number-nonblank', '--squeeze-blank', '--show-ends', '--show-tabs', '--show-all'] },
  head: { options: ['-q', '-v', '-z', '--quiet', '--verbose'], valueOptions: ['-n', '-c', '--lines', '--bytes'], numericOption: true },
  tail: { options: ['-q', '-v', '-z', '--quiet', '--verbose'], valueOptions: ['-n', '-c', '--lines', '--bytes'], numericOption: true },
  // Text processing (output filtering only)
  wc: { options: ['-l', '-w', '-c', '-m', '-L', '--lines', '--words', '--bytes', '--chars', '--max-line-length'] },
  sort: {
    options: ['-n', '-r', '-u', '-f', '-b', '-h', '-V', '-g', '-M', '-s', '-i', '-d', '-c', '-z', '--numeric-sort', '--reverse', '--unique', '--ignore-case', '--human-numeric-sort', '--version-sort', '--general-numeric-sort', '--month-sort', '--stable', '--check', '--dictionary-order', '--ignore-leading-blanks'],
    valueOptions: ['-k', '-t', '--key', '--field-separator'],
  },
  uniq: {
    options: ['-c', '-d', '-u', '-i', '-D', '-z', '--count', '--repeated', '--unique', '--ignore-case', '--all-repeated'],
    valueOptions: ['-w', '-s', '-f', '--check-chars', '--skip-chars', '--skip-fields'],
  },
  cut: {
    options: ['-s', '-n', '-z', '--only-delimited', '--complement'],
    valueOptions: ['-d', '-f', '-c', '-b', '--delimiter', '--fields', '--characters', '--bytes', '--output-delimiter'],
  },
  tr: { options: ['-d', '-s', '-c', '-C', '-t', '--delete', '--squeeze-repeats', '--complement', '--truncate-set1'], operands: 'literals' },
  column: { options: ['-t', '-x', '--table'], valueOptions: ['-s', '-c', '-o', '--separator', '--output-width', '--output-separator'] },
  // Utilities
  echo: { options: ['-n', '-e', '-E'], operands: 'literals' },
  printf: { operands: 'literals' },
  basename: { options: ['-a', '-z', '--multiple', '--zero'], valueOptions: ['-s', '--suffix'], operands: 'literals' },
  dirname: { options: ['-z', '--zero'], operands: 'literals' },
  realpath: {
    options: ['-e', '-m', '-s', '-z', '-q', '--canonicalize-existing', '--canonicalize-missing', '--no-symlinks', '--quiet', '--zero'],
    valueOptions: ['--relative-to', '--relative-base'],
  },
  file: { options: ['-b', '-i', '-L', '-z', '-h', '-k', '--brief', '--mime', '--mime-type', '--dereference'] },
  stat: { options: ['-L', '-t', '-f', '--dereference', '--terse', '--file-system'], valueOptions: ['-c', '--format', '--printf'] },
  du: {
    options: ['-h', '-s', '-a', '-c', '-k', '-m', '-b', '-S', '-x', '-L', '--human-readable', '--summarize', '--all', '--total', '--bytes', '--separate-dirs', '--si'],
    valueOptions: ['-d', '-B', '--max-depth', '--block-size', '--threshold'],
  },
  diff: {
    options: ['-u', '-r', '-q', '-w', '-i', '-B', '-b', '-N', '-y', '-c', '-s', '-a', '-E', '-Z', '--unified', '--recursive', '--brief', '--ignore-all-space', '--ignore-case', '--ignore-blank-lines', '--ignore-space-change', '--new-file', '--side-by-side', '--report-identical-files', '--text'],
    valueOptions: ['-U', '-C', '-W', '--width'],
  },
  comm: { options: ['-1', '-2', '-3', '-i', '-z', '--total', '--check-order', '--nocheck-order'], valueOptions: ['--output-delimiter'] },
  // Checksums
  md5sum: { options: ['-b', '-t', '-z', '--binary', '--text', '--zero'] },
  sha256sum: { options: ['-b', '-t', '-z', '--binary', '--text', '--zero'] },
}

export const ALLOWED_BASH_COMMANDS: ReadonlySet<string> = new Set(Object.keys(COMMAND_POLICIES))

const MAX_STAGES = 8
const MAX_TOKENS_PER_STAGE = 64

export function isPathWithinDirectory(filePath: string, directory: string): boolean {
  const resolvedPath = path.resolve(filePath)
  const resolvedDir = path.resolve(directory)
  return resolvedPath.startsWith(`${resolvedDir}${path.sep}`) || resolvedPath === resolvedDir
}

export function pathMatchesGlob(filePath: string, glob: string, baseDir: string): boolean {
  const resolvedPath = path.resolve(filePath)
  const resolvedBase = path.resolve(baseDir)

  if (!isPathWithinDirectory(resolvedPath, resolvedBase)) {
    return false
  }

  const relativePath = path.relative(resolvedBase, resolvedPath).replace(/\\/g, '/')

  try {
    const globRegex = glob
      .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
      .replace(/\*\*/g, '<<<GLOBSTAR>>>')
      .replace(/\*/g, '[^/]*')
      .replace(/<<<GLOBSTAR>>>/g, '.*')
      .replace(/\//g, '\\/')

    const regex = new RegExp(`^${globRegex}`)
    if (regex.test(relativePath)) {
      return true
    }

    if (glob.endsWith('/**') && !relativePath.endsWith('/')) {
      return regex.test(`${relativePath}/`)
    }

    return false
  } catch {
    return false
  }
}

export interface ShellValidationOptions {
  /** Narrows the policy table to a subset of commands. */
  allowedCommands?: ReadonlySet<string>
  /** Path operands must resolve inside this directory. */
  allowedBaseDirectory?: string
}

export type ShellValidationResult =
  | { ok: true, command: string }
  | { ok: false, reason: string }

type StageResult =
  | { ok: true }
  | { ok: false, reason: string }

interface ParsedCommandLine {
  stages: string[][]
  separators: string[]
}

type ParseResult =
  | { ok: true, parsed: ParsedCommandLine }
  | { ok: false, reason: string }

/**
 * Splits a command line into stages of argv tokens, resolving quotes and
 * refusing every shell construct the sandbox has no use for. Nothing here
 * interprets the tokens, so `awk 'BEGIN{system("id")}'` parses as a single
 * `awk` argument rather than as a command able to spawn `id`.
 */
function parseCommandLine(command: string): ParseResult {
  const stages: string[][] = []
  const separators: string[] = []
  let argv: string[] = []
  let token: string | null = null

  const endToken = () => {
    if (token !== null) {
      argv.push(token)
      token = null
    }
  }

  const endStage = (separator: string): ParseResult | null => {
    endToken()
    if (argv.length === 0) {
      return { ok: false, reason: `Empty command segment before "${separator}"` }
    }
    stages.push(argv)
    argv = []
    separators.push(separator)
    return null
  }

  for (let i = 0; i < command.length; i++) {
    const char = command[i]!

    if (char === '\'') {
      const end = command.indexOf('\'', i + 1)
      if (end === -1) {
        return { ok: false, reason: 'Unbalanced single quote' }
      }
      token = (token ?? '') + command.slice(i + 1, end)
      i = end
      continue
    }

    if (char === '"') {
      let value = ''
      let j = i + 1
      let closed = false
      while (j < command.length) {
        const inner = command[j]!
        if (inner === '\\' && ['"', '\\', '$', '`'].includes(command[j + 1] ?? '')) {
          value += command[j + 1]!
          j += 2
          continue
        }
        if (inner === '"') {
          closed = true
          break
        }
        if (inner === '`' || (inner === '$' && command[j + 1] === '(')) {
          return { ok: false, reason: 'Command substitution is not allowed' }
        }
        value += inner
        j++
      }
      if (!closed) {
        return { ok: false, reason: 'Unbalanced double quote' }
      }
      token = (token ?? '') + value
      i = j
      continue
    }

    if (char === '\\') {
      const next = command[i + 1]
      if (next === undefined) {
        return { ok: false, reason: 'Trailing backslash' }
      }
      token = (token ?? '') + next
      i++
      continue
    }

    if (char === ' ' || char === '\t') {
      endToken()
      continue
    }

    if (char === '\n' || char === '\r') {
      return { ok: false, reason: 'Newlines are not allowed' }
    }

    if (char === '`' || (char === '$' && command[i + 1] === '(')) {
      return { ok: false, reason: 'Command substitution is not allowed' }
    }

    if (char === '>' || char === '<') {
      return { ok: false, reason: 'Redirection is not allowed' }
    }

    if (char === '(' || char === ')' || char === '{' || char === '}') {
      return { ok: false, reason: 'Subshells and brace groups are not allowed' }
    }

    if (char === '|') {
      const isOr = command[i + 1] === '|'
      const error = endStage(isOr ? '||' : '|')
      if (error) return error
      if (isOr) i++
      continue
    }

    if (char === '&') {
      if (command[i + 1] !== '&') {
        return { ok: false, reason: 'Background execution is not allowed' }
      }
      const error = endStage('&&')
      if (error) return error
      i++
      continue
    }

    if (char === ';') {
      const error = endStage(';')
      if (error) return error
      continue
    }

    token = (token ?? '') + char
  }

  endToken()

  if (argv.length > 0) {
    stages.push(argv)
  } else if (separators.length > 0) {
    // A trailing `;` just terminates the last command; a dangling `|` or `&&` is
    // a syntax error, and silently dropping it would rewrite the command.
    const trailing = separators[separators.length - 1]!
    if (trailing !== ';') {
      return { ok: false, reason: `Empty command segment after "${trailing}"` }
    }
    separators.pop()
  }

  if (stages.length === 0) {
    return { ok: false, reason: 'Empty command' }
  }
  if (stages.length > MAX_STAGES) {
    return { ok: false, reason: `Too many command segments (max ${MAX_STAGES})` }
  }
  if (stages.some(stage => stage.length > MAX_TOKENS_PER_STAGE)) {
    return { ok: false, reason: `Too many arguments (max ${MAX_TOKENS_PER_STAGE})` }
  }

  return { ok: true, parsed: { stages, separators } }
}

type OptionResult =
  | { ok: true, consumesNext: boolean, name: string }
  | { ok: false, reason: string }

/** Resolves a whole-word option (`--include=*.md`, `-maxdepth 2`) against the policy. */
function validateWordOption(
  arg: string,
  command: string,
  options: ReadonlySet<string>,
  valueOptions: ReadonlySet<string>,
): OptionResult {
  const equals = arg.indexOf('=')
  const name = equals === -1 ? arg : arg.slice(0, equals)

  if (valueOptions.has(name)) {
    return { ok: true, consumesNext: equals === -1, name }
  }
  if (options.has(name)) {
    if (equals !== -1) {
      return { ok: false, reason: `Option does not take a value: ${name}` }
    }
    return { ok: true, consumesNext: false, name }
  }
  return { ok: false, reason: `Option not allowed for ${command}: ${name}` }
}

/** Resolves a short option cluster such as `-rl`, `-n5` or `-A`. */
function validateShortCluster(
  arg: string,
  command: string,
  options: ReadonlySet<string>,
  valueOptions: ReadonlySet<string>,
): OptionResult {
  const chars = arg.slice(1)

  for (let i = 0; i < chars.length; i++) {
    const name = `-${chars[i]}`

    if (valueOptions.has(name)) {
      // Whatever remains in the cluster is this option's value, as in `-n5`.
      return { ok: true, consumesNext: i === chars.length - 1, name }
    }
    if (!options.has(name)) {
      return { ok: false, reason: `Option not allowed for ${command}: ${name}` }
    }
  }

  return { ok: true, consumesNext: false, name: arg }
}

function validateStage(argv: string[], options?: ShellValidationOptions): StageResult {
  const command = argv[0]!

  if (command.includes('=')) {
    return { ok: false, reason: `Environment assignments are not allowed: ${command}` }
  }

  const policy = COMMAND_POLICIES[command]
  if (!policy || (options?.allowedCommands && !options.allowedCommands.has(command))) {
    return { ok: false, reason: `Command not allowed: ${command}` }
  }

  const allowedOptions = new Set(policy.options ?? [])
  const allowedValueOptions = new Set(policy.valueOptions ?? [])
  const rest = argv.slice(1)
  const operands: string[] = []
  let endOfOptions = false
  let hasPatternOption = false

  for (let i = 0; i < rest.length; i++) {
    const arg = rest[i]!

    if (endOfOptions || arg === '-' || !arg.startsWith('-')) {
      operands.push(arg)
      continue
    }

    if (arg === '--') {
      endOfOptions = true
      continue
    }

    if (policy.numericOption && /^-\d+$/.test(arg)) {
      continue
    }

    const result = arg.startsWith('--') || policy.singleDashWords
      ? validateWordOption(arg, command, allowedOptions, allowedValueOptions)
      : validateShortCluster(arg, command, allowedOptions, allowedValueOptions)

    if (!result.ok) {
      return result
    }
    if (PATTERN_OPTIONS.has(result.name)) {
      hasPatternOption = true
    }
    if (result.consumesNext && ++i >= rest.length) {
      return { ok: false, reason: `Option requires a value: ${result.name}` }
    }
  }

  const operandKind = policy.operands ?? 'paths'
  if (operandKind === 'literals' || !options?.allowedBaseDirectory) {
    return { ok: true }
  }

  // `grep pattern path...` — the leading operand is a regex, not a file.
  const pathOperands = operandKind === 'literal-then-paths' && !hasPatternOption
    ? operands.slice(1)
    : operands

  for (const operand of pathOperands) {
    const resolved = path.resolve(options.allowedBaseDirectory, operand)
    if (!isPathWithinDirectory(resolved, options.allowedBaseDirectory)) {
      return { ok: false, reason: `Path outside sandbox is not allowed: ${operand}` }
    }
  }

  return { ok: true }
}

/** Single-quotes a token so the shell treats every character as literal text. */
function quoteToken(token: string): string {
  return `'${token.replace(/'/g, '\'\\\'\'')}'`
}

/**
 * Parses and authorises a command line, returning an equivalent line that is
 * safe to hand to `bash -c`.
 *
 * The returned `command` is rebuilt from the parsed tokens with every argument
 * single-quoted, so it carries no metacharacters, no expansions and no nested
 * commands. Callers must execute that string rather than their own input.
 */
export function validateShellCommand(
  command: string,
  options?: ShellValidationOptions,
): ShellValidationResult {
  const parsed = parseCommandLine(command)
  if (!parsed.ok) {
    return { ok: false, reason: parsed.reason }
  }

  const { stages, separators } = parsed.parsed

  for (const stage of stages) {
    const result = validateStage(stage, options)
    if (!result.ok) {
      return result
    }
  }

  const sanitized = stages
    .map(stage => stage.map(quoteToken).join(' '))
    .reduce((line, stage, index) => `${line} ${separators[index - 1]!} ${stage}`)

  return { ok: true, command: sanitized }
}