asa_console 0.1.2

data/lib/asa_console/test.rb

@@ -0,0 +1,134 @@
+
+require 'asa_console'
+require 'asa_console/test/script'
+
+class ASAConsole
+  #
+  # Methods to declare and execute {ASAConsole} test scripts in a lab
+  # environment.
+  #
+  # @example Contents of `./my_test_file.rb`
+  #   ASAConsole::Test.script do |asa|
+  #     log 'Connecting...'
+  #     asa.connect
+  #     log 'Executing the "show failover" command...'
+  #     asa.show('failover')
+  #     log 'Disconnecting...'
+  #     asa.disconnect
+  #   end
+  #
+  # @example Execute scripts in `./my_test_file.rb`
+  #   require 'asa_console/test'
+  #
+  #   terminal_opts = { host: '192.0.2.1', user: 'admin', password: 'secret' }
+  #
+  #   ASAConsole::Test.color_scheme = :light
+  #   ASAConsole::Test.start('./my_test_file.rb', terminal_opts)
+  #
+  module Test
+    #
+    # @api private
+    @@scripts = []
+    #
+    # @api private
+    @@colors = {}
+
+    # Declare a test script by passing a block to this method.
+    #
+    # @yieldparam asa [ASAConsole] object to manipulate
+    def self.script(&block)
+      klass = Class.new(Script)
+      klass.send(:define_method, 'test!', &block)
+      @@scripts << klass
+    end
+
+    # Set the color scheme for test script output.
+    #
+    # @param scheme_key [Symbol]
+    #   `:light` for light (or bold) colors, `:dark` for dark colors. Any other
+    #   option prevents colorized output.
+    def self.color_scheme=(scheme_key)
+      case scheme_key
+      when :light
+        @@colors = {
+          prompt: "\e[1;36m",
+          input:  "\e[1;33m",
+          output: "\e[1;32m",
+          log:    "\e[1;31m",
+          info:   "\e[1;35m"
+        }
+      when :dark
+        @@colors = {
+          prompt: "\e[0;36m",
+          input:  "\e[0;33m",
+          output: "\e[0;32m",
+          log:    "\e[0;31m",
+          info:   "\e[0;35m"
+        }
+      else
+        @@colors = {}
+      end
+    end
+
+    # @api private
+    def self.colorize(str, color_key)
+      return str unless @@colors[color_key] && !str.empty?
+      @@colors[color_key] + str + "\e[0m"
+    end
+
+    # Returns the absolute path of the test script directory or, if a test name
+    # is given, returns the path to the test file.
+    #
+    # @overload test_path
+    #   @return [String] the filesystem path of the test script directory
+    # @overload test_path(test_name)
+    #   @param test_name [String] the test name
+    #   @return [String] the filesystem path of the named test script
+    # @return [String] a filesystem path
+    def self.test_path(test_name = nil)
+      path = File.realpath(File.join(File.dirname(__FILE__), '..', '..', 'script'))
+      path = File.join(path, "test_#{test_name}.rb") if test_name
+      path
+    end
+
+    # A list of test names that can be passed to the command line utility.
+    #
+    # @return [Array]
+    def self.test_names
+      names = Dir.glob(File.join(test_path, 'test_*.rb'))
+      names.collect { |file| file.sub(/.*test_(.*)\.rb$/, '\1') }.sort
+    end
+
+    # Load a ruby source file with test script declarations and execute them.
+    #
+    # The `terminal_opts` and `enable_password` parameters will be passed to a
+    # {ASAConsole} factory method to generate a test object for each script run.
+    #
+    # @param test_file [String]
+    # @param terminal_opts [Hash]
+    # @param enable_password [String]
+    # @param show_session_log [Boolean]
+    #   append the session log to the end of each test output if `true`
+    # @return [Boolean]
+    #   `true` if `test_file` can be loaded with `require`, or `false` otherwise
+    def self.start(test_file, terminal_opts, enable_password = nil, show_session_log = false)
+      begin
+        require test_file
+      rescue LoadError
+        puts "Unable to load #{test_file}"
+        return false
+      end
+
+      @@scripts.each do |klass|
+        script = klass.new(terminal_opts, enable_password)
+        script.run
+        script.show_session_log if show_session_log
+        puts
+        puts colorize('Test Complete!', :info)
+        puts
+      end
+
+      true
+    end
+  end
+end

data/lib/asa_console/test/script.rb

