ruby-jss 1.6.4 → 2.0.0a10

data/test/bin/runtests

@@ -1,6 +1,6 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
 
-### Copyright 2020 Pixar
+### Copyright 2022 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -25,36 +25,18 @@
 ###
 ###
 
-# Uses the MiniTest::Spec infrastructure to run one or tests of ruby-jss
-#
-# We do not use minitest/autorun, so that we have more control over which tests
-# are run and how. But the individual spec files are standard MiniTest::Spec
-# 'describe' blocks
-#
-# Those blocks become classes when the tests are run, and for each test,
-# an instance of the class is created.
-# As such, the interior of the blocks can be treated like class definitions,
-# defining constants, class methods, instance methods and so on.
-#
-# As well as that class-based infratructure, this tool includes a JSSTestHelper
-# module which defines usefule constants and helper methods, accessible from
-# anywhere via the module name.
-#
-
 require 'pathname'
 require 'getoptlong'
-require 'keychain'
-require 'minitest/spec'
-# require 'minitest/autorun' # DO NOT REQUIRE AUTORUN - we manually run each file below.
+require 'ruby-jss'
 
 # app
 class App
 
-  SPEC_SUFFIX = '_spec.rb'.freeze
+  TEST_MODULE_FILE_SUFFIX = '.rb'
 
   # Server and port come from CLI opts or ruby-jss.conf
   #
-  # User comes from CLI opt or keychain
+  # User comes from keychain, or prompt when saving credentials for host
   #
   # pw come from keychain, or is prompted and stored
   # in keychain with user.
@@ -62,85 +44,58 @@ class App
   # TODO: support for other APIConnection options
   #
   OPTS = GetoptLong.new(
-    ['--server', '-s', GetoptLong::REQUIRED_ARGUMENT],
+    ['--host', '-h', GetoptLong::REQUIRED_ARGUMENT],
     ['--port', '-p', GetoptLong::REQUIRED_ARGUMENT],
-    ['--user', '-u', GetoptLong::REQUIRED_ARGUMENT],
-    ['--db-server', '-S', GetoptLong::REQUIRED_ARGUMENT],
-    ['--db-port', '-P', GetoptLong::REQUIRED_ARGUMENT],
-    ['--db-user', '-U', GetoptLong::REQUIRED_ARGUMENT],
-    ['--gem-dir', '-g', '-i', GetoptLong::REQUIRED_ARGUMENT],
-    ['--saved-data', '-d', GetoptLong::NO_ARGUMENT],
-    ['--help', '-h', '-H', GetoptLong::NO_ARGUMENT]
+    ['--re-save', '-r', GetoptLong::REQUIRED_ARGUMENT],
+    ['--help', '-H', GetoptLong::NO_ARGUMENT]
   )
 
   # Setup
   def initialize
-    load_ruby_jss
+    raise "These tests only work in ruby-jss 2.0 and up. You are running #{JSS::VERSION}" unless JSS::VERSION[0].to_i > 1
+
     parse_opts
 
     @bindir = Pathname.new File.dirname(__FILE__)
     @appdir = @bindir.parent
     @libdir = @appdir + 'lib'
-    @specdir = @appdir + 'specs'
+    @testsdir = @appdir + 'tests'
 
     @tests_to_run = ARGV.dup
-    @tests_to_run = @specdir.children.map { |c| c.basename.to_s }.sort if @tests_to_run .empty?
+    @tests_to_run = @testsdir.children.map { |c| c.basename.to_s }.sort if @tests_to_run .empty?
+    @tests_to_run.delete_if { |t| t.start_with? '.'}
 
     @minitest_opts = ['--verbose']
 
-    helper_module = @libdir + 'testhelper.rb'
+    helper_module = @libdir + 'jamf_test.rb'
     load helper_module.to_s
   end # init
 
-  # Load the gem
-  def load_ruby_jss
-    if @custom_gem_dir
-      ENV['GEM_HOME'] = @custom_gem_dir
-      ENV['GEM_PATH'] = "#{@custom_gem_dir}:#{ENV['GEM_PATH']}"
-      Gem.paths = ENV
-    end
-    require 'ruby-jss'
-  end
-
   # Parse ARGV
   def parse_opts
     OPTS.each do |opt, arg|
       case opt
-      when '--server'
+      when '--host'
         @api_server = arg
