netsnmp 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6bb62b9abd416188660e04be1c12cf009b1df0e307030b9c239ea4b2acd73cc
-  data.tar.gz: ee88f7eb292f1a0077ab25e4677713290447e0e7755049bbe6db50f07d15d6a1
+  metadata.gz: 5119f7e6ec751a4d3ba54076e5597b0667de904eda86802e5e3544e40a753172
+  data.tar.gz: 35924abe6afc24d8a41c8b6429a0566644d6bf4674b2b83704ac3f215e217487
 SHA512:
-  metadata.gz: fc90cc626d4be2a04d598ec267bcfc108e87aea8e8a585a7611033fc56cb6c174a222250bb9eeeb05b2d03d058983b106c92c30ba3d91e922b171ecfbc37041a
-  data.tar.gz: '09dbbb277ae24d9b760c0de70738a02037da527d653d5e003632c1b41d808cc21c44034fb51bec63394a132fe3c30ffaac1adc846dc061ca483e13fc0719af97'
+  metadata.gz: 7662ff27d3242840034b7e72f0a85132fa7007ef44ab4e207ac79f13cfdc29c3709884b098bba97d83e0f157618a8ca8c4dab5d8919bc6686aba4452b990213f
+  data.tar.gz: 673c3ce56ca0154f5efc6247204ffebbd9d0966d43ba4371ba2cee98d10f1496e579eef84acf24349109315d35febb7c42716a8b88c432200cee3eeddd63cca3

data/README.md

@@ -32,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?
@@ -54,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
 
@@ -73,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
@@ -135,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:
@@ -213,10 +237,26 @@ 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
 
@@ -272,7 +312,6 @@ The job of the CI is:
 
 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,46 +33,16 @@ rescue LoadError
   end
 end
 
-module NETSNMP
-  module StringExtensions
-    # If you wonder why this is there: the oauth feature uses a refinement to enhance the
-    # Regexp class locally with #match? , but this is never tested, because ActiveSupport
-    # monkey-patches the same method... Please ActiveSupport, stop being so intrusive!
-    # :nocov:
-    refine(String) do
-      def match?(*args)
-        !match(*args).nil?
-      end
-    end
-  end
-
-  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

@@ -77,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
@@ -153,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

data/lib/netsnmp/message.rb

@@ -2,41 +2,76 @@
 
 module NETSNMP
   # Factory for the SNMP v3 Message format
-  module Message
-    module_function
+  class Message
+    using ASNExtensions
 
-    AUTHNONE               = OpenSSL::ASN1::OctetString.new("\x00" * 12)
+    prepend Loggable
+
+    AUTHNONE               = OpenSSL::ASN1::OctetString.new("\x00" * 12).with_label(:auth_mask)
     PRIVNONE               = OpenSSL::ASN1::OctetString.new("")
-    MSG_MAX_SIZE       = OpenSSL::ASN1::Integer.new(65507)
-    MSG_SECURITY_MODEL = OpenSSL::ASN1::Integer.new(3) # usmSecurityModel
-    MSG_VERSION        = OpenSSL::ASN1::Integer.new(3)
+    MSG_MAX_SIZE       = OpenSSL::ASN1::Integer.new(65507).with_label(:max_message_size)
+    MSG_SECURITY_MODEL = OpenSSL::ASN1::Integer.new(3).with_label(:security_model) # usmSecurityModel
+    MSG_VERSION        = OpenSSL::ASN1::Integer.new(3).with_label(:message_version)
     MSG_REPORTABLE     = 4
 
+    def initialize(**); end
+
+    def verify(stream, auth_param, security_level, security_parameters:)
+      security_parameters.verify(stream.sub(auth_param, AUTHNONE.value), auth_param, security_level: security_level)
+    end
+
     # @param [String] payload of an snmp v3 message which can be decoded
     # @param [NETSMP::SecurityParameters, #decode] security_parameters knowns how to decode the stream
     #
     # @return [NETSNMP::ScopedPDU] the decoded PDU
     #
     def decode(stream, security_parameters:)
-      asn_tree = OpenSSL::ASN1.decode(stream)
-      _version, _headers, sec_params, pdu_payload = asn_tree.value
+      log { "received encoded V3 message" }
+      log { Hexdump.dump(stream) }
+      asn_tree = OpenSSL::ASN1.decode(stream).with_label(:v3_message)
+
+      version, headers, sec_params, pdu_payload = asn_tree.value
+      version.with_label(:message_version)
+      headers.with_label(:headers)
+      sec_params.with_label(:security_params)
+      pdu_payload.with_label(:pdu)
+
+      _, _, message_flags, = headers.value
 
-      sec_params_asn = OpenSSL::ASN1.decode(sec_params.value).value
+      # get last byte
+      # discard the left-outermost bits and keep the remaining two
+      security_level = message_flags.with_label(:message_flags).value.unpack("C*").last & 3
 
-      engine_id, engine_boots, engine_time, _username, auth_param, priv_param = sec_params_asn.map(&:value)
+      sec_params_asn = OpenSSL::ASN1.decode(sec_params.value).with_label(:security_params)
 
-      # validate_authentication
-      security_parameters.verify(stream.sub(auth_param, AUTHNONE.value), auth_param)
+      engine_id, engine_boots, engine_time, username, auth_param, priv_param = sec_params_asn.value
+      engine_id.with_label(:engine_id)
+      engine_boots.with_label(:engine_boots)
+      engine_time.with_label(:engine_time)
+      username.with_label(:username)
+      auth_param.with_label(:auth_param)
+      priv_param.with_label(:priv_param)
 
-      engine_boots = engine_boots.to_i
-      engine_time = engine_time.to_i
+      log(level: 2) { asn_tree.to_hex }
+      log(level: 2) { sec_params_asn.to_hex }
 
-      encoded_pdu = security_parameters.decode(pdu_payload, salt: priv_param,
+      auth_param = auth_param.value
+
+      engine_boots = engine_boots.value.to_i
+      engine_time = engine_time.value.to_i
+
+      encoded_pdu = security_parameters.decode(pdu_payload, salt: priv_param.value,
                                                             engine_boots: engine_boots,
-                                                            engine_time: engine_time)
+                                                            engine_time: engine_time,
+                                                            security_level: security_level)
 
+      log { "received response PDU" }
       pdu = ScopedPDU.decode(encoded_pdu)
-      [pdu, engine_id, engine_boots, engine_time]
+      pdu.auth_param = auth_param
+      pdu.security_level = security_level
+
+      log(level: 2) { pdu.to_hex }
+      [pdu, engine_id.value, engine_boots, engine_time]
     end
 
     # @param [NETSNMP::ScopedPDU] the PDU to encode in the message
@@ -45,36 +80,49 @@ module NETSNMP
     # @return [String] the byte representation of an SNMP v3 Message
     #
     def encode(pdu, security_parameters:, engine_boots: 0, engine_time: 0)
+      log(level: 2) { pdu.to_hex }
+      log { "encoding PDU in V3 message..." }
       scoped_pdu, salt_param = security_parameters.encode(pdu, salt: PRIVNONE,
                                                                engine_boots: engine_boots,
                                                                engine_time: engine_time)
 
       sec_params = OpenSSL::ASN1::Sequence.new([
-                                                 OpenSSL::ASN1::OctetString.new(security_parameters.engine_id),
-                                                 OpenSSL::ASN1::Integer.new(engine_boots),
-                                                 OpenSSL::ASN1::Integer.new(engine_time),
-                                                 OpenSSL::ASN1::OctetString.new(security_parameters.username),
+                                                 OpenSSL::ASN1::OctetString.new(security_parameters.engine_id).with_label(:engine_id),
+                                                 OpenSSL::ASN1::Integer.new(engine_boots).with_label(:engine_boots),
+                                                 OpenSSL::ASN1::Integer.new(engine_time).with_label(:engine_time),
+                                                 OpenSSL::ASN1::OctetString.new(security_parameters.username).with_label(:username),
                                                  AUTHNONE,
                                                  salt_param
-                                               ])
+                                               ]).with_label(:security_params)
+      log(level: 2) { sec_params.to_hex }
+
       message_flags = MSG_REPORTABLE | security_parameters.security_level
-      message_id    = OpenSSL::ASN1::Integer.new(SecureRandom.random_number(2147483647))
+      message_id    = OpenSSL::ASN1::Integer.new(SecureRandom.random_number(2147483647)).with_label(:message_id)
       headers = OpenSSL::ASN1::Sequence.new([
-                                              message_id, MSG_MAX_SIZE,
-                                              OpenSSL::ASN1::OctetString.new([String(message_flags)].pack("h*")),
+                                              message_id,
+                                              MSG_MAX_SIZE,
+                                              OpenSSL::ASN1::OctetString.new([String(message_flags)].pack("h*")).with_label(:message_flags),
                                               MSG_SECURITY_MODEL
-                                            ])
+                                            ]).with_label(:headers)
 
       encoded = OpenSSL::ASN1::Sequence([
                                           MSG_VERSION,
                                           headers,
-                                          OpenSSL::ASN1::OctetString.new(sec_params.to_der),
+                                          OpenSSL::ASN1::OctetString.new(sec_params.to_der).with_label(:security_params),
                                           scoped_pdu
-                                        ]).to_der
+                                        ]).with_label(:v3_message)
+      log(level: 2) { encoded.to_hex }
+
+      encoded = encoded.to_der
+      log { Hexdump.dump(encoded) }
       signature = security_parameters.sign(encoded)
       if signature
-        auth_salt = OpenSSL::ASN1::OctetString.new(signature)
-        encoded.sub!(AUTHNONE.to_der, auth_salt.to_der)
+        log { "signing V3 message..." }
+        auth_salt = OpenSSL::ASN1::OctetString.new(signature).with_label(:auth)
+        log(level: 2) { auth_salt.to_hex }
+        none_der = AUTHNONE.to_der
+        encoded[encoded.index(none_der), none_der.size] = auth_salt.to_der
+        log { Hexdump.dump(encoded) }
       end
       encoded
     end