shells 0.1.5

data/lib/shells/pf_sense_common.rb

@@ -0,0 +1,400 @@
+require 'base64'
+require 'json'
+
+module Shells
+
+  ##
+  # Common functionality for interacting with a pfSense device.
+  module PfSenseCommon
+
+    ##
+    # An error raised when we fail to navigate the pfSense menu.
+    class MenuNavigationFailure < Shells::ShellError
+
+    end
+
+    ##
+    # Failed to locate the public key.
+    class PublicKeyNotFound < Shells::ShellError
+
+    end
+
+    ##
+    # Failed to validate the public key.
+    class PublicKeyInvalid < Shells::ShellError
+
+    end
+
+    ##
+    # Failed to locate the user on the device.
+    class UserNotFound < Shells::ShellError
+
+    end
+
+    ##
+    # Signals that we want to restart the device.
+    class RestartNow < Exception
+
+    end
+
+
+    ##
+    # The base shell used when possible.
+    BASE_SHELL = '/bin/sh'
+
+    ##
+    # The pfSense shell itself.
+    PF_SHELL = '/usr/local/sbin/pfSsh.php'
+
+    ##
+    # The prompt in the pfSense shell.
+    PF_PROMPT = 'pfSense shell:'
+
+    ##
+    # Gets the version of the pfSense firmware.
+    attr_accessor :pf_sense_version
+
+    ##
+    # Gets the user currently logged into the pfSense device.
+    attr_accessor :pf_sense_user
+
+    ##
+    # Gets the hostname of the pfSense device.
+    attr_accessor :pf_sense_host
+
+
+    def line_ending #:nodoc:
+      "\n"
+    end
+
+    def self.included(base)  #:nodoc:
+
+      # Trap the RestartNow exception.
+      # When encountered, change the :quit option to '/sbin/reboot'.
+      # This requires rewriting the @options instance variable since the hash is frozen
+      # after initial validation.
+      base.on_exception do |shell, ex|
+        if ex.is_a?(Shells::PfSenseCommon::RestartNow)
+          shell.send(:change_quit, '/sbin/reboot')
+          true
+        else
+          false
+        end
+      end
+
+    end
+
+    def validate_options  #:nodoc:
+      super
+      options[:shell] = :shell
+      options[:prompt] = 'pfSense shell:'
+      options[:quit] = 'exit'
+      options[:retrieve_exit_code] = false
+      options[:on_non_zero_exit_code] = :ignore
+      options[:override_set_prompt] = ->(sh) { true }
+      options[:override_get_exit_code] = ->(sh) { 0 }
+    end
+
+    def exec_shell(&block) #:nodoc:
+      super do
+        # We want to drop to the shell before executing the block.
+        # So we'll navigate the menu to get the option for the shell.
+        # For this first navigation we allow a delay only if we are not connected to a serial device.
+        # Serial connections are always on, so they don't need to initialize first.
+        menu_option = get_menu_option 'Shell', !(Shells::SerialSession > self.class)
+        raise MenuNavigationFailure unless menu_option
+
+        # For 2.3 and 2.4 this is a valid match.
+        # If future versions change the default prompt, we need to change our process.
+        # [VERSION][USER@HOSTNAME]/root:  where /root is the current dir.
+        shell_regex = /\[(?<VER>[^\]]*)\]\[(?<USERHOST>[^\]]*)\](?<CD>\/.*):\s*$/
+
+        # Now we execute the menu option and wait for the shell_regex to match.
+        temporary_prompt(shell_regex) do
+          exec menu_option.to_s, command_timeout: 5
+
+          # Once we have a match we should be able to repeat it and store the information from the shell.
+          data = prompt_match.match(combined_output)
+          self.pf_sense_version = data['VER']
+          self.pf_sense_user, _, self.pf_sense_host = data['USERHOST'].partition('@')
+        end
+
+        block.call
+
+        # Wait for the shell_regex to match again.
+        temporary_prompt(shell_regex) { wait_for_prompt nil, 4, false }
+
+        # Exit the shell to return to the menu.
+        send_data 'exit' + line_ending
+
+        # After the block we want to know what the Logout option is and we change the quit command to match.
+        menu_option = get_menu_option 'Logout'
+        raise MenuNavigationFailure unless menu_option
+        change_quit menu_option.to_s
+      end
+    end
+
+    def exec_prompt(&block) #:nodoc:
+      debug 'Initializing pfSense shell...'
+      exec '/usr/local/sbin/pfSsh.php', command_timeout: 5
+      begin
+        block.call
+      ensure
+        debug 'Quitting pfSense shell...'
+        send_data 'exit' + line_ending
+      end
+    end
+
+    ##
+    # Executes a series of commands on the pfSense shell.
+    def pf_exec(*commands)
+      ret = ''
+      commands.each { |cmd| ret += exec(cmd) }
+      ret + exec('exec')
+    end
+
+    ##
+    # Reloads the pfSense configuration on the device.
+    def parse_config
+      pf_exec 'parse_config(true);'
+      @config_parsed = true
+    end
+
+    ##
+    # Determines if the configuration has been parsed during this session.
+    def config_parsed?
+      instance_variable_defined?(:@config_parsed) && instance_variable_get(:@config_parsed)
+    end
+
+    ##
+    # Gets a configuration section from the pfSense device.
+    def get_config_section(section_name)
+      parse_config unless config_parsed?
+      JSON.parse pf_exec("echo json_encode($config[#{section_name.to_s.inspect}]);").strip
+    end
+
+    ##
+    # Sets a configuration section to the pfSense device.
+    #
+    # Returns the number of changes made to the configuration.
+    def set_config_section(section_name, values, message = '')
+      current_values = get_config_section(section_name)
+      changes = generate_config_changes("$config[#{section_name.to_s.inspect}]", current_values, values)
+      if changes&.any?
+        if message.to_s.strip == ''
+          message = "Updating #{section_name} section."
+        end
+        changes << "write_config(#{message.inspect});"
+
+        pf_exec(*changes)
+
+        (changes.size - 1)
+      else
+        0
+      end
+    end
+
+    ##
+    # Apply the firewall configuration.
+    #
+    # You need to apply the firewall configuration after you make changes to aliases, NAT rules, or filter rules.
+    def apply_filter_config
+      pf_exec(
+          'require_once("shaper.inc");',
+          'require_once("filter.inc");',
+          'filter_configure_sync();'
+      )
+    end
+
+    ##
+    # Applies the user configuration for the specified user.
+    def apply_user_config(user_id)
+      user_id = user_id.to_i
+      pf_exec(
+          'require_once("auth.inc");',
+          "$user_entry = $config[\"system\"][\"user\"][#{user_id}];",
+          '$user_groups = array();',
+          'foreach ($config["system"]["group"] as $gidx => $group) {',
+          '  if (is_array($group["member"])) {',
+          "    if (in_array(#{user_id}, $group[\"member\"])) { $user_groups[] = $group[\"name\"]; }",
+          '  }',
+          '}',
+          # Intentionally run set_groups before and after to ensure group membership gets fully applied.
+          'local_user_set_groups($user_entry, $user_groups);',
+          'local_user_set($user_entry);',
+          'local_user_set_groups($user_entry, $user_groups);'
+      )
+    end
+
+    ##
+    # Enabled public key authentication for the current pfSense user.
+    #
+    # Once this has been done you should be able to connect without using a password.
+    def enable_cert_auth(public_key = '~/.ssh/id_rsa.pub')
+      cert_regex = /^ssh-[rd]sa (?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)? \S*$/m
+
+      # get our cert unless the user provided a full cert for us.
+      unless public_key =~ cert_regex
+        public_key = File.expand_path(public_key)
+        if File.exist?(public_key)
+          public_key = File.read(public_key).to_s.strip
+        else
+          raise Shells::PfSenseCommon::PublicKeyNotFound
+        end
+        raise Shells::PfSenseCommon::PublicKeyInvalid unless public_key =~ cert_regex
+      end
+
+      cfg = get_config_section 'system'
+      user_id = nil
+      user_name = options[:user].downcase
+      cfg['user'].each_with_index do |user,index|
+        if user['name'].downcase == user_name
+          user_id = index
+
+          authkeys = Base64.decode64(user['authorizedkeys'].to_s).gsub("\r\n", "\n").strip
+          unless authkeys == '' || authkeys =~ cert_regex
+            warn "Existing authorized keys for user #{options[:user]} are invalid and are being reset."
+            authkeys = ''
+          end
+
+          if authkeys == ''
+            user['authorizedkeys'] = Base64.strict_encode64(public_key)
+          else
+            authkeys = authkeys.split("\n")
+            unless authkeys.include?(public_key)
+              authkeys << public_key unless authkeys.include?(public_key)
+              user['authorizedkeys'] = Base64.strict_encode64(authkeys.join("\n"))
+            end
+          end
+
+          break
+        end
+      end
+
+
+      raise Shells::PfSenseCommon::UserNotFound unless user_id
+
+      set_config_section 'system', cfg, "Enable certificate authentication for #{options[:user]}."
+
+      apply_user_config user_id
+    end
+
+
+    ##
+    # Exits the shell session immediately and requests a reboot of the pfSense device.
+    def reboot
+      raise Shells::SessionCompleted if session_complete?
+      raise Shells::PfSenseCommon::RestartNow
+    end
+
+    ##
+    # Exits the shell session immediately.
+    def quit
+      raise Shells::SessionCompleted if session_complete?
+      raise Shells::ShellBase::QuitNow
+    end
+
+
+
+    private
+
+    def generate_config_changes(prefix, old_value, new_value)
+      old_value = fix_config_arrays(old_value)
+      new_value = fix_config_arrays(new_value)
+
+      if new_value.is_a?(Hash)
+        changes = []
+
+        unless old_value.is_a?(Hash)
+          # make sure the value is an array now.
+          changes << "#{prefix} = array();"
+          # and change the old_value to be an empty hash so we can work with it.
+          old_value = {}
+        end
+
+        # now iterate the hashes and process the child elements.
+        new_value.each do |k, new_v|
+          old_v = old_value[k]
+          changes += generate_config_changes("#{prefix}[#{k.inspect}]", old_v, new_v)
+        end
+
+        changes
+      else
+        if new_value != old_value
+          if new_value.nil?
+            [ "unset #{prefix};" ]
+          else
+            [ "#{prefix} = #{new_value.inspect};" ]
+          end
+        else
+          [ ]
+        end
+      end
+    end
+
+    def fix_config_arrays(value)
+      if value.is_a?(Array)
+        value.each_with_index
+            .map{|v,i| [i,v]}.to_h                      # convert to hash
+            .inject({}){ |m,(k,v)| m[k.to_s] = v; m }   # stringify keys
+      elsif value.is_a?(Hash)
+        value.inject({}) { |m,(k,v)| m[k.to_s] = v; m } # stringify keys
+      else
+        value
+      end
+    end
+
+
+
+    # Processes the pfSense console menu to determine the option to send.
+    def get_menu_option(option_text, delay = true)
+      option_regex = /\s(\d+)\)\s*#{option_text}\s/i
+      prompt_text = 'Enter an option:'
+
+      temporary_prompt prompt_text do
+        begin
+
+          # give the prompt a few seconds to draw.
+          if delay
+            wait_for_prompt(nil, 4, false)
+          end
+
+          # See if we have a menu already.
+          menu_regex = /(?<MENU>\s0\)(?:.|\r|\n(?!\s0\)))*)#{prompt_text}[ \t]*$/
+          match = menu_regex.match(combined_output)
+          menu = match ? match['MENU'] : nil
+
+          push_buffer
+
+          if menu.nil?
+            # We want to redraw the menu.
+            # In order to do that, we need to send a command that is not valid.
+            # A blank line equates to a zero, which is (probably) the logout option.
+            # So we'll send a -1 to redraw the menu without actually running any commands.
+            debug 'Redrawing menu...'
+            menu = exec('-1', command_timeout: 5, timeout_error: false)
+
+            if last_exit_code == :timeout
+              # If for some reason the shell is/was running, we need to exit it to return to the menu.
+              # This time we will raise an error.
+              menu = exec('exit', command_timeout: 5)
+            end
+          end
+
+          # Ok, so now we have our menu options.
+          debug "Locating 'XX) #{option_text}' menu option..."
+          match = option_regex.match(menu)
+          if match
+            return match[1].to_i
+          else
+            return nil
+          end
+        ensure
+          pop_discard_buffer
+        end
+      end
+    end
+
+
+  end
+end

