baseline-rb 0.1.0

data/lib/baseline/acl.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Baseline
+  # 按首次匹配规则分析 IPv4 来源 ACL；不支持的语法保持未知。
+  class Acl
+    attr_reader :name, :rules, :line, :supported
+
+    # 冻结有序 ACL 规则及其来源、支持状态。
+    def initialize(name:, rules:, line:, supported: true)
+      @name, @rules, @line, @supported = name.freeze, Baseline.immutable(rules), line, supported
+      freeze
+    end
+
+    # 按 ACL 顺序匹配语义计算允许访问的来源范围。
+    def sources(protocol:, port: nil)
+      return unless supported && rules.any?
+      selected = rules.sort_by { |rule| rule.fetch(:sequence) }.select do |rule|
+        next unless [ "ip", protocol ].include?(rule.fetch(:protocol))
+        if rule[:destination_port]
+          return if port.nil?
+          next unless rule[:destination_port] == port
+        end
+        true
+      end
+      self.class.networks(permitted_ranges(selected))
+    end
+
+    # 返回公开的数据结构，并保留状态与诊断信息。
+    def to_h = { name: name, rules: rules, line: line, supported: supported }
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class} name=#{name} rules=#{rules.size} supported=#{supported}>"
+
+    # 归一化 ACL 来源地址；不推测不支持语法的含义。
+    def self.source(address, wildcard = nil)
+      return "0.0.0.0/0" if address == "any"
+      ip = IPAddr.new(address)
+      raise ArgumentError, "IPv4 ACL required" unless ip.ipv4?
+      if wildcard
+        mask = IPAddr.new(wildcard == "0" ? "0.0.0.0" : wildcard)
+        value = mask.to_i
+        raise ArgumentError, "Noncontiguous wildcard" unless mask.ipv4? && (value & (value + 1)).zero?
+        prefix = 32 - value.bit_length
+        ip = ip.mask(prefix)
+      end
+      "#{ip}/#{ip.prefix}"
+    end
+
+    # 将网络前缀转换为包含首尾地址的整数区间。
+    def self.range(cidr)
+      ip = IPAddr.new(cidr)
+      raise ArgumentError, "IPv4 ACL required" unless ip.ipv4?
+      [ ip.to_range.first.to_i, ip.to_range.last.to_i ]
+    end
+
+    # 通过地址区间相减，检查实际来源是否包含于策略批准的网段。
+    def self.subtract(ranges, removed)
+      removed.reduce(ranges) do |remaining, (left, right)|
+        remaining.flat_map do |first, last|
+          if right < first || left > last
+            [ [ first, last ] ]
+          else
+            [ ([ first, left - 1 ] if left > first), ([ right + 1, last ] if right < last) ].compact
+          end
+        end
+      end
+    end
+
+    # 判断所有实际来源范围是否均在允许范围内。
+    def self.within?(actual, expected)
+      subtract(actual.map { |cidr| range(cidr) }, expected.map { |cidr| range(cidr) }).empty?
+    end
+
+    # 将地址区间转换为数量最少的网络前缀。
+    def self.networks(ranges)
+      merged = ranges.sort.each_with_object([]) do |(first, last), result|
+        if result.any? && first <= result.last.last + 1
+          result.last[1] = [ result.last.last, last ].max
+        else
+          result << [ first, last ]
+        end
+      end
+      merged.flat_map do |first, last|
+        networks = []
+        while first <= last
+          aligned = first.zero? ? 32 : (first & -first).bit_length - 1
+          bits = [ aligned, (last - first + 1).bit_length - 1 ].min
+          networks << "#{IPAddr.new(first, Socket::AF_INET)}/#{32 - bits}"
+          first += 1 << bits
+        end
+        networks
+      end
+    end
+
+    private
+
+    # 按地址边界扫描一次；每个区间由最先匹配的生效规则决定。
+    def permitted_ranges(selected)
+      boundaries = Hash.new { |entries, address| entries[address] = [] }
+      selected.each_with_index do |rule, priority|
+        first, last = self.class.range(rule.fetch(:source))
+        boundaries[first] << [ priority, true ]
+        # 将闭区间终点转为下一地址的失效事件，统一处理相邻和重叠网段。
+        boundaries[last + 1] << [ priority, false ]
+      end
+      active, priorities, permitted = [], [], []
+      boundaries.keys.sort.each_cons(2) do |first, following|
+        boundaries.fetch(first).each do |priority, enabled|
+          active[priority] = enabled
+          push_priority(priorities, priority) if enabled
+        end
+        # 堆顶始终是配置顺序最靠前的生效规则，保持 ACL 首次匹配语义。
+        pop_priority(priorities) while priorities.any? && !active[priorities.first]
+        if priorities.any? && selected.fetch(priorities.first).fetch(:action) == "permit"
+          permitted << [ first, following - 1 ]
+        end
+      end
+      permitted
+    end
+
+    # 使用二叉最小堆维护规则优先级，避免反复排序生效规则。
+    def push_priority(heap, priority)
+      index = heap.size
+      heap << priority
+      while index.positive?
+        parent = (index - 1) / 2
+        break if heap[parent] <= priority
+        heap[index] = heap[parent]
+        index = parent
+      end
+      heap[index] = priority
+    end
+
+    # 移除已失效的堆顶规则；其他失效规则在升至堆顶时再清理。
+    def pop_priority(heap)
+      last = heap.pop
+      return if heap.empty?
+
+      index = 0
+      while (child = index * 2 + 1) < heap.size
+        child += 1 if child + 1 < heap.size && heap[child + 1] < heap[child]
+        break if last <= heap[child]
+        heap[index] = heap[child]
+        index = child
+      end
+      heap[index] = last
+    end
+  end
+end

data/lib/baseline/audit.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Baseline
+  # 仅分析传入文本，不读取文件、访问数据库、连接设备或执行修复。
+  class Audit
+    PARSERS = { "h3c" => Parsers::H3c, "huawei" => Parsers::Huawei,
+      "cisco_ios" => Parsers::CiscoIos, "cisco_nxos" => Parsers::CiscoNxos,
+      "hillstone" => Parsers::Hillstone, "palo_alto" => Parsers::PaloAlto }.freeze
+    ALIASES = { "h3c_wireless" => "h3c", "comware" => "h3c", "huawei_wireless" => "huawei", "vrp" => "huawei",
+      "ios" => "cisco_ios", "iosxe" => "cisco_ios", "ios_xe" => "cisco_ios", "cisco_ios_xe" => "cisco_ios",
+      "nxos" => "cisco_nxos", "nx_os" => "cisco_nxos", "stoneos" => "hillstone", "stone_os" => "hillstone",
+      "paloalto" => "palo_alto", "panos" => "palo_alto", "pan_os" => "palo_alto" }.freeze
+
+    # 绑定配置解析与基线评估使用的策略。
+    def initialize(policy:)
+      @evaluator = Evaluator.new(policy: policy)
+    end
+
+    # 解析配置证据，并评估适用的基线规则。
+    def call(configuration:, platform:, complete: false, context: {})
+      unless configuration.is_a?(String) && (platform.is_a?(String) || platform.is_a?(Symbol)) && [ true, false ].include?(complete)
+        raise ArgumentError, "Configuration text, platform and boolean completeness are required"
+      end
+      name = platform.to_s.strip.downcase.tr("-", "_")
+      name = ALIASES.fetch(name, name)
+      parser = PARSERS[name]
+      result = parser ? parser.parse(configuration, complete: complete) :
+        CtxParser::Result.new(status: :unsupported, issues: [ { code: :unsupported_platform } ])
+      facts = Configuration.new(platform: name, sha256: Digest::SHA256.hexdigest(configuration), result: result)
+      @evaluator.call(configuration: facts, context: context)
+    end
+
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class}>"
+  end
+end

data/lib/baseline/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Baseline
+  # 在归一化配置中区分输入完整性、已知事实与局部不支持的语法。
+  class Configuration
+    PARTIAL_SCOPE_FACTS = { "snmp.enabled" => true, "snmp.community_present" => true, "credentials.present" => true,
+      "snmp.write_enabled" => true, "credentials.storage_safe" => false }.freeze
+    attr_reader :platform, :sha256, :status, :facts, :sources, :issues
+
+    # 冻结配置事实及其平台、来源身份。
+    def initialize(platform:, sha256:, result:)
+      @platform, @sha256, @status = platform.dup.freeze, sha256.dup.freeze, result.status
+      record = result.records.first || {}
+      @facts = Baseline.immutable(record.fetch("facts", {}))
+      @sources = Baseline.immutable(record.fetch("sources", {}))
+      @issues = Baseline.immutable(result.issues)
+      freeze
+    end
+
+    # 判断配置采集与解析是否均已完成。
+    def complete? = status == :complete
+    # 读取已知值，同时保留事实缺失或未知的区别。
+    def value(path) = facts[path]
+
+    # 区分明确已知的事实与缺失、不支持的配置证据。
+    def known?(path)
+      facts.key?(path) && issues.none? do |issue|
+        scope = issue[:fact]
+        scope && (path == scope || path.start_with?("#{scope}."))
+      end
+    end
+
+    # 局部输入可证明存在或明确违规，但不能证明缺失或所有成员均满足条件。
+    def scope_known?(path)
+      return false unless known?(path)
+      return true if complete?
+      return false unless status == :partial
+
+      path == "hostname" || PARTIAL_SCOPE_FACTS.key?(path) && PARTIAL_SCOPE_FACTS[path] == value(path)
+    end
+
+    # 返回公开的数据结构，并保留状态与诊断信息。
+    def to_h
+      { platform: platform, sha256: sha256, status: status, facts: facts, sources: sources, issues: issues }
+    end
+
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class} platform=#{platform} status=#{status} facts=#{facts.size}>"
+  end
+end

data/lib/baseline/credential.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Baseline
+  # 仅在构造时分析凭据，不保留明文、密文或可枚举的摘要。
+  class Credential
+    COMMON = %w[admin administrator password passwd public private cisco huawei h3c root guest test 123456 12345678 123456789 1234567890 qwerty welcome changeme].freeze
+    attr_reader :attributes
+
+    # 提取可安全报告的凭据属性，随后丢弃传入的秘密值。
+    def initialize(owner:, kind:, format:, secret:, line:)
+      storage = case format.to_s
+      when "plain", "simple", "0" then "plaintext"
+      when "4", "5", "7" then "legacy"
+      when "6", "8", "9", "hash", "cipher", "irreversible-cipher" then "protected"
+      else "unknown"
+      end
+      values = { owner: owner, kind: kind, storage: storage, format: format.to_s, present: !secret.to_s.empty?, line: line }
+      if storage == "plaintext"
+        text = secret.to_s
+        values.merge!(length: text.length, character_classes: [ /[a-z]/, /[A-Z]/, /\d/, /[^a-zA-Z\d]/ ].count { |pattern| pattern.match?(text) },
+          common: COMMON.include?(text.downcase) || text.downcase == owner.to_s.downcase || /\A(.)\1+\z/.match?(text))
+      end
+      @attributes = Baseline.immutable(values)
+      freeze
+    end
+
+    # 返回公开的数据结构，并保留状态与诊断信息。
+    def to_h = attributes
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class} kind=#{attributes[:kind]} storage=#{attributes[:storage]}>"
+  end
+end

data/lib/baseline/document.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "ctx_parser/document"
+require "ctx_parser/banner"
+
+module Baseline
+  # 复用游标与配置树，识别厂商注释、横幅及不完整回显。
+  class Document < CtxParser::Document
+    protected
+
+    # 区分配置结构行与引号、横幅中的文本内容。
+    def classify(line)
+      text = line.text
+      return :ignored if text.empty?
+      @banner ||= CtxParser::Banner.new
+      return :ignored if @banner.consume(text)
+      if /--\s*More\s*--|\e\[|\A(?:%\s*(?:Invalid|Incomplete|Ambiguous)|Error:)/i.match?(text)
+        issues << { code: :incomplete_configuration, line: line.number }
+        return :ignored
+      end
+      return :boundary if text.start_with?("!", "#") || %w[end return].include?(text)
+      return :ignored if /\A(?:Building configuration|Current configuration)/i.match?(text)
+
+      :entry
+    end
+
+    # 报告配置文档结束时仍未闭合的横幅。
+    def finish
+      issues << { code: :incomplete_banner } if @banner&.open?
+    end
+  end
+end

data/lib/baseline/evaluator.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Baseline
+  # 根据策略评估归一化事实；厂商语法差异由解析器负责。
+  class Evaluator
+    # 绑定归一化证据评估使用的策略。
+    def initialize(policy:)
+      raise ArgumentError, "A baseline policy is required" unless policy.is_a?(Policy)
+      @policy = policy
+    end
+
+    # 评估适用基线规则，分别报告合规结果与证据覆盖率。
+    def call(configuration:, context: {})
+      raise ArgumentError, "Invalid baseline context" unless context.is_a?(Hash)
+      context = context.transform_keys(&:to_s).merge("vendor" => configuration.platform)
+      unless (context.keys - Policy::SCOPES).empty? && context.values.all? { |value| value.is_a?(String) && !value.strip.empty? }
+        raise ArgumentError, "Invalid baseline context"
+      end
+      findings = @policy.rules.select(&:enabled?).map { |rule| evaluate(rule, configuration, context) }
+      Report.new(configuration: configuration, policy_sha256: @policy.sha256, findings: findings, context: context)
+    end
+
+    private
+
+    # 使用已知事实和解析后的策略值评估单条适用规则。
+    def evaluate(rule, configuration, context)
+      attributes = { id: rule.id, title: rule.title, severity: rule.severity, actual: nil, expected: nil,
+        lines: configuration.sources.fetch(rule.fact, []), policy_path: [], details: {}, diagnostics: diagnostics(rule, configuration) }
+      applicable = applicability(rule, configuration, context)
+      return finding(attributes, :not_applicable, :scope_mismatch) if applicable == false
+      unless configuration.complete? || configuration.status == :partial
+        return finding(attributes, :unknown, configuration.status == :unsupported ? :unsupported_platform : :input_incomplete)
+      end
+      return finding(attributes, :unknown, :scope_unknown) if applicable.nil?
+      resolution = @policy.resolve_with_source(rule, context)
+      attributes[:policy_path] = resolution.path
+      return finding(attributes, :unknown, resolution.reason) if resolution.reason
+      expected = attributes[:expected] = resolution.value
+      unless configuration.known?(rule.fact)
+        return finding(attributes, :unknown, configuration.complete? ? :fact_unavailable : :input_incomplete)
+      end
+      actual = configuration.value(rule.fact)
+      attributes[:actual] = actual
+      status, reason = compare(rule.operator, actual, expected)
+      # 不完整输入不能证明通过；仅保留补充记录也无法推翻的明确违规。
+      if !configuration.complete? && (status == :pass || status == :fail && !partial_failure?(rule, actual, expected))
+        status, reason = :unknown, :input_incomplete
+      end
+      if status == :fail
+        attributes[:details] = differences(rule.operator, actual, expected)
+        # 尚未采集的配置可能补齐缺项，因此不将缺项作为已确认偏差展示。
+        attributes[:details].delete(:missing) unless configuration.complete?
+      end
+      finding(attributes, status, reason)
+    end
+
+    # 采集尚未完成时，仅报告后续缺失记录也无法推翻的明确违规。
+    def partial_failure?(rule, actual, expected)
+      case rule.operator
+      when :all_disabled, :subset, :networks_within, :password_strength then true
+      when :set_equals then (actual - expected).any?
+      when :equals
+        rule.fact == "snmp.write_enabled" && actual == true && expected == false ||
+          rule.fact == "credentials.storage_safe" && actual == false && expected == true
+      else false
+      end
+    end
+
+    # 按事实路径关联诊断，说明未知原因，同时避免泄露配置文本或凭据。
+    def diagnostics(rule, configuration)
+      scopes = [ rule.fact, *rule.applies_to.fetch("facts", {}).keys ]
+      configuration.issues.select do |issue|
+        fact = issue[:fact]
+        !fact || scopes.any? { |scope| scope == fact || scope.start_with?("#{fact}.") || fact.start_with?("#{scope}.") }
+      end
+    end
+
+    # 说明事实与策略的偏差，不改变比较结果。
+    def differences(operator, actual, expected)
+      case operator
+      when :set_equals then { missing: expected - actual, unexpected: actual - expected }
+      when :subset then { unexpected: actual - expected }
+      when :count_at_least then { minimum: expected, actual_count: actual.size }
+      when :networks_within then { outside_approved: actual.reject { |network| Acl.within?([ network ], expected) } }
+      when :all_disabled then { enabled: expected.select { |name| actual[name] == true } }
+      else {}
+      end
+    end
+
+    # 构造包含稳定状态和原因代码的规则检查结果。
+    def finding(attributes, status, reason)
+      Report::Finding.new(**attributes, status: status, reason: reason)
+    end
+
+    # 根据平台与设备上下文判断规则是否适用。
+    def applicability(rule, configuration, context)
+      unknown = false
+      rule.applies_to.each do |key, expected|
+        values = key == "facts" ? expected : { key => expected }
+        values.each do |name, criterion|
+          known = key == "facts" ? configuration.scope_known?(name) : context.key?(name)
+          value = key == "facts" ? configuration.value(name) : context[name]
+          if !known
+            unknown = true
+          elsif !(criterion.is_a?(Array) ? criterion.include?(value) : criterion == value)
+            return false
+          end
+        end
+      end
+      unknown ? nil : true
+    end
+
+    # 按声明的比较运算符处理归一化策略值。
+    def compare(operator, actual, expected)
+      case operator
+      when :password_strength then return password_strength(actual, expected)
+      when :all_disabled
+        return [ :unknown, :fact_type_mismatch ] unless actual.is_a?(Hash)
+        return [ :fail, :unnecessary_service_enabled ] if expected.any? { |name| actual[name] == true }
+        return [ :unknown, :service_state_unknown ] unless expected.all? { |name| actual[name] == false }
+        passed = true
+      when :equals
+        return [ :unknown, :fact_type_mismatch ] unless actual.class == expected.class || [ true, false ].include?(actual) && [ true, false ].include?(expected)
+        passed = actual == expected
+      else
+        return [ :unknown, :fact_type_mismatch ] unless actual.is_a?(Array) && actual.all? { |item| item.is_a?(String) }
+        passed = case operator
+        when :subset then (actual - expected).empty?
+        when :set_equals then actual.sort == expected.sort
+        when :count_at_least then actual.size >= expected
+        when :networks_within then Acl.within?(actual, expected)
+        end
+      end
+      [ passed ? :pass : :fail, passed ? nil : :deviation ]
+    rescue ArgumentError, IPAddr::InvalidAddressError
+      [ :unknown, :unsupported_address_family ]
+    end
+
+    # 检查可度量的凭据属性，不保存秘密值。
+    def password_strength(actual, expected)
+      return [ :unknown, :fact_type_mismatch ] unless actual.is_a?(Array) && actual.all? { |item| item.is_a?(Hash) }
+      visible = actual.select { |item| item[:storage] == "plaintext" }
+      weak = visible.any? do |item|
+        item[:common] || item.fetch(:length) < expected.fetch("min_length") || item.fetch(:character_classes) < expected.fetch("min_classes")
+      end
+      return [ :fail, :weak_password ] if weak
+      return [ :unknown, :password_strength_unobservable ] if actual.empty? || visible.size != actual.size
+      [ :pass, nil ]
+    end
+  end
+end