@@ -0,0 +1,48 @@
+
+class ASAConsole
+  module Test
+    #
+    # Parent class for {ASAConsole} test scripts.
+    #
+    class Script
+      # @private
+      def initialize(terminal_opts, enable_password = nil)
+        @asa = ASAConsole.ssh(terminal_opts)
+        @asa.enable_password = enable_password if enable_password
+        @asa.terminal.on_output do |prompt, input, output|
+          print Test.colorize(prompt, :prompt) if prompt
+          print Test.colorize(input, :input) if input
+          print Test.colorize(output, :output) if output
+        end
+      end
+
+      # @api private
+      def run
+        test! @asa
+      rescue Exception => e
+        puts
+        puts Test.colorize('Received Exception:', :info)
+        puts '  ' + e.class.name
+        puts Test.colorize('Message:', :info)
+        puts '  ' + e.message
+        puts Test.colorize('Stack Trace:', :info)
+        puts e.backtrace.join("\n").gsub(/^/, '  ')
+      end
+
+      # @api private
+      def show_session_log
+        puts Test.colorize('Session Log:', :info)
+        puts @asa.terminal.session_log.gsub(/^/, '  ').chomp
+        puts
+      end
+
+      # Call from within a {script} block to output status messages.
+      #
+      # @see script
+      # @param text [String]
+      def log(text)
+        puts Test.colorize(text, :log)
+      end
+    end
+  end
+end

data/lib/asa_console/util.rb

@@ -0,0 +1,151 @@
+
+require 'stringio'
+require 'asa_console/error'
+
+class ASAConsole
+  #
+  # Miscellaneous utility functions.
+  #
+  module Util
+    CISCO_TIME_REGEX = %r{
+      (?<hour> \d\d):
+      (?<min> \d\d):
+      (?<sec> \d\d)
+      (?:\.(?<subsec> \d\d\d)\s)?
+      (?<tz> .*?)\s
+      (?:(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)\s)?
+      (?<month> \w\w\w)\s
+      (?<day> \d\d?)\s
+      (?<year> \d\d\d\d)
+    }x
+
+    VERSION_EXPR_REGEX = %r{^
+      (?<opr> [><=!]=?)?\s*     # Comparison operator
+      (?<major> \d+) (?:        # Major release number
+        \.(?<minor> \d+|x) (?:  # Minor release number or x
+           \((?<maint> \d+|x)\) # Maintenance release number or x
+        )?
+      )?
+    $}x
+
+    # Convert a string with terminal control characters to plain text as it
+    # would appear in a terminal window.
+    #
+    # An ASA will use backspaces and carriage returns to hide text that has
+    # already been output to the console. For example, the ASA outputs extra
+    # characters to hide the `<--- More --->` prompt when the user presses a
+    # key.
+    #
+    # @param raw [String]
+    # @return [String]
+    def self.apply_control_chars(raw)
+      output = ''
+      raw.split("\n").each do |line|
+        io = StringIO.new
+        line.scan(/([^\r\x08]+|[\r\x08])/) do |m|
+          case m[0]
+          when "\r"
+            io.rewind
+          when "\x08"
+            io.pos = io.pos - 1
+          else
+            io.write(m[0])
+          end
+        end
+        output << io.string << "\n"
+      end
+      output.chop! unless raw.end_with?("\n")
+      output.delete("\x00")
+    end
+
+    # Parse the time format commonly used in various command output. This can be
+    # useful for things like extracting the configuration modification time from
+    # "show version" output or for parsing the last failover time.
+    #
+    # @note
+    #   It is not possible to reliably evaluate the timezone string without
+    #   running additional commands, so this function (optimistically) returns
+    #   a UTC timestamp. See {file:script/test_clock.rb} for one method of
+    #   adjusting a remote timestamp to local time using "show clock" commands.
+    #
+    # @param str [String]
+    # @yieldparam time [Time]
+    # @yieldparam tz [String]
+    #   timezone string set by "clock timezone" or "clock summer-time"
+    # @return [Time]
+    #   time represented in UTC
+    def self.parse_cisco_time(str)
+      m = CISCO_TIME_REGEX.match(str)
+      return nil unless m
+      tz      = m[:tz]
+      year    = m[:year].to_i
+      month   = m[:month]
+      day     = m[:day].to_i
+      hour    = m[:hour].to_i
+      min     = m[:min].to_i
+      sec     = m[:sec].to_i
+      subsec  = "0.#{m[:subsec]}".to_f
+      time = Time.utc(year, month, day, hour, min, sec) + subsec
+      time = yield(time, tz) if block_given?
+      time
+    end
+
+    # Match an ASA software version string in `x.x(x)` format against one or
+    # more conditional expressions.
+    #
+    # @see #version? The ASAConsole wrapper for this function
+    # @param version [String]
+    # @param exprs [Array<String>]
+    # @return [Boolean] `true` if _all_ expressions match, or `false` otherwise
+    def self.version_match?(version, exprs)
+      ver = []
+      version_match_parse(version) { |_opr, pattern| ver = pattern }
+      exprs.each do |e|
+        version_match_parse(e) do |opr, pattern|
+          return false unless version_match_compare(opr, ver, pattern)
+        end
+      end
+      true
+    end
+
+    # @api private
+    def self.version_match_parse(expr)
+      expr = expr.to_s # Forgive users who provide a number instead of a string
+      m = VERSION_EXPR_REGEX.match(expr)
+      fail Error::InvalidExpressionError, "Expression '#{expr}' is not valid" unless m
+      opr = m[:opr]
+      opr = '==' if opr == '=' || opr.nil? # Equality is the default operator
+      opr = '!=' if opr == '!'
+      pattern = [ m[:major].to_i ]
+      if m[:minor] && m[:minor] != 'x'
+        pattern << m[:minor].to_i
+        pattern << m[:maint].to_i if m[:maint] && m[:maint] != 'x'
+      end
+      yield(opr, pattern)
+    end
+
+    # @api private
+    def self.version_match_compare(opr, ver, pattern)
+      a = ver[0..(pattern.length - 1)]
+      b = pattern.clone
+      eq = true
+      gt = lt = false
+      a.each do |x|
+        y = b.shift
+        next if x == y
+        eq = false
+        gt = x > y
+        lt = x < y
+        break
+      end
+      case opr
+      when '>'  then gt
+      when '<'  then lt
+      when '==' then eq
+      when '>=' then gt || eq
+      when '<=' then lt || eq
+      when '!=' then !eq
+      end
+    end
+  end
+end

