chook 1.0.1.b2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e92976b3bdaf1f68f8b9f835d60801aaae016288
-  data.tar.gz: beef1b38609f5e0dd9e88f7426564e243a87cfe7
+SHA256:
+  metadata.gz: 05defee2dbf9d0d71b7657d491ac8eebf3c87529d1de1077365a3a2e82cc48fe
+  data.tar.gz: 845d410b10290129a233915600cf57ca7c89a855b2d504cb5593da885e5eef8c
 SHA512:
-  metadata.gz: 03aafa3c761df70e9ac55fb22262ef795148b0cde019c3e4ea11c9709618710bb29785de10f26c18640eb6ea2cbb894949a5474685311fe74e0412987fb5389e
-  data.tar.gz: 5b812b039b4298e8d662d778dd0ab9a5253f2a13ef29518c27869d169ce3228570036d9a64d85cfd9e0e5bee9d9ae96cb5a0f549d9377c02e0c30ee88ff81db6
+  metadata.gz: 153586d027c5c81d7ec5d0f0678d0c520879db7cef84cf3454134a4f7439601faa12463a3d227e7dd1ce6b561c18d4c95be781f39b2d0d787be742d5ea0b44fa
+  data.tar.gz: 10e36a024704ab54f38bfbfeec7f91da08a294c9a3d0c1b3c103d0aa924719045197a4f62e49ef4e4add8397004fc8578186d3c50ec03d53501839ac716384a5

data/CHANGES.md

@@ -0,0 +1,21 @@
+# Chook Change Log
+
+## v 1.1.0,  2018-10-15
+
+For details about the new features, please see README.md
+
+- Now requires 'thin' as the server engine.
+
+
+- Supports SSL and HTTP Basic Authentication
+
+
+- Server logging is now a thing, with access to logging from both internal and external handlers
+
+
+- A simple admin interface is available by pointing your browser at the chook server
+
+
+- Internal handlers are now stored as anonymous objects rather than Procs, and the handler code block
+  is stored as an instance method on the object. This means that either 'break' or 'return' will work
+  to exit a handler.

data/README.md

@@ -1,9 +1,10 @@
 
 # Chook
 
-Documentation is a work in progress. Please get in touch for assistance. <3
+Documentation is a work in progress. Please [get in touch](mailto:chook@pixar.com) for assistance. <3
 
 - [Introduction](#introduction)
+- [Installing Chook](#installing-chook)
 - [The Framework](#the-framework)
   - [Event Handlers](#event-handlers)
     - [Internal Handlers](#internal-handlers)
@@ -11,7 +12,11 @@ Documentation is a work in progress. Please get in touch for assistance. <3
   - [Putting It Together](#putting-it-together)
   - [Events and Subjects](#events-and-subjects)
 - [The Server](#the-server)
-- [Installing Chook](#installing-chook)
+  - [Server Configuration](#server-configuration)
+  - [SSL](#ssl)
+  - [Logging](#logging)
+  - [Admin Interface](#admin-interface)
+  - [Pointing Jamf Pro at your Chook server](#pointing-jamf-pro-at-your-chook-server)
 - [TODOs](#todos)
 
 
@@ -19,36 +24,46 @@ Documentation is a work in progress. Please get in touch for assistance. <3
 
 Chook is a Ruby module that implements a framework for working with webhook events
 sent by the JSS, the core of [Jamf Pro](https://www.jamf.com/products/jamf-pro/),
-a management tool for Apple devices.
+a management tool for Apple devices!
 
 Chook also provides a simple, sinatra-based HTTP server for handling those Events,
 and classes for sending simulated TestEvents to a webhook handling server.
 
-** You do not need to be a Ruby developer to use this framework! **
+**You do not need to be a Ruby developer to use Chook!**
 
 The webhook handling server that comes with Chook can use "Event Handlers" written in
 any language. See _Event Handlers_ and _The Server_ below for more information.
 
-Chook is still in development. While many of the basics work,
-there is much to be done before it can be considered complete.
-
 Although Chook integrates well with [ruby-jss](http://pixaranimationstudios.github.io/ruby-jss/index.html),
 it's a separate tool, and the two projects aren't dependent. However, ruby-jss
 does become a requirement when using sampling features to generate TestEvents.
 
 For more detail about the JSS webhooks API and the JSON data it passes, please see
-[Bryson Tyrrell's documentation.](https://unofficial-jss-api-docs.atlassian.net/wiki/display/JRA/Webhooks+API)
+[JAMF's developer reference.](http://developer.jamf.com/webhooks)
 
 **Note:** When creating webhooks from your JSS to be handled by the framework, you must
 specify JSON in the "Content Type" section. This framework does not support XML and
-will only generate Events in JSON format.
+will only generate Test Events in JSON format.
+
+
+## Installing Chook
+
+`gem install chook -n /usr/local/bin`
+
+It will also install "sinatra" and "thin", and their dependencies.
+
+Then fire up `irb` and `require 'chook'` to start playing around.
+
+OR
+
+run `/usr/local/bin/chook-server` and point some JSS webhooks at `http://my.computer.org/handle_webhook_event`
 
 ## The Framework
 
 The Chook framework abstracts webhook Events and their components as Ruby
 classes. When the JSON payload of a JSS webhook POST request is passed into the
-`Chook::Event.parse_event` method, an instance of the appropriate subclass
-of `Chook::Event` is returned, for example
+`Chook::Event.parse_event` method, an instance of the appropriate subclass of
+`Chook::Event` is returned, for example
 `Chook::Event::ComputerInventoryCompletedEvent`
 
 Each Event instance contains these important attributes:
@@ -104,7 +119,7 @@ All of these file names are valid handlers for ComputerAdded events:
 - COMPUTERAdded_notify_team
 - Computeradded-update-ldap
 
-There are two kinds of handlers:
+There are two kinds of handlers, distinguished by their file-executability.
 
 #### Internal Handlers
 
@@ -121,16 +136,70 @@ a handler for a Chook::ComputerAddedEvent
 Chook.event_handler do |event|
   cname = event.subject.deviceName
   uname = event.subject.realName
-  puts "Computer '#{cname}' was just added to the JSS for user #{uname}."
+  event.logger.info "Computer '#{cname}' was just added to the JSS for user #{uname}."
 end
 ```
 
-In this example, the code block takes one parameter, which it expects to be
-a Chook::ComputerAddedEvent instance, and uses it in the variable "event."
+The code block takes one parameter, which will be a Chook::ComputerAddedEvent instance,
+and in this example stores it in the variable "event."
+
 It then extracts the "deviceName" and "realName" values from the subject
-contained in the event, and uses them to send a message to stdout.
+contained in the event, and uses them to log a message in the chook log.
+
+**NameSpacing**
+
+Be careful when writing internal handlers - they all run in the same Ruby process!
+
+Not only do they have to be thread-safe, but be wary of cluttering the default
+namespace with constants that might overwrite each other.
+
+A good, very ruby-like, practice is to put the guts of your code into a Module or a Class
+and use that from inside the handler definition. Here's an example using a Class:
+
+```ruby
+require 'slack-em' # ficticious Slack-chat gem, for demonstation purposes
+
+class ComputerAdder
 
-Internal handlers **must not** be executable files. Executability is how the
+  SLACK_CHANNEL = '#mac-notifications'
+
+  def initialize(event)
+    @event = event
+    @cname = @event.subject.deviceName
+  end
+
+  def run
+    @event.logger.info "Adder Starting for computer #{@cname}"
+    notify_admins
+    @event.logger.info "Adder Finished for computer #{@cname}"
+  end
+
+  def notify_admins
+    SlackEm.send message: "Computer '#{@cname}' was just added to the JSS for user #{@event.subject.realName}.", channel: SLACK_CHANNEL
+    @event.logger.debug "Admins notified about computer #{@cname}"
+  end
+
+end
+
+Chook.event_handler do |event|
+  ComputerAddeder.new(event).run
+end
+```
+
+Here, the handler file defines a 'ComputerAdder' class that does all the work.
+The handler block merely creates an instance of ComputerAdder with the event,
+and tells the ComputerAdder instance to run. The instance's run method can
+then perform any steps desired.
+
+In this example, the SLACK_CHANNEL constant is defined inside the ComputerAdder class.
+Access to it from inside the class is done using just the constant itself. If you
+need to access that particular value from outside of the class, you can
+use ComputerAdder::SLACK_CHANNEL.
+
+This way, similar handlers can have their own SLACK_CHANNEL constants and
+there won't be any interference.
+
+NOTE: Internal handlers **must not** be executable files. Executability is how the
 framework determines if a handler is internal or external.
 
 #### External Handlers
@@ -142,7 +211,7 @@ desired. In this case the Chook framework is merely a conduit for passing
 the Posted JSON to the executable program.
 
 Here's a simple example using bash and [jq](https://stedolan.github.io/jq/) to
-do the same as the ruby example above:
+do the same as the first ruby example above:
 
 ```bash
 #!/bin/bash
@@ -235,15 +304,15 @@ the `Chook::Subjects` module.
 
 ## The Server
 
-Chook comes with a simple HTTP server that uses the Chook framework
+Chook comes with a simple HTTP(S) server that uses the Chook framework
 to handle all incoming webhook POST requests from the JSS via a single URL.
 
-To use it you'll need the [sinatra](http://www.sinatrarb.com/)
-ruby gem (`gem install sinatra`).
+To use it you'll need the [sinatra](http://www.sinatrarb.com/) web framework
+and the [thin](http://code.macournoyer.com/thin/) web server.
+Both will be installed automatically when you install chook as mentioned below.
 
-After that, just run the `chook-server` command located in the bin
-directory for chook and then point your webhooks at:
-http://my_hostname/handle_webhook_event
+After that, just run the `chook-server` command located in the bin directory
+for chook and then point your webhooks at: http://my_hostname/handle_webhook_event
 
 It will then process all incoming webhook POST requests using whatever handlers
 you have installed.
@@ -251,25 +320,163 @@ you have installed.
 To automate it on a dedicated machine, just make a LaunchDaemon plist to run
 that command and keep it running.
 
-## Installing Chook
+### Server Configuration
 
-`gem install chook -n /usr/local/bin`. It will also install "sinatra."
+The Chook server looks for a config file at `/etc/chook.conf`. If not found, default
+values are used. Full descriptions of the config values are provided in the sample
+config file at:
+/path/to/your/gem/folder/chook-<version>/data/chook.conf.example
 
-Then fire up `irb` and `require chook` to start playing around.
+Each config setting is on a single line thus: `key: value`. Blank lines and those starting with # are ignored.
 
-OR
+Here's a summary:
+
+ - port: The server port
+   - default = 80 or 443
+ - concurrency: Should events be processed simultaneously, or one-at-a time
+   - default = true
+ - handler_dir: The directory holding the andlers to load.
+   - default = /Library/Application Support/Chook
+ - use_ssl: Should the server use SSL (https)
+   - default = false
+ - ssl_cert_path: If SSL is used, the path to the server certificate
+   - no default
+ - ssl_private_key_path: If SSL is used, the path to the certificate key
+   - no default
+ - log_file: The path to the server log file
+   - default = /var/log/chook-server.log
+ - log_level: The severity level for log entries
+   - default = info
+ - logs_to_keep: How many old log files to keep when rotating
+   - default = 10
+ - log_max_megs: How big can a log file get before it's rotated.
+   - default = 10
+ - webhooks_user: The username for Basic Authentication
+   - no default, leave unset for no Authentication
+ - webhooks_user_pw: The file path, or command, to get the password for the webhooks_user.
+   - no default.
+
+See the sample config file for details about all of these settings.
+
+### SSL
+
+It is recommended to use SSL (https) if possible for security, although its beyond the scope
+of this document to go into a lot of detail about SSL and certificates.  That said, here
+are some pointers:
+
+- The certificate and key files should be in .pem format
+
+- Make sure you use a certificate that can be verified by the JSS.
+  - This might involved adding a CA to the JSS's Java Keystore.
+
+- If running on macOS, the 'thin' webserver and it's underlying 'eventmachine' gem may not
+  like the OS's openssl replacement 'libressl'.
+  - One solution is to use [homebrew](https://brew.sh/) to install openssl and then
+    install eventmachine using that openssl, something like this:
+
+    `brew install openssl ; brew link openssl --force ; gem install eventmachine -- --with-ssl-dir=/usr/local/`
+
+### Logging
+
+The Chook server logs activity into the file defined in the `log_file` config setting,
+`/var/log/chook-server.log` by default.
+
+It uses a standard ruby [Logger](http://ruby-doc.org/stdlib-2.3.3/libdoc/logger/rdoc/index.html)
+instance, which provides 5 severity levels: fatal (lowest), error, warn, info, and debug (highest).
+
+The `log_level` config setting defines the level when the server starts up, and log
+messages of that level or lower will be written to the log.
+
+The logger is generally available via `Chook.logger`. If you want to log an exeption with its backtrace, you can use `Chook.log_exception exception` to get the Exception class, message, and backtrace in the log.
+
+However, for logging from inside handlers, read on...
+
+#### Logging from handlers
+
+**Internal handlers**
+
+To write to the log file from within an internal handler, use the `#logger` method of the `event` object
+inside the handler block, like so:
+
+```ruby
+Chook.event_handler do |event|
+  event.logger.debug "This line appears in the log if the level is debug"
+  event.logger.info "This line appears in the log if the level is info or debug"
+  event.logger.error "This line appears in the log if the level is error, warn, info, or debug"
+end
+```
+
+If you want to log an exeption with its backtrace, you can pass the entire exception to the
+event loggers  'log_exception' method:  `event.logger.log_exception exception`
+
+Log entries written through event objects are preceded with 'Event *event_id*'  where *event_id* is
+an internal ID number for the specific even that wrote the entry.
+
+
+**External handlers**
+
+External Handlers can use a URL to make log entries by POSTing to `https://my.chookserver/log`
+
+The request body must be a JSON object wth 2 keys 'level' and 'message' where both values are strings.
+The 'level' must be one of the levels mentioned above, and the message is a single line of
+text.
+
+If your chook server is using Basic Authentication, it must be provided.
+
+Here's an example with curl, split to multi-line for clarity:
+
+```
+curl -H "Content-Type: application/json" \
+  -X POST \
+  --data '{"level":"debug", "message":"It Worked"}' \
+  https://user:passwd@chookserver.myorg.org/log
+```
+
+Messages logged via this url show up in the log preceded by 'ExternalEntry: '
+
+Any info needed to connect a log entry to a specific event must be included in
+your log message.
+
+### Admin Interface
+
+If you point your web browser at your Chook server, you'll see a simple admin interface.
+If your server uses Basic Authentication, you'll need to provide the name and password.
+
+The first section provides a live-stream of the server log file, and provides a way to
+change the server's log level on the fly. Note that this change affect the server itself
+not just the view in your browser. If you'd like to stop the stream temporarily (e.g. to
+select and copy some text from it), just pause and unpause with the checkbox.
+
+The second section lets you see which handlers are currently loaded, and if they are
+internal or external. There's also a button to reload the handlers from the handler
+directory without restarting the server - useful when you add, delete, or modify them.
+
+The final section just shows your current /etc/chook.conf file, or if there is none,
+the sample config file is shown, since it shows the default values.
+
+The admin page cannot be used to edit or upload handlers or change the config. For security
+reasons, you must do that on the server itself though normal administrative methods.
+
+### Pointing Jamf Pro at your Chook server
+
+Once your server is up and running, you can create webhooks in your Jamf Pro interface.
 
-run `/usr/local/bin/chook-server` and point some JSS webhooks at that machine.
+1. Navigate to Settings => Global Management => Webhooks
+2. Click "New"
+3. Give your webhook a display name
+4. Enter the URL for your Chook server, ending with 'handle_webhook_event', e.g:
+  - `http://my.chookserver.edu/handle_webhook_event`
+  - `https://my.chookserver.edu:8443/handle_webhook_event`
+5. If you use Basic Authentication, enter the name and password
+6. The default timeouts should be OK, but raise them a bit if you're experiencing errors.
+7. Set the content type to JSON
+8. Select the event that triggers the webook
+9. Click "Enabled" at the top.
+10. Click "Save"
 
+Watch the Chook log, with the level at info or debug, to see events come in.
 
 ## TODOs
 
-- Add SSL support to the server
-- Improved thread management for handlers
-- Logging and Debug options
-- Handler reloading for individual, or all, Event subclasses
 - Better YARD docs
-- Better namespace protection for internal handlers
-- Improved configuration
 - Proper documentation beyond this README
-- I'm sure there's more to do...

data/bin/chook-server

@@ -24,5 +24,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,104 @@
+#################
+# 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' and this will be the username
+# required to make any connection to the Chook server.
+# Leaving this empty will allow any connection without 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: