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

data/lib/auditea/inventory/collector.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require_relative "string_bound"
+
+module Auditea
+  module Inventory
+    # Collects a normalized runtime + dependency inventory for AudiTea.
+    # Never includes filesystem paths, remote URLs, tokens, or env vars.
+    module Collector
+      SCHEMA_VERSION = 1
+      MAX_PACKAGES = 400
+      MAX_FIELD_BYTES = 128
+      MAX_REQUIREMENT_BYTES = 256
+      # Leave headroom under Transport::Limits::SINGLE_MAX_BYTES after envelope/provenance.
+      MAX_INVENTORY_BYTES = 110_000
+
+      module_function
+
+      def collect
+        packages, completeness, packages_total = collect_packages
+        inventory = {
+          "schema_version" => SCHEMA_VERSION,
+          "completeness" => completeness,
+          "runtime" => runtime_metadata,
+          "package_manager" => package_manager_metadata,
+          "openssl" => openssl_metadata,
+          "sdk" => {
+            "name" => "auditea",
+            "version" => VERSION
+          },
+          "packages" => packages,
+          "package_count" => packages.size
+        }
+        inventory["packages_total"] = packages_total if packages_total && packages_total != packages.size
+
+        framework = framework_metadata
+        inventory["framework"] = framework if framework
+
+        release = Auditea.configuration.release
+        inventory["application"] = { "release" => bound_string(release) } if present?(release)
+
+        inventory = enforce_size_bound(inventory)
+        inventory["digest"] = DigestComputer.compute(inventory)
+        inventory
+      end
+
+      def runtime_metadata
+        {
+          "language" => "ruby",
+          "engine" => bound_string(RUBY_ENGINE),
+          "version" => bound_string(RUBY_VERSION),
+          "patchlevel" => bound_string(RUBY_PATCHLEVEL.to_s),
+          "platform" => bound_string(RUBY_PLATFORM),
+          "gem_platform" => bound_string(Gem::Platform.local.to_s)
+        }
+      end
+
+      def framework_metadata
+        return nil unless defined?(::Rails)
+
+        version =
+          if defined?(::Rails::VERSION::STRING)
+            ::Rails::VERSION::STRING
+          elsif ::Rails.respond_to?(:version)
+            ::Rails.version
+          end
+        return nil unless present?(version)
+
+        { "name" => "rails", "version" => bound_string(version) }
+      end
+
+      def package_manager_metadata
+        meta = { "rubygems_version" => bound_string(Gem::VERSION) }
+        meta["bundler_version"] = bound_string(::Bundler::VERSION) if defined?(::Bundler::VERSION)
+        meta
+      end
+
+      def openssl_metadata
+        meta = {}
+        meta["extension_version"] = bound_string(::OpenSSL::VERSION) if defined?(::OpenSSL::VERSION)
+        if defined?(::OpenSSL) && ::OpenSSL.const_defined?(:OPENSSL_VERSION)
+          meta["build_version"] = bound_string(::OpenSSL::OPENSSL_VERSION)
+        end
+        if defined?(::OpenSSL) && ::OpenSSL.const_defined?(:OPENSSL_LIBRARY_VERSION)
+          meta["library_version"] = bound_string(::OpenSSL::OPENSSL_LIBRARY_VERSION)
+        end
+        meta
+      end
+
+      def collect_packages
+        locked = current_platform_bundle_packages
+        return finalize_packages(locked, "bundle_locked") if locked
+
+        loaded = loaded_gem_packages
+        finalize_packages(loaded, "loaded_only")
+      end
+
+      def finalize_packages(packages, completeness)
+        packages = Array(packages)
+        packages = sort_packages(packages)
+        total = packages.size
+        if total > MAX_PACKAGES
+          packages = packages.first(MAX_PACKAGES)
+          completeness = "truncated"
+        end
+        [packages, completeness, total]
+      end
+
+      # Prefer Bundler.definition.specs — the materialized SpecSet for the
+      # current platform / force_ruby_platform — not every lockfile platform variant.
+      # Only claim bundle_locked when every materialized spec normalizes and the
+      # direct-dependency map is available; otherwise return nil → loaded_only.
+      def current_platform_bundle_packages
+        return nil unless defined?(::Bundler)
+        return nil unless ::Bundler.respond_to?(:definition)
+
+        definition = ::Bundler.definition
+        return nil if definition.nil?
+        return nil unless definition.respond_to?(:specs)
+
+        specs = Array(definition.specs)
+        return nil if specs.empty?
+
+        directs = direct_dependency_map
+        return nil if directs.nil?
+
+        packages = []
+        specs.each do |spec|
+          pkg = package_from_spec(spec, directs)
+          # Do not silently omit a failed spec while still claiming bundle_locked.
+          return nil if pkg.nil?
+
+          packages << pkg
+        end
+        return nil if packages.empty?
+
+        packages
+      rescue StandardError
+        nil
+      end
+
+      def loaded_gem_packages
+        directs = direct_dependency_map || {}
+        Gem.loaded_specs.values.filter_map { |spec| package_from_spec(spec, directs) }
+      rescue StandardError
+        []
+      end
+
+      # Returns a Hash of direct deps, or nil when the map cannot be obtained.
+      # Callers that claim bundle_locked must treat nil as failure (do not invent
+      # direct: false for every package).
+      def direct_dependency_map
+        return nil unless defined?(::Bundler)
+        return nil unless ::Bundler.respond_to?(:definition)
+
+        definition = ::Bundler.definition
+        return nil if definition.nil?
+        return nil unless definition.respond_to?(:dependencies)
+
+        definition.dependencies.each_with_object({}) do |dep, memo|
+          name = dep.name.to_s
+          next if name.empty?
+
+          memo[name] = {
+            "direct" => true,
+            "requirement" => bound_string(dep.requirement.to_s, MAX_REQUIREMENT_BYTES)
+          }
+        end
+      rescue StandardError
+        nil
+      end
+
+      def package_from_spec(spec, directs)
+        name = bound_string(spec.name)
+        return nil if name.nil? || name.empty?
+
+        version = bound_string(spec.version.to_s)
+        return nil if version.nil? || version.empty?
+
+        platform = normalize_platform(spec)
+        entry = {
+          "ecosystem" => "RubyGems",
+          "name" => name,
+          "version" => version,
+          "platform" => platform,
+          "direct" => false,
+          "source_type" => classify_source(spec)
+        }
+
+        direct = directs[name]
+        if direct
+          entry["direct"] = true
+          entry["requirement"] = direct["requirement"] if present?(direct["requirement"])
+        end
+
+        revision = git_revision(spec)
+        entry["revision"] = bound_string(revision) if present?(revision)
+
+        entry
+      rescue StandardError
+        nil
+      end
+
+      def normalize_platform(spec)
+        platform =
+          if spec.respond_to?(:platform) && spec.platform
+            spec.platform.to_s
+          else
+            "ruby"
+          end
+        platform = "ruby" if platform.empty?
+        bound_string(platform)
+      end
+
+      def classify_source(spec)
+        source = spec.respond_to?(:source) ? spec.source : nil
+        return "unknown" if source.nil?
+
+        class_name = source.class.name.to_s
+        case class_name
+        when /Source::Rubygems\z/, /RubygemsRemote\z/
+          "rubygems"
+        when /Source::Git\z/
+          "git"
+        when /Source::Path\z/, /Source::Gemspec\z/
+          "path"
+        else
+          return "git" if source.respond_to?(:revision) && present?(safe_revision(source))
+          return "path" if source.respond_to?(:path)
+
+          "unknown"
+        end
+      rescue StandardError
+        "unknown"
+      end
+
+      def git_revision(spec)
+        source = spec.respond_to?(:source) ? spec.source : nil
+        return nil unless source
+
+        class_name = source.class.name.to_s
+        return nil unless class_name.include?("Git")
+
+        safe_revision(source)
+      rescue StandardError
+        nil
+      end
+
+      def safe_revision(source)
+        return nil unless source.respond_to?(:revision)
+
+        revision = source.revision
+        return nil unless revision.is_a?(String)
+        return nil unless revision.match?(/\A[0-9a-f]{7,40}\z/i)
+
+        revision.downcase
+      rescue StandardError
+        nil
+      end
+
+      def sort_packages(packages)
+        packages.sort_by { |pkg| [pkg["name"].to_s, pkg["version"].to_s, pkg["platform"].to_s] }
+      end
+
+      def enforce_size_bound(inventory)
+        json_bytes = JSON.generate(inventory_for_size(inventory)).bytesize
+        return inventory if json_bytes <= MAX_INVENTORY_BYTES
+
+        packages = inventory["packages"].dup
+        total = inventory["packages_total"] || packages.size
+        while packages.size > 1
+          candidate = inventory.merge("packages" => packages)
+          break if JSON.generate(inventory_for_size(candidate)).bytesize <= MAX_INVENTORY_BYTES
+
+          packages.pop
+        end
+
+        inventory.merge(
+          "packages" => packages,
+          "package_count" => packages.size,
+          "packages_total" => total,
+          "completeness" => "truncated"
+        )
+      end
+
+      def inventory_for_size(inventory)
+        inventory.except("digest")
+      end
+
+      def bound_string(value, max_bytes = MAX_FIELD_BYTES)
+        StringBound.truncate(value, max_bytes)
+      end
+
+      def present?(value)
+        !(value.nil? || (value.respond_to?(:empty?) && value.empty?))
+      end
+    end
+  end
+end

data/lib/auditea/inventory/digest.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Auditea
+  module Inventory
+    # Stable digest over normalized inventory (no timestamps / PIDs / hostnames).
+    module DigestComputer
+      module_function
+
+      def compute(inventory)
+        payload = canonicalize(inventory_without_digest(inventory))
+        Digest::SHA256.hexdigest(JSON.generate(payload))
+      end
+
+      def inventory_without_digest(inventory)
+        case inventory
+        when Hash
+          inventory.each_with_object({}) do |(key, value), memo|
+            next if key.to_s == "digest"
+
+            memo[key.to_s] = inventory_without_digest(value)
+          end
+        when Array
+          inventory.map { |value| inventory_without_digest(value) }
+        else
+          inventory
+        end
+      end
+
+      def canonicalize(value)
+        case value
+        when Hash
+          value.keys.map(&:to_s).sort.to_h do |key|
+            [key, canonicalize(hash_fetch(value, key))]
+          end
+        when Array
+          value.map { |child| canonicalize(child) }
+        when String, Numeric, TrueClass, FalseClass, NilClass
+          value
+        else
+          value.to_s
+        end
+      end
+
+      # Prefer key existence over truthiness so false/nil are preserved.
+      def hash_fetch(hash, key)
+        return hash[key] if hash.key?(key)
+
+        sym = key.to_sym
+        return hash[sym] if hash.key?(sym)
+
+        nil
+      end
+      private_class_method :hash_fetch
+    end
+  end
+end

