ruby-jss 2.1.0 → 3.0.0b1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 970c4289986bb3f0b3ea9a60b31777a29b4c927879a3204d28c3f9bdd46a2a9f
-  data.tar.gz: f75ae4ae8ba5bd0cfadb065c62f495fcb4eea86b2473aa5d8357569e9ce49059
+  metadata.gz: a7af617b6ac8bb27cbc7d5c790a2de9fa788fb3d426ae062581654fbc9f77c5f
+  data.tar.gz: f5dfabfdde6c466951862fdc458321ad4f9384293e1fe773fb78a0ca80e51283
 SHA512:
-  metadata.gz: b86acc435cc02cdd0976361305331b4bf98b176fd25c8accb791cfba794c7bdf6d42d94d62cc76b11cb510e9c3ac23495ac99aa244e76a39e5e6e061aeeae4a8
-  data.tar.gz: 31f95548e2cb64bedb1781977222c705183c3e866ce8c8a9fb5532dfdbdeabe11d59faa92818c8506d5235d2fc868d1eb58d949b17ecc5f6c3d66bafde910750
+  metadata.gz: 85fd8c1218206a35545cc034058996a5b03183f29ac443cf65735c547975afcedaf406f74099f610380a1b72272db5240c2427ab4e87201ef5d9ec7ceffd2f29
+  data.tar.gz: a04b06cbcb9858b06dfe738ced2943e37b6a12088da394599b6ccfae66ac0a9c1bc82a264dac02c0379308141d4cc9795594c19639f473e5684cdd62e48db368

data/CHANGES.md

@@ -14,6 +14,33 @@ __Please update all installations of ruby-jss to at least v1.6.0.__
 
 Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue and providing examples of how it could be exploited.
 
+--------
+
+## \[UNRELEASED]
+
+### Added
+  - Jamf::Policy.flush_logs_for_computers: formerly private class method, now public and used for flushing policy logs for specific computers.
+
+### Fixed
+  - Fix bug in MDM enable_lost_mode instance method, and make the default behavior match the API
+  - Specify the connection instance when validating ids in MacOSManagedUpdates
+  - Send mandatory field 'name' with a MobileDeviceApplication request (Thanks @yanniks!)
+  - Policy Log Flushing now reflects API limitation: You can flush logs for a policy for all computers, or for a computer for all policies, but not specific policies for specific computers. See Jamf::Policy.flush_logs and Jamf::Policy.flush_logs_for_computers
+  - A validation method wasn't passing cnx param correctly.
+
+### Changed
+  - MacOSManagedUpdates.send_managed_os_update takes symbols as the updateAction
+
+## \[2.1.1] - 2022-11-07
+
+### Fixed & Deprecated
+
+  - The classic API no longer includes SHA256 hashes of various passwords - the data value is there, but only contains a string of asterisks. As such, ruby-jss can no longer use those to validate some passwords before trying to use them. The methods doing so are still present, but only return `true`. If an incorrect password is given, the underlying process that uses it will fail on its own.
+  These methods will be removed in a future version of ruby-jss:
+    - `Jamf::DistributionPoint#check_pw`  Used mostly by the `Jamf::DistributionPoint#mount` method
+    - `Jamf::Policy.verify_management_password`
+
+
 ## \[2.1.0] - 2022-10-10
 
 ### Added

data/lib/jamf/api/classic/api_objects/computer.rb

@@ -1158,15 +1158,29 @@ module Jamf
       @need_to_update = true
     end
 
-    # flush the logs for this computer in a given policy
-    # @see Jamf::Policy.flush_logs
+    # Flush all policy logs for this computer older than a given time period.
     #
