ruby_llm-docker 0.0.1 → 0.2.5

data/lib/ruby_llm/docker/create_volume.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for creating Docker volumes.
+    #
+    # This tool provides the ability to create persistent Docker volumes for
+    # data storage that survives container lifecycle events. Volumes are the
+    # preferred mechanism for persisting data generated and used by Docker
+    # containers.
+    #
+    # == Features
+    #
+    # - Create named persistent volumes
+    # - Support for different volume drivers
+    # - Comprehensive error handling
+    # - Duplicate name detection
+    # - Flexible storage configuration
+    #
+    # == Volume Drivers
+    #
+    # Docker supports various volume drivers:
+    # - **local**: Default driver using host filesystem
+    # - **nfs**: Network File System for shared storage
+    # - **cifs**: Common Internet File System
+    # - **rexray**: External storage orchestration
+    # - **Custom**: Third-party volume drivers
+    #
+    # == Persistence Benefits
+    #
+    # Docker volumes provide several advantages:
+    # - **Data Persistence**: Survive container deletion and recreation
+    # - **Performance**: Better performance than bind mounts on Docker Desktop
+    # - **Portability**: Can be moved between containers and hosts
+    # - **Backup**: Easier to backup and restore than container filesystems
+    # - **Sharing**: Can be shared between multiple containers
+    # - **Management**: Managed by Docker daemon with proper lifecycle
+    #
+    # == Security Considerations
+    #
+    # Volume creation affects data security:
+    # - **Data Isolation**: Volumes provide isolation between containers
+    # - **Access Control**: Volume permissions affect data access
+    # - **Storage Location**: Local volumes stored on host filesystem
+    # - **Shared Access**: Multiple containers can access the same volume
+    #
+    # Security implications:
+    # - Volumes persist data beyond container lifecycle
+    # - Volume names may reveal application details
+    # - Shared volumes can leak data between containers
+    # - Storage driver choice affects security properties
+    #
+    # Best practices:
+    # - Use descriptive but not sensitive volume names
+    # - Implement proper volume access controls
+    # - Regular backup of critical volume data
+    # - Monitor volume usage and access patterns
+    # - Choose appropriate drivers for security requirements
+    #
+    # == Example Usage
+    #
+    #   # Create basic local volume
+    #   CreateVolume.call(
+    #     server_context: context,
+    #     name: "app-data"
+    #   )
+    #
+    #   # Create volume with specific driver
+    #   CreateVolume.call(
+    #     server_context: context,
+    #     name: "shared-storage",
+    #     driver: "nfs"
+    #   )
+    #
+    # @see ListVolumes
+    # @see RemoveVolume
+    # @see Docker::Volume.create
+    # @since 0.1.0
+    class CreateVolume < RubyLLM::Tool
+      description 'Create a Docker volume'
+
+      param :name, type: :string, desc: 'Name of the volume'
+      param :driver, type: :string, desc: 'Driver to use (default: local)', required: false
+
+      # Create a new Docker volume for persistent data storage.
+      #
+      # This method creates a named Docker volume that can be used by containers
+      # for persistent data storage. The volume will survive container deletion
+      # and can be shared between multiple containers.
+      #
+      # @param name [String] name for the new volume
+      # @param server_context [Object] RubyLLM context (unused but required)
+      # @param driver [String] volume driver to use (default: "local")
+      #
+      # @return [RubyLLM::Tool::Response] volume creation results
+      #
+      # @raise [Docker::Error::ConflictError] if volume name already exists
+      # @raise [StandardError] for other volume creation failures
+      #
+      # @example Create application data volume
+      #   response = CreateVolume.call(
+      #     server_context: context,
+      #     name: "webapp-data"
+      #   )
+      #
+      # @example Create NFS volume
+      #   response = tool.execute(
+      #     name: "shared-files",
+      #     driver: "nfs"
+      #   )
+      #
+      # @see Docker::Volume.create
+      def execute(name:, driver: 'local')
+        options = {
+          'Name' => name,
+          'Driver' => driver
+        }
+
+        ::Docker::Volume.create(name, options)
+
+        "Volume #{name} created successfully"
+      rescue ::Docker::Error::ConflictError
+        "Volume #{name} already exists"
+      rescue StandardError => e
+        "Error creating volume: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/exec_container.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for executing commands inside running 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.
+    #
+    # == ⚠️ CRITICAL SECURITY WARNING ⚠️
+    #
+    # 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
+    #
+    # 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
+    #
+    # == Features
+    #
+    # - 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
+    #
+    # == Example Usage
+    #
+    #   # Simple command execution
+    #   ExecContainer.call(
+    #     server_context: context,
+    #     id: "my-container",
+    #     cmd: "ls -la /app"
+    #   )
+    #
+    #   # Advanced execution with custom environment
+    #   ExecContainer.call(
+    #     server_context: context,
+    #     id: "web-server",
+    #     cmd: "python manage.py migrate",
+    #     working_dir: "/app",
+    #     user: "appuser",
+    #     env: ["DJANGO_ENV=production", "DEBUG=false"],
+    #     timeout: 120
+    #   )
+    #
+    # @see Docker::Container#exec
+    # @since 0.1.0
+    class ExecContainer < RubyLLM::Tool
+      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)
+        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
+
+        # 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
+  end
+end

data/lib/ruby_llm/docker/fetch_container_logs.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for retrieving 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.
+    #
+    # == 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
+    #
+    # == 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
+    #
+    # 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
+    #
+    # == Example Usage
+    #
+    #   # Get all logs
+    #   FetchContainerLogs.call(
+    #     server_context: context,
+    #     id: "web-server"
+    #   )
+    #
+    #   # Get recent logs with timestamps
+    #   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
+    #   )
+    #
+    # @see ExecContainer
+    # @see Docker::Container#logs
+    # @since 0.1.0
+    class FetchContainerLogs < RubyLLM::Tool
+      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
+
+      # 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)
+        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
+  end
+end

data/lib/ruby_llm/docker/list_containers.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM 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.
+    #
+    # == Security Notes
+    #
+    # 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.
+    #
+    # == Example Usage
+    #
+    #   # List all containers (default behavior)
+    #   ListContainers.call(server_context: context)
+    #
+    #   # Explicitly request all containers
+    #   ListContainers.call(server_context: context, all: true)
+    #
+    # @see Docker::Container.all
+    # @since 0.1.0
+    class ListContainers < RubyLLM::Tool
+      description 'List Docker containers'
+
+      param :all, type: :boolean, desc: 'Show all containers (default shows all containers including stopped ones)',
+                  required: false
+
+      # 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
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/list_images.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM 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.
+    #
+    # == Features
+    #
+    # - List all local Docker images
+    # - Comprehensive image metadata
+    # - No configuration required
+    # - Read-only operation
+    # - Includes both tagged and untagged images
+    #
+    # == Image Information Included
+    #
+    # 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
+    #
+    # == Security Considerations
+    #
+    # 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
+    #
+    # While generally safe, consider access control:
+    # - Limit exposure of image inventory
+    # - Be cautious with sensitive image names
+    # - Monitor for unauthorized image access attempts
+    #
+    # == Example Usage
+    #
+    #   # List all images
+    #   ListImages.call(server_context: context)
+    #
+    # @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
+    # @since 0.1.0
+    class ListImages < RubyLLM::Tool
+      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
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/list_networks.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for listing Docker networks.
+    #
+    # This tool provides functionality to list all Docker networks available on
+    # the system, including built-in networks (bridge, host, none) and custom
+    # user-defined networks. It returns comprehensive information about network
+    # configuration, drivers, and connected containers.
+    #
+    # == Features
+    #
+    # - List all Docker networks on the system
+    # - Comprehensive network metadata
+    # - No configuration required
+    # - Read-only operation
+    # - Includes built-in and custom networks
+    #
+    # == Network Information Included
+    #
+    # The response typically includes:
+    # - **Network ID**: Unique identifier for the network
+    # - **Name**: Human-readable network name
+    # - **Driver**: Network driver (bridge, host, overlay, etc.)
+    # - **Scope**: Network scope (local, global, swarm)
+    # - **IPAM**: IP Address Management configuration
+    # - **Connected Containers**: Containers attached to the network
+    # - **Options**: Driver-specific configuration options
+    #
+    # == Security Considerations
+    #
+    # This is a read-only operation that reveals network topology:
+    # - Exposes network architecture and segmentation
+    # - Shows container connectivity patterns
+    # - May reveal internal network design
+    # - Could aid in network reconnaissance
+    #
+    # While generally safe, consider access control:
+    # - Limit exposure of network topology information
+    # - Be cautious with sensitive network names
+    # - Monitor for unauthorized network discovery
+    # - Consider network isolation requirements
+    #
+    # == Example Usage
+    #
+    #   # List all networks
+    #   ListNetworks.call(server_context: context)
+    #
+    # @example Usage in network management
+    #   # Get available networks before container creation
+    #   networks_response = ListNetworks.call(server_context: context)
+    #   # Use network information to select appropriate networks
+    #
+    # @see CreateNetwork
+    # @see RemoveNetwork
+    # @see Docker::Network.all
+    # @since 0.1.0
+    class ListNetworks < RubyLLM::Tool
+      description 'List Docker networks'
+
+      # List all Docker networks available on the system.
+      #
+      # This method retrieves information about all Docker networks, including
+      # both system-created networks (bridge, host, none) and user-defined
+      # custom networks. The information includes comprehensive metadata for
+      # each network.
+      #
+      # @return [String] comprehensive network information
+      #
+      # @example List all networks
+      #   response = tool.execute
+      #   # Returns detailed info for all Docker networks
+      #
+      # @see Docker::Network.all
+      def execute
+        ::Docker::Network.all.map(&:info).to_s
+      end
+    end
+  end
+end