data/lib/auditea/inventory/emitter.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Inventory
+    # Process-local emission gate: ~daily refresh, immediate emit on digest change.
+    module Emitter
+      ACTION = "runtime.inventory"
+      CATEGORY = "security"
+
+      module_function
+
+      def capture!(force: true)
+        return skipped("disabled") unless Auditea.configuration.capture_runtime_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
+
+      # Cheap gate for request/lifecycle hooks — does not collect until due.
+      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 ? "runtime_inventory_explicit" : "runtime_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/inventory/string_bound.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Inventory
+    # UTF-8-safe byte bounds for inventory string fields.
+    module StringBound
+      ELLIPSIS = "…"
+      ELLIPSIS_BYTES = ELLIPSIS.bytesize
+
+      module_function
+
+      # Returns a string with bytesize <= max_bytes (valid UTF-8), or nil for nil input.
+      # When truncating, reserves ELLIPSIS_BYTES from the budget when max_bytes allows;
+      # otherwise truncates without an ellipsis. max_bytes <= 0 yields "".
+      def truncate(value, max_bytes)
+        return nil if value.nil?
+        return "" if max_bytes <= 0
+
+        string = value.to_s
+        return string if string.bytesize <= max_bytes
+
+        if max_bytes < ELLIPSIS_BYTES
+          truncate_bytes(string, max_bytes)
+        else
+          "#{truncate_bytes(string, max_bytes - ELLIPSIS_BYTES)}#{ELLIPSIS}"
+        end
+      end
+
+      def truncate_bytes(string, budget)
+        return "" if budget <= 0
+
+        truncated = string.b.byteslice(0, budget)
+        truncated.force_encoding(Encoding::UTF_8)
+        until truncated.empty? || truncated.valid_encoding?
+          truncated = truncated.byteslice(0, truncated.bytesize - 1)
+          truncated.force_encoding(Encoding::UTF_8)
+        end
+        truncated
+      end
+      private_class_method :truncate_bytes
+    end
+  end
+end

data/lib/auditea/inventory.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "inventory/string_bound"
+require_relative "inventory/digest"
+require_relative "inventory/collector"
+require_relative "inventory/emitter"
+require_relative "inventory/background_refresh"
+
+module Auditea
+  # Runtime and dependency inventory for AudiTea (opt-in).
+  module Inventory
+    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/middleware/context.rb

@@ -4,6 +4,7 @@ module Auditea
   module Middleware
     # Rack middleware: sets CurrentContext with safe structural request fields.
     # Does NOT store session_id, cookies, Authorization, or query strings.
+    # Opportunistic inventory refresh uses a cheap due-gate only; collection is rare.
     class Context
       def initialize(app)
         @app = app
@@ -21,6 +22,7 @@ module Auditea
         )
         @app.call(env)
       ensure
+        opportunistically_refresh_inventory
         CurrentContext.clear!
       end
 
@@ -30,6 +32,29 @@ module Auditea
         path = request.path.to_s
         path.split("?", 2).first
       end
