chook 1.0.1.b2 → 1.1.5

data/bin/chook-server

@@ -1,5 +1,7 @@
 #!/usr/bin/ruby
 
+Process.setproctitle('chook')
+
 ### Copyright 2017 Pixar
 
 ###
@@ -24,5 +26,33 @@
 ###    language governing permissions and limitations under the Apache License.
 ###
 ###
+
+require 'getoptlong'
+
+# The CLI options for GetoptLong
+OPTS = GetoptLong.new(
+  ['--log', '-l',  GetoptLong::REQUIRED_ARGUMENT],
+  ['--dev', '-d',  GetoptLong::NO_ARGUMENT]
+)
+
+env = :production
+log_level = nil
+
+OPTS.each do |opt, arg|
+  case opt
+  when '--log'
+    log_level = arg
+  when '--dev'
+    env = :development
+  end # case
+end # opts.each
+
+ENV['APP_ENV'] = env.to_s
+
 require 'chook/server'
-Chook::Server.run!
+begin
+  Chook::Server.run! log_level: log_level
+rescue => e
+  Chook.logger.fatal e.to_s
+  e.backtrace.each { |line| Chook.logger.fatal "..#{line}" }
+end

data/data/chook.conf.example

@@ -0,0 +1,183 @@
+#################
+# This sample config file uses default settings.
+#
+# Each setting is defined on one line like so:
+#
+#     key: value
+#
+# Values may have spaces.
+#
+# Blank lines and those starting with # are ignored.
+
+#################
+# The port used by the server.
+# Default: 443 when use_ssl is true, 80 otherwise
+#
+port: 80
+
+#################
+# By default incoming webhooks are handled in parallel
+# If you have problems (e.g. a handler isn't thread-safe) try setting this
+# to false and hooks will be handled one at a time, in the order received.
+# Default: true
+#
+concurrency: true
+
+#################
+# The directory holding the internal and external handlers.
+# Their filenames must start with a known webhook name, and
+# their executability determines internal (not executable)
+# versus external (executable). See README.md for details.
+# Default: /Library/Application Support/Chook
+#
+handler_dir: /Library/Application Support/Chook
+
+#################
+# Should the server use SSL (https)? Ignored unless the engine is 'thin'
+# Default: false
+#
+use_ssl: false
+
+#################
+# When using SSL, the path to the SSL certificate to use, in PEM format
+# Required if use_ssl == true and engine == thin
+# Default: none
+#
+ssl_cert_path:
+
+#################
+# When using SSL, the path to the private key for the SSL certificate, in PEM format
+# Required if use_ssl == true and engine == thin
+# Default: none
+#
+ssl_private_key_path:
+
+#################
+# The path to the file used for chook server logging
+# Default: /var/log/chook-server.log
+#
+log_file: /var/log/chook-server.log
+
+#################
+# The detail level for the log. One of:
+# fatal (only fatal errors logged), error, warn, info, or debug (everything logged)
+# Default: info
+#
+log_level: info
+
+#################
+# How many old log files to keep when rotating?
+# Set to 0, or don't set at all, to disable auto-rotating
+# of log files.
+# Default: 10
+#
+logs_to_keep: 10
+
+#################
+# The log file rotates automatically when it reaches this size in megabytes.
+# Default: 10
+#
+log_max_megs: 10
+
+#################
+# Any value here will turn on 'HTTP Basic Authentication' for webhooks,
+# and this will be the username required for a Jamf Pro server to send
+# webhooks to the Chook server.
+#
+# Leaving this empty will allow receiving of webooks with no authentication
+#
+# Default: none
+#
+webhooks_user:
+
+#################
+# When 'HTTP Basic Authentication' is enabled by setting webhooks_user, this
+# tells chook how to learn the password for that user:
+#
+# - If its a path to a file, the file contains the password and nothing else.
+#   The file must be owned by the user running the chook server, and must have
+#   mode 0600.
+#
+# - If it ends with a pipe character (|), everything execpt the pipe is considered
+#   to be a shell command, executable by the user running the chook server.
+#   The standard-output of the command will be the password.
+#
+# Default: none
+#
+webhooks_user_pw:
+
+#################
+# Any value here will require authentication to view the admin web page.
+#
+# Leaving this empty will allow anyone to see the admin web page.
+#
+# If the value here is 'use_jamf' then anyone can log in with their
+# Jamf Pro credentials, and the admin_pw setting is ignored
+# (see the jamf_* settings below)
+#
+# If the value is anything else, it is the username required to
+# log in to the admin web page.
+#
+# Default: none
+#
+admin_user:
+
+#################
+# When admin page authentication is enabled by setting admin_user, this
+# tells chook how to learn the password for that user:
+#
+# - if the admin_user is 'use_jamf' then this is ignored, see the jamf_* settings below
+#
+# - If its a path to a file, the file contains the password and nothing else.
+#   The file must be owned by the user running the chook server, and must have
+#   mode 0600.
+#
+# - If it ends with a pipe character (|), everything execpt the pipe is considered
+#   to be a shell command, executable by the user running the chook server.
+#   The standard-output of the command will be the password.
+#
+# Default: none
+#
+admin_pw:
+
+#################
+# When admin page authentication is enabled by setting admin_user,
+# this is how many seconds before the browser session expires and the
+# admin must log in again.
+#
+# Default: 86400 (24 hours)
+#
+admin_session_expires: 86400
+
+#################
+# When the admin_user is 'use_jamf', this is the hostname of the
+# Jamf Pro server to use for authentication
+#
+# Default: none, but /etc/ruby-jss.conf will be honored
+#
+jamf_server:
+
+#################
+# When the admin_user is 'use_jamf', this is the port of the
+# Jamf Pro server to use for Authentication
+#
+# Default: none, but /etc/ruby-jss.conf will be honored
+#
+jamf_port:
+
+#################
+# When the admin_user is 'use_jamf', should SSL be used when
+# connection to the jamf_server? true or false
+#
+# Default: none, but /etc/ruby-jss.conf will be honored
+#
+jamf_use_ssl:
+
+#################
+# When the admin_user is 'use_jamf', and jamf_use_ssl is true,
+# should SSL certificates from the jamf server be
+# validated?
+#
+# Default: none, but /etc/ruby-jss.conf will be honored
+#
+jamf_verify_cert:

data/data/com.pixar.chook-server.plist

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+        <key>Label</key>
+        <string>com.pixar.chook-server</string>
+        <key>StandardOutPath</key>
+        <string>/var/log/chook-server.log</string>
+        <key>StandardErrorPath</key>
+        <string>/var/log/chook-server.log</string>
+        <key>ProgramArguments</key>
+        <array>
+                <string>/usr/local/pixar/bin/chook-server</string>
+        </array>
+        <key>RunAtLoad</key>
+        <true/>
+        <key>KeepAlive</key>
+        <true/>
+</dict>
+</plist>

data/data/sample_handlers/RestAPIOperation.rb

@@ -23,23 +23,23 @@
 ###
 ###
 
-Chook.event_handler do |event|
-  eobject = event.event_object
-  whook = event.webhook
+# this module is just a namespace so we don't conflict with other handlers
+module APIOpHandler
 
   REPORT_ACTIONS = {
     'PUT' => 'update',
     'POST' => 'create',
     'DELETE' => 'delete'
-  }.freeze unless defined? REPORT_ACTIONS
+  }.freeze
+
+end
+
+Chook.event_handler do |event|
+  event.logger.debug "This is a handler-level debug message for event #{event.object_id}"
 
-  action = REPORT_ACTIONS[eobject.restAPIOperationType]
+  action = APIOpHandler::REPORT_ACTIONS[event.subject.restAPIOperationType]
 
-  return nil unless action
+  break 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
+  event.logger.info "API #{action}: #{event.subject.objectTypeName} '#{event.subject.objectName}' (id #{event.subject.objectID})"
 end

data/data/sample_handlers/SmartGroupComputerMembershipChange.rb

@@ -23,11 +23,8 @@
 ###
 ###
 
-HANDLER_NAME = File.basename __FILE__
-CHANGELOG = '/tmp/smart-computer-group-changes.log'.freeze
-
 Chook.event_handler do |event|
