12.10 Path Boundary Protection

Path boundary protection ensures that tool operations do not exceed the allowed path scope. This is a seemingly simple but detail-rich security mechanism.

Basic Principle

Every operation involving file paths goes through checkPathConstraints validation:

1. Main working directory check: The path must be within the current project directory (cwd) and its subdirectories
2. Additional working directory check: Extra allowed paths added via the /add-dir command
3. Out-of-bounds rejection: Paths not within any allowed scope are directly rejected

Symlink Resolution

Simple path.resolve is insufficient to defend against all attacks. An attacker can create symlinks within the project directory pointing to external paths:

# Attack example
ln -s /etc/passwd ./project/innocent-file
# Now ./project/innocent-file passes the path check (within the project directory)
# But actually points to /etc/passwd

Therefore, the system resolves symlinks for both the path and the working directory, performing symmetric comparison. On macOS, special handling is also needed: /home is a symlink to /System/Volumes/Data/home, and /tmp points to /private/tmp.

Bash-Specific Path Validation

src/tools/BashTool/pathValidation.ts implements dedicated path extractors (PATH_EXTRACTORS) for each command type, covering a wide range of commands:

Command Category	Commands
Directory operations	cd, mkdir
File operations	touch, rm, rmdir, mv, cp
Read commands	cat, head, tail, sort, uniq, wc, cut, paste, column, tr, file, stat, strings, hexdump, od, base64, nl
Search commands	ls, find, grep, rg
Edit commands	sed, awk
VCS	git
Data processing	jq, diff
Checksums	sha256sum, sha1sum, md5sum

The path extraction logic differs for each command—for example, cp needs to validate both source and destination paths, mv likewise, while cat only needs to validate the read path.

Dangerous Deletion Protection

checkDangerousRemovalPaths specifically protects against catastrophic deletion operations. When it detects that the target of rm or rmdir is a critical system path (such as /, /home, /etc, ~), it forces user confirmation and does not offer the "Always allow" option—preventing users from accidentally saving rm -rf / as an auto-allow rule.

Source: src/tools/BashTool/pathValidation.ts, src/utils/permissions/pathValidation.ts