train-juniper 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abb9487cdbf492d9b94f9b45699e2a434095509e128d5928863e5fdff3c73241
-  data.tar.gz: 0d9d6746cb16f185eef54b199aaf02b4509e66cc9292af3475913bae89f3e36c
+  metadata.gz: 86bf86dd54cabe94e072c6e3a2b64ffcdfbdf774a5f33f1a3a76012829dd71bc
+  data.tar.gz: c2e5d2fe1ecfa259f78c2d80f76d94eaa68afb817d584c57d02bfb4c46779924
 SHA512:
-  metadata.gz: 8c7c246e820daa1d436c03d4f95e7acab6bef59c600c9f18d99fcc94b63989a0adf00a483661fc362db634871446b469aa0bed753a6852b40d2da768709882d8
-  data.tar.gz: db80d5fdefcb80294734f162b67f48f21219859ebed3ee294bcb1449876be0a7c7758e4ed613c8fc3e40a9d7d67c25df12316cc56e31352dc648eda2c8184c59
+  metadata.gz: 168356b0c2a48f7b4817acb535571c2b651d12365dc7340c96c9b2b2d6db30981516683c29965bd295459d8cbb2b2625e020a35789a3bbed4d295ce29712264e
+  data.tar.gz: 8a209708671652728890ff96f75b3a2da922f37f93c61896881e99b387adc15ecc1e889d6e416637dc0eee011ed1f1b9b0fcd33b99c2bacfe15f2736daaa9da8

data/CHANGELOG.md

@@ -5,6 +5,49 @@ 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).
 
+## [0.7.1] - 2025-06-23
+
+### Added
+
+- Implement Priority 2 DRY improvements and boost coverage to 90.88%
+- Add coverage analysis utility script
+- Boost test coverage to 93.13% and enhance coverage analysis tool
+- **coverage**: Integrate coverage reporting into release process and CI/CD
+- **docs**: Enhance coverage report with Material for MkDocs styling
+
+### Documentation
+
+- Add YARD documentation for inspect method and test organization guide
+- Add YARD documentation for all constants
+- **roadmap**: Modernize with v0.7.1 status and Material styling
+
+### Fixed
+
+- Add v0.7.0 to mkdocs and automate nav updates
+- **coverage**: Properly handle SimpleCov :nocov: markers in analysis
+- **docs**: Move Security Policy to About section in navigation
+
+### Miscellaneous Tasks
+
+- Fix all RuboCop violations and prepare for v0.7.1 release
+- Remove .rubocop_todo.yml after fixing all violations
+
+### Refactor
+
+- Streamline release process for GitHub Actions
+- Phase 1 modularization - extract JuniperFile, EnvironmentHelpers, and Validation
+- Reorganize directory structure to follow Train plugin conventions
+- Phase 2 modularization - extract CommandExecutor and ErrorHandling
+- Phase 3 modularization - extract SSHSession and BastionProxy
+- DRY improvements for v0.7.1
+- Fix all RuboCop complexity issues without using todos
+- **docs**: Reorganize navigation for better user experience
+
+### Testing
+
+- Fix platform edge case test and boost coverage to 99.75%
+- Achieve 100% code coverage 🎯
+
 ## [0.7.0] - 2025-06-23
 
 ### Added

data/Rakefile

@@ -103,5 +103,5 @@ end
 #------------------------------------------------------------------#
 #                    Bundler Gem Tasks
 #------------------------------------------------------------------#
-# This provides the standard 'rake release' task that rubygems/release-gem expects
-require 'bundler/gem_tasks'
+# Bundler gem tasks disabled - we use GitHub Actions for gem publication
+# require 'bundler/gem_tasks'

data/lib/train-juniper/connection/bastion_proxy.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'train-juniper/constants'
+
+module TrainPlugins
+  module Juniper
+    # Handles bastion host proxy configuration and authentication
+    module BastionProxy
+      # Configure bastion proxy for SSH connection
+      # @param ssh_options [Hash] SSH options to modify
+      def configure_bastion_proxy(ssh_options)
+        require 'net/ssh/proxy/jump' unless defined?(Net::SSH::Proxy::Jump)
+
+        # Build proxy jump string from bastion options
+        bastion_user = @options[:bastion_user] || @options[:user]
+        bastion_port = @options[:bastion_port]
+
+        proxy_jump = if bastion_port == Constants::DEFAULT_SSH_PORT
+                       "#{bastion_user}@#{@options[:bastion_host]}"
+                     else
+                       "#{bastion_user}@#{@options[:bastion_host]}:#{bastion_port}"
+                     end
+
+        @logger.debug("Using bastion host: #{proxy_jump}")
+
+        # Set up automated password authentication via SSH_ASKPASS
+        setup_bastion_password_auth
+
+        ssh_options[:proxy] = Net::SSH::Proxy::Jump.new(proxy_jump)
+      end
+
+      # Set up SSH_ASKPASS for bastion password authentication
+      def setup_bastion_password_auth
+        bastion_password = @options[:bastion_password] || @options[:password]
+        return unless bastion_password
+
+        @ssh_askpass_script = create_ssh_askpass_script(bastion_password)
+        ENV['SSH_ASKPASS'] = @ssh_askpass_script
+        ENV['SSH_ASKPASS_REQUIRE'] = 'force'
+        @logger.debug('Configured SSH_ASKPASS for automated bastion authentication')
+      end
+
+      # Create temporary SSH_ASKPASS script for automated password authentication
+      # @param password [String] The password to use
+      # @return [String] Path to the created script
+      def create_ssh_askpass_script(password)
+        require 'tempfile'
+
+        script = Tempfile.new(['ssh_askpass', '.sh'])
+        script.write("#!/bin/bash\necho '#{password}'\n")
+        script.close
+        File.chmod(0o755, script.path)
+
+        @logger.debug("Created SSH_ASKPASS script at #{script.path}")
+        script.path
+      end
+
+      # Generate SSH proxy command for bastion host using ProxyJump (-J)
+      # @param bastion_user [String] Username for bastion
+      # @param bastion_port [Integer] Port for bastion
+      # @return [String] SSH command string
+      def generate_bastion_proxy_command(bastion_user, bastion_port)
+        args = ['ssh']
+
+        # SSH options for connection
+        Constants::STANDARD_SSH_OPTIONS.each do |key, value|
+          args += ['-o', "#{key}=#{value}"]
+        end
+
+        # Use ProxyJump (-J) which handles password authentication properly
+        jump_host = if bastion_port == Constants::DEFAULT_SSH_PORT
+                      "#{bastion_user}@#{@options[:bastion_host]}"
+                    else
+                      "#{bastion_user}@#{@options[:bastion_host]}:#{bastion_port}"
+                    end
+        args += ['-J', jump_host]
+
+        # Add SSH keys if specified
+        if @options[:key_files]
+          Array(@options[:key_files]).each do |key_file|
+            args += ['-i', key_file]
+          end
+        end
+
+        # Target connection - %h and %p will be replaced by Net::SSH
+        args += ['%h', '-p', '%p']
+
+        args.join(' ')
+      end
+    end
+  end
+end

