auditea 0.1.0.beta.1 → 0.1.0.beta.2

data/lib/auditea/host_inventory/collector.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require "digest"
+require "etc"
+require "rbconfig"
+require "socket"
+require_relative "../inventory/string_bound"
+require_relative "../inventory/digest"
+
+module Auditea
+  module HostInventory
+    # Collects a bounded host/platform inventory.
+    # Never transmits raw hostname, machine-id, paths, env vars, credentials, or tokens.
+    # Opaque host_key is either configured or a local SHA-256 of non-transmitted material.
+    module Collector
+      SCHEMA_VERSION = 1
+      MAX_FIELD_BYTES = 128
+      MAX_HOST_KEY = 128
+      HOST_KEY_FORMAT = /\A[A-Za-z0-9._:-]{8,128}\z/
+      MAX_INVENTORY_BYTES = 8_192
+      OS_RELEASE_PATH = "/etc/os-release"
+
+      module_function
+
+      def collect
+        inventory = {
+          "schema_version" => SCHEMA_VERSION,
+          "host_key" => resolve_host_key!,
+          "platform" => platform_metadata,
+          "hardware" => hardware_metadata,
+          "runtime_context" => runtime_context_metadata,
+          "sdk" => {
+            "name" => "auditea",
+            "version" => VERSION
+          }
+        }
+
+        label = configured_label
+        inventory["label"] = label if label
+
+        inventory = enforce_size_bound(inventory)
+        inventory["digest"] = Inventory::DigestComputer.compute(inventory)
+        inventory
+      end
+
+      def resolve_host_key!
+        configured = Auditea.configuration.host_key.to_s.strip
+        configured = ENV.fetch("AUDITEA_HOST_KEY", "").to_s.strip if configured.empty?
+        if present?(configured)
+          unless configured.match?(HOST_KEY_FORMAT)
+            raise ConfigurationError,
+                  "AUDITEA_HOST_KEY must match opaque host key format"
+          end
+
+          return configured
+        end
+
+        Digest::SHA256.hexdigest(local_identity_material.join("\0"))
+      end
+
+      # Local-only inputs. Never included in the inventory payload.
+      # Containers sharing an image machine-id still differentiate via hostname material.
+      def local_identity_material
+        parts = []
+        machine = read_local_machine_id
+        parts << machine if present?(machine)
+        parts << safe_local_hostname if containerized? || !present?(machine)
+        parts << "container" if containerized?
+        parts << RUBY_PLATFORM.to_s
+        parts << RbConfig::CONFIG["arch"].to_s
+        parts << RbConfig::CONFIG["host_os"].to_s
+        parts
+      end
+      private_class_method :local_identity_material
+
+      def read_local_machine_id
+        %w[/etc/machine-id /var/lib/dbus/machine-id].each do |path|
+          next unless File.readable?(path)
+
+          value = File.read(path, 64).to_s.strip
+          return value if present?(value)
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+      private_class_method :read_local_machine_id
+
+      def safe_local_hostname
+        Socket.gethostname.to_s
+      rescue StandardError
+        "unknown"
+      end
+      private_class_method :safe_local_hostname
+
+      def configured_label
+        label = Auditea.configuration.host_label.to_s.strip
+        label = ENV.fetch("AUDITEA_HOST_LABEL", "").to_s.strip if label.empty?
+        return nil unless present?(label)
+
+        bound_string(label)
+      end
+      private_class_method :configured_label
+
+      def platform_metadata
+        uname = safe_uname
+        arch = first_present(uname[:machine], RbConfig::CONFIG["arch"], RUBY_PLATFORM)
+        os = os_identity(uname)
+        meta = {
+          "os_family" => bound_string(os_family),
+          "os_name" => bound_string(os[:name]),
+          "architecture" => bound_string(arch),
+          "kernel_name" => bound_string(uname[:sysname]),
+          "kernel_release" => bound_string(uname[:release])
+        }
+        meta["os_version"] = bound_string(os[:version]) if present?(os[:version])
+        meta.compact
+      end
+      private_class_method :platform_metadata
+
+      def os_identity(uname)
+        if os_family == "linux"
+          release = parse_os_release
+          return {
+            name: first_present(release["NAME"], release["ID"], "Linux"),
+            version: first_present(release["VERSION_ID"], release["VERSION"])
+          }
+        end
+
+        {
+          name: first_present(uname[:sysname], RbConfig::CONFIG["host_os"]),
+          # Never substitute kernel build metadata (uname.version) as product OS version.
+          version: nil
+        }
+      end
+      private_class_method :os_identity
+
+      def parse_os_release(path: OS_RELEASE_PATH)
+        return {} unless File.readable?(path)
+
+        File.foreach(path).with_object({}) do |line, memo|
+          line = line.strip
+          next if line.empty? || line.start_with?("#")
+
+          key, value = line.split("=", 2)
+          next if key.nil? || value.nil?
+
+          memo[key] = value.delete_prefix('"').delete_suffix('"').delete_prefix("'").delete_suffix("'")
+        end
+      rescue StandardError
+        {}
+      end
+      private_class_method :parse_os_release
+
+      def first_present(*values)
+        values.find { |value| present?(value) }
+      end
+      private_class_method :first_present
+
+      def hardware_metadata
+        count = safe_logical_cpu_count
+        return {} unless count
+
+        { "logical_cpu_count" => count }
+      end
+      private_class_method :hardware_metadata
+
+      def runtime_context_metadata
+        { "container" => containerized? }
+      end
+      private_class_method :runtime_context_metadata
+
+      def safe_uname
+        return {} unless Etc.respond_to?(:uname)
+
+        raw = Etc.uname
+        return {} unless raw.is_a?(Hash)
+
+        {
+          sysname: raw[:sysname] || raw["sysname"],
+          release: raw[:release] || raw["release"],
+          version: raw[:version] || raw["version"],
+          machine: raw[:machine] || raw["machine"]
+        }
+      rescue StandardError
+        {}
+      end
+      private_class_method :safe_uname
+
+      def os_family
+        host_os = RbConfig::CONFIG["host_os"].to_s.downcase
+        case host_os
+        when /linux/ then "linux"
+        when /darwin|mac os/ then "macos"
+        when /mswin|mingw|cygwin/ then "windows"
+        when /bsd/ then "bsd"
+        else "other"
+        end
+      end
+      private_class_method :os_family
+
+      def safe_logical_cpu_count
+        return Etc.nprocessors if Etc.respond_to?(:nprocessors)
+
+        nil
+      rescue StandardError
+        nil
+      end
+      private_class_method :safe_logical_cpu_count
+
+      def containerized?
+        return true if File.exist?("/.dockerenv")
+
+        false
+      rescue StandardError
+        false
+      end
+      private_class_method :containerized?
+
+      def enforce_size_bound(inventory)
+        json = JSON.generate(inventory)
+        return inventory if json.bytesize <= MAX_INVENTORY_BYTES
+
+        # Drop optional fields first; keep identity + required platform.
+        trimmed = inventory.dup
+        trimmed.delete("label")
+        trimmed["hardware"] = {}
+        trimmed["runtime_context"] = {}
+        trimmed
+      end
+      private_class_method :enforce_size_bound
+
+      def bound_string(value)
+        return nil unless present?(value)
+
+        Inventory::StringBound.truncate(value.to_s, MAX_FIELD_BYTES)
+      end
+      private_class_method :bound_string
+
+      def present?(value)
+        !value.nil? && value.to_s.strip != ""
+      end
+      private_class_method :present?
+    end
+  end
+end

data/lib/auditea/host_inventory/emitter.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Auditea
+  module HostInventory
+    # Process-local emission gate: ~daily refresh, immediate emit on digest change.
+    # Independent of Runtime Inventory emitter state; shares refresh interval config.
+    module Emitter
+      ACTION = "host.inventory"
+      CATEGORY = "security"
+
+      module_function
+
+      def capture!(force: true)
+        return skipped("disabled") unless Auditea.configuration.capture_host_inventory?
+
+        return skipped("not_due") if !force && !collection_due?
+
+        mark_collection_attempt!
+        inventory = Collector.collect
+        emit(inventory, force: force)
+      rescue StandardError => error
+        Auditea.handle_error(error)
+      end
+
+      def maybe_capture!
+        capture!(force: false)
+      end
+
+      def collection_due?(now: monotonic_now)
+        state_mutex.synchronize do
+          return true if @last_collection_attempt_at.nil?
+
+          (now - @last_collection_attempt_at) >= Auditea.configuration.inventory_refresh_interval
+        end
+      end
+
+      def reset!
+        state_mutex.synchronize do
+          @last_digest = nil
+          @last_emitted_at = nil
+          @last_collection_attempt_at = nil
+        end
+      end
+
+      def emit(inventory, force:)
+        digest = inventory["digest"].to_s
+        unless force || should_emit?(digest)
+          return { ok: true, skipped: true, reason: "unchanged_within_interval", digest: digest }
+        end
+
+        result = Auditea.capture(
+          ACTION,
+          category: CATEGORY,
+          evidence: { "inventory" => inventory },
+          metadata: { "sdk_event_kind" => force ? "host_inventory_explicit" : "host_inventory_auto" }
+        )
+
+        mark_emitted!(digest) if result.is_a?(Hash) && (result[:ok] || result["ok"])
+        result.is_a?(Hash) ? result.merge(digest: digest) : result
+      end
+      private_class_method :emit
+
+      def should_emit?(digest)
+        state_mutex.synchronize do
+          return true if @last_digest.nil?
+          return true if digest != @last_digest
+          return true if @last_emitted_at.nil?
+
+          (monotonic_now - @last_emitted_at) >= Auditea.configuration.inventory_refresh_interval
+        end
+      end
+      private_class_method :should_emit?
+
+      def mark_emitted!(digest)
+        state_mutex.synchronize do
+          @last_digest = digest
+          @last_emitted_at = monotonic_now
+        end
+      end
+      private_class_method :mark_emitted!
+
+      def mark_collection_attempt!
+        state_mutex.synchronize do
+          @last_collection_attempt_at = monotonic_now
+        end
+      end
+      private_class_method :mark_collection_attempt!
+
+      def skipped(reason)
+        { ok: false, skipped: true, reason: reason }
+      end
+      private_class_method :skipped
+
+      def state_mutex
+        @state_mutex ||= Mutex.new
+      end
+      private_class_method :state_mutex
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+      private_class_method :monotonic_now
+    end
+  end
+end

