train-k8s-container-mitre 2.0.0

data/lib/train-k8s-container/platform.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'shell_detector'
+
+module TrainPlugins
+  module K8sContainer
+    # Platform detection module for k8s-container transport
+    # Uses Train's built-in platform detection to identify the actual OS
+    # inside the container (e.g., ubuntu, alpine, centos) rather than
+    # returning a generic 'k8s-container' platform.
+    #
+    # Additionally adds 'kubernetes' and 'container' to the family hierarchy
+    # so users can check platform.kubernetes? and platform.container? to know
+    # they are running inside a Kubernetes container.
+    module Platform
+      # Detect platform inside the container using Train's standard detection
+      # This allows InSpec resources to work properly by knowing the actual OS
+      def platform
+        return @platform if @platform
+
+        # Use Train's built-in platform detection scanner
+        # This reads /etc/os-release, /etc/redhat-release, etc. to detect the OS
+        # Train raises PlatformDetectionFailed if it can't detect the platform
+        begin
+          @platform = Train::Platforms::Detect.scan(self)
+        rescue Train::PlatformDetectionFailed
+          # Fall back to unknown platform for distroless/minimal containers
+          @platform = nil
+        end
+
+        # If detection fails, fall back to a generic unix platform
+        # This handles distroless containers where OS detection may fail
+        @platform ||= fallback_platform
+
+        # Add kubernetes and container families so users can check:
+        # - platform.kubernetes? => true
+        # - platform.container? => true
+        add_k8s_families(@platform)
+
+        @platform
+      end
+
+      private
+
+      # Register kubernetes and container families with Train and add them
+      # to the detected platform's family hierarchy
+      def add_k8s_families(plat)
+        return unless plat
+
+        # Register the families with Train if not already registered
+        # These are added as top-level families (no parent)
+        Train::Platforms.family('kubernetes') unless Train::Platforms.families['kubernetes']
+        Train::Platforms.family('container') unless Train::Platforms.families['container']
+
+        # Append to the family hierarchy so kubernetes? and container? methods work
+        plat.family_hierarchy << 'kubernetes' unless plat.family_hierarchy.include?('kubernetes')
+        plat.family_hierarchy << 'container' unless plat.family_hierarchy.include?('container')
+
+        # Re-add platform methods to include the new family? methods
+        plat.add_platform_methods
+      end
+
+      # Fallback platform when Train's detection fails (distroless, minimal containers)
+      def fallback_platform
+        detect_shell # Trigger shell detection
+        container_os = @shell_detector&.container_os || :unknown
+
+        # Create a minimal platform with appropriate families
+        plat = Train::Platforms.name('unknown')
+
+        case container_os
+        when :unix
+          plat.in_family('unix')
+          plat.in_family('linux')
+        when :windows
+          plat.in_family('windows')
+        end
+
+        force_platform!('unknown', release: 'unknown')
+      end
+
+      def detect_shell
+        return unless is_a?(Train::Plugins::Transport::BaseConnection)
+
+        client = send(:kubectl_client)
+        @shell_detector ||= ShellDetector.new(client)
+        @shell_detector.detect
+      rescue NoMethodError
+        nil
+      end
+    end
+  end
+end

