Network Sandboxing
Relevant source files
The following files were used as context for generating this wiki page:Network and filesystem sandboxing is a security feature within the Tusk Drift CLI, primarily used by the AI Agent (tusk exp init). It isolates shell commands executed by the agent to prevent unintended or malicious actions, ensuring that operations are confined to the project's scope. This mechanism provides a secure environment for the AI to interact with the user's file system and network.
The sandboxing is implemented using the fence library, which in turn relies on underlying system tools like bubblewrap and socat on Linux. Sandboxing is applied to one-shot commands run via the agent's run_command tool, but not to long-running processes like the user's service, which needs to make real external calls during the recording phase.
Sources: internal/agent/README.md, README.md:38-44, internal/agent/tools/process.go:190-194
Architecture and Dependencies
The sandboxing architecture is centered around the ProcessManager which integrates with the fence library. The availability of this feature depends on the operating system and the presence of specific dependencies.
Sources: internal/agent/tools/process.go:21-28
Core Components
The following diagram illustrates the relationship between the Tusk Drift CLI and its sandboxing dependencies.
This diagram shows that the ProcessManager uses the fence library, which requires bubblewrap and socat to be installed on the system.
Sources: internal/agent/tools/process.go:56-65, README.md:38-44
System Requirements
For sandboxing to be enabled on Linux, the following packages must be installed. If they are not found, sandboxing is automatically disabled, and commands are run without network or filesystem isolation.
| Package | Description | Installation (Debian/Ubuntu) |
|---|---|---|
bubblewrap | Provides unprivileged sandboxing | sudo apt install bubblewrap |
socat | Multipurpose relay for bidirectional data | sudo apt install socat |
On Windows, the recommended approach is to use WSL, which allows for the use of the Linux sandboxing environment. Native Windows support uses a different TCP communication mode and does not use this sandboxing mechanism.
Sources: README.md:38-50, 63-79
Initialization
The ProcessManager is initialized with sandboxing capabilities via NewProcessManagerWithOptions. It can be explicitly disabled by passing disableSandbox: true.
// internal/agent/agent.go:80-80
pm := NewProcessManagerWithOptions(cfg.WorkDir, cfg.DisableSandbox, cfg.Debug)
During initialization, the ProcessManager attempts to initialize fence. If this fails (e.g., due to missing dependencies), the fenceEnabled flag is set to false, and the CLI proceeds without sandboxing.
Sources: internal/agent/agent.go:80, internal/agent/tools/process.go:56-65
Sandboxing Configuration
When enabled, the fence library is configured with specific rules for network and filesystem access. These rules are defined in the createFenceConfig function and are designed to allow legitimate package management and file operations while blocking access to sensitive areas of the system.
Sources: internal/agent/tools/process.go:73-76
Filesystem Access
The sandbox restricts file read/write operations to prevent the agent from modifying files outside the project directory or reading sensitive system files.
| Type | Paths Allowed | Paths Denied |
|---|---|---|
| Write | Project directory (workDir), .tusk/, node_modules/, /tmp, ~/.npm, ~/.cache | ../* (directory traversal) |
| Read | (Implicitly most of project) | /etc/shadow, /etc/passwd |
Sources: internal/agent/tools/process.go:94-111
Network Access
Network access is restricted to a list of allowed domains, primarily for package managers and common code hosting platforms.
| Allowed Domains - registry.npmjs.org
registry.yarnpkg.compypi.org*.github.com*.gitlab.comlocalhost,127.0.0.1|
Local network binding is also permitted, allowing sandboxed processes to start local servers if needed.
Sources: internal/agent/tools/process.go:79-92
Execution Flow
Sandboxing is applied when the AI agent uses the run_command tool. The start_background_process tool, which is used to run the user's service for recording, is intentionally not sandboxed because it needs to make real outbound calls to databases and other services.
Sources: internal/agent/executor.go:142-154, internal/agent/tools/process.go:190-194
Pre-Execution Safety Checks
Before a command is even passed to the sandbox, it undergoes a preliminary safety check via validateCommandSafety. This function blocks a list of inherently dangerous command patterns to provide a first line of defense.
| Blocked Pattern Examples | Reason for Blocking |
|---|---|
rm -rf | Recursive forced deletion |
> /dev/ | Writing to device files |
| `:(){: | :&};:` |
sudo | Elevated privileges not allowed |
wget, curl | Downloading files (use http_request tool instead) |
npm publish | Publishing packages |
git push | Pushing to remote repository |
Sources: internal/agent/tools/process.go:121-188
Sandboxed Command Execution
The sequence diagram below shows the process of executing a sandboxed command.
This flow demonstrates that a command is first validated for safety, then wrapped by the fence sandboxing logic, and finally executed by the operating system.
Sources: internal/agent/tools/process.go:197-211, internal/agent/agent.go:622-732
Summary
The network sandboxing feature in tusk-drift-cli is a critical security measure for the AI-powered setup agent. By leveraging fence and system utilities like bubblewrap, it creates a controlled environment for executing shell commands. This is complemented by a preliminary command validation step. The system is designed to be robust, gracefully disabling sandboxing if dependencies are missing, while clearly delineating which agent tools are sandboxed and which are not, balancing security with the functional requirements of recording application behavior.