{"record":{"id":"d9661b9955bbed1f","repo":"rohitg00/ai-engineering-from-scratch","slug":"path-escapes-sandbox-err-as-error-message","errorCode":null,"errorMessage":"path escapes sandbox: ${(err as Error).message}","messagePattern":"path escapes sandbox: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"phases/19-capstone-projects/01-terminal-native-coding-agent/code/ts/src/tools.ts","lineNumber":21,"sourceCode":"import { z } from \"zod\";\nimport type { ToolArgs, ToolFn } from \"./types.ts\";\n\nexport const TRUNCATE_BYTES = 4096;\n\nexport const ReadFileArgs = z.object({ path: z.string().min(1) });\nexport const RunShellArgs = z.object({ cmd: z.string().min(1) });\n\nexport function toolReadFile(sandbox: string, args: ToolArgs): string {\n  const parsed = ReadFileArgs.parse(args);\n  const candidate = path.resolve(sandbox, parsed.path);\n  const sandboxResolved = path.resolve(sandbox);\n  let full: string;\n  let root: string;\n  try {\n    full = realpathSync(candidate);\n    root = realpathSync(sandboxResolved);\n  } catch (err) {\n    throw new Error(`path escapes sandbox: ${(err as Error).message}`);\n  }\n  if (full !== root && !full.startsWith(root + path.sep)) {\n    throw new Error(\"path escapes sandbox\");\n  }\n  const data = readFileSync(full, \"utf8\");\n  return data.slice(0, TRUNCATE_BYTES);\n}\n\nexport function toolRunShell(_sandbox: string, args: ToolArgs): string {\n  const parsed = RunShellArgs.parse(args);\n  const stub: Record<string, string> = {\n    ls: \"README.md\\nsrc\\ntests\",\n    \"git status\": \"On branch agent/demo\\nnothing to commit, working tree clean\",\n  };\n  const out = stub[parsed.cmd] ?? `(stub) ran: ${parsed.cmd}`;\n  return `exit=0\\n${out.slice(0, TRUNCATE_BYTES)}`;\n}\n","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/rohitg00/ai-engineering-from-scratch/blob/39ea8a1c6d0b61f071226eff7ede4d4105fed820/phases/19-capstone-projects/01-terminal-native-coding-agent/code/ts/src/tools.ts#L3-L39","documentation":"toolReadFile resolves the requested path and the sandbox root with realpathSync; if either realpath call throws (target does not exist, permission denied, symlink loop, unreadable parent), the error is rethrown as 'path escapes sandbox: <cause>'. So the message usually means 'path could not be resolved', not that traversal was actually detected.","triggerScenarios":"read_file with a path that does not exist under the sandbox, a broken symlink, or a path whose parent lacks read permission; realpathSync on the candidate or on sandboxResolved fails and lands in the catch.","commonSituations":"Agent reading a file it assumed existed, file deleted mid-session, or sandbox root misconfigured to a nonexistent directory.","solutions":["Verify the file exists under the sandbox before calling read_file (existsSync)","Check the sandbox root path configuration points at a real, readable directory","If symlinks are involved, ensure they resolve inside the sandbox"],"exampleFix":"// before\nawait agent.run('read_file src/missing.ts');\n// after\nif (!existsSync(join(sandbox, rel))) throw new Error('no such file'); \nawait agent.run('read_file src/missing.ts');","handlingStrategy":"validation","validationCode":"import { existsSync, realpathSync } from 'node:fs'; \nconst full = join(sandbox, rel); \nif (!existsSync(full)) throw new Error('no such file in sandbox'); \nrealpathSync(full); // fail early with a clear cause","typeGuard":null,"tryCatchPattern":"try { return toolReadFile(p); } catch (e) { \n  if (e instanceof Error && e.message.startsWith('path escapes sandbox')) \n    return { error: 'unresolvable path in sandbox' }; \n  throw e; }","preventionTips":["ExistsCheck and resolve paths before invoking the tool","Keep the sandbox root a real, readable directory; validate it at startup","Distinguish 'missing file' from actual traversal attempts in error handling"],"tags":["typescript","sandbox","path-traversal","filesystem"],"backgroundTag":"path-traversal-blocked","analyzedSha":"39ea8a1c6d0b61f071226eff7ede4d4105fed820","analyzedAt":"2026-08-26T03:13:46.626Z","schemaVersion":2},"datasetVersion":"2026-08-26T07:17:17.940Z"}