+
+      def opportunistically_refresh_inventory
+        refresh_runtime_inventory
+        refresh_host_inventory
+      rescue StandardError => error
+        Auditea.handle_error(error)
+      end
+
+      def refresh_runtime_inventory
+        return unless Auditea.configuration.capture_runtime_inventory?
+        return unless Auditea::Inventory.collection_due?
+
+        # Never collect/deliver inline on the request path (even with sync transport).
+        Auditea::Inventory.schedule_refresh!
+      end
+
+      def refresh_host_inventory
+        return unless Auditea.configuration.capture_host_inventory?
+        return unless Auditea::HostInventory.collection_due?
+
+        # Never collect/deliver inline on the request path (even with sync transport).
+        Auditea::HostInventory.schedule_refresh!
+      end
     end
   end
 end

data/lib/auditea/railtie.rb

@@ -22,6 +22,13 @@ module Auditea
 
     config.after_initialize do
       at_exit { Auditea.shutdown }
+      begin
+        # Startup capture is explicit (force) so long-lived refresh can stay gated.
+        Auditea.capture_runtime_inventory! if Auditea.configuration.capture_runtime_inventory?
+        Auditea.capture_host_inventory! if Auditea.configuration.capture_host_inventory?
+      rescue StandardError => error
+        Auditea.handle_error(error)
+      end
     end
   end
 end

data/lib/auditea/sanitizer.rb

@@ -6,6 +6,10 @@ module Auditea
   # Exact normalized key matching only (no substring matches).
   module Sanitizer
     FILTERED = "[FILTERED]"
+    DEFAULT_ARRAY_MAX = 100
+    # Inventory packages are intentionally larger than ordinary evidence arrays.
+    # Keep in sync with Inventory::Collector::MAX_PACKAGES (literal avoids load-order coupling).
+    INVENTORY_PACKAGES_ARRAY_MAX = 400
     SENSITIVE_KEYS = %w[
       password password_confirmation password_digest authorization cookie set_cookie
       api_key access_token refresh_token secret secret_key client_secret private_key token
@@ -42,6 +46,14 @@ module Auditea
       "#{string.byteslice(0, max_bytes)}…"
     end
 
+    def inventory_packages_path?(path)
+      path.to_s == "evidence.inventory.packages"
+    end
+
+    def array_limit_for(path)
+      inventory_packages_path?(path) ? INVENTORY_PACKAGES_ARRAY_MAX : DEFAULT_ARRAY_MAX
+    end
+
     def deep_sanitize(value, depth:, path:, redacted:)
       cfg = Auditea.configuration
       return { "truncated" => true, "reason" => "max_depth" } if depth > cfg.nesting_max_depth
@@ -59,7 +71,8 @@ module Auditea
           end
         end
       when Array
-        value.first(100).each_with_index.map do |child, index|
+        limit = array_limit_for(path)
+        value.first(limit).each_with_index.map do |child, index|
           child_path = path ? "#{path}[#{index}]" : "[#{index}]"
           deep_sanitize(child, depth: depth + 1, path: child_path, redacted: redacted)
         end

data/lib/auditea/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Auditea
-  VERSION = "0.1.0.beta.1"
+  VERSION = "0.1.0.beta.2"
 end

data/lib/auditea.rb

@@ -28,6 +28,8 @@ require_relative "auditea/transport/http"
 require_relative "auditea/transport/queue"
 require_relative "auditea/client"
 require_relative "auditea/log"
+require_relative "auditea/inventory"
+require_relative "auditea/host_inventory"
 require_relative "auditea/instrumentation/request"
 require_relative "auditea/instrumentation/exception"
 require_relative "auditea/instrumentation/logger_adapter"
@@ -54,6 +56,8 @@ module Auditea
       @configuration = Configuration.new
       @client&.shutdown
       @client = nil
+      Inventory.reset!
+      HostInventory.reset!
     end
 
     def client
@@ -97,6 +101,26 @@ module Auditea
       handle_error(error)
     end
 
+    # Opt-in runtime + dependency inventory (`runtime.inventory`). Default off.
+    # Does not raise on collection failure unless raise_errors is enabled.
+    def capture_runtime_inventory!(force: true)
+      Inventory.capture!(force: force)
+    end
+
+    # Bounded refresh for long-lived processes (~daily when unchanged).
+    def maybe_capture_runtime_inventory!
+      Inventory.maybe_capture!
+    end
+
+    # Opt-in host/platform inventory (`host.inventory`). Default off.
+    def capture_host_inventory!(force: true)
+      HostInventory.capture!(force: force)
+    end
+
+    def maybe_capture_host_inventory!
+      HostInventory.maybe_capture!
+    end
+
     def flush(timeout: 5)
       client.flush(timeout: timeout)
     rescue StandardError => error