asa_console 0.1.2

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    Yzc1YjUzZDY2YWUwMjY2Y2IyZTM2YTcyMDQ2M2M2MjE4MDVmYmNkYw==
+  data.tar.gz: !binary |-
+    ZGFkZjI4YjZlNTc3OTExYmY0YTA2MGFmYjc2YWVlZDk3Nzk3NzFlMw==
+SHA512:
+  metadata.gz: !binary |-
+    MTRhYjE5YzE5ZDhiYjQzZWJmNGM2NTM0ZDA3YTdjNzczM2VkZjYyYTc4ZDJm
+    ZTFiN2I2MjAzZTUxNTYzNDUxYzU1N2I5MGJlNTZhNThjNWJkYmRlNzk4NzQz
+    M2I1YWExNGExZWE3YzZhZjM2YTQ2MmQyNWYzZDQ2NjQyMTU0OWU=
+  data.tar.gz: !binary |-
+    MTE2YTQ4NTJjZGUzMTU2MzkyZWY4YTVhMGVlOGM3YzhhMTQzMDUzOGViZTIz
+    YzY0MzMzNzFhMjJjOTY2M2JkMGIzYmZiOWRhZGZlYWRjYTI4NDlhYjQ5NmQy
+    MWM1MjFmNDkwYmUwMjMzNGQ0ODZkMmY4ZDU1M2Y4ZTgzODVmN2Y=

data/.yardopts

@@ -0,0 +1,8 @@
+--default-return void
+--markup markdown
+--no-api
+--no-cache
+--no-private
+-
+LICENSE.md
+script/*

data/LICENSE.md

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+=====================
+
+Copyright (c) 2015 Henry Goodman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,116 @@
+[![Build Status](https://travis-ci.org/hgoodman/asa-console.svg?branch=master)](https://travis-ci.org/hgoodman/asa-console)
+[![Code Climate](https://codeclimate.com/github/hgoodman/asa-console/badges/gpa.svg)](https://codeclimate.com/github/hgoodman/asa-console)
+[![Test Coverage](https://codeclimate.com/github/hgoodman/asa-console/badges/coverage.svg)](https://codeclimate.com/github/hgoodman/asa-console/coverage)
+[![Gem Version](https://badge.fury.io/rb/asa_console.svg)](https://badge.fury.io/rb/asa_console)
+[![YARD Docs](https://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/hgoodman/asa-console/)
+
+ASAConsole
+==========
+
+A ruby gem for Cisco ASA management via an interactive terminal session.
+
+This gem lets a program interact with a Cisco ASA using CLI commands. It includes a minimal set of functions for issuing commands and parsing the results.
+
+Caveats
+=======
+
+Most people would be better off using [Cisco's official REST API](http://www.cisco.com/c/en/us/td/docs/security/asa/api/qsg-asa-api.html) plugin for the ASA platform. This gem does not use the supported API. It was developed as an academic pursuit and may not be suitable for your environment. It is distributed under the [MIT License](LICENSE.md), which is to say that it comes with no warranty of any kind.
+
+That being said, you might find it useful if you are working with older hardware or if you have other special requirements. The official REST API plugin is only supported on 5500-X, ASAv and newer platforms.
+
+For the time being, direct SSH is the only transport method implemented by this gem although it could easily be extended to support alternatives like using a serial console or a jump box.
+
+Getting Started
+===============
+
+The easiest way to get started is to browse through the test files in the [script](script/) folder. To supplement its automated tests, this gem provides a framework for live testing against devices in a lab environment. There are several canned test scripts that demonstrate different features of the library.
+
+Each script executes a series of commands declared in a block as show below. The test runner displays output as it would appear in an SSH session and adds color to indicate how the output is being parsed. Informational messages can be added to the output with the `log` method.
+
+```ruby
+ASAConsole::Test.script do |asa|
+  log 'Connecting...'
+  asa.connect
+  if asa.version? '>= 9.4(1)'
+    asa.priv_exec 'no terminal interactive'
+  else
+    log 'The "no terminal interactive" command is not supported'
+  end
+  log 'Disconnecting...'
+  asa.disconnect
+end
+```
+
+The included test scripts are designed to be non-invasive and to leave the device configuration in its original state. Nevertheless, running them in a production environment is not recommended.
+
+Command Line Utility
+--------------------
+
+**Usage**
+
+    asatest [options] <testname> [asaname]
+
+**Examples**
+
+List command line options and available tests:
+
+    asatest --help
+
+Execute a canned test:
+
+    asatest connect
+
+Load a custom test file:
+
+    asatest -f ./my_test_file.rb
+
+Configuration Files
+-------------------
+
+The `asatest` executable will read a list of default command line options from the file `~/.asa-console/test_options.yaml`. Here is an example of the file format:
+
+```yaml
+---
+show-session-log: true
+color: light
+```
+
+Each key matches a long-form command line option with the leading "--" removed. Run the program with "--help" for a complete list.
+
+Device information is needed for running live tests. By default, the program will look for appliance information in `~/.asa-console/test_appliances.yaml`. Here is an example of the file format:
+
+```yaml
+---
+default_appliance: firewall002
+appliances:
+  firewall001:
+    terminal_opts:
+      host: 10.7.7.1
+      connect_timeout: 20
+  firewall002:
+    terminal_opts:
+      host: 10.7.7.254
+      user: testuser
+      password: execpass
+    enable_password: enablepass
+```
+
+If any of the following options are not found in this file, the user will be prompted to enter values for them.
+
+- `terminal_opts[host]`
+- `terminal_opts[user]`
+- `terminal_opts[password]`
+- `enable_password`
+
+The enable password can be omitted if it is the same as the terminal password or if it is otherwise not needed.
+
+API Documentation
+=================
+
+You can view online documentation at [rubydoc.info](http://www.rubydoc.info/github/hgoodman/asa-console/) or generate it yourself with:
+
+    rake yardoc
+
+To include documentation for objects used in testing and development:
+
+    rake yardoc_dev

data/asa_console.gemspec

@@ -0,0 +1,30 @@
+
+Gem::Specification.new do |s|
+  s.name        = 'asa_console'
+  s.version     = '0.1.2'
+  s.summary     = 'Cisco ASA management via an interactive terminal session'
+  s.description = 'This gem lets a program interact with a Cisco ASA using CLI
+  commands. It includes a minimal set of functions for issuing commands and
+  parsing the results.'.gsub(/\s+/, ' ')
+  s.author      = 'Henry Goodman'
+  s.email       = 'github@henrygoodman.com'
+  s.homepage    = 'https://github.com/hgoodman/asa-console/'
+  s.license     = 'MIT'
+  s.has_rdoc    = 'yard'
+  s.files       = Dir[__FILE__, 'lib/**/*', 'script/*', '*.md', '.yardopts']
+  s.executables = ['asatest']
+
+  s.add_runtime_dependency('net-ssh', '~> 2.9.2')
+  s.add_runtime_dependency('highline', '~> 1.7')
+
+  s.add_development_dependency('bundler',   '~> 1.7')
+  s.add_development_dependency('rake',      '~> 10.4')
+  s.add_development_dependency('redcarpet', '~> 3.3')
+  s.add_development_dependency('rspec',     '~> 3.4')
+  s.add_development_dependency('rubocop',   '~> 0.35')
+  s.add_development_dependency('simplecov', '~> 0.11')
+  s.add_development_dependency('thor',      '~> 0.19')
+  s.add_development_dependency('yard',      '~> 0.8')
+
+  s.required_ruby_version = '>=1.9.3'
+end

data/bin/asatest

@@ -0,0 +1,113 @@
+#!/bin/env ruby
+
+require 'yaml'
+require 'getoptlong'
+require 'highline/import'
+require 'asa_console/test'
+
+DEFAULT_OPTION_FILE = File.join(Dir.home, '.asa-console', 'test_options.yaml')
+DEFAULT_APPLIANCE_FILE = File.join(Dir.home, '.asa-console', 'test_appliances.yaml')
+DEFAULT_COLOR = :dark
+
+def usage
+  puts %(
+  Usage:
+    #{$PROGRAM_NAME} [options] <testname> [asaname]
+
+  Options:
+    -h, --help                    Display this message
+    -f, --file                    Interpret <testname> as an explicit file name
+    -o, --option-file <file>      YAML file with command line defaults for this utility
+    -a, --appliance-file <file>   YAML file with ASA device list and terminal options
+    -s, --show-session-log        Include the full session log in the command output
+    -c, --color (light|dark|off)  Colorize output using light or dark colors
+
+  Defaults:
+    --option-file     #{DEFAULT_OPTION_FILE}
+    --appliance-file  #{DEFAULT_APPLIANCE_FILE}
+    --color           #{DEFAULT_COLOR}
+
+  Available Tests:
+    #{ASAConsole::Test.test_names.join("\n    ")}
+  ).gsub(/^  /, '')
+  puts
+  exit 1
+end
+
+cli_opts = {}
+
+begin
+  cli = GetoptLong.new(
+    [ '--help',             '-h', GetoptLong::NO_ARGUMENT ],
+    [ '--file',             '-f', GetoptLong::NO_ARGUMENT ],
+    [ '--option-file',      '-o', GetoptLong::REQUIRED_ARGUMENT ],
+    [ '--appliance-file',   '-a', GetoptLong::REQUIRED_ARGUMENT ],
+    [ '--show-session-log', '-s', GetoptLong::NO_ARGUMENT ],
+    [ '--color',            '-c', GetoptLong::REQUIRED_ARGUMENT ]
+  )
+  cli.each do |opt, arg|
+    cli_opts[opt.sub(/^--/, '')] = (arg == '' ? true : arg)
+  end
+rescue GetoptLong::MissingArgument
+  usage
+end
+
+help = false
+is_file = false
+option_file = DEFAULT_OPTION_FILE
+appliance_file = DEFAULT_APPLIANCE_FILE
+show_session_log = false
+color = DEFAULT_COLOR
+
+option_file = cli_opts['option-file'] if cli_opts['option-file']
+if File.readable? option_file
+  cli_opts = YAML.load_file(option_file).merge(cli_opts)
+end
+
+cli_opts.each do |opt, arg|
+  case opt
+  when 'help'             then  help = arg
+  when 'file'             then  is_file = arg
+  when 'appliance-file'   then  appliance_file = arg
+  when 'show-session-log' then  show_session_log = arg
+  when 'color'            then  color = arg.to_sym
+  end
+end
+
+test_name = ARGV.shift if ARGV.length > 0
+asa_name = ARGV.shift if ARGV.length > 0
+
+ASAConsole::Test.color_scheme = color
+
+enable_password = nil
+
+if File.readable? appliance_file
+  config = YAML.load_file(appliance_file)
+  asa_name ||= config['default_appliance']
+  if asa_name
+    if config['appliances'][asa_name].is_a?(Hash)
+      terminal_opts = config['appliances'][asa_name]['terminal_opts']
+      enable_password = config['appliances'][asa_name]['enable_password']
+    else
+      puts "Error: Configuration missing for #{asa_name.dump}"
+      exit 1
+    end
+  end
+end
+
+usage if help || test_name.nil?
+
+test_file = is_file ? File.expand_path(test_name) : ASAConsole::Test.test_path(test_name)
+
+terminal_opts ||= {}
+terminal_opts.keys.each { |key| terminal_opts[key.to_sym] = terminal_opts.delete(key) }
+terminal_opts[:host] = ask 'Host Name: ' unless terminal_opts[:host]
+terminal_opts[:user] = ask 'User Name: ' unless terminal_opts[:user]
+terminal_opts[:password] = ask('Password: ') { |q| q.echo = '*' } unless terminal_opts[:password]
+
+unless enable_password
+  pw = ask('Enable Password [ENTER for none]: ') { |q| q.echo = '*' }
+  enable_password = pw if pw.length > 0
+end
+
+exit 1 unless ASAConsole::Test.start(test_file, terminal_opts, enable_password, show_session_log)

data/lib/asa_console.rb

@@ -0,0 +1,283 @@
+
+require 'asa_console/config'
+require 'asa_console/error'
+require 'asa_console/terminal/fake_ssh'
+require 'asa_console/terminal/ssh'
+
+#
+# Command line interface to a Cisco ASA.
+#
+# @example
+#   # Create an instance of ASAConsole for an SSH connection
+#   asa = ASAConsole.ssh(
+#     host: 'fw01.example.com', # Required by Net::SSH
+#     user: 'admin',            # Required by Net::SSH
+#     password: 'mypass',       # Optional in case you want to use SSH keys
+#     connect_timeout: 3,       # Converted to the Net::SSH :timeout value
+#     command_timeout: 10,      # How long to wait for a command to execute?
+#     enable_password: 'secret' # Optional if it's the same as :password
+#   )
+#
+#   # Other Net::SSH options can be set before connecting
+#   asa.terminal.ssh_opts[:port] = 2022
+#
+#   asa.connect
+#   puts asa.show('version')
+#   asa.disconnect
+#
+# @attr_reader config_mode [String, nil]
+#   Configuration submode string (e.g. "config", "config-if") or `nil` if not
+#   in a configuration mode
+# @attr terminal [Object]
+#   An instance of a class from the {Terminal} module
+# @attr enable_password [String, nil]
+#   Enable password or `nil` if the enble password is not required
+#
+class ASAConsole
+  attr_reader :config_mode
+  attr_accessor :terminal
+  attr_accessor :enable_password
+
+  PASSWORD_PROMPT   = /^Password: +\z/
+  EXEC_PROMPT       = /^[\w\.\/-]+> +\z/
+  PRIV_EXEC_PROMPT  = /^[\w\.\/-]+(?:\(config[\s\w-]*\))?# +\z/
+  ANY_EXEC_PROMPT   = /^[\w\.\/-]+(?:(?:\(config[\s\w-]*\))?#|>) +\z/
+  CONFIG_PROMPT     = /^[\w\.\/-]+\(config[\s\w-]*\)# +\z/
+  INVALID_CMD_CHAR  = /[^\x20-\x3e\x40-\x7e]/
+  CONFIG_MODE_REGEX = /^[\w\.\-\/]+\((config[\s\w\-]*)\)# $/
+  CMD_ERROR_REGEX   = /^ERROR: (?:% )?(.*)/
+
+  class << self
+    # Factory method for a fake SSH console session.
+    #
+    # @api development
+    # @see Terminal::FakeSSH#initialize Terminal::FakeSSH constructor
+    # @option opts ... options for the {Terminal::FakeSSH} constructor
+    # @option opts [String] :enable_password
+    # @return [ASAConsole]
+    def fake_ssh(opts)
+      enable_password = opts.delete(:enable_password)
+      terminal = Terminal::FakeSSH.new(opts)
+      new terminal, enable_password
+    end
+
+    # Factory method for an SSH console session.
+    #
+    # @see Terminal::SSH#initialize Terminal::SSH constructor
+    # @option opts ... options for the {Terminal::SSH} constructor
+    # @option opts [String] :enable_password
+    # @return [ASAConsole]
+    def ssh(opts)
+      enable_password = opts.delete(:enable_password)
+      terminal = Terminal::SSH.new(opts)
+      new terminal, enable_password
+    end
+
+    private :new
+  end
+
+  # @private
+  def initialize(terminal, enable_password = nil)
+    @config_mode = nil
+    @terminal = terminal
+    @terminal.on_output do
+      matches = CONFIG_MODE_REGEX.match(@terminal.prompt)
+      @config_mode = matches ? matches[1] : nil
+    end
+    @enable_password = enable_password
+    @version = nil
+    @running_config = {}
+  end
+
+  # @return [void]
+  def connect
+    @terminal.connect
+    priv_exec! 'terminal pager lines 0'
+  end
+
+  # @return [Boolean]
+  def connected?
+    @terminal.connected?
+  end
+
+  # @return [void]
+  def disconnect
+    while @terminal.connected? && @terminal.prompt =~ ANY_EXEC_PROMPT
+      @terminal.send('exit', ANY_EXEC_PROMPT) { |success| break unless success }
+    end
+    @terminal.disconnect
+  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. Raises an exception if the
+  # expected prompt has not been received after waiting for `command_timeout`
+  # seconds following the last data transfer.
+  #
+  # @param line [String]
+  # @param expect_regex [Regexp]
+  # @param is_password [Boolean]
+  #   if `true`, `line` will be masked with asterisks in the session log
+  # @raise [Error::ExpectedPromptFailure]
+  # @return [String] output from the command, if any
+  def send(line, expect_regex, is_password = false)
+    must_be_connected!
+    line = line.gsub(INVALID_CMD_CHAR, "\x16\\0") unless is_password
+    @terminal.send(line, expect_regex, is_password) do |success, output|
+      fail Error::ExpectedPromptFailure, "Expected prompt not found in output: #{output}" unless success
+      output
+    end
+  end
+
+  # Execute a command in any configuration mode.
+  #
+  # @param command [String]
+  # @option opts [Regexp] :expect_prompt
+  #   prompt expected after executing the command
+  # @option opts [Boolean] :ignore_output
+  #   if `true`, do not raise an error when the command generates output (unless
+  #   the output is an error message)
+  # @option opts [Boolean] :ignore_errors
+  #   if `true`, ignore error messages in the output (implies `:ignore_output`)
+  # @option opts [Boolean] :require_config_mode
+  #   a specific configuration submode required to execute the command
+  # @return [String] output from the command, if any
+  def config_exec(command, opts = {})
+    must_be_connected!
+    enable! if @terminal.prompt =~ EXEC_PROMPT
+
+    expect_prompt = opts.fetch(:expect_prompt, CONFIG_PROMPT)
+    ignore_output = opts.fetch(:ignore_output, false)
+    ignore_errors = opts.fetch(:ignore_errors, false)
+    require_config_mode = opts[:require_config_mode]
+
+    unless @terminal.prompt =~ CONFIG_PROMPT
+      send('configure terminal', CONFIG_PROMPT)
+    end
+
+    if require_config_mode && @config_mode != require_config_mode
+      message = "Will not execute command in '%s' mode (expected '%s')"
+      fail Error::ConfigModeError, message % [ @config_mode, require_config_mode ]
+    end
+
+    # Any part of the config may change, so clear the cache.
+    @running_config = {}
+
+    output = send(command, expect_prompt)
+
+    unless ignore_errors
+      error = CMD_ERROR_REGEX.match(output)
+      fail Error::CommandError, "Error output after executing '#{command}': #{error[1]}" if error
+      unless ignore_output || output.empty?
+        fail Error::UnexpectedOutputError, "Unexpected output after executing '#{command}': #{output}"
+      end
+    end
+
+    output
+  end
+
+  # Execute a command from top-level configuration mode. This method is a
+  # wrapper for {#config_exec}.
+  #
+  # @see #config_exec
+  # @param command [String]
+  # @param opts [Hash] options for {#config_exec}
+  # @return [String] output from the command, if any
+  def config_exec!(command, opts = {})
+    must_be_connected!
+    send('exit', CONFIG_PROMPT) while @config_mode && @config_mode != 'config'
+    config_exec(command, opts)
+  end
+
+  # Execute a command in any privileged EXEC mode (includes config EXEC modes).
+  #
+  # @param command [String]
+  # @return [String] output from the command, if any
+  def priv_exec(command)
+    must_be_connected!
+    enable! if @terminal.prompt =~ EXEC_PROMPT
+    output = send(command, PRIV_EXEC_PROMPT)
+    error = CMD_ERROR_REGEX.match(output)
+    fail Error::CommandError, "Error output after executing '#{command}': #{error[1]}" if error
+    output
+  end
+
+  # Execute a command in privileged EXEC mode (excludes config EXEC modes). This
+  # method is a wrapper for {#priv_exec}.
+  #
+  # @see #priv_exec
+  # @param command [String]
+  # @return [String] output from the command, if any
+  def priv_exec!(command)
+    must_be_connected!
+    send('exit', PRIV_EXEC_PROMPT) while @config_mode
+    priv_exec(command)
+  end
+
+  # A shortcut for running "show" commands.
+  #
+  # @param subcmd [String]
+  # @return [String]
+  def show(subcmd)
+    priv_exec('show ' + subcmd)
+  end
+
+  # Execute a "show running-conifg [...]" command and load the results into a
+  # {Config} object.
+  #
+  # @see Config
+  # @param subcmd [String, nil]
+  # @return [Config] a top-level {Config} node with nested config
+  def running_config(subcmd = nil)
+    unless @running_config.key? subcmd
+      output = subcmd ? show('running-config ' + subcmd) : show('running-config')
+      @running_config[subcmd] = Config.new(nested_config: output)
+    end
+    @running_config[subcmd]
+  rescue Error::CommandError
+    Config.new
+  end
+
+  # ASA software version in `x.x(x)` format.
+  #
+  # @return [String]
+  def version
+    unless @version
+      # Reassemble the version string on the off chance that an interim release
+      # is reported in the format "x.x(x.x)" versus "x.x(x)x".
+      regex = /^Cisco Adaptive Security Appliance Software Version (\d+)\.(\d+)\((\d+).*?\)/
+      matches = regex.match(show('version'))
+      fail Error::VersionParseError, 'Unable to determine appliance version' unless matches
+      @version = '%d.%d(%d)' % matches[1..3]
+    end
+    @version
+  end
+
+  # Return the result of comparing the ASA software version with a list of
+  # expressions. Will `yield` once on success if a block is given.
+  #
+  # @example
+  #   asa.version? '9.x', '< 9.3' do
+  #     puts 'Running version 9.0, 9.1 or 9.2'
+  #   end
+  #
+  # @see Util.version_match? The utility function called by this method
+  # @param exprs [Array<String>]
+  # @return [Boolean] `true` if _all_ expressions match, or `false` otherwise
+  def version?(*exprs)
+    success = Util.version_match?(version, exprs)
+    yield if success && block_given?
+    success
+  end
+
+  def enable!
+    send('enable', PASSWORD_PROMPT)
+    password = @enable_password ? @enable_password : @terminal.password
+    send(password, PRIV_EXEC_PROMPT, true)
+  end
+  private :enable!
+
+  def must_be_connected!
+    fail Error::NotConnectedError, 'Terminal is not connected' unless @terminal.connected?
+  end
+  private :must_be_connected!
+end