Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

13.6 KB
Raw Blame
import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, describe, expect, it } from 'vitest'
import { GUARD_REASONS, fileRefusal, shellRefusal, type GuardFacts } from './shellGuard.js'

/** No filesystem and no live processes: each rule is read from the words alone. */
const facts = (over: Partial<GuardFacts> = {}): GuardFacts => ({
  cwd: '/work/repo', platform: 'darwin',
  privateFolder: () => false, linkedWorktree: () => false, liveCwds: () => [],
  ...over,
})

const refused = (command: string, over: Partial<GuardFacts> = {}) => shellRefusal(command, facts(over))

describe('shell guard: kill by name', () => {
  it.each([
    'pkill -f node',
    'killall Finder',
    '/usr/bin/pkill harness',
    'kill $(pgrep -f vitest)',
    'kill -9 `pidof node`',
    'pgrep -f "next dev" | xargs kill',
    'ps aux | grep node | awk \'{print $2}\' | xargs kill -9',
    'lsof -ti :3000 | xargs kill',
    'for p in $(pgrep node); do kill $p; done',
    'fuser -k 3000/tcp',
    'bash -lc "pkill -f tsx"',
    'sh -c \'killall node\'',
    'true && env FOO=1 pkill node',
    'taskkill /IM node.exe /F',
    'Stop-Process -Name node',
    'Get-Process node | Stop-Process',
  ])('refuses %s', (command) => {
    expect(refused(command)).toBe(GUARD_REASONS.killByName)
  })

  it.each([
    'kill 12345',
    'kill -TERM 4242',
    'kill "$SERVER_PID"',
    'kill $(cat "$T/server.pid")',
    'ps -p 4242 >/dev/null && kill 4242',
    'taskkill /PID 4242 /F',
    'Stop-Process -Id 4242',
    'pgrep -fl vitest',
    'ps aux | grep node',
    'git log --grep=pkill',
    'echo "never use pkill"',
    'grep -rn killall src',
  ])('lets %s through', (command) => {
    expect(refused(command)).toBeNull()
  })
})

describe('shell guard: kill -1, every process the account can reach', () => {
  it.each([
    'kill -1',
    'kill -4242',
    'kill -- -4242',
    'kill -TERM -4242',
    'kill -s TERM -4242',
    'kill -n 9 -4242',
    'kill -- 0',
    'kill -9 -1',
    'kill -- -1',
    'kill -KILL -1',
    'kill -s TERM -1',
    '/bin/kill -1 -1',
    'kill 4242 -1',
    '/bin/kill -9 -1 ; true',
  ])('refuses %s', (command) => {
    expect(refused(command)).toBe(GUARD_REASONS.killAll)
  })

  it.each([
    'kill -1 4242',
    'kill -l',
  ])('lets %s through', (command) => {
    expect(refused(command)).toBeNull()
  })
})

describe('shell guard: sudo and system-wide installs', () => {
  it.each([
    'sudo rm -rf /opt/thing',
    'sudo -u other whoami',
    'doas pkg_add vim',
    'su -c "make install"',
    'npm install -g typescript',
    'npm i --global pnpm',
    'npm install --location=global tsx',
    'pnpm add -g turbo',
    'yarn global add serve',
    'bun add -g vercel',
    'brew install jq',
    'brew upgrade',
    'apt-get install -y ripgrep',
    'apt install jq',
    'dnf install gcc',
    'port install wget',
    'pacman -S ripgrep',
    'pacman -Syu',
    'pacman -Rns ripgrep',
    'pip install --break-system-packages requests',
    'python3 -m pip install --break-system-packages rich',
    'installer -pkg Thing.pkg -target /',
    'softwareupdate -i -a',
    'winget install Git.Git',
    'choco install nodejs',
    'msiexec /i thing.msi',
    'osascript -e \'do shell script "id" with administrator privileges\'',
    'Start-Process pwsh -Verb RunAs',
    'cd cli && sudo npm ci',
  ])('refuses %s', (command) => {
    expect(refused(command)).toBe(GUARD_REASONS.systemWide)
  })

  it.each([
    'npm ci',
    'npm install --save-dev vitest',
    'npm i lodash',
    'npx tsc --noEmit',
    'pnpm install',
    'brew list',
    'brew --prefix',
    'pacman -Qq',
    'pacman --query ripgrep',
    'pip install -r requirements.txt',
    'python3 -m venv .venv && .venv/bin/pip install rich',
    'cargo install ripgrep --root "$T/tools"',
    'git commit -m "no sudo here"',
    'grep -rn sudo docs',
  ])('lets %s through', (command) => {
    expect(refused(command)).toBeNull()
  })
})

