netsnmp 0.1.8 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63503f340ea989e7ea9f123bbb49901852322145256fe06ce44c0244dfeb9300
-  data.tar.gz: f3981e9e148338f926428324836436c40ed38e4c84143a10ad0541052d302506
+  metadata.gz: c87bf65264474758aed741b992dadbd6bbb277aae52b925254da2e5fea56c5b3
+  data.tar.gz: cf7134f2e8b451c619aabdf9dcd6b931404ab51afd7953c785e4013a348cce02
 SHA512:
-  metadata.gz: c0b078e30151385ab01d3825431debe83531cf70089536538a372574b3ee40deef8b53c99673a774553b3afed903b3773af2db57a782dffec7a403373cfeb06e
-  data.tar.gz: ed3b9b066c6330e1bc4f9367e1c05bcd14f93c9874a492295cac1df29f1e48079aa76225fe16fb35bc7b975a0c66a5208fea0395715603e932dd8d80b5b6cd0c
+  metadata.gz: 1cade51302613f51f8da018351401b27c2d0fe08a43b915a79252ff420d5efdfe4a405ce29a60f10ade2d0f0f4a03dc2302117653043c451dd01683e8eb2c7a5
+  data.tar.gz: 0ce54aa2fb2cba42f47ccab2fd83e2536e8fd9e73d29d2f7a85aef4ab90d9e0c956f64f0f8fbe19f95c36a048ab2911492f55c4ca95ada0843941a896564b2cf

data/README.md

@@ -1,7 +1,6 @@
 # netsnmp
 