data/lib/train-k8s-container/pty_session.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'pty'
+require 'timeout'
+require_relative 'errors'
+require_relative 'ansi_sanitizer'
+
+module TrainPlugins
+  module K8sContainer
+    # PTY-based persistent shell session for performance optimization
+    # Maintains a single kubectl exec session instead of spawning per command
+    class PtySession
+      class PtyError < K8sContainerError; end
+      class SessionClosedError < PtyError; end
+      class CommandTimeoutError < PtyError; end
+
+      attr_reader :session_key, :reader, :writer, :pid
+
+      DEFAULT_COMMAND_TIMEOUT = 60
+      DEFAULT_SESSION_TIMEOUT = 300
+
+      def initialize(session_key:, kubectl_cmd:, shell: '/bin/bash', timeout: DEFAULT_SESSION_TIMEOUT, logger: nil)
+        @session_key = session_key
+        @kubectl_cmd = kubectl_cmd
+        @shell = shell
+        @timeout = timeout
+        @command_timeout = DEFAULT_COMMAND_TIMEOUT
+        # Logger is optional - all logging uses safe navigation (@logger&.method)
+        @logger = logger
+        @reader = nil
+        @writer = nil
+        @pid = nil
+      end
+
+      def connect
+        raise SessionClosedError, 'Session already connected' if connected?
+
+        @logger&.debug("Opening persistent session for #{@session_key} with #{@shell}")
+        @reader, @writer, @pid = PTY.spawn("#{@kubectl_cmd} -- #{@shell}")
+        @writer.sync = true
+
+        # Wait briefly for shell to be ready (no prompt expected without --tty)
+        sleep(0.1)
+
+        @logger&.debug("Persistent session established (PID: #{@pid})")
+        true
+      rescue StandardError => e
+        cleanup
+        raise PtyError, "Failed to connect: #{e.message}"
+      end
+
+      def connected?
+        @reader && @writer && !@reader.closed? && !@writer.closed?
+      end
+
+      def healthy?
+        return false unless connected?
+
+        begin
+          Process.kill(0, @pid)
+          true
+        rescue Errno::ESRCH
+          false
+        end
+      end
+
+      def execute(command)
+        raise SessionClosedError, 'Session not connected' unless connected?
+        raise SessionClosedError, 'Session unhealthy' unless healthy?
+
+        @logger&.debug("Executing in PTY session: #{command}")
+
+        # Send command with exit code marker
+        cmd_with_marker = "#{command} 2>&1 ; echo __EXIT_CODE__=$?"
+        @writer.puts(cmd_with_marker)
+        @writer.flush
+
+        # Read output until exit code marker
+        output = read_until_marker
+        parse_output(output, command)
+      rescue Errno::EIO => e
+        raise SessionClosedError, "Connection lost: #{e.message}"
+      rescue Timeout::Error
+        raise CommandTimeoutError, "Command timed out after #{@command_timeout}s"
+      end
+
+      def disconnect
+        return unless connected?
+
+        @logger&.debug("Closing PTY session #{@session_key}")
+        begin
+          @writer.puts 'exit' unless @writer.closed?
+          @writer.close unless @writer.closed?
+          @reader.close unless @reader.closed?
+          Process.wait(@pid, Process::WNOHANG)
+        rescue StandardError => e
+          @logger&.warn("Error during disconnect: #{e.message}")
+        ensure
+          @reader = nil
+          @writer = nil
+          @pid = nil
+        end
+      end
+
+      alias cleanup disconnect
+
+      private
+
+      def read_until_marker
+        buffer = +'' # Unfreeze string
+
+        Timeout.timeout(@command_timeout) do
+          while (line = @reader.gets)
+            buffer << line
+            break if line =~ /__EXIT_CODE__=(\d+)/
+          end
+        end
+
+        buffer
+      end
+
+      def parse_output(buffer, command)
+        # Strip ANSI sequences
+        cleaned = strip_ansi_sequences(buffer)
+
+        # Extract exit code
+        exit_code = 1
+        if (match = cleaned.match(/__EXIT_CODE__=(\d+)/))
+          exit_code = match[1].to_i
+        end
+
+        # Remove exit code line
+        cleaned = cleaned.gsub(/__EXIT_CODE__=\d+.*$/, '')
+
+        # Split into lines and remove command echo
+        lines = cleaned.lines
+        # Remove command wrapper echo (exact match)
+        cmd_wrapper = "#{command} 2>&1 ; echo __EXIT_CODE__=$?"
+        lines.reject! { |l| l.strip == cmd_wrapper.strip || l.strip == command.strip }
+
+        output = lines.join
+
+        # Separate stdout/stderr based on exit code
+        if exit_code.zero?
+          Train::Extras::CommandResult.new(output.strip, '', exit_code)
+        else
+          Train::Extras::CommandResult.new('', output.strip, exit_code)
+        end
+      end
+
+      def strip_ansi_sequences(text)
+        AnsiSanitizer.sanitize(text)
+      end
+    end
+  end
+end

data/lib/train-k8s-container/result_processor.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative 'ansi_sanitizer'
+require_relative 'retry_handler'
+
+module TrainPlugins
+  module K8sContainer
+    # Processes kubectl command results: validation, sanitization, exit code parsing
+    # Consolidates result processing logic for cleaner separation of concerns
+    class ResultProcessor
+      # Connection error patterns that trigger retries
+      # Note: Be specific to avoid false positives (e.g., "command not found" is NOT a connection error)
+      CONNECTION_ERROR_PATTERNS = [
+        'error dialing backend',
+        'connection refused',
+        'pods "',           # "pods \"name\" not found" - kubectl can't find pod
+        'namespaces "',     # "namespaces \"name\" not found" - kubectl can't find namespace
+        'Error from server', # kubectl API errors
+      ].freeze
+
+      # Commands that don't produce output (used for silent failure detection)
+      SILENT_COMMANDS = %w[true false touch mkdir rm sleep test].freeze
+
+      # Process a command result: validate, sanitize, and return Train::Extras::CommandResult
+      # @param result [Mixlib::ShellOut::Result] The raw command result
+      # @param command [String] The command that was executed
+      # @param logger [Logger] Logger instance for warnings
+      # @return [Train::Extras::CommandResult] Processed result
+      # @raise [RetryHandler::NetworkError] On silent failures
+      # @raise [RetryHandler::ConnectionError] On connection errors
+      def self.process(result, command, logger)
+        validate(result, command, logger)
+        sanitize(result)
+      end
+
+      # Validate result for connection errors and silent failures
+      # @param result [Object] Result with exit_status, stdout, stderr
+      # @param command [String] The command that was executed
+      # @param logger [Logger] Logger instance
+      # @raise [RetryHandler::NetworkError] On silent failures
+      # @raise [RetryHandler::ConnectionError] On connection errors
+      def self.validate(result, command, logger)
+        # Detect silent network failures (kubectl returns exit 0 despite errors)
+        if result.exit_status.zero? && result.stdout.empty? && result.stderr.empty? && should_produce_output?(command)
+          logger.warn("Silent failure detected for command: #{command}")
+          raise RetryHandler::NetworkError, 'Silent failure - no output received'
+        end
+
+        # Check for connection-related errors in stderr
+        if CONNECTION_ERROR_PATTERNS.any? { |pattern| result.stderr.include?(pattern) }
+          logger.warn("Connection error: #{result.stderr}")
+          raise RetryHandler::ConnectionError, result.stderr
+        end
+
+        result
+      end
+
+      # Sanitize result: remove ANSI sequences, parse exit codes
+      # @param result [Object] Result with stdout, stderr, exit_status
+      # @return [Train::Extras::CommandResult] Sanitized result
+      def self.sanitize(result)
+        Train::Extras::CommandResult.new(
+          AnsiSanitizer.sanitize(result.stdout),
+          AnsiSanitizer.sanitize(clean_exit_message(result.stderr)),
+          parse_exit_code(result.stderr) || result.exit_status
+        )
+      end
+
+      # Check if a command should produce output
+      # @param command [String] The command to check
+      # @return [Boolean] True if command should produce output
+      def self.should_produce_output?(command)
+        SILENT_COMMANDS.none? { |cmd| command.start_with?(cmd) }
+      end
+
+      # Parse actual exit code from kubectl's stderr message
+      # kubectl sometimes appends: "command terminated with exit code N"
+      # @param stderr [String] stderr output from kubectl
+      # @return [Integer, nil] Parsed exit code or nil
+      def self.parse_exit_code(stderr)
+        match = stderr.match(/command terminated with exit code (\d+)/)
+        match[1].to_i if match
+      end
+
+      # Clean kubectl's exit message from stderr
+      # @param stderr [String] stderr output from kubectl
+      # @return [String] Cleaned stderr without kubectl messages
+      def self.clean_exit_message(stderr)
+        # Remove kubectl's "command terminated with exit code" message
+        stderr.gsub(/command terminated with exit code \d+\n?/, '')
+      end
+    end
+  end
+end

data/lib/train-k8s-container/retry_handler.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module TrainPlugins
+  module K8sContainer
+    # Handles retry logic with exponential backoff for transient errors
+    class RetryHandler
+      MAX_RETRIES = 3
+      BASE_DELAY = 1 # seconds
+
+      class NetworkError < K8sContainerError; end
+      class ConnectionError < K8sContainerError; end
+
+      def self.with_retry(max_retries: MAX_RETRIES, logger: nil)
+        retries = 0
+
+        begin
+          yield
+        rescue NetworkError, ConnectionError => e
+          retries += 1
+          if retries <= max_retries
+            delay = BASE_DELAY * (2**(retries - 1)) # Exponential backoff
+            logger&.warn("Transient error (attempt #{retries}/#{max_retries}): #{e.message}, retrying in #{delay}s")
+            sleep(delay)
+            retry
+          else
+            logger&.error("Failed after #{max_retries} retries: #{e.message}")
+            raise Train::TransportError, "Failed after #{max_retries} retries: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/train-k8s-container/session_manager.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require_relative 'pty_session'
+
+module TrainPlugins
+  module K8sContainer
+    # Thread-safe manager for PTY session pool
+    # Maintains one session per unique namespace/pod/container combination
+    class SessionManager
+      include Singleton
+
+      def initialize
+        @sessions = {}
+        @mutex = Mutex.new
+        @cleanup_registered = false
+        register_cleanup
+      end
+
+      # Get or create a session for the given key
+      # @param session_key [String] Unique key "namespace/pod/container"
+      # @param kubectl_cmd [String] Base kubectl exec command
+      # @param shell [String] Shell to use (/bin/bash, /bin/sh, etc.)
+      # @param timeout [Integer] Session timeout in seconds
+      # @param logger [Logger] Logger instance
+      # @return [PtySession] Active session
+      def get_session(session_key, kubectl_cmd:, shell: '/bin/bash', timeout: 300, logger: nil)
+        @mutex.synchronize do
+          unless @sessions[session_key]&.healthy?
+            # Cleanup old session if exists (must be done inside mutex, not via cleanup_session)
+            if @sessions[session_key]
+              old_session = @sessions.delete(session_key)
+              old_session&.cleanup
+            end
+
+            logger&.debug("Creating new PTY session for #{session_key}")
+            @sessions[session_key] = PtySession.new(
+              session_key: session_key,
+              kubectl_cmd: kubectl_cmd,
+              shell: shell,
+              timeout: timeout,
+              logger: logger
+            )
+            @sessions[session_key].connect
+          end
+
+          @sessions[session_key]
+        end
+      rescue PtySession::PtyError
+        # Cleanup without recursive mutex (already inside synchronize block)
+        @sessions.delete(session_key)
+        raise
+      end
+
+      # Cleanup a specific session
+      # @param session_key [String] Session to cleanup
+      def cleanup_session(session_key)
+        @mutex.synchronize do
+          session = @sessions.delete(session_key)
+          session&.cleanup
+        end
+      end
+
+      # Cleanup all sessions
+      def cleanup_all
+        @mutex.synchronize do
+          @sessions.each_value(&:cleanup)
+          @sessions.clear
+        end
+      end
+
+      # Get session count (for monitoring/testing)
+      def session_count
+        @sessions.size
+      end
+
+      # Get all session keys (for monitoring/testing)
+      def session_keys
+        @sessions.keys
+      end
+
+      private
+
+      def register_cleanup
+        return if @cleanup_registered
+
+        at_exit do
+          cleanup_all
+        end
+
+        @cleanup_registered = true
+      end
+    end
+  end
+end

