ruby-jss 1.6.0 → 2.0.0a11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e0dafc4e4ff96d1752578ca2cdb38bd4410f6aa5a32d42d02b8abf499269ab0
-  data.tar.gz: 5d4cb7b7846541246c029f9d562fed7a30eba677aeae8f50e186d0ebcef33a97
+  metadata.gz: 89a063540145b18ab23771f87ad6eb8db80c154e911138b75a7a233117fb6dc6
+  data.tar.gz: 139bc4655da8a6a1e4bed21add476f6bfaa844dbda4fb0e477fdcee45079cc9e
 SHA512:
-  metadata.gz: ca56f63003f45b7eeeda5adc2843dc399c4944126d116fc16dd8ce73b3a5af70333a581847b5e15641b76171e8bf6e7969622a52052fff1d25fbace4564c36d3
-  data.tar.gz: 37dd3abb514c208cda9329296ce1b1f4aa9746adb1a93837920d47a62aa171db20bcd9aa20927012445e979b8b69ecc07642202eaef6f0faa9252b2bd28df9dc
+  metadata.gz: 33d23b52e0f0bb2f42a4a606ae34288b4b7ceb35e3d051ccb1281456709cdee7d4bcaea26681f30126239e30bde8de55bc550fe021d2e59a9cd0f05fdeb40d65
+  data.tar.gz: b8b8c46c351833c47493ad2512349b952522d2916bcac4b0143a0c49aa140187635be582ad5971da0a63e599fbd263900eecb01bce24b88da6f88a8457ea82fc

data/.yardopts

@@ -5,3 +5,4 @@
 LICENSE.txt
 CHANGES.md
 THANKS.md
+README-2.0.0.md

data/CHANGES.md

@@ -4,7 +4,87 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## \[1.6.0] - 2021-05-??
+## **IMPORTANT: Known Security Issue in v1.5.3 and below**
+
+Versions of ruby-jss prior to 1.6.0 contain a known security issue due to the use of the 'plist' gem.
+
+This has been resolved in 1.6.0, which now uses the CFProperlyList gem.
+
+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.
+
+## \[2.0.0] - Unreleased
+
+Version 2.0.0 is a major refactoring of ruby-jss. While attempting to provide as much backward compatibility as possible, there are some significant changes and v2.0.0 is not fully backward compatible. **PLEASE TEST YOUR CODE EXTENSIVELY**
+
+Here are the high-level changes and there are many many others. For more details, see [CHANGES-2.0.0](CHANGES-2.0.0.md)
+
+- Combined access to both APIs.
+  - The Classic and Jamf Pro APIs are no longer separated into the JSS and Jamf modules. There is only the `Jamf` module, and `JSS` is merely an alias of it, so all your code refering to the JSS module should still work.
+- Auto-generated classes for the Jamf Pro API
+  - Base classes for JamfPro API objects are automatically generated from the OAPI3 Schema available at https://your.jamf.server/api/schema. This make it much simpler for ruby-jss to implement and update new and changed objects and endpoints in the Jamf Pro API.
+- Code is auto-loaded from disk
+  - Because the auto-generated classes add hundreds of files to the gem, ruby-jss now uses [Zeitwerk](https://github.com/fxn/zeitwerk) to auto-load only the files it needs when they are needed.
+
+
+## \[1.6.7] - 2022-02-22
+
+### Added
+
+  - Support for the FORCE_IPA_UPLOAD parameter when uploading mobiledeviceapplicationsipa data. This makes the server upload the .ipa to cloud distribution points, as it does when uploaded via the WebUI.
+
+## \[1.6.6] - 2022-02-06
+
+### Added
+
+  - Support for EnableRemoteDesktop and DisableRemoteDesktop MDM commands
+
+## \[1.6.5] - 2021-10-14
+
+### Fixed
+
+  - Uplodable#upload now works with Faraday
+
+### Added
+
+  - Attribute 'os_type' added to JSS::MobileDeviceApplication
+
+## \[1.6.4] - 2021-10-04
+
+### Fixed
+
+  - Removed erroneous call to generate self-service XML from JSS::RestrictedSoftware#rest_xml, restricted software items in Jamf Pro are not 'self servable'. Thanks to @marekluban for catching and reporting this one!
+
+### Added
+
+  - Attribute reader JSS::Computer#security, returning the hash of data from the 'security' subset of API computer data.
+
+## \[1.6.3] - 2021-09-13
+
+### Fixed
+
+  - Fixed a bug where some Jamf Pro API CollectionResource subclasses could not be fetched twice without a '.all' scache refresh
+
+### Changed
+
+  - DBConnection.valid_server? connection timeout raised to 60 seconds
+
+  - Update JSS.expand_min_os to handle the fact that OS versions from Apple now have three meaningful parts (major.minor.patch) and that the patch version might be an 'x', as well as the minor version.
+
+
+## \[1.6.1] - 2021-07-27
+
+### Fixed
+
+  - Resolved some more typo-errors regarding display names in the SelfServable mixin module.
+
+### Changed
+
+  - MySQL connections via the DBConnection class now report some authentication errors more clearly.
+
+
+## \[1.6.0] - 2021-05-24
 
 ### Fixed
 
@@ -89,7 +169,7 @@ Big thanks to @cybertunnel for many enhancements and fixes.
 
   - Removed dependency on net-ldap, which hasn't been used in a while
 
-  - Removed the redundant JSS::APIConnection instance methods that were just wrappers for various APIObject subclass Class methods, e.g. `JSS.api.valid_id :computers, 'compName'`. Please use the class method directly, e.g. `JSS::Computer.valid_id 'compName'`
+  - Removed the redundant JSS::APIConnection instance methods that were just wrappers for various APIObject subclass Class methods, e.g. `Jamf.cnx.valid_id :computers, 'compName'`. Please use the class method directly, e.g. `JSS::Computer.valid_id 'compName'`
 
 ### Fixed
 
@@ -450,7 +530,7 @@ To change the number of retries, provide an integer with the `retries:` paramete
   - The class method allows adding and removing members without fetching an instance of the group.
   - The instance method adds and/or removes members immediately, without needing to call #update or #save
 
-- LDAPServer.server_for_user and .server_for_group class methods, return the id of the first LDAP server containing the given user or group
+- LdapServer.server_for_user and .server_for_group class methods, return the id of the first LDAP server containing the given user or group
 
 - Client.homedir(user) and Client.do_not_disturb?(user)
 
@@ -462,7 +542,7 @@ To change the number of retries, provide an integer with the `retries:` paramete
   rather than
     `https://myjss.myserver.edu:8443/`
   then use this parameter to specify the path below the root e.g:
-    `JSS.api.connect server: 'myjss.myserver.edu', server_path: 'dev_mgmt/jssweb', port: 8443 [...]`
+    `Jamf.cnx.connect server: 'myjss.myserver.edu', server_path: 'dev_mgmt/jssweb', port: 8443 [...]`
   (Thanks @christopher.kemp!)
 
 - Packages in Jamf Pro 10.10 and higher now include checksum data (`hash_type` and `hash_value` in the raw data) via the classic API. This has been integrated into JSS::Package via the following methods:
@@ -541,7 +621,7 @@ Finally we're going to version 1.0, which we should have done when we went opens
 
   If you are using macOS 10.12 or lower to connect to Jamf Pro 10.4 (the lowest Jamf server supported by this version of ruby-jss), you must specify the older TLS when using APIConnection#connect, e.g.
 
-  `JSS.api.connect server: 'myjss.myschool.edu', user: 'username', pw: :prompt, ssl_version: :TLSv1`
+  `Jamf.cnx.connect server: 'myjss.myschool.edu', user: 'username', pw: :prompt, ssl_version: :TLSv1`
 
   Machines running macOS 10.12 or lower will not be able to connect to Jamf Pro > v10.4 with the built-in ruby openssl library. If you specify `ssl_version: :TLSv1` you will get an error because the server won't accept it. If you leave the default :TLSv1_2, ruby's openssl library will complain that it doesn't know about that.
 

data/README-2.0.0.md

@@ -0,0 +1,324 @@
+# ruby-jss 2.0: Combined access to the Classic and Jamf Pro APIs
+
+Version 2.0.0 is a major refactoring of ruby-jss. While attempting to provide as much backward compatibility as possible, there are some significant changes under the hood. **_PLEASE TEST YOUR CODE EXTENSIVELY_**
+
+This document discusses the high-level changes, listing the detailed changes that have already happened, as well as planned changes and deprecations. It also provides some discussion and background around all of this. It is a work-in-progress at the moment, and hopefully will prompt discussion and decision-making in the #ruby-jss channel of MacAdmins Slack (Please join us!)
+
+These changes have been in mind for some time, but the ability (soon to be requirement) for the Classic API to authenticate with Bearer Tokens from the Jamf Pro API means that the time has come, so here we are!
+
+**CONTENTS**
+
+<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
+
+- [Requirements](#requirements)
+- [High level changes](#high-level-changes)
+  - [Ruby 3.x support](#ruby-3x-support)
+  - [Combined API access](#combined-api-access)
+    - [A single Connection class](#a-single-connection-class)
+      - [Connecting to the API](#connecting-to-the-api)
+        - [The default connection](#the-default-connection)
+    - [A single namespace `Jamf`](#a-single-namespace-jamf)
+      - [Inherant differences between the APIs](#inherant-differences-between-the-apis)
+      - [Which API does an object come from?](#which-api-does-an-object-come-from)
+  - [Automatic code generation](#automatic-code-generation)
+  - [Autoloading with Zeitwerk](#autoloading-with-zeitwerk)
+- [Notable changes from ruby-jss 1.x](#notable-changes-from-ruby-jss-1x)
+  - [Paged queries to the Jamf Pro API](#paged-queries-to-the-jamf-pro-api)
+  - [API data are no longer cached (?)](#api-data-are-no-longer-cached-)
+  - [No Attribute aliases for Jamf Pro API objects](#no-attribute-aliases-for-jamf-pro-api-objects)
+  - [Class/Mixin hierarchy for Jamf Pro API objects](#classmixin-hierarchy-for-jamf-pro-api-objects)
+- [Planned deprecations](#planned-deprecations)
+  - [Use of the term 'api' in method names, parameter names, and attributes](#use-of-the-term-api-in-method-names-parameter-names-and-attributes)
+  - [`.map_all_ids_to` method for Classic API collection classes](#map_all_ids_to-method-for-classic-api-collection-classes)
+  - [Using `.make`, `#create`, and `#update` for Classic API objects](#using-make-create-and-update-for-classic-api-objects)
+  - [JSS::CONFIG](#jssconfig)
+  - [Jamf::Connection instance methods `#next_refresh`, `#secs_to_refresh`, &  `#time_to_refresh`](#jamfconnection-instance-methods-next_refresh-secs_to_refresh---time_to_refresh)
+  - [Cross-object validation in setters](#cross-object-validation-in-setters)
+  - [.fetch :random](#fetch-random)
+- [Documentation](#documentation)
+- [How to install for testing](#how-to-install-for-testing)
+- [Contact](#contact)
+
+<!-- /TOC -->
+
+## Requirements
+
+ruby-jss 2.0 requires ruby 2.6.3 or higher, and a Jamf Pro server running version 10.35 or higher.
+
+This means it will work with the OS-supplied /usr/bin/ruby in macOS 10.15 Catalina and above, until Apple removes ruby from the OS.
+
+## High level changes
+
+### Ruby 3.x support
+
+The plan is for ruby-jss 2.0+ to be compatible with ruby 2.7 and higher, including ruby 3.x
+
+As of this writing, basic access to the API seems to be working in ruby 3, but much much more testing is needed.
+
+It looks like the biggest changes have been dealing with keyword arguments as Hashs.  Methods defined with `def methodname([...] foo = {}` need to be changed to `def methodname([...] **foo` and calls to those methods, even in your own code, need to be changed to `methodname([...] **foo)` when `foo` is a hash of keyword args.
+
+**IMPORTANT**: do not pass raw hashes as 'keyword' args.  Instead use the double-splat: `methodname(**hash)` which should be compatible with ruby 3.x and 2.7.x
+
+for more info see [Separation of positional and keyword arguments in Ruby 3.0](https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/)
+
+### Combined API access
+
+ruby-jss has always used the `JSS` module to encapsulate all access to the Classic API. When the Jamf Pro API became a thing, the `Jamf` module was created as the way to interact with that API as it grew and developed.
+
+Even though the latest Jamf Pro release notes say the Jamf Pro API is still officially "open for user testing", it has stablized enough that it is used by many folks for production work.
+
+The announcement with Jamf Pro 10.35 that the Classic API can use, and will eventually require, a Bearer Token from the Jamf Pro API meant that it was time to merge the two in ruby-jss.
+
+#### A single Connection class
+
+There is now one `Jamf::Connection` class, instances of which are connections to a Jamf Pro server. Once connected, the connection instance maintains connections to _both_ APIs and other classes use them as needed. As before, there are low-level methods available for sending HTTP requests manually, which are specific to each API. See the documentation for `Jamf::Connection` (link TBA) for details.
+
+##### Connecting to the API
+
+Most of the previous methods and parameters for making API connections to either API should still work, including using a URL rather than individual connection parameters. So both of these are valid and identical:
+
+```ruby
+a_connection = Jamf::Connection.new 'https://apiuser@my.jamf.server:8443/', pw: :prompt
+
+another_connection = Jamf::Connection.new host: 'my.jamf.server', port: 8443, user: 'apiuser', pw: :prompt
+```
+
+Other connection parameters can be passed in as normal.
+
+###### The default connection
+
+The top-level module methods for accessing the 'default' connection are still available and are now synonyms: `Jamf.cnx` and `JSS.api` both return the current default Jamf::Connection instance. There is also a top-level methods`Jamf.connect` which is the same as `Jamf.cnx.connect`. The top-level methods for changing the default connection are still there. The use of `JSS::API` has been deprecated for years now, and still is (see below).
+
+#### A single namespace `Jamf`
+
+Version 2.0.0 combines the `JSS` module and the `Jamf` module into a single `Jamf` module, with `JSS` aliased to it. This means you can use them interchangably to refer to the Jamf module, and existing code that used either should still work. The module name no longer indicates which API you're working with.
+
+For example, the `JSS::Computer` class, from the Classic API, is still a thing, but now just points to the `Jamf::Computer` class, still from the Classic API.  The `Jamf::InventoryPreloadRecord` class, from the Jamf Pro API remains as is, but can also be referred to as `JSS::InventoryPreloadRecord`
+
+##### Inherant differences between the APIs
+
+In theory, you shouldn't need to worry about which classes and objects come from which API - you can just `.fetch`, `.create`, `.save`, etc.. and ruby-jss will deal with the API interaction for you.
+
+However, in reality the two APIs have different functionality, some of which must be reflected in the ruby classes that represent objects in those APIs.
+
+Take, for example, the classes for 'Collection Resources' - API endpoints that let you deal with collections of objects like Computers, or Inventory Preload Records.  These classes implement a `.all` class method, which retrieves a list of some data about all members of the collection.
+
+Not only is the data returned in such lists very different between the APIs, but in the Jamf Pro API, you can ask the server to return the list already sorted, possibly filtered, or 'paged' in groups of some number of items. None of that is possible in the Classic API.
+
+The `.all` method, and its relatives like `.all_ids`, `.all_names`, etc. exist for Collection Resources in both APIs, but the methods take different parameters, e.g. to deal with sorting and filtering. Jamf Pro API classes have a `.pager` method which returns an object from which you can retrieve the 'pages' of your query.
+
+##### Which API does an object come from?
+
+To confirm which API a class comes from, just look at its `API_SOURCE` constant, e.g. `Jamf::Computer::API_SOURCE`. This constant will return a symbol, either `:classic` or `:jamf_pro`
+
+### Automatic code generation
+
+While the Classic API classes in ruby-jss are very hand-built and must be manually edited to add access to new data, the Jamf Pro API has an OpenAPI3 specification - a JSON document that fully describes the entire API and what it can do.
+
+The API documentation you see at your own Jamf Pro server at https://your.jamf.server/api/doc/ is generated from the OAPI specification. The specification itself can be seen at https://your.jamf.server/api/schema.
+
+In ruby-jss 2.0 and up, the OAPI spec is used to automatically generate hundreds of 'base' classes in ruby-jss, each with automatically generated attribute getters, setters, validators, and other useful methods. These base classes can then be used as the superclasses of the Jamt Pro API objects we implement for direct use in ruby-jss - and the majority of the coding is already done! The subclasses implementing objects in ruby-jss can then be expanded and customized beyond the simple, auto-generated superclass.
+
+Not only does this make it fast and simple to implement new objects in ruby-jss, but allows fast and simple updates to existing objects, when new functionality is introduced to the API.
+
+If you develop ruby-jss, please see (documentation link TBA) for more info about how to use the auto-generated classes.
+
+### Autoloading with Zeitwerk
+
+Because the classes generated from the OAPI spec number in the hundreds, it's a waste of memory and time to load all of them in every time you `require ruby-jss`, since most of them will never be used for any given application.
+
+To deal with this, ruby-jss now uses the wonderfully cool [Zeitwerk gem](https://github.com/fxn/zeitwerk) to automatically load only the files needed for classes and modules as they are used.
+
+In fact, if you'd like to see it in action, just `touch /tmp/ruby-jss-verbose-loading` or `export RUBY_JSS_VERBOSE_LOADING=1` before you `require ruby-jss`.
+Then as files load, lines will be written to standard error indicating:
+
+  - Zeitwerk just loaded something from a file
+  - A module was mixed-in to some other module or class
+  - A method was just automatically defined
+
+## Notable changes from ruby-jss 1.x
+
+### Paged queries to the Jamf Pro API
+
+In the previous Jamf module, to get paged API results from a list of all objects in a collection, you would use the `page_size:` and `page:` parameters to the `.all` class method, and then use `.next_page_of_all` to get subsequent pages. Unfortunately the way this happened was not threadsafe.
+
+Now to get paged results, use the `.pager` class method, optionally sorted and filtered, as with `.all`. You'll be given a `Jamf::Pager` object, which you can then use to retrieve sequential or arbitrary pages from the query.
+
+The `.all` method will never deliver paged results, however if you give it a `filter` parameter for classes that support filtering, then `.all` returns "all that match the filter", which may be fewer than the entire collection.
+
+### API data are no longer cached (?)
+
+**NOTE:** As of this writing, caching has been removed for the objects from the Jamf Pro API, but caching remains in the Classic API. Its removal, or the re-instatement of caching for JP API objects, are pending discussion with users of ruby-jss.
+
+Pre-2.0, methods that would fetch large datasets from the server would always cache that data in the Connection object, and by default use the cache in future calls unless a `refresh` parameter is given. These datasets included:
+
+- collection lists, used by `.all` and friends, like `.all_ids` and `.valid_id`
+- Extension Attribute, definitions, used for validating Extension Attribute values
+
+In 2.0+, that caching has been removed for objects from them Jamf Pro API.
+
+ If you want to avoid repeated GET requests to the server when you aren't worried that the resulting data may have changed, you can store the results of `.all` in a variable, and either use it yourself, or pass it in to other methods via the `cached_list:` parameter. Passing in a cached_list wil prevent those methods from calling `.all` and reaching out to the server again.
+
+**WARNING**: Be careful that the list you pass in via `cached_list` contains the correct data structure for the class, and came from the desired Connection instance.
+
+### No Attribute aliases for Jamf Pro API objects
+
+Objects from the Jamf Pro API will no longer define aliases for the attribute names that come from the API itself. This means, e.g., to get the name of a ComputerPrestage or MobileDevicePrestage, you have to ask for its `displayName` not its `name`, since the property comes from the API as `displayName`. To see a list  of all the names, you must use `.all_displayNames` not `.all_names`.  For objects with a 'name' property (most of them) then you can use `.name` and `.all_names`.
+
+The reason behind this is twofold: 1) to simplify ruby-jss's code and automate as much as possible; 2) to reflect what Jamf actually gives us in the APIs.
+
+This is a breaking change from earlier ruby-jss versions, for which Jamf Pro API objects had the potential for aliases of their attribute names.
+
+### Class/Mixin hierarchy for Jamf Pro API objects
+
+If you contribute to ruby-jss, be aware that the structure of superclasses, subclasses, and mixin modules, and their file locations has changed drastically. Also changed is how to implement new objects using the OAPI auto-generated classes. These changes are due to using the auto-generated classes, as well as using Zeitwerk to autoload everything.
+
+There's a lot to document about these changes, and much of the current documentation is out of date, referring to how things were done when the Jamf module was separate and only talked to the Jamf Pro API.
+
+Give us time and we'll get everything updated. In the meantime, feel free to reach out in the #ruby-jss channel of Macadmins Slack, or open an issue on GitHub, or email ruby-jss@pixar.com.
+
+## Planned deprecations
+
+### Use of the term 'api' in method names, parameter names, and attributes
+
+Use `cnx` instead. Example:
+
+```ruby
+my_connection = Jamf::Connection.new 'https://user@my.jamf.server:8443/', pw: :prompt
+
+# OLD
+JSS::Computer.all_names api: my_connection
+
+# NEW
+JSS::Computer.all_names cnx: my_connection
+
+# OLD
+comp = JSS::Computer.fetch name: 12, api: my_connection
+comp.api # => my_connection
+
+# NEW
+comp = JSS::Computer.fetch id: 12, cnx: my_connection
+comp.cnx # => my_connection
+```
+
+In ruby-jss < 2.0, the term `api` is used with the Classic API in method names, method parameters, instance variables, attributes, and constants. It is used to pass, access, or hold instances of JSS::APIConnnection, e.g. so a method that talks to the server would use the passed connection rather than the module-wide default connection.  But, the thing being passed is a 'connection' not an 'API', and now that there are actually two APIs at play, that usage is even less appropriate.
+
+The Original Jamf module, which accessed only the Jamf Pro API, has always used the better-suited abbreviation `cnx` for this, and now that is standard everywhere. For now `api` should continue to work, but it will be removed 'eventually', so please start changing your code now.
+
+Accordingly, `JSS::API` (which should never have been a constant to begin with) is also deprecated. To access the default connection, use `Jamf.cnx`
+
+### `.map_all_ids_to` method for Classic API collection classes
+
+The `map_all_ids_to` method for the Classic API collection classes has been superceded by the more flexible `map_all` method, bringing it in-line with the Jamf Pro API classes.
+
+For now `map_all_ids_to` still works, however it's just a wrapper for `map_all`. Eventually the older method will be removed.
+
+### Using `.make`, `#create`, and `#update` for Classic API objects
+
+Use `.create` and `#save` instead, as with the Jamf Pro API objects
+
+In previous ruby-jss, both APIs avoided the use of the ruby-standard `.new` on Collection Resource classes, because the word 'new' in this context is ambiguous: are you creating a new instance of the class in ruby (which might already exist on the server), or are you creating a new object in Jamf Pro that doesn't yet exist on the server?
+
+In v2.0.0 we are standardizing on the behavior of the previous Jamf module:
+
+  - `Jamf::SomeCollectionClass.create` class method for instantiating a ruby object to be added as a new SomeCollectionClass object to Jamf Pro
+
+  - `Jamf::SomeCollectionClass#save` instance method for sending an object to the server to be created OR updated in Jamf pro.
+    - Note that `#save` has been available for this use since the earliest versions of ruby-jss.
+
+
+
+This means that these deprecated methods will go away for Classic API objects
+
+  - `Jamf::SomeCollectionClass.make` class method for instantiating a ruby object to be added as a new SomeCollectionClass to Jamf Pro
+    - use `Jamf::SomeCollectionClass.create` instead
+
+  - `Jamf::SomeCollectionClass#create` instance method for sending a new object to the API to be created on the server.
+    - Use `Jamf::SomeCollectionClass#save` instead.
+    - Note that `#save` has been a wrapper for both `#create` and `#update` since the earliest versions of ruby-jss.
+
+  - `Jamf::SomeCollectionClass#update` instance method for then sending changes to an existing object to the API to be update on the server.
+    - Use `Jamf::SomeCollectionClass#save` instead.
+    - Note that `#save` has been a wrapper for both `#create` and `#update` since the earliest versions of ruby-jss.
+
+```ruby
+# OLD
+
+# Get a ruby instance of a new policy to be added to Jamf Pro
+new_policy = Jamf::Policy.make name: 'my-policy'
+# ... set other values for the policy, then
+# Create it in Jamf Pro
+new_policy.create # new_policy.save has always been a synonym
+
+# fetch an existing policy from the server
+existing_policy = Jamf::Policy.fetch name: 'older-policy'
+# ... change some values for the policy, then
+# Update it in Jamf Pro
+existing_policy.update # existing_policy.save has always been a synonym
+
+# NEW
+
+# Get a ruby instance of a new policy to be added to Jamf Pro
+new_policy = Jamf::Policy.create name: 'my-policy'
+# ... set other values for the policy, then
+# Create it in Jamf Pro
+new_policy.save
+
+# fetch an existing policy from the server
+existing_policy = Jamf::Policy.fetch name: 'older-policy'
+# ... change some values for the policy, then
+# Update it in Jamf Pro
+existing_policy.save
+```
+
+### JSS::CONFIG
+
+This also should never have been a constant.  Use Jamf.config.  JSS::CONFIG will go away eventually.
+
+### Jamf::Connection instance methods `#next_refresh`, `#secs_to_refresh`, &  `#time_to_refresh`
+
+These values are actually part of the token used by the connection, not the conection itself. Replace them with `#token.next_refresh`, `#token.secs_to_refresh`, & `#token.time_to_refresh`
+
+### Cross-object validation in setters
+
+Most 'setters' (methods that let you set values for the attributes of an object) in ruby-jss perform some kind of validation to make sure the value you're trying to set is valid for that attribute. While still true, in v2.0 and up, this validation will be much more limited, mostly to ensuring the new value is of the correct type, e.g. an integer or a string, or a Jamf::Timestamp.
+
+Objects from the Classic API have also provided validation that goes beyond that - using other API objects as needed to 'pre-validate' your data in the setter method.
+
+For example, If you try to target a Policy scope to a certain ComputerGroup, when you use `my_policy.scope.add_target :computer_group, 1234` ruby-jss will use the Classic API to confirm that there actually is a computer group with the id 1234. If not, it will raise an exception.
+
+Or when you try to set the value of an extension attribute on a Computer object, ruby-jss will retrieve the details of the ComputerExtensionAttribute definition from the api, and make sure that the value you are setting is valid - the data type, and if a Popup Menu is the input, the value is one of the popup choices.
+
+This validation happens before you try to send the new data to the server.
+
+This type of pre-validation will be removed over time from objects in the Classic API, for 3 reasons:
+
+1) The API itself will perform this validation when you send the data, and will return an error if there's a problem.
+2) Removing this validation will simplify the code, and reduce interdependency between objects
+3) Removing this code will make it easier to understand the permissions needed to do things in ruby-jss
+
+The last point is very important.  Right now, in order to be able to manipulate the scope of any scopable object, the account with which you're accessing the API must have at least 'read' permission on all the different kinds of objects that _might_ be in the scope: computers, computer groups, buildings, departments, network segments, and so on. Removing or limiting the validation-based interdependency will make it easier to limit the access needed for API service accounts, and thereby increase overall security.
+
+### .fetch :random
+
+You can still fetch random objects from a collection, but use `.fetch random: true`. The older `.fetch :random` is deprecated and will be removed.
+
+## Documentation
+
+The YARD documentation for v2.0.0 is available before release in the [github.io site for ruby-jss](http://pixaranimationstudios.github.io/ruby-jss/docs/v2.x/index.html).
+
+All the documentation for ruby-jss is in need of updating, from the top-level README to the auto-generated YARD docs.  If you have questions that aren't answered there, please reach out (see Contact, below)
+
+## How to install for testing
+
+`gem install ruby-jss --version 2.0.0xy`
+
+where x is 'a' or 'b', and y is the alpha or beta number
+
+You can also clone the GitHub repo, cd into the top level of the project and run `gem build ruby-jss.gemspec`, then install the resulting gem.
+
+Check GitHub or rubygems.org to make sure you have the lastest test version.
+
+## Contact
+
+If you have questions or feedback about all this, please reach out in the [#ruby-jss channel of Macadmins Slack](https://macadmins.slack.com/archives/C03C7F563MK), or open an issue on GitHub, or email ruby-jss@pixar.com.

data/README.md

@@ -1,29 +1,48 @@
 # ruby-jss: Working with the Jamf Pro Classic API in Ruby
 [![Gem Version](https://badge.fury.io/rb/ruby-jss.svg)](http://badge.fury.io/rb/ruby-jss)
 
+## **IMPORTANT: Known Security Issue in v1.5.3 and below**
+
+Versions of ruby-jss prior to 1.6.0 contain a known security issue due to the use of the 'plist' gem.
+
+This has been resolved in 1.6.0, which now uses the CFProperlyList gem.
+
+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.
+
 ### Table of contents
-* [DESCRIPTION](#description)
-* [SYNOPSIS](#synopsis)
-* [USAGE](#usage)
-  * [Connecting to the API](#connecting-to-the-api)
-  * [Working with JSS Objects (a.k.a REST Resources)](#working-with-jss-objects-aka-rest-resources)
-  * [Listing Objects](#listing-objects)
-  * [Retrieving Objects](#retrieving-objects)
-  * [Updating Objects](#updating-objects)
-  * [Deleting Objects](#deleting-objects)
-* [OBJECTS IMPLEMENTED](#objects-implemented)
-  * [Creatable and Updatable](#creatable-and-updatable)
-  * [Updatable but not Creatable](#updatable-but-not-creatable)
-  * [Read-Only](#read-only)
-  * [Creatable and Updatable](#creatable-and-updatable)
-  * [Deletable](#deletable)
-* [CONFIGURATION](#configuration)
-  * [Passwords](#passwords)
-* [BEYOND THE API](#beyond-the-api)
-* [REQUIREMENTS](#requirements)
-* [INSTALL](#install)
-* [HELP](#help)
-* [LICENSE](#license)
+
+<!-- TOC -->
+
+- [DESCRIPTION](#description)
+  - [Contact](#contact)
+- [SYNOPSIS](#synopsis)
+- [USAGE](#usage)
+  - [Connecting to the API](#connecting-to-the-api)
+  - [Working with JSS Objects](#working-with-jss-objects)
+    - [Listing Objects](#listing-objects)
+    - [Retrieving Objects](#retrieving-objects)
+    - [Creating Objects](#creating-objects)
+    - [Updating Objects](#updating-objects)
+    - [Deleting Objects](#deleting-objects)
+- [OBJECTS IMPLEMENTED](#objects-implemented)
+  - [Creatable and Updatable](#creatable-and-updatable)
+  - [Updatable, but must be created in the Web UI](#updatable-but-must-be-created-in-the-web-ui)
+  - [Creatable only](#creatable-only)
+  - [Read-Only](#read-only)
+  - [Deletable](#deletable)
+    - [Other useful classes & modules:](#other-useful-classes--modules)
+- [Object-related API endpoints](#object-related-api-endpoints)
+- [CONFIGURATION](#configuration)
+  - [Passwords](#passwords)
+- [BEYOND THE API](#beyond-the-api)
+- [INSTALL](#install)
+- [REQUIREMENTS](#requirements)
+- [HELP](#help)
+- [LICENSE](#license)
+
+<!-- /TOC -->
 
 ## DESCRIPTION
 
@@ -45,7 +64,12 @@ Hopefully others will find it useful, and add more to it as well.
 
 [Full technical documentation can be found here.](http://www.rubydoc.info/gems/ruby-jss/)
 
-NOTE: ruby-jss 1.2.4 will introduce beta-level support for the Jamf Pro API in a ruby module called 'Jamf', See  README-JP-API.md in /lib/jamf, or in the 'Files' section of the YARD docs file for details.
+NOTE: ruby-jss 2.0.0 is in testing, see [README-2.0.0.md](README-2.0.0.md) for more info.
+
+### Contact
+
+If you have questions or feedback about ruby-jss, please reach out in the [#ruby-jss channel of Macadmins Slack](https://macadmins.slack.com/archives/C03C7F563MK), or open an issue on GitHub, or email ruby-jss@pixar.com.
+
 
 ## SYNOPSIS
 
@@ -55,7 +79,7 @@ Here are some simple examples of using ruby-jss
 require 'ruby-jss'
 
 # Connect to the API
-JSS.api.connect user: jss_user, pw: jss_user_pw, server: jss_server_hostname
+Jamf.cnx.connect user: jss_user, pw: jss_user_pw, server: jss_server_hostname
 
 # get an array of basic data about all JSS::Package objects in the JSS:
 pkgs = JSS::Package.all
@@ -99,12 +123,12 @@ ns.save
 
 Before you can work with JSS Objects via the API, you have to connect to it.
 
-The method `JSS.api` returns the currently active connection to the API (an instance of a {JSS::APIConnection}, q.v.).
+The method `Jamf.cnx` returns the currently active connection to the API (an instance of a {JSS::APIConnection}, q.v.).
 
-When the JSS Module is first loaded, that connection object isn't connected to anything. To remedy that, use `JSS.api.connect`, passing it parameters for the connection. In this example, those parameters are stored in the local variables jss_user, jss_user_pw, and jss_server_hostname, and others are left as default.
+When the JSS Module is first loaded, that connection object isn't connected to anything. To remedy that, use `Jamf.cnx.connect`, passing it parameters for the connection. In this example, those parameters are stored in the local variables jss_user, jss_user_pw, and jss_server_hostname, and others are left as default.
 
 ```ruby
-JSS.api.connect user: jss_user, pw: jss_user_pw, server: jss_server_hostname
+Jamf.cnx.connect user: jss_user, pw: jss_user_pw, server: jss_server_hostname
 ```
 
 Make sure the user has privileges in the JSS to do things with desired objects. Note that these might be more than you think, since some objects refer to other objects, like Sites and Categories.
@@ -282,7 +306,7 @@ Here's what we've implemented so far. See each Class's [documentation(http://www
 These must be created and edited via the JSS WebApp
 
 * {JSS::DistributionPoint}
-* {JSS::LDAPServer}
+* {JSS::LdapServer}
 * {JSS::NetBootServer}
 * {JSS::SoftwareUpdateServer}
 
@@ -292,7 +316,7 @@ All supported API Objects can be deleted
 
 #### Other useful classes & modules:
 
-* {JSS::APIConnection} - An object representing a connection to the Classic API on some server. The 'default' connection object is available via `JSS.api` but you can create others, and pass them into calls like `.fetch` as needed. This is useful when working with multiple servers at a time, such as a production and a test server. Objects retrieved from a connection know which connection they came from, and will only send changes via that connection.
+* {JSS::APIConnection} - An object representing a connection to the Classic API on some server. The 'default' connection object is available via `Jamf.cnx` but you can create others, and pass them into calls like `.fetch` as needed. This is useful when working with multiple servers at a time, such as a production and a test server. Objects retrieved from a connection know which connection they came from, and will only send changes via that connection.
 * {JSS::DBConnection} - An object representing the connection to MySQL database, if used.
 * {JSS::Server} - An object representing the Jamf Pro server being used by a connection. An instance is available in the #server attribute of a {JSS::APIConnection}.
 * {JSS::Client} - An object representing the local machine as a Jamf-managed client, and provifing Jamf-related info and methods
@@ -342,11 +366,11 @@ api_username: readonly-api-user
 api_verify_cert: false
 ```
 
-and then any calls to JSS.api.connect will assume that server and username, and won't complain about the self-signed certificate.
+and then any calls to Jamf.cnx.connect will assume that server and username, and won't complain about the self-signed certificate.
 
 ### Passwords
 
-The config files don't store passwords and the {JSS::Configuration} instance doesn't work with them. You'll have to use your own methods for acquiring the password for the JSS.api.connect call.
+The config files don't store passwords and the {JSS::Configuration} instance doesn't work with them. You'll have to use your own methods for acquiring the password for the Jamf.cnx.connect call.
 
 The {JSS::APIConnection.connect} method also accepts the symbols :stdin# and :prompt as values for the :pw argument, which will cause it to read the password from a line of stdin, or prompt for it in the shell.
 
@@ -356,7 +380,7 @@ Here's an example of how to use a password stored in a file:
 
 ```ruby
 password = File.read "/path/to/secure/password/file" # read the password from a file
-JSS.api.connect pw: password   # other arguments used from the config settings
+Jamf.cnx.connect pw: password   # other arguments used from the config settings
 ```
 
 And here's an example of how to read a password from a web server and use it.
@@ -364,7 +388,7 @@ And here's an example of how to read a password from a web server and use it.
 ```ruby
 require 'open-uri'
 password =  URI.parse('https://server.org.org/path/to/password').read
-JSS.api.connect pw: password   # other arguments used from the config settings
+Jamf.cnx.connect pw: password   # other arguments used from the config settings
 ```
 
 ## BEYOND THE API
@@ -419,6 +443,6 @@ There's a [wiki on the github page](https://github.com/PixarAnimationStudios/rub
 
 ## LICENSE
 
-Copyright 2020 Pixar
+Copyright 2022 Pixar
 
 Licensed under the Apache License, Version 2.0 (the "Apache License") with modifications. See LICENSE.txt for details