-[![Build Status](https://travis-ci.org/swisscom/ruby-netsnmp.svg?branch=master)](https://travis-ci.org/swisscom/ruby-netsnmp)
-[![Coverage Status](https://coveralls.io/repos/github/swisscom/ruby-netsnmp/badge.svg?branch=master)](https://coveralls.io/github/swisscom/ruby-netsnmp?branch=master)
+![Tests](https://github.com/swisscom/ruby-netsnmp/workflows/Tests/badge.svg)
 [![Code Climate](https://codeclimate.com/github/swisscom/ruby-netsnmp/badges/gpa.svg)](https://codeclimate.com/github/swisscom/ruby-netsnmp)
 [![Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/github/swisscom/ruby-netsnmp/master)
 
@@ -33,7 +32,7 @@ This gem provides:
 
 * Implementation in ruby of the SNMP Protocol for v3, v2c and v1 (most notable the rfc3414 and 3826).
 * Client/Manager API with simple interface for get, genext, set and walk.
-* No dependencies.
+* Pure Ruby.
 * Support for concurrency and evented I/O.
 
 ## Why?
@@ -55,10 +54,12 @@ All of these issues are resolved here.
 ## Features
 
 * Client Interface, which supports SNMP v3, v2c, and v1
-* Supports get, getnext, set and walk calls.
+* Supports get, getnext, set and walk calls
+* MIB support
 * Proxy IO object support (for eventmachine/celluloid-io)
 * Ruby >= 2.1 support (modern)
 * Pure Ruby (no FFI)
+* Easy PDU debugging
 
 ## Examples
 
@@ -74,12 +75,11 @@ manager = NETSNMP::Client.new(host: "localhost", port: 33445, username: "simulat
                               context: "a172334d7d97871b72241397f713fa12")
 
 # SNMP get
-# sysName.0
-manager.get(oid: "1.3.6.1.2.1.1.0") #=> 'tt'
+manager.get(oid: "sysName.0") #=> 'tt'
 
 # SNMP walk
 # sysORDescr
-manager.walk(oid: "1.3.6.1.2.1.1.1").each do |oid_code, value|
+manager.walk(oid: "sysORDescr").each do |oid_code, value|
   # do something with them  
   puts "for #{oid_code}: #{value}"
 end
@@ -136,6 +136,29 @@ manager.set("somecounteroid", value: 999999, type: 6)
 ```
 * Fork this library, extend support, write a test and submit a PR (the desired solution ;) )
 
+## MIB
+
+`netsnmp` will load the default MIBs from known or advertised (via `MIBDIRS`) directories (provided that they're installed in the system). These will be used for the OID conversion.
+
+Sometimes you'll need to load more, your own MIBs, in which case, you can use the following API:
+
+```ruby
+require "netsnmp"
+
+NETSNMP::MIB.load("MY-MIB")
+# or, if it's not in any of the known locations
+NETSNMP::MIB.load("/path/to/MY-MIB.txt")
+```
+
+You can install common SNMP mibs by using your package manager:
+
+```
+# using apt-get
+> apt-get install snmp-mibs-downloader
+# using apk
+> apk --update add net-snmp-libs
+```
+
 ## Concurrency
 
 In ruby, you are usually adviced not to share IO objects across threads. The same principle applies here to `NETSNMP::Client`: provided you use it within a thread of execution, it should behave safely. So, something like this would be possible:
@@ -214,15 +237,32 @@ NETSNMP::Client.new(share_options.merge(proxy: router_proxy, security_parameters
 end
 ```
 
+## Compatibility
+
+This library supports and is tested against ruby versions 2.1 or more recent, including ruby 3. It also supports and tests against Truffleruby.
+
 ## OpenSSL
 
 All encoding/decoding/encryption/decryption/digests are done using `openssl`, which is (still) a part of the standard library. If at some point `openssl` is removed and not specifically distributed, you'll have to install it yourself. Hopefully this will never happen.
 
+It also uses the `openssl` ASN.1 API to encode/decode BERs, which is known to be strict, and [may not be able to decode PDUs if not compliant with the supported RFC](https://github.com/swisscom/ruby-netsnmp/issues/47).
+
+## Debugging
+
+You can either set the `NETSNMP_DEBUG` to the desided debug level (currently, 1 and 2). The logs will be written to stderr.
+
+You can also set it for a specific client:
+
+```ruby
+manager2 = NETSNMP::Client.new(debug: $stderr, debug_level: 2, ....)
+```
+
 
 ## Tests
 
 This library uses RSpec. The client specs are "integration" tests, in that we communicate with an [snmpsim-built snmp agent simulator](https://github.com/etingof/snmpsim).
 
+
 ### RSpec
 
 You can run all tests by typing:
@@ -234,37 +274,31 @@ You can run all tests by typing:
 ...
 ```
 
-### SNMP Simulator
-
-You can install the package yourself (ex: `pip install snmpsim`) and run the server locally, and then set the `SNMP_PORT` environment variable, where the snmp simulator is running.
-
-#### Docker
 
-The preferred way to use the snmp simulator is by using docker.
+### Docker
 
-In order to start the simulator container, run:
+The most straightforward way of running the tests is by using the `docker-compose` setup (which is also what's used in the CI). Run it against the ruby version you're targeting:
 
 ```
-> spec/support/spec.sh start
+> docker-compose -f docker-compose.yml -f docker-compose-ruby-${RUBY_MAJOR_VERSION}.${RUBY_MAJOR_VERSION}.yml run netsnmp
 ```
 
-after, you just need to set the `SNMP_PORT` variable to the port found typing:
+The CI runs the tests against all supported ruby versions. If changes break a specific version of ruby, make sure you commit appropriate changes addressing the edge case, or let me know in the issues board, so I can help.
 
-```
-> docker port test-snmp 1161/udp
-```
+### SNMP Simulator
 
-and run the tests. 
+The SNMP simulator runs in its own container in the `docker` setup.
 
-#### CI
+You can install the package yourself (ex: `pip install snmpsim`) and run the server locally, and then set the `SNMP_PORT` environment variable, where the snmp simulator is running.
 
-If you want to replicate what the CI is doing, just do:
+#### CI
 
-```
-> spec/support/spec.sh run
-```
+The job of the CI is:
 
-Which should: build and run the simulator container, run the tests, run rubocop, and remove all artifacts.
+* Run all the tests;
+* Make sure the tests cover an appropriate surface of the code;
+* Lint the code;
+* (for ruby 3.0) type check the code;
 
 
 ## Contributing
@@ -278,7 +312,6 @@ Which should: build and run the simulator container, run the tests, run rubocop,
 
 There are some features which this gem doesn't support. It was built to provide a client (or manager, in SNMP language) implementation only, and the requirements were fulfilled. However, these notable misses will stand-out:
 
-* No MIB support (you can only work with OIDs)
 * No server (Agent, in SNMP-ish) implementation.
 * No getbulk support.
 

data/lib/netsnmp.rb

@@ -33,34 +33,16 @@ rescue LoadError
   end
 end
 
-module NETSNMP
-  def self.debug=(io)
-    @debug_output = io
-  end
-
-  def self.debug(&blk)
-    @debug_output << blk.call + "\n" if @debug_output
-  end
-
-  unless defined?(Hexdump) # support the hexdump gem
-    module Hexdump
-      def self.dump(data, width: 8)
-        pairs = data.unpack("H*").first.scan(/.{4}/)
-        pairs.each_slice(width).map do |row|
-          row.join(" ")
-        end.join("\n")
-      end
-    end
-  end
-end
-
 require "netsnmp/errors"
+require "netsnmp/extensions"
+require "netsnmp/loggable"
 
 require "netsnmp/timeticks"
 
 require "netsnmp/oid"
 require "netsnmp/varbind"
 require "netsnmp/pdu"
+require "netsnmp/mib"
 require "netsnmp/session"
 
 require "netsnmp/scoped_pdu"

data/lib/netsnmp/client.rb

@@ -23,8 +23,7 @@ module NETSNMP
     #      puts client.get(oid: "1.3.6.1.2.1.1.5.0")
     #    end
     #
-    def initialize(**options)
-      version = options[:version]
+    def initialize(version: nil, **options)
       version = case version
                 when Integer then version # assume the use know what he's doing
                 when /v?1/ then 0
@@ -33,7 +32,7 @@ module NETSNMP
                 end
 
       @retries = options.fetch(:retries, RETRIES)
-      @session ||= version == 3 ? V3Session.new(options) : Session.new(options)
+      @session ||= version == 3 ? V3Session.new(**options) : Session.new(version: version, **options)
       return unless block_given?
       begin
         yield self
@@ -78,7 +77,7 @@ module NETSNMP
     # @return [Enumerator] the enumerator-collection of the oid-value pairs
     #
     def walk(oid:)
-      walkoid = oid
+      walkoid = OID.build(oid)
       Enumerator.new do |y|
         code = walkoid
         first_response_code = nil
@@ -154,7 +153,7 @@ module NETSNMP
       retries = @retries
       begin
         yield
-      rescue Timeout::Error => e
+      rescue Timeout::Error, IdNotInTimeWindowError => e
         raise e if retries.zero?
         retries -= 1
         retry

data/lib/netsnmp/encryption/aes.rb

@@ -22,13 +22,12 @@ module NETSNMP
         end
 
         encrypted_data = cipher.update(decrypted_data) + cipher.final
-        NETSNMP.debug { "encrypted:\n#{Hexdump.dump(encrypted_data)}" }
 
         [encrypted_data, salt]
       end
 
       def decrypt(encrypted_data, salt:, engine_boots:, engine_time:)
-        raise Error, "invalid priv salt received" unless (salt.length % 8).zero?
+        raise Error, "invalid priv salt received" unless !salt.empty? && (salt.length % 8).zero?
 
         cipher = OpenSSL::Cipher::AES128.new(:CFB)
         cipher.padding = 0
@@ -39,7 +38,6 @@ module NETSNMP
         cipher.key = aes_key
         cipher.iv = iv
         decrypted_data = cipher.update(encrypted_data) + cipher.final
-        NETSNMP.debug { "decrypted:\n#{Hexdump.dump(decrypted_data)}" }
 
         hlen, bodylen = OpenSSL::ASN1.traverse(decrypted_data) { |_, _, x, y, *| break x, y }
         decrypted_data.byteslice(0, hlen + bodylen)

data/lib/netsnmp/encryption/des.rb

@@ -24,7 +24,6 @@ module NETSNMP
         end
 
         encrypted_data = cipher.update(decrypted_data) + cipher.final
-        NETSNMP.debug { "encrypted:\n#{Hexdump.dump(encrypted_data)}" }
         [encrypted_data, salt]
       end
 
@@ -41,7 +40,6 @@ module NETSNMP
         cipher.key = des_key
         cipher.iv = iv
         decrypted_data = cipher.update(encrypted_data) + cipher.final
-        NETSNMP.debug { "decrypted:\n#{Hexdump.dump(decrypted_data)}" }
 
         hlen, bodylen = OpenSSL::ASN1.traverse(decrypted_data) { |_, _, x, y, *| break x, y }
         decrypted_data.byteslice(0, hlen + bodylen)

data/lib/netsnmp/errors.rb

@@ -4,4 +4,5 @@ module NETSNMP
   Error = Class.new(StandardError)
   ConnectionFailed = Class.new(Error)
   AuthenticationFailed = Class.new(Error)
+  IdNotInTimeWindowError = Class.new(Error)
 end

data/lib/netsnmp/extensions.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module NETSNMP
+  module IsNumericExtensions
+    refine String do
+      def integer?
+        each_byte do |byte|
+          return false unless byte >= 48 && byte <= 57
+        end
+        true
+      end
+    end
+  end
+
+  module StringExtensions
+    refine(String) do
+      unless String.method_defined?(:match?)
+        def match?(*args)
+          !match(*args).nil?
+        end
+      end
+
+      unless String.method_defined?(:unpack1)
+        def unpack1(format)
+          unpack(format).first
+        end
+      end
+    end
+  end
+
+  module ASNExtensions
+    ASN_COLORS = {
+      OpenSSL::ASN1::Sequence => 34, # blue
+      OpenSSL::ASN1::OctetString => 32, # green
+      OpenSSL::ASN1::Integer => 33, # yellow
+      OpenSSL::ASN1::ObjectId => 35, # magenta
+      OpenSSL::ASN1::ASN1Data => 36 # cyan
+    }.freeze
+
+    # basic types
+    ASN_COLORS.each_key do |klass|
+      refine(klass) do
+        def to_hex
+          "#{colorize_hex} (#{value.to_s.inspect})"
+        end
+      end
+    end
+
+    # composite types
+    refine(OpenSSL::ASN1::Sequence) do
+      def to_hex
+        values = value.map(&:to_der).join
+        hex_values = value.map(&:to_hex).map { |s| s.gsub(/(\t+)/) { "\t#{Regexp.last_match(1)}" } }.map { |s| "\n\t#{s}" }.join
+        der = to_der
+        der = der.sub(values, "")
+
+        "#{colorize_hex(der)}#{hex_values}"
+      end
+    end
+
+    refine(OpenSSL::ASN1::ASN1Data) do
+      attr_reader :label
+
+      def with_label(label)
+        @label = label
+        self
+      end
+
+      def to_hex
+        case value
+        when Array
+          values = value.map(&:to_der).join
+          hex_values = value.map(&:to_hex)
+                            .map { |s| s.gsub(/(\t+)/) { "\t#{Regexp.last_match(1)}" } }
+                            .map { |s| "\n\t#{s}" }.join
+          der = to_der
+          der = der.sub(values, "")
+        else
+          der = to_der
+          hex_values = nil
+        end
+
+        "#{colorize_hex(der)}#{hex_values}"
+      end
+
+      private
+
+      def colorize_hex(der = to_der)
+        hex = Hexdump.dump(der, separator: " ")
+        lbl = @label || self.class.name.split("::").last
+        "#{lbl}: \e[#{ASN_COLORS[self.class]}m#{hex}\e[0m"
+      end
+    end
+  end
+
+  module Hexdump
+    using StringExtensions
+
+    def self.dump(data, width: 8, in_groups_of: 4, separator: "\n")
+      pairs = data.unpack1("H*").scan(/.{#{in_groups_of}}/)
+      pairs.each_slice(width).map do |row|
+        row.join(" ")
+      end.join(separator)
+    end
+  end
+
+  # Like a string, but it prints an hex-string version of itself
+  class HexString < String
+    def inspect
+      Hexdump.dump(self, in_groups_of: 2, separator: " ")
+    end
+  end
+end

data/lib/netsnmp/loggable.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module NETSNMP
+  module Loggable
+    DEBUG = ENV.key?("NETSNMP_DEBUG") ? $stderr : nil
+    DEBUG_LEVEL = (ENV["NETSNMP_DEBUG"] || 1).to_i
+
+    def initialize(debug: DEBUG, debug_level: DEBUG_LEVEL, **opts)
+      super(**opts)
+      @debug = debug
+      @debug_level = debug_level
+    end
+
+    private
+
+    COLORS = {
+      black: 30,
+      red: 31,
+      green: 32,
+      yellow: 33,
+      blue: 34,
+      magenta: 35,
+      cyan: 36,
+      white: 37
+    }.freeze
+
+    def log(level: @debug_level)
+      return unless @debug
+      return unless @debug_level >= level
+
+      debug_stream = @debug
+
+      debug_stream << (+"\n" << yield << "\n")
+    end
+  end
+end