ruby_llm-docker 0.2.5 → 0.3.0

data/lib/ruby_llm/docker/exec_container.rb

@@ -2,143 +2,124 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for executing commands inside running Docker containers.
+    # MCP tool for executing commands inside Docker containers.
     #
-    # This tool provides the ability to execute arbitrary commands inside running
-    # Docker containers, with full control over execution environment including
-    # working directory, user context, environment variables, and stdin input.
+    # This tool provides the ability to execute arbitrary commands inside
+    # running Docker containers. It supports interactive and non-interactive
+    # execution, environment variable injection, working directory specification,
+    # and user context switching within the container.
     #
-    # == ⚠️ CRITICAL SECURITY WARNING ⚠️
+    # == Features
     #
-    # This tool is EXTREMELY DANGEROUS as it allows arbitrary command execution
-    # within Docker containers. This can be used to:
-    # - Execute malicious code inside containers
-    # - Access sensitive data within container filesystems
-    # - Escalate privileges if container is poorly configured
-    # - Perform lateral movement within containerized environments
-    # - Exfiltrate data from applications
+    # - Execute arbitrary commands in running containers
+    # - Support for command arguments and shell parsing
+    # - Environment variable injection
+    # - Working directory specification
+    # - User context switching (run as specific user)
+    # - Standard input, output, and error handling
+    # - Configurable execution timeouts
     #
-    # ONLY use this tool in trusted environments with proper security controls:
-    # - Ensure containers run with minimal privileges
-    # - Use read-only filesystems where possible
-    # - Implement proper network segmentation
-    # - Monitor and audit all command executions
-    # - Never expose this tool to untrusted clients
+    # == Security Considerations
     #
-    # == Features
+    # **CRITICAL WARNING**: This tool provides arbitrary command execution
+    # capabilities with significant security implications:
+    #
+    # - **Code Execution**: Can run any command available in the container
+    # - **File System Access**: Can read, write, and modify container files
+    # - **Network Access**: Can initiate network connections from container
+    # - **Process Manipulation**: Can start, stop, and signal processes
+    # - **Data Exposure**: Can access sensitive data within the container
+    # - **Privilege Escalation**: May exploit container or kernel vulnerabilities
+    # - **Resource Consumption**: Can consume container and host resources
+    #
+    # **Security Recommendations**:
+    # - Implement strict access controls and authentication
+    # - Use dedicated execution containers with minimal privileges
+    # - Monitor and log all command executions
+    # - Apply resource limits and timeouts
+    # - Validate and sanitize all command inputs
+    # - Consider using read-only file systems where possible
+    # - Implement network segmentation for container environments
     #
-    # - Execute commands with custom working directory
-    # - Run commands as specific users
-    # - Set custom environment variables
-    # - Provide stdin input to commands
-    # - Configurable timeout protection
-    # - Comprehensive error handling
-    # - Separate stdout/stderr capture
+    # == Parameters
+    #
+    # - **id**: Container ID or name (required)
+    # - **cmd**: Command to execute (shell-parsed into arguments) (required)
+    # - **working_dir**: Working directory for command execution (optional)
+    # - **user**: User to run the command as (optional, e.g., "1000" or "username")
+    # - **env**: Environment variables as comma-separated KEY=VALUE pairs (optional)
+    # - **stdin**: Input to send to command via stdin (optional)
+    # - **timeout**: Timeout in seconds (optional, default: 60)
     #
     # == Example Usage
     #
-    #   # Simple command execution
-    #   ExecContainer.call(
+    #   # Basic command execution
+    #   response = ExecContainer.call(
     #     server_context: context,
-    #     id: "my-container",
-    #     cmd: "ls -la /app"
+    #     id: "web-container",
+    #     cmd: "nginx -t"
     #   )
     #
-    #   # Advanced execution with custom environment
-    #   ExecContainer.call(
+    #   # Advanced execution with environment
+    #   response = ExecContainer.call(
     #     server_context: context,
