mayu 0.1.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c61048046382829176afa3f7fb6f7c5bfcbda14bf86d8e1bc9aa7249ee1bb52
+  data.tar.gz: 66e12c39eb042dbe1b5693bea135f1129c49e423e1d0c3e01aa6c1b75a4dc606
+SHA512:
+  metadata.gz: f368f2c55b4d3d20a74b7d6e376a6df61d68281c6d33627bd470e75a52606bee7307a27409a54844f9feb3357a11dd850929b9838c7fbd76014146ad91cd2f03
+  data.tar.gz: 333ae0c533a8f749165716e446771cf273025685fc812a61225ac46a6c1f3932e75794057ef90ed1259002322729ac96f5c301a95881d84f3ec5d14ce80e9687

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.6.0
+before_install: gem install bundler -v 1.16.1

data/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in mayu.gemspec
+gemspec
+
+#gem 'graphed_fuzzy_search', path: File.expand_path('~/git/github.com/sorah/graphed_fuzzy_search')
+gem 'puma'

data/Gemfile.lock

@@ -0,0 +1,69 @@
+PATH
+  remote: .
+  specs:
+    mayu (0.1.0.beta1)
+      aws-sdk-s3
+      graphed_fuzzy_search
+      sinatra
+      wlc_snmp
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    aws-partitions (1.53.0)
+    aws-sdk-core (3.13.0)
+      aws-partitions (~> 1.0)
+      aws-sigv4 (~> 1.0)
+      jmespath (~> 1.0)
+    aws-sdk-kms (1.3.0)
+      aws-sdk-core (~> 3)
+      aws-sigv4 (~> 1.0)
+    aws-sdk-s3 (1.8.0)
+      aws-sdk-core (~> 3)
+      aws-sdk-kms (~> 1)
+      aws-sigv4 (~> 1.0)
+    aws-sigv4 (1.0.2)
+    diff-lcs (1.3)
+    graphed_fuzzy_search (0.1.0)
+    jmespath (1.3.1)
+    mustermann (1.0.1)
+    puma (3.11.0)
+    rack (2.0.3)
+    rack-protection (2.0.0)
+      rack
+    rake (12.3.0)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.0)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.0)
+    sinatra (2.0.0)
+      mustermann (~> 1.0)
+      rack (~> 2.0)
+      rack-protection (= 2.0.0)
+      tilt (~> 2.0)
+    snmp (1.2.0)
+    tilt (2.0.8)
+    wlc_snmp (0.1.0)
+      snmp
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  mayu!
+  puma
+  rake
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   1.16.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Sorah Fukumori
+
+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,206 @@
+# Mayu: Rack app to locate employees in an office by Wi-Fi MAC address and WLC association data
+
+__UNDER DEVELOPMENT, just API works__
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mayu'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mayu
+
+## Set up
+
+### Components
+
+1. Associaton collector: Collecting pair of MAC address => AP name
+2. User collector: Collecting pair of MAC address => user information
+3. Frontend: Web API and Frontend
+
+This gem includes (1) for Cisco WLC and (3). About (2), you have to write your own script to generate JSON.
+
+All data is stored in Amazon S3.
+
+### Running associaton collector
+
+```
+bundle exec mayu-association-collector
+```
+
+- `--interval` (default: 60, env: `$MAYU_ASSOC_INTERVAL`): Interval in seconds to run updating.
+- `--ttl` (default: 300, env: `$MAYU_ASSOC_TTL`): seconds to remove disappeared devices from list.
+- `--wlc` (required, env: `$MAYU_ASSOC_WLC`): Address of WLC for SNMP communication
+- `--community` (required, env: `$MAYU_ASSOC_WLC_COMMUNITY`): SNMP community of WLC
+- `--use-ap-mac-for-key` (env: `$MAYU_ASSOC_AP_MAC_KEY`): Use MAC address of AP for identifying APs, instead of its name
+- `--use-wlc-user` (env: `$MAYU_ASSOC_USE_WLC_USER`): Use username assigned by WLC for identifying user
+- Choose either:
+  - File:
+    - `--output` (required, env: `$MAYU_ASSOC_FILE`)
+  - S3:
+    - `--s3-region` (required, env: `$MAYU_ASSOC_S3_REGION`)
+    - `--s3-bucket` (required, env: `$MAYU_ASSOC_S3_BUCKET`)
+    - `--s3-key` (required, env: `$MAYU_ASSOC_S3_KEY`)
+
+### Running user collector
+
+Write your own logic to collect your employees' device MAC addresses.
+
+See [Internal](#internal) and place a properly formatted JSON file in S3.
+
+### Running web frontend
+
+```
+bundle exec rackup
+```
+
+Run as a Rack app. Refer the bundled [config.ru](./config.ru)
+
+The bundled config.ru accepts:
+
+- `$MAYU_WEB_RELOAD_INTERVAL` (default: 60)
+- `$MAYU_ASSOC_S3_REGION`
+- `$MAYU_ASSOC_S3_BUCKET`
+- `$MAYU_ASSOC_S3_KEY`
+- `$MAYU_USER_S3_REGION`
+- `$MAYU_USER_S3_BUCKET`
+- `$MAYU_USER_S3_KEY`
+
+Also, this app needs a list of APs for displaying a map.
+
+- `$MAYU_AP_S3_REGION`
+- `$MAYU_AP_S3_BUCKET`
+- `$MAYU_AP_S3_KEY`
+
+This JSON file should be formatted with a format in [Internal](#internal)
+
+## Internal
+
+### Formats
+
+- All datetimes in a JSON should be formatted in ISO8601.
+- MAC addresses should be formatted like `00:00:5e:00:53:a1` (hex, `:` separated, all lower case)
+
+#### Association
+
+``` json
+{
+  "associations": [
+    {
+      "mac": "DEVICE_MAC",
+      "user_key": "USER",
+      "ap_key": "AP_KEY",
+      "updated_at": "UPDATED_AT",
+      "appeared_at": "APPEARED_AT",
+      "disappeared_at": "DISAPPEARED_AT"
+    }
+  ]
+}
+```
+
+- `DEVICE_MAC`: MAC address
+- `USER` (optional): User key, if a user is determinable by an association. Otherwise user will be looked up from device MAC.
+- `AP_KEY`: AP key (name, MAC address or anything. Key should be consistent among all other JSON files)
+- `UPDATED_AT`: Time that this association updated.
+- `APPEARED_AT`: Time that this association appeared.
+- `DISAPPEARED_AT` (optional): Time that this association disappeared.
+
+#### Users
+
+``` json
+{
+  "users": [
+    {
+      "key": "KEY",
+      "name": "NAME",
+      "aliases": ["ALIAS"],
+      "gravatar_email": "GRAVATAR_EMAIL"
+    }
+  ],
+  "devices": [
+    {
+      "user_key": "USER_KEY",
+      "key": "DEVICE_KEY",
+      "mac": "DEVICE_MAC",
+      "kind": "DEVICE_KIND"
+    }
+  ]
+}
+```
+
+- `KEY`: Key (should be consistent among all other JSONs)
+- `NAME`: Name
+- `ALIAS` (optional): Alias (username, email, etc)
+- `GRAVATAR_EMAIL` (optional): Gravatar email
+- `DEVICE_MAC`: Device Wi-Fi MAC address that user owns.
+- `DEVICE_KIND` (default: `other`): Kind of device (`pc`, `phone`, `tablet`, `other`)
+
+#### APs
+
+``` json
+{
+  "maps": {
+    "MAP_KEY": {
+      "name": "MAP_NAME",
+      "url": "MAP_IMAGE_URL",
+      "fg_color": "HI_COLOR",
+      "bg_color": "HI_COLOR",
+      "highlight_color": "HI_COLOR"
+    }
+  },
+  "aps": {
+    "AP_KEY": {
+      "name": "AP_NAME",
+      "description": "AP_DESCRIPTION",
+      "map_key": "AP_MAP_KEY",
+      "map_x": "AP_MAP_X",
+      "map_y": "AP_MAP_Y"
+    }
+  }
+}
+```
+
+- `MAP_KEY`: Key of map (should be consistent among other JSON files)
+- `MAP_NAME`: Name of map (Floor name, etc)
+- `MAP_IMAGE_URL`: Image URL
+- `MAP_HI_COLOR`: Color for highlighting
+- `AP_KEY`: AP key
+- `AP_NAME`: Name of AP
+- `AP_DESCRIPTION`: Description of AP (location information for human, etc)
+- `AP_MAP_KEY`: Map corresponding for AP
+- `AP_MAP_X`: X position of AP in map
+- `AP_MAP_Y`: Y position of AP in map
+
+### Relations
+
+- user
+  - devices
+    - association
+- association
+  - ap
+  - device
+- map
+  - aps
+    - associations
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sorah/mayu.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/mayu-association-collector

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+require 'mayu'
+require 'optionparser'
+
+$stdout.sync = true
+
+interval = ENV.fetch('MAYU_ASSOC_INTERVAL', 60).to_i
+options = {
+  ttl: ENV['MAYU_ASSOC_TTL']&.to_i,
+  host: ENV['MAYU_ASSOC_WLC'],
+  community: ENV['MAYU_ASSOC_WLC_COMMUNITY'],
+  ap_mac_for_key: ENV['MAYU_ASSOC_AP_MAC_KEY'],
+  use_wlc_user: ENV['MAYU_ASSOC_USE_WLC_USER'],
+}.to_a.select { |k,v| v }.to_h
+
+s3_options = {
+  region: ENV['MAYU_ASSOC_S3_REGION'],
+  bucket: ENV['MAYU_ASSOC_S3_BUCKET'],
+  key: ENV['MAYU_ASSOC_S3_KEY'],
+}.to_a.select { |k,v| v }.to_h
+file_options = {
+  path: ENV['MAYU_ASSOC_FILE']
+}.to_a.select { |k,v| v }.to_h
+
+OptionParser.new do |opt|
+  opt.on('-i SEC', '--interval SEC', 'interval between updates, in seconds') do |sec|
+    interval = sec.to_i
+  end
+  opt.on('-l TTL', '--ttl TTL', 'seconds to remove disappeared associations from list') do |sec|
+    options[:ttl] = sec.to_i
+  end
+  opt.on('-h HOST', '--wlc HOST', 'address of WLC for SNMP') do |host|
+    options[:host] = host
+  end
+  opt.on('-c COMMUNITY', '--community COMMUNITY', 'SNMP community') do |community|
+    options[:community] = community
+  end
+  opt.on('--use-ap-mac-for-key', 'Use AP MAC address for identifying APs') do
+    options[:ap_mac_for_key] = true
+  end
+  opt.on('--use-wlc-use', 'Use username assigned by WLC for identifying user') do
+    options[:use_wlc_user] = true
+  end
+
+  opt.on('-r REGION', '--s3-region REGION', 'S3 region') do |region|
+    s3_options[:s3_region] = true
+  end
+  opt.on('-b BUCKET', '--s3-bucket BUCKET', 'S3 bucket') do |bucket|
+    s3_options[:s3_bucket] = true
+  end
+  opt.on('-k KEY', '--s3-key KEY', 'S3 key') do |key|
+    s3_options[:s3_key] = key
+  end
+
+  opt.on('-o FILE', '--output FILE') do |path|
+    file_options[:path] = path
+  end
+end.parse!(ARGV)
+
+options[:store] = if file_options.empty?
+  Mayu::Stores::S3.new(**s3_options)
+else
+  Mayu::Stores::File.new(**file_options)
+end
+
+collector_factory = lambda do
+  Mayu::CiscoWlcCollector.new(**options)
+end
+collector_factory.call # check for errors
+
+loop do
+  puts '=> Updating...'
+  collector = collector_factory.call
+  collector.perform!
+
+  puts " * #{Time.now.xmlschema}: #{collector.associations.size} associations"
+
+  sleep interval
+rescue SignalException, SystemExit => e
+  raise
+rescue Exception => e
+  $stderr.puts e.full_message
+  sleep interval
+end

data/config.ru

@@ -0,0 +1,41 @@
+require 'mayu'
+
+stores = []
+interval = ENV.fetch('MAYU_WEB_RELOAD_INTERVAL', 60).to_i
+
+%w(ASSOC USER AP).each do |k|
+  if ENV["MAYU_#{k}_S3_REGION"] && ENV["MAYU_#{k}_S3_BUCKET"] && ENV["MAYU_#{k}_S3_KEY"]
+    regions = ENV["MAYU_#{k}_S3_REGION"].split(?;)
+    buckets = ENV["MAYU_#{k}_S3_BUCKET"].split(?;)
+    keys = ENV["MAYU_#{k}_S3_KEY"].split(?;)
+    regions.zip(buckets, keys).each do |region, bucket, key|
+      stores.push(
+        Mayu::Stores::S3.new(
+          region: region || regions.first,
+          bucket: bucket || buckets.first,
+          key: key || keys.first,
+        )
+      )
+    end
+  end
+  if ENV["MAYU_#{k}_FILE"]
+    files = ENV["MAYU_#{k}_FILE"].split(?;)
+    files.each do |file|
+      stores.push(
+        Mayu::Stores::File.new(
+          path: file,
+        )
+      )
+    end
+  end
+end
+
+store = Mayu::Stores::Concat.new(stores: stores)
+loader = Mayu::Loader.new(store: store).load
+#binding.irb
+
+run Mayu.app(
+  store: store,
+  refresh_interval: interval,
+  slack_slash_command_token: ENV['MAYU_SLACK_SLASH_COMMAND_TOKEN'],
+)