data/lib/shells/pf_sense_serial_session.rb

@@ -0,0 +1,55 @@
+require 'shells/serial_session'
+require 'shells/pf_sense_common'
+
+module Shells
+
+  ##
+  # Executes a serial session with a pfSense host.
+  #
+  # Valid options:
+  # +path+::
+  #     The path to the serial device (e.g. - COM3 or /dev/tty2)
+  #     This is a required option.
+  # +speed+::
+  #     The bitrate for the connection.
+  #     The default is 115200.
+  # +data_bits+::
+  #     The number of data bits for the connection.
+  #     The default is 8.
+  # +parity+::
+  #     The parity for the connection.
+  #     The default is :none.
+  # +silence_timeout+::
+  #     When a command is executing, this is the maximum amount of time to wait for any feedback from the shell.
+  #     If set to 0 (or less) there is no timeout.
+  #     Unlike +command_timeout+ this value resets every time we receive feedback.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +command_timeout+::
+  #     When a command is executing, this is the maximum amount of time to wait for the command to finish.
+  #     If set to 0 (or less) there is no timeout.
+  #     Unlike +silence_timeout+ this value does not reset when we receive feedback.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  #
+  #   Shells::PfSenseSerialSession.new(
+  #       path: 'COM3'
+  #   ) do |shell|
+  #     cfg = shell.get_config_section("aliases")
+  #     cfg["alias"] ||= []
+  #     cfg["alias"] << {
+  #         :name => "MY_NETWORK",
+  #         :type => "network",
+  #         :address => "192.168.1.0/24",
+  #         :descr => "My home network",
+  #         :details => "Created #{Time.now.to_s}"
+  #     }
+  #     shell.set_config_section("aliases", cfg, "Add home network")
+  #     shell.apply_filter_config
+  #   end
+  #
+  class PfSenseSerialSession < SerialSession
+
+    include PfSenseCommon
+
+  end
+
+end

