train-juniper 0.7.1 → 0.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86bf86dd54cabe94e072c6e3a2b64ffcdfbdf774a5f33f1a3a76012829dd71bc
-  data.tar.gz: c2e5d2fe1ecfa259f78c2d80f76d94eaa68afb817d584c57d02bfb4c46779924
+  metadata.gz: 6da9bb07db2daaa3ca21d2fef18b0a200ff15597495dece758e0e509d10c13ad
+  data.tar.gz: 86e802113118c172748e2187e09db4c95c080f393dc083932a65386d19c82f3c
 SHA512:
-  metadata.gz: 168356b0c2a48f7b4817acb535571c2b651d12365dc7340c96c9b2b2d6db30981516683c29965bd295459d8cbb2b2625e020a35789a3bbed4d295ce29712264e
-  data.tar.gz: 8a209708671652728890ff96f75b3a2da922f37f93c61896881e99b387adc15ecc1e889d6e416637dc0eee011ed1f1b9b0fcd33b99c2bacfe15f2736daaa9da8
+  metadata.gz: 0137dee8f2547f0973d2e513491574e624f55a605993ca8e6211e1c84c77341fe840d45704903e25eaeacb6e043b1846556f2f124ee08863c591357e34c37ecb
+  data.tar.gz: ddd016a7cf4cc47d68e9e0f89283d874ea563abab20cc6f2e822d67658694bac3782d3cef0ef4f2a1976bfbf4b2a8652050ff87c9b9d13c18864a5c26a169482

data/.env.example

@@ -1,29 +1,16 @@
-# Train-Juniper Environment Variables Example
-# Copy this file to .env and fill in your actual values
-# The plugin automatically detects these environment variables
+# Example .env file for Windows testing
+# Copy this to .env and fill in your actual values
 
-# Juniper Device Connection
-JUNIPER_HOST=your.device.hostname.com
-JUNIPER_USER=your_username
-JUNIPER_PASSWORD=your_password
-JUNIPER_PORT=22
-JUNIPER_TIMEOUT=60
+# Target Juniper device (behind bastion)
+JUNIPER_HOST=192.168.1.100
+JUNIPER_USER=admin
+JUNIPER_PASSWORD=device_password
 
-# Bastion/Jump Host (optional - only if device is behind jump host)
-JUNIPER_BASTION_HOST=your.jumphost.com
-JUNIPER_BASTION_USER=your_jump_username
-JUNIPER_BASTION_PORT=22
-JUNIPER_BASTION_PASSWORD=your_jump_password
+# Bastion/Jump host
+BASTION_HOST=bastion.example.com
+BASTION_USER=jumpuser
+BASTION_PASSWORD=bastion_password
 
-# Custom Proxy Command (alternative to bastion host)
-# JUNIPER_PROXY_COMMAND=ssh your.jumphost.com -W %h:%p
-
-# Usage Examples:
-# 1. Basic connection (auto-detects above variables):
-#    inspec detect -t juniper://
-#
-# 2. Override specific values:
-#    inspec detect -t juniper://different_user@different_host --password override_pass
-#
-# 3. Test connection:
-#    source .env && inspec detect -t juniper:// -l debug
+# Optional: Custom ports
+# JUNIPER_PORT=22
+# BASTION_PORT=22

data/CHANGELOG.md

@@ -5,6 +5,59 @@ 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.4] - 2025-06-24
+
+### Added
+
+- Add Windows plink.exe support for bastion authentication
+
+### Documentation
+
+- Add Windows bastion setup guide and improve navigation
+- Fix MkDocs link warnings
+- Add host key acceptance instructions and InSpec testing examples
+- Improve Windows documentation and standardize on inspec shell
+
+### Miscellaneous Tasks
+
+- Fix linting issues in Windows test script
+
+### Testing
+
+- Add Windows testing scripts and guide
+- Add .env file support to Windows test scripts
+
+## [0.7.3] - 2025-06-23
+
+### Documentation
+
+- Improve README structure for better MkDocs rendering
+- Add platform support section to README
+
+### Fixed
+
+- Follow standard RubyGems conventions for gem packaging
+- Remove .md extensions from internal MkDocs links
+- **docs**: Improve Support section formatting with subsections
+- **windows**: Use PowerShell for SSH_ASKPASS on Windows and add cross-platform CI/CD
+- **ci**: Add comprehensive platform support for cross-platform compatibility
+- Update ffi dependency to support Ruby 3.3 on Windows
+- Handle Windows PowerShell script paths in bastion proxy tests
+- Use direct gem push instead of rubygems/release-gem action
+- Complete release workflow implementation
+
+### Miscellaneous Tasks
+
+- Add session.md to .gitignore
+
+### Styling
+
+- Fix trailing whitespace in bastion proxy files
+
+### Testing
+
+- Add nocov markers for Windows-specific PowerShell code
+
 ## [0.7.1] - 2025-06-23
 
 ### Added
@@ -26,6 +79,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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
+- Resolve RuboCop violations for CI/CD compliance
+- Update release task to handle GitHub Actions gem publishing
+- Resolve final RuboCop issues in release task
 
 ### Miscellaneous Tasks
 

data/README.md

@@ -175,11 +175,11 @@ This allows maximum flexibility while providing sensible defaults for common sce
 | `key_files` | SSH private key files | - | - |
 | `keys_only` | Use only specified keys | false | - |
 
-**Notes**: 
-- Cannot specify both `bastion_host` and `proxy_command` simultaneously
-- 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
+!!! note "Important Configuration Notes"
+    - Cannot specify both `bastion_host` and `proxy_command` simultaneously
+    - 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
 
@@ -280,7 +280,8 @@ Train.create('juniper', {
 
 ### Common Authentication Issues
 
-#### ❌ **Error**: "No bastion password specified"
+#### ❌ Error: "No bastion password specified"
+
 **Solution**: Train doesn't have `--bastion-password`. Use one of these patterns:
 ```bash
 # Same password for both (most common)
@@ -293,7 +294,8 @@ inspec detect -t "juniper://user@device?bastion_host=jump" --key-files ~/.ssh/id
 inspec detect -t "juniper://user@device?proxy_command=sshpass%20-p%20jumppass%20ssh%20jumpuser@jump%20-W%20%h:%p" --password "device_pass"
 ```
 
-#### ❌ **Error**: "Authentication failed"
+#### ❌ Error: "Authentication failed"
+
 **Solutions**:
 ```bash
 # Verify bastion connection first
@@ -309,7 +311,8 @@ inspec detect -t "juniper://user@device?bastion_host=jump&proxy_command=ssh%20-v
 inspec detect -t "juniper://user@device?bastion_host=jump" --password "pass" -l debug
 ```
 
-#### ❌ **Error**: "Connection timeout"
+#### ❌ Error: "Connection timeout"
+
 **Solutions**:
 ```bash
 # Increase timeouts
@@ -349,6 +352,7 @@ result = connection.run_command('show version')
 ```
 
 Mock mode provides:
+
 - ✅ Realistic JunOS command outputs
 - ✅ Platform detection (JunOS 12.1X47-D15.4)
 - ✅ Error simulation for negative testing
@@ -393,10 +397,30 @@ This plugin implements the Train Plugin V1 API with:
 - **Platform** (`lib/train-juniper/platform.rb`) - JunOS platform detection
 - **Version** (`lib/train-juniper/version.rb`) - Plugin version management
 
+### Platform Support
+
+This gem supports a wide range of platforms to ensure maximum compatibility:
+
+| Platform | Description | Use Case |
+|----------|-------------|----------|
+| `ruby` | Platform-independent | Pure Ruby installations |
+| `x86_64-linux` | Standard Linux | Most Linux servers and CI/CD |
+| `aarch64-linux` | ARM64 Linux | AWS Graviton, Raspberry Pi |
+| `x86_64-linux-musl` | Alpine Linux | Docker containers |
+| `x86_64-darwin` | Intel macOS | Older Mac workstations |
+| `arm64-darwin-*` | Apple Silicon macOS | Modern Mac workstations |
+| `x64-mingw-ucrt` | Windows (UCRT) | Windows 10/11 with modern Ruby ([bastion setup](windows-bastion-setup.md)) |
+| `x86_64-freebsd` | FreeBSD | Network appliances (JunOS heritage) |
+| `x86_64-solaris` | Solaris/illumos | Enterprise environments |
+
+!!! note "Platform Compatibility"
+    This comprehensive platform support ensures the plugin works wherever InSpec runs, from developer workstations to CI/CD pipelines to production jump hosts. The FreeBSD support is particularly relevant given that JunOS is based on FreeBSD.
+
 ### Documentation
 
 - **[Installation Guide](installation.md)** - Complete installation instructions
 - **[Basic Usage](basic-usage.md)** - Getting started with the plugin
+- **[Windows Bastion Setup](windows-bastion-setup.md)** - Windows bastion/jump host authentication guide
 - **[Release Process](RELEASE_PROCESS.md)** - How to cut releases and publish gems
 - **[Project Roadmap](ROADMAP.md)** - Future development plans and contribution opportunities
 
@@ -407,19 +431,29 @@ This plugin implements the Train Plugin V1 API with:
 
 ## Contributing
 
+We welcome contributions! Here's how to get started:
+
 1. Fork the repository
-2. Create a feature branch
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
 3. Make your changes with tests
-4. Run `bundle exec rake test` 
+4. Run `bundle exec rake test` to ensure tests pass
 5. Submit a pull request
 
+Please see our [Contributing Guide](CONTRIBUTING.md) for more details.
+
 ## Support and Contact
 
+### General Support
+
 For questions, feature requests, or general support:
+
 - Email: [saf@mitre.org](mailto:saf@mitre.org)
 - GitHub Issues: [https://github.com/mitre/train-juniper/issues](https://github.com/mitre/train-juniper/issues)
 
+### Security Issues
+
 For security issues or vulnerabilities:
+
 - Email: [saf-security@mitre.org](mailto:saf-security@mitre.org)
 - GitHub Security: [https://github.com/mitre/train-juniper/security](https://github.com/mitre/train-juniper/security)
 

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

@@ -1,26 +1,41 @@
 # frozen_string_literal: true
 
 require 'train-juniper/constants'
+require 'train-juniper/connection/windows_proxy'
+require 'train-juniper/connection/ssh_askpass'
 
 module TrainPlugins
   module Juniper
     # Handles bastion host proxy configuration and authentication
     module BastionProxy
+      include WindowsProxy
+      include SshAskpass
+
       # 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]
+        bastion_password = @options[:bastion_password] || @options[:password]
 
-        proxy_jump = if bastion_port == Constants::DEFAULT_SSH_PORT
-                       "#{bastion_user}@#{@options[:bastion_host]}"
-                     else
-                       "#{bastion_user}@#{@options[:bastion_host]}:#{bastion_port}"
-                     end
+        # On Windows with password auth, use plink.exe if available
+        if Gem.win_platform? && bastion_password && plink_available?
+          configure_plink_proxy(ssh_options, bastion_user, bastion_port, bastion_password)
+        else
+          configure_standard_proxy(ssh_options, bastion_user, bastion_port)
+        end
+      end
+
+      private
+
+      # Configure standard SSH proxy using Net::SSH::Proxy::Jump
+      # @param ssh_options [Hash] SSH options to modify
+      # @param bastion_user [String] Username for bastion
+      # @param bastion_port [Integer] Port for bastion
+      def configure_standard_proxy(ssh_options, bastion_user, bastion_port)
+        require 'net/ssh/proxy/jump' unless defined?(Net::SSH::Proxy::Jump)
 
+        proxy_jump = build_proxy_jump_string(bastion_user, bastion_port)
         @logger.debug("Using bastion host: #{proxy_jump}")
 
         # Set up automated password authentication via SSH_ASKPASS
@@ -29,30 +44,35 @@ module TrainPlugins
         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')
+      # Configure plink.exe proxy for Windows password authentication
+      # @param ssh_options [Hash] SSH options to modify
+      # @param bastion_user [String] Username for bastion
+      # @param bastion_port [Integer] Port for bastion
+      # @param bastion_password [String] Password for bastion
+      def configure_plink_proxy(ssh_options, bastion_user, bastion_port, bastion_password)
+        require 'net/ssh/proxy/command' unless defined?(Net::SSH::Proxy::Command)
+
+        proxy_cmd = build_plink_proxy_command(
+          @options[:bastion_host],
+          bastion_user,
+          bastion_port,
+          bastion_password
+        )
+
+        @logger.debug('Using plink.exe for bastion proxy')
+        ssh_options[:proxy] = Net::SSH::Proxy::Command.new(proxy_cmd)
       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
+      # Build proxy jump string from bastion options
+      # @param bastion_user [String] Username for bastion
+      # @param bastion_port [Integer] Port for bastion
+      # @return [String] Proxy jump string
+      def build_proxy_jump_string(bastion_user, bastion_port)
+        if bastion_port == Constants::DEFAULT_SSH_PORT
+          "#{bastion_user}@#{@options[:bastion_host]}"
+        else
+          "#{bastion_user}@#{@options[:bastion_host]}:#{bastion_port}"
+        end
       end
 
       # Generate SSH proxy command for bastion host using ProxyJump (-J)
@@ -68,11 +88,7 @@ module TrainPlugins
         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
+        jump_host = build_proxy_jump_string(bastion_user, bastion_port)
         args += ['-J', jump_host]
 
         # Add SSH keys if specified

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+
+module TrainPlugins
+  module Juniper
+    # SSH_ASKPASS script management for automated password authentication
+    module SshAskpass
+      # 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)
+        if Gem.win_platform?
+          create_windows_askpass_script(password)
+        else
+          create_unix_askpass_script(password)
+        end
+      end
+
+      private
+
+      # Create Windows PowerShell script for SSH_ASKPASS
+      # @param password [String] The password to use
+      # @return [String] Path to the wrapper batch file
+      def create_windows_askpass_script(password)
+        # :nocov:
+        # Create Windows PowerShell script
+        script = Tempfile.new(['ssh_askpass', '.ps1'])
+        # PowerShell handles escaping better, just escape quotes
+        escaped_password = password.gsub("'", "''")
+        script.write("Write-Output '#{escaped_password}'\r\n")
+        script.close
+
+        # Create a wrapper batch file to execute PowerShell with bypass policy
+        wrapper = Tempfile.new(['ssh_askpass_wrapper', '.bat'])
+        wrapper.write("@echo off\r\npowershell.exe -ExecutionPolicy Bypass -File \"#{script.path}\"\r\n")
+        wrapper.close
+
+        @logger.debug("Created SSH_ASKPASS PowerShell script at #{script.path} with wrapper at #{wrapper.path}")
+        wrapper.path
+        # :nocov:
+      end
+
+      # Create Unix shell script for SSH_ASKPASS
+      # @param password [String] The password to use
+      # @return [String] Path to the created script
+      def create_unix_askpass_script(password)
+        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
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module TrainPlugins
+  module Juniper
+    # Windows-specific proxy handling using plink.exe
+    # This pattern is used by various Ruby projects for Windows SSH support,
+    # including hglib.rb (Mercurial) and follows Net::SSH::Proxy::Command patterns
+    module WindowsProxy
+      # Check if plink.exe is available on Windows
+      # @return [Boolean] true if plink.exe is found in PATH
+      def plink_available?
+        return false unless Gem.win_platform?
+
+        ENV['PATH'].split(File::PATH_SEPARATOR).any? do |path|
+          File.exist?(File.join(path, 'plink.exe'))
+        end
+      end
+
+      # Build plink.exe proxy command for Windows bastion authentication
+      # @param bastion_host [String] Bastion hostname
+      # @param user [String] Username for bastion
+      # @param port [Integer] Port for bastion
+      # @param password [String] Password for bastion
+      # @return [String] Complete plink command string
+      def build_plink_proxy_command(bastion_host, user, port, password)
+        parts = []
+        parts << 'plink.exe'
+        parts << '-batch' # Non-interactive mode
+        parts << '-ssh'   # Force SSH protocol (not telnet)
+        parts << '-pw'
+        parts << (password.include?(' ') ? "\"#{password}\"" : password)
+
+        if port && port != 22
+          parts << '-P'
+          parts << port.to_s
+        end
+
+        parts << "#{user}@#{bastion_host}"
+        parts << '-nc'
+        parts << '%h:%p' # Netcat mode for proxying
+
+        parts.join(' ')
+      end
+    end
+  end
+end

data/lib/train-juniper/version.rb

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

data/train-juniper.gemspec

@@ -68,8 +68,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'net-ssh', '>= 2.9', '< 8.0'
 
   # 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'
+  # Updated to support Ruby 3.3 on Windows (ffi 1.17.x required)
+  spec.add_dependency 'ffi', '>= 1.15.5', '< 1.18.0'
 
   # Development dependencies
   spec.add_development_dependency 'bundler', '~> 2.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: train-juniper
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.4
 platform: ruby
 authors:
 - MITRE Corporation
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-23 00:00:00.000000000 Z
+date: 2025-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: train-core
@@ -53,7 +53,7 @@ dependencies:
         version: 1.15.5
     - - "<"
       - !ruby/object:Gem::Version
-        version: 1.17.0
+        version: 1.18.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -63,7 +63,7 @@ dependencies:
         version: 1.15.5
     - - "<"
       - !ruby/object:Gem::Version
-        version: 1.17.0
+        version: 1.18.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -227,8 +227,10 @@ files:
 - 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_askpass.rb
 - lib/train-juniper/connection/ssh_session.rb
 - lib/train-juniper/connection/validation.rb
+- lib/train-juniper/connection/windows_proxy.rb
 - lib/train-juniper/constants.rb
 - lib/train-juniper/file_abstraction/juniper_file.rb
 - lib/train-juniper/helpers/environment.rb