ruby-jss 1.2.3 → 1.2.4a1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db7db3a85a2ce09946ec84f4b254f948f566daa8f5e0e9b8f939c9efb8eefef1
-  data.tar.gz: 1edb35f947212312c165f2ff0fa1ed3c4a059fb58f0abb5de9bea8877bfab3a0
+  metadata.gz: 25d16b4c34d2790bdf6175543f81a2125e80ddf0c2c49cbb76d340b76dd562df
+  data.tar.gz: a09cfceaaecd6c3109cafbd0d7912a1c66326c6c5ddaae479a4260816c50ede9
 SHA512:
-  metadata.gz: d8d61d9f03d99a289f0b5c4dd0fefe246f824fac21003e905bbc5dd25c6e2ff84bffbc6eb3244086db8af143ca39722e738711c82cf5f8b9174c6183d8c40d03
-  data.tar.gz: db954707cef1f340613ecb27657d38673e6117ac4b9db05ba3025bab6ba4446e220808346856e4c50003eca58fc84dfb8c6e640d2a41e3a32987e9dc5766a99a
+  metadata.gz: fb2e1e6fb575db16ade4b819bbea3cfb73ce6956c1012569f2be10d757ed05f31c4671605065a6c619667afa3a2540119af0afee5cf506d1ae8455d4aa42d4c0
+  data.tar.gz: 4af7406b1457c0c70d4873578920938b942ed7b6ea15702898f74450453720f30b24803addf8762426f617b7e223ef34ae2d51453df5cf283da35c32d27a8854

data/lib/jamf.rb

@@ -0,0 +1,169 @@
+# Copyright 2019 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.
+#
+#
+
+#
+# JAMF, A Ruby module for interacting with a JAMF Pro Server via the JAMF API
+#
+
+### Standard Libraries
+require 'English'
+require 'json'
+require 'yaml'
+require 'pathname'
+require 'time'
+require 'singleton'
+require 'open-uri'
+require 'ipaddr'
+require 'base64'
+require 'shellwords'
+require 'digest'
+require 'open3'
+
+
+### Gems
+require 'rest-client'
+require 'plist'
+
+# Used, among other places, in the Connection::APIError class
+require 'immutable-struct'
+
+# TODO: needed?
+# require 'recursive-open-struct'
+
+# non-api parts of Jamf module
+require 'jamf/configuration'
+require 'jamf/exceptions'
+require 'jamf/utility'
+require 'jamf/validate'
+require 'jamf/version'
+
+# backports and extensions to existing Ruby classes
+require 'jamf/compatibility'
+require 'jamf/ruby_extensions'
+
+# API connection
+require 'jamf/api/connection'
+
+
+# The main module.
+# See README.md
+#
+module Jamf
+
+  # The minimum Ruby version that works with this gem
+  # 2.3 allows us to start using some nice features like the safe-navigation
+  # operator and Array#dig & Hash#dig, and such.
+  #
+  # For a list of features, see https://github.com/ruby/ruby/blob/v2_3_0/NEWS
+  # and http://nithinbekal.com/posts/ruby-2-3-features/
+  #
+  MINIMUM_RUBY_VERSION = '2.3'.freeze
+
+  if Gem::Version.new(RUBY_VERSION) < Gem::Version.new(MINIMUM_RUBY_VERSION)
+    raise "Can't use the JAMF module, ruby itself must be version #{MINIMUM_RUBY_VERSION} or greater."
+  end
+
+  # AUTOLOADING
+  ##################################
+
+  # Top-level API Abstract Classes
+  autoload :JSONObject, 'jamf/api/abstract_classes/json_object'
+  autoload :Resource, 'jamf/api/abstract_classes/resource'
+  autoload :SingletonResource, 'jamf/api/abstract_classes/singleton_resource'
+  autoload :CollectionResource, 'jamf/api/abstract_classes/collection_resource'
+
+  # Abstract Classes used for JSONObject subclasses
+  autoload :Prestage, 'jamf/api/abstract_classes/prestage'
+  autoload :PrestageSkipSetupItems, 'jamf/api/abstract_classes/prestage_skip_setup_items'
+
+  # Abstract Classes not used for JSONObject subclasses
+  autoload :GenericReference, 'jamf/api/abstract_classes/generic_reference'
+
+  # MixIn Modules
+  autoload :ChangeLog, 'jamf/api/mixins/change_log'
+  autoload :Extendable, 'jamf/api/mixins/extendable'
+  autoload :Locatable, 'jamf/api/mixins/locatable'
+  autoload :Referable, 'jamf/api/mixins/referable'
+  autoload :Searchable, 'jamf/api/mixins/searchable'
+  autoload :Lockable, 'jamf/api/mixins/lockable'
+  autoload :UnCreatable, 'jamf/api/mixins/uncreatable'
+  autoload :Immutable, 'jamf/api/mixins/immutable'
+  autoload :UnDeletable, 'jamf/api/mixins/undeletable'
+  autoload :Abstract, 'jamf/api/mixins/abstract'
+
+  # Utility modules
+  autoload :Validate, 'jamf/validate'
+
+  # Subclasses of JSONObject, but not Resource
+  autoload :AndroidDetails, 'jamf/api/json_objects/android_details'
+  autoload :AppleTVDetails, 'jamf/api/json_objects/appletv_details'
+  autoload :CellularNetwork, 'jamf/api/json_objects/cellular_network'
+  autoload :ChangeLogEntry, 'jamf/api/json_objects/change_log_entry'
+  autoload :ComputerPrestageSkipSetupItems, 'jamf/api/json_objects/computer_prestage_skip_setup_items'
+  autoload :Country, 'jamf/api/json_objects/country'
+  autoload :ExtensionAttributeValue, 'jamf/api/json_objects/extension_attribute_value'
+  autoload :InstalledApplication, 'jamf/api/json_objects/installed_application'
+  autoload :InstalledCertificate, 'jamf/api/json_objects/installed_certificate'
+  autoload :InstalledConfigurationProfile, 'jamf/api/json_objects/installed_configuration_profile'
+  autoload :InstalledEBook, 'jamf/api/json_objects/installed_ebook'
+  autoload :InstalledProvisioningProfile, 'jamf/api/json_objects/installed_provisioning_profile'
+  autoload :InventoryPreloadExtensionAttribute, 'jamf/api/json_objects/inventory_preload_extension_attribute'
+  autoload :IosDetails, 'jamf/api/json_objects/ios_details'
+  autoload :Location, 'jamf/api/json_objects/location'
+  autoload :PrestageLocation, 'jamf/api/json_objects/prestage_location'
+  autoload :PrestageSyncStatus, 'jamf/api/json_objects/prestage_sync_status'
+  autoload :MobileDeviceDetails, 'jamf/api/json_objects/mobile_device_details'
+  autoload :MobileDeviceSecurity, 'jamf/api/json_objects/mobile_device_security'
+  autoload :MobileDevicePrestageName, 'jamf/api/json_objects/md_prestage_name'
+  autoload :MobileDevicePrestageNames, 'jamf/api/json_objects/md_prestage_names'
+  autoload :MobileDevicePrestageSkipSetupItems, 'jamf/api/json_objects/md_prestage_skip_setup_items'
+  autoload :PurchasingData, 'jamf/api/json_objects/purchasing_data'
+  autoload :PrestagePurchasingData, 'jamf/api/json_objects/prestage_purchasing_data'
+  autoload :PrestageScope, 'jamf/api/json_objects/prestage_scope'
+  autoload :PrestageAssignment, 'jamf/api/json_objects/prestage_assignment'
+
+  # Subclasses of SingletonResource
+  autoload :ClientCheckInSettings, 'jamf/api/resources/singleton_resources/client_checkin_settings'
+  autoload :ReEnrollmentSettings, 'jamf/api/resources/singleton_resources/reenrollment_settings'
+  autoload :AppStoreCountryCodes, 'jamf/api/resources/singleton_resources/app_store_country_codes'
+
+  # Subclasses of CollectionResource
+  autoload :Attachment, 'jamf/api/resources/collection_resources/attachment'
+  autoload :Building, 'jamf/api/resources/collection_resources/building'
+  autoload :Computer, 'jamf/api/resources/collection_resources/computer'
+  autoload :ComputerPrestage, 'jamf/api/resources/collection_resources/computer_prestage'
+  autoload :Department, 'jamf/api/resources/collection_resources/department'
+  autoload :ExtensionAttribute, 'jamf/api/resources/collection_resources/extension_attribute'
+  autoload :InventoryPreloadRecord, 'jamf/api/resources/collection_resources/inventory_preload_record'
+  autoload :MobileDevice, 'jamf/api/resources/collection_resources/mobile_device'
+  autoload :MobileDevicePrestage, 'jamf/api/resources/collection_resources/md_prestage'
+  autoload :Site, 'jamf/api/resources/collection_resources/site'
+  autoload :Script, 'jamf/api/resources/collection_resources/script'
+
+  # other classes used as attributes inside the resource classes
+  autoload :IPAddress, 'jamf/api/attribute_classes/ip_address'
+  autoload :Timestamp, 'jamf/api/attribute_classes/timestamp'
+
+end # module

