ruby-jss 0.6.5 → 0.6.6

data/lib/jss/webhooks/configuration.rb

@@ -0,0 +1,212 @@
+### Copyright 2016 Pixar
+###
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###
+###    You may obtain a copy of the Apache License at
+###
+###        http://www.apache.org/licenses/LICENSE-2.0
+###
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+###
+###
+
+module JSSWebHooks
+
+  # The configuration object
+  class Configuration
+
+    include Singleton
+
+    # The location of the default config file
+    DEFAULT_CONF_FILE = Pathname.new '/etc/jsswebhooks.conf'
+
+    ### The attribute keys we maintain, and the type they should be stored as
+    CONF_KEYS = {
+      server_port: :to_i,
+      server_engine:  :to_sym,
+      handler_dir: :to_s,
+      handler_computer_added: :to_s,
+      handler_computer_check_in: :to_s,
+      handler_computer_inventory_completed: :to_s,
+      handler_computer_policy_finished: :to_s,
+      handler_computer_push_capability_changed: :to_s,
+      handler_jss_shutdown: :to_s,
+      handler_jss_startup: :to_s,
+      handler_mobile_device_check_in: :to_s,
+      handler_mobile_device_command_complete: :to_s,
+      handler_mobile_device_enrolled: :to_s,
+      handler_mobile_device_push_sent: :to_s,
+      handler_mobile_device_unenrolled: :to_s,
+      handler_patch_software_title_updated: :to_s,
+      handler_push_sent: :to_s,
+      handler_rest_api_operation: :to_s,
+      handler_scep_challenge: :to_s,
+      handler_smart_group_computer_membership_change: :to_s,
+      handler_smart_group_mobile_device_membership_change: :to_s
+    }.freeze
+
+    #####################################
+    ### Class Variables
+    #####################################
+
+    #####################################
+    ### Class Methods
+    #####################################
+
+    #####################################
+    ### Attributes
+    #####################################
+
+    # automatically create accessors for all the CONF_KEYS
+    CONF_KEYS.keys.each { |k| attr_accessor k }
+
+    #####################################
+    ### Constructor
+    #####################################
+
+    ###
+    ### Initialize!
+    ###
+    def initialize
+      read_global
+    end
+
+    #####################################
+    ### Public Instance Methods
+    #####################################
+
+    ###
+    ### Clear all values
+    ###
+    ### @return [void]
+    ###
+    def clear_all
+      CONF_KEYS.keys.each { |k| send "#{k}=".to_sym, nil }
+    end
+
+    ###
+    ### (Re)read the global prefs, if it exists.
+    ###
+    ### @return [Boolean] was the file loaded?
+    ###
+    def read_global
+      return false unless DEFAULT_CONF_FILE.file? && DEFAULT_CONF_FILE.readable?
+      read DEFAULT_CONF_FILE
+    end
+
+    ###
+    ### Clear the settings and reload the prefs file, or another file if provided
+    ###
+    ### @param file[String,Pathname] a non-standard prefs file to load
+    ###
+    ### @return [Boolean] was the file reloaded?
+    ###
+    def reload(file = DEFAULT_CONF_FILE)
+      file = Pathname.new file
+      return false unless file.file? and file.readable?
+      clear_all
+      read file
+    end
+
+    ###
+    ### Save the prefs into a file
+    ###
+    ### @param file[Symbol,String,Pathname] either :user, :global, or an arbitrary file to save.
+    ###
+    ### @return [void]
+    ###
+    def save(file)
+      path = Pathname.new(file)
+
+      # file already exists? read it in and update the values.
+      # Don't overwrite it, since the user might have comments
+      # in there.
+      if path.readable?
+        data = path.read
+
+        # go thru the known attributes/keys
+        CONF_KEYS.keys.sort.each do |k|
+          # if the key exists, update it.
+          if data =~ /^#{k}:/
+            data.sub!(/^#{k}:.*$/, "#{k}: #{send k}")
+
+          # if not, add it to the end unless it's nil
+          else
+            data += "\n#{k}: #{send k}" unless send(k).nil?
+          end # if data =~ /^#{k}:/
+        end # each do |k|
+
+      else # not readable, make a new file
+        data = ''
+        CONF_KEYS.keys.sort.each do |k|
+          data << "#{k}: #{send k}\n" unless send(k).nil?
+        end
+      end # if path readable
+
+      # make sure we end with a newline, the save it.
+      data << "\n" unless data.end_with?("\n")
+      path.jss_save data
+    end # save file
+
+    ###
+    ### Print out the current settings to stdout
+    ###
+    ### @return [void]
+    ###
+    def print
+      CONF_KEYS.keys.sort.each { |k| puts "#{k}: #{send k}" }
+    end
+
+    #####################################
+    ### Private Instance Methods
+    #####################################
+    private
+
+    ###
+    ### Read in any prefs file
+    ###
+    ### @param file[String,Pathname] the file to read
+    ###
+    ### @return [Boolean] was the file read?
+    ###
+    def read(file)
+      available_conf_keys = CONF_KEYS.keys
+      Pathname.new(file).read.each_line do |line|
+        # skip blank lines and those starting with #
+        next if line =~ /^\s*(#|$)/
+
+        line.strip =~ /^(\w+?):\s*(\S.*)$/
+        key = Regexp.last_match(1)
+        next unless key
+        attr = key.to_sym
+        setter = "#{key}=".to_sym
+        value = Regexp.last_match(2).strip
+
+        next unless available_conf_keys.include? attr
+
+        # convert the value to the correct class
+        value = value.send(CONF_KEYS[attr]) if value
+
+        send(setter, value)
+      end # do line
+      true
+    end # read file
+
+  end # class Configuration
+
+  # The single instance of Configuration
+  CONFIG = JSSWebHooks::Configuration.instance
+
+end # module

data/lib/jss/webhooks/data/sample_handlers/RestAPIOperation-executable

@@ -0,0 +1,90 @@
+#!/bin/bash
+
+### Copyright 2016 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.
+###
+###
+
+# NOTE: Native bash doesn't have any easy way to parse JSON.
+# Instead, you should really use a tool like 'jq' https://stedolan.github.io/jq/.
+#
+# If you have jq, set its correct path in the JQ variable below.
+#
+# If not, this script will use a hacky, VERY inappropriate and breakable
+# way to parse JSON!
+# But, it works enough to demonstrate the idea of using bash to write a handler.
+
+# Enter your path to jq
+JQ=/usr/local/bin/jq
+
+# read all of stdin into a variable
+while read line ; do JSON="$JSON $line" ; done
+
+# use jq if we can
+if [ -x "$JQ" ] ; then
+
+  hookname=`echo $JSON | "$JQ" -r '.webhook.name'`
+  authname=`echo $JSON | "$JQ" -r '.event.authorizedUsername'`
+  otype=`echo $JSON | "$JQ" -r '.event.objectTypeName'`
+  oname=`echo $JSON | "$JQ" -r '.event.objectName'`
+  oid=`echo $JSON | "$JQ" -r '.event.objectID'`
+  optype=`echo $JSON | "$JQ" -r '.event.restAPIOperationType'`
+
+# otherwise, hacky bash parsing.
+else
+
+  # use a comma as the field separator for the for-loop
+  IFS=','
+
+  # loop thru comma-separated chunks
+  for chunk in $JSON ; do
+    hookre='"name": "(.+)"'
+    [[ $chunk =~ $hookre ]] && hookname="${BASH_REMATCH[1]}"
+    authunamere='"authorizedUsername": "(.+)"'
+    [[ $chunk =~ $authunamere ]] && authname="${BASH_REMATCH[1]}"
+    otypere='"objectTypeName": "(.+)"'
+    [[ $chunk =~ $otypere ]] && otype="${BASH_REMATCH[1]}"
+    onamere='"objectName": "(.+)"'
+    [[ $chunk =~ $onamere ]] && oname="${BASH_REMATCH[1]}"
+    oidre='"objectID": (.+)'
+    [[ $chunk =~ $oidre ]] && oid="${BASH_REMATCH[1]}"
+    optypere='"restAPIOperationType": "(.+)"'
+    [[ $chunk =~ $optypere ]] && optype="${BASH_REMATCH[1]}"
+  done
+
+fi # if [ -x "$JQ" ] ; then
+
+# make an 'action' out of the operation type
+# or exit if we don't know or don't care.
+case $optype in
+  GET) exit 0 ;;
+  PUT) action=create ;;
+  POST) action=update ;;
+  DELETE) action=delete ;;
+  *) exit 15 ;;
+esac
+
+# output
+echo "The JSS WebHook named '${hookname}' was just triggered.
+It indicates that Casper user '${authname}' just used the JSS API to ${action}
+the JSS ${otype}named '${oname}' (id ${oid})
+"

data/lib/jss/webhooks/data/sample_handlers/RestAPIOperation.rb

@@ -0,0 +1,44 @@
+### Copyright 2016 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.
+###
+###
+
+JSSWebHooks.event_handler do |event|
+  eobject = event.event_object
+  whook = event.webhook
+
+  REPORT_ACTIONS = {
+    'PUT' => 'update',
+    'POST' => 'create',
+    'DELETE' => 'delete'
+  }.freeze unless defined? REPORT_ACTIONS
+
+  action = REPORT_ACTIONS[eobject.restAPIOperationType]
+
+  return nil unless action
+
+  puts <<-ENDMSG
+The JSS WebHook named '#{whook.name}' was just triggered.
+It indicates that Casper user '#{eobject.authorizedUsername}' just used the JSS API to #{action}
+the JSS #{eobject.objectTypeName} named '#{eobject.objectName}' (id #{eobject.objectID})
+ENDMSG
+end

data/lib/jss/webhooks/data/sample_jsons/ComputerAdded.json

@@ -0,0 +1,27 @@
+{
+  "webhook": {
+    "id": 1,
+    "name": "ComputerAdded Webhook",
+    "webhookEvent": "ComputerAdded"
+  },
+  "event": {
+    "udid": "99848AF0-xxxx-XXXX-xxxx-B79B9F65D7F8",
+    "deviceName": "wanderer",
+    "model": "MacBookPro10,1",
+    "macAddress": "yy:E0:yy:16:yy:E9",
+    "alternateMacAddress": "32:xx:1A:xx:xx:60",
+    "serialNumber": "VM87S764H831",
+    "osVersion": "10.15.2",
+    "osBuild": "48673",
+    "userDirectoryID": "-1",
+    "username": "username",
+    "realName": "User Name",
+    "emailAddress": "user@school.edu",
+    "phone": "x3369",
+    "position": "Apple Peeler",
+    "department": "MacBack",
+    "building": "Soho",
+    "room": "s167",
+    "jssID": 1322
+  }
+}

