sensu-plugins-snmptrap-extension 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b9ade74acbf2e688353c1fbe51c10fb310d33993
+  data.tar.gz: 183bbd5e5cdb31f9a0af9ed1a1f22344da3b5eeb
+SHA512:
+  metadata.gz: 1bd4fb7ba9941e00a1deadcd5d6b10232824a87b7156b684702a85aaffc55471ca0fb34be1cb1bc038587b0d3b6959b28db88232f253af6c564897f719b7b47f
+  data.tar.gz: 686ece3016f49c2e329ee4988f84b2831d1cbccf1c06452cff74ab96197ac8acf7e2e692767494c3940ddbecc39f1da9b306bb71782c4eb79e3b24d011fd29ae

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+#Change Log
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+This CHANGELOG follows the format listed at [Keep A Changelog](http://keepachangelog.com/)
+
+## Unreleased
+### Added
+- Rake, gemspecs and basic core test code
+- This CHANGELOG
+- Travis configuration for test building
+
+### Changed
+- Moved script to bin sub-directory as part of refactor to adhere to sensu-plugin conventions
+
+
+## 0.0.1 - 2015-05-20
+### Added
+- initial release

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Sensu-Plugins
+
+MIT License
+
+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,96 @@
+# Sensu SNMP Trap Extension
+
+Creates an SNMP trap listening to all incoming traps on the configured interface and triggers events into sensu as JIT events when specifying the source of the event.
+
+[![Build Status](https://travis-ci.org/warmfusion/sensu-extension-snmptrap.svg)](https://travis-ci.org/warmfusion/sensu-extension-snmptrap)
+
+## TODO
+
+Also able to run as a 'polling' service in either Check or Metrics mode where values can be directly compared against expectations (eg value > 10)
+or where values are sent to Sensu as metrics values for charting or other purposes.
+
+
+## Configuration
+
+The SNMPTrap configuration is defined in a json file inside conf.d/extensions (or anywhere sensu consumes configuration)
+and includes a traps configuration element that describes:
+
+* An array of traps that the extension will monitor for events (from any host) which includes
+    * `trap_oid` - the identity of the trap
+    * `trap` - A hash of key/value pairs that can be used as template values in the event
+    * `event` - The template event to send to Sensu, including {template} variables for customisation based on the message
+
+
+### Templating
+
+Any value defined in `trap` that contains an OID that is included in the incoming trap can be used as part of any element of the
+event being sent to Sensu. This includes handlers, names (Only AlphaNumeric allow), status etc etc.
+
+Simply wrap your template in braces and it will be automatically replaced during processing. See the heartbeatrate in the example
+below.
+
+> Note: The 'source' and 'hostname' variables are automatically provided to you. Hostname contains the FQDN name of the server (or the IP if it 
+> can't get resolved) and 'source' contains the IP address (with no lookups)
+
+### Basic Extension Configuration
+
+
+     {
+      "snmp": {
+ 
+       }
+     }
+
+### Trap Configuration
+
+Each SNMP Trap is configured in its own configuration file. This lets you easily create configuration through Puppet/Chef etc without
+having to manipulate the same configuration file.
+
+Simply create a uniquely named json file in `/etc/sensu/traps.d` containing the definition of the trap(s) you wish to capture and
+act upon.
+
+
+    [
+      {
+        "trap_oid": "1.3.6.1.4.1.8072.2.3.0.1",
+        "trap": {
+          "heartbeatrate": "1.3.6.1.4.1.8072.2.3.2.1" 
+        },
+        "event": {
+          "name": "snmp-trap-{hostname}",
+          "status": 1,
+          "output": "Heartbeat Rate {heartbeatrate}", 
+          "handler": "default"
+         }
+       },
+       ...
+     ]
+
+The JSON file is an array of trap definitions containing:
+
+* trap_oid
+  * Definition: (String) The OID to monitor for events on
+* trap
+  * Definition: (Array) Key/Value pairs representing named variables (key) against the OID values of the message elements (value)
+    which can then be used as template values in the event section
+* event
+  * Definition: (Hash) The event to trigger if the SNMP trap is recieved - Accepts any value that will then get sent to sensu
+    as a normal check event - this includes handlers, subdues, or custom key/value pairs as you require.
+  * name
+    * Definition: (String) The name of the sensu check that is sent to the sensu-client - ALPHANUMERIC and should be fairly unique (Required)
+  * status
+    * Definition: (Numeric) The numeric status of the status (0-OK, 1-Warning, 2-Critical, 3-Unknown) (Required)
+  * output
+    * Definition: (String) The message to send to the sensu client (Required)
+  * handler
+    * Definition: (String) The handler that the sensu-server should use to process this event (Optional)
+
+
+## Appendix 
+
+Handy Test script:
+
+    snmptrap -v 2c -c public localhost:1062 "" NET-SNMP-EXAMPLES-MIB::netSnmpExampleHeartbeatNotification  netSnmpExampleHeartbeatRate i 123456
+
+
+Released under the same terms as Sensu (the MIT license). 

data/bin/extension-snmptrap.rb

@@ -0,0 +1,239 @@
+#! /usr/bin/env ruby
+#
+#   extension-snmptrap.rb
+#
+# DESCRIPTION:
+#   Handles incoming SNMP Traps and emits sensu events
+#   Creates an SNMP trap listening to all incoming traps on any interface and triggers events into sensu as JIT clients specifying the source of the event.
+#
+#   Also able to run as a 'polling' service in either Check or Metrics mode
+#   where values can be directly compared against expectations (eg value > 10)
+#   or where values are sent to Sensu as metrics values for charting or
+#   other purposes.
+#
+#       {
+#        "snmp": { }
+#       }
+#
+# OUTPUT:
+#   N/A - Extension submits multiple events of different types based on snmp configuration
+#
+# PLATFORMS:
+#   Linux
+#
+# DEPENDENCIES:
+#   gem: snmp
+#
+# USAGE:
+#  Traps are configured in /etc/sensu/traps.d directory, one json file containing one or more trap configurations
+#  as described in the README.md that accompanies this script.
+#
+# NOTES:
+#   No special notes. This should be fairly straight forward.
+#
+# LICENSE:
+#   Toby Jackson <toby@warmfusion.co.uk>
+#   Peter Daugavietis <pdaugavietis@gmail.com>
+#   Released under the same terms as Sensu (the MIT license); see LICENSE
+#   for details.
+#
+#
+# ##############################
+# Handy Test script:
+# snmptrap -v 2c -c public localhost:1062 "" NET-SNMP-EXAMPLES-MIB::netSnmpExampleHeartbeatNotification  netSnmpExampleHeartbeatRate i 123456
+#
+# Useful SNMP browser to help find things:
+# http://tools.cisco.com/Support/SNMP/do/BrowseOID.do?local=en&translate=Translate&objectInput=1.3.6.1.2.1.1.5
+#
+# http://www.net-snmp.org/docs/mibs/ucdavis.html#laTable
+# Load Average Last Minute -  .1.3.6.1.4.1.2021.10.1.3.1
+#
+require 'net/http'
+require 'snmp'
+require 'json'
+include SNMP
+
+module Sensu
+  module Extension
+    class SNMPTrapHandler < Check
+      # assume the /etc/sensu/extensions folder as location for relative
+      data_path = File.expand_path(File.dirname(__FILE__) + '/../mibs')
+
+      DEFAULT_MIB_PATH = nil
+      if File.exist?(data_path)
+        DEFAULT_MIB_PATH = data_path
+      else
+        @logger.info "Could not find default MIB directory, tried:\n  #{data_path}"
+      end
+
+      def name
+        'SnmpTrapHandler'
+      end
+
+      def description
+        'SNMP Extension that handles/traps SNMP events'
+      end
+
+      def options
+        return @options if @options
+        @options = {
+          bind: '0.0.0.0',
+          port: 1062,
+          community: 'public',
+          handler: 'default',
+          send_interval: 60,
+          trapdefs_dir: '/etc/sensu/traps.d',
+          mibs_dir: '/etc/sensu/mibs'
+        }
+        @options.merge!(@settings[:snmp]) if @settings[:snmp].is_a?(Hash)
+        @options
+      end
+
+      def definition
+        {
+          type: 'extension',
+          name: name,
+          publish: false # Don't run this extension as a check
+        }
+      end
+
+      def post_init
+        # Setup SNMPTrap
+        @logger.debug "Loading SNMPTrap definitions from #{options[:trapdefs_dir]}"
+        @trapdefs = []
+        Dir.glob(options[:trapdefs_dir] + '/*.json') do |file|
+          # do something with the file here
+          @logger.info file
+          @trapdefs.concat Array(JSON.parse(File.read(file)))
+        end
+
+        @logger.debug @trapdefs.to_json
+
+        @mibs = []
+        Dir.glob(options[:mibs_dir] + '/*.yaml') do |file|
+          # do something with the file here
+          @logger.debug "Reading MIB configuration from #{File.basename(file, '.yaml')}"
+          @mibs << File.basename(file, '.yaml')
+        end
+        @logger.debug @mibs.to_json
+
+        start_trap_listener
+      end
+
+      def run(_data = nil, _options = {}, &callback)
+        @logger.warn('SNMP Trap: Run called as a check - this is not supported')
+        output = 'SNMPHandler extension should not be called as a standalone check'
+        callback.call(output, 3)
+      end
+
+      def start_trap_listener
+        @logger.info('Starting SNMP Trap listener...')
+
+        SNMP::TrapListener.new(Host: options[:bind], Port: options[:port]) do |manager|
+          # Need patched Gem to allow the following functions/lookups
+          # Need to copy the MIBs from somewhere to the Gem location needed (or fix the importing mechanism too)
+
+          # If the following MIB code is used, SNMPTrap hangs up and stops working... dont know why - possibly
+          # an implicit .join() somewhere locking things up ?
+          # SNMP::MIB.import_modules(@mibs)
+          # manager.load_modules(@mibs, DEFAULT_MIB_PATH)
+          # @mib = manager.mib
+
+          manager.on_trap_v1 do |trap|
+            @logger.info('v1-Trap caught')
+            @logger.info trap.to_json
+          end
+
+          manager.on_trap_v2c do |trap|
+            @logger.info('v2-Trap caught')
+            @logger.info(trap.to_json)
+
+            processed = false
+            @trapdefs.each do |trapdef|
+              if !trapdef['trap_oid'].nil?
+                trapdef_oid = SNMP::ObjectId.new(trapdef['trap_oid'])
+              else
+                trapdef_oid = SNMP::ObjectId.new(@mib.oid(trapdef[:trap_name]))
+              end
+              @logger.debug 'trapdef ' + trapdef_oid.inspect
+              @logger.debug 'trap ' + trap.trap_oid.inspect
+              # only accept configured traps
+              if trap.trap_oid == trapdef_oid
+                @logger.info "Processing known v2 trap #{trap.trap_oid}"
+                process_v2c_trap trap, trapdef
+                processed = true
+                break
+              end
+              @logger.debug "Ignoring unrecognised trap: #{trap.trap_oid}" unless processed
+            end
+          end
+
+          @logger.info("SNMP Trap listener has started on #{options[:bind]}:#{options[:port]}")
+        end
+      end
+
+      private
+
+      # Doesn't appear to be possible to ping Sensu directly for async event triggering
+      # even though we're inside Sensu right now...
+      def publish_check_result(check)
+        # a little risky: we're assuming Sensu-Client is listening on Localhost:3030
+        # for submitted results : https://sensuapp.org/docs/latest/clients#client-socket-input
+        @logger.info "Sending SNMP check event: #{check.to_json}"
+
+        host = settings[:client][:bind] ||= '127.0.0.1'
+        port = settings[:client][:port] ||= '3030'
+        t = TCPSocket.new host, port
+        t.write(check.to_json + "\n")
+      end
+
+      def process_v2c_trap(trap, trapdef)
+        hostname = trap.source_ip
+        begin
+          hostname = Resolv.getname(trap.source_ip)
+        rescue Resolv::ResolvError
+          @logger.debug("Unable to resolve name for #{trap.source_ip}")
+        end
+
+        fields = {}
+        fields[:source] = trap.source_ip
+        fields[:hostname] = hostname
+
+        @logger.debug('Checking trap definition for key/value template pairs')
+        Array(trapdef['trap']).each do |key, value|
+          begin
+            value = SNMP::ObjectId.new(value)
+          rescue
+            value = SNMP::ObjectId.new(@mib.oid(value))
+          end
+
+          @logger.debug key.inspect + ', ' + value.inspect
+          @logger.debug trap.varbind_list.inspect
+          val = trap.varbind_list.find { |vb| vb.name == value }
+          if val.nil?
+            @logger.warn("trap.#{key} has OID(#{value}) that was not found in incoming trap - Check your configuration")
+          end
+          @logger.debug("Discovered value of #{key} is '#{val}'")
+          fields[key] = val.value unless val.nil?
+        end
+
+        @logger.debug("Template fields are: #{fields.inspect}")
+
+        # Replace any {template} values in the event with the value of
+        # snmp values defined in the traps configuration
+        fields.each do |key, value|
+          trapdef['event'].each do |k, v|
+            @logger.debug("Looking for #{key} in #{trapdef['event'][k]}")
+            begin
+              trapdef['event'][k] = v.gsub("{#{key}}", value.to_s.gsub('/', '-'))
+            rescue
+              trapdef['event'][k] = v
+            end
+          end
+        end
+        @logger.debug trapdef['event']
+        publish_check_result trapdef['event']
+      end
+    end
+  end
+end

data/lib/sensu-plugins-snmptrap-extension.rb

@@ -0,0 +1 @@
+require 'sensu-plugins-snmptrap-extension/version'

data/lib/sensu-plugins-snmptrap-extension/version.rb

@@ -0,0 +1,9 @@
+module SensuPluginsSnmptrapExtension
+  module Version
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+
+    VER_STRING = [MAJOR, MINOR, PATCH].compact.join('.')
+  end
+end

metadata

@@ -0,0 +1,241 @@
+--- !ruby/object:Gem::Specification
+name: sensu-plugins-snmptrap-extension
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Toby Jackson <toby@warmfusion.co.uk>
+- Peter Daugavietis <pdaugavietis@gmail.com>
+autorequire: 
+bindir: bin
+cert_chain:
+- certs/sensu-plugins.pem
+date: 2016-06-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: snmp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+- !ruby/object:Gem::Dependency
+  name: sensu-plugin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+- !ruby/object:Gem::Dependency
+  name: net
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: codeclimate-test-reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: github-markup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.32.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.32.1
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: Sensu extension for trapping SNMP events and reemiting as templated events
+email: <toby@warmfusion.co.uk>
+executables:
+- extension-snmptrap.rb
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/extension-snmptrap.rb
+- lib/sensu-plugins-snmptrap-extension/version.rb
+- lib/sensu-plugins-snmptrap-extension.rb
+- LICENSE
+- README.md
+- CHANGELOG.md
+homepage: https://github.com/warmfusion/sensu-sensu-extension-snmptrap
+licenses:
+- MIT
+metadata:
+  maintainer: '@warmfusion'
+  development_status: active
+  production_status: unstable - testing recommended
+  release_draft: 'false'
+  release_prerelease: 'false'
+post_install_message: You can use the embedded Ruby by setting EMBEDDED_RUBY=true
+  in /etc/default/sensu
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14.1
+signing_key: 
+specification_version: 4
+summary: Sensu extension to capture SNMP trap events
+test_files: []
+has_rdoc: