train-juniper 0.6.2 → 0.7.1

data/lib/train-juniper/helpers/environment.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module TrainPlugins
+  module Juniper
+    # Helper methods for safely handling environment variables
+    module Environment
+      # Helper method to safely get environment variable value
+      # Returns nil if env var is not set or is empty string
+      # @param key [String] The environment variable name
+      # @return [String, nil] The value or nil if not set/empty
+      def env_value(key)
+        value = ENV.fetch(key, nil)
+        return nil if value.nil? || value.empty?
+
+        value
+      end
+
+      # Helper method to get environment variable as integer
+      # Returns nil if env var is not set, empty, or not a valid integer
+      # @param key [String] The environment variable name
+      # @return [Integer, nil] The integer value or nil if not valid
+      def env_int(key)
+        value = env_value(key)
+        return nil unless value
+
+        value.to_i
+      end
+    end
+  end
+end

data/lib/train-juniper/helpers/logging.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module TrainPlugins
+  module Juniper
+    # Provides consistent logging patterns across the plugin
+    module Logging
+      # Log a command execution attempt
+      # @param cmd [String] The command being executed
+      def log_command(cmd)
+        @logger.debug("Executing command: #{cmd}")
+      end
+
+      # Log a connection attempt
+      # @param target [String] The host/target being connected to
+      # @param port [Integer] The port number
+      def log_connection_attempt(target, port = nil)
+        if port
+          @logger.debug("Attempting connection to #{target}:#{port}")
+        else
+          @logger.debug("Attempting connection to #{target}")
+        end
+      end
+
+      # Log an error with consistent formatting
+      # @param error [Exception, String] The error to log
+      # @param context [String] Additional context for the error
+      def log_error(error, context = nil)
+        message = if error.is_a?(Exception)
+                    "#{error.class}: #{error.message}"
+                  else
+                    error.to_s
+                  end
+
+        if context
+          @logger.error("#{context}: #{message}")
+        else
+          @logger.error(message)
+        end
+      end
+
+      # Log successful connection
+      # @param target [String] The host that was connected to
+      def log_connection_success(target)
+        @logger.info("Successfully connected to #{target}")
+      end
+
+      # Log SSH session details (redacting sensitive info)
+      # @param options [Hash] SSH options hash
+      def log_ssh_options(options)
+        safe_options = options.dup
+        safe_options[:password] = '[REDACTED]' if safe_options[:password]
+        safe_options[:passphrase] = '[REDACTED]' if safe_options[:passphrase]
+        safe_options[:keys] = safe_options[:keys]&.map { |k| File.basename(k) } if safe_options[:keys]
+
+        @logger.debug("SSH options: #{safe_options.inspect}")
+      end
+
+      # Log platform detection results
+      # @param platform_name [String] Detected platform name
+      # @param version [String] Detected version
+      def log_platform_detection(platform_name, version)
+        @logger.info("Platform detected: #{platform_name} #{version}")
+      end
+
+      # Log bastion connection attempt
+      # @param bastion_host [String] The bastion host
+      def log_bastion_connection(bastion_host)
+        @logger.debug("Connecting through bastion host: #{bastion_host}")
+      end
+
+      # Log mock mode activation
+      def log_mock_mode
+        @logger.info('Running in mock mode - no real device connection')
+      end
+    end
+  end
+end

data/lib/train-juniper/helpers/mock_responses.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Mock responses for Juniper device commands
+# This module contains all mock data used in testing and mock mode
+module TrainPlugins
+  module Juniper
+    # Mock responses for common JunOS commands
+    # Used when running in mock mode for testing without real devices
+    module MockResponses
+      # Configuration of mock responses
+      # Maps command patterns to response methods or strings
+      RESPONSES = {
+        'show version' => :mock_show_version_output,
+        'show chassis hardware' => :mock_chassis_output,
+        'show configuration' => "interfaces {\n    ge-0/0/0 {\n        unit 0;\n    }\n}",
+        'show route' => "inet.0: 5 destinations, 5 routes\n0.0.0.0/0       *[Static/5] 00:00:01\n",
+        'show system information' => "Hardware: SRX240H2\nOS: JUNOS 12.1X47-D15.4\n",
+        'show interfaces' => "Physical interface: ge-0/0/0, Enabled, Physical link is Up\n"
+      }.freeze
+
+      # Mock JunOS version output for testing
+      # @return [String] mock output for 'show version' command
+      def self.mock_show_version_output
+        <<~OUTPUT
+          Hostname: lab-srx
+          Model: SRX240H2
+          Junos: 12.1X47-D15.4
+          JUNOS Software Release [12.1X47-D15.4]
+        OUTPUT
+      end
+
+      # Mock chassis hardware output
+      # @return [String] mock output for 'show chassis hardware' command
+      def self.mock_chassis_output
+        <<~OUTPUT
+          Hardware inventory:
+          Item             Version  Part number  Serial number     Description
+          Chassis                                JN123456          SRX240H2
+        OUTPUT
+      end
+
+      # Get mock response for a command
+      # @param cmd [String] the command to get response for
+      # @return [Array<String, Integer>] tuple of [output, exit_status]
+      def self.response_for(cmd)
+        response = RESPONSES.find { |pattern, _| cmd.match?(/#{pattern}/) }
+
+        if response
+          output = response[1].is_a?(Symbol) ? send(response[1]) : response[1]
+          [output, 0]
+        else
+          ["% Unknown command: #{cmd}", 1]
+        end
+      end
+    end
+  end
+end

data/lib/train-juniper/platform.rb

@@ -5,16 +5,19 @@
 
 module TrainPlugins::Juniper
   # Platform detection mixin for Juniper network devices
+  # @note This module is mixed into the Connection class to provide platform detection
   module Platform
     # Platform name constant for consistency
     PLATFORM_NAME = 'juniper'
 
     # Platform detection for Juniper network devices
-    #
-    # For dedicated transport plugins, we use force_platform! to bypass
-    # Train's automatic platform detection, which might run commands before
-    # the connection is ready. This is the standard pattern used by official
-    # Train plugins like train-k8s-container.
+    # @return [Train::Platform] Platform object with JunOS details
+    # @note Uses force_platform! to bypass Train's automatic detection
+    # @example
+    #   platform = connection.platform
+    #   platform.name     #=> "juniper"
+    #   platform.release  #=> "12.1X47-D15.4"
+    #   platform.arch     #=> "x86_64"
     def platform
       # Return cached platform if already computed
       return @platform if defined?(@platform)
@@ -39,73 +42,75 @@ module TrainPlugins::Juniper
       platform_obj = force_platform!(PLATFORM_NAME, platform_details)
       logger&.debug("Set platform data: #{platform_obj.platform}")
 
+      # Log platform detection results if logging helpers available
+      log_platform_detection(PLATFORM_NAME, device_version) if respond_to?(:log_platform_detection)
+
       # Cache the platform object to prevent repeated calls
       @platform = platform_obj
     end
 
     private
 
-    # Detect JunOS version from device output
-    # This runs safely after the connection is established
-    def detect_junos_version
-      # Return cached version if already detected
-      return @detected_junos_version if defined?(@detected_junos_version)
+    # Generic detection helper for version and architecture
+    # @param attribute_name [String] Name of the attribute to detect
+    # @param command [String] Command to run (default: 'show version')
+    # @yield [String] Block that extracts the attribute from command output
+    # @return [String, nil] Detected attribute value or nil
+    def detect_attribute(attribute_name, command = 'show version', &extraction_block)
+      cache_var = "@detected_#{attribute_name}"
+      return instance_variable_get(cache_var) if instance_variable_defined?(cache_var)
 
-      # Only try version detection if we have an active connection
       unless respond_to?(:run_command_via_connection)
         logger&.debug('run_command_via_connection not available yet')
-        return @detected_junos_version = nil
+        return instance_variable_set(cache_var, nil)
       end
 
       logger&.debug("Mock mode: #{@options&.dig(:mock)}, Connected: #{connected?}")
 
       begin
-        # Check if connection is ready before running commands
-        unless connected?
-          logger&.debug('Not connected, skipping version detection')
-          return @detected_junos_version = nil
-        end
-
-        # Execute 'show version' command to get JunOS information
-        logger&.debug("Running 'show version' command")
-        result = run_command_via_connection('show version')
+        return instance_variable_set(cache_var, nil) unless connected?
 
-        unless result&.exit_status&.zero?
-          logger&.debug("Command failed with exit status: #{result&.exit_status}")
-          return @detected_junos_version = nil
-        end
+        # Reuse cached command result if available
+        result = @cached_show_version_result || run_command_via_connection(command)
+        @cached_show_version_result ||= result if command == 'show version' && result&.exit_status&.zero?
 
-        # Cache the result for architecture detection to avoid duplicate calls
-        @cached_show_version_result = result
+        return instance_variable_set(cache_var, nil) unless result&.exit_status&.zero?
 
-        # Parse JunOS version from output using multiple patterns
-        version = extract_version_from_output(result.stdout)
+        value = extraction_block.call(result.stdout)
 
-        if version
-          logger&.debug("Detected JunOS version: #{version}")
-          @detected_junos_version = version
+        if value
+          logger&.debug("Detected #{attribute_name}: #{value}")
+          instance_variable_set(cache_var, value)
         else
-          logger&.debug("Could not parse JunOS version from: #{result.stdout[0..100]}")
-          @detected_junos_version = nil
+          logger&.debug("Could not parse #{attribute_name} from: #{result.stdout[0..100]}")
+          instance_variable_set(cache_var, nil)
         end
       rescue StandardError => e
-        # If version detection fails, log and return nil
-        logger&.debug("JunOS version detection failed: #{e.message}")
-        @detected_junos_version = nil
+        logger&.debug("#{attribute_name} detection failed: #{e.message}")
+        instance_variable_set(cache_var, nil)
       end
     end
 
+    # Detect JunOS version from device output
+    # @return [String, nil] JunOS version string or nil if not detected
+    # @note This runs safely after the connection is established
+    def detect_junos_version
+      detect_attribute('junos_version') { |output| extract_version_from_output(output) }
+    end
+
     # Extract version string from JunOS show version output
+    # @param output [String] Raw output from 'show version' command
+    # @return [String, nil] Extracted version string or nil
     def extract_version_from_output(output)
       return nil if output.nil? || output.empty?
 
       # Try multiple JunOS version patterns
       patterns = [
-        /Junos:\s+([\d\w\.-]+)/,                           # "Junos: 12.1X47-D15.4"
-        /JUNOS Software Release \[([\d\w\.-]+)\]/,         # "JUNOS Software Release [12.1X47-D15.4]"
-        /junos version ([\d\w\.-]+)/i,                     # "junos version 21.4R3"
-        /Model: \S+, JUNOS Base OS boot \[([\d\w\.-]+)\]/, # Some hardware variants
-        /([\d]+\.[\d]+[\w\.-]*)/                           # Generic version pattern
+        /Junos:\s+([\w\d.-]+)/,                           # "Junos: 12.1X47-D15.4"
+        /JUNOS Software Release \[([\w\d.-]+)\]/,         # "JUNOS Software Release [12.1X47-D15.4]"
+        /junos version ([\w\d.-]+)/i,                     # "junos version 21.4R3"
+        /Model: \S+, JUNOS Base OS boot \[([\w\d.-]+)\]/, # Some hardware variants
+        /([\d]+\.[\d]+[\w.-]*)/                           # Generic version pattern
       ]
 
       patterns.each do |pattern|
@@ -117,56 +122,22 @@ module TrainPlugins::Juniper
     end
 
     # Detect JunOS architecture from device output
-    # This runs safely after the connection is established
+    # @return [String, nil] Architecture string or nil if not detected
+    # @note This runs safely after the connection is established
     def detect_junos_architecture
-      # Return cached architecture if already detected
-      return @detected_junos_architecture if defined?(@detected_junos_architecture)
-
-      # Only try architecture detection if we have an active connection
-      return @detected_junos_architecture = nil unless respond_to?(:run_command_via_connection)
-
-      begin
-        # Check if connection is ready before running commands
-        return @detected_junos_architecture = nil unless connected?
-
-        # Reuse version detection result to avoid duplicate 'show version' calls
-        # Both version and architecture come from the same command output
-        if defined?(@detected_junos_version) && @detected_junos_version
-          # We already have the output from version detection, parse architecture from it
-          result = @cached_show_version_result
-        else
-          # Execute 'show version' command and cache the result
-          result = run_command_via_connection('show version')
-          @cached_show_version_result = result if result&.exit_status&.zero?
-        end
-
-        return @detected_junos_architecture = nil unless result&.exit_status&.zero?
-
-        # Parse architecture from output using multiple patterns
-        arch = extract_architecture_from_output(result.stdout)
-
-        if arch
-          logger&.debug("Detected JunOS architecture: #{arch}")
-          @detected_junos_architecture = arch
-        else
-          logger&.debug("Could not parse JunOS architecture from: #{result.stdout[0..100]}")
-          @detected_junos_architecture = nil
-        end
-      rescue StandardError => e
-        # If architecture detection fails, log and return nil
-        logger&.debug("JunOS architecture detection failed: #{e.message}")
-        @detected_junos_architecture = nil
-      end
+      detect_attribute('junos_architecture') { |output| extract_architecture_from_output(output) }
     end
 
     # Extract architecture string from JunOS show version output
+    # @param output [String] Raw output from 'show version' command
+    # @return [String, nil] Architecture string (x86_64, arm64, etc.) or nil
     def extract_architecture_from_output(output)
       return nil if output.nil? || output.empty?
 
       # Try multiple JunOS architecture patterns
       patterns = [
         /Model:\s+(\S+)/, # "Model: SRX240H2" -> extract model as arch indicator
-        /Junos:\s+[\d\w\.-]+\s+built\s+[\d-]+\s+[\d:]+\s+by\s+builder\s+on\s+(\S+)/, # Build architecture
+        /Junos:\s+[\w\d.-]+\s+built\s+[\d-]+\s+[\d:]+\s+by\s+builder\s+on\s+(\S+)/, # Build architecture
         /JUNOS.*\[([\w-]+)\]/,                                 # JUNOS package architecture
         /Architecture:\s+(\S+)/i,                              # Direct architecture line
         /Platform:\s+(\S+)/i,                                  # Platform designation

data/lib/train-juniper/transport.rb

@@ -7,6 +7,13 @@ require 'train-juniper/connection'
 
 module TrainPlugins
   module Juniper
+    # Transport plugin for Juniper JunOS devices
+    # @example Create a connection
+    #   conn = Train.create('juniper',
+    #     host: '192.168.1.1',
+    #     user: 'admin',
+    #     password: 'secret'
+    #   )
     class Transport < Train.plugin(1)
       name 'juniper'
 
@@ -20,7 +27,7 @@ module TrainPlugins
 
       # Proxy/Bastion host support (Train standard options)
       option :bastion_host, default: nil
-      option :bastion_user, default: nil # Let connection handle env vars and defaults
+      option :bastion_user, default: nil # Falls back to main user if not specified
       option :bastion_port, default: 22
       option :bastion_password, default: nil # Separate password for bastion authentication
       option :proxy_command, default: nil
@@ -45,6 +52,11 @@ module TrainPlugins
       option :disable_complete_on_space, default: false
 
       # Create and return a connection to a Juniper device
+      # @param _instance_opts [Hash] Instance options (unused, for compatibility)
+      # @return [TrainPlugins::Juniper::Connection] Cached connection instance
+      # @example
+      #   transport = TrainPlugins::Juniper::Transport.new(options)
+      #   conn = transport.connection
       def connection(_instance_opts = nil)
         # Cache the connection instance for reuse
         # @options contains parsed connection details from train URI

data/lib/train-juniper/version.rb

@@ -7,6 +7,7 @@
 
 module TrainPlugins
   module Juniper
-    VERSION = '0.6.2'
+    # Version number of the train-juniper plugin
+    VERSION = '0.7.1'
   end
 end

data/train-juniper.gemspec

@@ -70,4 +70,20 @@ Gem::Specification.new do |spec|
   # FFI dependency - required by train-core
   # Match InSpec 7's FFI version range for compatibility
   spec.add_dependency 'ffi', '>= 1.15.5', '< 1.17.0'
+
+  # Development dependencies
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'byebug', '~> 11.1'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'mocha', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rubocop', '~> 1.0'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'yard', '~> 0.9'
+
+  # Security testing
+  spec.add_development_dependency 'bundler-audit', '~> 0.9'
+
+  # Documentation generation
+  spec.add_development_dependency 'redcarpet', '~> 3.5'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: train-juniper
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.1
 platform: ruby
 authors:
 - MITRE Corporation
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-19 00:00:00.000000000 Z
+date: 2025-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: train-core
@@ -64,6 +64,146 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.17.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.1'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
 description: Provides SSH connectivity to Juniper Networks devices running JunOS for
   InSpec compliance testing and infrastructure inspection. Supports platform detection,
   command execution, and configuration file access.
@@ -84,6 +224,16 @@ files:
 - SECURITY.md
 - lib/train-juniper.rb
 - lib/train-juniper/connection.rb
+- lib/train-juniper/connection/bastion_proxy.rb
+- lib/train-juniper/connection/command_executor.rb
+- lib/train-juniper/connection/error_handling.rb
+- lib/train-juniper/connection/ssh_session.rb
+- lib/train-juniper/connection/validation.rb
+- lib/train-juniper/constants.rb
+- lib/train-juniper/file_abstraction/juniper_file.rb
+- lib/train-juniper/helpers/environment.rb
+- lib/train-juniper/helpers/logging.rb
+- lib/train-juniper/helpers/mock_responses.rb
 - lib/train-juniper/platform.rb
 - lib/train-juniper/transport.rb
 - lib/train-juniper/version.rb