-      when '--user'
-        @api_user = arg
       when '--port'
         @api_port = arg
-      when '--db-server'
-        @db_server = arg
-      when '--db-user'
-        @db_user = arg
-      when '--db-port'
-        @db_port = arg
+      when '--re-save'
+        @re_save_creds = true
       when '--gem-dir'
         @custom_gem_dir = arg
-      when '--saved-data'
-        @show_saved_data = true
       when '--help'
         @show_help = true
       end # case
     end # opts.each
   end
 
-  # the default values
-  def apply_defaults
-    @api_server ||= JSS::CONFIG.api_server_name
-    @api_port ||= JSS::CONFIG.api_server_port
-    @db_server ||= JSS::CONFIG.db_server_name
-    @db_port ||= JSS::CONFIG.db_server_port
-  end
-
+  #######################
   def run
     return if show_help
-    return if show_saved_data
-    connect_to_servers
+    raise ArgumentError, 'A server hostname must be provided with --host' unless @api_server
     return unless prod_server_confirmed_if_needed?
+
+    connect
     run_tests
   end
 
@@ -155,74 +110,52 @@ class App
     prod_server_line = conf.readlines.select { |l| l.start_with? 'api_server_name' }.first
     return true unless prod_server_line
 
-    prod_server = prod_server_line.chomp.split(': ').last
+    prod_server = prod_server_line.chomp.split(': ').last.strip
     return true unless prod_server == @api_server
 
     print "Really run the tests on the production server '#{prod_server}'? (y/n): "
-    doit = gets.chomp
+    doit = $stdin.gets.chomp
     doit == 'y'
   end
 
-  def connect_to_servers
-    jss_keychain_creds = JSSTestHelper::Auth.rw_credentials_from_keychain(:jss)
-    if jss_keychain_creds
-      @api_server ||= jss_keychain_creds[:server]
-      @api_port ||= jss_keychain_creds[:port]
-      @api_user ||= jss_keychain_creds[:user]
-      pw = jss_keychain_creds[:pw]
-    else
-      apply_defaults
-      raise 'Please specify a server with --server' unless @api_server
-      raise 'Please specify a user with --user' unless @api_user
-      pw = 'nopw'
-    end
-
-    JSSTestHelper::Auth.connect_to_api(server: @api_server, port: @api_port, user: @api_user, pw: pw )
+  ###################################
+  def connect
+    JamfTest::Auth.delete_api_creds(@api_server) if @re_save_creds
+    JamfTest::Auth.connect_to_api host: @api_server, port: @api_port
   end
 
+  ###################################
   def run_tests
-    JSSTestHelper.say "Starting tests of ruby-jss v #{JSS::VERSION}"
-    JSSTestHelper.say "API Connection: #{@api_user}@#{@api_server}:#{@api_port} running Jamf Pro #{JSS.api.server.version}"
-
-    base_runnables = MiniTest::Runnable.runnables.dup
+    JamfTest.say "Starting tests of ruby-jss v#{Jamf::VERSION}, using ruby version #{RUBY_VERSION}"
+    JamfTest.say "API Connection: #{Jamf.cnx}; Server running Jamf Pro #{Jamf.cnx.jamf_version}"
 
     @tests_to_run.each do |t|
-      t += SPEC_SUFFIX unless t.end_with? SPEC_SUFFIX
-      specfile = @specdir + t
-
-      puts
-
-      if specfile.file?
-        JSSTestHelper.say "Running test #{specfile.basename}: "
-        load specfile.to_s
-
-        MiniTest.run @minitest_opts.dup
+      t = t.chomp TEST_MODULE_FILE_SUFFIX
+      testfile = @testsdir + "#{t}#{TEST_MODULE_FILE_SUFFIX}"
+      unless testfile.file?
+        JamfTest.say "Skipping unknown test #{testfile.basename}"
+        next
+      end
 
-        # clear this files specs from the run list..
-        MiniTest::Runnable.runnables.select! { |r| base_runnables.include? r }
-        puts
-      else
-        JSSTestHelper.say "Skipping unknown test #{specfile.basename}"
-      end # if
+      load testfile.to_s
+      test_class = JamfTest.const_get(camelize_snake(t))
 