-  now = Time.now.strftime '%Y-%m-%d %H:%M:%S'
-  msg = "#{now} #{HANDLER_NAME}: Smart Computer Group '#{event.event_object.name}' changed.\n"
-  open(CHANGELOG, 'a') { |file| file.write msg }
+  event.logger.debug "Computer Smart Group Changed: #{event.subject.name}"
+  event.logger.debug "  Additions: #{event.subject.groupAddedDevicesIds.join ', '}"
+  event.logger.debug "  Removals: #{event.subject.groupRemovedDevicesIds.join ', '}"
 end

data/data/sample_jsons/SmartGroupComputerMembershipChange.json

@@ -8,6 +8,8 @@
     "name": "OddComputers",
     "smartGroup": true,
     "jssid": 95,
-    "computer": true
+    "computer": true,
+    "groupAddedDevicesIds": [1,2,3,4,5],
+    "groupRemovedDevicesIds": [6,7,8,9,10]
   }
 }

data/data/sample_jsons/SmartGroupMobileDeviceMembershipChange.json

@@ -8,6 +8,8 @@
     "name": "OddMobileDevs",
     "smartGroup": true,
     "jssid": 99,
-    "computer": false
+    "computer": false,
+    "groupAddedDevicesIds": [1,2,3,4,5],
+    "groupRemovedDevicesIds": [6,7,8,9,10]
   }
 }

data/lib/chook/configuration.rb

@@ -35,16 +35,33 @@ module Chook
     # The location of the default config file
     DEFAULT_CONF_FILE = Pathname.new '/etc/chook.conf'
 
-    # The attribute keys we maintain, and the type they should be stored as
+    SAMPLE_CONF_FILE = Pathname.new(__FILE__).parent.parent.parent + 'data/chook.conf.example'
+
+    # The attribute keys we maintain, and how they should be converted to
+    # the value used by chook internally.
+    #
+    # For descriptions of the keys, see data/chook.conf.example
+    #
     CONF_KEYS = {
-      server_port: :to_i,
-      server_engine:  :to_sym,
-      handler_dir: nil,
+      port: :to_i,
+      concurrency: Chook::Procs::STRING_TO_BOOLEAN,
+      handler_dir: Chook::Procs::STRING_TO_PATHNAME,
       use_ssl: Chook::Procs::STRING_TO_BOOLEAN,
-      ssl_private_key_path: Chook::Procs::STRING_TO_PATHNAME,
-      ssl_private_key_pw_path: nil,
       ssl_cert_path: Chook::Procs::STRING_TO_PATHNAME,
-      ssl_cert_name: nil
+      ssl_private_key_path: Chook::Procs::STRING_TO_PATHNAME,
+      log_file: Chook::Procs::STRING_TO_PATHNAME,
+      log_level: Chook::Procs::STRING_TO_LOG_LEVEL,
+      log_max_megs:  :to_i,
+      logs_to_keep: :to_i,
+      webhooks_user: nil,
+      webhooks_user_pw: nil,
+      admin_user: nil,
+      admin_pw: nil,
+      admin_session_expires: :to_i,
+      jamf_server: nil,
+      jamf_port: :to_i,
+      jamf_use_ssl: Chook::Procs::STRING_TO_BOOLEAN,
+      jamf_verify_cert: Chook::Procs::STRING_TO_BOOLEAN
     }.freeze
 
     # Class Variables
@@ -193,6 +210,8 @@ module Chook
   end # class Configuration
 
   # The single instance of Configuration
-  CONFIG = Chook::Configuration.instance
+  def self.config
+    Chook::Configuration.instance
+  end
 
 end # module

data/lib/chook/event.rb

@@ -65,8 +65,9 @@ module Chook
       'ComputerAdded' => Chook::Subject::COMPUTER,
       'ComputerCheckIn' => Chook::Subject::COMPUTER,
       'ComputerInventoryCompleted' => Chook::Subject::COMPUTER,
-      'ComputerPolicyFinished' => Chook::Subject::COMPUTER,
+      'ComputerPolicyFinished' => Chook::Subject::POLICY_FINISHED,
       'ComputerPushCapabilityChanged' => Chook::Subject::COMPUTER,