data/lib/shells/pf_sense_ssh_session.rb

@@ -0,0 +1,56 @@
+require 'shells/ssh_session'
+require 'shells/pf_sense_common'
+
+module Shells
+
+  ##
+  # Executes an SSH session with a pfSense host.
+  #
+  # Valid options:
+  # +host+::
+  #     The name or IP address of the host to connect to.  Defaults to 'localhost'.
+  # +port+::
+  #     The port on the host to connect to.  Defaults to 22.
+  # +user+::
+  #     The user to login with.  This option is required.
+  # +password+::
+  #     The password to login with.
+  #     If our public key is an authorized key on the host, the password is ignored.
+  # +silence_timeout+::
+  #     When a command is executing, this is the maximum amount of time to wait for any feedback from the shell.
+  #     If set to 0 (or less) there is no timeout.
+  #     Unlike +command_timeout+ this value resets every time we receive feedback.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +command_timeout+::
+  #     When a command is executing, this is the maximum amount of time to wait for the command to finish.
+  #     If set to 0 (or less) there is no timeout.
+  #     Unlike +silence_timeout+ this value does not reset when we receive feedback.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +connect_timeout+::
+  #     This is the maximum amount of time to wait for the initial connection to the SSH shell.
+  #
+  #   Shells::PfSenseSshSession.new(
+  #       host: '10.10.10.10',
+  #       user: 'somebody',
+  #       password: 'super-secret'
+  #   ) do |shell|
+  #     cfg = shell.get_config_section("aliases")
+  #     cfg["alias"] ||= []
+  #     cfg["alias"] << {
+  #         :name => "MY_NETWORK",
+  #         :type => "network",
+  #         :address => "192.168.1.0/24",
+  #         :descr => "My home network",
+  #         :details => "Created #{Time.now.to_s}"
+  #     }
+  #     shell.set_config_section("aliases", cfg, "Add home network")
+  #     shell.apply_filter_config
+  #   end
+  #
+  class PfSenseSshSession < SshSession
+
+    include PfSenseCommon
+
+  end
+
+end

data/lib/shells/serial_session.rb

@@ -0,0 +1,184 @@
+require 'rubyserial'
+require 'shells/shell_base'
+require 'shells/bash_common'
+
+module Shells
+  ##
+  # Executes a serial session with a device.
+  #
+  # The default setup of this class should work well with any bash-like shell.
+  # In particular, the +exec_prompt+ method sets the "PS1" environment variable, which should set the prompt the shell
+  # uses, and the +get_exit_code+ methods retrieves the value of the "$?" variable which should contain the exit code
+  # from the last action.  Because there is a possibility that your shell does not utilize those methods, the
+  # +override_set_prompt+ and +override_get_exit_code+ options are available to change the behavior.
+  #
+  #
+  # Valid options:
+  # +path+::
+  #     The path to the serial device (e.g. - COM3 or /dev/tty2)
+  #     This is a required option.
+  # +speed+::
+  #     The bitrate for the connection.
+  #     The default is 115200.
+  # +data_bits+::
+  #     The number of data bits for the connection.
+  #     The default is 8.
+  # +parity+::
+  #     The parity for the connection.
+  #     The default is :none.
+  # +prompt+::
+  #     The prompt used to determine when processes finish execution.
+  #     Defaults to '~~#', but if that doesn't work for some reason because it is valid output from one or more
+  #     commands, you can change it to something else.  It must be unique and cannot contain certain characters.
+  #     The characters you should avoid are !, $, \, /, ", and ' because no attempt is made to escape them and the
+  #     resulting prompt can very easily become something else entirely.  If they are provided, they will be
+  #     replaced to protect the shell from getting stuck.
+  # +quit+::
+  #     If set, this defines the command to execute when quitting the session.
+  #     The default is "exit" which will probably work most of the time.
+  # +retrieve_exit_code+::
+  #     If set to a non-false value, then the default behavior will be to retrieve the exit code from the shell after
+  #     executing a command.  If set to a false or nil value, the default behavior will be to ignore the exit code
+  #     from the shell.  When retrieved, the exit code is stored in the +last_exit_code+ property.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +on_non_zero_exit_code+::
+  #     If set to :ignore (the default) then non-zero exit codes will not cause errors.  You will still be able to check
+  #     the +last_exit_code+ property to determine if the command was successful.
+  #     If set to :raise then non-zero exit codes will cause a Shells::NonZeroExitCode to be raised when a command exits
+  #     with a non-zero return value.
+  #     This option only comes into play when +retrieve_exit_code+ is set to a non-false value.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +silence_timeout+::
+  #     When a command is executing, this is the maximum amount of time to wait for any feedback from the shell.
+  #     If set to 0 (or less) there is no timeout.
+  #     Unlike +command_timeout+ this value resets every time we receive feedback.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +command_timeout+::
+  #     When a command is executing, this is the maximum amount of time to wait for the command to finish.
+  #     If set to 0 (or less) there is no timeout.
+  #     Unlike +silence_timeout+ this value does not reset when we receive feedback.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +override_set_prompt+::
+  #     If provided, this must be set to either a command string that will set the prompt, or a Proc that accepts
+  #     the shell as an argument.
+  #     If set to a string, the string is sent to the shell and we wait up to two seconds for the prompt to appear.
+  #     If that fails, we resend the string and wait one more time before failing.
+  #     If set to a Proc, the Proc is called.  If the Proc returns a false value, we fail.  If the Proc returns
+  #     a non-false value, we consider it successful.
+  # +override_get_exit_code+::
+  #     If provided, this must be set to either a command string that will retrieve the exit code, or a Proc that
+  #     accepts the shell as an argument.
+  #     If set to a string, the string is sent to the shell and the output is parsed as an integer and used as the exit
+  #     code.
+  #     If set to a Proc, the Proc is called and the return value of the proc is used as the exit code.
+  #
+  #   Shells::SerialSession.new(
+  #       path: '/dev/ttyusb3',
+  #       speed: 9600
+  #   ) do |shell|
+  #     shell.exec('cd /usr/local/bin')
+  #     user_bin_files = shell.exec('ls -A1').split("\n")
+  #     @app_is_installed = user_bin_files.include?('my_app')
+  #   end
+  #
+  class SerialSession < Shells::ShellBase
+
+    include BashCommon
+
+    ##
+    # Sets the line ending for the instance.
+    def line_ending=(value)
+      @line_ending = value || "\r\n"
+    end
+
+    ##
+    # Gets the line ending for the instance.
+    def line_ending
+      @line_ending ||= "\r\n"
+    end
+
+    protected
+
+    def validate_options #:nodoc:
+      options[:speed] ||= 115200
+      options[:data_bits] ||= 8
+      options[:parity] ||= :none
+      options[:quit] ||= 'exit'
+      options[:connect_timeout] ||= 5
+
+      raise InvalidOption, 'Missing path.' if options[:path].to_s.strip == ''
+    end
+
+    def exec_shell(&block) #:nodoc:
+
+      debug 'Opening serial port...'
+      @serport = Serial.new options[:path], options[:speed], options[:data_bits], options[:parity]
+
+      begin
+        # start buffering
+        buffer_input
+
+        # yield to the block
+        block.call
+
+      ensure
+        # send the quit message.
+        send_data options[:quit] + line_ending
+
+        debug 'Closing serial port...'
+        @serport.close
+        @serport = nil
+      end
+    end
+
+    def exec_prompt(&block) #:nodoc:
+      cmd = options[:override_set_prompt] || "PS1=\"#{options[:prompt]}\""
+      if cmd.respond_to?(:call)
+        raise Shells::FailedToSetPrompt unless cmd.call(self)
+      else
+        # set the prompt, wait up to 2 seconds for a response, then try one more time.
+        begin
+          exec cmd, command_timeout: 2, retrieve_exit_code: false
+        rescue Shells::CommandTimeout
+          begin
+            exec cmd, command_timeout: 2, retrieve_exit_code: false
+          rescue Shells::CommandTimeout
+            raise Shells::FailedToSetPrompt
+          end
+        end
+      end
+
+      # yield to the block
+      block.call
+    end
+
+    def send_data(data) #:nodoc:
+      @serport.write data
+      debug "Sent: (#{data.size} bytes) #{(data.size > 32 ? (data[0..30] + '...') : data).inspect}"
+    end
+
+    def loop(&block) #:nodoc:
+      while true
+        while true
+          data = ''
+          while (byte = @serport.getbyte)
+            data << byte.chr
+          end
+          break if data == ""
+          debug "Received: (#{data.size} bytes) #{(data.size > 32 ? (data[0..30] + '...') : data).inspect}"
+          @_stdout_recv.call data
+        end
+        break unless block&.call
+      end
+    end
+
+    def stdout_received(&block) #:nodoc:
+      @_stdout_recv = block
+    end
+
+    def stderr_received(&block) #:nodoc:
+      @_stderr_recv = block
+    end
+
+  end
+end