asa_console 0.1.2

data/lib/asa_console/config.rb

@@ -0,0 +1,170 @@
+
+require 'stringio'
+
+class ASAConsole
+  #
+  # A parser for ASA running/startup config.
+  #
+  # Each instance represents a single config entry which may include nested
+  # lines of config that can be queried with {#select} or {#select_all}.
+  #
+  # @example Print ACEs with line numbers for each access list
+  #   # Start by fetching a top-level Config object
+  #   config = asa.running_config('access-list')
+  #   config.names_of('access-list').each do |acl|
+  #     puts "Access list #{acl}:"
+  #     counter = 0
+  #     config.select('access-list', acl) do |ace|
+  #       counter += 1
+  #       puts " Line #{counter}: #{ace.line}"
+  #     end
+  #     puts
+  #   end
+  #
+  # @example List all interfaces that participate in EIGRP
+  #   # Start by fetching a top-level Config object
+  #   config = asa.running_config('all router eigrp')
+  #   router = config.select('router eigrp')
+  #   router.select('passive-interface') do |passive_interface|
+  #     ifname = passive_interface.config_data
+  #     next if ifname == 'default'
+  #     if passive_interface.negated?
+  #       puts "Interface '#{ifname}' is sending routing updates"
+  #     else
+  #       puts "Interface '#{ifname}' is passive"
+  #     end
+  #   end if router
+  #
+  # @attr_reader keystr [String, nil]
+  #   Key used to select the line of config represented by this object, or `nil`
+  #   if the object contains nested top-level config.
+  # @attr_reader config_name [String, nil]
+  #   An identifier, such as an access list name, used to distinguish between
+  #   config entries of the same type.
+  # @attr_reader config_data [String, nil]
+  #   Remainder of the config line following the {#keystr} and {#config_name}.
+  #
+  class Config
+    attr_reader :keystr
+    attr_reader :config_name
+    attr_reader :config_data
+
+    # @see #running_config
+    # @option opts [String] :keystr class attribute
+    # @option opts [String] :config_name class attribute
+    # @option opts [String] :config_data class attribute
+    # @option opts [Boolean] :negated
+    #   `true` if the config line began with "no", or `false` otherwise
+    # @option opts [String] :nested_config
+    #   a multiline string of config (indentation stripped)
+    def initialize(opts = {})
+      @keystr         = opts[:keystr]
+      @config_name    = opts[:config_name]
+      @config_data    = opts[:config_data]
+      @negated        = opts.fetch(:negated, false)
+      @nested_config  = opts.fetch(:nested_config, '')
+    end
+
+    # @return [String, nil]
+    #   the selected line, or `nil` if this is a top-level object
+    def line
+      parts = []
+      parts << 'no' if @negated
+      parts << @keystr if @keystr
+      parts << @config_name if @config_name
+      parts << @config_data if @config_data
+      parts.empty? ? nil : parts.join(' ')
+    end
+
+    # @return [Boolean]
+    #   `true` if the selected line began with "no", or `false` otherwise
+    def negated?
+      @negated ? true : false
+    end
+
+    # @return [Boolean]
+    #   `true` if there is no nested config, or `false` otherwise
+    def empty?
+      @nested_config.empty?
+    end
+
+    # Select all lines of nested config. Equivalent to {#select} with no
+    # arguments.
+    #
+    # @yieldparam config [Config]
+    # @yieldreturn [nil] if a block is given
+    # @return [Array<Config>] if no block given
+    def select_all
+      result = []
+      select do |config|
+        if block_given?
+          yield config
+        else
+          result << config
+        end
+      end
+      result unless block_given?
+    end
+
+    # Select the first matching line of the nested config or `yield` all
+    # matching lines if a block is given.
+    #
+    # @param keystr [String, nil]
+    # @param config_name [String, nil]
+    # @yieldparam config [Config]
+    # @yieldreturn [nil] if a block is given
+    # @return [Config] if no block given
+    def select(keystr = nil, config_name = nil)
+      prefix = [keystr, config_name].join(' ').strip
+      regex = /^(?<no>no )?#{Regexp.escape(prefix)} ?(?<data>.+)?/
+
+      io = StringIO.open(@nested_config)
+      lines = io.readlines
+      io.close
+
+      loop do
+        break if lines.empty?
+
+        m = regex.match(lines.shift)
+        next unless m
+
+        nested_config = ''
+        loop do
+          break unless lines[0] && lines[0].start_with?(' ')
+          nested_config << lines.shift.sub(/^ /, '')
+        end
+
+        config = Config.new(
+          keystr:         keystr,
+          config_name:    config_name,
+          config_data:    m[:data],
+          negated:        !m[:no].nil?,
+          nested_config:  nested_config
+        )
+
+        if block_given?
+          yield config
+        else
+          return config
+        end
+      end
+
+      nil
+    end
+
+    # @see #select
+    # @param keystr [String]
+    # @return [Array<String>]
+    #   a unique list of config element names matched by `keystr`
+    def names_of(keystr)
+      names = []
+      regex = /^(?:no )?#{Regexp.escape(keystr)} (?<name>\S+)/
+      @nested_config.each_line do |line|
+        m = regex.match(line)
+        next unless m
+        names << m[:name] unless names.include? m[:name]
+      end
+      names
+    end
+  end
+end