describe('shell guard: heredocs', () => {
  it.each([
    "cat > notes.md <<'EOF'\nnever run sudo or pkill here\nEOF",
    'gh pr comment 1 --body-file - <<EOF\nuse sudo apt install x, then killall Finder\nEOF',
  ])('reads a heredoc body as text, not commands: %j', (command) => {
    expect(refused(command)).toBeNull()
  })

  it('still reads the command a heredoc feeds', () => {
    expect(refused('cat <<EOF | sudo tee /etc/x\nhi\nEOF')).toBe(GUARD_REASONS.systemWide)
    expect(refused('cat <<-EOF > /tmp/x\n\tbody\n\tEOF')).toBe(GUARD_REASONS.fixedTmp)
  })
})

describe('shell guard: temporary paths in simple variables', () => {
  it.each([
    'OUT=/tmp; echo hi > "$OUT/shared.txt"',
    'OUT=/tmp; cat ${OUT}/shared.txt',
    'OUT=/private; OUT="$OUT/tmp"; touch "$OUT/shared.txt"',
    'OUT=/tmp; NEXT=$OUT; curl -o "$NEXT/shared.txt" https://example.com',
    'export OUT=/tmp; tee "$OUT/shared.txt"',
    "bash -c 'OUT=/tmp; echo hi > \"$OUT/shared.txt\"'",
  ])('refuses %s', command => {
    expect(refused(command)).toBe(GUARD_REASONS.fixedTmp)
  })

  it.each([
    'OUT=/work; echo hi > "$OUT/shared.txt"',
    'OUT=/tmp; OUT=/work; echo hi > "$OUT/shared.txt"',
    "OUT=/tmp; echo '$OUT/shared.txt'",
    "OUT=/tmp; echo \\$OUT/shared.txt",
    'OUT=$(mktemp -d "${TMPDIR:-/tmp}/out.XXXXXX"); echo hi > "$OUT/shared.txt"',
  ])('allows %s', command => {
    expect(refused(command)).toBeNull()
  })
})

