auditea 0.1.0.beta.1 → 0.1.0.beta.3

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
@@ -11,6 +12,7 @@ module Auditea
 
       def call(env)
         CurrentContext.clear!
+        Instrumentation::Exception::Deduper.clear!
         request = ::Rack::Request.new(env)
         CurrentContext.set(
           "request_id" => env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"],
@@ -21,7 +23,9 @@ module Auditea
         )
         @app.call(env)
       ensure
+        opportunistically_refresh_inventory
         CurrentContext.clear!
+        Instrumentation::Exception::Deduper.clear!
       end
 
       private
@@ -30,6 +34,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

@@ -18,10 +18,18 @@ module Auditea
     initializer "auditea.instrumentation" do
       Auditea::Instrumentation::Request.install!
       Auditea::Instrumentation::ActiveJob.install!
+      Auditea::Instrumentation::ErrorSubscriber.install!
     end
 
     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.3"
 end

data/lib/auditea.rb

@@ -28,8 +28,12 @@ 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/structural_request"
+require_relative "auditea/instrumentation/error_subscriber"
 require_relative "auditea/instrumentation/logger_adapter"
 require_relative "auditea/instrumentation/active_job"
 require_relative "auditea/middleware/context"
@@ -54,6 +58,8 @@ module Auditea
       @configuration = Configuration.new
       @client&.shutdown
       @client = nil
+      Inventory.reset!
+      HostInventory.reset!
     end
 
     def client
@@ -90,6 +96,25 @@ module Auditea
     # Alias kept for legacy familiarity (KEEP CONCEPT).
     alias track capture
 
+    # First-class exception capture → action `exception.raised` / category `error`.
+    # Rebuilds structured exception evidence (type, message, frames, handled, mechanism).
+    # Uses CurrentContext when present; sanitizes like normal events; fail-open by default.
+    def capture_exception(error, handled: false, mechanism: nil, severity: "error",
+                          context: nil, metadata: nil, evidence: nil)
+      Instrumentation::Exception.capture(
+        error,
+        handled: handled,
+        mechanism: mechanism || "auditea.capture_exception",
+        severity: severity,
+        context: context,
+        metadata: (metadata || {}).merge("sdk_event_kind" => "explicit"),
+        evidence: evidence,
+        claim: true
+      )
+    rescue StandardError => error
+      handle_error(error)
+    end
+
     # Structured application log as a first-class event (not Rails.logger auto-forward).
     def log(level, message, context: {}, metadata: {})
       Log.record(level, message, context: context, metadata: metadata)
@@ -97,6 +122,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: auditea
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta.1
+  version: 0.1.0.beta.3
 platform: ruby
 authors:
 - AudiTea
@@ -9,8 +9,8 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Capture business events, Rails request evidence, exceptions, and structured
-  logs for AudiTea /api/v1.
+description: Capture business events, Rails request evidence, exceptions, structured
+  logs, and optional runtime/host inventory for AudiTea /api/v1.
 email:
 - opensource@auditea.app
 executables: []
@@ -30,10 +30,22 @@ files:
 - lib/auditea/configuration.rb
 - lib/auditea/current_context.rb
 - lib/auditea/event_builder.rb
+- lib/auditea/host_inventory.rb
+- lib/auditea/host_inventory/background_refresh.rb
+- lib/auditea/host_inventory/collector.rb
+- lib/auditea/host_inventory/emitter.rb
 - lib/auditea/instrumentation/active_job.rb
+- lib/auditea/instrumentation/error_subscriber.rb
 - lib/auditea/instrumentation/exception.rb
 - lib/auditea/instrumentation/logger_adapter.rb
 - lib/auditea/instrumentation/request.rb
+- lib/auditea/instrumentation/structural_request.rb
+- lib/auditea/inventory.rb
+- lib/auditea/inventory/background_refresh.rb
+- lib/auditea/inventory/collector.rb
+- lib/auditea/inventory/digest.rb
+- lib/auditea/inventory/emitter.rb
+- lib/auditea/inventory/string_bound.rb
 - lib/auditea/log.rb
 - lib/auditea/middleware/context.rb
 - lib/auditea/railtie.rb