ruby-jss 1.0.0b2 → 1.0.0b6

data/test/lib/testhelper/auth.rb

@@ -0,0 +1,275 @@
+### Copyright 2018 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 JSSTestHelper
+
+  # auth
+  module Auth
+
+    KEYCHAIN_LABEL_BASE = 'com.pixar.ruby-jss.testing'.freeze
+
+    KEYCHAIN_JSS_LABEL = KEYCHAIN_LABEL_BASE + '.api'
+    KEYCHAIN_DB_LABEL = KEYCHAIN_LABEL_BASE + '.db'
+    KEYCHAIN_DIST_LABEL = KEYCHAIN_LABEL_BASE + '.distribution'
+
+    KEYCHAIN_DIST_ACCT = 'From JSS'.freeze
+
+    KEYCHAIN_LABELS = {
+      jss: KEYCHAIN_JSS_LABEL,
+      db: KEYCHAIN_DB_LABEL,
+      dist: KEYCHAIN_DIST_LABEL
+    }.freeze
+
+    module_function
+
+    # return the user's API password, prompting for it if we don't already have
+    # it
+    #
+    def api_pw(server: nil, port: nil, user: nil)
+      return @api_pw if @api_pw
+      # If we're here, we need to get the pw via prompt
+      @api_pw = prompt_for_password prompt: "Enter the API password for #{user}@#{server}:#{port}" do |apw|
+        begin
+          JSS.api.disconnect
+          JSS.api.connect user: user, pw: apw, server: server, port: port
+          true
+        rescue JSS::AuthenticationError
+          false
+        end # begin
+      end # do apw
+      raise JSS::AuthenticationError, "Incorrect API password for #{user}@#{server}:#{port}" unless @api_pw
+      @api_pw
+    end
+
+    # return the server, port, and user, which we might have gotten fromthe keychain
+    def connect_to_api(server: nil, user: nil, port: nil, pw: nil)
+      return if JSS.api.connected?
+
+      JSS.api.connect server: server, port: port, user: user, pw: pw
+      @api_pw = pw
+      { server: JSS.api.hostname, port: JSS.api.port, user: JSS.api.jss_user }
+    rescue JSS::AuthenticationError
+      # If we're here, we need to prompt for the pw
+      pw = api_pw server: server, port: port, user: user
+    ensure
+      # store the pw
+      save_rw_credentials label: KEYCHAIN_JSS_LABEL, acct: JSS.api.jss_user, server: JSS.api.hostname, port: JSS.api.port, pw: pw if JSS.api.connected?
+    end
+
+    # TODO: update this as API above so there's only one per keychain.
+    def db_pw
+      return @db_pw if @db_pw
+
+      # If we're here, we need to get the passwd for the user
+      @db_pw = prompt_for_password prompt: "Enter the MySQL password for #{@db_user}@#{@db_server}" do |apw|
+        begin
+          JSS::DB_CNX.disconnect
+          JSS::DB_CNX.connect server: @db_server, user: @db_user, pw: apw
+          true
+        rescue Mysql::ServerError::AccessDeniedError
+          false
+        end # begin
+      end # do apw
+
+      raise JSS::AuthenticationError, "Incorrect MySQL password for #{@db_user}@#{@db_server}" unless @db_pw
+      @db_pw
+    end
+
+    # TODO: update this as API above so there's only one per keychain.
+    def connect_to_db(server: nil, user: nil)
+      return if JSS::DB_CNX.connected?
+      @db_server = server ? server : JSS::CONFIG.api_server_name
+      @db_user = user
+
+      raise 'No db_server_name defined in /etc/ruby-jss.conf. Please specify with --db-server' unless @db_server
+
+      # look in the keychain
+      keychain_creds = rw_credentials_from_keychain(:db, @db_server, @db_user)
+
+      # did we get a user/pw? Use it
+      if keychain_creds
+        @db_user ||= keychain_creds[:user]
+        begin
+          JSS::DB_CNX.connect server: @db_server, user: @db_user, pw: keychain_creds[:password]
+
+          return
+        rescue Mysql::ServerError::AccessDeniedError
+          # re-prompt if bad pw in keychain
+          say "Stored MySQL password for #{@db_user}@#{@db_server} is incorrect"
+        end # begin
+      else
+        # Couldn't find a stored user for server, and no user given on CLI - error.
+        raise "No user stored for MySQL server '#{@db_server}'. Please specify with --db-user" unless @db_user
+      end
+
+      # If we're here, we need to get the passwd for the user
+      pw = db_pw
+
+      # store the pw
+      save_rw_credentials KEYCHAIN_DB_LABEL, @db_user, @db_server, pw
+    end
+
+    # TODO: pass in the API server for which we want the dist point pw
+    # must be connected to api
+    # and make it like API connection above, 1 per keychain.
+    def dist_point_pw
+      keychain_creds = rw_credentials_from_keychain(:db, @api_server, KEYCHAIN_DIST_ACCT)
+      if keychain_creds
+        @distpw = keychain_creds[:password]
+        return @distpw if JSS::DistributionPoint.master_distribution_point.check_pw :rw, distpw
+      end
+
+      # if we're here, there was no stored pw or it was incorrect
+
+      # If we're here, we need to get the passwd for the master dist point
+      prmpt = "Enter the RW password for the Master Distribution Point on JSS #{@api_server}"
+      @distpw = prompt_for_password prompt: prmpt do |apw|
+        JSS::DistributionPoint.master_distribution_point.check_pw :rw, apw
+      end # do apw
+
+      raise JSS::AuthenticationError, "Incorrect RW password for the Master Distribution Point on JSS #{@api_server}" unless @distpw
+
+      # store the pw
+      save_rw_credentials KEYCHAIN_DIST_LABEL, KEYCHAIN_DIST_ACCT, @api_server, @distpw
+      @distpw
+    end
+
+    # Fetch read-write credentials from the login keychain
+    #
+    # If the login keychain is locked, the user will be prompted
+    # to unlock it in the GUI.
+    #
+    # @param kind[Symbol] which kind of credentials? :jss, :db, or :dist
+    #
+    # @return [Hash{Symbol => String}, nil] A Hash with :server, :user and :password
+    #   values, nil if no matching keychain item.
+    #
+    def rw_credentials_from_keychain(kind)
+      Keychain.user_interaction_allowed = true
+      unlock_keychain
+      label = KEYCHAIN_LABELS[kind]
+      raise JSS::InvalidDataError, "argument must be one of :#{RW_CREDENTIAL_KINDS.join ', :'}" unless label
+
+      pw_search = { label: label }
+      pw_item = Keychain.default.internet_passwords.where(pw_search).first
+
+      return nil unless pw_item
+
+      { server: pw_item.server, user: pw_item.account, pw: pw_item.password, port: pw_item.port }
+    end
+
+    # Save the credentials in the login keychain
+    #
+    # @param user[String] the username to save
+    #
+    # @param pw[String] the password to save with the username
+    #
+    # @return [void]
+    #
+    def save_rw_credentials(label: nil, acct: nil, server: nil, pw: nil, port: nil)
+      Keychain.default.internet_passwords.where(label: label).all.each(&:delete)
+      item = Keychain.default.internet_passwords.create label: label, account: acct, server: server, password: pw, port: port
+      item.save!
+    end
+
+    # Prompt the user to unlock the default keychain
+    #
+    # @return [void]
+    #
+    def unlock_keychain
+      return true unless Keychain.default.locked?
+      unlocked = prompt_for_password prompt: 'Enter your keychain password' do |pw|
+        begin
+          Keychain.default.unlock! pw
+          true
+        rescue Keychain::AuthFailedError
+          false
+        end # begin
+      end # prompt for pass
+      raise JSS::AuthenticationError, 'Failed to unlock default keychain' unless unlocked
+    end # unlock keychain
+
+    # 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 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
+
+  end # module auth
+
+end # module JSSTestHelper