+      'DeviceAddedToDEP' => Chook::Subject::DEP_DEVICE,
       'JSSShutdown' => Chook::Subject::JAMF_SOFTWARE_SERVER,
       'JSSStartup' => Chook::Subject::JAMF_SOFTWARE_SERVER,
       'MobileDeviceCheckIn' => Chook::Subject::MOBILE_DEVICE,
@@ -94,6 +95,9 @@ module Chook
 
     #### Attrbutes common to all events
 
+    # @return [String] A unique identifier for this chook event
+    attr_reader :id
+
     # @return [Integer] The webhook id in the JSS that caused this event
     attr_reader :webhook_id
 
@@ -128,6 +132,7 @@ module Chook
     # event. Any not provided will be nil.
     #
     def initialize(**args)
+      @id = "#{Time.now.to_i}-#{SecureRandom.urlsafe_base64 8}"
       if args[:raw_json]
         @raw_json = args[:raw_json]
         @parsed_json = JSON.parse @raw_json, symbolize_names: true

data/lib/chook/event/handled_event.rb

@@ -25,7 +25,6 @@
 
 require 'chook/event/handled_event/handlers'
 
-#
 module Chook
 
   # Load sample JSON files, one per event type
@@ -62,9 +61,6 @@ module Chook
 
     #### Class Methods
 
-    # Given some raw_json from the jss, create and return the correct
-    # HandledEvent subclass
-
     # For each event type in Chook::Event::EVENTS
     # generate a class for it, set its SUBJECT_CLASS constant
     # and add it to the HandledEvents module.
@@ -99,6 +95,7 @@ module Chook
     # @return [JSSWebHooks::Event subclass] the Event subclass matching the event
     #
     def self.parse_event(raw_event_json)
+      return nil if raw_event_json.to_s.empty?
       event_json = JSON.parse(raw_event_json, symbolize_names: true)
       event_name = event_json[:webhook][:webhookEvent]
       Chook::HandledEvents.const_get(event_name).new raw_event_json
@@ -121,13 +118,21 @@ module Chook
       super raw_json: raw_event_json
     end # init
 
+    def event_class_name
+      self.class.const_get(Chook::Event::EVENT_NAME_CONST)
+    end
+
+    # Run all the general handlers for this event class
+    #
     def handle
-      handlers = Handlers.handlers[self.class.const_get(Chook::Event::EVENT_NAME_CONST)]
+      handlers = Handlers.handlers[event_class_name]
+      return "No handlers loaded for #{event_class_name} events" unless handlers.is_a? Array
+
       handlers.each do |handler|
         case handler
         when Pathname
           pipe_to_executable handler
-        when Proc
+        when Object
           handle_with_proc handler
         end # case
       end # @handlers.each do |handler|
@@ -135,18 +140,40 @@ module Chook
       # the handle method should return a string,
       # which is the body of the HTTP result for
       # POSTing the event
-      "Processed by #{handlers.count} handlers\n"
+      "Processed by #{handlers.count} general handlers"
     end # def handle
 
-    # TODO: Add something here that cleans up old threads and forks
+    # run a single handler specified by filename
+    #
+    def handle_by_name(handler_to_run)
+      handler = Handlers.named_handlers[handler_to_run]
+      return "No named handler '#{handler_to_run}'" unless handler
+
+      if handler.is_a? Pathname
+        pipe_to_executable handler
+      else
+        handle_with_proc handler
+      end # if
+      "Processed by named handler '#{handler_to_run}'"
+    end
+
+    # TODO: these threads will die midstream when the server stops.
+    # Find a way to .join them or otherwise clean them up.
+
     def pipe_to_executable(handler)
+      logger.debug "EXTERNAL: Sending JSON to stdin of '#{handler.basename}'"
       _thread = Thread.new do
         IO.popen([handler.to_s], 'w') { |h| h.puts @raw_json }
       end
     end
 
     def handle_with_proc(handler)
-      _thread = Thread.new { handler.call self }
+      logger.debug "INTERNAL: Running Handler defined in #{handler.handler_file}"
+      _thread = Thread.new { handler.handle self }
+    end
+
+    def logger
+      @logger ||= Chook::HandledEventLogger.new self
     end
 
   end # class HandledEvent