zabbix_manager 6.0.0 → 6.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b40a4744edcbba667b1c548c576b6451e637dee80bce28755a151f58e02a553b
-  data.tar.gz: 5d5ee350721f10da7ea9f93582bf06fc6c5b6ac4e5a9bbaa445058f43c205a45
+  metadata.gz: ad8094e06c6d99c1ff334dd2cf9d86c40bb9f45467d811e53be92d1ffcf05bb3
+  data.tar.gz: 90375dfe1473875e17e2b8e82b3f947818076239b1ceb3d2f868001b600f4c12
 SHA512:
-  metadata.gz: db558e058564904b417225b8f59df28a741b7f73d787f104180dd878e017899fadfe077d4194b2e2f2b2995639cf9c42ab585abf25f0d06308af9f8a6549eeba
-  data.tar.gz: 5c6a2e519171dec793941f13ba766aad04679a008196dad090b784614fa59882c851c810554c0c8ee479ba8aa7493779c5c2f770bfc1d24c0efb8da4a730da7d
+  metadata.gz: 629f1278b1f79497c95de696db6c46169b75995c34e69993508c12672227b2ebf3f8264a9ba228e001c83a68f2c352f3aa80a771ff729effd95b7d50e6ca0e2f
+  data.tar.gz: d0d7377ba225db508bcc46bf177a65518dcdade2beb6190b92ed2d5bb1b17367748f2f2f3a005daf46af329437c8ec4d80f3e452f626bda440bd96b60a442945

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # CHANGELOG
 
+## 6.0.1 (2026-10-05)
+
+* Discover batch item keys once per host and validate returned ownership, identities and duplicate targets before writes.
+* Snapshot item, interface and trigger definitions; reject non-scalar or non-positive IDs in single-host operations.
+* Report malformed high-level resource query responses as ProtocolError so batch reconciliation can isolate discovery failures.
+* Correlate request logs by request_id, suppress rejected method text, and avoid tag/serialization overhead for disabled severities.
+* Validate method encodings, Bearer-compatible tokens and logger severity setters before use while retaining Unicode password authentication.
+
+* Filter native SNMPv3 authentication/privacy passphrases and complete escaped quoted credentials in diagnostic logs.
+* Snapshot line definitions before discovery so caller mutations cannot change validated interfaces, identities or trigger attributes.
+* Use an ID index for traffic metadata ownership checks, avoiding quadratic lookups while preserving query order and missing-item states.
+* Correct Ruby layout violations to restore the existing RuboCop gate.
+
 ## 6.0.0 (2026-10-01)
 
 * Fix role ID queries and host-scoped value map identities, keeping immutable host fields out of updates.

data/README.md

