train-k8s-container-mitre 2.0.0

data/SECURITY.md

@@ -0,0 +1,100 @@
+# Security Policy
+
+## Reporting Security Issues
+
+The MITRE SAF team takes security seriously. If you discover a security vulnerability in the train-k8s-container plugin, please report it responsibly.
+
+### Contact Information
+
+- **Email**: [saf-security@mitre.org](mailto:saf-security@mitre.org)
+- **GitHub**: Use the [Security tab](https://github.com/mitre/train-k8s-container/security) to report vulnerabilities privately
+
+### What to Include
+
+When reporting security issues, please provide:
+
+1. **Description** of the vulnerability
+2. **Steps to reproduce** the issue
+3. **Potential impact** assessment
+4. **Suggested fix** (if you have one)
+
+### Response Timeline
+
+- **Acknowledgment**: Within 48 hours
+- **Initial Assessment**: Within 7 days
+- **Fix Timeline**: Varies by severity (critical: 7-14 days, high: 14-30 days)
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 2.x.x   | Yes       |
+| < 2.0   | No        |
+
+## Security Best Practices
+
+### For Users
+
+- **Keep Updated**: Use the latest version of the plugin
+- **Secure Credentials**: Never commit kubeconfig files to version control
+- **Use RBAC**: Configure minimal Kubernetes RBAC permissions for scanner service accounts
+- **Network Security**: Use network policies to restrict pod-to-pod communication
+
+### For Contributors
+
+- **Dependency Scanning**: Run `bundle audit` before submitting PRs
+- **Credential Handling**: Never log or expose credentials in code
+- **Input Validation**: Sanitize all user inputs
+- **Test Security**: Include security tests for new features
+
+## Security Testing
+
+The plugin includes comprehensive security testing:
+
+```bash
+# Check for vulnerable dependencies
+bundle exec bundle-audit check --update
+
+# Run security workflow locally
+bundle exec rake security
+```
+
+## Security Measures
+
+This project implements comprehensive automated security scanning:
+
+### Secret Scanning
+- **Tool**: TruffleHog OSS
+- **Frequency**: Every push, pull request, and weekly
+- **Coverage**: 800+ secret types (API keys, tokens, credentials)
+
+### Vulnerability Scanning
+- **Tool**: bundler-audit
+- **Frequency**: Every push, pull request, and weekly
+- **Database**: Ruby Advisory Database (continuously updated)
+
+### Software Bill of Materials (SBOM)
+- **Tool**: CycloneDX Ruby
+- **Format**: JSON
+- **Retention**: 90 days in GitHub artifacts
+- **Standard**: OWASP CycloneDX specification
+
+## Known Security Considerations
+
+### kubectl Execution
+This plugin executes commands via `kubectl exec`. Security considerations:
+
+- **Command injection**: Commands are sanitized with `Shellwords.escape`
+- **ANSI sequences**: Output is sanitized to prevent terminal escape attacks (CVE-2021-25743)
+- **Credentials**: Uses kubeconfig authentication (same security as kubectl)
+- **RFC 1123 validation**: Pod and container names are validated
+
+### Container Access
+- Requires existing kubectl access to target namespace/pod
+- Does not bypass Kubernetes RBAC
+- Runs commands with container's default user permissions
+
+## Contact
+
+- **Security issues**: [saf-security@mitre.org](mailto:saf-security@mitre.org)
+- **General questions**: [saf@mitre.org](mailto:saf@mitre.org) or open a GitHub issue

data/VERSION

@@ -0,0 +1 @@
+2.0.0

data/cliff.toml

@@ -0,0 +1,80 @@
+# git-cliff configuration for train-k8s-container
+# See: https://git-cliff.org/docs/configuration
+
+[changelog]
+# changelog header
+header = """
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+"""
+# template for the changelog body
+body = """
+{% if version %}\
+    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}\
+    ## [Unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | striptags | trim | upper_first }}
+    {% for commit in commits %}
+        - {% if commit.scope %}**{{ commit.scope }}**: {% endif %}{{ commit.message | upper_first }}\
+    {% endfor %}
+{% endfor %}\n
+"""
+# remove the leading and trailing whitespace from the template
+trim = true
+# changelog footer
+footer = """
+<!-- generated by git-cliff -->
+"""
+
+[git]
+# parse the commits based on https://www.conventionalcommits.org
+conventional_commits = true
+# filter out the commits that are not conventional
+filter_unconventional = false
+# process each line of a commit as an individual commit
+split_commits = false
+# regex for preprocessing the commit messages
+commit_preprocessors = [
+    # Extract issue numbers from commit messages
+    { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/mitre/train-k8s-container/issues/${2}))"},
+]
+# regex for parsing and grouping commits
+commit_parsers = [
+    { message = "^feat", group = "Added" },
+    { message = "^fix", group = "Fixed" },
+    { message = "^doc", group = "Documentation" },
+    { message = "^perf", group = "Performance" },
+    { message = "^refactor", group = "Refactor" },
+    { message = "^style", group = "Styling" },
+    { message = "^test", group = "Testing" },
+    { message = "^chore\\(release\\): prepare for", skip = true },
+    { message = "^chore\\(deps\\)", skip = true },
+    { message = "^chore\\(pr\\)", skip = true },
+    { message = "^chore\\(pull\\)", skip = true },
+    { message = "^chore|^ci", group = "Miscellaneous Tasks" },
+    { body = ".*security", group = "Security" },
+    { message = "^revert", group = "Revert" },
+]
+# protect breaking changes from being skipped due to matching a skipping commit_parser
+protect_breaking_commits = false
+# filter out the commits that are not matched by commit parsers
+filter_commits = false
+# glob pattern for matching git tags
+tag_pattern = "v[0-9]*"
+# regex for skipping tags
+skip_tags = ""
+# regex for ignoring tags
+ignore_tags = ""
+# sort the tags topologically
+topo_order = false
+# sort the commits inside sections by oldest/newest order
+sort_commits = "oldest"
+# limit the number of commits included in the changelog.
+# limit_commits = 42

data/docs/README.md

@@ -0,0 +1 @@
+# Docs for train-k8s-container

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module TrainPlugins
+  module K8sContainer
+    # ANSI sequence sanitization module
+    # Removes ANSI escape sequences and normalizes line endings
+    # Addresses CVE-2021-25743 (terminal escape sequence injection)
+    module AnsiSanitizer
+      # Pre-compiled regexes for performance (frozen constants)
+      CSI_REGEX = /\e\[([;\d]+)?[A-Za-z]/
+      OSC_REGEX = /\e\][^\a]*\a/
+      CURSOR_REGEX = /\e\[A|\e\[C|\e\[K/
+      LINE_ENDING_REGEX = /\r\n?/
+
+      # Remove ANSI escape sequences and normalize line endings
+      # @param text [String] The text to sanitize
+      # @return [String] Sanitized text with ANSI sequences removed
+      def self.sanitize(text)
+        return '' if text.nil? || text.empty?
+
+        # Use single string mutation instead of chaining to reduce allocations
+        result = text.dup
+        result.gsub!(CSI_REGEX, '') # CSI sequences (colors, cursor movement)
+        result.gsub!(OSC_REGEX, '') # OSC sequences (terminal title, etc)
+        result.gsub!(CURSOR_REGEX, '') # Cursor movement (up, forward, erase)
+        result.gsub!(LINE_ENDING_REGEX, "\n") # Normalize all line endings
+        result
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'train'
+require 'train/plugins'
+require 'train/file/remote/linux'
+require 'train/file/remote/windows'
+require_relative 'platform'
+require_relative 'kubernetes_name_validator'
+
+module TrainPlugins
+  module K8sContainer
+    # Connection class for Kubernetes container transport
+    # Executes commands inside containers via kubectl exec
+    class Connection < Train::Plugins::Transport::BaseConnection
+      include TrainPlugins::K8sContainer::Platform
+
+      # URI format: k8s-container://<namespace>/<pod>/<container_name>
+      # @example k8s-container://default/shell-demo/nginx
+
+      def initialize(options)
+        super
+
+        # Parse URI path format (InSpec converts k8s-container://target to path="//target"):
+        # - k8s-container://pod/container → path="//pod/container" (default namespace)
+        # - k8s-container://namespace/pod/container → path="//namespace/pod/container"
+        path_parts = options[:path]&.split('/')&.reject(&:empty?)
+
+        if path_parts&.length == 2
+          # Format: //pod/container (default namespace)
+          @namespace = options[:namespace] || TrainPlugins::K8sContainer::KubectlExecClient::DEFAULT_NAMESPACE
+          @pod = options[:pod] || path_parts.first
+          @container_name = options[:container_name] || path_parts[1]
+        elsif path_parts&.length == 3
+          # Format: //namespace/pod/container
+          @namespace = options[:namespace] || path_parts.first
+          @pod = options[:pod] || path_parts[1]
+          @container_name = options[:container_name] || path_parts[2]
+        else
+          # No valid path - must use explicit options
+          @namespace = options[:namespace] || TrainPlugins::K8sContainer::KubectlExecClient::DEFAULT_NAMESPACE
+          @pod = options[:pod]
+          @container_name = options[:container_name]
+        end
+
+        validate_parameters
+      end
+
+      def uri
+        "k8s-container://#{@namespace}/#{@pod}/#{@container_name}"
+      end
+
+      # Delegate to kubectl_client for consistent identifier across all components
+      def unique_identifier
+        kubectl_client.unique_identifier
+      end
+
+      private
+
+      attr_reader :pod, :container_name, :namespace
+
+      def kubectl_client
+        @kubectl_client ||= KubectlExecClient.new(
+          pod:,
+          namespace:,
+          container_name:
+        )
+      end
+
+      def run_command_via_connection(cmd, &)
+        kubectl_client.execute(cmd)
+      end
+
+      def validate_parameters
+        raise ArgumentError, 'Missing Parameter `pod`' unless pod
+        raise ArgumentError, 'Missing Parameter `container_name`' unless container_name
+
+        # Validate Kubernetes resource names (RFC 1123 compliance, injection prevention)
+        KubernetesNameValidator.validate!(pod, resource_type: 'pod')
+        KubernetesNameValidator.validate!(namespace, resource_type: 'namespace')
+        KubernetesNameValidator.validate!(container_name, resource_type: 'container')
+      end
+
+      def file_via_connection(path, *_args)
+        # Basic path traversal prevention
+        raise ArgumentError, 'File path cannot be nil' if path.nil?
+        raise ArgumentError, 'File path cannot be empty' if path.empty?
+
+        # Detect container OS to use appropriate file handler
+        detect_shell # Triggers OS detection in ShellDetector
+        container_os = @shell_detector&.container_os || :unknown
+
+        case container_os
+        when :windows
+          ::Train::File::Remote::Windows.new(self, path)
+        else
+          # Default to Linux for unix and unknown (distroless still uses Unix paths)
+          ::Train::File::Remote::Linux.new(self, path)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'train'
+
+module TrainPlugins
+  module K8sContainer
+    # Base error class for k8s-container transport
+    class K8sContainerError < Train::TransportError; end
+
+    # kubectl binary not found in PATH
+    class KubectlNotFoundError < K8sContainerError; end
+
+    # Container not found in specified pod
+    class ContainerNotFoundError < K8sContainerError; end
+
+    # Pod not found in specified namespace
+    class PodNotFoundError < K8sContainerError; end
+
+    # Container has no shell (distroless) and command requires one
+    class ShellNotAvailableError < K8sContainerError; end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module TrainPlugins
+  module K8sContainer
+    # Builds kubectl exec command strings with proper escaping
+    # Consolidates all command building logic to eliminate duplication
+    class KubectlCommandBuilder
+      attr_reader :kubectl_path, :pod, :namespace, :container_name
+
+      def initialize(kubectl_path:, pod:, namespace:, container_name:)
+        @kubectl_path = kubectl_path
+        @pod = pod
+        @namespace = namespace
+        @container_name = container_name
+      end
+
+      # Base kubectl exec command components (used by all builders)
+      def base_command
+        [
+          @kubectl_path, 'exec', '--stdin',
+          @pod, '-n', @namespace, '-c', @container_name,
+        ]
+      end
+
+      # Build command for Unix shell execution
+      # @param shell_path [String] Path to shell (e.g., '/bin/bash')
+      # @param command [String] Command to execute
+      # @return [String] Complete kubectl command
+      def with_shell(shell_path, command)
+        [
+          *base_command,
+          '--', shell_path, '-c', Shellwords.escape(command),
+        ].join(' ')
+      end
+
+      # Build command for Windows shell execution
+      # @param shell_path [String] Shell name (e.g., 'cmd.exe', 'powershell.exe')
+      # @param command [String] Command to execute
+      # @return [String] Complete kubectl command
+      def with_windows_shell(shell_path, command)
+        flag = shell_flag_for(shell_path)
+        [
+          *base_command,
+          '--', shell_path, flag, Shellwords.escape(command),
+        ].join(' ')
+      end
+
+      # Build command for direct binary execution (no shell)
+      # @param command [String] Command to execute (will be split on spaces)
+      # @return [String] Complete kubectl command
+      def direct_binary(command)
+        [
+          *base_command,
+          '--',
+        ].concat(command.split).join(' ')
+      end
+
+      # Build command with hardcoded /bin/sh (for raw execution)
+      # @param command [String] Command to execute
+      # @return [String] Complete kubectl command
+      def with_raw_shell(command)
+        [
+          *base_command,
+          '--', '/bin/sh', '-c', Shellwords.escape(command),
+        ].join(' ')
+      end
+
+      private
+
+      # Get the appropriate shell flag for Windows shells
+      # @param shell_path [String] Shell path
+      # @return [String] Shell flag ('/c' for cmd, '-Command' for PowerShell)
+      def shell_flag_for(shell_path)
+        case shell_path
+        when 'cmd.exe'
+          '/c'
+        when 'powershell.exe', 'pwsh.exe'
+          '-Command'
+        else
+          '-c' # Fallback to Unix-style
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'mixlib/shellout' unless defined?(Mixlib::ShellOut)
+require 'shellwords'
+require 'logger'
+require 'train/options'
+require 'train/extras'
+require_relative 'retry_handler'
+require_relative 'session_manager'
+require_relative 'ansi_sanitizer'
+require_relative 'kubectl_command_builder'
+require_relative 'result_processor'
+
+module TrainPlugins
+  module K8sContainer
+    # Kubectl exec client for executing commands in Kubernetes containers
+    # Supports both one-off execution (Mixlib::ShellOut) and persistent sessions (PTY)
+    class KubectlExecClient
+      attr_reader :pod, :container_name, :namespace
+
+      DEFAULT_NAMESPACE = 'default'
+      DEFAULT_TIMEOUT = 60
+      SHELL_DETECTION_TIMEOUT = 5
+
+      def initialize(pod:, namespace: nil, container_name: nil, kubectl_path: 'kubectl', timeout: DEFAULT_TIMEOUT, logger: nil, use_pty: nil)
+        @pod = pod
+        @container_name = container_name
+        @namespace = namespace
+        @kubectl_path = kubectl_path
+        @timeout = timeout
+        @logger = logger || default_logger
+        @shell_detector = nil # Will be created lazily
+        # Default to enabled (opt-out via use_pty: false or TRAIN_K8S_SESSION_MODE=false)
+        @use_pty = use_pty.nil? ? (ENV['TRAIN_K8S_SESSION_MODE'] != 'false') : use_pty
+        @pty_fallback_disabled = false
+        @command_builder = KubectlCommandBuilder.new(
+          kubectl_path: @kubectl_path,
+          pod: @pod,
+          namespace: @namespace,
+          container_name: @container_name
+        )
+      end
+
+      def execute(command, opts = {})
+        @logger.debug("Executing command in #{@namespace}/#{@pod}/#{@container_name}: #{command}")
+
+        if @use_pty && pty_available? && !@pty_fallback_disabled
+          execute_via_pty(command, opts)
+        else
+          execute_via_shellout(command, opts)
+        end
+      rescue Errno::ENOENT => e
+        @logger.error("kubectl not found at '#{@kubectl_path}': #{e.message}")
+        raise KubectlNotFoundError, "kubectl not found at '#{@kubectl_path}'"
+      rescue Mixlib::ShellOut::CommandTimeout
+        @logger.error("Command timed out after #{opts[:timeout] || @timeout}s: #{command}")
+        raise Train::CommandTimeoutReached, "Command timed out: #{command}"
+      end
+
+      # Raw execution for shell detection (uses /bin/sh directly)
+      def execute_raw(command)
+        instruction = @command_builder.with_raw_shell(command)
+        run_shellout(instruction, timeout: SHELL_DETECTION_TIMEOUT)
+      rescue Errno::ENOENT => _e
+        Train::Extras::CommandResult.new('', '', 1)
+      end
+
+      # Unique identifier for this connection (namespace/pod/container)
+      # Used for session management and logging
+      def unique_identifier
+        "#{@namespace}/#{@pod}/#{@container_name}"
+      end
+
+      private
+
+      def pty_available?
+        # PTY only works on Unix-like operating systems
+        !RUBY_PLATFORM.match?(/windows|mswin|msys|mingw|cygwin/)
+      end
+
+      def execute_via_pty(command, opts)
+        @logger.debug('Using PTY session for execution')
+        shell = detect_shell
+        raise ShellNotAvailableError, 'No shell available for PTY mode' unless shell
+
+        session = create_pty_session(shell, opts)
+        session.execute(command)
+      rescue PtySession::SessionClosedError => e
+        # Try reconnecting once
+        @logger.warn("PTY session closed: #{e.message}, attempting reconnect")
+        SessionManager.instance.cleanup_session(session_key)
+        session = create_pty_session(shell, opts)
+        session.execute(command)
+      rescue PtySession::PtyError, ShellNotAvailableError => e
+        @logger.error("PTY execution failed: #{e.message}, falling back to one-off execution")
+        @pty_fallback_disabled = true
+        execute_via_shellout(command, opts)
+      end
+
+      def execute_via_shellout(command, opts)
+        @logger.debug('Using one-off execution (Mixlib::ShellOut)')
+
+        RetryHandler.with_retry(max_retries: opts[:max_retries] || 3, logger: @logger) do
+          shell = detect_shell
+
+          result = if shell
+                     execute_with_shell(shell, command, opts)
+                   else
+                     execute_without_shell(command, opts)
+                   end
+
+          ResultProcessor.process(result, command, @logger)
+        end
+      end
+
+      # Session key reuses unique_identifier for consistency
+      def session_key
+        unique_identifier
+      end
+
+      # Execute a command via Mixlib::ShellOut and return Train::Extras::CommandResult
+      # Consolidates the repeated shellout pattern for DRY compliance
+      # @param instruction [String] The full kubectl command to execute
+      # @param timeout [Integer] Command timeout in seconds
+      # @return [Train::Extras::CommandResult] The command result
+      def run_shellout(instruction, timeout:)
+        shell = Mixlib::ShellOut.new(instruction, timeout: timeout)
+        res = shell.run_command
+        Train::Extras::CommandResult.new(res.stdout, res.stderr, res.exitstatus)
+      end
+
+      # Lazy-load and cache shell detector (caching at instance level)
+      # ShellDetector also caches detection result internally for efficiency
+      # This double-caching prevents both repeated object creation and detection attempts
+      def detect_shell
+        require_relative 'shell_detector' unless defined?(ShellDetector)
+        @shell_detector ||= ShellDetector.new(self)
+        @shell_detector.detect
+      end
+
+      def execute_with_shell(shell_path, command, opts)
+        instruction = if ShellDetector.windows_shell?(shell_path)
+                        @command_builder.with_windows_shell(shell_path, command)
+                      else
+                        @command_builder.with_shell(shell_path, command)
+                      end
+        run_shellout(instruction, timeout: opts[:timeout] || @timeout)
+      end
+
+      def create_pty_session(shell, opts)
+        SessionManager.instance.get_session(
+          session_key,
+          kubectl_cmd: @command_builder.base_command.join(' '),
+          shell: shell,
+          timeout: opts[:timeout] || @timeout,
+          logger: @logger
+        )
+      end
+
+      def execute_without_shell(command, opts)
+        # For distroless - can only execute simple binaries
+        if command.match?(/[|&;<>()$`\\"]/)
+          raise ShellNotAvailableError,
+                "Container has no shell - cannot execute complex command with operators: #{command}"
+        end
+
+        instruction = @command_builder.direct_binary(command)
+        run_shellout(instruction, timeout: opts[:timeout] || @timeout)
+      end
+
+      def default_logger
+        Logger.new($stdout, level: ENV['TRAIN_K8S_LOG_LEVEL'] || Logger::WARN)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module TrainPlugins
+  module K8sContainer
+    # Validates Kubernetes resource names to prevent injection attacks
+    # Follows RFC 1123 DNS subdomain naming standard
+    module KubernetesNameValidator
+      # RFC 1123 DNS subdomain name:
+      # - Lowercase alphanumeric characters, '-' or '.'
+      # - Must start and end with alphanumeric
+      # - Maximum 253 characters
+      VALID_NAME_REGEX = /\A[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)?\z/
+      MAX_NAME_LENGTH = 253
+
+      # Validate a Kubernetes resource name (pod, namespace, container)
+      # @param name [String] The name to validate
+      # @param resource_type [String] Type of resource (for error messages)
+      # @raise [ArgumentError] If name is invalid
+      # @return [String] The validated name
+      def self.validate!(name, resource_type: 'resource')
+        raise ArgumentError, "#{resource_type} name cannot be nil" if name.nil?
+        raise ArgumentError, "#{resource_type} name cannot be empty" if name.empty?
+
+        raise ArgumentError, "#{resource_type} name too long (max #{MAX_NAME_LENGTH} chars): #{name}" if name.length > MAX_NAME_LENGTH
+
+        unless VALID_NAME_REGEX.match?(name)
+          raise ArgumentError, "Invalid #{resource_type} name '#{name}': must be RFC 1123 DNS subdomain " \
+                               "(lowercase alphanumeric, '-' or '.', start/end with alphanumeric)"
+        end
+
+        name
+      end
+
+      # Check if name is valid without raising
+      # @param name [String] The name to check
+      # @return [Boolean] True if valid
+      def self.valid?(name)
+        return false if name.nil? || name.empty? || name.length > MAX_NAME_LENGTH
+
+        VALID_NAME_REGEX.match?(name)
+      end
+    end
+  end
+end