data/lib/auditea/host_inventory.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "inventory/string_bound"
+require_relative "inventory/digest"
+require_relative "host_inventory/collector"
+require_relative "host_inventory/emitter"
+require_relative "host_inventory/background_refresh"
+
+module Auditea
+  # Opt-in host/platform inventory (`host.inventory`). Default off.
+  # Distinct from runtime/dependency inventory: reports opaque node identity + OS facts.
+  module HostInventory
+    module_function
+
+    def capture!(force: true)
+      Emitter.capture!(force: force)
+    end
+
+    def maybe_capture!
+      Emitter.maybe_capture!
+    end
+
+    # Cheap request-path entry: schedule background capture when due (never inline).
+    def schedule_refresh!
+      BackgroundRefresh.schedule!
+    end
+
+    def collection_due?
+      Emitter.collection_due?
+    end
+
+    def reset!
+      Emitter.reset!
+      BackgroundRefresh.reset!
+    end
+  end
+end

data/lib/auditea/inventory/background_refresh.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Inventory
+    # Process-local, single-flight background refresh for runtime.inventory.
+    # Middleware only schedules; collection/delivery never run inline on the Rack path.
+    module BackgroundRefresh
+      module_function
+
+      def schedule!
+        return false unless Auditea.configuration.capture_runtime_inventory?
+        return false unless Emitter.collection_due?
+        return false unless claim_slot!
+
+        thread = Thread.new { run_capture }
+        thread.name = "auditea-runtime-inventory" if thread.respond_to?(:name=)
+        true
+      rescue StandardError => error
+        release_slot!
+        Auditea.handle_error(error)
+        false
+      end
+
+      def reset!
+        state_mutex.synchronize do
+          @inflight = false
+        end
+      end
+
+      def inflight?
+        state_mutex.synchronize { !!@inflight }
+      end
+
+      def claim_slot!
+        state_mutex.synchronize do
+          return false if @inflight
+
+          @inflight = true
+          true
+        end
+      end
+      private_class_method :claim_slot!
+
+      def release_slot!
+        state_mutex.synchronize { @inflight = false }
+      end
+      private_class_method :release_slot!
+
+      def run_capture
+        Emitter.capture!(force: false)
+      rescue StandardError => error
+        Auditea.handle_error(error)
+      ensure
+        release_slot!
+      end
+      private_class_method :run_capture
+
+      def state_mutex
+        @state_mutex ||= Mutex.new
+      end
+      private_class_method :state_mutex
+    end
+  end
+end