data/test/lib/testhelper/patch_mgmt.rb

@@ -0,0 +1,123 @@
+### Copyright 2018 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 JSSTestHelper
+
+  # auth
+  module PatchMgmt
+
+    EXT_SRC_NAME = 'rubyjss-testPatchSource.company.com'.freeze
+    EXT_SRC_PORT = 8843
+
+    PATCH_TITLE_NAME = 'rubyjss-testPatchTitle'.freeze
+    PATCH_TITLE_SOURCE = 'Jamf'.freeze
+
+    PATCHCPOL_NAME = 'rubyjss-testPatchPolicy'.freeze
+
+    module_function
+
+    # Sources
+
+    def internal_src
+      @internal_src ||= JSS::PatchInternalSource.fetch id: 1
+    end
+
+    def external_src
+      @external_src ||= JSS::PatchExternalSource.make name: EXT_SRC_NAME
+    end
+
+    def refetch_external_src
+      @external_src = JSS::PatchExternalSource.fetch name: EXT_SRC_NAME
+    end
+
+    def delete_external_src
+      return [] unless JSS::PatchExternalSource.all_names(:refresh).include? EXT_SRC_NAME
+      JSS::PatchExternalSource.delete JSS::PatchExternalSource.map_all_ids_to(:name).invert[EXT_SRC_NAME]
+    end
+
+    # Titles
+
+    def name_id
+      @name_id ||= JSS::PatchInternalSource.available_name_ids(1).sample
+    end
+
+    def title(refresh = false)
+      @title = nil if refresh
+      return @title if @title
+      @title =
+        if JSS::PatchTitle.all_names.include? PATCH_TITLE_NAME
+          JSS::PatchTitle.fetch source: PATCH_TITLE_SOURCE, name_id: name_id
+        else
+          JSS::PatchTitle.make name: PATCH_TITLE_NAME, source: PATCH_TITLE_SOURCE, name_id: name_id
+        end
+    end
+
+    def delete_title
+      return [] unless JSS::PatchTitle.all_names(:refresh).include? PATCH_TITLE_NAME
+      JSS::PatchTitle.delete JSS::PatchTitle.map_all_ids_to(:name).invert[PATCH_TITLE_NAME]
+    end
+
+    # Versions
+
+    def version_key
+      @version_key ||= title.versions.keys.sample
+    end
+
+    # Patch Policies
+
+    def policy(refresh = false)
+      @policy = nil if refresh
+      return @policy if @policy
+
+      # make sure we have a title with which to create a patch pol
+      unless title.in_jss
+        title.source_id = 1 unless title.source_id
+        title.name_id = name_id unless title.name_id
+        title.save
+      end
+
+      # make sre the desired version has a package
+      unless title.versions[version_key].package_id.is_a? Integer
+        title.versions[version_key].package = JSS::Package.all_ids.sample
+        title.save
+      end
+
+      # if the policy exists fetch it, otherwise make it
+      @policy =
+        if JSS::PatchPolicy.all_names(:refresh).include? PATCHCPOL_NAME
+          JSS::PatchPolicy.fetch name: PATCHCPOL_NAME
+        else
+          JSS::PatchPolicy.make name: PATCHCPOL_NAME, patch_title: title
+        end
+    end
+
+    def delete_policy
+      return [] unless JSS::PatchPolicy.all_names(:refresh).include? PATCHCPOL_NAME
+      JSS::PatchPolicy.delete JSS::PatchPolicy.map_all_ids_to(:name).invert[PATCHCPOL_NAME]
+    end
+
+  end # module PatchMgmt
+
+end # module JSSTestHelper