data/lib/train-k8s-container/shell_detector.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module TrainPlugins
+  module K8sContainer
+    # Detects available shell in container with tiered fallback
+    # Supports Unix shells (bash, sh, ash) and Windows shells (cmd, PowerShell)
+    class ShellDetector
+      UNIX_SHELLS = [
+        '/bin/bash',   # Ubuntu, Debian, RHEL, CentOS
+        '/bin/sh',     # POSIX standard, symlink in most distros
+        '/bin/ash',    # Alpine, BusyBox
+        '/bin/zsh', # Less common but possible
+      ].freeze
+
+      WINDOWS_SHELLS = [
+        'cmd.exe',           # Windows command prompt (most reliable)
+        'powershell.exe',    # PowerShell 5.1 (Windows Server)
+        'pwsh.exe', # PowerShell Core 6+
+      ].freeze
+
+      # Linux distribution family mappings based on /etc/os-release ID
+      # Maps distribution IDs to Train family names
+      LINUX_FAMILY_MAP = {
+        # Debian family
+        'debian' => 'debian',
+        'ubuntu' => 'debian',
+        'linuxmint' => 'debian',
+        'raspbian' => 'debian',
+        'kali' => 'debian',
+        # RedHat family
+        'rhel' => 'redhat',
+        'centos' => 'redhat',
+        'fedora' => 'fedora',
+        'rocky' => 'redhat',
+        'almalinux' => 'redhat',
+        'ol' => 'redhat', # Oracle Linux
+        'amzn' => 'redhat', # Amazon Linux
+        # SUSE family
+        'sles' => 'suse',
+        'opensuse' => 'suse',
+        'opensuse-leap' => 'suse',
+        'opensuse-tumbleweed' => 'suse',
+        # Alpine
+        'alpine' => 'alpine',
+        # Arch
+        'arch' => 'arch',
+        'manjaro' => 'arch',
+        # Gentoo
+        'gentoo' => 'gentoo',
+      }.freeze
+
+      def initialize(kubectl_client)
+        @kubectl_client = kubectl_client
+        @detected_shell = :not_detected
+        @container_os = :unknown
+        @linux_family = nil
+      end
+
+      def detect
+        return @detected_shell unless @detected_shell == :not_detected
+
+        # Detect container OS first (heuristic approach like train-docker)
+        detect_container_os
+
+        # Try appropriate shells based on OS
+        shells_to_try = case @container_os
+                        when :unix then UNIX_SHELLS
+                        when :windows then WINDOWS_SHELLS
+                        else UNIX_SHELLS + WINDOWS_SHELLS # Try both if unknown
+                        end
+
+        shells_to_try.each do |shell_path|
+          if shell_available?(shell_path)
+            @detected_shell = shell_path
+            return @detected_shell
+          end
+        end
+
+        @detected_shell = nil # No shell available (distroless)
+      end
+
+      def shell_available?(shell_path)
+        if self.class.windows_shell?(shell_path)
+          windows_shell_available?(shell_path)
+        else
+          unix_shell_available?(shell_path)
+        end
+      rescue StandardError
+        false
+      end
+
+      # Check if shell is a Windows shell (ends with .exe)
+      # @param shell_path [String] Path or name of shell
+      # @return [Boolean] True if Windows shell
+      def self.windows_shell?(shell_path)
+        shell_path.end_with?('.exe')
+      end
+
+      def unix_shell_available?(shell_path)
+        # Use test -x to check if shell exists and is executable
+        result = @kubectl_client.execute_raw("test -x #{shell_path} && echo OK")
+        result.stdout.strip == 'OK' && result.exit_status.zero?
+      end
+
+      def windows_shell_available?(shell_path)
+        # For Windows, use 'where' command to check if shell exists
+        result = @kubectl_client.execute_raw("where #{shell_path}")
+        result.exit_status.zero? && !result.stdout.empty?
+      end
+
+      def shell_type
+        case @detected_shell
+        when '/bin/bash' then :bash
+        when '/bin/sh' then :sh
+        when '/bin/ash' then :ash
+        when '/bin/zsh' then :zsh
+        when 'cmd.exe' then :cmd
+        when 'powershell.exe' then :powershell
+        when 'pwsh.exe' then :pwsh
+        when nil then :none
+        else :unknown
+        end
+      end
+
+      attr_reader :container_os, :linux_family
+
+      def windows_container?
+        @container_os == :windows
+      end
+
+      def unix_container?
+        @container_os == :unix
+      end
+
+      # Check if container is running Linux (subset of Unix)
+      def linux_container?
+        @container_os == :unix && !@linux_family.nil?
+      end
+
+      private
+
+      def detect_container_os
+        # Try a simple Unix command - fails on Windows with specific error pattern
+        # Following train-docker's heuristic approach
+        result = @kubectl_client.execute_raw('echo test')
+
+        @container_os = if result.exit_status.zero? && result.stdout.strip == 'test'
+                          # Unix container (echo works normally)
+                          # Also detect Linux family for more specific platform matching
+                          detect_linux_family
+                          :unix
+                        elsif result.stderr.match?(/not recognized|not found|command not found/i)
+                          # Likely Windows (Unix commands fail)
+                          :windows
+                        else
+                          # Unknown - will try both shell types
+                          :unknown
+                        end
+      rescue StandardError
+        @container_os = :unknown
+      end
+
+      # Detect Linux distribution family from /etc/os-release
+      # This enables InSpec resources that require os.linux? to work
+      def detect_linux_family
+        # Try to read /etc/os-release which is standard on modern Linux
+        result = @kubectl_client.execute_raw('cat /etc/os-release 2>/dev/null')
+        return unless result.exit_status.zero?
+
+        # Parse the ID field from os-release
+        os_release = result.stdout
+        id_match = os_release.match(/^ID=["']?([^"'\n]+)["']?$/i)
+        return unless id_match
+
+        distro_id = id_match[1].downcase.strip
+        @linux_family = LINUX_FAMILY_MAP[distro_id]
+
+        # If no exact match, try ID_LIKE for derivative distros
+        return if @linux_family
+
+        id_like_match = os_release.match(/^ID_LIKE=["']?([^"'\n]+)["']?$/i)
+        return unless id_like_match
+
+        # ID_LIKE can have multiple values, try each one
+        id_like_match[1].split.each do |like_id|
+          family = LINUX_FAMILY_MAP[like_id.downcase.strip]
+          if family
+            @linux_family = family
+            break
+          end
+        end
+      rescue StandardError
+        # Ignore errors - linux_family will remain nil (defaults to generic linux)
+        nil
+      end
+    end
+  end
+end