@@ -89,9 +89,9 @@ zabbix = ZabbixManager.connect(
 )
 ```
 
-Logging uses `ActiveSupport::Logger` and `ActiveSupport::TaggedLogging`; structured credential filtering uses `ActiveSupport::ParameterFilter`. Pass `log_level: :info` to create a logger on standard error, or inject your application's logger. Logging is disabled unless one of these options is supplied, and logging failures do not change API outcomes.
+Logging uses `ActiveSupport::Logger` and `ActiveSupport::TaggedLogging`; structured credential filtering uses `ActiveSupport::ParameterFilter`. Pass `log_level: :info` to create a logger on standard error, or inject your application's logger. Logging is disabled unless one of these options is supplied, and logging failures do not change API outcomes. Request lifecycle events include a per-client `request_id` for correlation; request parameters and rejected method text are never logged. Disabled log severities skip tag construction and serialization. API tokens must contain printable ASCII characters without whitespace; username/password authentication continues to support Unicode.
 
-Passwords, API tokens, authorization values, cookies, and session IDs are filtered. Request parameters and response bodies are not logged. API exceptions expose the server error code and request ID, without remote messages or data that might echo arbitrary secrets. Malformed or mismatched JSON-RPC responses and invalid mutation ID receipts raise `ProtocolError < TransportError`: a write may already have happened, so it must not be blindly replayed.
+Passwords, API tokens, SNMPv3 authentication/privacy passphrases, authorization values, cookies, and session IDs are filtered. Quoted diagnostic credentials are filtered as complete values, including escaped quotes and backslashes. Request parameters and response bodies are not logged. API exceptions expose the server error code and request ID, without remote messages or data that might echo arbitrary secrets. Malformed or mismatched JSON-RPC responses and invalid mutation ID receipts raise `ProtocolError < TransportError`: a write may already have happened, so it must not be blindly replayed.
 
 HTTPS certificate verification is disabled by default as required by this project. Set `verify_ssl: true` (and optionally `ca_file:`) to enable peer verification.
 
@@ -232,6 +232,8 @@ Invalid caller input raises `ZabbixManager::Invalid`, ambiguous remote ownership
 
 `traffic.series` reads explicit item IDs; `traffic.for_interface` discovers both interface directions. Both expose missing data and query truncation, preserve numeric precision, and keep raw history separate from hourly trends. They never substitute zero or a stale last value for missing samples.
 
+Device and line definitions are copied before validation and discovery. Changes to caller-owned strings or nested fields during reconciliation do not alter the validated definition.
+
 Multiword resource accessors use Ruby snake_case: `host_groups`, `host_interfaces`, `http_tests`, `media_types`, `proxy_groups`, `user_groups`, `user_macros`, `value_maps`, and `discovery_rules`.
 
 The focused modules expose explicit operations:
@@ -243,8 +245,11 @@ The focused modules expose explicit operations:
 * `user_groups.replace_users`, `user_groups.replace_host_group_permissions`
 * `host_interfaces.for_host`, `host_interfaces.reconcile_for_host`, `host_interfaces.delete_many`
 * `items.for_host`, `items.upsert_by_key`, `items.upsert_many`, `items.set_status`, `items.delete_many`
+
 * `triggers.for_host`, `triggers.upsert_for_host`, `triggers.add_dependencies`, `triggers.replace_dependencies`, `triggers.set_status`, `triggers.delete_many`
 
+`items.upsert_many` discovers existing keys once per host before any write, then preserves input write order. Item and interface batch definitions are copied before discovery, including nested strings. Single-host helpers require a positive integer `hostid` or its decimal string representation. Identity lookup and batch helpers reject malformed query containers or required IDs with `ProtocolError`; `get_raw` preserves native response pass-through.
+
 
 ## Supported Ruby Versions
 The minimum Ruby version is **3.4**. CI runs Ruby 3.4 and 4.0.

data/lib/zabbix_manager/classes/host_interfaces.rb

@@ -24,11 +24,11 @@ class ZabbixManager
     # 查询指定主机的全部接口，可选择同时返回关联监控项。
     # @return [Array<Hash>]
     def for_host(hostid, select_items: nil)
-      raise Invalid, "hostid is required" if hostid.blank?
+      positive_id_attribute(hostid, "hostid")
 
       params = { hostids: hostid, output: "extend" }
       params[:selectItems] = select_items if select_items
-      @client.api_request(method: "hostinterface.get", params: params)
+      response_objects(@client.api_request(method: "hostinterface.get", params: params))
     end
 
     # 规范化并校验接口定义，不执行远端查询或写入。
@@ -67,7 +67,7 @@ class ZabbixManager
     def delete_many(hostid:, interfaceids:)
       ids = normalized_ids(interfaceids)
 
-      owned_ids = for_host(hostid).map { |interface| interface.fetch("interfaceid").to_s }
+      owned_ids = for_host(hostid).map { |interface| response_identifier(interface["interfaceid"]).to_s }
       foreign_ids = ids - owned_ids
       raise Conflict, "interfaces do not belong to host #{hostid}: #{foreign_ids.join(", ")}" if foreign_ids.any?
 
@@ -104,7 +104,7 @@ class ZabbixManager
     def normalize_definition(interface)
       raise Invalid, "interface must be a hash" unless interface.is_a?(Hash)
 
-      attributes = interface.deep_symbolize_keys
+      attributes = interface.deep_symbolize_keys.deep_dup
       if attributes.key?(:type)
         type = integer_attribute(attributes[:type], "interface type")
         raise Invalid, "interface type must be 1, 2, 3, or 4" unless [1, 2, 3, 4].include?(type)

data/lib/zabbix_manager/classes/hosts.rb

@@ -145,6 +145,7 @@ class ZabbixManager
     # 按主机 ID 查询唯一主机，并返回表达式需要的技术名称。
     # @return [Hash, nil]
     def find_by_id(hostid)
+      positive_id_attribute(hostid, "hostid")
       find_host_by_filter(hostid: hostid)
     end
 
@@ -233,6 +234,7 @@ class ZabbixManager
           selectInterfaces: %w[interfaceid ip dns]
         }
       )
+      response_objects(result)
       raise Conflict, "host lookup is ambiguous for #{filter.inspect}" if result.length > 1
 
       response_identifier(result.first["hostid"]) if result.first
@@ -247,6 +249,7 @@ class ZabbixManager
           method: "hostinterface.get",
           params: { filter: { field => candidate }, output: ["hostid"] }
         )
+        response_objects(result).each { |interface| response_identifier(interface["hostid"], "hostid") }
         matches.concat(result)
       end
       matches.uniq! { |interface| interface.fetch("hostid") }
@@ -264,6 +267,7 @@ class ZabbixManager
           filter: filter
         }
       )
+      response_objects(result)
       raise Conflict, "host lookup is ambiguous for #{filter.inspect}" if result.length > 1
 
       response_identifier(result.first["hostid"]).to_s if result.first

data/lib/zabbix_manager/classes/items.rb

@@ -41,22 +41,20 @@ class ZabbixManager
     # 查询主机监控项，可按稳定 key 集合过滤并选择关联对象。
     # @return [Array<Hash>]
     def for_host(hostid, keys: nil, output: "extend", select_preprocessing: nil, select_tags: nil)
-      raise Invalid, "hostid is required" if hostid.blank?
+      positive_id_attribute(hostid, "hostid")
 
       params = { hostids: hostid, output: output }
       params[:filter] = { key_: keys } if keys.present?
       params[:selectPreprocessing] = select_preprocessing if select_preprocessing
       params[:selectTags] = select_tags if select_tags
-      @client.api_request(method: "item.get", params: params)
+      response_objects(@client.api_request(method: "item.get", params: params))
     end
 
     # 按主机和稳定 key 查询唯一监控项。
     # @return [Hash, nil]
     def find_by_key(hostid:, key:)
       result = for_host(hostid, keys: key, output: "extend", select_preprocessing: "extend")
-      raise Conflict, "multiple items use key #{key} on host #{hostid}" if result.length > 1
-
-      result.first
+      index_items(result, hostid, [key])[key]
     end
 
     # 按 hostid + key_ 幂等创建或更新监控项。
@@ -70,11 +68,15 @@ class ZabbixManager
     # @return [Array<Integer>]
     def upsert_many(collection)
       items = Array(collection).map { |data| validate_item!(data) }
-      identities = items.map { |item| [item[:hostid].to_s, item[:key_].to_s] }
+      identities = items.map { |item| [positive_id_attribute(item[:hostid], "hostid").to_s, item[:key_]] }
       duplicate = identities.tally.find { |_identity, count| count > 1 }&.first
       raise Invalid, "duplicate hostid + key_ identity #{duplicate.join(":")}" if duplicate
 
-      plans = items.map { |item| plan_item(item) }
+      existing = batch_items(items)
+      plans = items.map do |item|
+        identity = [positive_id_attribute(item[:hostid], "hostid").to_s, item[:key_]]
+        plan_item(item, existing[identity])
+      end
       if block_given?
         effective = plans.map do |attributes, current|
           if current && !%w[type value_type].all? { |field| current.key?(field) }
@@ -114,6 +116,7 @@ class ZabbixManager
     # 方向和接口精确匹配由 Monitoring 业务层负责。
     # @return [Array<Hash>]
     def monitored_traffic_candidates(hostid)
+      positive_id_attribute(hostid, "hostid")
       @client.api_request(
         method: "item.get",
         params: {
@@ -150,9 +153,44 @@ class ZabbixManager
 
     private
 
+    # 每个主机只读取一次期望 key 集合，全部发现和校验完成后才开始写入。
+    def batch_items(items)
+      groups = items.group_by { |item| positive_id_attribute(item[:hostid], "hostid").to_s }
+      ids = {}
+      groups.each_with_object({}) do |(owner, definitions), result|
+        hostid = definitions.first[:hostid]
+        keys = definitions.map { |item| item[:key_] }
+        rows = for_host(hostid, keys: keys, select_preprocessing: "extend")
+        index_items(rows, hostid, keys).each do |key, row|
+          id = response_identifier(row["itemid"])
+          raise ProtocolError, "item.get returned duplicate item IDs across hosts" if ids.key?(id)
+
+          ids[id] = true
+          result[[owner, key]] = row
+        end
+      end
+    end
+
+    # 不信任服务端过滤器：返回项必须位于所请求的主机和 key 集合中。
+    def index_items(rows, hostid, keys)
+      owner = positive_id_attribute(hostid, "hostid")
+      requested = keys.to_h { |key| [key, true] }
+      ids = {}
+      response_objects(rows).each_with_object({}) do |row, result|
+        id = response_identifier(row["itemid"])
+        unless response_identifier(row["hostid"], "hostid") == owner && requested.key?(row["key_"])
+          raise ProtocolError, "item.get returned an item outside the requested host and keys"
+        end
+        raise Conflict, "multiple items use the same key on host #{hostid}" if result.key?(row["key_"])
+        raise ProtocolError, "item.get returned duplicate item IDs" if ids.key?(id)
+
+        ids[id] = true
+        result[row["key_"]] = row
+      end
+    end
+
     # 创建必填字段必须在整批写入开始前校验。
-    def plan_item(attributes)
-      current = find_by_key(hostid: attributes[:hostid], key: attributes[:key_])
+    def plan_item(attributes, current = find_by_key(hostid: attributes[:hostid], key: attributes[:key_]))
       validate_item_type!(attributes[:type]) if attributes.key?(:type)
       response_identifier(current["itemid"]) if current
       unless current
@@ -177,10 +215,15 @@ class ZabbixManager
     # @return [Hash]
     # @api private
     def validate_item!(data)
-      attributes = data.deep_symbolize_keys
-      raise Invalid, "hostid is required" if attributes[:hostid].blank?
-      raise Invalid, "key_ is required" if attributes[:key_].blank?
-      raise Invalid, "name is required" if attributes[:name].blank?
+      raise Invalid, "item must be a hash" unless data.is_a?(Hash)
+
+      attributes = data.deep_symbolize_keys.deep_dup
+      positive_id_attribute(attributes[:hostid], "hostid")
+      %i[key_ name].each do |field|
+        unless attributes[field].is_a?(String) && attributes[field].present?
+          raise Invalid, "#{field} must be a non-empty string"
+        end
+      end
 
       attributes
     end
@@ -216,12 +259,12 @@ class ZabbixManager
 
     # 回查监控项归属，阻止共享高权限令牌跨主机修改。
     def verify_host_ownership!(hostid, ids)
-      raise Invalid, "hostid is required" if hostid.blank?
+      positive_id_attribute(hostid, "hostid")
 
       result = @client.api_request(
         method: "item.get", params: { hostids: hostid, itemids: ids, output: ["itemid"] }
       )
-      owned_ids = result.map { |item| item.fetch("itemid").to_s }
+      owned_ids = response_objects(result).map { |item| response_identifier(item["itemid"]).to_s }
       foreign_ids = ids - owned_ids
       raise Conflict, "items do not belong to host #{hostid}: #{foreign_ids.join(", ")}" if foreign_ids.any?
     end

data/lib/zabbix_manager/classes/proxies.rb

@@ -54,6 +54,8 @@ class ZabbixManager
           }
         }
       )
+      result = response_objects(result)
+      result.each { |proxy_data| response_identifier(proxy_data["proxyid"]) }
       raise Conflict, "proxy lookup is ambiguous for #{proxy}" if result.length > 1
 
       result.first&.fetch("proxyid", nil)

data/lib/zabbix_manager/classes/triggers.rb

@@ -43,7 +43,7 @@ class ZabbixManager
     # @return [Array<Hash>]
     def for_host(hostid, output: "extend", select_items: nil, select_functions: nil,
                  select_dependencies: nil, select_tags: nil, filter: nil)
-      raise Invalid, "hostid is required" if hostid.blank?
+      positive_id_attribute(hostid, "hostid")
 
       params = { hostids: hostid, output: output }
       params[:selectItems] = select_items if select_items
@@ -51,12 +51,13 @@ class ZabbixManager
       params[:selectDependencies] = select_dependencies if select_dependencies
       params[:selectTags] = select_tags if select_tags
       params[:filter] = filter if filter.present?
-      @client.api_request(method: "trigger.get", params: params)
+      response_objects(@client.api_request(method: "trigger.get", params: params))
     end
 
     # 按主机、描述和可选标签查询唯一触发器。
     # @return [Hash, nil]
     def find_for_host(hostid:, description:, tags: nil)
+      positive_id_attribute(hostid, "hostid")
       params = {
         hostids: hostid,
         filter: { description: description },
@@ -68,6 +69,8 @@ class ZabbixManager
         method: "trigger.get",
         params: params
       )
+      response_objects(result)
+      result.each { |trigger| response_identifier(trigger["triggerid"]) }
       raise Conflict, "multiple triggers match #{description} on host #{hostid}" if result.length > 1
 
       result.first
@@ -79,6 +82,7 @@ class ZabbixManager
     # @param managed_key [String] 稳定、非秘密的受管身份
     # @return [Hash, nil]
     def find_managed_for_host(hostid:, managed_key:)
+      positive_id_attribute(hostid, "hostid")
       result = @client.api_request(
         method: "trigger.get",
         params: {
@@ -90,6 +94,8 @@ class ZabbixManager
           selectTags: "extend"
         }
       )
+      response_objects(result)
+      result.each { |trigger| response_identifier(trigger["triggerid"]) }
       raise Conflict, "multiple triggers use managed key #{managed_key}" if result.length > 1
 
       result.first
@@ -101,7 +107,12 @@ class ZabbixManager
       id = normalized_ids([triggerid]).first
       params = { triggerids: id, output: "extend" }
       params[:selectDependencies] = select_dependencies if select_dependencies
-      result = @client.api_request(method: "trigger.get", params: params)
+      result = response_objects(@client.api_request(method: "trigger.get", params: params))
+      result.each do |trigger|
+        unless response_identifier(trigger["triggerid"]).to_s == id
+          raise ProtocolError, "trigger.get returned an unexpected trigger ID"
+        end
+      end
       raise Conflict, "multiple triggers use triggerid #{id}" if result.length > 1
 
       result.first
@@ -111,7 +122,8 @@ class ZabbixManager
     # 可通过 Client 的 upsert_lock 接入跨进程锁。
     # @return [Integer]
     def upsert_for_host(data)
-      attributes = data.deep_symbolize_keys
+      attributes = data.deep_symbolize_keys.deep_dup
+      positive_id_attribute(attributes[:hostid], "hostid")
       lock_key = "trigger:#{attributes[:hostid]}:#{attributes[:managed_key] || attributes[:description]}"
       @client.with_upsert_lock(lock_key) { perform_upsert_for_host(attributes) }
     end
@@ -185,7 +197,7 @@ class ZabbixManager
       attributes = data.deep_symbolize_keys
       hostid = attributes.delete(:hostid)
       managed_key = attributes.delete(:managed_key)&.to_s
-      raise Invalid, "hostid is required" if hostid.blank?
+      positive_id_attribute(hostid, "hostid")
       raise Invalid, "description is required" if attributes[:description].blank?
       raise Invalid, "expression is required" if attributes[:expression].blank?
 
@@ -228,7 +240,7 @@ class ZabbixManager
 
       raise ResultUnknown,
             "trigger create result is unknown; inspect managed key #{managed_key.inspect} before retrying: " \
-            "#{original_error.message}"
+              "#{original_error.message}"
     end
 
     # 对结果不确定的创建执行短暂退避回读，不重放写请求。
@@ -269,12 +281,12 @@ class ZabbixManager
 
     # 回查触发器归属，阻止共享高权限令牌跨主机修改。
     private def verify_host_ownership!(hostid, ids)
-      raise Invalid, "hostid is required" if hostid.blank?
+      positive_id_attribute(hostid, "hostid")
 
       result = @client.api_request(
         method: "trigger.get", params: { hostids: hostid, triggerids: ids, output: ["triggerid"] }
       )
-      owned_ids = result.map { |trigger| trigger.fetch("triggerid").to_s }
+      owned_ids = response_objects(result).map { |trigger| response_identifier(trigger["triggerid"]).to_s }
       foreign_ids = ids - owned_ids
       raise Conflict, "triggers do not belong to host #{hostid}: #{foreign_ids.join(", ")}" if foreign_ids.any?
     end

data/lib/zabbix_manager/classes/user_groups.rb

@@ -40,7 +40,7 @@ class ZabbixManager
       group_ids = collection_ids(user_group_ids, "user_group_ids")
       users = collection_ids(user_ids, "user_ids", allow_empty: true)
       membership = api_version >= Gem::Version.new("6.0") ?
-        { users: users.map { |id| { userid: id } } } : { userids: users }
+                     { users: users.map { |id| { userid: id } } } : { userids: users }
       result = @client.api_request(
         method: "usergroup.update",
         params: group_ids.map { |id| membership.merge(usrgrpid: id) }

data/lib/zabbix_manager/classes/user_macros.rb

@@ -96,6 +96,7 @@ class ZabbixManager
     private
 
     def unique_macro_id(result, id_field)
+      response_objects(result)
       raise Conflict, "multiple macros match the requested identity" if result.length > 1
 
       response_identifier(result.first[id_field], id_field) if result.first

data/lib/zabbix_manager/client.rb

@@ -12,6 +12,9 @@ class ZabbixManager
     SUPPORTED_MAJOR_VERSIONS = (4..7)
     UNAUTHENTICATED_METHODS = %w[apiinfo.version user.login].freeze
     UPSERT_MUTEX_STRIPES = 64
+    LOG_LEVELS = { debug: Logger::DEBUG, info: Logger::INFO, warn: Logger::WARN,
+                   error: Logger::ERROR, fatal: Logger::FATAL, unknown: Logger::UNKNOWN }.freeze
+    private_constant :LOG_LEVELS
 
     attr_reader :options, :logger, :api_version
 
@@ -54,16 +57,20 @@ class ZabbixManager
     # @raise [ApiError] 服务器明确拒绝请求
     # @raise [TransportError, ProtocolError] 未收到能够确认结果的有效响应
     def api_request(method:, params: {})
+      method = method.dup.freeze if method.is_a?(String)
       validate_request!(method, params)
       started_at = monotonic_time
       message = request_message(method, params)
-      log(:debug, "request.started", method: method)
+      log(:debug, "request.started", method: method, request_id: message[:id])
       body = @transport.request(JSON.generate(message), bearer_token: bearer_token_for(method))
       result = parse_response(body, message.fetch(:id))
-      log(:info, "request.completed", method: method, duration_ms: elapsed_ms(started_at))
+      log(:info, "request.completed", method: method, request_id: message[:id], duration_ms: elapsed_ms(started_at))
       result
     rescue StandardError => error
-      log(:warn, "request.failed", method: method, duration_ms: elapsed_ms(started_at), error: error.class.name)
+      if started_at
+        log(:warn, "request.failed", method: method, request_id: message&.fetch(:id),
+                                     duration_ms: elapsed_ms(started_at), error: error.class.name)
+      end
       raise
     end
 
@@ -92,6 +99,9 @@ class ZabbixManager
     def log(level, event, data = {})
       return unless @logger
 
+      severity = LOG_LEVELS[level]
+      return if severity && @logger.respond_to?(:level) && @logger.level > severity
+
       @logger.tagged("zabbix_manager") do
         @logger.public_send(level) { JSON.generate(LogSanitizer.sanitize(data.merge(event: event))) }
       end
@@ -140,7 +150,9 @@ class ZabbixManager
     end
 
     def validate_request!(method, params)
-      unless method.is_a?(String) && method.match?(/\A[a-z][a-z0-9_]*\.[a-z][a-zA-Z0-9_]*\z/)
+      valid_method = method.is_a?(String) && method.valid_encoding? && method.ascii_only? &&
+                     method.match?(/\A[a-z][a-z0-9_]*\.[a-z][a-zA-Z0-9_]*\z/)
+      unless valid_method
         raise Invalid, "method must be a Zabbix API method name"
       end
       raise Invalid, "params must be a Hash or Array" unless params.is_a?(Hash) || params.is_a?(Array)

data/lib/zabbix_manager/configuration.rb

@@ -56,6 +56,12 @@ class ZabbixManager
         value = @options[key]
         raise Invalid, "#{key} must be a String" unless value.nil? || value.is_a?(String)
 
+        if key == :api_token && value && !value.empty?
+          unless value.valid_encoding? && value.ascii_only? && value.match?(/\A[!-~]+\z/)
+            raise Invalid, "api_token must contain printable ASCII characters without whitespace"
+          end
+        end
+
         @options.delete(key) if value.blank?
       end
       raise Invalid, "url is required" if @options[:url].blank?
@@ -99,7 +105,9 @@ class ZabbixManager
       raise Invalid, "upsert_lock must respond to call(key, &block)" if lock && !lock.respond_to?(:call)
 
       logger = @options[:logger]
-      return if logger.nil? || %i[debug info warn formatter formatter=].all? { |method| logger.respond_to?(method) }
+      required = %i[debug info warn formatter formatter=]
+      required << :level= if @options.key?(:log_level)
+      return if logger.nil? || required.all? { |method| logger.respond_to?(method) }
 
       raise Invalid, "logger must support the Ruby Logger interface"
     end

data/lib/zabbix_manager/log_sanitizer.rb

@@ -9,9 +9,9 @@ class ZabbixManager
   module LogSanitizer
     REDACTED = "[FILTERED]"
     MAX_STRING_LENGTH = 2_000
-    SENSITIVE_KEY_NAMES = "auth|authorization|api_token|community|cookie|http_password|password|passwd|" \
-                          "privatekey|secret|sessionid|snmp_community|snmpv3_authpassphrase|" \
-                          "snmpv3_privpassphrase|tls_psk|tls_psk_identity|token"
+    SENSITIVE_KEY_NAMES = "auth|authorization|authpassphrase|api_token|community|cookie|" \
+      "http_password|password|passwd|privatekey|privpassphrase|secret|sessionid|snmp_community|snmpv3_authpassphrase|" \
+      "snmpv3_privpassphrase|tls_psk|tls_psk_identity|token"
     SENSITIVE_KEYS = /\A(?:#{SENSITIVE_KEY_NAMES})\z/i
     FILTER = ActiveSupport::ParameterFilter.new(
       [SENSITIVE_KEYS, ->(_key, value) { value.replace(sanitize_string(value)) if value.is_a?(String) }]
@@ -39,19 +39,18 @@ class ZabbixManager
     # 清理字符串中的认证头和常见敏感键值。
     def sanitize_string(value)
       sanitized = value.dup
-      sanitized.gsub!(/\b(Bearer|Basic)\s+[^\s,;]+/i, "\\1 #{REDACTED}")
+      # 先处理完整引号值，避免认证头规则在值内的分隔符处截断秘密。
       sanitized.gsub!(
-        /((?:authorization)["']?\s*(?:=>|:|=)\s*)[^,;}\]]+/i,
-        "\\1#{REDACTED}"
-      )
-      sanitized.gsub!(
-        /((?:#{SENSITIVE_KEY_NAMES})["']?\s*(?:=>|:|=)\s*)(["'])(.*?)\2/i,
+        /((?:#{SENSITIVE_KEY_NAMES})["']?\s*(?:=>|:|=)\s*)(["'])((?:\\.|(?!\2)[^\\])*)\2/im,
         "\\1\\2#{REDACTED}\\2"
       )
       sanitized.gsub!(
-        /((?:#{SENSITIVE_KEY_NAMES})["']?\s*(?:=>|:|=)\s*)(?!["'])[^,;}\]]+/i,
+        /((?:#{SENSITIVE_KEY_NAMES})["']?\s*(?:=>|:|=)\s*+)
+         (?!["']|#{Regexp.escape(REDACTED)}(?=[,;}\]]|\z))
+         (?:#{Regexp.escape(REDACTED)}|[^,;}\]])+/ix,
         "\\1#{REDACTED}"
       )
+      sanitized.gsub!(/\b(Bearer|Basic)\s+[^\s,;]+/i, "\\1 #{REDACTED}")
       sanitized.length > MAX_STRING_LENGTH ? "#{sanitized[0, MAX_STRING_LENGTH]}...[TRUNCATED]" : sanitized
     end
   end

data/lib/zabbix_manager/monitoring/device.rb

@@ -213,8 +213,9 @@ class ZabbixManager
 
         @attributes[:macros] = Validation.array!(@attributes[:macros], "macros").map do |macro|
           value = Validation.hash!(macro, "macro")
-          raise Invalid, "macros accept macro, value, type and description" if
-            (value.keys - %i[macro value type description]).any?
+          if (value.keys - %i[macro value type description]).any?
+            raise Invalid, "macros accept macro, value, type and description"
+          end
           unless value[:macro].is_a?(String) && value[:macro].match?(/\A\{\$[^{}\r\n]+\}\z/)
             raise Invalid, "macro name must use {$NAME} syntax"
           end

data/lib/zabbix_manager/monitoring/line.rb

@@ -14,11 +14,12 @@ class ZabbixManager
       attr_reader :host_reference, :interface_name, :threshold, :low_traffic, :status, :speed,
                   :reachability_target, :metadata
 
+      # 保存调用方定义的独立快照；等待锁和远端发现期间不重新读取可变输入。
       # 仅解析本地定义，不访问服务器；status/speed 为开关或显式 itemid 选择器。
       # @param attributes [Hash] 规范化后的单端点清单字段
       # @raise [Invalid] 字段、阈值或目标格式不合法
       def initialize(attributes)
-        @attributes = Validation.hash!(attributes, "line")
+        @attributes = Validation.hash!(attributes, "line").deep_dup
         @attributes.assert_valid_keys(*FIELDS)
         @interface_name = Validation.text!(@attributes[:interface_name], "line interface_name")
         validate_identity!
@@ -88,7 +89,7 @@ class ZabbixManager
         end
 
         candidates = @attributes.key?(:host_candidates) ?
-          Validation.array!(@attributes[:host_candidates], "host_candidates") : [host]
+                       Validation.array!(@attributes[:host_candidates], "host_candidates") : [host]
         candidates = candidates.map { |value| Validation.text!(value, "line host candidate").strip }.uniq
         raise Invalid, "line host candidate is required" if candidates.empty?
 

data/lib/zabbix_manager/monitoring/traffic_items.rb

@@ -102,6 +102,7 @@ class ZabbixManager
         counter_direction(item[:snmp_oid]) || item[:key_].to_s.match?(/if(?:hc)?(in|out)octets/i) ||
           (%w[0 7].include?(item[:type].to_s) && item[:key_].match?(/\Anet\.if\.(in|out)\[/))
       end
+
       private_class_method :raw_counter?
 
       private

data/lib/zabbix_manager/resource.rb

@@ -73,7 +73,9 @@ class ZabbixManager
 
       normalized_ids([id])
 
-      current = dump_by_id(key.to_sym => id).find { |item| item.fetch(key).to_s == id.to_s }
+      current = response_objects(dump_by_id(key.to_sym => id)).find do |item|
+        response_identifier(item[key]) == id.to_i
+      end
       return id.to_i if current && attributes_match?(current, attributes)
 
       response_id(update_raw([attributes]), expected: [id])
@@ -83,7 +85,7 @@ class ZabbixManager
     # @param data [Hash] 包含 identify 指定的业务标识
     # @return [Array<Hash>]
     def get_full_data(data)
-      get_raw(filter: identity_filter(data), output: "extend")
+      response_objects(get_raw(filter: identity_filter(data), output: "extend"))
     end
 
     # 按对象 ID 查询完整对象。
@@ -94,13 +96,16 @@ class ZabbixManager
       id = attributes[key.to_sym]
       raise Invalid, "#{key} is required" if id.blank?
 
-      get_raw(filter: { key.to_sym => id }, output: "extend")
+      response_objects(get_raw(filter: { key.to_sym => id }, output: "extend"))
     end
 
     # @return [Hash] 业务标识到原生字符串 ID 的映射
     # @raise [Conflict] 多个资源具有相同业务标识
     def all
-      get_raw(output: "extend").each_with_object({}) do |item, result|
+      response_objects(get_raw(output: "extend")).each_with_object({}) do |item, result|
+        response_identifier(item[key])
+        raise ProtocolError, "invalid #{method_name} response: #{identify} is missing" unless item.key?(identify)
+
         name = item.fetch(identify)
         raise Conflict, "multiple #{method_name} objects share the same identity" if result.key?(name)
 
@@ -116,7 +121,12 @@ class ZabbixManager
       name = attributes[identify.to_sym]
       raise Invalid, "#{identify} not supplied in call to get_id" if name.nil?
 
-      matches = get_raw(filter: attributes, output: [key, identify]).select do |item|
+      rows = response_objects(get_raw(filter: attributes, output: [key, identify]))
+      rows.each do |item|
+        response_identifier(item[key])
+        raise ProtocolError, "invalid #{method_name} response: #{identify} is missing" unless item.key?(identify)
+      end
+      matches = rows.select do |item|
         item[identify].to_s == name.to_s
       end
       raise Conflict, "multiple #{method_name} objects match the requested identity" if matches.length > 1
@@ -163,6 +173,23 @@ class ZabbixManager
 
     private
 
+    # 高层查询必须区分空结果与损坏的响应；原生 get_raw 保持透传。
+    def response_objects(result)
+      unless result.is_a?(Array) && result.all? { |object| object.is_a?(Hash) }
+        raise ProtocolError, "invalid #{method_name} response: expected an array of objects"
+      end
+
+      result
+    end
+
+    # 单对象查询边界不能接受 ID 集合、布尔值或浮点数。
+    def positive_id_attribute(value, name)
+      id = integer_attribute(value, name)
+      raise Invalid, "#{name} must be a positive integer" unless id.positive?
+
+      id
+    end
+
     def validate_boolean!(value, name)
       raise Invalid, "#{name} must be true or false" unless value == true || value == false
     end

data/lib/zabbix_manager/traffic.rb

@@ -108,6 +108,7 @@ class ZabbixManager
 
     # 显式主机过滤和响应归属检查保证外部 itemid 不能越过查询边界。
     def items_for_host(hostid, ids)
+      requested_ids = ids.to_h { |id| [id, true] }
       rows = @manager.query(method: "item.get", params: {
                               hostids: [hostid], itemids: ids, monitored: true,
                               output: %w[itemid hostid name units value_type]
@@ -115,7 +116,7 @@ class ZabbixManager
       response_rows!(rows, "item.get").each_with_object({}) do |item, result|
         id = response_integer!(item["itemid"], "itemid", positive: true).to_s
         owner = response_integer!(item["hostid"], "hostid", positive: true).to_s
-        unless ids.include?(id) && owner == hostid && !result.key?(id)
+        unless requested_ids.key?(id) && owner == hostid && !result.key?(id)
           raise ProtocolError, "item.get returned unexpected or duplicate item ownership"
         end
         unless item["name"].is_a?(String) && item["units"].is_a?(String)

data/lib/zabbix_manager/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  VERSION = "6.0.0"
+  VERSION = "6.0.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zabbix_manager
 version: !ruby/object:Gem::Version
-  version: 6.0.0
+  version: 6.0.1
 platform: ruby
 authors:
 - WENWU YAN