data/test/lib/testhelper.rb

@@ -0,0 +1,69 @@
+### Copyright 2018 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.
+###
+###
+
+# Methods and constants for the tests
+module JSSTestHelper
+
+  TOP_PREFIX = '>>>>>'.freeze
+  TEST_PREFIX = '---->'.freeze
+
+  ERROR_PREFIX1 = '****-> ERROR in :'.freeze
+  ERROR_PREFIX2 = '****->   '.freeze
+
+  module_function
+
+  def say(msg, from: :top)
+    msgs = msg.is_a?(Array) ? msg : [msg]
+    prefix =
+      if from == :top
+        TOP_PREFIX
+      else
+        puts # for interlacing with minitest's dots
+        "-- #{from} #{TEST_PREFIX}"
+      end
+    msgs.each { |m| puts "#{prefix} #{m}" }
+  end
+
+  def report(a_problem)
+    if a_problem.is_a? Exception
+      puts caller_locations
+      src = caller_locations(5..5).first
+      msg = a_problem.to_s
+    else
+      src = caller_locations(3..3).first
+      msg = a_problem
+    end
+    location = "method '#{src.label}' at line #{src.lineno} of #{File.basename src.path}"
+    @errors << "#{location}: #{msg}"
+    puts " #{ERROR_PREFIX1} #{location}"
+    puts " #{ERROR_PREFIX2} #{msg}"
+  end
+
+end # module JSSTestHelper
+
+# load in the rest of the module
+libdir = Pathname.new File.dirname(__FILE__)
+moduledir = libdir + 'testhelper'
+moduledir.children.each { |mf| load mf.to_s }

