Module filesystem 

Filesystem tools with path traversal protection.

All tools in this module operate within a configured base_path directory, preventing access to files outside this boundary. This security model protects against directory traversal attacks where malicious input like ../../../etc/passwd attempts to escape the intended directory.

Security Model

Every file operation validates paths using validate_path before execution:

• Paths are resolved relative to base_path (or used directly if absolute)
• The resolved path is canonicalized to eliminate .., ., and symlinks
• The canonical path must start with the canonical base_path
• For non-existent paths, the nearest existing ancestor is validated instead

This means symlinks that point outside base_path are rejected, and crafted paths like subdir/../../../etc/passwd are caught after canonicalization.

Defense in Depth

Path validation provides guardrails for AI agents, not a complete security boundary. Error messages intentionally include path details to help agents understand and correct invalid requests.

For production deployments with untrusted input, use defense in depth:

• Docker isolation: Run tools in containers with only necessary directories mounted
• OS-level permissions: Use a dedicated user with minimal filesystem access
• Network isolation: Restrict container network access where possible

These tools are one layer in a security stack, not a standalone sandbox.

Available Tools

Tool	Description
ReadFileTool	Read file contents with optional offset/limit
ReadMultipleFilesTool	Read multiple files concurrently
WriteFileTool	Write or append to files
CreateDirectoryTool	Create directories (including parents)
ListDirectoryTool	List directory contents recursively
MoveFileTool	Move or rename files and directories
FileInfoTool	Get file metadata (size, timestamps, type)

Building Custom Tools

Use validate_path when building your own filesystem tools:

use mixtape_tools::filesystem::validate_path;
use std::path::Path;

let base = Path::new("/app/data");
let user_input = Path::new("../etc/passwd");

// This will return an error because the path escapes base
assert!(validate_path(base, user_input).is_err());

Structs

CreateDirectoryTool

Tool for creating directories

FileInfoTool

Tool for retrieving file metadata

ListDirectoryTool

Tool for listing directory contents

MoveFileTool

Tool for moving or renaming files and directories

ReadFileTool

Tool for reading file contents from the filesystem

ReadMultipleFilesTool

Tool for reading multiple files concurrently

WriteFileTool

Tool for writing content to files

Functions

all_tools

Returns all filesystem tools

mutative_tools

Returns all mutative filesystem tools

read_only_tools

Returns all read-only filesystem tools

validate_path

Validates that a path is within the base directory, preventing directory traversal attacks.