train-juniper 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4428bf34013845866814e344ce4f67460a6af1a70fc33f33641a9412fee9dccb
-  data.tar.gz: 40f7a51485657e5616c744fa379283c8c0dfc1dbaa6d3a307ac4e9c909884d0d
+  metadata.gz: abb9487cdbf492d9b94f9b45699e2a434095509e128d5928863e5fdff3c73241
+  data.tar.gz: 0d9d6746cb16f185eef54b199aaf02b4509e66cc9292af3475913bae89f3e36c
 SHA512:
-  metadata.gz: 31d2993f5e85a04ff1c1940644242df90e1c19066339eb8be395ec1378767fce53958278318f58e1fea7a51c0ea5f0923f5447f8f204f5b374e4e8ca6e4d91bd
-  data.tar.gz: f0da0acd3ea9398723a62cbb5a5f73a9af010c440218a7a01f62ba2f4071eb33833d7d284b5e4b55d166f0e61c3b47988bd85cd3854dad6eb00f2155551b1dd0
+  metadata.gz: 8c7c246e820daa1d436c03d4f95e7acab6bef59c600c9f18d99fcc94b63989a0adf00a483661fc362db634871446b469aa0bed753a6852b40d2da768709882d8
+  data.tar.gz: db80d5fdefcb80294734f162b67f48f21219859ebed3ee294bcb1449876be0a7c7758e4ed613c8fc3e40a9d7d67c25df12316cc56e31352dc648eda2c8184c59

data/CHANGELOG.md

@@ -5,23 +5,40 @@ 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.6.2] - 2025-06-18
+## [0.7.0] - 2025-06-23
+
+### Added
+
+- Add security enhancements and input validation
+- V0.7.0 - enhanced security, YARD docs, and Windows support
+
+### Documentation
+
+- Update roadmap and fix documentation issues
 
 ### Fixed
 