data/script/test_clock.rb

@@ -0,0 +1,39 @@
+
+#
+# This script demonstrates a method for converting a firewall timestamp to a
+# time in the local timezone. We have to explicitly query for the UTC offset
+# since the timezone string can be set to any arbitrary value.
+#
+ASAConsole::Test.script do |asa|
+  asa.connect
+
+  log "Local time is #{Time.now.getlocal}"
+
+  time = ASAConsole::Util.parse_cisco_time(asa.show('clock')) do |t, tz|
+    log "Remote time (not adjusted for timezone) is #{t}"
+    log "Remote timezone string is #{tz}"
+
+    # We need to use "all clock" instead of "clock" since the timezone line is
+    # omitted from default output when using UTC.
+    result = asa.running_config('all clock').select('clock timezone').config_data
+    matches = /(?<tz>[\S]+) (?<offset>\-?\d+)/.match(result)
+
+    # It's technically possible for the summer time string to match the timezone
+    # string, but let's assume this firewall has a sane configuration.
+    if tz == matches[:tz]
+      log 'Assuming we are not on summer time...'
+      offset = matches[:offset].to_i
+    else
+      log 'Assuming we are on summer time...'
+      offset = matches[:offset].to_i + 1
+    end
+
+    log "UTC offset is #{offset}"
+
+    t.getlocal - (offset * 3600)
+  end
+
+  log "Remote time (adjusted to the local timezone) is #{time}"
+
+  asa.disconnect
+end

data/script/test_connect.rb

@@ -0,0 +1,10 @@
+
+#
+# A simple connection test.
+#
+ASAConsole::Test.script do |asa|
+  log 'Connecting...'
+  asa.connect
+  log 'Disconnecting...'
+  asa.disconnect
+end

data/script/test_error_command.rb

@@ -0,0 +1,15 @@
+
+#
+# This test will raise a command error.
+#
+ASAConsole::Test.script do |asa|
+  log 'Connecting...'
+  asa.connect
+
+  log 'Generating an error...'
+  asa.priv_exec('derp derp derp')
+
+  # It won't get this far.
+  log 'Disconnecting...'
+  asa.disconnect
+end

data/script/test_error_connect.rb

@@ -0,0 +1,31 @@
+
+#
+# The connection will fail with a timeout error.
+#
+ASAConsole::Test.script do |asa|
+  asa.terminal.host = '192.0.2.1' # Non-routable IP from RFC 5737
+
+  # We already know it's going to time out so there's no need to wait long.
+  asa.terminal.connect_timeout = 1
+
+  log 'Connecting to a non-routable IP...'
+  asa.connect
+
+  # It won't get this far.
+  log 'Disconnecting...'
+  asa.disconnect
+end
+
+#
+# The connection will fail with an authentication error.
+#
+ASAConsole::Test.script do |asa|
+  asa.terminal.password = 'wrong password'
+
+  log 'Connecting with the wrong password...'
+  asa.connect
+
+  # It won't get this far.
+  log 'Disconnecting...'
+  asa.disconnect
+end

data/script/test_error_enable.rb

@@ -0,0 +1,18 @@
+
+#
+# Test for failure when #connect attempts to enter privileged EXEC mode.
+#
+ASAConsole::Test.script do |asa|
+  asa.enable_password = 'bad enable password'
+
+  # The #connect method will time out waiting for a prompt ending in "#" because
+  # the next prompt it receives will be a second "Password:" prompt.
+  asa.terminal.command_timeout = 1
+
+  log 'Connecting with a bad enable password...'
+  asa.connect
+
+  # It won't get this far.
+  log 'Disconnecting...'
+  asa.disconnect
+end