data/lib/asa_console/error.rb

@@ -0,0 +1,43 @@
+
+class ASAConsole
+  # Parent class for all other {ASAConsole} exceptions.
+  class Exception < ::RuntimeError; end
+
+  # Container for exceptions to avoid cluttering the namespace.
+  module Error
+    # Raised when an unexpected "ERROR: [...]" message is received.
+    class CommandError < Exception; end
+
+    # Raised when attempting to execute a configuration command in the wrong
+    # config mode or submode.
+    class ConfigModeError < Exception; end
+
+    # Any type of connection failure.
+    class ConnectFailure < Exception; end
+
+    # Raised when a terminal object times out waiting for an expected prompt.
+    class ExpectedPromptFailure < Exception; end
+
+    # Raised when checking an ASA version against an unsupported expression.
+    class InvalidExpressionError < Exception; end
+
+    # Raised when a required option hash entry is missing.
+    class MissingOptionError < Exception; end
+
+    # Raised when attempting to execute a command on a disconnected terminal.
+    class NotConnectedError < Exception; end
+
+    # Raised (by default) when a configuration command generates output instead
+    # of just presenting the next config prompt.
+    class UnexpectedOutputError < Exception; end
+
+    # Raised when there is a failure parsing the appliance version string.
+    class VersionParseError < Exception; end
+
+    # A {ConnectFailure} caused by invalid credentials.
+    class AuthenticationFailure < ConnectFailure; end
+
+    # A {ConnectFailure} caused by a timeout.
+    class ConnectionTimeoutError < ConnectFailure; end
+  end
+end

data/lib/asa_console/terminal.rb

@@ -0,0 +1,9 @@
+
+class ASAConsole
+  #
+  # Container for duck-typed classes that provide an interactive command line
+  # session of some kind.
+  #
+  module Terminal
+  end
+end

data/lib/asa_console/terminal/fake_ssh.rb

@@ -0,0 +1,145 @@
+
+require 'asa_console/terminal/ssh'
+
+class ASAConsole
+  module Terminal
+    #
+    # A subclass of {SSH} that overrides the {SSH#connect} method to generate
+    # stub objects for RSpec testing.
+    #
+    # The constructor takes the same hash options as {SSH#initialize}, but
+    # requires one additional option; `:input_proc`, a proc that takes two
+    # arguments:
+    #   * `input` -- A command or other input that is being passed to the
+    #     simulated appliance.
+    #   * `prompt` -- Last prompt displayed on the terminal when the `input`
+    #     text was entered.
+    #
+    # The proc is expected to return an array with three elements:
+    #   * `output` -- Result of sending `input` to the simulated appliance.
+    #   * `prompt` -- Next prompt to present within the session.
+    #   * `disconnect` -- `true` to indicate that the SSH connection has been
+    #     closed (e.g. if "exit" was sent to the terminal), or `false`
+    #     otherwise.
+    #
+    # @example
+    #   input_proc = proc do |input|
+    #     prompt = 'TEST# '
+    #     case input
+    #     when "terminal pager lines 0\n", nil
+    #       output = prompt
+    #       disconnect = false
+    #     when "exit\n"
+    #       output = "\nLogoff\n\n"
+    #       disconnect = true
+    #     else
+    #       output = "ERROR: Command not implemented\n" + prompt
+    #       disconnect = false
+    #     end
+    #     [output, prompt, disconnect]
+    #   end
+    #
+    #   asa = ASAConsole.fake_ssh(
+    #     host: 'ignored',
+    #     user: 'ignored',
+    #     input_proc: input_proc
+    #   )
+    #   asa.connect
+    #
+    #   # This will raise an error
+    #   asa.priv_exec('write memory')
+    #
+    # @api development
+    class FakeSSH < SSH
+      #
+      # @api private
+      attr_accessor :raw_buffer
+      #
+      # @api private
+      attr_accessor :raw_session_log
+      #
+      # @api private
+      attr_accessor :session
+      #
+      # @api private
+      attr_accessor :channel
+      #
+      # @api private
+      attr_accessor :last_output_received
+      #
+      # @api private
+      attr_accessor :input_proc
+
+      # Wrapper for the {SSH} class constructor that extracts `:input_proc` from
+      # the options hash and passes the rest to the parent.
+      #
+      # @option opts [Proc] :input_proc
+      # @option opts ... options for the {SSH} constructor
+      # @see SSH#initialize SSH constructor
+      def initialize(opts)
+        @input_proc = opts.delete(:input_proc)
+        fail Error::MissingOptionError, 'Option :input_proc is missing or invalid' \
+          unless @input_proc.is_a? Proc
+        super(opts)
+      end
+
+      # Connect to a simulated appliance. This method creates anonymous stub
+      # classes that take the place of `Net::SSH::Connection::Session` and
+      # `Net::SSH::Connection::Channel`. The stub classes implement only the
+      # subset of methods that are used by the {SSH} terminal class.
+      #
+      # @return [void]
+      def connect
+        @session = Class.new do
+          def initialize
+            @closed = false
+          end
+          def close
+            @closed = true
+          end
+          def closed?
+            @closed ? true : false
+          end
+        end.new
+
+        @channel = Class.new do
+          attr_reader :terminal
+          def initialize(terminal)
+            @terminal = terminal
+            @input_buffer = ''
+            @output_buffer, @prompt = @terminal.input_proc.call
+          end
+          def connection
+            self
+          end
+          def process(timeout)
+            sleep timeout
+            @terminal.raw_buffer = @output_buffer
+            @terminal.raw_session_log << @output_buffer
+            @output_buffer = ''
+            fail Net::SSH::Disconnect if @terminal.session.closed?
+          end
+          def send_data(input)
+            @input_buffer << input
+            return unless @input_buffer.end_with? "\n"
+            @output_buffer << @input_buffer
+            output, prompt, disconnect = @terminal.input_proc.call(@input_buffer, @prompt)
+            @output_buffer << output
+            @prompt = prompt
+            @terminal.session.close if disconnect
+            @input_buffer = ''
+            @terminal.last_output_received = Time.now.getlocal
+          end
+        end.new(self)
+
+        @connected = true
+
+        # This is copied verbatim from the parent #connect method
+        expect(ANY_EXEC_PROMPT) do |success, output|
+          @on_output_callbacks.each { |c| c.call(nil, nil, output) }
+          fail Error::ConnectFailure 'Failed to parse EXEC prompt', self unless success
+        end
+      end
+    end
+  end
+end