data/lib/jamf/api/abstract_classes/collection_resource.rb

@@ -0,0 +1,422 @@
+# Copyright 2019 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.
+#
+#
+
+# The module
+module Jamf
+
+  # A Collection Resource in Jamf Pro
+  #
+  # See {Jamf::Resource} for general info about API resources.
+  #
+  # Collection resources have more than one resource within them, and those
+  # can (usually) be created and deleted as well as fetched and updated.
+  # The entire collection (or a part of it) can also be fetched as an Array.
+  # When the whole collection is fetched, the result is cached for future use.
+  #
+  # # Subclassing
+  #
+  # ## Creatability, & Deletability
+  #
+  # Sometimes the API doesn't support creation of new members of the collection.
+  # If that's the case, just extend the subclass with Jamf::UnCreatable
+  # and the '.create' class method will raise an error.
+  #
+  # Similarly for deletion of members: if the API doesn't have a way to delete
+  # them, extend the subclass with Jamf::UnDeletable
+  #
+  # See also Jamf::JSONObject, which talks about extending subclasses
+  # with Jamf::Immutable
+  #
+  # ## Bulk Deletion
+  #
+  # Some collection resources have a resource for bulk deletion, passing in
+  # a JSON array of ids to delete.
+  #
+  # If so, just define a BULK_DELETE_RSRC, and the .delete class method
+  # will use it, rather than making multiple calls to delete individual
+  # items. See Jamf::Category::BULK_DELETE_RSRC for an example
+  #
+  # @abstract
+  #
+  class CollectionResource < Jamf::Resource
+
+    extend Jamf::Abstract
+    include Comparable
+
+    # Public Class Methods
+    #####################################
+
+    # @return [Array<Symbol>] the attribute names that are marked as identifiers
+    #
+    def self.identifiers
+      self::OBJECT_MODEL.select { |_attr, deets| deets[:identifier] }.keys
+    end
+
+    # An array of attribute names that are required when
+    # making new CollectionResources
+    # See the OBJECT_MODEL documentation in {Jamf::JSONObject}
+    def self.required_attributes
+      self::OBJECT_MODEL.select { |_attr, deets| deets[:required] }.keys
+    end
+
+    # The Collection members Array for this class, retrieved from
+    # the RSRC_PATH as Parsed JSON, but not instantiated into instances
+    # unless instantiate: is truthy.
+    #
+    # E.g. for {Jamf::Settings::Building}, this would be the Array of Hashes
+    # returned by GETing the resource .../settings/obj/building
+    #
+    # This Array is cached in the {Jamf::Connection} instance used to
+    # retrieve it, and future calls to .all will return the cached Array
+    # unless refresh is truthy.
+    #
+    # TODO: Investigate https://www.rubydoc.info/github/mloughran/api_cache
+    #
+    # @param refresh[Boolean] re-read the data from the API?
+    #
+    # @param cnx[Jamf::Connection] an API connection to use for the query.
+    #   Defaults to the corrently active connection. See {Jamf::Connection}
+    #
+    # @param instantiate[Boolean] The Array contains instances of this class
+    #   rather than the JSON Hashes from the API.
+    #
+    # @return  [Array<Object>] An Array of all objects of this class in the JSS.
+    #
+    def self.all(refresh = false, cnx: Jamf.cnx, instantiate: false)
+      validate_not_abstract
+      cnx.collection_cache[self] = nil if refresh
+      return cnx.collection_cache[self] if cnx.collection_cache[self]
+
+      raw = cnx.get rsrc_path
+      cnx.collection_cache[self] =
+        if raw.is_a?(Hash) && raw[:results]
+          raw[:results]
+        else
+          raw
+        end
+
+      return cnx.collection_cache[self] unless instantiate
+
+      cnx.collection_cache[self].map { |m| new m }
+    end
+
+    # An array of the ids for all collection members
+    #
+    # @param refresh (see .all)
+    #
+    # @param cnx (see .all)
+    #
+    # @return [Array<Integer>]
+    #
+    def self.all_ids(refresh = false, cnx: Jamf.cnx)
+      all(refresh, cnx: cnx).map { |m|  m[:id] }
+    end
+
+    # rubocop:disable Naming/UncommunicativeMethodParamName
+
+    # A Hash of all members of this collection where the keys are some
+    # identifier and values are any other attribute.
+    #
+    # @param ident [Symbol] An identifier of this Class, used as the key
+    #   for the mapping Hash.
+    #
+    # @param to [Symbol] The attribute to which the ident will be mapped
+    #
+    # @param refresh (see .all)
+    #
+    # @param cnx (see .all)
+    #
+    # @return [Hash {Symbol: Object}] A Hash of identifier mapped to attribute
+    #
+    def self.map_all(ident, to:, cnx: Jamf.cnx, refresh: false)
+      raise Jamf::InvalidDataError, "No identifier #{ident} for class #{self}" unless
+      identifiers.include? ident
+
+      raise Jamf::NoSuchItemError, "No attribute #{to} for class #{self}" unless self::OBJECT_MODEL.key? to
+
+      list = all refresh, cnx: cnx
+      to_class = self::OBJECT_MODEL[to][:class]
+      mapped = list.map do |i|
+        [
+          i[ident],
+          to_class.is_a?(Symbol) ? i[to] : to_class.new(i[to])
+        ]
+      end # do i
+      mapped.to_h
+    end
+    # rubocop:enable Naming/UncommunicativeMethodParamName
+
+    # Given any identfier value for this collection, return the valid
+    # id, or nil if there's no match for the given value.
+    #
+    # If you know the value is a certain identifier, e.g. a serial_number
+    # then you can specify the identifier, for a faster search:
+    #
+    #   valid_id serial_number: 'AB12DE34' # => Int or nil
+    #
+    # If you don't know wich identifier you have, just pass the value and
+    # all identifiers are searched
+    #
+    #   valid_id 'AB12DE34' # => Int or nil
+    #   valid_id 'SomeComputerName' # => Int or nil
+    #
+    # When the value is a string, the seach is case-insensitive
+    #
+    # TODO: When 'Searchability' is more dialed in via the searchable
+    # mixin, which implements enpoints like 'POST /v1/search-mobile-devices'
+    # then use that before using the 'all' list.
+    #
+    # @param value [Object] A value to search for as an identifier.
+    #
+    # @param refresh[Boolean] Reload the list data from the API
+    #
+    # @param ident: [Symbol] Restrict the search to this identifier.
+    #  E.g. if :serial_number, then the value must be
+    #  a known serial number, it is not checked against other identifiers
+    #
+    # @param cnx: (see .all)
+    #
+    # @return [Object, nil] the primary identifier of the matching object,
+    #   or nil if it doesn't exist
+    #
+    def self.valid_id(value = nil, refresh: true, cnx: Jamf.cnx, **ident_hash)
+      unless ident_hash.empty?
+        ident, value = ident_hash.first
+        return id_from_other_ident ident, value, refresh, cnx: cnx
+      end
+
+      # check the id itself first
+      return value if all_ids(refresh, cnx: cnx).include? value
+
+      idents = identifiers - [:id]
+      val_is_str = value.is_a? String
+
+      idents.each do |ident|
+        match = all(cnx: cnx).select do |m|
+          val_is_str ? m[ident].to_s.casecmp?(value) : m[ident] == value
+        end.first
+        return match[:id] if match
+      end # identifiers.each do |ident|
+
+      nil
+    end
+
+    # Bu default, subclasses are creatable, i.e. new instances can be created
+    # with .create, and added to the JSS with .save
+    # If a subclass is NOT creatble for any reason, just add
+    #   extend Jamf::UnCreatable
+    # and this method will return false
+    #
+    # @return [Boolean]
+    def self.creatable?
+      true
+    end
+
+    # Make a new thing to be added to the API
+    def self.create(params, cnx: Jamf.cnx)
+      raise Jamf::UnsupportedError, "#{self}'s are not currently creatable via the API" unless self.creatable?
+
+      validate_not_abstract
+
+      validate_required_attributes params
+
+      params.delete :id # no such animal when .creating
+      params[:creating_from_create] = true
+      new params, cnx: cnx
+    end
+
+    # Retrieve a member of a CollectionResource from the API
+    #
+    # To create new members to be added to the JSS, use
+    # {Jamf::CollectionResource.create}
+    #
+    # If you know the specific identifier attribute you're looking up, e.g.
+    # :id or :name or :udid, (or an aliase thereof) then you can specify it like
+    # `.fetch name: 'somename'`, or `.fetch udid: 'someudid'`
+    #
+    # If you don't know if (or don't want to type it) you can just use
+    # `.fetch 'somename'`, or `.fetch 'someudid'` and all identifiers will be
+    # searched for a match.
+    #
+    # @param ident_value[Object] A value for any identifier for this subclass.
+    #  All identifier attributes will be searched for a match.
+    #
+    # @param cnx[Jamf::Connection] the connection to use to fetch the object
+    #
+    # @param ident_hash[Hash] an identifier attribute key and a search value
+    #
+    # @return [CollectionResource] The ruby-instance of a Jamf object
+    #
+    def self.fetch(ident_value = nil, cnx: Jamf.cnx, **ident_hash)
+      validate_not_abstract
+      id =
+        if ident_value == :random
+          all_ids.sample
+        elsif ident_value
+          valid_id ident_value
+        elsif ident_hash.empty?
+          nil
+        else
+          ident, lookup_value = ident_hash.first
+          valid_id ident => lookup_value
+        end
+
+      raise Jamf::NoSuchItemError, "No matching #{self}" unless id
+
+      data = cnx.get "#{rsrc_path}/#{id}"
+      new data, cnx: cnx
+    end # fetch
+
+    # By default, CollectionResource subclass instances are deletable.
+    # If not, just extend the subclass with Jamf::UnDeletable, and this
+    # will return false, and .delete & #delete will raise errors
+    def self.deletable?
+      true
+    end
+
+    # Delete one or more objects by identifier
+    # Any valid identifier for the class can be used (id, name, udid, etc)
+    # Identifiers can be provided as an array or as separate parameters
+    #
+    # e.g. .delete [1,3, 34, 4]
+    # or .delete 'myComputer', 'that-computer', 'OtherComputer'
+    #
+    # @param idents[Array<integer>, Integer]
+    #
+    # @param cnx[Jamf::Connection]
+    #
+    # @return [Array] the identifiers that were not found, so couldn't be deleted
+    #
+    def self.delete(*idents, cnx: Jamf.cnx)
+      raise Jamf::UnsupportedError, "Deleting #{self} objects is not currently supported" unless deletable?
+
+      idents.flatten!
+      no_valid_ids = []
+
+      idents.map do |ident|
+        id = valid_id ident
+        no_valid_ids << ident unless id
+        id
+      end
+      idents.compact!
+
+      # TODO: some rsrcs have a 'bulk delete' version...
+      idents.each { |id| cnx.delete "#{rsrc_path}/#{id}" }
+
+      no_valid_ids
+    end
+
+    # Private Class Methods
+    #####################################
+
+    # TODO: better pluralizing?
+    #
+    def self.create_list_methods(attr_name, attr_def)
+      list_method_name = "all_#{attr_name}s"
+
+      define_singleton_method(list_method_name) do |refresh = false, cnx: Jamf.cnx|
+        all_list = all(refresh, cnx: cnx)
+        if attr_def[:class].is_a? Symbol
+          all_list.map { |i| i[attr_name] }.uniq
+        else
+          all_list.map { |i| attr_def[:class].new i[attr_name] }
+        end
+      end # define_singleton_method
+
+      return unless attr_def[:aliases]
+
+      # aliases - TODO: is there a more elegant way?
+      attr_def[:aliases].each do |a|
+        define_singleton_method("all_#{a}s") do |refresh = false, cnx: Jamf.cnx|
+          send list_method_name, refresh, cnx: cnx
+        end # define_singleton_method
+      end # each alias
+    end # create_list_methods
+    private_class_method :create_list_methods
+
+    # validate that our .create data has the required attribute values.
+    # They can't be nil or empty.
+    #
+    def self.validate_required_attributes(data)
+      required_attributes.each do |atr|
+        raise Jamf::MissingDataError, "Required attribute '#{atr}:' may not be nil or empty" if data[atr].to_s.empty?
+      end
+    end
+    private_class_method :validate_required_attributes
+
+    # Given an indentier attr. key, and a value,
+    # return the id where that ident has that value, or nil
+    #
+    def self.id_from_other_ident(ident, value, refresh = true, cnx: Jamf.cnx)
+      raise ArgumentError, "Unknown identifier '#{ident}' for #{self}" unless identifiers.include? ident
+
+      # check the id itself first
+      return value if ident == :id && all_ids(refresh, cnx: cnx).include?(value)
+
+      # all ident values => ids
+      ident_map = map_all(ident, to: :id, cnx: cnx, refresh: refresh)
+
+      # case-insensitivity for string values
+      value = ident_map.keys.j_ci_fetch_string(value) if value.is_a? String
+
+      ident_map[value]
+    end
+    private_class_method :id_from_other_ident
+
+
+    # Instance Methods
+    #####################################
+
+    def exist?
+      !@id.nil?
+    end
+
+    def rsrc_path
+      return unless exist?
+      "#{self.class.rsrc_path}/#{@id}"
+    end
+
+    def delete
+      raise Jamf::UnsupportedError, "Deleting #{self} objects is not currently supported" unless self.class.deletable?
+      @cnx.delete rsrc_path
+    end
+
+    # Two collection resource objects are the same if their id's are the same
+    def <=>(other)
+      id <=> other.id
+    end
+
+    # Private Instance Methods
+    ############################################
+    private
+
+    def create_in_jamf
+      result = @cnx.post self.class.rsrc_path, to_jamf
+      @id = result[:id]
+    end
+
+  end # class CollectionResource
+
+end # module JAMF