-    #     id: "web-server",
-    #     cmd: "python manage.py migrate",
+    #     id: "app-container",
+    #     cmd: "bundle exec rails console",
     #     working_dir: "/app",
-    #     user: "appuser",
-    #     env: ["DJANGO_ENV=production", "DEBUG=false"],
-    #     timeout: 120
+    #     user: "rails",
+    #     env: "RAILS_ENV=production,DEBUG=true",
+    #     timeout: 300
     #   )
     #
-    # @see Docker::Container#exec
+    # @see ::Docker::Container#exec
     # @since 0.1.0
-    class ExecContainer < RubyLLM::Tool
+    EXEC_CONTAINER_DEFINITION = ToolForge.define(:exec_container) do
       description 'Execute a command inside a running Docker container. ' \
                   'WARNING: This provides arbitrary command execution within the container. ' \
                   'Ensure proper security measures are in place.'
 
-      param :id, type: :string, desc: 'Container ID or name'
-      param :cmd, type: :string, desc: 'Command to execute (e.g., "ls -la /app" or "python script.py")'
-      param :working_dir, type: :string, desc: 'Working directory for the command (optional)', required: false
-      param :user, type: :string, desc: 'User to run the command as (optional, e.g., "1000" or "username")',
-                   required: false
-      param :env, type: :string,
-                  desc: 'Environment variables as comma-separated KEY=VALUE pairs ' \
-                        '(optional, e.g., "VAR1=value1,VAR2=value2")',
-                  required: false
-      param :stdin, type: :string, desc: 'Input to send to the command via stdin (optional)', required: false
-      param :timeout, type: :integer, desc: 'Timeout in seconds (optional, default: 60)', required: false
-
-      # Execute a command inside a running Docker container.
-      #
-      # This method provides comprehensive command execution capabilities within
-      # Docker containers, including advanced features like custom user context,
-      # environment variables, working directory, and stdin input.
-      #
-      # The command is parsed using shell-like syntax with support for quoted
-      # arguments. Output is captured separately for stdout and stderr, and
-      # the exit code is reported.
-      #
-      # @param id [String] container ID or name to execute command in
-      # @param cmd [String] command to execute (shell-parsed into arguments)
-      # @param server_context [Object] RubyLLM context (unused but required)
-      # @param working_dir [String, nil] working directory for command execution
-      # @param user [String, nil] user to run command as (username or UID)
-      # @param env [String, nil] environment variables as comma-separated KEY=VALUE pairs
-      # @param stdin [String, nil] input to send to command via stdin
-      # @param timeout [Integer] maximum execution time in seconds (default: 60)
-      #
-      # @return [RubyLLM::Tool::Response] execution results including stdout, stderr, and exit code
-      #
-      # @raise [Docker::Error::NotFoundError] if container doesn't exist
-      # @raise [Docker::Error::TimeoutError] if execution exceeds timeout
-      # @raise [StandardError] for other execution failures
-      #
-      # @example Basic command execution
-      #   response = ExecContainer.call(
-      #     server_context: context,
-      #     id: "web-container",
-      #     cmd: "nginx -t"
-      #   )
-      #
-      # @example Advanced execution with environment
-      #   response = tool.execute(
-      #     id: "app-container",
-      #     cmd: "bundle exec rails console",
-      #     working_dir: "/app",
-      #     user: "rails",
-      #     env: ["RAILS_ENV=production"],
-      #     timeout: 300
-      #   )
-      #
-      # @see Docker::Container#exec
-      def execute(id:, cmd:, working_dir: nil, user: nil,
-                  env: nil, stdin: nil, timeout: 60)
+      param :id,
+            type: :string,
+            description: 'Container ID or name'
+
+      param :cmd,
+            type: :string,
+            description: 'Command to execute (e.g., "ls -la /app" or "python script.py")'
+
+      param :working_dir,
+            type: :string,
+            description: 'Working directory for the command (optional)',
+            required: false
+
+      param :user,
+            type: :string,
+            description: 'User to run the command as (optional, e.g., "1000" or "username")',
+            required: false
+
+      param :env,
+            type: :string,
+            description: 'Environment variables as comma-separated KEY=VALUE pairs (optional)',
+            required: false
+
+      param :stdin,
+            type: :string,
+            description: 'Input to send to the command via stdin (optional)',
+            required: false
+
+      param :timeout,
+            type: :integer,
+            description: 'Timeout in seconds (optional, default: 60)',
+            required: false,
+            default: 60
+
+      execute do |id:, cmd:, working_dir: nil, user: nil, env: nil, stdin: nil, timeout: 60|
         container = ::Docker::Container.get(id)
 
         # Parse command string into array
-        # Simple shell-like parsing: split on spaces but respect quoted strings
         cmd_array = Shellwords.split(cmd)
 
-        # Parse environment variables string into array if provided
-        env_array = nil
-        env_array = env.split(',').map(&:strip).select { |e| e.include?('=') } if env && !env.empty?
-
-        # Build exec options
-        exec_options = {
-          'Cmd' => cmd_array,
-          'AttachStdout' => true,
-          'AttachStderr' => true
-        }
-        exec_options['WorkingDir'] = working_dir if working_dir
-        exec_options['User'] = user if user
-        exec_options['Env'] = env_array if env_array
-        exec_options['AttachStdin'] = true if stdin
+        # Parse environment variables from comma-separated string to array
+        env.split(',').map(&:strip) if env && !env.empty?
 
         # Execute the command
         stdout_data = []
@@ -181,5 +162,7 @@ module RubyLLM
         "Error executing command: #{e.message}"
       end
     end
+
+    ExecContainer = EXEC_CONTAINER_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/fetch_container_logs.rb

@@ -2,116 +2,92 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for retrieving Docker container logs.
+    # MCP tool for fetching Docker container logs.
     #
-    # This tool provides access to container logs with flexible filtering and
-    # formatting options. It can retrieve both stdout and stderr logs with
-    # optional timestamps and tail functionality for recent entries.
+    # This tool retrieves log output from Docker containers, including both
+    # standard output and standard error streams. It supports filtering by
+    # stream type, limiting output length, timestamp inclusion, and retrieving
+    # logs from both running and stopped containers.
     #
     # == Features
     #
-    # - Retrieve stdout and/or stderr logs
-    # - Optional timestamp inclusion
-    # - Tail functionality for recent logs
-    # - Flexible log stream selection
-    # - Comprehensive error handling
-    # - Works with any container state
-    #
-    # == Log Sources
-    #
-    # Docker containers can generate logs from multiple sources:
-    # - **stdout**: Standard output from container processes
-    # - **stderr**: Standard error from container processes
-    # - **timestamps**: Docker-generated timestamps for each log line
+    # - Fetch logs from running and stopped containers
+    # - Separate or combined stdout and stderr streams
+    # - Configurable output length limiting (tail functionality)
+    # - Optional timestamp inclusion for log entries
+    # - Support for container identification by ID or name
+    # - Comprehensive error handling and status reporting
     #
     # == Security Considerations
     #
     # Container logs may contain sensitive information:
-    # - Application secrets and API keys
-    # - User data and personal information
-    # - Internal system information
-    # - Database connection strings
-    # - Error messages with stack traces
+    # - **Application Data**: Database queries, API keys, user data
+    # - **System Information**: Internal paths, configuration details
+    # - **Error Details**: Stack traces revealing application internals
+    # - **Access Patterns**: User behavior and system usage information
+    # - **Debugging Information**: Temporary credentials or session data
+    #
+    # Implement proper access controls and data sanitization for log access.
     #
-    # Security recommendations:
-    # - Review log content before sharing
-    # - Limit access to container logs
-    # - Sanitize logs in production environments
-    # - Use log rotation to manage log size
-    # - Be cautious with log forwarding
+    # == Parameters
+    #
+    # - **id**: Container ID or name (required)
+    # - **stdout**: Include stdout in logs (optional, default: true)
+    # - **stderr**: Include stderr in logs (optional, default: true)
+    # - **timestamps**: Show timestamps for log entries (optional, default: false)
+    # - **tail**: Number of lines to show from end of logs (optional, default: all)
     #
     # == Example Usage
     #
-    #   # Get all logs
-    #   FetchContainerLogs.call(
+    #   # Fetch all logs
+    #   response = FetchContainerLogs.call(
     #     server_context: context,
     #     id: "web-server"
     #   )
     #
-    #   # Get recent logs with timestamps
-    #   FetchContainerLogs.call(
+    #   # Fetch recent errors with timestamps
+    #   response = FetchContainerLogs.call(
     #     server_context: context,
     #     id: "app-container",
-    #     tail: 100,
-    #     timestamps: true
-    #   )
-    #
-    #   # Get only error logs
-    #   FetchContainerLogs.call(
-    #     server_context: context,
-    #     id: "database",
     #     stdout: false,
-    #     stderr: true
+    #     stderr: true,
+    #     timestamps: true,
+    #     tail: 100
     #   )
     #
-    # @see ExecContainer
-    # @see Docker::Container#logs
+    # @see ::Docker::Container#logs
     # @since 0.1.0
-    class FetchContainerLogs < RubyLLM::Tool
+    FETCH_CONTAINER_LOGS_DEFINITION = ToolForge.define(:fetch_container_logs) do
       description 'Fetch Docker container logs'
 
-      param :id, type: :string, desc: 'Container ID or name'
-      param :stdout, type: :boolean, desc: 'Include stdout (default: true)', required: false
-      param :stderr, type: :boolean, desc: 'Include stderr (default: true)', required: false
-      param :tail, type: :integer, desc: 'Number of lines to show from the end of logs (default: all)',
-                   required: false
-      param :timestamps, type: :boolean, desc: 'Show timestamps (default: false)', required: false
+      param :id,
+            type: :string,
+            description: 'Container ID or name'
+
+      param :stdout,
+            type: :boolean,
+            description: 'Include stdout (default: true)',
+            required: false,
+            default: true
+
+      param :stderr,
+            type: :boolean,
+            description: 'Include stderr (default: true)',
+            required: false,
+            default: true
 
-      # Retrieve logs from a Docker container.
-      #
-      # This method fetches logs from the specified container with configurable
-      # options for log sources (stdout/stderr), formatting (timestamps), and
-      # quantity (tail). The logs are returned as a text response.
-      #
-      # @param id [String] container ID (full or short) or container name
-      # @param server_context [Object] RubyLLM context (unused but required)
-      # @param stdout [Boolean] whether to include stdout logs (default: true)
-      # @param stderr [Boolean] whether to include stderr logs (default: true)
-      # @param tail [Integer, nil] number of recent lines to return (nil for all)
-      # @param timestamps [Boolean] whether to include timestamps (default: false)
-      #
-      # @return [RubyLLM::Tool::Response] container logs as text
-      #
-      # @raise [Docker::Error::NotFoundError] if container doesn't exist
-      # @raise [StandardError] for other log retrieval failures
-      #
-      # @example Get all logs
-      #   response = FetchContainerLogs.call(
-      #     server_context: context,
-      #     id: "nginx-server"
-      #   )
-      #
-      # @example Get recent error logs with timestamps
-      #   response = tool.execute(
-      #     id: "app-container",
-      #     stdout: false,
-      #     stderr: true,
-      #     tail: 50,
-      #     timestamps: true
-      #   )
-      #
-      # @see Docker::Container#logs
-      def execute(id:, stdout: true, stderr: true, tail: nil, timestamps: false)
+      param :tail,
+            type: :integer,
+            description: 'Number of lines to show from the end of logs (default: all)',
+            required: false
+
+      param :timestamps,
+            type: :boolean,
+            description: 'Show timestamps (default: false)',
+            required: false,
+            default: false
+
+      execute do |id:, stdout: true, stderr: true, tail: nil, timestamps: false|
         container = ::Docker::Container.get(id)
 
         options = {
@@ -128,5 +104,7 @@ module RubyLLM
         "Error fetching logs: #{e.message}"
       end
     end
+
+    FetchContainerLogs = FETCH_CONTAINER_LOGS_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/list_containers.rb

@@ -2,58 +2,64 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for listing Docker containers.
+    # MCP tool for listing Docker containers.
     #
-    # This tool provides functionality to list all Docker containers on the system,
-    # including both running and stopped containers. It returns detailed information
-    # about each container including names, images, status, ports, and other metadata.
+    # This tool provides comprehensive information about all Docker containers
+    # on the system, including both running and stopped containers. It returns
+    # detailed metadata for each container including names, images, status,
+    # network configuration, and resource usage.
     #
-    # == Security Notes
+    # == Features
     #
-    # This is a read-only operation that provides system information about containers.
-    # While generally safe, it may reveal information about the Docker environment
-    # that could be useful for reconnaissance.
+    # - Lists all containers (running and stopped)
+    # - Provides detailed container metadata
+    # - Shows network configuration and port mappings
+    # - Displays resource usage and statistics
+    # - Includes mount point information
+    # - Shows container labels and annotations
     #
-    # == Example Usage
+    # == Security Considerations
+    #
+    # This tool provides system information that could be useful for:
+    # - **System Reconnaissance**: Reveals running services and configurations
+    # - **Network Discovery**: Shows internal network topology
+    # - **Resource Analysis**: Exposes system resource usage patterns
     #
-    #   # List all containers (default behavior)
-    #   ListContainers.call(server_context: context)
+    # Use with appropriate access controls in production environments.
     #
-    #   # Explicitly request all containers
-    #   ListContainers.call(server_context: context, all: true)
+    # == Return Format
     #
-    # @see Docker::Container.all
+    # Returns an array of container objects with comprehensive metadata:
+    # - Container names and IDs
+    # - Image information and tags
+    # - Current state and status
+    # - Network settings and port bindings
+    # - Mount points and volumes
+    # - Labels and environment details
+    #
+    # == Example Usage
+    #
+    #   containers = ListContainers.call(server_context: context)
+    #   containers.each do |container|
+    #     puts "#{container['Names'].first}: #{container['State']}"
+    #   end
+    #
+    # @see ::Docker::Container.all
     # @since 0.1.0
-    class ListContainers < RubyLLM::Tool
+    LIST_CONTAINERS_DEFINITION = ToolForge.define(:list_containers) do
       description 'List Docker containers'
 
-      param :all, type: :boolean, desc: 'Show all containers (default shows all containers including stopped ones)',
-                  required: false
+      param :all,
+            type: :boolean,
+            description: 'Show all containers (default shows all containers including stopped ones)',
+            required: false,
+            default: true
 
-      # List all Docker containers with detailed information.
-      #
-      # Retrieves information about all containers on the system, including:
-      # - Container names and IDs
-      # - Image information
-      # - Current state (running, stopped, etc.)
-      # - Port mappings
-      # - Network configuration
-      # - Volume mounts
-      # - Creation and status timestamps
-      #
-      # @param server_context [Object] the RubyLLM context (unused but required)
-      # @param all [Boolean] whether to show all containers (default: true)
-      # @return [RubyLLM::Tool::Response] response containing container information
-      #
-      # @example List all containers
-      #   response = ListContainers.call(server_context: context)
-      #   # Returns detailed info for all containers
-      #
-      # @see Docker::Container.all
-      def execute(all: true)
-        require 'docker'
-        ::Docker::Container.all(all: all).map(&:info).to_s
+      execute do |all: true|
+        ::Docker::Container.all(all: all).map(&:info)
       end
     end
+
+    ListContainers = LIST_CONTAINERS_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/list_images.rb

@@ -2,78 +2,57 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for listing Docker images.
+    # MCP tool for listing Docker images.
     #
-    # This tool provides functionality to list all Docker images available on
-    # the local system. It returns comprehensive information about each image
-    # including IDs, tags, sizes, creation dates, and other metadata.
+    # This tool provides comprehensive information about all Docker images
+    # stored on the local system. It returns detailed metadata including
+    # image sizes, creation dates, tags, and usage statistics.
     #
     # == Features
     #
-    # - List all local Docker images
-    # - Comprehensive image metadata
-    # - No configuration required
-    # - Read-only operation
-    # - Includes both tagged and untagged images
+    # - Lists all locally stored Docker images
+    # - Provides detailed image metadata and statistics
+    # - Shows image sizes and storage usage
+    # - Displays repository tags and digests
+    # - Includes creation timestamps and labels
+    # - Reports container usage counts
     #
-    # == Image Information Included
+    # == Security Considerations
     #
-    # The response typically includes:
-    # - **Image ID**: Unique identifier for the image
-    # - **Repository Tags**: All tags associated with the image
-    # - **Size**: Virtual and actual size of the image
-    # - **Created**: Timestamp when image was created
-    # - **Parent ID**: Base image information
-    # - **RepoDigests**: Content-addressable identifiers
+    # This tool provides information that could be useful for:
+    # - **System Analysis**: Reveals installed software and versions
+    # - **Vulnerability Assessment**: Shows potential attack surfaces
+    # - **Resource Planning**: Exposes storage usage patterns
     #
-    # == Security Considerations
+    # Monitor access to this tool in production environments.
     #
-    # This is a read-only operation that reveals system information:
-    # - Exposes available images and versions
-    # - May reveal internal application details
-    # - Shows image sources and repositories
-    # - Could aid in reconnaissance activities
+    # == Return Format
     #
-    # While generally safe, consider access control:
-    # - Limit exposure of image inventory
-    # - Be cautious with sensitive image names
-    # - Monitor for unauthorized image access attempts
+    # Returns an array of image objects with comprehensive metadata:
+    # - Repository tags and digests
+    # - Image sizes and virtual sizes
+    # - Creation timestamps
+    # - Container usage counts
+    # - Labels and annotations
+    # - Parent-child relationships
     #
     # == Example Usage
     #
-    #   # List all images
-    #   ListImages.call(server_context: context)
+    #   images = ListImages.call(server_context: context)
+    #   images.each do |image|
+    #     puts "#{image['RepoTags']}: #{image['Size']} bytes"
+    #   end
     #
-    # @example Usage in container management
-    #   # Get available images before container creation
-    #   images_response = ListImages.call(server_context: context)
-    #   # Use image information to select appropriate base images
-    #
-    # @see PullImage
-    # @see BuildImage
-    # @see Docker::Image.all
+    # @see ::Docker::Image.all
     # @since 0.1.0
-    class ListImages < RubyLLM::Tool
+    LIST_IMAGES_DEFINITION = ToolForge.define(:list_images) do
       description 'List Docker images'
 
-      # List all Docker images available on the local system.
-      #
-      # This method retrieves information about all Docker images stored
-      # locally, including both tagged and untagged images. The information
-      # includes comprehensive metadata for each image.
-      #
-      # @param args [Array] variable arguments (unused but accepted for compatibility)
-      #
-      # @return [RubyLLM::Tool::Response] comprehensive image information
-      #
-      # @example List all local images
-      #   response = ListImages.call
-      #   # Returns detailed info for all local Docker images
-      #
-      # @see Docker::Image.all
-      def execute
-        ::Docker::Image.all.map(&:info).to_s
+      execute do
+        ::Docker::Image.all.map(&:info)
       end
     end
+
+    ListImages = LIST_IMAGES_DEFINITION.to_ruby_llm_tool
   end
 end