+      puts
+      JamfTest.say "Running test #{testfile.basename}: "
+      test_class.new.run_tests
+    rescue => e
+      puts "ERROR in '#{testfile.basename}': #{e.class}: #{e}"
+      puts e.backtrace
     end # each
   end # run tests
 
-  # display saved keychain data if asked
-  def show_saved_data
-    return false unless @show_saved_data
-    jss_keychain_creds = JSSTestHelper::Auth.rw_credentials_from_keychain(:jss)
-    msg =
-      if jss_keychain_creds
-        "JSS API Tests will run as user '#{jss_keychain_creds[:user]}' on server '#{jss_keychain_creds[:server]}', port #{jss_keychain_creds[:port]}"
-      else
-        'No JSS API credentials saved, please use --server, --user and --port (if needed)'
-      end
-    puts msg
-    true
+  ###################################
+  def camelize_snake(str)
+    str.to_s.split('_').map(&:capitalize).join
   end
 
   # display help if asked
+  ###################################
   def show_help
     return false unless @show_help
     puts <<-USAGEBLURB
@@ -258,18 +191,12 @@ If a different user is later specified for that server, you'll be prompted again
 for a password, and the keychain will be updated.
 
 Options
-  --server, -s <host>         the hostname for the JSS API connection
-  --port, -p <port>           the port for the API connection
-  --user, -u <user>           the API username for the connection
-                                NOTE: must have permissions to perform the tests!
-  --db-server, -S <host>      the hostname for the JSS API connection
-  --db-port, -P <port>        the port for the API connectino
-  --db-user, -U <user>        the API username for the connection
-  --gem-dir, -g, -i <path>    the path from which to require ruby-jss
-                                (sets GEM_HOME to this path before requiring)
-  --saved-data, -d            show the connection data saved in the keychain,
-                                if any. (no tests run, password not shown)
-  --help, -h, -H              show this help
+  --host, -h <host>           The hostname for the JSS API connection
+  --port, -p <port>           The port for the API connection
+  --re-save, -r               Prompt for user and passwd for this host, even if
+                                already saved in the keychain
+  --gem-dir, -g, <path>       The path from which to require ruby-jss
+  --help, -h, -H              Show this help
     USAGEBLURB
     true
   end # show_help
@@ -282,9 +209,9 @@ if $PROGRAM_NAME == __FILE__
     app = App.new
     app.run
     exit 0
-  rescue => the_exception
-    warn "An error occurred: #{the_exception.message}"
-    warn the_exception.backtrace
+  rescue => e
+    puts "ERROR #{e.class}: #{e}"
+    puts e.backtrace
     exit 1
   end # begin
 end # if $0 == __FILE__

data/test/lib/jamf_test/APITest.rb

@@ -0,0 +1,80 @@
+### Copyright 2022 Pixar
+###
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###
+###    You may obtain a copy of the Apache License at
+###
+###        http://www.apache.org/licenses/LICENSE-2.0
+###
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+###
+###
+
+module JamfTest
+
+  class APITest
+
+    #####
+    def say(msg)
+      JamfTest.say msg, from: self.class.to_s
+    end
+
+    # The main test method
+    # each subclass MUST define a run_class_tests method
+    #####
+    def run_tests
+      run_class_tests
+
+      say "Done! Congrats, #{self.class} looks good!"
+    end
+
+    #####
+    def validate_hash(hash, has_key: nil, val_class: nil)
+      raise 'Value is not a Hash' unless hash.is_a? Hash
+      return unless has_key
+
+      raise "Hash does not have required key #{has_key}" unless hash.key? has_key
+      return unless val_class
+
+      raise "Value for Hash key #{has_key} is not a #{val_class}" unless hash[has_key].is_a? val_class
+    end
+
+    #####
+    def validate_array(ary, item_class: nil)
+      raise 'Value is not an Array' unless ary.is_a? Array
+      return unless item_class
+
+      if ary.empty?
+        puts 'WARNING: Array is empty! This may be OK depending on your environment'
+        return
+      end
+
+      raise "Randomly chosen item from Array is not a #{item_class}" unless ary.sample.is_a? item_class
+    end
+
+    # Ruby 3's default behavior when raising exceptions will include the output
+    # of #inspect, recursively for all data in an object.
+    # For many OAPIObjects, esp JPAPI Resources, this includes the embedded
+    # Connection object and all the caches is might hold, which might be
+    # thousands of lines.
+    # we override that here to prevent that. I've heard rumor this will be
+    # fixed in ruby 3.2
+    def inspect
+      "<#{self.class}:#{object_id}>"
+    end
+
+  end # class
+
+end # module JamfTest