describe('shell guard: fixed names in /tmp', () => {
  it.each([
    'echo hi > /tmp/out.txt',
    'cat build.log >>/tmp/build.log',
    'curl -o /tmp/thing.tgz https://example.com/thing.tgz',
    'curl --output=/tmp/thing.tgz https://example.com',
    'node script.js | tee /private/tmp/log.txt',
    'mkdir -p /tmp/work && cp a /tmp/work/',
    'touch /var/tmp/marker',
    'harness super-tab instructions > /tmp/instr_wren.txt 2>&1',
    'cd /tmp && echo x > y',
    'bash -c "echo x > /tmp/y"',
    'export OUT=/tmp/out.json',
    'sh /tmp/planted.sh',
  ])('refuses %s', (command) => {
    expect(refused(command)).toBe(GUARD_REASONS.fixedTmp)
  })

  it.each([
    'T=$(mktemp -d "${TMPDIR:-/tmp}/wren.XXXXXX")',
    'mktemp -d /tmp/build.XXXXXX',
    'mktemp -p /tmp',
    'echo x > "$TMPDIR/wren.abc/out.txt"',
    'ls /tmp',
    'curl https://example.com/tmp/file',
    'git log -- src/tmp/x.ts',
    'echo "/tmpfoo"',
  ])('lets %s through', (command) => {
    expect(refused(command)).toBeNull()
  })

  it('lets through a path inside a folder only this account can open (made by mktemp -d)', () => {
    const own = (path: string) => path === '/tmp/wren.AbC123'
    expect(refused('echo x > /tmp/wren.AbC123/out.txt', { privateFolder: own })).toBeNull()
    expect(refused('echo x > /tmp/other/out.txt', { privateFolder: own })).toBe(GUARD_REASONS.fixedTmp)
  })

  it('takes Claude Code\'s own folder (mode 700, this account\'s) as private, and another account\'s as not', () => {
    const own = (path: string) => path === '/private/tmp/claude-600' || path === '/tmp/claude-600'
    expect(refused('cat /private/tmp/claude-600/project/tasks/abc.output', { privateFolder: own })).toBeNull()
    expect(refused('tail -5 /tmp/claude-600/x/y.output', { privateFolder: own })).toBeNull()
    expect(refused('cat /private/tmp/claude-501/x/scratchpad/notes.md', { privateFolder: own })).toBe(GUARD_REASONS.fixedTmp)
  })

  it('checks relative redirections against the command cwd', () => {
    expect(refused('echo hi > shared.txt', { cwd: '/tmp' })).toBe(GUARD_REASONS.fixedTmp)
    expect(refused('echo hi > shared.txt')).toBeNull()
    expect(refused('echo hi', { cwd: '/tmp' })).toBeNull()
  })

  it('does not treat an escape from a private temporary folder as private', () => {
    const own = (path: string) => path === '/tmp/private'
    expect(refused('echo hi > /tmp/private/../shared.txt', { privateFolder: own })).toBe(GUARD_REASONS.fixedTmp)
    expect(refused('echo hi > ../shared.txt', { cwd: '/tmp/private', privateFolder: own })).toBe(GUARD_REASONS.fixedTmp)
    expect(refused('echo hi > inside.txt', { cwd: '/tmp/private', privateFolder: own })).toBeNull()
  })

  it('checks relative file-tool paths before allowing a fixed temporary name', () => {
    expect(fileRefusal('shared.txt', facts({ cwd: '/tmp' }))).toBe(GUARD_REASONS.fixedTmp)
    expect(fileRefusal('../shared.txt', facts({ cwd: '/tmp/private', privateFolder: path => path === '/tmp/private' })))
      .toBe(GUARD_REASONS.fixedTmp)
    expect(fileRefusal('notes.md', facts())).toBeNull()
  })
})

describe('shell guard: removing a worktree a live process uses', () => {
  const worktree = '/work/trees/bold-pine'
  const linked = (path: string) => path === worktree

  it.each([
    `git worktree remove ${worktree}`,
    `git worktree remove --force ${worktree}`,
    `git -C /work/repo worktree remove -f ${worktree}`,
    `rm -rf ${worktree}`,
    `rm -r -f ${worktree}/`,
    'git worktree remove ../trees/bold-pine',
  ])('refuses %s while a process works in it', (command) => {
    const liveCwds = () => [{ pid: 4242, cwd: `${worktree}/cli` }]
    expect(refused(command, { linkedWorktree: linked, liveCwds, cwd: '/work/repo' })).toBe(GUARD_REASONS.liveWorktree(worktree, 4242))
  })

  it('lets a worktree nobody works in go', () => {
    const liveCwds = () => [{ pid: 1, cwd: '/' }, { pid: 7, cwd: '/work/trees/bold-pine-2' }]
    expect(refused(`git worktree remove ${worktree}`, { linkedWorktree: linked, liveCwds })).toBeNull()
    expect(refused(`rm -rf ${worktree}`, { linkedWorktree: linked, liveCwds })).toBeNull()
  })

  it('does not check folders that are not worktrees', () => {
    const liveCwds = () => [{ pid: 4242, cwd: '/work/repo/node_modules/x' }]
    expect(refused('rm -rf node_modules', { liveCwds, cwd: '/work/repo' })).toBeNull()
  })

  // Rowan's security review (11-06): naming the worktree's parent, a glob over the worktrees or a ~/ path removed it too.
  describe('through a folder that holds it', () => {
    const live = () => [{ pid: 4242, cwd: `${worktree}/cli` }]
    const holding = { linkedWorktree: linked, liveCwds: live, home: '/work', cwd: '/work/repo',
      entries: (path: string) => (path === '/work/trees' ? ['bold-pine', 'other'] : path === '/work' ? ['trees', 'repo'] : []) }

    it.each([
      ['rm -rf /work/trees', '/work/trees'],
      ['rm -rf ../trees', '/work/trees'],
      ['rm -rf ~/trees', '/work/trees'],
      ['rm -rf /work/trees/*', worktree],
      ['rm -rf /work/trees/bold-*', worktree],
      ['cd /work && rm -rf tr*', '/work/trees'],
    ])('refuses %s', (command, target) => {
      expect(refused(command, holding)).toBe(GUARD_REASONS.liveWorktree(target, 4242))
    })

    it('lets the folder go when nobody works in the worktree it holds', () => {
      expect(refused('rm -rf /work/trees', { ...holding, liveCwds: () => [{ pid: 7, cwd: '/work/repo' }] })).toBeNull()
    })

    it('reads no live processes for a folder holding no worktree', () => {
      const liveCwds = () => { throw new Error('read live processes') }
      expect(refused('rm -rf build dist/*', { ...holding, liveCwds })).toBeNull()
    })
  })

  it('refuses when it cannot tell which processes are live', () => {
    expect(refused(`git worktree remove ${worktree}`, { linkedWorktree: linked, liveCwds: () => null }))
      .toBe(GUARD_REASONS.worktreeUnknown(worktree))
  })
})