-    def flush_policy_logs(policy, older_than: 0, period: :days)
-      Jamf::Policy.flush_logs(
-        policy,
+    # IMPORTANT: from the Jamf Developer Site:
+    #   The ability to flush logs is currently only supported for flushing all logs
+    #   for a given policy or all logs for a given computer. There is no support for
+    #   flushing logs for a given policy and computer combination.
+    #
+    # With no parameters, will flush all logs for the computer
+    #
+    # NOTE: Currently the API doesn't have a way to flush only failed policies.
+    #
+    # @param older_than[Integer] 0, 1, 2, 3, or 6
+    #
+    # @param period[Symbol] :days, :weeks, :months, or :years
+    #
+    # @see Jamf::Policy.flush_logs_for_computers
+    #
+    def flush_policy_logs(older_than: 0, period: :days)
+      Jamf::Policy.flush_logs_for_computers(
+        [@id],
         older_than: older_than,
         period: period,
-        computers: [@id], cnx: @cnx
+        cnx: @cnx
       )
     end
 

data/lib/jamf/api/classic/api_objects/distribution_point.rb

@@ -259,8 +259,8 @@ module Jamf
     attr_reader :ssh_password_sha256
 
     def initialize(**args)
-      super 
-      
+      super
+
       @ip_address = @init_data[:ip_address]
       @local_path = @init_data[:local_path]
       @enable_load_balancing = @init_data[:enable_load_balancing]
@@ -294,44 +294,28 @@ module Jamf
 
       @port = @init_data[:ssh_password]
 
-      # Note, as of Casper 9.3:
-      # :management_password_md5=>"xxxxx"
-      # and
-      # :management_password_sha256=> "xxxxxxxxxx"
-      # Are the read/write password
-      #
-      # An empty passwd is
-      # MD5 = d41d8cd98f00b204e9800998ecf8427e
-      # SHA256 = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
-      #
-      # Seemms the read-only pw isn't available in the API
-
       # if we mount for fileservice, where's the mountpoint?
       @mountpoint = DEFAULT_MOUNTPOINT_DIR + "#{DEFAULT_MOUNTPOINT_PREFIX}#{@id}"
     end # init
 
-    # Check the validity of a password.
+    # @deprecated The API no longer sends SHA256 hashed password data, and instead
+    #   only has a string of asterisks, meaning we can no longer use it to validate
+    #   passwords before attempting to use them. Instead, the processes that use
+    #   them, e.g. mounting a Dist. Point, will fail on their own if the pw is not
+    #   valid.
     #
-    # @param user[Symbol] one of :ro, :rw, :ssh, :http
+    #   This method remains defined for backward-compatibility with any existing
+    #   code that calls it. but it will always return true. It will be removed in
+    #   a future version
     #
-    # @param pw[String] the password to check for the given user
+    # @param user[Symbol] ignored
     #
-    # @return [Boolean,Nil] was the password correct?
-    #   nil is returned if there is no password set in the JSS.
+    # @param pw[String] ignored
     #
-    def check_pw(user, pw)
-      raise Jamf::InvalidDataError, 'The first parameter must be one of :ro, :rw, :ssh, :http' unless %i[ro rw ssh http].include? user
-
-      sha256 = case user
-               when :rw then @read_write_password_sha256
-               when :ro then @read_only_password_sha256
-               when :http then @http_password_sha256
-               when :ssh then @ssh_password_sha256
-               end # case
-
-      return nil if sha256 == EMPTY_PW_256
-
-      sha256 == Digest::SHA2.new(256).update(pw).to_s
+    # @return [TrueClass] Allow the process calling this to continue.
+    #
+    def check_pw(_user = nil, _pw = nil)
+      true
     end
 
     # Check to see if this dist point is reachable for downloads (read-only)
@@ -350,7 +334,6 @@ module Jamf
     def reachable_for_download?(pw = '', check_http = true)
       return :http if check_http && http_reachable?(pw)
       return :mountable if mounted?
-      return false unless check_pw :ro, pw
 
       begin
         mount pw, :ro
@@ -371,7 +354,6 @@ module Jamf
     #
     def reachable_for_upload?(pw)
       return :mountable if mounted?
-      return false unless check_pw :rw, pw
 
       begin
         mount pw, :rw
@@ -413,12 +395,6 @@ module Jamf
                    pw
                  end
 
-      pwok = check_pw(access, password)
-      unless pwok
-        msg = pwok.nil? ? "No #{access} password set in the JSS" : "Incorrect password for #{access} account"
-        raise Jamf::InvalidDataError, msg
-      end
-
       username = access == :ro ? @read_only_username : @read_write_username
 
       safe_pw = CGI.escape password.to_s
@@ -481,7 +457,7 @@ module Jamf
     private
 
     # can the dp be reached for http downloads?
-    def http_reachable?(pw)
+    def http_reachable?(pw = nil)
       return false unless http_downloads_enabled
 
       url =

data/lib/jamf/api/classic/api_objects/mdm.rb

@@ -476,7 +476,7 @@ module Jamf
             raise Jamf::UnmanagedError, "#{self} with id #{target_id} is not managed. Cannot send command." unless all_mgd.include? target_id
           end
         end # unles
-        
+
         targets
       end
 
@@ -860,7 +860,7 @@ module Jamf
         cnx = api if api
 
         unless WALLPAPER_LOCATIONS.keys.include? wallpaper_setting
-          raise ArgumentError, 
+          raise ArgumentError,
                 "wallpaper_setting must be one of: :#{WALLPAPER_LOCATIONS.keys.join ', :'}"
         end
 
@@ -999,7 +999,7 @@ module Jamf
       #
       # @param play_sound[Boolean] Play a sound when entering lost mode
       #
-      # @param enforce_lost_mode[Boolean] Re-enabled lost mode when re-enrolled after wipe.
+      # @param enforce_lost_mode[Boolean] Re-enable lost mode when re-enrolled after wipe. Default is false
       #
       # @param cnx [Jamf::Connection] the API thru which to send the command
       #
@@ -1011,7 +1011,7 @@ module Jamf
         phone: nil,
         footnote: nil,
         play_sound: false,
-        enforce_lost_mode: true,
+        enforce_lost_mode: false,
         api: nil,
         cnx: Jamf.cnx
       )
@@ -1081,7 +1081,7 @@ module Jamf
 
         status = FLUSHABLE_STATUSES[status]
 
-        # TODO: add 'unmanaged_ok:' param to raw_targets_to_ids method, so that we can 
+        # TODO: add 'unmanaged_ok:' param to raw_targets_to_ids method, so that we can
         # use this to flush commands for unmanaged machines.
         target_ids = raw_targets_to_ids targets, cnx: cnx, expand_groups: false, unmanaged_ok: true
 
@@ -1378,21 +1378,21 @@ module Jamf
     #
     # @param play_sound[Boolean] Play a sound when entering lost mode
     #
-    # @param enforce_lost_mode[Boolean] Re-enabled lost mode when re-enrolled after wipe.
+    # @param enforce_lost_mode[Boolean] Re-enable lost mode when re-enrolled after wipe. Default is false
     #
     # @return (see .send_mdm_command)
     #
     def enable_lost_mode(
       message: nil,
-      phone_number: nil,
+      phone: nil,
       footnote: nil,
-      enforce_lost_mode: true,
+      enforce_lost_mode: false,
       play_sound: false
     )
       self.class.enable_lost_mode(
         @id,
         message: message,
-        phone_number: phone_number,
+        phone: phone,
         footnote: footnote,
         play_sound: play_sound,
         enforce_lost_mode: enforce_lost_mode, cnx: @cnx

data/lib/jamf/api/classic/api_objects/mobile_device_application.rb

@@ -544,6 +544,7 @@ module Jamf
       doc = REXML::Document.new Jamf::Connection::XML_HEADER
       obj = doc.add_element self.class::RSRC_OBJECT_KEY.to_s
       gen = obj.add_element 'general'
+      gen.add_element('name').text = @display_name
       gen.add_element('display_name').text = @display_name
       gen.add_element('description').text = @description
       gen.add_element('os_type').text = @os_type

data/lib/jamf/api/classic/api_objects/policy.rb

@@ -166,7 +166,7 @@ module Jamf
       selected: 'Currently Selected Startup Disk (No Bless)',
       netboot: 'NetBoot',
       os_installer: 'inPlaceOSUpgradeDirectory'
-    }.freeze # Note: any other value in :specify_startup is a path to some other drive to boot from, e.g. /Volumes/Foo
+    }.freeze # NOTE: any other value in :specify_startup is a path to some other drive to boot from, e.g. /Volumes/Foo
 
     ACCOUNT_ACTIONS = {
       create: 'Create',
@@ -200,9 +200,9 @@ module Jamf
     }.freeze
 
     DISK_ENCRYPTION_ACTIONS = {
-      apply: "apply",
-      remediate: "remediate",
-      none: "none"
+      apply: 'apply',
+      remediate: 'remediate',
+      none: 'none'
     }
 
     PRINTER_ACTIONS = {
@@ -293,10 +293,19 @@ module Jamf
     # Class Methods
     ######################
 
-    # Flush logs for a given policy older than some number of days, weeks,
-    # months or years, possibly limited to one or more computers.
+    # Flush logs for a given policy older than a given time period.
+    # This flushes the logs of the given policy for all computers.
     #
-    # With no parameters, flushes all logs for the policy for all computers.
+    # IMPORTANT: from the Jamf Developer Site:
+    #   The ability to flush logs is currently only supported for flushing all logs
+    #   for a given policy or all logs for a given computer. There is no support for
+    #   flushing logs for a given policy and computer combination.
+    #
+    # (See .flush_logs_for_computers to to flush all logs for given computers)
+    #
+    # With no parameters, flushes all logs for the policy.
+    #
+    # Without older_than: and period:, will flush all logs for the policy
     #
     # NOTE: Currently the API doesn't have a way to flush only failed policies.
     #
@@ -306,52 +315,74 @@ module Jamf
     #
     # @param policy[Integer,String] The id or name of the policy to flush
     #
-    # @param older_than[Integer] 0, 1, 2, 3, or 6
+    # @param older_than[Integer] 0, 1, 2, 3, or 6, defaults to 0
     #
-    # @param period[Symbol] :days, :weeks, :months, or :years
-    #
-    # @param computers[Array<Integer,String>] Identifiers of the target computers
-    #   either ids, names, SNs, macaddrs, or UDIDs. If omitted, flushes logs for
-    #   all computers
+    # @param period[Symbol] :days, :weeks, :months, or :years, defaults to :days
     #
     # @param cnx [Jamf::Connection] the API  connection to use.
     #
     # @return [void]
     #
-    def self.flush_logs(policy, older_than: 0, period: :days, computers: [], api: nil, cnx: Jamf.cnx)
+    def self.flush_logs(policy, older_than: 0, period: :days, api: nil, cnx: Jamf.cnx)
       cnx = api if api
 
-      orig_timeout = cnx.timeout
       pol_id = valid_id policy, cnx: cnx
       raise Jamf::NoSuchItemError, "No Policy identified by '#{policy}'." unless pol_id
 
-      older_than = LOG_FLUSH_INTERVAL_INTEGERS[older_than]
-      raise Jamf::InvalidDataError, "older_than must be one of these integers: #{LOG_FLUSH_INTERVAL_INTEGERS.keys.join ', '}" unless older_than
-
-      period = LOG_FLUSH_INTERVAL_PERIODS[period]
-      raise Jamf::InvalidDataError, "period must be one of these symbols: :#{LOG_FLUSH_INTERVAL_PERIODS.keys.join ', :'}" unless period
-
-      computers = [computers] unless computers.is_a? Array
+      older_than, period = validate_log_flush_params(older_than, period)
 
       # log flushes can be really slow
+      orig_timeout = cnx.timeout
       cnx.timeout = 1800 unless orig_timeout && orig_timeout > 1800
 
-      return cnx.c_delete "#{LOG_FLUSH_RSRC}/policy/id/#{pol_id}/interval/#{older_than}+#{period}" if computers.empty?
-
-      flush_logs_for_specific_computers pol_id, older_than, period, computers, cnx
+      cnx.c_delete "#{LOG_FLUSH_RSRC}/policy/id/#{pol_id}/interval/#{older_than}+#{period}"
     ensure
       cnx.timeout = orig_timeout
     end
 
-    # use an XML body in a DELETE request to flush logs for
-    # a list of computers - used by the flush_logs class method
-    def self.flush_logs_for_specific_computers(pol_id, older_than, period, computers, cnx)
+    # Flush policy logs for specific computers older than  a given time period.
+    # This flushes the logs for all policies for these computers.
+    #
+    # IMPORTANT: from the Jamf Developer Site:
+    #   The ability to flush logs is currently only supported for flushing all logs
+    #   for a given policy or all logs for a given computer. There is no support for
+    #   flushing logs for a given policy and computer combination.
+    #
+    # (See .flush_logs to to flush all logs for a given policy)
+    #
+    # Without older_than: and period:, will flush all logs for the computers
+    #
+    # NOTE: Currently the API doesn't have a way to flush only failed policies.
+    #
+    # WARNING: Log flushing can take a long time, and the API call doesnt return
+    # until its finished. The connection timeout will be temporarily raised to
+    # 30 minutes, unless it's already higher.
+    #
+    # @param computers[Array<Integer,String>] Identifiers of the target computers
+    #   either ids, names, SNs, macaddrs, or UDIDs.
+    #
+    # @param older_than[Integer] 0, 1, 2, 3, or 6, defaults to 0
+    #
+    # @param period[Symbol] :days, :weeks, :months, or :years, defaults to :days
+    #
+    # @param cnx [Jamf::Connection] the API  connection to use.
+    #
+    # @return [void]
+    #
+    def self.flush_logs_for_computers(computers = [], older_than: 0, period: :days, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
+      computers = [computers] unless computers.is_a? Array
+      raise JSS::InvalidDataError, 'One or more computers must be specified' if computers.empty?
+
+      older_than, period = validate_log_flush_params(older_than, period)
+
       # build the xml body for a DELETE request
       xml_doc = REXML::Document.new Jamf::Connection::XML_HEADER
       lf = xml_doc.add_element 'logflush'
       lf.add_element('log').text = 'policy'
-      lf.add_element('log_id').text = pol_id.to_s
       lf.add_element('interval').text = "#{older_than} #{period}"
+
       comps_elem = lf.add_element 'computers'
       computers.each do |c|
         id = Jamf::Computer.valid_id c, cnx: cnx
@@ -361,13 +392,41 @@ module Jamf
         ce.add_element('id').text = id.to_s
       end
 
+      # for debugging the xml...
+      #
+      # formatter = REXML::Formatters::Pretty.new(2)
+      # formatter.compact = true
+      # formatter.write(xml_doc, $stdout)
+      # puts
+      # return
+
+      # log flushes can be really slow
+      orig_timeout = cnx.timeout
+      cnx.timeout = 1800 unless orig_timeout && orig_timeout > 1800
+
       # Do a DELETE request with a body.
-      cnx.delete(LOG_FLUSH_RSRC) do |req|
+      resp = cnx.c_cnx.delete(LOG_FLUSH_RSRC) do |req|
         req.headers[Jamf::Connection::HTTP_CONTENT_TYPE_HEADER] = Jamf::Connection::MIME_XML
         req.body = xml_doc.to_s
       end
+
+      resp.body
+    ensure
+      cnx.timeout = orig_timeout
     end
-    private_class_method :flush_logs_for_specific_computers
+
+    # validate the logflush params
+    # @return [Array<String>]
+    def self.validate_log_flush_params(older_than, period)
+      older_than = LOG_FLUSH_INTERVAL_INTEGERS[older_than]
+      raise Jamf::InvalidDataError, "older_than must be one of these integers: #{LOG_FLUSH_INTERVAL_INTEGERS.keys.join ', '}" unless older_than
+
+      period = LOG_FLUSH_INTERVAL_PERIODS[period]
+      raise Jamf::InvalidDataError, "period must be one of these symbols: :#{LOG_FLUSH_INTERVAL_PERIODS.keys.join ', :'}" unless period
+
+      [older_than, period]
+    end
+    private_class_method :validate_log_flush_params
 
     # Attributes
     ######################
@@ -751,7 +810,7 @@ module Jamf
         @management_account = amaint[:management_account]
         @accounts = amaint[:accounts]
 
-        @packages = @init_data[:package_configuration][:packages] ? @init_data[:package_configuration][:packages] : []
+        @packages = @init_data[:package_configuration][:packages] || []
 
         @scripts = @init_data[:scripts]
 
@@ -815,6 +874,7 @@ module Jamf
     #
     def enabled=(new_val)
       return if @enabled == new_val
+
       @enabled = Jamf::Validate.boolean new_val
       @need_to_update = true
     end
@@ -868,9 +928,7 @@ module Jamf
 
       # if the event is not 'none' and attempts is <= 0,
       # set events to 1, or the API won't accept it
-      unless evt == RETRY_EVENTS[:none]
-        @retry_attempts = 1 unless @retry_attempts.positive?
-      end
+      @retry_attempts = 1 if !(evt == RETRY_EVENTS[:none]) && !@retry_attempts.positive?
 
       @retry_event = evt
       @need_to_update = true
@@ -934,6 +992,7 @@ module Jamf
     #
     def target_drive=(path_to_drive)
       raise Jamf::InvalidDataError, 'Path to target drive must be absolute' unless path_to_drive.to_s.start_with? '/'
+
       @target_drive = path_to_drive.to_s
       @need_to_update = true
     end
@@ -946,6 +1005,7 @@ module Jamf
     #
     def offline=(new_val)
       raise Jamf::InvalidDataError, 'New value must be boolean true or false' unless Jamf::TRUE_FALSE.include? new_val
+
       @offline = new_val
       @need_to_update = true
     end
@@ -960,6 +1020,7 @@ module Jamf
     #
     def set_trigger_event(type, new_val)
       raise Jamf::InvalidDataError, "Trigger type must be one of #{TRIGGER_EVENTS.keys.join(', ')}" unless TRIGGER_EVENTS.key?(type)
+
       if type == :custom
         raise Jamf::InvalidDataError, 'Custom triggers must be Strings' unless new_val.is_a? String
       else
@@ -977,6 +1038,7 @@ module Jamf
     #
     def server_side_activation=(activation)
       raise Jamf::InvalidDataError, 'Activation must be a Time' unless activation.is_a? Time
+
       @server_side_limitations[:activation] = activation
       @need_to_update = true
     end
@@ -989,6 +1051,7 @@ module Jamf
     #
     def server_side_expiration=(expiration)
       raise Jamf::InvalidDataError, 'Expiration must be a Time' unless expiration.is_a? Time
+
       @server_side_limitations[:expiration] = expiration
       @need_to_update = true
     end
@@ -999,6 +1062,7 @@ module Jamf
     #
     def verify_startup_disk=(bool)
       return if @verify_startup_disk == bool
+
       @verify_startup_disk = Jamf::Validate.boolean bool
       @need_to_update = true
     end
@@ -1007,6 +1071,7 @@ module Jamf
     #
     def permissions_repair=(bool)
       return if @permissions_repair == bool
+
       @permissions_repair = Jamf::Validate.boolean bool
       @need_to_update = true
     end
@@ -1015,6 +1080,7 @@ module Jamf
     #
     def recon=(bool)
       return if @recon == bool
+
       @recon = Jamf::Validate.boolean bool
       @need_to_update = true
     end
@@ -1024,6 +1090,7 @@ module Jamf
     #
     def fix_byhost=(bool)
       return if @fix_byhost == bool
+
       @fix_byhost = Jamf::Validate.boolean bool
       @need_to_update = true
     end
@@ -1032,6 +1099,7 @@ module Jamf
     #
     def reset_name=(bool)
       return if @reset_name == bool
+
       @reset_name = Jamf::Validate.boolean bool
       @need_to_update = true
     end
@@ -1040,6 +1108,7 @@ module Jamf
     #
     def flush_system_cache=(bool)
       return if @flush_system_cache == bool
+
       @flush_system_cache = Jamf::Validate.boolean bool
       @need_to_update = true
     end # see attr_reader :recon
@@ -1048,6 +1117,7 @@ module Jamf
     #
     def install_cached_pkgs=(bool)
       return if @install_cached_pkgs == bool
+
       @install_cached_pkgs = Jamf::Validate.boolean bool
       @need_to_update = true
     end
@@ -1056,6 +1126,7 @@ module Jamf
     #
     def flush_user_cache=(bool)
       return if @flush_user_cache == bool
+
       @flush_user_cache = Jamf::Validate.boolean bool
       @need_to_update = true
     end
@@ -1071,6 +1142,7 @@ module Jamf
     #
     def no_user_logged_in=(no_user_option)
       raise Jamf::InvalidDataError, "no_user_logged_in options: #{NO_USER_LOGGED_IN.join(', ')}" unless NO_USER_LOGGED_IN.include? no_user_option
+
       @reboot_options[:no_user_logged_in] = no_user_option
       @need_to_update = true
     end
@@ -1083,6 +1155,7 @@ module Jamf
     #
     def user_logged_in=(logged_in_option)
       raise Jamf::InvalidDataError, "user_logged_in options: #{USER_LOGGED_IN.join(', ')}" unless USER_LOGGED_IN.include? logged_in_option
+
       @reboot_options[:user_logged_in] = logged_in_option
       @need_to_update = true
     end
@@ -1095,6 +1168,7 @@ module Jamf
     #
     def reboot_message=(message)
       raise Jamf::InvalidDataError, 'Reboot message must be a String' unless message.is_a? String
+
       @reboot_options[:message] = message
       @need_to_update = true
     end
@@ -1107,6 +1181,7 @@ module Jamf
     # @return [void] description of returned object
     def user_message_start=(message)
       raise Jamf::InvalidDataError, 'User message must be a String' unless message.is_a? String
+
       @user_message_start = message
       @need_to_update = true
     end
@@ -1118,6 +1193,7 @@ module Jamf
     # @return [void] description of returned object
     def user_message_end=(message)
       raise Jamf::InvalidDataError, 'User message must be a String' unless message.is_a? String
+
       @user_message_finish = message
       @need_to_update = true
     end
@@ -1133,6 +1209,7 @@ module Jamf
     #
     def startup_disk=(startup_disk_option)
       raise Jamf::InvalidDataError, "#{startup_disk_option} is not a valid Startup Disk" unless startup_disk_option.is_a? String
+
       @reboot_options[:startup_disk] = 'Specify Local Startup Disk'
       self.specify_startup = startup_disk_option
       @need_to_update = true
@@ -1147,6 +1224,7 @@ module Jamf
     #
     def specify_startup=(startup_volume)
       raise Jamf::InvalidDataError, "#{startup_volume} is not a valid Startup Disk" unless startup_volume.is_a? String
+
       @reboot_options[:specify_startup] = startup_volume
       @need_to_update = true
     end
@@ -1172,6 +1250,7 @@ module Jamf
     #
     def minutes_until_reboot=(minutes)
       raise Jamf::InvalidDataError, 'Minutes until reboot must be an Integer' unless minutes.is_a? Integer
+
       @reboot_options[:minutes_until_reboot] = minutes
       @need_to_update = true
     end
@@ -1185,6 +1264,7 @@ module Jamf
     #
     def file_vault_2_reboot=(fv_bool)
       raise Jamf::InvalidDataError, 'FileVault 2 Reboot must be a Boolean' unless fv_bool.jss_boolean?
+
       @reboot_options[:file_vault_2_reboot] = fv_bool
       @need_to_update = true
     end
@@ -1206,6 +1286,7 @@ module Jamf
     #
     def run_command=(command)
       raise Jamf::InvalidDataError, 'Command to run must be a String' unless command.is_a? String
+
       @files_processes[:run_command] = command
       @need_to_update = true
     end
@@ -1262,7 +1343,7 @@ module Jamf
     #
     def search_by_path
       if @files_processes[:search_by_path].nil?
-        return nil
+        nil
       else
         Pathname.new @files_processes[:search_by_path]
       end
@@ -1289,6 +1370,7 @@ module Jamf
     #
     def set_search_by_path(path, delete = false)
       raise Jamf::InvalidDataError, 'Path to search for must be a String or a Pathname' unless path.is_a?(String) || path.is_a?(Pathname)
+
       @files_processes[:search_by_path] = path.to_s
       @files_processes[:delete_file] = delete ? true : false
       @need_to_update = true
@@ -1308,6 +1390,7 @@ module Jamf
     #
     def spotlight_search=(term)
       raise Jamf::InvalidDataError, 'Spotlight search term must be a String' unless term.is_a? String
+
       @files_processes[:spotlight_search] = term
       @need_to_update = true
     end
@@ -1326,6 +1409,7 @@ module Jamf
     #
     def locate_file=(term)
       raise Jamf::InvalidDataError, 'Term to locate must be a String' unless term.is_a? String
+
       @files_processes[:locate_file] = term
       @need_to_update = true
     end
@@ -1571,7 +1655,6 @@ module Jamf
       @directory_bindings
     end
 
-
     # Remove a directory binding from this policy by name or id
     #
     # @param identifier [String,Integer] the name or id of the directory binding to remove
@@ -1596,7 +1679,6 @@ module Jamf
       @dock_items.map { |p| p[:name] }
     end
 
-
     ###### Printers
 
     # Add a specific printer object to the policy.
@@ -1661,7 +1743,7 @@ module Jamf
 
       name = Jamf::DockItem.map_all_ids_to(:name, cnx: @cnx)[id]
 
-      @dock_items << {id: id, name: name, action: DOCK_ITEM_ACTIONS[action]}
+      @dock_items << { id: id, name: name, action: DOCK_ITEM_ACTIONS[action] }
 
       @need_to_update = true
       @dock_items
@@ -1677,24 +1759,18 @@ module Jamf
 
     # @return [Array] the id's of the printers handled by the policy
     def printer_ids
-        begin
-            @printers.map { |p| p[:id] }
-            rescue TypeError
-            return []
-        end
+      @printers.map { |p| p[:id] }
+    rescue TypeError
+      []
     end
 
     # @return [Array] the names of the printers handled by the policy
     def printer_names
-        begin
-            @printers.map { |p| p[:name] }
-            rescue TypeError
-            return []
-        end
+      @printers.map { |p| p[:name] }
+    rescue TypeError
+      []
     end
 
-
-
     ###### Disk Encryption
 
     # Sets the Disk Encryption application to "Remediate" and sets the remediation key type to individual.
@@ -1703,12 +1779,12 @@ module Jamf
     #
     # @return [Void]
     #
-    def reissue_key()
+    def reissue_key
       if @disk_encryption[:action] != DISK_ENCRYPTION_ACTIONS[:remediate]
         # Setting New Action
         hash = {
           action: DISK_ENCRYPTION_ACTIONS[:remediate],
-          remediate_key_type: "Individual"
+          remediate_key_type: 'Individual'
         }
 
         @disk_encryption = hash
@@ -1716,12 +1792,10 @@ module Jamf
 
       else
         # Update
-        return
+        nil
       end
-
     end
 
-
     # Sets the Disk Encryption application to "Apply" and sets the correct disk encryption configuration ID using either the name or id.
     #
     # @author Tyler Morgan
@@ -1729,7 +1803,6 @@ module Jamf
     # @return [Void]
     #
     def apply_encryption_configuration(identifier)
-
       id = Jamf::DiskEncryptionConfiguration.valid_id identifier
 
       return if id.nil?
@@ -1744,14 +1817,13 @@ module Jamf
       @need_to_update = true
     end
 
-
     # Removes the Disk Encryption settings associated with this specific policy.
     #
     # @author Tyler Morgan
     #
     # @return [Void]
     #
-    def remove_encryption_configuration()
+    def remove_encryption_configuration
       hash = {
         action: DISK_ENCRYPTION_ACTIONS[:none]
       }
@@ -1774,16 +1846,16 @@ module Jamf
 
       management_data = {}
 
-      if action == :change_pw || action == :reset_pw
-        raise Jamf::MissingDataError, ":password must be provided when changing management account password" if opts[:password].nil?
+      if %i[change_pw reset_pw].include?(action)
+        raise Jamf::MissingDataError, ':password must be provided when changing management account password' if opts[:password].nil?
 
         management_data = {
           action: MGMT_ACCOUNT_ACTIONS[action],
           managed_password: opts[:password]
         }
-      elsif action == :reset_random || action == :generate_pw
-        raise Jamf::MissingDataError, ":password_length must be provided when setting a random password" if opts[:password_length].nil?
-        raise Jamf::InvalidDataError, ":password_length must be an Integer" unless opts[:password_length].is_a? Integer
+      elsif %i[reset_random generate_pw].include?(action)
+        raise Jamf::MissingDataError, ':password_length must be provided when setting a random password' if opts[:password_length].nil?
+        raise Jamf::InvalidDataError, ':password_length must be an Integer' unless opts[:password_length].is_a? Integer
 
         management_data = {
           action: MGMT_ACCOUNT_ACTIONS[action],
@@ -1800,21 +1872,23 @@ module Jamf
       @need_to_update = true
 
       @management_account
-
     end
 
-    # Check if management password matches provided password
+    # @deprecated The API no longer sends SHA256 hashed password data, and instead
+    #   only has a string of asterisks, meaning we can no longer use it to validate
+    #   passwords before attempting to use them. Instead, the processes that use
+    #   the password will fail on their own if the pw is not valid.
     #
-    # @param password[String] the password that is SHA256'ed to compare to the one from the API.
+    #   This method remains defined for backward-compatibility with any existing
+    #   code that calls it. but it will always return true. Itwill be removed in
+    #   a future version
     #
-    # @return [Boolean] The result of the comparison of the management password and provided text.
+    # @param password[String] ignored
     #
-    def verify_management_password(password)
-      raise Jamf::InvalidDataError, "Management password must be a string." unless password.is_a? String
-
-      raise Jamf::UnsupportedError, "'#{@management_account[:action].to_s}' does not support management passwords." unless @management_account[:action] == MGMT_ACCOUNT_ACTIONS[:change_pw] || @management_account[:action] == MGMT_ACCOUNT_ACTIONS[:reset_pw]
-
-      return Digest::SHA256.hexdigest(password).to_s == @management_account[:managed_password_sha256].to_s
+    # @return [TrueClass] Allow the process calling this to continue.
+    #
+    def verify_management_password(_password = nil)
+      true
     end
 
     ###### Actions
@@ -1829,17 +1903,22 @@ module Jamf
     #
     def run(show_output = false)
       return nil unless enabled?
+
       output = Jamf::Client.run_jamf('policy', "-id #{id}", show_output)
       return nil if output.include? 'No policies were found for the ID'
+
       $CHILD_STATUS.exitstatus.zero? ? true : false
     end
     alias execute run
 
-    # Flush logs for this policy older than
-    # some number of days, weeks, months or years, possibly limited to
-    # one or more computers
+    # Flush logs for this policy older than a given time period.
+    #
+    # IMPORTANT: from the Jamf Developer Site:
+    #   The ability to flush logs is currently only supported for flushing all logs
+    #   for a given policy or all logs for a given computer. There is no support for
+    #   flushing logs for a given policy and computer combination.
     #
-    # With no parameters, flushes all logs for all computers
+    # With no parameters, will flush all logs for the policy
     #
     # NOTE: Currently the API doesn't have a way to flush only failed policies.
     #
@@ -1851,19 +1930,16 @@ module Jamf
     #
     # @param period[Symbol] :days, :weeks, :months, or :years
     #
-    # @param computers[Array<Integer,String>] Identifiers of the target computers
-    #   either ids, names, SNs, macaddrs, or UDIDs
-    #
     # @return [void]
     #
-    def flush_logs(older_than: 0, period: :days, computers: [])
-      raise Jamf::NoSuchItemError, "Policy doesn't exist in the JSS. Use #create first." unless @in_jss
+    def flush_logs(older_than: 0, period: :days)
+      raise Jamf::NoSuchItemError, "Policy doesn't exist in the JSS. Use #save first." unless @in_jss
 
       Jamf::Policy.flush_logs(
         @id,
         older_than: older_than,
         period: period,
-        computers: computers, cnx: @cnx
+        cnx: @cnx
       )
     end
 
@@ -1944,6 +2020,7 @@ module Jamf
 
       id = Jamf::Script.valid_id identifier, cnx: @cnx
       raise Jamf::NoSuchItemError, "No script matches '#{identifier}'" unless id
+
       id
     end
 
@@ -1963,12 +2040,13 @@ module Jamf
         else Jamf::Validate.integer(opts[:position])
         end
 
-        # if the given position is past the end, set it to -1 (the end)
-        opts[:position] = -1 if opts[:position] > @directory_bindings.size
+      # if the given position is past the end, set it to -1 (the end)
+      opts[:position] = -1 if opts[:position] > @directory_bindings.size
+
+      id = Jamf::DirectoryBinding.valid_id identifier, cnx: @cnx
+      raise Jamf::NoSuchItemError, "No directory binding matches '#{identifier}'" unless id
 
-        id = Jamf::DirectoryBinding.valid_id identifier, cnx: @cnx
-        raise Jamf::NoSuchItemError, "No directory binding matches '#{identifier}'" unless id
-        id
+      id
     end
 
     # Raises an error if the printer being added isn't valid, additionally checks the options and sets defaults where possible.
@@ -1994,14 +2072,17 @@ module Jamf
       raise Jamf::MissingDataError, "action must be provided, must be one of :#{PRINTER_ACTIONS.keys.join(':,')}." if opts[:action].nil?
       raise Jamf::InvalidDataError, "action must be one of :#{PRINTER_ACTIONS.keys.join(',:')}." unless PRINTER_ACTIONS.keys.include? opts[:action]
 
-
       # Checks if the make_default option is valid, and sets the default if needed.
-      raise Jamf::InvalidDataError, "make_default must be either true or false." unless opts[:make_default].is_a?(TrueClass) || opts[:make_default].is_a?(FalseClass) || opts[:make_default].nil?
+      unless opts[:make_default].is_a?(TrueClass) || opts[:make_default].is_a?(FalseClass) || opts[:make_default].nil?
+        raise Jamf::InvalidDataError,
+              'make_default must be either true or false.'
+      end
 
       opts[:make_default] = false if opts[:make_default].nil?
 
       id = Jamf::Printer.valid_id identifier, cnx: @cnx
       raise Jamf::NoSuchItemError, "No printer matches '#{identifier}'" unless id
+
       id
     end
 
@@ -2081,7 +2162,7 @@ module Jamf
 
       disk_encryption = obj.add_element 'disk_encryption'
 
-      @disk_encryption.each do |k,v|
+      @disk_encryption.each do |k, v|
         disk_encryption.add_element(k.to_s).text = v.to_s
       end
 

data/lib/jamf/api/classic/api_objects/scopable/scope.rb

@@ -476,7 +476,10 @@ module Jamf
         item_id = validate_item(:target, key, item)
         return if @targets[key]&.include?(item_id)
 
-        raise Jamf::AlreadyExistsError, "Can't set #{key} target to '#{item}' because it's already an explicit exclusion." if @exclusions[key]&.include?(item_id)
+        if @exclusions[key]&.include?(item_id)
+          raise Jamf::AlreadyExistsError,
+                "Can't set #{key} target to '#{item}' because it's already an explicit exclusion."
+        end
 
         @targets[key] << item_id
         @all_targets = false
@@ -775,7 +778,7 @@ module Jamf
       ################
       def scoped_machines
         scoped_machines = {}
-        @target_class.all_objects(cnx: container.cnx).each do |machine|
+        @target_class.all_objects(:refresh, cnx: container.cnx).each do |machine|
           scoped_machines[machine.id] = machine.name if in_scope? machine
         end
         scoped_machines

data/lib/jamf/api/jamf_pro/mixins/macos_managed_updates.rb

@@ -19,14 +19,14 @@
 #    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.
-#
-#
+
+# frozen_string_literal: true
 
 module Jamf
 
   # This module should be mixed in to Jamf::Computer and Jamf::ComputerGroup
   #
-  # It provides access to the macos-managed-software-updates JPAPI resource for 
+  # It provides access to the macos-managed-software-updates JPAPI resource for
   # managed OS update commands to managed macs running Big Sur or higher.
   #
   module MacOSManagedUpdates
@@ -37,7 +37,7 @@ module Jamf
       includer.extend(ClassMethods)
     end
 
-    # These resources in the Jamf Pro API can be used to send Managed macOS 
+    # These resources in the Jamf Pro API can be used to send Managed macOS
     # updates to clients running Big Sur or higher
     MANAGED_SW_UPDATES_RSRC = 'v1/macos-managed-software-updates'
 
@@ -45,7 +45,7 @@ module Jamf
     MANAGED_SW_UPDATES_AVAILABLE_VERSIONS_RSRC = "#{MANAGED_SW_UPDATES_RSRC}/available-updates"
 
     # POSTing JSON data to this resource will send the MDM commands to install os updates
-    # For details about the data to send, see 
+    # For details about the data to send, see
     # https://developer.jamf.com/jamf-pro/reference/post_v1-macos-managed-software-updates-send-updates
     MANAGED_SW_UPDATES_SEND_UPDATES_RSRC = "#{MANAGED_SW_UPDATES_RSRC}/send-updates"
 
@@ -53,6 +53,12 @@ module Jamf
     DOWNLOAD_AND_INSTALL = 'DOWNLOAD_AND_INSTALL'
     DOWNLOAD_ONLY = 'DOWNLOAD_ONLY'
 
+    # for easier use of these values as the updateAction
+    UPDATE_ACTIONS = {
+      install: DOWNLOAD_AND_INSTALL,
+      download: DOWNLOAD_ONLY
+    }
+
     # Class Methods
     #####################################
     module ClassMethods
@@ -73,48 +79,52 @@ module Jamf
 
       # Send the os update command to target Computers or a ComputerGroup
       #
-      # @param updateAction [String] Required. 'DOWNLOAD_AND_INSTALL' or 'DOWNLOAD_ONLY'
+      # @param updateAction [Symbol] Required. Use :install to send the
+      #   DOWNLOAD_AND_INSTALL action, or :download to send  DOWNLOAD_ONLY
       #
-      # @param deviceIds [String, Integer, Array<String, Integer>] Identifiers for the 
+      # @param deviceIds [String, Integer, Array<String, Integer>] Identifiers for the
       #   computer targets. Required if no groupId is given.
       #
       # @param groupId [String, Integer] Identifier for the computer group target.
-      #   Requied if no deviceIDs are given.
+      #   Requied if no deviceIds are given.
       #
-      # @param maxDeferrals [Integer] Allow users to defer the update the provided number 
-      #   of times before macOS forces the update. If a value is provided, the Software 
-      #   Update will use the InstallLater install action. MaxDeferral is ignored if using the 
-      #   DOWNLOAD_ONLY updateAction.
+      # @param maxDeferrals [Integer] Allow users to defer the update the provided number
+      #   of times before macOS forces the update. If a value is provided, the Software
+      #   Update will use the InstallLater install action. MaxDeferral is ignored if using the
+      #   :download updateAction.
       #
-      # @param version [String] The OS version to install. If no value is provided, the 
+      # @param version [String] The OS version to install. If no value is provided, the
       #   version will default to latest version based on device eligibility.
       #
       # @param skipVersionVerification [Boolean] Should the specified version be installed
       #   even it it isn't applicable to this machine? If no value is provided, will default to false.
-      #   If true, the specified version will be forced to complete DownloadAndInstall
-      #   install action.
+      #   If true, the specified version will be forced to complete the :install updateAction.
       #
       # @param applyMajorUpdate [Boolean] Available only when updating to the latest version
       #   based on device eligibility. Defaults to false. If false the calculated latest version
       #   will only include minor version updates. If a value is provided, the calculated latest
       #   version will include minor and major version updates.
       #
-      # @param forceRestart [Boolean]  Will default to false. Can only be true if updateAction 
-      #   is DOWNLOAD_AND_INSTALLn and the devices the command is sent to are on macOs 11 or higher. 
-      #   If true, the DownloadAndInstall action is performed, a restart will be forced. 
-      #   MaxDeferral will be ignored if true. 
+      # @param forceRestart [Boolean]  Will default to false. Can only be true if updateAction
+      #   is :install and the target devices are on macOs 11 or higher.
+      #   If true, the DownloadAndInstall action is performed, a restart will be forced.
+      #   MaxDeferral will be ignored if true.
       #
-      # @param cnx [Jamf::Connection] The API connection to use. Defaults to Jamf.cnx 
+      # @param cnx [Jamf::Connection] The API connection to use. Defaults to Jamf.cnx
       #
-      # @return [Jamf::OAPISchemas::MacOsManagedSoftwareUpdateResponse] 
+      # @return [Jamf::OAPISchemas::MacOsManagedSoftwareUpdateResponse]
       ########################
       def send_managed_os_update(updateAction:, deviceIds: nil, groupId: nil, maxDeferrals: nil, version: nil, skipVersionVerification: false, applyMajorUpdate: false, forceRestart: false, cnx: Jamf.cnx)
-        if self == Jamf::Computer 
+        action_to_send = UPDATE_ACTIONS.value?(updateAction) ? updateAction : UPDATE_ACTIONS[updateAction]
+
+        raise ArgumentError, "Unknown updateAction, must be one of: #{UPDATE_ACTIONS.keys.join ', '}" unless action_to_send
+
+        if self == Jamf::Computer
           raise ArgumentError, 'Must provide one or more deviceIds' unless deviceIds
         elsif self == Jamf::ComputerGroup
           raise ArgumentError, 'Must provide a groupId' unless groupId
         else
-          raise Jamf::UnsupportedError, 'This method is only available for Jamf::Computer and Jamf::ComputerGroup' 
+          raise Jamf::UnsupportedError, 'This method is only available for Jamf::Computer and Jamf::ComputerGroup'
         end
 
         if version
@@ -124,9 +134,9 @@ module Jamf
 
         if deviceIds
           deviceIds = [deviceIds] unless deviceIds.is_a?(Array)
-          deviceIds.map! { |id| valid_id id }
+          deviceIds.map! { |id| valid_id id, cnx: cnx }
         end
-        groupId = valid_id groupId if groupId
+        groupId = valid_id(groupId, cnx: cnx) if groupId
 
         data = {}
         # ids in the JPAPI are string containing integers
@@ -137,11 +147,11 @@ module Jamf
         data[:version] = version if version
         data[:skipVersionVerification] = skipVersionVerification if skipVersionVerification
         data[:applyMajorUpdate] = applyMajorUpdate if applyMajorUpdate
-        data[:updateAction] = updateAction if updateAction
-        data[:forceRestart] = forceRestart if forceRestart  
-        
+        data[:updateAction] = action_to_send
+        data[:forceRestart] = forceRestart if forceRestart
+
         payload = Jamf::OAPISchemas::MacOsManagedSoftwareUpdate.new(data).to_json
-        
+
         result = cnx.jp_post MANAGED_SW_UPDATES_SEND_UPDATES_RSRC, payload
         Jamf::OAPISchemas::MacOsManagedSoftwareUpdateResponse.new result
       end
@@ -161,14 +171,14 @@ module Jamf
       groupId = is_a?(Jamf::Computer) ? nil : @id
 
       self.class.send_managed_os_update(
-        deviceIds: deviceIds, 
-        groupId: groupId, 
-        maxDeferrals: maxDeferrals, 
-        version: version, 
-        skipVersionVerification: skipVersionVerification, 
-        applyMajorUpdate: applyMajorUpdate, 
-        forceRestart: forceRestart, 
-        updateAction: updateAction, 
+        deviceIds: deviceIds,
+        groupId: groupId,
+        maxDeferrals: maxDeferrals,
+        version: version,
+        skipVersionVerification: skipVersionVerification,
+        applyMajorUpdate: applyMajorUpdate,
+        forceRestart: forceRestart,
+        updateAction: updateAction,
         cnx: @cnx
       )
     end

data/lib/jamf/validate.rb

@@ -98,7 +98,9 @@ module Jamf
     #
     # @return [Object] the validated unique value
     #
-    def self.doesnt_already_exist(klass, identifier, val, msg: nil, api: Jamf.cnx)
+    def self.doesnt_already_exist(klass, identifier, val, msg: nil, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
       return val unless klass.all(:refresh, cnx: cnx).map { |i| i[identifier] }.include? val
 
       key = klass.real_lookup_key identifier

data/lib/jamf/version.rb

@@ -27,6 +27,6 @@
 module Jamf
 
   ### The version of ruby-jss
-  VERSION = '2.1.0'.freeze
+  VERSION = '3.0.0b1'.freeze
 
 end # module

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-jss
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.0.0b1
 platform: ruby
 authors:
 - Chris Lasell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-10-11 00:00:00.000000000 Z
+date: 2023-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: CFPropertyList
@@ -824,9 +824,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.6.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.0.3.1
 signing_key: