Merge pull request github#54 from github/instance-audit

Add full instance auditor

Author: kylemacey

api/ruby/instance-auditing/.gitignore

@@ -0,0 +1 @@
+*.xlsx

api/ruby/instance-auditing/README.md

@@ -0,0 +1,13 @@
+# Instance auditor
+
+This script creates an spreadsheet file that will allow you to audit the access of each team and user with all of the organizations across your GitHub Enterprise instance.
+
+## Getting started
+
+The user who is going to run the script must be on the "Owners" team of every organization you wish to audit. You can promote all users with Site Admin access to owners of every organization by running [`ghe-org-admin-promote`](https://help.github.com/enterprise/admin/articles/command-line-utilities/#ghe-org-admin-promote).
+
+You will also need to [generate a Personal Access Token](https://help.github.com/enterprise/user/articles/creating-an-access-token-for-command-line-use/) for that user with the `admin:org` permission.
+
+## Output
+
+This utility will create a file in the same directory called `audit.xlsx` containing the audit data. 

api/ruby/instance-auditing/instance_auditor.rb

@@ -0,0 +1,52 @@
+
+# GitHub & GitHub Enterprise Instance auditor
+# =======================================
+#
+# Usage: ruby instance_audit.rb
+#
+# These environment variables must be set:
+# - GITHUB_TOKEN: A valid personal access token with Organzation admin priviliges
+# - GITHUB_API_ENDPOINT: A valid GitHub/GitHub Enterprise API endpoint URL
+#                        (use http://api.github.com for GitHub.com auditing)
+#
+# Requires the Octokit Rubygem: https://github.com/octokit/octokit.rb
+# Requires the axlsx Rubygem:   https://github.com/randym/axlsx
+
+require 'octokit.rb'
+require 'axlsx'
+
+begin
+  ACCESS_TOKEN = ENV.fetch("GITHUB_TOKEN")
+  API_ENDPOINT = ENV.fetch("GITHUB_API_ENDPOINT")
+rescue KeyError
+  $stderr.puts "To run this script, please set the following environment variables:"
+  $stderr.puts "- GITHUB_TOKEN: A valid personal access token with Organzation admin priviliges"
+  $stderr.puts "- GITHUB_API_ENDPOINT: A valid GitHub/GitHub Enterprise API endpoint URL"
+  $stderr.puts "                       (use http://api.github.com for GitHub.com auditing)"
+  exit 1
+end
+
+Octokit.configure do |kit|
+  kit.api_endpoint = API_ENDPOINT
+  kit.access_token = ACCESS_TOKEN
+  kit.auto_paginate = true
+end
+
+client = Octokit::Client.new
+
+Axlsx::Package.new do |p|
+  client.organizations.each do |org|
+    p.workbook.add_worksheet(:name => org[:login]) do |sheet|
+      sheet.add_row %w{Organization Team Repo User Access}
+      client.organization_teams(org[:login]).each do |team|
+        client.team_repos(team[:id]).each do |repo|
+          client.team_members(team[:id]).each do |user|
+            sheet.add_row [org[:login], team[:name], repo[:name], user[:login], team[:permission]]
+          end
+        end
+      end
+    end
+  end
+  p.use_shared_strings = true
+  p.serialize("#{Time.now.strftime "%Y-%m-%d"}-audit.xlsx")
+end