data/lib/asa_console/terminal/ssh.rb

@@ -0,0 +1,223 @@
+
+require 'net/ssh'
+require 'asa_console/error'
+require 'asa_console/terminal'
+require 'asa_console/util'
+
+class ASAConsole
+  module Terminal
+    #
+    # An SSH terminal session.
+    #
+    # @attr host [String]
+    #   Hostname or IP address.
+    # @attr user [String]
+    #   SSH username.
+    # @attr password [String]
+    #   SSH password.
+    # @attr ssh_opts [Hash]
+    #   Option hash passed to `Net::SSH::start`.
+    # @attr command_timeout [Numeric]
+    #   Maximum time to wait for a command to execute.
+    # @attr connect_timeout [Numeric]
+    #   SSH connection timeout. (`:timeout` option passed to `Net::SSH::start`)
+    # @attr_reader prompt [String, nil]
+    #   Prompt currently displayed on the terminal or `nil` if not connected.
+    #
+    class SSH
+      DEFAULT_CONNECT_TIMEOUT = 5
+      DEFAULT_COMMAND_TIMEOUT = 5
+
+      attr_accessor :host
+      attr_accessor :user
+      attr_accessor :ssh_opts
+      attr_accessor :command_timeout
+
+      attr_reader :prompt
+
+      # @see Terminal
+      # @option opts [String] :host
+      # @option opts [String] :user
+      # @option opts [String] :password
+      # @option opts [Numeric] :connect_timeout
+      # @option opts [Numeric] :command_timeout
+      def initialize(opts)
+        fail Error::MissingOptionError, 'Option :host is missing' unless opts[:host]
+        fail Error::MissingOptionError, 'Option :user is missing' unless opts[:user]
+
+        @host = opts[:host]
+        @user = opts[:user]
+        @ssh_opts = {
+          timeout: opts.fetch(:connect_timeout, DEFAULT_CONNECT_TIMEOUT),
+          number_of_password_prompts: 0 # Avoid prompting for password on authentication failure
+        }
+        self.password = opts[:password]
+        @command_timeout = opts.fetch(:command_timeout, DEFAULT_COMMAND_TIMEOUT)
+        @prompt = nil
+
+        @raw_buffer           = ''
+        @raw_session_log      = ''
+        @connected            = false
+        @channel              = nil
+        @session              = nil
+        @last_output_received = nil
+        @on_output_callbacks  = []
+      end
+
+      def password
+        @ssh_opts[:password]
+      end
+
+      def password=(str)
+        @ssh_opts[:password] = str
+        @ssh_opts[:auth_methods] = ['password'] if str
+      end
+
+      def connect_timeout
+        @ssh_opts[:timeout]
+      end
+
+      def connect_timeout=(timeout)
+        @ssh_opts[:timeout] = timeout
+      end
+
+      # Start an SSH session and send a remote shell request. The method blocks
+      # until an EXEC prompt is received or a timeout is reached.
+      #
+      # @see https://tools.ietf.org/html/rfc4254 RFC 4254
+      # @raise [Error::ConnectFailure] for all error types
+      # @raise [Error::AuthenticationFailure]
+      #   subclass of {Error::ConnectFailure}
+      # @raise [Error::ConnectionTimeoutError]
+      #   subclass of {Error::ConnectFailure}
+      # @return [void]
+      def connect
+        Net::SSH.start(@host, @user, @ssh_opts) do |session|
+          @session = session
+          @session.open_channel do |channel|
+            channel.send_channel_request('shell') do |ch, ch_success|
+              fail Error::ConnectFailure, 'Failed to start remote shell' unless ch_success
+              @connected = true
+              @channel = ch
+              @channel.on_data do |_ch, data|
+                @last_output_received = Time.now.getlocal
+                @raw_session_log << data
+                @raw_buffer << data
+              end
+              @channel.on_close do
+                @connected = false
+              end
+              expect(ANY_EXEC_PROMPT) do |success, output|
+                @on_output_callbacks.each { |c| c.call(nil, nil, output) }
+                fail Error::ConnectFailure, 'Failed to parse EXEC prompt', self unless success
+              end
+              return # Workaround for Net::SSH limitations borrowed from Puppet
+            end
+          end
+        end
+      rescue Timeout::Error
+        raise Error::ConnectionTimeoutError, "Timeout connecting to #{@host}"
+      rescue Net::SSH::AuthenticationFailed
+        raise Error::AuthenticationFailure, "Authentication failed for #{@user}@#{@host}"
+      rescue SystemCallError, SocketError => e
+        raise Error::ConnectFailure, "#{e.class}: #{e.message}"
+      end
+
+      # @return [Boolean]
+      def connected?
+        @connected = false if @session.nil? || @session.closed?
+        @connected
+      end
+
+      # @return [void]
+      def disconnect
+        @session.close if connected?
+      rescue Net::SSH::Disconnect
+        @session = nil
+      end
+
+      # Send a line of text to the console and block until the expected prompt
+      # is seen in the output or a timeout is reached.
+      #
+      # @note
+      #   Special characters are not escaped by this method. Use the
+      #   {ASAConsole} wrapper for unescaped text.
+      #
+      # @see ASAConsole#send ASAConsole wrapper for this method
+      # @param line [String]
+      # @param expect_regex [Regexp]
+      # @param is_password [Boolean]
+      # @yieldparam success [Boolean]
+      # @yieldparam output [String]
+      # @return [void]
+      def send(line, expect_regex, is_password = false)
+        last_prompt = @prompt
+        @channel.send_data "#{line}\n" if connected?
+        input = (is_password ? '*' * line.length : line) + "\n"
+        expect(expect_regex) do |success, output|
+          output = output.sub(/^[^\n]*\n/m, '') # Remove echoed input
+          @on_output_callbacks.each { |c| c.call(last_prompt, input, output) }
+          yield(success, output)
+        end
+      end
+
+      # Register a proc to be called whenever the {#send} method finishes
+      # processing a transaction (whether successful or not).
+      #
+      # @example
+      #   @command_log = []
+      #   asa.terminal.on_output do |prompt, command, output|
+      #     if prompt && prompt !~ ASAConsole::PASSWORD_PROMPT
+      #       @command_log << command
+      #     end
+      #   end
+      #
+      # @yieldparam prompt [String]
+      # @yieldparam command [String]
+      # @yieldparam output [String]
+      # @return [void]
+      def on_output(&block)
+        @on_output_callbacks << block
+      end
+
+      # @return [String] a complete log of the SSH session
+      def session_log
+        Util.apply_control_chars(@raw_session_log)
+      end
+
+      def buffer
+        Util.apply_control_chars(@raw_buffer)
+      end
+      protected :buffer
+
+      def expect(prompt_regex)
+        @last_output_received = Time.now.getlocal
+
+        while buffer !~ prompt_regex
+          begin
+            @channel.connection.process(0.1)
+            break if Time.now.getlocal - @last_output_received > @command_timeout
+          rescue Net::SSH::Disconnect, IOError
+            @connected = false
+            break
+          end
+        end
+
+        matches = prompt_regex.match(buffer)
+        if matches.nil?
+          success = false
+          @prompt = nil
+        else
+          success = true
+          @prompt = matches[0]
+        end
+
+        output = buffer.sub(prompt_regex, '')
+        @raw_buffer = ''
+
+        yield(success, output)
+      end
+      protected :expect
+    end
+  end
+end