// The Mac test of #3506: macOS's mktemp, given no template and no folder, makes its file in the account's own temporary folder
// (/var/folders/…/T) whatever TMPDIR says. Every agent and app of the account shares that folder, so it is never an agent's
// allowed folder, and an agent's owner's settings stop it there with a question it waits on (Authorder, 11-07).
describe('shell guard: mktemp on a Mac', () => {
  it.each([
    'mktemp',
    'mktemp -d',
    'T=$(mktemp -d)',
    'mktemp -q -d',
    'mktemp -t build',
    'mktemp -dt build',
    'mktemp -d -t build -u',
  ])('refuses %s, saying how to make it in the agent\'s own folder', (command) => {
    expect(refused(command)).toBe(GUARD_REASONS.macMktemp)
  })

  it.each([
    'T=$(mktemp -d "${TMPDIR:-/tmp}/wren.XXXXXX")',
    'mktemp "$TMPDIR/out.XXXXXX"',
    'mktemp -d -p "$TMPDIR"',
    'mktemp -dp "$TMPDIR"',
    'mktemp -d -t build -p "$TMPDIR"',
    'mktemp -d --tmpdir',
    'mktemp --tmpdir="$TMPDIR"',
    'mktemp -d work.XXXXXX',
  ])('allows %s, which TMPDIR or its folder decides', (command) => {
    expect(refused(command)).toBeNull()
  })

  it('leaves Linux alone, whose mktemp follows TMPDIR', () => {
    expect(refused('mktemp -d', { platform: 'linux' })).toBeNull()
    expect(refused('T=$(mktemp)', { platform: 'linux' })).toBeNull()
  })
})

describe('shell guard: ordinary work', () => {
  it.each([
    'git status --short',
    'cd cli && npx vitest run src/superTabs/shellGuard.spec.ts',
    'harness super-tab --tab abc mine',
    'gh pr view 12 --json title',
    'make check-ui-style',
    'flutter test test/super_tab_discovery_test.dart',
    'git worktree list',
    'rm -f build/out.js',
    '',
  ])('lets %s through', (command) => {
    expect(refused(command)).toBeNull()
  })
})

describe('shell guard: real folders', () => {
  const made: string[] = []
  afterEach(() => { for (const dir of made.splice(0)) rmSync(dir, { recursive: true, force: true }) })

  it('reads a mktemp -d folder as private and a shared one as not', async () => {
    const { privateFolderOf, linkedWorktreeOf } = await import('./shellGuard.js')
    const own = mkdtempSync(join(tmpdir(), 'guard-'))
    made.push(own)
    expect(privateFolderOf(own)).toBe(true)
    chmodSync(own, 0o755)
    expect(privateFolderOf(own)).toBe(false)
    const tree = join(own, 'tree')
    mkdirSync(tree)
    expect(linkedWorktreeOf(tree)).toBe(false)
    writeFileSync(join(tree, '.git'), 'gitdir: /work/repo/.git/worktrees/tree\n')
    expect(linkedWorktreeOf(tree)).toBe(true)
  })
})