Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base
refactor(sandbox): parse shell commands into argv before execution
Hugo Richard1b20754e9b8f
diff --git a/README.md b/README.mdindex cfb4743..78d8b62 100644--- a/README.md+++ b/README.md@@ -53,7 +53,7 @@ Share any conversation with a single click. Generates a public read-only link wi### Shared Sandbox Pool-Sandboxes are pooled across users and conversations. When a chat starts, it connects to an already-running sandbox instead of creating a new one — startup in under 100ms. If none is available, a pre-built snapshot spins one up in 1–3s. Sandboxes are read-only with blocked dangerous commands, and automatically shared so multiple agents search the same up-to-date content without duplicating resources.+Sandboxes are pooled across users and conversations. When a chat starts, it connects to an already-running sandbox instead of creating a new one — startup in under 100ms. If none is available, a pre-built snapshot spins one up in 1–3s. Because a sandbox is shared, agents reach it through a parsed command policy that permits only read-only commands — nothing that can write a file or spawn a process — so multiple agents search the same up-to-date content without duplicating resources or affecting each other.## [Architecture](./docs/ARCHITECTURE.md)diff --git a/apps/app/server/api/sandbox/shell.post.ts b/apps/app/server/api/sandbox/shell.post.tsindex 85e5f23..3741212 100644--- a/apps/app/server/api/sandbox/shell.post.ts+++ b/apps/app/server/api/sandbox/shell.post.ts@@ -13,18 +13,21 @@ const bodySchema = z.object({)const MAX_OUTPUT = 50000+const SANDBOX_ROOT = '/vercel/sandbox'-function validateCommand(command: string): void {+/** Returns the re-quoted command to execute — never run the caller's own string. */+function sanitizeCommand(command: string): string {const validation = validateShellCommand(command, {- allowedBaseDirectory: '/vercel/sandbox',+ allowedBaseDirectory: SANDBOX_ROOT,})if (!validation.ok) {throw createError({statusCode: 400,message: validation.reason,- data: { why: 'The command failed security validation', fix: 'Use only allowed commands within /vercel/sandbox' },+ data: { why: 'The command failed security validation', fix: `Use only allowed commands within ${SANDBOX_ROOT}` },})}+ return validation.command}function truncateOutput(output: string): string {@@ -48,10 +51,7 @@ export default defineEventHandler(async (event) => {const body = await readValidatedBody(event, bodySchema.parse)const commands = body.commands || [body.command!]-- for (const cmd of commands) {- validateCommand(cmd)- }+ const executableCommands = commands.map(sanitizeCommand)const isBatch = commands.length > 1requestLog.set({ commandCount: commands.length, isBatch })@@ -62,12 +62,12 @@ export default defineEventHandler(async (event) => {const results: CommandResult[] = []- for (const command of commands) {+ for (const [index, command] of commands.entries()) {const execStart = Date.now()const result = await sandbox.runCommand({cmd: 'bash',- args: ['-c', command],- cwd: '/vercel/sandbox',+ args: ['-c', executableCommands[index]!],+ cwd: SANDBOX_ROOT,})results.push({diff --git a/apps/app/server/utils/bot/savoir.ts b/apps/app/server/utils/bot/savoir.tsindex b7a6f89..e97e031 100644--- a/apps/app/server/utils/bot/savoir.ts+++ b/apps/app/server/utils/bot/savoir.ts@@ -2,41 +2,31 @@ import { tool } from 'ai'import { z } from 'zod'import { db, schema } from '@nuxthub/db'import { createError } from 'evlog'-import type { GenerateResult, ReportUsageOptions } from '@savoir/sdk'+import { validateShellCommand, type GenerateResult, type ReportUsageOptions } from '@savoir/sdk'import { getOrCreateSandbox } from '../sandbox/manager'import { getAgentConfig, type AgentConfigData } from '../agent-config'-const BLOCKED_PATTERNS = [- /\brm\s+-rf?\b/i,- /\brmdir\b/i,- /\bmkdir\b/i,- /\btouch\b/i,- /\bchmod\b/i,- /\bchown\b/i,- /\bsudo\b/i,- /\bcurl\b/i,- /\bwget\b/i,- /\bnc\b/i,- /\bssh\b/i,- /\bgit\b/i,- />\s*\//,- /\bdd\b/i,- /\bkill\b/i,- /\bpkill\b/i,-]-const MAX_OUTPUT = 50000--function validateCommand(command: string): void {- for (const pattern of BLOCKED_PATTERNS) {- if (pattern.test(command)) {- throw createError({- message: 'Command blocked by security policy',- status: 403,- why: `Command contains blocked pattern: ${command.slice(0, 50)}`,- })- }+const SANDBOX_ROOT = '/vercel/sandbox'++/**+ * Returns the re-quoted command to execute — never run the agent's own string.+ * Bot adapters reach this with input derived from untrusted issue and message+ * bodies, so they share the single policy used by the HTTP shell endpoint.+ */+function sanitizeCommand(command: string): string {+ const validation = validateShellCommand(command, {+ allowedBaseDirectory: SANDBOX_ROOT,+ })+ if (!validation.ok) {+ throw createError({+ message: 'Command blocked by security policy',+ status: 403,+ why: validation.reason,+ fix: `Use only allowed read-only commands within ${SANDBOX_ROOT}`,+ })}+ return validation.command}function truncateOutput(output: string): string {@@ -73,15 +63,15 @@ Use standard Unix commands to explore and read files.`,yield { status: 'loading' as const }const start = Date.now()- validateCommand(command)+ const executableCommand = sanitizeCommand(command)const active = await getOrCreateSandbox(sessionId);({ sessionId } = active)const result = await active.sandbox.runCommand({cmd: 'bash',- args: ['-c', command],- cwd: '/vercel/sandbox',+ args: ['-c', executableCommand],+ cwd: SANDBOX_ROOT,})const stdout = truncateOutput(await result.stdout())@@ -117,17 +107,17 @@ Maximum 10 commands per batch.`,yield { status: 'loading' as const }const start = Date.now()- for (const cmd of commands) validateCommand(cmd)+ const executableCommands = commands.map(sanitizeCommand)const active = await getOrCreateSandbox(sessionId);({ sessionId } = active)const results = []- for (const command of commands) {+ for (const [index, command] of commands.entries()) {const result = await active.sandbox.runCommand({cmd: 'bash',- args: ['-c', command],- cwd: '/vercel/sandbox',+ args: ['-c', executableCommands[index]!],+ cwd: SANDBOX_ROOT,})results.push({diff --git a/apps/app/server/utils/sandbox/git.ts b/apps/app/server/utils/sandbox/git.tsindex 22ac1ca..89d58ac 100644--- a/apps/app/server/utils/sandbox/git.ts+++ b/apps/app/server/utils/sandbox/git.ts@@ -88,11 +88,17 @@ export async function commit(sandbox: Sandbox, message: string): Promise<void> {}}-/** Pushes branch to remote repository with upstream tracking */+/**+ * Pushes branch to remote repository.+ *+ * The URL carries an access token, so the push must not set upstream tracking:+ * `--set-upstream` would record the tokenised URL in `.git/config`, where it+ * outlives the push and is readable by anything with access to the filesystem.+ */export async function push(sandbox: Sandbox, repoUrl: string, branch: string): Promise<void> {const result = await sandbox.runCommand({cmd: 'git',- args: ['push', '--set-upstream', repoUrl, branch],+ args: ['push', repoUrl, `${branch}:${branch}`],cwd: '/vercel/sandbox',})@@ -105,6 +111,30 @@ export async function push(sandbox: Sandbox, repoUrl: string, branch: string): P}}+/**+ * Removes the git metadata directory before a snapshot is taken.+ *+ * Snapshots are restored into sandboxes that every user's agent shares and can+ * read, so `.git` must not travel with them: it holds the clone and push+ * credentials as well as the full history, none of which the agent needs to+ * search documentation.+ */+export async function stripGitMetadata(sandbox: Sandbox): Promise<void> {+ const result = await sandbox.runCommand({+ cmd: 'rm',+ args: ['-rf', '/vercel/sandbox/.git'],+ cwd: '/vercel/sandbox',+ })++ if (result.exitCode !== 0) {+ throw createError({+ message: 'Failed to remove git metadata before snapshot',+ why: await result.stderr(),+ fix: 'Snapshots must not ship .git, which carries repository credentials',+ })+ }+}+/** Generates formatted commit message from sync results with source list */export function generateCommitMessage(results: SyncSourceResult[]): string {const successfulSources = results.filter(r => r.success)diff --git a/apps/app/server/utils/sandbox/manager.ts b/apps/app/server/utils/sandbox/manager.tsindex 44e249a..933b6b1 100644--- a/apps/app/server/utils/sandbox/manager.ts+++ b/apps/app/server/utils/sandbox/manager.ts@@ -4,6 +4,7 @@ import type { ActiveSandbox, SandboxManagerConfig, SnapshotMetadata } from './tyimport { getCurrentSnapshot, setCurrentSnapshot } from './snapshot'import { deleteSandboxSession, generateSessionId, getSandboxSession, setSandboxSession, touchSandboxSession } from './session'import { getSnapshotRepoConfig } from './snapshot-config'+import { stripGitMetadata } from './git'const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000const SANDBOX_TIMEOUT_MS = 5 * 60 * 1000@@ -76,6 +77,8 @@ export async function createSnapshotFromRepo(repoUrl: string, branch: string = 'log.info('sandbox', `Sandbox created: ${sandbox.sandboxId}, taking snapshot...`)+ await stripGitMetadata(sandbox)+const snapshot = await sandbox.snapshot()log.info('sandbox', `Snapshot created: ${snapshot.snapshotId}`)diff --git a/apps/app/server/workflows/create-snapshot/steps/create-and-snapshot.ts b/apps/app/server/workflows/create-snapshot/steps/create-and-snapshot.tsindex 90080a1..418bdb4 100644--- a/apps/app/server/workflows/create-snapshot/steps/create-and-snapshot.ts+++ b/apps/app/server/workflows/create-snapshot/steps/create-and-snapshot.ts@@ -8,6 +8,7 @@ import { getStepMetadata } from 'workflow'import { log } from 'evlog'import type { SnapshotConfig } from '../types'import { createSandbox } from '../../../utils/sandbox/context'+import { stripGitMetadata } from '../../../utils/sandbox/git'export interface SnapshotResult {snapshotId: string@@ -23,6 +24,8 @@ export async function stepCreateAndSnapshot(config: SnapshotConfig): Promise<Snaconst sandbox = await createSandbox(config, 2 * 60 * 1000)log.info('snapshot', `[${stepId}] Sandbox created: ${sandbox.sandboxId}`)+ await stripGitMetadata(sandbox)+const snapshot = await sandbox.snapshot()log.info('snapshot', `[${stepId}] Snapshot created: ${snapshot.snapshotId}`)diff --git a/apps/app/server/workflows/sync-docs/steps/take-snapshot.ts b/apps/app/server/workflows/sync-docs/steps/take-snapshot.tsindex d80bad2..1f7973b 100644--- a/apps/app/server/workflows/sync-docs/steps/take-snapshot.ts+++ b/apps/app/server/workflows/sync-docs/steps/take-snapshot.ts@@ -7,6 +7,7 @@import { getStepMetadata } from 'workflow'import { log } from 'evlog'import { Sandbox } from '@vercel/sandbox'+import { stripGitMetadata } from '../../../utils/sandbox/git'export interface TakeSnapshotResult {snapshotId: string@@ -21,6 +22,8 @@ export async function stepTakeSnapshot(sandboxId: string): Promise<TakeSnapshotR// Reconnect to existing sandboxconst sandbox = await Sandbox.get({ sandboxId })+ await stripGitMetadata(sandbox)+const snapshot = await sandbox.snapshot()log.info('sync', `[${stepId}] Snapshot created: ${snapshot.snapshotId}`)diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 0aee980..dd2fdbb 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -199,9 +199,18 @@ The sandbox system uses [Vercel Sandbox Snapshots](https://vercel.com/docs/verce#### Allowed Commands-The sandbox only permits read-only commands: `find`, `ls`, `tree`, `grep`, `cat`, `head`, `tail`, `wc`, `sort`, `uniq`, `diff`, `echo`, `stat`, `file`, `du`, `basename`, `dirname`, `realpath`, `xargs`.+Commands are not pattern-matched. `validateShellCommand()` in `@savoir/sdk` parses the line into pipeline stages and argv tokens, checks each stage against a per-command policy, then rebuilds the line with every argument single-quoted. Callers execute that rebuilt line, never the string they were given, so arguments cannot reopen the shell.-Blocked: `rm`, `curl`, `wget`, `git`, `ssh`, `sudo`, command substitution, redirects, interpreters.+Permitted: `find`, `ls`, `tree`, `grep`, `egrep`, `fgrep`, `cat`, `head`, `tail`, `wc`, `sort`, `uniq`, `cut`, `tr`, `column`, `echo`, `printf`, `basename`, `dirname`, `realpath`, `file`, `stat`, `du`, `diff`, `comm`, `md5sum`, `sha256sum` — each restricted to its own allowlist of options.++Two rules shape that table:++- **No command that can spawn another.** `awk`, `sed` and `xargs` are excluded, along with interpreters. A name-only allowlist cannot constrain what such a command does with its arguments: `awk 'BEGIN{system("id")}'` is a valid `awk` invocation.+- **No command that can write.** `tee` is excluded, as are writing options of otherwise read-only commands (`sort -o`, `find -delete`, `find -fprintf`). The snapshot is shared between users, so a write primitive is a cross-user integrity issue, not just a local one.++Also refused: redirections, command substitution, subshells, background execution, newlines, environment-assignment prefixes, and any path operand resolving outside `/vercel/sandbox`.++Because arguments are quoted, the shell performs no glob expansion. Pass patterns to the tool that handles them (`grep --include='*.md'`, `find -name '*.md'`) rather than relying on the shell to expand `docs/*.md`. Pipelines and `&&`, `||`, `;` between allowed commands continue to work.### 4. AI Agent (Router + Model Selection)@@ -394,7 +403,9 @@ See [ENVIRONMENT.md](./ENVIRONMENT.md) for the complete list.### Sandbox Isolation- Each sandbox runs in an isolated Vercel environment-- No network access from within the sandbox-- Read-only filesystem (cloned snapshot repo)-- Commands limited to read-only operations (grep, cat, find, ls, etc.)-- Blocked: destructive commands, network tools, interpreters, redirects+- Sandboxes are pooled and shared between users, so treat their filesystem as shared state: the command policy is what keeps one user's agent from altering what another user's agent reads+- The filesystem is writable at the OS level; it is the command policy, not a mount option, that keeps access read-only+- Commands are parsed into argv and checked against a per-command policy, then re-quoted before execution (see [Allowed Commands](#allowed-commands))+- No command in the policy can write a file or spawn another process+- The same policy covers the HTTP endpoint and the bot adapters, whose input derives from untrusted issue and message bodies+- `.git` is removed before every snapshot is taken: it carries the clone and push credentials, and anything inside a snapshot is readable by every agent that shares itdiff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.tsindex b7935dd..c14b263 100644--- a/packages/sdk/src/index.ts+++ b/packages/sdk/src/index.ts@@ -2,7 +2,8 @@ import { SavoirClient } from './client'import { createBashBatchTool, createBashTool } from './tools'import type { AgentConfig, GenerateResult, ReportUsageOptions, SavoirConfig } from './types'-export { ALLOWED_BASH_COMMANDS, BLOCKED_SHELL_PATTERNS, isPathWithinDirectory, pathMatchesGlob, validateShellCommand } from './shell-policy'+export { ALLOWED_BASH_COMMANDS, isPathWithinDirectory, pathMatchesGlob, validateShellCommand } from './shell-policy'+export type { ShellValidationOptions, ShellValidationResult } from './shell-policy'export type { SavoirConfig, ShellResponse, ShellBatchResponse, ShellCommandResult, SyncOptions, SyncResponse, SnapshotResponse, GitHubSource, YouTubeSource, SourcesResponse, SyncSourceResponse, AgentConfig, GenerateResult, ReportUsageOptions } from './types'export { SavoirError, NetworkError } from './errors'diff --git a/packages/sdk/src/shell-policy.test.ts b/packages/sdk/src/shell-policy.test.tsindex 8770ae6..2b2f667 100644--- a/packages/sdk/src/shell-policy.test.ts+++ b/packages/sdk/src/shell-policy.test.ts@@ -1,33 +1,148 @@import { describe, expect, test } from 'bun:test'import { isPathWithinDirectory, pathMatchesGlob, validateShellCommand } from './shell-policy'+const SANDBOX = { allowedBaseDirectory: '/vercel/sandbox' }++function validate(command: string) {+ return validateShellCommand(command, SANDBOX)+}++function reason(command: string): string {+ const result = validate(command)+ if (result.ok) {+ throw new Error(`Expected "${command}" to be rejected, got: ${result.command}`)+ }+ return result.reason+}+describe('validateShellCommand', () => {test('accepts allowed command', () => {- const result = validateShellCommand('ls -la docs/')- expect(result).toEqual({ ok: true })+ expect(validate('ls -la docs/')).toEqual({ ok: true, command: `'ls' '-la' 'docs/'` })})- test('rejects blocked shell pattern', () => {- const result = validateShellCommand('ls $(pwd)')- expect(result.ok).toBe(false)+ test('accepts the documented search patterns', () => {+ const commands = [+ 'grep -rl "useAsyncData" docs/ --include="*.md" | head -5',+ 'grep -rlE "term1|term2" docs/ --include="*.md" | head -5',+ 'grep -n -C3 "keyword" docs/path/file.md',+ 'find docs/ -name "*routing*" -name "*.md"',+ 'find docs/ -maxdepth 2 -type d',+ 'head -100 docs/nuxt/index.md',+ 'head -20 docs/nuxt/index.md',+ 'cat docs/path/file.md',+ 'wc -l docs/path/file.md',+ 'ls docs/ | sort | uniq -c | sort -rn | head -10',+ 'grep -c "term" docs/a.md docs/b.md && echo done',+ ]++ for (const command of commands) {+ expect(validate(command).ok).toBe(true)+ }})test('rejects disallowed command', () => {- const result = validateShellCommand('curl https://example.com')+ expect(reason('curl https://example.com')).toBe('Command not allowed: curl')+ expect(reason('id')).toBe('Command not allowed: id')+ })++ test('rejects commands that can spawn other commands', () => {+ // Allowlisting a command name cannot constrain what that command does with+ // its arguments, so interpreters and exec wrappers stay out of the table.+ expect(reason(`awk 'BEGIN{system("id")}'`)).toBe('Command not allowed: awk')+ expect(reason(`awk 'BEGIN{system("curl https://attacker.example")}'`)).toBe('Command not allowed: awk')+ expect(reason('xargs id')).toBe('Command not allowed: xargs')+ expect(reason('echo x | xargs -I% id')).toBe('Command not allowed: xargs')+ expect(reason('sed -i "s/a/b/" README.md')).toBe('Command not allowed: sed')+ expect(reason('python -c "import os"')).toBe('Command not allowed: python')+ expect(reason('less README.md')).toBe('Command not allowed: less')+ })++ test('rejects commands that can write to the sandbox', () => {+ expect(reason('tee /vercel/sandbox/poison.md')).toBe('Command not allowed: tee')+ expect(reason('echo hi | tee /vercel/sandbox/README.md')).toBe('Command not allowed: tee')+ expect(reason('sort -o /vercel/sandbox/README.md docs/a.md')).toBe('Option not allowed for sort: -o')+ expect(reason('find . -name "*.md" -delete')).toBe('Option not allowed for find: -delete')+ expect(reason('find . -fprintf /vercel/sandbox/out.md "%p"')).toBe('Option not allowed for find: -fprintf')+ expect(reason('cat docs/a.md > /vercel/sandbox/README.md')).toBe('Redirection is not allowed')+ expect(reason('cat docs/a.md >> /vercel/sandbox/README.md')).toBe('Redirection is not allowed')+ })++ test('rejects command substitution and shell control constructs', () => {+ expect(reason('ls $(pwd)')).toBe('Command substitution is not allowed')+ expect(reason('ls `pwd`')).toBe('Command substitution is not allowed')+ expect(reason('cat "$(id)"')).toBe('Command substitution is not allowed')+ expect(reason('ls docs/ &')).toBe('Background execution is not allowed')+ expect(reason('(ls docs/)')).toBe('Subshells and brace groups are not allowed')+ expect(reason('cat docs/a.md\nid')).toBe('Newlines are not allowed')+ expect(reason('LD_PRELOAD=/tmp/x.so grep -r a docs/')).toBe('Environment assignments are not allowed: LD_PRELOAD=/tmp/x.so')+ })++ test('rejects paths outside the sandbox, however they are written', () => {+ expect(reason('cat /etc/passwd')).toBe('Path outside sandbox is not allowed: /etc/passwd')+ expect(reason('cat "/etc/passwd"')).toBe('Path outside sandbox is not allowed: /etc/passwd')+ expect(reason(`cat '/etc/passwd'`)).toBe('Path outside sandbox is not allowed: /etc/passwd')+ expect(reason('cat ../../../etc/passwd')).toBe('Path outside sandbox is not allowed: ../../../etc/passwd')+ expect(reason('cat ./../../../etc/passwd')).toBe('Path outside sandbox is not allowed: ./../../../etc/passwd')+ expect(reason('cat /vercel/sandbox/../../etc/passwd')).toBe('Path outside sandbox is not allowed: /vercel/sandbox/../../etc/passwd')+ expect(reason('grep -r secret /etc')).toBe('Path outside sandbox is not allowed: /etc')+ expect(reason('cat docs/a.md /etc/passwd')).toBe('Path outside sandbox is not allowed: /etc/passwd')+ })++ test('treats a leading grep operand as a pattern, not a path', () => {+ expect(validate('grep -rl "/api/users" docs/').ok).toBe(true)+ expect(reason('grep -rl -e "/api/users" /etc')).toBe('Path outside sandbox is not allowed: /etc')+ })++ test('rejects malformed quoting instead of guessing', () => {+ expect(reason(`cat 'docs/a.md`)).toBe('Unbalanced single quote')+ expect(reason('cat "docs/a.md')).toBe('Unbalanced double quote')+ expect(reason('cat docs/a.md |')).toBe('Empty command segment after "|"')+ expect(reason('| head -5')).toBe('Empty command segment before "|"')+ expect(validate('cat docs/a.md;').ok).toBe(true)+ })++ test('rejects options outside the per-command allowlist', () => {+ expect(reason('tail -f docs/a.md')).toBe('Option not allowed for tail: -f')+ expect(reason('grep -f patterns.txt docs/')).toBe('Option not allowed for grep: -f')+ expect(reason('head --lines')).toBe('Option requires a value: --lines')+ })++ test('sanitized command quotes every token', () => {+ const result = validate('grep -rlE "term1|term2" docs/ | head -5')expect(result).toEqual({- ok: false,- reason: 'Command not allowed: curl',+ ok: true,+ command: `'grep' '-rlE' 'term1|term2' 'docs/' | 'head' '-5'`,})})- test('rejects absolute path outside sandbox', () => {- const result = validateShellCommand('cat /etc/passwd', {- allowedBaseDirectory: '/vercel/sandbox',- })- expect(result).toEqual({- ok: false,- reason: 'Path outside sandbox is not allowed: /etc/passwd',+ test('sanitized command neutralises metacharacters inside arguments', () => {+ // The pattern survives as data: bash sees one quoted argument, not a pipeline.+ const result = validate(`grep -r 'a; id' docs/`)+ expect(result).toEqual({ ok: true, command: `'grep' '-r' 'a; id' 'docs/'` })+ })++ test('sanitized command escapes embedded single quotes', () => {+ const result = validate(`grep -r "it's" docs/`)+ expect(result).toEqual({ ok: true, command: `'grep' '-r' 'it'\\''s' 'docs/'` })+ })++ test('sanitizing is idempotent', () => {+ const once = validate('grep -rl "keyword" docs/ | head -5')+ expect(once.ok).toBe(true)+ if (!once.ok) return+ expect(validate(once.command)).toEqual(once)+ })++ test('honours a narrowed command set', () => {+ const result = validateShellCommand('ls docs/', {+ ...SANDBOX,+ allowedCommands: new Set(['cat']),})+ expect(result).toEqual({ ok: false, reason: 'Command not allowed: ls' })+ })++ test('skips path checks when no base directory is set', () => {+ expect(validateShellCommand('cat /etc/passwd').ok).toBe(true)})})diff --git a/packages/sdk/src/shell-policy.ts b/packages/sdk/src/shell-policy.tsindex decadc5..14f55da 100644--- a/packages/sdk/src/shell-policy.ts+++ b/packages/sdk/src/shell-policy.ts@@ -1,67 +1,165 @@import path from 'node:path'-export const ALLOWED_BASH_COMMANDS = new Set([+/** 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',- 'ls',- 'tree',+ 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',- 'egrep',- 'fgrep',+ 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',- 'head',- 'tail',- 'less',- 'more',- // Text processing (output filtering)- 'wc',- 'sort',- 'uniq',- 'cut',- 'awk',- 'sed',- 'tr',- 'column',+ 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',- 'printf',- 'test',- '[',- 'true',- 'false',- 'basename',- 'dirname',- 'realpath',- 'file',- 'stat',- 'du',- 'diff',- 'comm',- 'xargs',- 'tee',- // String/path helpers- 'md5sum',- 'sha256sum',-])--export const BLOCKED_SHELL_PATTERNS = [- /\$\(/, // command substitution $(...)- /`[^`]+`/, // backtick substitution- /\beval\b/, // eval- /\bexec\b/, // exec- /\bsource\b/, // source- /\bbash\b/, // nested bash- /\bsh\b/, // nested sh- /\bzsh\b/, // nested zsh- /\benv\b/, // env (can run arbitrary commands)- />\s*[^\s|]/, // write redirection (> file)- /\bpython\b/, // interpreter- /\bnode\b/, // interpreter- /\bperl\b/, // interpreter- /\bruby\b/, // interpreter-]+ 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 = 64export function isPathWithinDirectory(filePath: string, directory: string): boolean {const resolvedPath = path.resolve(filePath)@@ -103,73 +201,341 @@ export function pathMatchesGlob(filePath: string, glob: string, baseDir: string)}export interface ShellValidationOptions {- allowedCommands?: Set<string>- blockedPatterns?: RegExp[]+ /** 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 }-function extractPotentialPathTokens(command: string): string[] {- const tokenRegex = /(?:^|\s)(\/[^\s|;&]+|\.{1,2}\/[^\s|;&]+)/g- const tokens: 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)- let match: RegExpExecArray | null = null- while ((match = tokenRegex.exec(command)) !== null) {- const [, token] = match- if (token) {- tokens.push(token.replace(/^['"]|['"]$/g, ''))+ 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}` }+}- return tokens+/** 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 validatePaths(command: string, allowedBaseDirectory?: string): ShellValidationResult {- if (!allowedBaseDirectory) {- return { ok: true }+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 tokens = extractPotentialPathTokens(command)- for (const token of tokens) {- if (token.startsWith('../')) {- return { ok: false, reason: `Path traversal is not allowed: ${token}` }+ 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 (token.startsWith('/')) {- if (!isPathWithinDirectory(token, allowedBaseDirectory)) {- return { ok: false, reason: `Path outside sandbox is not allowed: ${token}` }- }++ 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 blockedPatterns = options?.blockedPatterns ?? BLOCKED_SHELL_PATTERNS- const allowedCommands = options?.allowedCommands ?? ALLOWED_BASH_COMMANDS-- for (const pattern of blockedPatterns) {- if (pattern.test(command)) {- return { ok: false, reason: `Command contains blocked pattern: ${command.slice(0, 50)}` }- }+ const parsed = parseCommandLine(command)+ if (!parsed.ok) {+ return { ok: false, reason: parsed.reason }}- const segments = command.split(/\s*(?:\|(?!\|)|\|\||&&|;)\s*/)- for (const segment of segments) {- const trimmed = segment.trim()- if (!trimmed) continue- const words = trimmed.split(/\s+/)- const cmdName = words.find(w => !w.includes('=')) || words[0]- if (!cmdName || !allowedCommands.has(cmdName)) {- return { ok: false, reason: `Command not allowed: ${cmdName || 'unknown'}` }+ const { stages, separators } = parsed.parsed++ for (const stage of stages) {+ const result = validateStage(stage, options)+ if (!result.ok) {+ return result}}- return validatePaths(command, options?.allowedBaseDirectory)+ const sanitized = stages+ .map(stage => stage.map(quoteToken).join(' '))+ .reduce((line, stage, index) => `${line} ${separators[index - 1]!} ${stage}`)++ return { ok: true, command: sanitized }}