Sandbox Filesystem Tool

Tool Arguments Schema

Define a Zod schema with the following structure:

const sandboxFilesystemSchema = z.object({
  operation: z.enum(['read', 'write', 'list', 'createDir', 'delete', 'exists', 'info']),
  path: z.string().describe('Target filesystem path within sandbox'),
  content: z.string().optional().describe('Content to write (for write operation)'),
  encoding: z.string().default('utf-8').optional().describe('Character encoding'),
  recursive: z.boolean().default(false).optional().describe('Enable recursive operations'),
  force: z.boolean().default(false).optional().describe('Force overwrite or deletion'),
});

type SandboxFilesystemArgs = z.infer<typeof sandboxFilesystemSchema>;

Implementation Structure

import { Injectable } from '@nestjs/common';
import { z } from 'zod';
import { ToolBase } from '@loopstack/core';
import { BlockConfig, ToolResult, WithArguments } from '@loopstack/common';

@Injectable()
@BlockConfig({
  config: {
    description: 'Secure filesystem operations within Docker sandbox environments',
  },
})
@WithArguments(sandboxFilesystemSchema)
export class SandboxFilesystemTool extends ToolBase<SandboxFilesystemArgs> {
  
  async execute(args: SandboxFilesystemArgs): Promise<ToolResult<any>> {
    // 1. Validate path for security (no ../ traversal)
    // 2. Normalize path
    // 3. Execute operation based on args.operation
    // 4. Return structured result with success, data, metadata
  }
}

Tool Result Structure

Return a ToolResult with this structure:

{
  data: {
    success: boolean,
    data: any,              // Operation-specific payload
    error?: string,         // Error message if failed
    metadata?: {            // Additional context
      bytesWritten?: number,
      itemsCount?: number,
      // etc.
    }
  }
}

Security Requirements

Path Validation

• CRITICAL: Block path traversal attacks by rejecting paths containing ../
• Normalize all paths before execution
• Restrict access to sandbox-designated directories only
• Never allow access to system directories like /etc, /sys, /proc

Resource Limits

• Enforce maxFileSize configuration (suggest default: 10MB)
• Implement operation timeouts (suggest default: 5000ms)
• Limit recursive depth to prevent infinite loops (suggest max: 10 levels)

Error Handling

• Sanitize error messages to prevent information leakage
• Provide generic errors to users, detailed logs internally
• Fail safely on permission errors

Configuration Options

Support these configuration properties in the tool:

interface SandboxFilesystemConfig {
  defaultEncoding?: string;      // Default: 'utf-8'
  maxFileSize?: number;          // Default: 10485760 (10MB)
  allowedPaths?: string[];       // Whitelist of accessible paths
  timeoutMs?: number;            // Default: 5000
}

Usage Examples

Example 1: Read a Configuration File