data/test/specs/api_connection_spec.rb

@@ -0,0 +1,57 @@
+### Copyright 2018 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.
+###
+###
+
+describe JSS::APIConnection do
+
+  ##### Constants
+
+  TEST_CONNECTION_NAME = 'testconnection'.freeze
+
+  ##### Specs
+
+  # this happens before each 'it' block below.
+  before do
+    @newcon = JSS::APIConnection.new(
+      server: JSS.api.hostname,
+      user: JSS.api.jss_user,
+      pw: JSSTestHelper::Auth.api_pw(server: nil, port: nil, user: nil),
+      name: TEST_CONNECTION_NAME
+    )
+  end
+
+  it 'can be created' do
+    @newcon.must_be_instance_of JSS::APIConnection
+  end
+
+  it 'has a settable name at creation' do
+    @newcon.name.must_equal TEST_CONNECTION_NAME
+  end
+
+  it 'can be made default' do
+    JSS.use_api_connection @newcon
+    JSS.api.name.must_equal TEST_CONNECTION_NAME
+  end
+
+end

data/test/specs/patch01_source_spec.rb

@@ -0,0 +1,54 @@
+### Copyright 2018 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.
+###
+###
+
+# Patch Source MetaClass
+#
+describe JSS::PatchSource do
+
+  ##### Specs
+
+  it 'can list all patch sources' do
+    JSS::PatchSource.all.must_be_instance_of Array
+    JSS::PatchSource.all.first.must_be_instance_of Hash
+  end
+
+  it 'can be used to fetch subclass' do
+    JSS::PatchSource.fetch(id: 1).must_be_instance_of JSS::PatchInternalSource
+  end
+
+  it 'can list available titles for a subclass from class method' do
+    titles = JSS::PatchSource.available_titles 1
+    titles.must_be_instance_of Array
+    titles.first.must_be_instance_of Hash
+    titles.first[:last_modified].must_be_instance_of Time
+  end
+
+  it 'can list available name_ids for a subclass from class method' do
+    name_ids = JSS::PatchSource.available_name_ids 1
+    name_ids.must_be_instance_of Array
+    name_ids.first.must_be_instance_of String
+  end
+
+end # describe JSS::PatchSource

data/test/specs/patch02_internal_source_spec.rb

@@ -0,0 +1,88 @@
+### Copyright 2018 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.
+###
+###
+
+# Internal Sources
+#
+describe JSS::PatchInternalSource do
+
+  ##### Class Methods
+
+  ##### Instance Methods
+
+  # shortcut
+  def src
+    JSSTestHelper::PatchMgmt.internal_src
+  end
+
+  ##### Specs
+
+  it 'cannot be created' do
+    proc { JSS::PatchInternalSource.make name: 'foo' }.must_raise JSS::UnsupportedError
+  end
+
+  it 'cannot be modified' do
+    proc { src.host_name = 'foo' }.must_raise NoMethodError
+    proc { src.port = 'foo' }.must_raise NoMethodError
+  end
+
+  it 'cannot be disabled' do
+    proc { src.disable }.must_raise NoMethodError
+  end
+
+  it 'cannot be deleted' do
+    proc { src.delete }.must_raise JSS::UnsupportedError
+  end
+
+  it 'tells us if it is enabled' do
+    JSS::TRUE_FALSE.must_include src.enabled?
+  end
+
+  it 'tells us its hostname' do
+    src.host_name.must_be_instance_of String
+    src.host_name.wont_be_empty
+  end
+
+  it 'tells us its port' do
+    src.port.must_be_kind_of Integer
+  end
+
+  it 'tells us if ssl is enabled' do
+    JSS::TRUE_FALSE.must_include src.ssl_enabled?
+  end
+
+  it 'lists its available titles' do
+    titles = src.available_titles
+    titles.must_be_instance_of Array
+    titles.first.must_be_instance_of Hash
+    titles.first[:last_modified].must_be_instance_of Time
+  end
+
+  it 'lists its available name_ids' do
+    name_ids = src.available_name_ids
+    name_ids.must_be_instance_of Array
+    name_ids.first.must_be_instance_of String
+  end
+
+end # describe JSS::PatchInternalSource