-- Fix Windows installation issue by relaxing FFI dependency to match InSpec 7 (>= 1.15.5, < 1.17.0) (#2)
-- Fix mock mode platform detection to correctly show JunOS version instead of gem version
-- Update release workflow to use trusted publishing with OIDC authentication
-- Update workflows to use Ruby 3.3 for improved trusted publishing support
+- Empty environment variables no longer override CLI flags
+- Remove Brakeman from security tasks
 
-### Added
+### Miscellaneous Tasks
 
-- Add `mock?` method to properly support mock mode in platform detection
-- Add comprehensive mock mode documentation to README
+- Update .gitignore for untracked files
 
-### Changed
+### Refactor
+
+- Apply DRY principles throughout codebase
+- Extract common version detection pattern
+
+### Styling
+
+- Fix RuboCop offenses in connection files
+
+## [0.6.2] - 2025-06-19
+
+### Fixed
 
-- Update release process documentation to reflect trusted publishing setup
+- Windows FFI compatibility and mock mode platform detection
 
 ## [0.6.1] - 2025-06-18
 

data/README.md

@@ -64,9 +64,9 @@ $ inspec detect -t juniper://admin@192.168.1.1 --password yourpassword
 
 == Platform Details
 Name:      juniper
-Families:  network
+Families:  bsd
 Release:   21.4R3-S1.6
-Arch:      network
+Arch:      x86_64
 
 # Interactive shell
 $ inspec shell -t juniper://admin@192.168.1.1 --password yourpassword
@@ -77,23 +77,29 @@ inspec> command('show version').stdout
 ### With Bastion Host (Jump Host)
 
 ```bash
-# Using Train standard bastion host options
-$ inspec shell -t "juniper://admin@10.1.1.1?bastion_host=jump.example.com&bastion_user=netadmin&bastion_password=jumppass"
+# Simplified: Same username/password for bastion and device (most common)
+$ inspec shell -t juniper://admin@10.1.1.1 --password yourpassword \
+    --bastion-host jump.example.com
+
+# Different credentials for bastion and device
+$ inspec shell -t juniper://admin@10.1.1.1 --password device_password \
+    --bastion-host jump.example.com --bastion-user netadmin \
+    --bastion-password jump_password
 
 # With custom port
-$ inspec shell -t "juniper://admin@10.1.1.1?bastion_host=jump.example.com&bastion_user=netadmin&bastion_port=2222&bastion_password=jumppass"
+$ inspec shell -t juniper://admin@10.1.1.1 --password yourpassword \
+    --bastion-host jump.example.com --bastion-port 2222
 
 # Using environment variables (recommended for automation)
 export JUNIPER_BASTION_HOST=jump.example.com
-export JUNIPER_BASTION_USER=netadmin  
-export JUNIPER_BASTION_PASSWORD=jump_password
-export JUNIPER_PASSWORD=device_password
+export JUNIPER_PASSWORD=shared_password  # Used for both bastion and device
 $ inspec shell -t juniper://admin@10.1.1.1
 
-# Same password for both bastion and device (common scenario)
+# Different passwords via environment
 export JUNIPER_BASTION_HOST=jump.example.com
-export JUNIPER_BASTION_USER=admin
-export JUNIPER_PASSWORD=shared_password  # Used for both when bastion_password not set
+export JUNIPER_BASTION_USER=netadmin  
+export JUNIPER_BASTION_PASSWORD=jump_password
+export JUNIPER_PASSWORD=device_password
 $ inspec shell -t juniper://admin@10.1.1.1
 ```
 
@@ -135,6 +141,16 @@ inspec detect -t juniper://  # Reads from .env automatically
 
 ## Configuration Options
 
+### Option Priority
+
+The plugin uses the following priority order for configuration values:
+
+1. **Command-line flags** (highest priority) - e.g., `--bastion-user`
+2. **Environment variables** - e.g., `JUNIPER_BASTION_USER`  
+3. **Defaults/Fallbacks** (lowest priority) - e.g., bastion_user falls back to main user
+
+This allows maximum flexibility while providing sensible defaults for common scenarios.
+
 ### Connection Options
 
 | Option | Description | Default | Environment Variable |
@@ -152,7 +168,7 @@ inspec detect -t juniper://  # Reads from .env automatically
 | Option | Description | Default | Environment Variable |
 |--------|-------------|---------|---------------------|
 | `bastion_host` | SSH bastion/jump host | - | `JUNIPER_BASTION_HOST` |
-| `bastion_user` | SSH bastion username | root | `JUNIPER_BASTION_USER` |
+| `bastion_user` | SSH bastion username | Falls back to main `user` | `JUNIPER_BASTION_USER` |
 | `bastion_port` | SSH bastion port | 22 | `JUNIPER_BASTION_PORT` |
 | `bastion_password` | Password for bastion authentication | - | `JUNIPER_BASTION_PASSWORD` |
 | `proxy_command` | Custom SSH ProxyCommand | - | `JUNIPER_PROXY_COMMAND` |
@@ -161,7 +177,8 @@ inspec detect -t juniper://  # Reads from .env automatically
 
 **Notes**: 
 - Cannot specify both `bastion_host` and `proxy_command` simultaneously
-- If `bastion_password` not provided, falls back to using `password` for bastion authentication
+- If `bastion_user` not provided, falls back to using main `user` for bastion authentication
+- If `bastion_password` not provided, falls back to using main `password` for bastion authentication
 - Supports automated password authentication via SSH_ASKPASS mechanism
 
 ### InSpec Configuration File

data/Rakefile

@@ -33,14 +33,8 @@ end
 require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new(:lint) do |t|
-  # Choices of rubocop rules to enforce are deeply personal.
-  # Here, we set things up so that your plugin will use the Bundler-installed
-  # train gem's copy of the Train project's rubocop.yml file (which
-  # is indeed packaged with the train gem).
-  require 'train/globals'
-  train_rubocop_yml = File.join(Train.src_root, '.rubocop.yml')
-
-  t.options = ['--display-cop-names', '--config', train_rubocop_yml]
+  # Use our local .rubocop.yml configuration
+  t.options = ['--display-cop-names', '--config', '.rubocop.yml']
 end
 
 #------------------------------------------------------------------#
@@ -70,11 +64,7 @@ task 'security:secrets' do
   end
 end
 
-desc 'Run Brakeman security vulnerability scan'
-task 'security:brakeman' do
-  puts 'Running Brakeman security scan...'
-  system('bundle exec brakeman --exit-on-warn --quiet --force') or abort('Security vulnerabilities found')
-end
+# Brakeman removed - it's for Rails apps, not Ruby gems
 
 desc 'Run comprehensive security scan'
 task 'security:scan' do
@@ -83,7 +73,7 @@ task 'security:scan' do
 end
 
 desc 'Run all security checks'
-task security: %w[security:dependencies security:brakeman test:security]
+task security: %w[security:dependencies test:security]
 
 desc 'Run all tests including security'
 task 'test:all' => %w[test security]
@@ -93,6 +83,23 @@ task 'test:all' => %w[test security]
 #------------------------------------------------------------------#
 Dir['tasks/*.rake'].each { |f| load f }
 
+#------------------------------------------------------------------#
+#                    Documentation Tasks
+#------------------------------------------------------------------#
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.files = ['lib/**/*.rb']
+    t.options = ['--no-private']
+    t.stats_options = ['--list-undoc']
+  end
+rescue LoadError
+  desc 'YARD documentation task'
+  task :yard do
+    puts 'YARD is not available. Run `bundle install` to install it.'
+  end
+end
+
 #------------------------------------------------------------------#
 #                    Bundler Gem Tasks
 #------------------------------------------------------------------#

data/lib/train-juniper/connection.rb

@@ -28,22 +28,51 @@ module TrainPlugins
 
       attr_reader :ssh_session
 
+      # Configuration mapping for environment variables
+      ENV_CONFIG = {
+        host: { env: 'JUNIPER_HOST' },
+        user: { env: 'JUNIPER_USER' },
+        password: { env: 'JUNIPER_PASSWORD' },
+        port: { env: 'JUNIPER_PORT', type: :int, default: 22 },
+        timeout: { env: 'JUNIPER_TIMEOUT', type: :int, default: 30 },
+        bastion_host: { env: 'JUNIPER_BASTION_HOST' },
+        bastion_user: { env: 'JUNIPER_BASTION_USER' },
+        bastion_port: { env: 'JUNIPER_BASTION_PORT', type: :int, default: 22 },
+        bastion_password: { env: 'JUNIPER_BASTION_PASSWORD' },
+        proxy_command: { env: 'JUNIPER_PROXY_COMMAND' }
+      }.freeze
+
+      # Initialize a new Juniper connection
+      # @param options [Hash] Connection options
+      # @option options [String] :host The hostname or IP address of the Juniper device
+      # @option options [String] :user The username for authentication
+      # @option options [String] :password The password for authentication (optional if using key_files)
+      # @option options [Integer] :port The SSH port (default: 22)
+      # @option options [Integer] :timeout Connection timeout in seconds (default: 30)
+      # @option options [String] :bastion_host Jump/bastion host for connection
+      # @option options [String] :proxy_command SSH proxy command
+      # @option options [Logger] :logger Custom logger instance
+      # @option options [Boolean] :mock Enable mock mode for testing
       def initialize(options)
         # Configure SSH connection options for Juniper devices
         # Support environment variables for authentication (following train-vsphere pattern)
         @options = options.dup
-        @options[:host] ||= ENV.fetch('JUNIPER_HOST', nil)
-        @options[:user] ||= ENV.fetch('JUNIPER_USER', nil)
-        @options[:password] ||= ENV.fetch('JUNIPER_PASSWORD', nil)
-        @options[:port] ||= ENV['JUNIPER_PORT']&.to_i || 22
-        @options[:timeout] ||= ENV['JUNIPER_TIMEOUT']&.to_i || 30
-
-        # Proxy/bastion environment variables (Train standard)
-        # Only set from environment if not explicitly provided
-        @options[:bastion_host] = @options[:bastion_host] || ENV.fetch('JUNIPER_BASTION_HOST', nil)
-        @options[:bastion_user] = @options[:bastion_user] || ENV['JUNIPER_BASTION_USER'] || 'root'
-        @options[:bastion_port] = @options[:bastion_port] || ENV['JUNIPER_BASTION_PORT']&.to_i || 22
-        @options[:proxy_command] = @options[:proxy_command] || ENV.fetch('JUNIPER_PROXY_COMMAND', nil)
+
+        # Apply environment variable configuration using DRY approach
+        ENV_CONFIG.each do |key, config|
+          # Skip if option already has a value from command line
+          next if @options[key]
+
+          # Get value from environment
+          env_val = config[:type] == :int ? env_int(config[:env]) : env_value(config[:env])
+
+          # Only apply env value if it exists, otherwise use default (but not for nil CLI values)
+          if env_val
+            @options[key] = env_val
+          elsif !@options.key?(key) && config[:default]
+            @options[key] = config[:default]
+          end
+        end
 
         @options[:keepalive] = true
         @options[:keepalive_interval] = 60
@@ -55,14 +84,11 @@ module TrainPlugins
         @cli_prompt = /[%>$#]\s*$/
         @config_prompt = /[%#]\s*$/
 
-        # Log connection info without exposing credentials
-        safe_options = @options.except(:password, :proxy_command, :key_files)
-        @logger.debug("Juniper connection initialized with options: #{safe_options.inspect}")
-        @logger.debug("Environment: JUNIPER_BASTION_USER=#{ENV.fetch('JUNIPER_BASTION_USER',
-                                                                     nil)} -> bastion_user=#{@options[:bastion_user]}")
+        # Log connection info safely
+        log_connection_info
 
-        # Validate proxy configuration early (Train standard)
-        validate_proxy_options
+        # Validate all connection options
+        validate_connection_options!
 
         super(@options)
 
@@ -80,42 +106,65 @@ module TrainPlugins
         to_s
       end
 
-      # File operations for Juniper configuration files
-      # Supports reading configuration files and operational data
+      # Access Juniper configuration and operational data as pseudo-files
+      # @param path [String] The pseudo-file path to access
+      # @return [JuniperFile] A file-like object for accessing Juniper data
+      # @example Access interface configuration
+      #   file = connection.file('/config/interfaces')
+      #   puts file.content
+      # @example Access operational data
+      #   file = connection.file('/operational/interfaces')
+      #   puts file.content
       def file_via_connection(path)
         # For Juniper devices, "files" are typically configuration sections
         # or operational command outputs rather than traditional filesystem paths
         JuniperFile.new(self, path)
       end
 
-      # File transfer operations (following network device pattern)
-      # Network devices don't support traditional file upload/download
-      # Use run_command() for configuration management instead
+      # Upload files to Juniper device (not supported)
+      # @param locals [String, Array<String>] Local file path(s)
+      # @param remote [String] Remote destination path
+      # @raise [NotImplementedError] Always raises as uploads are not supported
+      # @note Network devices use command-based configuration instead of file uploads
       def upload(locals, remote)
         raise NotImplementedError, "#{self.class} does not implement #upload() - network devices use command-based configuration"
       end
 
+      # Download files from Juniper device (not supported)
+      # @param remotes [String, Array<String>] Remote file path(s)
+      # @param local [String] Local destination path
+      # @raise [NotImplementedError] Always raises as downloads are not supported
+      # @note Use run_command() to retrieve configuration data instead
       def download(remotes, local)
         raise NotImplementedError, "#{self.class} does not implement #download() - use run_command() to retrieve configuration data"
       end
 
       # 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)
-        return mock_command_result(cmd) if @options[:mock]
+        # Sanitize command to prevent injection
+        safe_cmd = sanitize_command(cmd)
+
+        return mock_command_result(safe_cmd) if @options[:mock]
 
         begin
           # Ensure we're connected
           connect unless connected?
 
-          @logger.debug("Executing command: #{cmd}")
+          @logger.debug("Executing command: #{safe_cmd}")
 
           # Execute command via SSH session
-          output = @ssh_session.exec!(cmd)
+          output = @ssh_session.exec!(safe_cmd)
 
           @logger.debug("Command output: #{output}")
 
           # Format JunOS result
-          format_junos_result(output, cmd)
+          format_junos_result(output, safe_cmd)
         rescue StandardError => e
           @logger.error("Command execution failed: #{e.message}")
           # Handle connection errors gracefully
@@ -123,17 +172,91 @@ module TrainPlugins
         end
       end
 
-      # JunOS error patterns from implementation plan
-      JUNOS_ERROR_PATTERNS = [
-        /^error:/i,
-        /syntax error/i,
-        /invalid command/i,
-        /unknown command/i,
-        /missing argument/i
+      # 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
+
+      # 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
+
+      # Mock response configuration
+      MOCK_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
+
+      # 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
 
+      # Check connection health
+      # @return [Boolean] true if connection is healthy, false otherwise
+      # @example
+      #   if connection.healthy?
+      #     puts "Connection is healthy"
+      #   end
+      def healthy?
+        return false unless connected?
+
+        result = run_command_via_connection('show version')
+        result.exit_status.zero?
+      rescue StandardError
+        false
+      end
+
+      # List of sensitive option keys to redact in logs
+      SENSITIVE_OPTIONS = %i[password bastion_password key_files proxy_command].freeze
+      private_constant :SENSITIVE_OPTIONS
+
       private
 
+      # Log connection info without exposing sensitive data
+      def log_connection_info
+        safe_options = @options.except(*SENSITIVE_OPTIONS)
+        @logger.debug("Juniper connection initialized with options: #{safe_options.inspect}")
+        @logger.debug("Environment: JUNIPER_BASTION_USER=#{env_value('JUNIPER_BASTION_USER')} -> bastion_user=#{@options[:bastion_user]}")
+      end
+
+      # 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
+
       # Establish SSH connection to Juniper device
       def connect
         return if connected?
@@ -145,28 +268,15 @@ module TrainPlugins
 
           @logger.debug('Establishing SSH connection to Juniper device')
 
-          ssh_options = {
-            port: @options[:port] || 22,
-            password: @options[:password],
-            timeout: @options[:timeout] || 30,
-            verify_host_key: :never,
-            keepalive: @options[:keepalive],
-            keepalive_interval: @options[:keepalive_interval]
-          }
-
-          # Add SSH key authentication if specified
-          if @options[:key_files]
-            ssh_options[:keys] = Array(@options[:key_files])
-            ssh_options[:keys_only] = @options[:keys_only]
-          end
+          ssh_options = build_ssh_options
 
           # Add bastion host support if configured
           if @options[:bastion_host]
             require 'net/ssh/proxy/jump' unless defined?(Net::SSH::Proxy::Jump)
 
             # Build proxy jump string from bastion options
-            bastion_user = @options[:bastion_user] || 'root'
-            bastion_port = @options[:bastion_port] || 22
+            bastion_user = @options[:bastion_user] || @options[:user] # Use explicit bastion user or fallback to main user
+            bastion_port = @options[:bastion_port]
 
             proxy_jump = if bastion_port == 22
                            "#{bastion_user}@#{@options[:bastion_host]}"
@@ -286,8 +396,76 @@ module TrainPlugins
         lines.join("\n")
       end
 
+      # Helper method to safely get environment variable value
+      # Returns nil if env var is not set or is empty string
+      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
+      def env_int(key)
+        value = env_value(key)
+        return nil unless value
+
+        value.to_i
+      rescue ArgumentError
+        nil
+      end
+
+      # 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
+
+      # 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!
+        port = @options[:port].to_i
+        raise Train::ClientError, "Invalid port: #{@options[:port]} (must be 1-65535)" unless port.between?(1, 65_535)
+      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!
+        port = @options[:bastion_port].to_i
+        raise Train::ClientError, "Invalid bastion_port: #{@options[:bastion_port]} (must be 1-65535)" unless port.between?(1, 65_535)
+      end
+
       # Validate proxy configuration options (Train standard)
-      def validate_proxy_options
+      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'
@@ -340,19 +518,11 @@ module TrainPlugins
 
       # Mock command execution for testing
       def mock_command_result(cmd)
-        case cmd
-        when /show version/
-          CommandResult.new(mock_show_version_output, '', 0)
-        when /show chassis hardware/
-          CommandResult.new(mock_chassis_output, '', 0)
-        when /show configuration/
-          CommandResult.new("interfaces {\n    ge-0/0/0 {\n        unit 0;\n    }\n}", '', 0)
-        when /show route/
-          CommandResult.new("inet.0: 5 destinations, 5 routes\n0.0.0.0/0       *[Static/5] 00:00:01\n", '', 0)
-        when /show system information/
-          CommandResult.new("Hardware: SRX240H2\nOS: JUNOS 12.1X47-D15.4\n", '', 0)
-        when /show interfaces/
-          CommandResult.new("Physical interface: ge-0/0/0, Enabled, Physical link is Up\n", '', 0)
+        response = MOCK_RESPONSES.find { |pattern, _| cmd.match?(/#{pattern}/) }
+
+        if response
+          output = response[1].is_a?(Symbol) ? send(response[1]) : response[1]
+          CommandResult.new(output, '', 0)
         else
           CommandResult.new("% Unknown command: #{cmd}", '', 1)
         end
@@ -380,11 +550,19 @@ module TrainPlugins
 
     # File abstraction for Juniper configuration and operational data
     class JuniperFile
+      # Initialize a new JuniperFile
+      # @param connection [Connection] The Juniper connection instance
+      # @param path [String] The virtual file path
       def initialize(connection, path)
         @connection = connection
         @path = path
       end
 
+      # Get the content of the virtual file
+      # @return [String] The command output based on the path
+      # @example
+      #   file = connection.file('/config/interfaces')
+      #   file.content  # Returns output of 'show configuration interfaces'
       def content
         # For Juniper devices, translate file paths to appropriate commands
         case @path

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)
@@ -45,67 +48,66 @@ module TrainPlugins::Juniper
 
     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
+        return instance_variable_set(cache_var, nil) unless connected?
 
-        # Execute 'show version' command to get JunOS information
-        logger&.debug("Running 'show version' command")
-        result = run_command_via_connection('show version')
+        # 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?
 
-        unless result&.exit_status&.zero?
-          logger&.debug("Command failed with exit status: #{result&.exit_status}")
-          return @detected_junos_version = nil
-        end
-
-        # 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 +119,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.0'
   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.0
 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.