Filesystem Fence
Restricts file access to authorized areas and protects sensitive files.
This guard is primarily relevant to administrators and deployments where agents have file system access. If your agents only handle conversations without file operations, this guard runs silently in the background with nothing to monitor.
What It Does
When your agent can read and write files, you want to make sure it stays within its designated area. Filesystem Fence draws a boundary around your agent's workspace -- files inside the boundary are accessible, everything outside is off-limits.
It also provides extra protection for especially sensitive files (like environment variables and configuration files) even within the workspace. The guard catches both direct attempts to access restricted files and indirect tricks like using specially crafted file paths to escape the boundary. Think of it as a fence around your agent's yard -- with locks on the shed where you keep the valuables.
The guard uses a fail-closed approach (when something goes wrong, deny access rather than allow it): if anything goes wrong when checking a file path (for example, if a path can't be fully resolved), access is denied rather than allowed. This means even novel bypass techniques default to being blocked.
Why It Matters
Without file access controls, an attacker could read sensitive configuration, credentials, or data -- or worse, modify critical files to change how your system works. This guard is essential for any agent that has file system tools enabled.
Even if your agent only needs to read documents in a single folder, Filesystem Fence ensures it can never wander outside that folder, no matter what instructions it receives.
What Gets Caught
- Paths outside the workspace — any attempt to read or write files outside the agent's designated workspace directory
- Path traversal — using
../sequences (or encoded variants) to escape the workspace boundary - Environment files — reading
.env,.env.local,.env.production, or similar files that typically contain secrets - Agent personality files — writing to
SOUL.mdor_SOUL.md, which define the agent's behavior - Protected system paths — access to CrabShield's own configuration and system directories
- Symlink tricks — creating a symlink (a shortcut file that points to another location) inside the workspace that points to a file outside it
What won't trigger it: Reading and writing files inside the workspace, accessing files in exempted paths (if configured), and normal file operations that stay within boundaries. If a skill legitimately needs to access a file outside the workspace, add it to the exemption's allowedPaths.
Example
An agent is helping a user find information and attempts to read ../../etc/passwd — a path traversal attack that tries to escape the workspace and access a sensitive system file. Filesystem Fence detects the ../ sequence, determines the resolved path is outside the agent's workspace, and blocks the file read. The audit log shows the attempted path, the resolved destination, and the reason for blocking (path traversal). The agent cannot access the file and the operation fails safely.
Settings
These settings are available in the CrabShack dashboard under your agent's security configuration.
| Setting | What It Controls |
|---|---|
| Workspace Only | Restrict all file access to the agent's workspace directory |
| Protected Paths | Additional paths that are always blocked, even within the workspace |
| Block .env Reads | Prevent reading environment variable files |
| Block SOUL.md Writes | Prevent modification of agent personality files |
| Exemptions | Allow specific skills to access files outside the workspace |
How It Responds
Unauthorized file access is blocked and logged. There's no "warn" mode for this guard -- if a file is outside the boundary or on the protected list, access is denied. This strict approach ensures there's no gap where sensitive files could be accessed while you're reviewing alerts.
If This Guard Blocks You
-
Check the audit log. Navigate to Security > Audit Log in the CrabShack dashboard. Filter by Filesystem Fence to find the relevant event. Click on the event row to see details including the skill name and channel — you'll need these values if you want to create an exemption.
-
Understand the detection. The audit log shows the file path that was blocked and the reason — path outside workspace, path traversal detected, protected file (like
.env), or symlink (a shortcut file that points to another location, which could trick the guard into accessing restricted files) pointing outside the boundary. If a skill legitimately needs to access a file outside the workspace, create an exemption with the specificallowedPathsfor that skill. If a.envread was blocked and the skill needs environment variables, consider passing them through a safer mechanism rather than having the agent read the file directly. -
Adjust if needed. Create an exemption with
allowedPathsfor specific files a skill needs outside the workspace. This guard doesn't have a Warn mode — access is either allowed or denied. See the Configuration page for details on exemptions.
Prefer creating a targeted exemption for a specific skill or channel over disabling the guard entirely. If you're seeing frequent false positives, a suppression lets you silence a specific detection label temporarily while you refine your settings.
Default Behavior
The guard runs in workspace-only mode by default. Environment files and personality files are protected. Access errors are always denied (fail-closed). No changes occur during lockdown because the default settings are already strict.
Related Guards
- Tool Gate -- provides tool-level access control, complementing the path-level enforcement here.
- Config Tamper Detection -- detects unauthorized changes to CrabShield's own configuration.
- Credential Vault -- redacts credentials found in file contents that the agent reads.