lita-gsuite 0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 39fffd8c5976caaef1dd7c8b68a7562f95aa6f9b
+  data.tar.gz: 342a2b5efcf4f14b2f66a2083ebb201ee9c521dc
+SHA512:
+  metadata.gz: 6df288e9de29014dbae5c9523441cfbf4b9bde4d67850ce04ac627963d564830dd32cc06c71e88346baf88f295d8a6f2360954fbaa3b320a1928ab1be6bec1bf
+  data.tar.gz: 145eb15b7d0ed9e454cd5bbdab45ad5a4a25470805bb46455e7dee8c34d5706634e1fe2172735092ee06f688f6f71e08ef3db15976a68d318e7c2824e3cae150

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016 James Healy
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+# lita-gsuite
+
+A lita plugin for interacting with a GSuite account.
+
+By design, only read-only access is requested. This is intended to provide some visibility
+into the account, not provide administrative functions.
+
+This was written for a GSuite account with ~125 active users. It may not scale
+well to larger accounts, but feedback and optimisations are welcome.
+
+## Installation
+
+Add this gem to your lita installation by including the following line in your Gemfile:
+
+    gem "lita-gsuite", git: "http://github.com/yob/lita-gsuite.git"
+
+## Configuration
+
+Edit your lita\_config.rb to include the following lines lines. Some of the
+values are sensitive, so using ENV vars is recommended to keep the values out
+of version control.
+
+When an API call to google is required, we want to make it with tokens that
+are tied to the specific user that requested data. To do so, we use Google's
+OAuth2 support.
+
+That requires an OAuth2 client ID and secret - see "Authentication" below for more
+details on how to generate these:
+
+    config.handlers.gsuite.oauth_client_id = ENV["GOOGLE_CLIENT_ID"]
+    config.handlers.gsuite.oauth_client_secret = ENV["GOOGLE_CLIENT_SECRET"]
+
+## Authentication
+
+The lita bot requires an OAuth client ID and secret before it can initiate
+the process to generate an OAuth2 token for each user.
+
+These can be created on the [Google Developers
+Console](https://console.developers.google.com/), and Google has [some
+documentation](https://developers.google.com/identity/protocols/OAuth2).
+
+You should be given the opportunity to view the new ID and secret. Be sure to copy them
+down, as they can't be retrieved again later.
+
+Once the handler is configured and running, each user that wants to interact with it
+will be prompted to complete an OAuth authorisation process before they can start. This
+generates an API token that's specific to them and will be used to make API calls on
+their behalf.
+
+## Enable Google API
+
+The GSuite API must be explicitly enabled for your account, and the new service account
+must be whitelisted before it can access any data.
+
+1. Sign in to https://admin.google.com
+2. Visit the Security tab, click "API reference" and "Enable API Access"
+
+## Chat commands
+
+### Administrators
+
+List users with super or delegated administrative privileges, and their two-factor
+auth status.
+
+    lita gsuite list-admins
+
+### Empty Groups
+
+List groups with no members.
+
+    lita gsuite empty-groups
+
+### Inactive Users
+
+List active users that haven't logged in for 8 weeks.  This may be helpful for
+identifying accounts that should be suspended or deleted.
+
+    lita gsuite suspension-candidates
+
+### Suspended Users
+
+List suspended users that haven't logged in for 26 weeks. This may be helpful
+for identifying accounts that have been suspended for a long time and may be
+candidates for deletion.
+
+    lita gsuite deletion-candidates
+
+### User with No Organisational Unit
+
+List users not assigned to an Organisational Unit.
+
+    lita gsuite no-ou
+
+### Two Factor Authentication
+
+Print key stats on Second Factor Authentication uptake.
+
+    lita gsuite two-factor-stats
+
+### Two Factor Authentication Disabled
+
+Print users within an Organisational Unit that don't have Second Factor Authentication enabled.
+
+    lita gsuite two-factor-off /OUPATH
+
+## Periodic Updates
+
+To help monitor the above reports automatically, it's possible to schedule them to be printed in
+a channel periodically.
+
+List the reports that will periodically print in the current channel:
+
+    lita gsuite schedule list
+
+List the reports that are available to print periodically:
+
+    lita gsuite schedule commands
+
+Schedule a weekly report in the current channel, specified in UTC time:
+
+    lita gsuite schedule add-weekly <day-of-the-week> HH:MM <report-name>
+    lita gsuite schedule add-weekly wednesday 01:00 list-admins
+    lita gsuite schedule add-weekly monday 13:45 no-ou
+
+Schedule a time-window report that will run regularly and print output when
+new data is available:
+
+    lita gsuite schedule add-window <report-name>
+    lita gsuite schedule add-window list-activities
+
+Delete a scheduled report from the current room. The ID can be find in the
+output of "schedule list":
+
+    lita gsuite schedule del <id>

data/lib/lita-gsuite.rb

@@ -0,0 +1,15 @@
+require "lita/commands/deletion_candidates"
+require "lita/commands/empty_groups"
+require "lita/commands/list_admins"
+require "lita/commands/list_activities"
+require "lita/commands/no_org_unit"
+require "lita/commands/suspension_candidates"
+require "lita/commands/two_factor_off"
+require "lita/commands/two_factor_stats"
+
+require "lita/weekly_schedule"
+require "lita/window_schedule"
+
+require "lita/gsuite_gateway"
+require "lita/gsuite"
+require "lita/redis_token_store"

data/lib/lita/commands/deletion_candidates.rb

@@ -0,0 +1,49 @@
+module Lita
+  module Commands
+
+    class DeletionCandidates
+      MAX_WEEKS_SUSPENDED = 26
+
+      def name
+        'deletion-candidates'
+      end
+
+      def run(robot, target, gateway, opts = {})
+        msg = build_msg(gateway)
+        robot.send_message(target, msg) if msg
+        robot.send_message(target, "No users found") if msg.nil? && opts[:negative_ack]
+      end
+
+      private
+
+      def build_msg(gateway)
+        users = long_term_suspended_users(gateway)
+        if users.any?
+          msg = "The following users are suspended, and have not logged in for #{MAX_WEEKS_SUSPENDED} weeks. "
+          msg += "If appropriate, consider deleting their accounts:\n"
+          msg += users.map { |user|
+            "- #{user.path}"
+          }.sort.join("\n")
+        end
+      end
+
+      def long_term_suspended_users(gateway)
+        timestamp = max_weeks_suspended_ago
+
+        gateway.users.select { |user|
+          user.suspended?
+        }.select { |user|
+          user.last_login_at < timestamp
+        }
+      end
+
+      def max_weeks_suspended_ago
+        (Time.now.utc - weeks_in_seconds(MAX_WEEKS_SUSPENDED)).to_datetime
+      end
+
+      def weeks_in_seconds(weeks)
+        60 * 60 * 24 * 7 * weeks.to_i
+      end
+    end
+  end
+end

data/lib/lita/commands/empty_groups.rb

@@ -0,0 +1,36 @@
+module Lita
+  module Commands
+
+    class EmptyGroups
+
+      def name
+        'empty-groups'
+      end
+
+      def run(robot, target, gateway, opts = {})
+        msg = build_msg(gateway)
+        robot.send_message(target, msg) if msg
+        robot.send_message(target, "No groups found") if msg.nil? && opts[:negative_ack]
+      end
+
+      private
+
+      def build_msg(gateway)
+        groups = empty_groups(gateway)
+
+        if groups.any?
+          msg = "The following groups have no members, which may result in undelivered email.\n"
+          msg += groups.map { |group|
+            "- #{group.email}"
+          }.join("\n")
+        end
+      end
+
+      def empty_groups(gateway)
+        gateway.groups.select { |group|
+          group.member_count == 0
+        }
+      end
+    end
+  end
+end

data/lib/lita/commands/list_activities.rb

@@ -0,0 +1,27 @@
+module Lita
+  module Commands
+
+    class ListActivities
+
+      def name
+        'list-activities'
+      end
+
+      def duration_minutes
+        10
+      end
+
+      def buffer_minutes
+        10
+      end
+
+      def run(robot, target, gateway, window_start, window_end)
+        activities = gateway.admin_activities(window_start, window_end)
+        activities.sort_by(&:time).map(&:to_msg).each_with_index do |message, index|
+          robot.send_message(target, message)
+          sleep(1) # TODO ergh. required to stop slack disconnecting us for high sending rates
+        end
+      end
+    end
+  end
+end

data/lib/lita/commands/list_admins.rb

@@ -0,0 +1,39 @@
+module Lita
+  module Commands
+
+    class ListAdmins
+
+      def name
+        'list-admins'
+      end
+
+      def run(robot, target, gateway, opts = {})
+        msg = build_msg(gateway)
+        robot.send_message(target, msg) if msg
+        robot.send_message(target, "No admins found") if msg.nil? && opts[:negative_ack]
+      end
+
+      private
+
+      def build_msg(gateway)
+        users = all_admins(gateway)
+
+        if users.any?
+          msg = "The following accounts have administrative privileges:\n"
+          msg += users.map { |user|
+            "- #{user.ou_path}/#{user.email} (2fa enabled: #{tfa?(user)})"
+          }.join("\n")
+        end
+      end
+
+      def all_admins(gateway)
+        (gateway.delegated_admins + gateway.super_admins).uniq.sort_by(&:path)
+      end
+
+      def tfa?(user)
+        user.two_factor_enabled? ? "Y" : "N"
+      end
+    end
+
+  end
+end

data/lib/lita/commands/no_org_unit.rb

@@ -0,0 +1,38 @@
+module Lita
+  module Commands
+    class NoOrgUnit
+
+      def name
+        'no-org-unit'
+      end
+
+      def run(robot, target, gateway, opts = {})
+        msg = build_msg(gateway)
+        robot.send_message(target, msg) if msg
+        robot.send_message(target, "No users are missing an org unit") if msg.nil? && opts[:negative_ack]
+      end
+
+      private
+
+      def build_msg(gateway)
+        users = no_org_unit_users(gateway)
+
+        if users.any?
+          msg = "The following users are not assigned to an organisational unit:\n"
+          msg += users.sort_by(&:path).map { |user|
+            "- #{user.email}"
+          }.join("\n")
+        end
+      end
+
+      def no_org_unit_users(gateway)
+        gateway.users.reject { |user|
+          user.suspended?
+        }.select { |user|
+          user.ou_path == "/"
+        }
+      end
+
+    end
+  end
+end

data/lib/lita/commands/suspension_candidates.rb

@@ -0,0 +1,49 @@
+module Lita
+  module Commands
+    class SuspensionCandidates
+      MAX_WEEKS_WITHOUT_LOGIN = 8
+
+      def name
+        'suspension-candidates'
+      end
+
+      def run(robot, target, gateway, opts = {})
+        msg = build_msg(gateway)
+        robot.send_message(target, msg) if msg
+        robot.send_message(target, "No users found") if msg.nil? && opts[:negative_ack]
+      end
+
+      private
+
+      def build_msg(gateway)
+        users = active_users_with_no_recent_login(gateway)
+
+        if users.any?
+          msg = "The following users have active accounts, but have not logged in for #{MAX_WEEKS_WITHOUT_LOGIN} weeks. "
+          msg += "If appropriate, consider suspending or deleting their accounts:\n"
+          msg += users.map { |user|
+            "- #{user.path}"
+          }.sort.join("\n")
+        end
+      end
+
+      def active_users_with_no_recent_login(gateway)
+        timestamp = max_weeks_without_login_ago
+
+        gateway.users.reject { |user|
+          user.suspended?
+        }.select { |user|
+          user.last_login_at < timestamp && user.created_at < timestamp
+        }
+      end
+
+      def max_weeks_without_login_ago
+        (Time.now.utc - weeks_in_seconds(MAX_WEEKS_WITHOUT_LOGIN)).to_datetime
+      end
+
+      def weeks_in_seconds(weeks)
+        60 * 60 * 24 * 7 * weeks.to_i
+      end
+    end
+  end
+end

data/lib/lita/commands/two_factor_off.rb

@@ -0,0 +1,49 @@
+module Lita
+  module Commands
+
+    class TwoFactorOff
+
+      def initialize(ou_path = "/")
+        @ou_path = ou_path
+      end
+
+      def name
+        'two-factor-off'
+      end
+
+      def run(robot, target, gateway, opts = {})
+        msg = build_msg(gateway)
+        robot.send_message(target, msg) if msg
+        if msg.nil? && opts[:negative_ack]
+          robot.send_message(target, "All users in #{@ou_path} have Two Factor Authentication enabled")
+        end
+      end
+
+      private
+
+      def build_msg(gateway)
+        users = active_users_without_tfa(gateway)
+
+        if users.any?
+          msg = "Users in #{@ou_path} with Two Factor Authentication disabled:\n\n"
+          users.each do |user|
+            msg += "- #{user.email}\n"
+          end
+          msg
+        end
+      end
+
+      def active_users_without_tfa(gateway)
+        gateway.users.reject { |user|
+          user.suspended?
+        }.reject { |user|
+          user.two_factor_enabled?
+        }.select { |user|
+          user.ou_path == @ou_path
+        }.sort_by { |user|
+          user.path
+        }
+      end
+    end
+  end
+end