ruby_llm-docker 0.0.1 → 0.3.0

data/lib/ruby_llm/docker/exec_container.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for executing commands inside Docker containers.
+    #
+    # 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.
+    #
+    # == Features
+    #
+    # - 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
+    #
+    # == Security Considerations
+    #
+    # **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
+    #
+    # == 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
+    #
+    #   # Basic command execution
+    #   response = ExecContainer.call(
+    #     server_context: context,
+    #     id: "web-container",
+    #     cmd: "nginx -t"
+    #   )
+    #
+    #   # Advanced execution with environment
+    #   response = ExecContainer.call(
+    #     server_context: context,
+    #     id: "app-container",
+    #     cmd: "bundle exec rails console",
+    #     working_dir: "/app",
+    #     user: "rails",
+    #     env: "RAILS_ENV=production,DEBUG=true",
+    #     timeout: 300
+    #   )
+    #
+    # @see ::Docker::Container#exec
+    # @since 0.1.0
+    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,
+            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
+        cmd_array = Shellwords.split(cmd)
+
+        # Parse environment variables from comma-separated string to array
+        env.split(',').map(&:strip) if env && !env.empty?
+
+        # Execute the command
+        stdout_data = []
+        stderr_data = []
+        exit_code = nil
+
+        begin
+          # Use container.exec which returns [stdout, stderr, exit_code]
+          result = if stdin
+                     container.exec(cmd_array, stdin: StringIO.new(stdin), wait: timeout)
+                   else
+                     container.exec(cmd_array, wait: timeout)
+                   end
+
+          stdout_data = result[0]
+          stderr_data = result[1]
+          exit_code = result[2]
+        rescue ::Docker::Error::TimeoutError
+          return "Command execution timed out after #{timeout} seconds"
+        end
+
+        # Format response
+        response_text = "Command executed in container #{id}\n"
+        response_text += "Exit code: #{exit_code}\n\n"
+
+        if stdout_data && !stdout_data.empty?
+          stdout_str = stdout_data.join
+          response_text += "STDOUT:\n#{stdout_str}\n" unless stdout_str.strip.empty?
+        end
+
+        if stderr_data && !stderr_data.empty?
+          stderr_str = stderr_data.join
+          response_text += "\nSTDERR:\n#{stderr_str}\n" unless stderr_str.strip.empty?
+        end
+
+        response_text.strip
+      rescue ::Docker::Error::NotFoundError
+        "Container #{id} not found"
+      rescue StandardError => e
+        "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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for fetching Docker container logs.
+    #
+    # 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
+    #
+    # - 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 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.
+    #
+    # == 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
+    #
+    #   # Fetch all logs
+    #   response = FetchContainerLogs.call(
+    #     server_context: context,
+    #     id: "web-server"
+    #   )
+    #
+    #   # Fetch recent errors with timestamps
+    #   response = FetchContainerLogs.call(
+    #     server_context: context,
+    #     id: "app-container",
+    #     stdout: false,
+    #     stderr: true,
+    #     timestamps: true,
+    #     tail: 100
+    #   )
+    #
+    # @see ::Docker::Container#logs
+    # @since 0.1.0
+    FETCH_CONTAINER_LOGS_DEFINITION = ToolForge.define(:fetch_container_logs) do
+      description 'Fetch Docker container logs'
+
+      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
+
+      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 = {
+          stdout: stdout,
+          stderr: stderr,
+          timestamps: timestamps
+        }
+        options[:tail] = tail if tail
+
+        container.logs(options)
+      rescue ::Docker::Error::NotFoundError
+        "Container #{id} not found"
+      rescue StandardError => e
+        "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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for listing Docker containers.
+    #
+    # 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.
+    #
+    # == Features
+    #
+    # - 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
+    #
+    # == 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
+    #
+    # Use with appropriate access controls in production environments.
+    #
+    # == Return Format
+    #
+    # 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
+    LIST_CONTAINERS_DEFINITION = ToolForge.define(:list_containers) do
+      description 'List Docker containers'
+
+      param :all,
+            type: :boolean,
+            description: 'Show all containers (default shows all containers including stopped ones)',
+            required: false,
+            default: true
+
+      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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for listing Docker images.
+    #
+    # 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
+    #
+    # - 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
+    #
+    # == Security Considerations
+    #
+    # 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
+    #
+    # Monitor access to this tool in production environments.
+    #
+    # == Return Format
+    #
+    # 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
+    #
+    #   images = ListImages.call(server_context: context)
+    #   images.each do |image|
+    #     puts "#{image['RepoTags']}: #{image['Size']} bytes"
+    #   end
+    #
+    # @see ::Docker::Image.all
+    # @since 0.1.0
+    LIST_IMAGES_DEFINITION = ToolForge.define(:list_images) do
+      description 'List Docker images'
+
+      execute do
+        ::Docker::Image.all.map(&:info)
+      end
+    end
+
+    ListImages = LIST_IMAGES_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/list_networks.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for listing Docker networks.
+    #
+    # This tool provides comprehensive information about all Docker networks
+    # configured on the system. It returns detailed network configuration
+    # including IPAM settings, connected containers, and network drivers.
+    #
+    # == Features
+    #
+    # - Lists all Docker networks (built-in and custom)
+    # - Provides detailed network configuration
+    # - Shows IPAM (IP Address Management) settings
+    # - Displays connected containers
+    # - Includes driver information and options
+    # - Reports network scope and capabilities
+    #
+    # == Security Considerations
+    #
+    # Network information can be sensitive as it reveals:
+    # - **Network Topology**: Internal network architecture
+    # - **IP Addressing**: Subnet configurations and ranges
+    # - **Container Connectivity**: Service interconnections
+    # - **Network Isolation**: Security boundary configurations
+    #
+    # Restrict access to this tool in production environments.
+    #
+    # == Return Format
+    #
+    # Returns an array of network objects with comprehensive metadata:
+    # - Network names and IDs
+    # - Driver types and configurations
+    # - IPAM settings and subnet information
+    # - Connected container details
+    # - Network options and labels
+    # - Scope and capability flags
+    #
+    # == Example Usage
+    #
+    #   networks = ListNetworks.call(server_context: context)
+    #   networks.each do |network|
+    #     puts "#{network['Name']}: #{network['Driver']}"
+    #   end
+    #
+    # @see ::Docker::Network.all
+    # @since 0.1.0
+    LIST_NETWORKS_DEFINITION = ToolForge.define(:list_networks) do
+      description 'List Docker networks'
+
+      execute do
+        ::Docker::Network.all.map(&:info)
+      end
+    end
+
+    ListNetworks = LIST_NETWORKS_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/list_volumes.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for listing Docker volumes.
+    #
+    # This tool provides comprehensive information about all Docker volumes
+    # configured on the system. It returns detailed volume metadata including
+    # mount points, drivers, usage statistics, and associated containers.
+    #
+    # == Features
+    #
+    # - Lists all Docker volumes (named and anonymous)
+    # - Provides detailed volume metadata
+    # - Shows mount points and storage locations
+    # - Displays driver information and options
+    # - Includes creation timestamps and labels
+    # - Reports volume scope and capabilities
+    #
+    # == Security Considerations
+    #
+    # Volume information can reveal sensitive details about:
+    # - **Data Storage**: Persistent data locations and structures
+    # - **File System Access**: Mount points and storage paths
+    # - **Container Dependencies**: Volume usage patterns
+    # - **Data Persistence**: Backup and recovery points
+    #
+    # Monitor access to this tool and implement appropriate controls.
+    #
+    # == Return Format
+    #
+    # Returns an array of volume objects with comprehensive metadata:
+    # - Volume names and mount points
+    # - Driver types and configurations
+    # - Creation timestamps
+    # - Labels and options
+    # - Scope information
+    # - Storage usage details
+    #
+    # == Example Usage
+    #
+    #   volumes = ListVolumes.call(server_context: context)
+    #   volumes.each do |volume|
+    #     puts "#{volume['Name']}: #{volume['Mountpoint']}"
+    #   end
+    #
+    # @see ::Docker::Volume.all
+    # @since 0.1.0
+    LIST_VOLUMES_DEFINITION = ToolForge.define(:list_volumes) do
+      description 'List Docker volumes'
+
+      execute do
+        ::Docker::Volume.all.map(&:info)
+      end
+    end
+
+    ListVolumes = LIST_VOLUMES_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/pull_image.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for pulling Docker images from registries.
+    #
+    # This tool provides the ability to download Docker images from Docker
+    # registries (like Docker Hub) to the local system. It supports flexible
+    # tag specification and handles various image naming conventions.
+    #
+    # == Features
+    #
+    # - Pull images from any accessible Docker registry
+    # - Flexible tag specification (explicit or default)
+    # - Support for official and user repositories
+    # - Automatic latest tag handling
+    # - Comprehensive error handling
+    # - Progress tracking through Docker daemon
+    #
+    # == Security Considerations
+    #
+    # Pulling images can introduce security risks:
+    # - **Malicious Images**: Images may contain malware or backdoors
+    # - **Vulnerable Software**: Images may have known security vulnerabilities
+    # - **Untrusted Sources**: Images from unknown publishers may be compromised
+    # - **Supply Chain Attacks**: Legitimate-looking images may be malicious
+    # - **Resource Consumption**: Large images can consume significant disk space
+    #
+    # **Security Recommendations**:
+    # - Only pull images from trusted registries and publishers
+    # - Verify image signatures when available
+    # - Scan pulled images for vulnerabilities
+    # - Use specific tags rather than 'latest'
+    # - Monitor registry access and authentication
+    # - Regularly update and patch images
+    #
+    # == Tag Handling
+    #
+    # The tool handles tags intelligently:
+    # - If image includes tag (e.g., "nginx:1.21"), use as specified
+    # - If separate tag provided, append to image name
+    # - If no tag specified, default to "latest"
+    # - Supports all Docker tag conventions
+    #
+    # == Parameters
+    #
+    # - **from_image**: Image name to pull (required, e.g., "ubuntu" or "ubuntu:22.04")
+    # - **tag**: Tag to pull (optional, defaults to "latest" if not specified in from_image)
+    #
+    # == Example Usage
+    #
+    #   # Pull latest version
+    #   response = PullImage.call(
+    #     server_context: context,
+    #     from_image: "nginx"
+    #   )
+    #
+    #   # Pull specific version
+    #   response = PullImage.call(
+    #     server_context: context,
+    #     from_image: "postgres",
+    #     tag: "13.8"
+    #   )
+    #
+    # @see ::Docker::Image.create
+    # @since 0.1.0
+    PULL_IMAGE_DEFINITION = ToolForge.define(:pull_image) do
+      description 'Pull a Docker image'
+
+      param :from_image,
+            type: :string,
+            description: 'Image name to pull (e.g., "ubuntu" or "ubuntu:22.04")'
+
+      param :tag,
+            type: :string,
+            description: 'Tag to pull (optional, defaults to "latest" if not specified in from_image)',
+            required: false
+
+      execute do |from_image:, tag: nil|
+        # If tag is provided separately, append it to from_image
+        # If from_image already has a tag (contains :), use as-is
+        # Otherwise default to :latest
+        image_with_tag = if tag
+                           "#{from_image}:#{tag}"
+                         elsif from_image.include?(':')
+                           from_image
+                         else
+                           "#{from_image}:latest"
+                         end
+
+        image = ::Docker::Image.create('fromImage' => image_with_tag)
+
+        "Image #{image_with_tag} pulled successfully. ID: #{image.id}"
+      rescue ::Docker::Error::NotFoundError
+        "Image #{image_with_tag} not found"
+      rescue StandardError => e
+        "Error pulling image: #{e.message}"
+      end
+    end
+
+    PullImage = PULL_IMAGE_DEFINITION.to_ruby_llm_tool
+  end
+end