data/lib/jss/webhooks/data/sample_jsons/ComputerCheckIn.json

@@ -0,0 +1,27 @@
+{
+  "webhook": {
+    "id": 2,
+    "name": "ComputerCheckin Webhook",
+    "webhookEvent": "ComputerCheckin"
+  },
+  "event": {
+    "udid": "99848AF0-xxxx-XXXX-xxxx-B79B9F65D7F8",
+    "deviceName": "wanderer",
+    "model": "MacBookPro10,1",
+    "macAddress": "yy:E0:yy:16:yy:E9",
+    "alternateMacAddress": "32:xx:1A:xx:xx:60",
+    "serialNumber": "VM87S764H831",
+    "osVersion": "10.15.2",
+    "osBuild": "48673",
+    "userDirectoryID": "-1",
+    "username": "username",
+    "realName": "User Name",
+    "emailAddress": "user@school.edu",
+    "phone": "x3369",
+    "position": "Apple Peeler",
+    "department": "MacBack",
+    "building": "Soho",
+    "room": "s167",
+    "jssID": 1322
+  }
+}

data/lib/jss/webhooks/data/sample_jsons/ComputerInventoryCompleted.json

@@ -0,0 +1,27 @@
+{
+  "webhook": {
+    "id": 3,
+    "name": "ComputerInventoryCompleted Webhook",
+    "webhookEvent": "ComputerInventoryCompleted"
+  },
+  "event": {
+    "udid": "99848AF0-xxxx-XXXX-xxxx-B79B9F65D7F8",
+    "deviceName": "wanderer",
+    "model": "MacBookPro10,1",
+    "macAddress": "yy:E0:yy:16:yy:E9",
+    "alternateMacAddress": "32:xx:1A:xx:xx:60",
+    "serialNumber": "VM87S764H831",
+    "osVersion": "10.15.2",
+    "osBuild": "48673",
+    "userDirectoryID": "-1",
+    "username": "username",
+    "realName": "User Name",
+    "emailAddress": "user@school.edu",
+    "phone": "x3369",
+    "position": "Apple Peeler",
+    "department": "MacBack",
+    "building": "Soho",
+    "room": "s167",
+    "jssID": 1322
+  }
+}

data/lib/jss/webhooks/data/sample_jsons/ComputerPolicyFinished.json

@@ -0,0 +1,27 @@
+{
+  "webhook": {
+    "id": 4,
+    "name": "ComputerPolicyFinished Webhook",
+    "webhookEvent": "ComputerPolicyFinished"
+  },
+  "event": {
+    "udid": "99848AF0-xxxx-XXXX-xxxx-B79B9F65D7F8",
+    "deviceName": "wanderer",
+    "model": "MacBookPro10,1",
+    "macAddress": "yy:E0:yy:16:yy:E9",
+    "alternateMacAddress": "32:xx:1A:xx:xx:60",
+    "serialNumber": "VM87S764H831",
+    "osVersion": "10.15.2",
+    "osBuild": "48673",
+    "userDirectoryID": "-1",
+    "username": "username",
+    "realName": "User Name",
+    "emailAddress": "user@school.edu",
+    "phone": "x3369",
+    "position": "Apple Peeler",
+    "department": "MacBack",
+    "building": "Soho",
+    "room": "s167",
+    "jssID": 1322
+  }
+}