data/lib/train-juniper/connection/command_executor.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module TrainPlugins
+  module Juniper
+    # Handles command execution, sanitization, and output formatting
+    module CommandExecutor
+      # Command sanitization patterns
+      # Note: Pipe (|) is allowed as it's commonly used in JunOS commands
+      DANGEROUS_COMMAND_PATTERNS = [
+        /[;&<>$`]/,     # Shell metacharacters (excluding pipe)
+        /\n|\r/,        # Newlines that could inject commands
+        /\\(?![nrt])/   # Escape sequences (except valid ones like \n, \r, \t)
+      ].freeze
+
+      # Execute commands on Juniper device via SSH
+      # @param cmd [String] The JunOS command to execute
+      # @return [CommandResult] Result object with stdout, stderr, and exit status
+      # @raise [Train::ClientError] If command contains dangerous characters
+      # @example
+      #   result = connection.run_command('show version')
+      #   puts result.stdout
+      def run_command_via_connection(cmd)
+        # Sanitize command to prevent injection
+        safe_cmd = sanitize_command(cmd)
+
+        return mock_command_result(safe_cmd) if @options[:mock]
+
+        begin
+          # :nocov: Real SSH execution cannot be tested without actual devices
+          # Ensure we're connected
+          connect unless connected?
+
+          log_command(safe_cmd)
+
+          # Execute command via SSH session
+          output = @ssh_session.exec!(safe_cmd)
+
+          @logger.debug("Command output: #{output}")
+
+          # Format JunOS result
+          format_junos_result(output, safe_cmd)
+        rescue StandardError => e
+          log_error(e, 'Command execution failed')
+          # Handle connection errors gracefully
+          error_result(e.message)
+          # :nocov:
+        end
+      end
+
+      private
+
+      # Sanitize command to prevent injection attacks
+      def sanitize_command(cmd)
+        cmd_str = cmd.to_s.strip
+
+        if DANGEROUS_COMMAND_PATTERNS.any? { |pattern| cmd_str.match?(pattern) }
+          raise Train::ClientError, "Invalid characters in command: #{cmd_str.inspect}"
+        end
+
+        cmd_str
+      end
+
+      # Format JunOS command results
+      def format_junos_result(output, cmd)
+        # Parse JunOS-specific error patterns
+        if junos_error?(output)
+          error_result(output)
+        else
+          success_result(output, cmd)
+        end
+      end
+
+      # Clean command output
+      def clean_output(output, cmd)
+        # Handle nil output gracefully
+        return '' if output.nil?
+
+        # Remove command echo and prompts
+        lines = output.to_s.split("\n")
+        lines.reject! { |line| line.strip == cmd.strip }
+
+        # Remove JunOS prompt patterns from the end
+        lines.pop while lines.last&.strip&.match?(/^[%>$#]+\s*$/)
+
+        lines.join("\n")
+      end
+
+      # Mock command execution for testing
+      def mock_command_result(cmd)
+        output, exit_status = MockResponses.response_for(cmd)
+        # For mock mode, network devices return errors as stdout
+        Train::Extras::CommandResult.new(output, '', exit_status)
+      end
+
+      # Factory method for successful command results
+      # @param output [String] Command output
+      # @param cmd [String, nil] Original command for cleaning output
+      # @return [Train::Extras::CommandResult] Successful result object
+      def success_result(output, cmd = nil)
+        output = clean_output(output, cmd) if cmd
+        Train::Extras::CommandResult.new(output, '', 0)
+      end
+
+      # Factory method for error command results
+      # @param message [String] Error message
+      # @return [Train::Extras::CommandResult] Error result object
+      def error_result(message)
+        Train::Extras::CommandResult.new('', message, 1)
+      end
+    end
+  end
+end

data/lib/train-juniper/connection/error_handling.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module TrainPlugins
+  module Juniper
+    # Handles error detection, classification, and messaging
+    module ErrorHandling
+      # JunOS error patterns organized by type
+      JUNOS_ERRORS = {
+        configuration: [/^error:/i, /configuration database locked/i],
+        syntax: [/syntax error/i],
+        command: [/invalid command/i, /unknown command/i],
+        argument: [/missing argument/i]
+      }.freeze
+
+      # Flattened error patterns for quick matching
+      JUNOS_ERROR_PATTERNS = JUNOS_ERRORS.values.flatten.freeze
+
+      # Check for JunOS error patterns
+      # @param output [String] Command output to check
+      # @return [Boolean] true if output contains error patterns
+      def junos_error?(output)
+        return false if output.nil? || output.empty?
+
+        JUNOS_ERROR_PATTERNS.any? { |pattern| output.match?(pattern) }
+      end
+
+      # Handle connection errors with helpful messages
+      # @param error [StandardError] The error that occurred
+      # @raise [Train::TransportError] Always raises with formatted message
+      def handle_connection_error(error)
+        @logger.error("SSH connection failed: #{error.message}")
+
+        if bastion_auth_error?(error)
+          raise Train::TransportError, bastion_error_message(error)
+        else
+          raise Train::TransportError, "Failed to connect to Juniper device #{@options[:host]}: #{error.message}"
+        end
+      end
+
+      # Check if error is bastion authentication related
+      # @param error [StandardError] The error to check
+      # @return [Boolean] true if error is bastion-related
+      def bastion_auth_error?(error)
+        @options[:bastion_host] &&
+          (error.message.include?('Permission denied') || error.message.include?('command failed'))
+      end
+
+      # Build helpful bastion error message
+      # @param error [StandardError] The original error
+      # @return [String] Detailed error message with troubleshooting steps
+      def bastion_error_message(error)
+        <<~ERROR
+          Failed to connect to Juniper device #{@options[:host]} via bastion #{@options[:bastion_host]}: #{error.message}
+
+          Possible causes:
+          1. Incorrect bastion credentials (user: #{@options[:bastion_user] || @options[:user]})
+          2. Network connectivity issues to bastion host
+          3. Bastion host SSH service not available on port #{@options[:bastion_port]}
+          4. Target device not reachable from bastion
+
+          Authentication options:
+          - Password: Use --bastion-password (or JUNIPER_BASTION_PASSWORD env var)
+          - SSH Key: Use --key-files option to specify SSH private key files
+          - SSH Agent: Ensure your SSH agent has the required keys loaded
+
+          For more details, see: https://mitre.github.io/train-juniper/troubleshooting/#bastion-authentication
+        ERROR
+      end
+    end
+  end
+end

data/lib/train-juniper/connection/ssh_session.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module TrainPlugins
+  module Juniper
+    # Handles SSH session management and configuration
+    module SSHSession
+      # SSH option mapping configuration
+      SSH_OPTION_MAPPING = {
+        port: :port,
+        password: :password,
+        timeout: :timeout,
+        keepalive: :keepalive,
+        keepalive_interval: :keepalive_interval,
+        keys: ->(opts) { Array(opts[:key_files]) if opts[:key_files] },
+        keys_only: ->(opts) { opts[:keys_only] if opts[:key_files] }
+      }.freeze
+
+      # Default SSH options for Juniper connections
+      # @note verify_host_key is set to :never for network device compatibility
+      SSH_DEFAULTS = {
+        verify_host_key: :never
+      }.freeze
+
+      # Establish SSH connection to Juniper device
+      def connect
+        return if connected?
+
+        # :nocov: Real SSH connections cannot be tested without actual devices
+        begin
+          # Use direct SSH connection (network device pattern)
+          # Defensive loading - only require if not fully loaded
+          require 'net/ssh' unless defined?(Net::SSH) && Net::SSH.respond_to?(:start)
+
+          @logger.debug('Establishing SSH connection to Juniper device')
+
+          ssh_options = build_ssh_options
+
+          # Add bastion host support if configured
+          if @options[:bastion_host]
+            log_bastion_connection(@options[:bastion_host])
+            configure_bastion_proxy(ssh_options)
+          end
+
+          log_connection_attempt(@options[:host], @options[:port])
+          log_ssh_options(ssh_options)
+
+          # Direct SSH connection
+          @ssh_session = Net::SSH.start(@options[:host], @options[:user], ssh_options)
+          log_connection_success(@options[:host])
+
+          # Configure JunOS session for automation
+          test_and_configure_session
+        rescue StandardError => e
+          handle_connection_error(e)
+        end
+        # :nocov:
+      end
+
+      # Check if SSH connection is active
+      # @return [Boolean] true if connected, false otherwise
+      def connected?
+        return true if @options[:mock]
+
+        !@ssh_session.nil?
+      rescue StandardError
+        false
+      end
+
+      # Check if running in mock mode
+      # @return [Boolean] true if in mock mode
+      def mock?
+        @options[:mock] == true
+      end
+
+      # Test connection and configure JunOS session
+      def test_and_configure_session
+        @logger.debug('Testing SSH connection and configuring JunOS session')
+
+        # Test connection first
+        @ssh_session.exec!('echo "connection test"')
+        @logger.debug('SSH connection test successful')
+
+        # Optimize CLI for automation
+        @ssh_session.exec!('set cli screen-length 0')
+        @ssh_session.exec!('set cli screen-width 0')
+        @ssh_session.exec!('set cli complete-on-space off') if @options[:disable_complete_on_space]
+
+        @logger.debug('JunOS session configured successfully')
+      rescue StandardError => e
+        @logger.warn("Failed to configure JunOS session: #{e.message}")
+      end
+
+      private
+
+      # Build SSH connection options from @options
+      def build_ssh_options
+        SSH_DEFAULTS.merge(
+          SSH_OPTION_MAPPING.each_with_object({}) do |(ssh_key, option_key), opts|
+            value = option_key.is_a?(Proc) ? option_key.call(@options) : @options[option_key]
+            opts[ssh_key] = value unless value.nil?
+          end
+        )
+      end
+    end
+  end
+end

data/lib/train-juniper/connection/validation.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module TrainPlugins
+  module Juniper
+    # Validation methods for connection options
+    module Validation
+      # Validate all connection options
+      def validate_connection_options!
+        validate_required_options!
+        validate_option_types!
+        validate_proxy_options!
+      end
+
+      # Validate required options are present
+      def validate_required_options!
+        raise Train::ClientError, 'Host is required' unless @options[:host]
+        raise Train::ClientError, 'User is required' unless @options[:user]
+      end
+
+      # Validate option types and ranges
+      def validate_option_types!
+        validate_port! if @options[:port]
+        validate_timeout! if @options[:timeout]
+        validate_bastion_port! if @options[:bastion_port]
+      end
+
+      # Validate port is in valid range
+      def validate_port!
+        validate_port_value!(:port)
+      end
+
+      # Validate timeout is positive number
+      def validate_timeout!
+        timeout = @options[:timeout]
+        raise Train::ClientError, "Invalid timeout: #{timeout} (must be positive number)" unless timeout.is_a?(Numeric) && timeout.positive?
+      end
+
+      # Validate bastion port is in valid range
+      def validate_bastion_port!
+        validate_port_value!(:bastion_port)
+      end
+
+      private
+
+      # DRY method for validating port values
+      # @param port_key [Symbol] The options key containing the port value
+      # @param port_name [String] The name to use in error messages (defaults to port_key)
+      def validate_port_value!(port_key, port_name = nil)
+        port_name ||= port_key.to_s.tr('_', ' ')
+        port = @options[port_key].to_i
+        raise Train::ClientError, "Invalid #{port_name}: #{@options[port_key]} (must be 1-65535)" unless port.between?(1, 65_535)
+      end
+
+      # Validate proxy configuration options (Train standard)
+      def validate_proxy_options!
+        # Cannot use both bastion_host and proxy_command simultaneously
+        if @options[:bastion_host] && @options[:proxy_command]
+          raise Train::ClientError, 'Cannot specify both bastion_host and proxy_command'
+        end
+      end
+    end
+  end
+end