data/test/lib/jamf_test/auth.rb

@@ -0,0 +1,267 @@
+### Copyright 2022 Pixar
+
+###
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###
+###    You may obtain a copy of the Apache License at
+###
+###        http://www.apache.org/licenses/LICENSE-2.0
+###
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+###
+###
+
+module JamfTest
+
+  # auth
+  module Auth
+
+    require 'open3'
+    require 'pathname'
+
+    # The security command
+    SEC_COMMAND = '/usr/bin/security'
+
+    # exit status when the keychain password provided is incorrect
+    SEC_STATUS_AUTH_ERROR = 51
+
+    # exit status when the desired item isn't found in the keychain
+    SEC_STATUS_NOT_FOUND_ERROR = 44
+
+    KEYCHAIN_LABEL_BASE = 'ruby-jss testing suite: '.freeze
+    KEYCHAIN_API_LABEL = KEYCHAIN_LABEL_BASE + 'API Access'
+
+    KEYCHAIN_SVC_BASE = 'com.pixar.ruby-jss.testing'.freeze
+    KEYCHAIN_API_SVC = KEYCHAIN_SVC_BASE + '.api'
+
+    ###########################
+    def self.connect_to_api(host:, port: nil)
+      creds = api_creds host: host
+      creds ||= prompt_for_api_pw(host: host, port: port)
+
+      Jamf.connect host: host, port: creds[:port], user: creds[:user], pw: creds[:pw]
+    end
+
+    # return the user's API password, prompting for it if we don't already have
+    # it
+    ###########################
+    def self.prompt_for_api_pw(host:, port: nil)
+      # If we're here, we need to get theuser and  pw via prompt
+      print "Enter the API username for #{host}: "
+      user = $stdin.gets.chomp
+
+      pw = prompt_for_password prompt: "Enter the API password for #{user}@#{host}" do |apw|
+        Jamf.cnx.disconnect
+        Jamf.cnx.connect user: user, pw: apw, host: host, port: port
+        true
+      rescue JSS::AuthenticationError
+        false
+        # begin
+      end # do apw
+      raise JSS::AuthenticationError, "Incorrect API password for #{user}@#{host}" unless pw
+
+      save_api_creds(host: host, user: user, pw: pw, port: port)
+
+      { user: user, pw: pw, port: port }
+    end
+
+    # Prompt the user for a password in the shell
+    # Returns:
+    #   - a valid password, or
+    #   - false if no valid password after the max number of tries
+    #
+    # Displays the provided promp. Passes what the user types to the block you
+    # provide, which must return a Boolean indicating if the password was correct.
+    #
+    # @param prompt[String] The message asking for the password
+    #
+    # @option max_tries[Integer] The max number of times to let the
+    #   user enter the passwd. Defaults to 3
+    #
+    # @option retry_msg[String] the text to display after a failure,
+    #   but before :max_tries failures. Defaults to "Try again: " followed
+    #   by the text arg.
+    #
+    # @option failed_msg[String] The message to display after :max_tries
+    #   failures. Defaults to  "Too many failed attempts"
+    #
+    # @yield The block should figure out if the user typed the correct password
+    #
+    # @yieldparam pw [String] The password typed by the user in the input field
+    #
+    # @yieldreturn [Boolean] Was the password correct?
+    #
+    # @return [String] The validated password
+    # @return [false] The user failed after max_tries: attempts.
+    #
+    ############################
+    def self.prompt_for_password(**options)
+      colon = ':'
+      # set defaults
+      options[:prompt] ||= 'Enter your password:'
+      options[:prompt] << colon unless options[:prompt].end_with? colon
+      options[:max_tries] ||= 3
+      options[:retry_msg] ||= "Try Again. #{options[:prompt]}"
+      options[:failed_msg] ||= 'Too many failed attempts'
+
+      tries = 0
+
+      prompt = options[:prompt]
+
+      while tries < options[:max_tries]
+        print "#{prompt} "
+        system 'stty -echo'
+        pw = $stdin.gets.chomp
+        puts
+        system 'stty echo'
+        return pw if yield pw
+
+        prompt = options[:retry_msg]
+        tries += 1
+      end
+      puts options[:failed_msg]
+      false
+    ensure # make sure terminal is usable at the end of this
+      system 'stty echo'
+    end # prompt_for_password
+
+    # Save the API testing credentials to the default keychain
+    ###########################
+    def self.save_api_creds(host:, user:, pw:, port: nil)
+      delete_api_creds(host: host)
+
+      cmd = +'add-internet-password'
+      cmd << " -a #{escape_for_security user}"
+      cmd << " -s #{escape_for_security host}"
+      cmd << " -l #{escape_for_security KEYCHAIN_API_LABEL}"
+      cmd << " -P #{port}" if port
+      cmd << " -w #{escape_for_security pw}"
+
+      run_security cmd
+      :saved
+    end
+
+    ###########################
+    def self.delete_api_creds(host:)
+      # NOTE: -s must come before -l
+      cmd = +'delete-internet-password'
+      cmd << " -s #{escape_for_security host}"
+      cmd << " -l #{escape_for_security KEYCHAIN_API_LABEL}"
+
+      run_security cmd
+      :deleted
+    rescue
+      nil
+    end
+
+    # retrieve the API testing credentials from the default keychain
+    #
+    # @return [Hash] The user, pw and possibly port for accessing the API
+    #   on the host
+    ###########################
+    def self.api_creds(host:)
+      # NOTE: -s must come before -l
+      cmd = +'find-internet-password'
+      cmd << " -s #{escape_for_security host}"
+      cmd << " -l #{escape_for_security KEYCHAIN_API_LABEL}"
+      output = run_security(cmd)
+
+      output =~ /"acct"<blob>="(.+)"$/
+      user = Regexp.last_match[1]
+
+      output =~ /"port"<uint32>=0x([A-F0-9]+)( |$)/
+      port = Regexp.last_match[1]
+      port &&= port.to_i(16)
+
+      cmd << ' -w'
+      pw = run_security(cmd).chomp
+
+      { user: user, pw: pw, port: port }
+    rescue
+      nil
+    end
+
+    # Run the security command in interactive mode on a given keyshcain,
+    # passing in a subcommand and its arguments. so that they don't appear in the
+    # `ps` output
+    #
+    # @param cmd [String] the subcommand being passed to 'security' with
+    #   all needed options. It will not be visible outide this process, so
+    #   its OK to put passwords into the options.
+    #
+    # @return [String] the stdout of the 'security' command.
+    #
+    #################################
+    def self.run_security(cmd)
+      output = ''
+      errs = ''
+      exit_status = nil
+
+      Open3.popen3("#{SEC_COMMAND} -i") do |stdin, stdout, stderr, wait_thr|
+        # pid = wait_thr.pid # pid of the started process.
+        stdin.puts cmd
+        stdin.close
+        output = stdout.read
+        errs = stderr.read
+        exit_status = wait_thr.value # Process::Status object returned.
+      end
+      return output.chomp if exit_status.success?
+
+      case exit_status.exitstatus
+      when SEC_STATUS_AUTH_ERROR
+        raise 'Incorrect keychain password'
+      when SEC_STATUS_NOT_FOUND_ERROR
+        raise 'No matching item was found in the keychain'
+      else
+        errs.chomp!
+        errs =~ /: returned\s+(-?\d+)$/
+        errnum = Regexp.last_match(1)
+        desc = nil
+        if errnum
+          desc = `#{SEC_COMMAND} error #{errnum}`
+          desc =
+            if desc.include?('unknown error')
+              nil
+            else
+              desc.chomp.split(errnum).last
+            end
+        end
+        desc ||= errs
+        raise "Keychain Error: #{desc.gsub("\n", '; ')}; exit status #{exit_status.exitstatus}"
+      end # case
+    end # run_security
+
+    # given a string, wrap it in single quotes and escape internal single quotes
+    # and backslashes so it can be used in the interactive 'security' command
+    #
+    # @param str[String] the string to escape
+    #
+    # @return [String] the escaped string
+    ############################
+    def self.escape_for_security(str)
+      # first escape backslashes
+      str = str.to_s.gsub '\\', '\\\\\\'
+
+      # then single quotes
+      str.gsub! "'", "\\\\'"
+
+      # if other things need escaping, add them here
+
+      "'#{str}'"
+    end # escape
+
+  end # module auth
+
+end # module JamfTest