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

data/lib/auditea/instrumentation/exception.rb

@@ -2,28 +2,56 @@
 
 module Auditea
   module Instrumentation
+    # Structured exception → `exception.raised` evidence.
+    #
+    # Capture paths (fail-open at the Auditea boundary):
+    # - explicit Auditea.capture_exception
+    # - Rails ErrorReporter subscriber (preferred when available)
+    # - process_action.action_controller fallback when ErrorReporter is absent
     module Exception
+      MAX_FRAMES = 40
+      MESSAGE_MAX = 500
+
       module_function
 
+      def capture(error, handled: false, mechanism: nil, severity: "error",
+                  context: nil, metadata: nil, evidence: nil, claim: true)
+        return { ok: false, skipped: true, reason: "disabled" } unless Auditea.configuration.capture_exceptions
+        return { ok: false, skipped: true, reason: "not_an_exception" } unless error.is_a?(::Exception)
+        return { ok: false, skipped: true, reason: "duplicate" } if claim && !Deduper.claim!(error)
+
+        merged_evidence = merge_evidence(error, handled: handled, mechanism: mechanism, evidence: evidence)
+        meta = { "sdk_event_kind" => "auto_observed" }
+        meta.merge!(stringify_keys(metadata)) if metadata
+
+        Auditea.capture(
+          "exception.raised",
+          category: "error",
+          severity: severity || "error",
+          evidence: merged_evidence,
+          context: context,
+          metadata: meta
+        )
+      rescue StandardError => error
+        Auditea.handle_error(error)
+      end
+
       def capture_from_notification(event)
+        # Prefer Rails ErrorReporter when installed so handled/source semantics stay
+        # consistent and ActionDispatch does not double-emit with process_action.
+        return if ErrorSubscriber.installed?
+
         payload = event.payload || {}
         exception = payload[:exception_object]
         exception ||= build_from_array(payload[:exception])
         return unless exception
 
-        frames = safe_frames(exception)
         path = payload[:path].to_s.split("?", 2).first
-
-        Auditea.capture(
-          "exception.raised",
-          category: "error",
-          severity: "error",
+        capture(
+          exception,
+          handled: false,
+          mechanism: "action_controller.process_action",
           evidence: {
-            "exception" => {
-              "type" => exception.class.name,
-              "message" => Sanitizer.truncate_string(exception.message.to_s, 500),
-              "frames" => frames
-            }.compact,
             "http" => {
               "method" => payload[:method],
               "path" => path,
@@ -33,15 +61,46 @@ module Auditea
               "controller" => payload[:controller],
               "action" => payload[:action]
             }.compact
-          },
-          metadata: {
-            "sdk_event_kind" => "auto_observed"
           }
         )
       rescue StandardError => error
         Auditea.handle_error(error)
       end
 
+      def merge_evidence(error, handled:, mechanism:, evidence:)
+        base = stringify_keys(evidence || {})
+        exception = base["exception"].is_a?(Hash) ? base["exception"].dup : {}
+        exception["type"] ||= error.class.name
+        exception["message"] ||= Sanitizer.truncate_string(error.message.to_s, MESSAGE_MAX)
+        exception["frames"] ||= safe_frames(error)
+        exception["handled"] = handled ? true : false unless exception.key?("handled")
+        exception["mechanism"] = mechanism.to_s if mechanism && !exception.key?("mechanism")
+
+        http = base["http"].is_a?(Hash) ? base["http"].dup : {}
+        enrich_http_from_context!(http)
+
+        rails = base["rails"].is_a?(Hash) ? base["rails"].dup : {}
+
+        {
+          "exception" => exception.compact,
+          "http" => compact_hash(http),
+          "rails" => compact_hash(rails)
+        }.compact.merge(base.except("exception", "http", "rails"))
+      end
+
+      def compact_hash(hash)
+        cleaned = hash.compact
+        cleaned.empty? ? nil : cleaned
+      end
+
+      def enrich_http_from_context!(http)
+        ctx = CurrentContext.to_h
+        http_ctx = ctx["http"].is_a?(Hash) ? ctx["http"] : {}
+        http["method"] ||= http_ctx["method"]
+        path = http_ctx["path"].to_s.split("?", 2).first
+        http["path"] ||= path unless path.nil? || path.empty?
+      end
+
       def build_from_array(pair)
         return nil unless pair.is_a?(Array) && pair.size >= 2
 
@@ -56,9 +115,12 @@ module Auditea
       def safe_frames(exception)
         return [] unless exception.respond_to?(:backtrace) && exception.backtrace
 
-        exception.backtrace.first(20).map do |line|
+        exception.backtrace.first(MAX_FRAMES).map do |line|
           file, linenum, method_name = parse_frame(line)
-          { "file" => file, "line" => linenum, "method" => method_name }.compact
+          frame = { "file" => file, "line" => linenum, "method" => method_name }.compact
+          in_app = classify_in_app(file)
+          frame["in_app"] = in_app unless in_app.nil?
+          frame
         end
       end
 
@@ -70,6 +132,62 @@ module Auditea
           [line, nil, nil]
         end
       end
+
+      # Deterministic app-vs-framework marking. Returns nil when unknown (omit key).
+      def classify_in_app(file)
+        path = file.to_s
+        return nil if path.empty?
+
+        return true if path.start_with?("app/") || path.include?("/app/")
+        return false if path.include?("/gems/") || path.include?("/ruby/") ||
+                        path.include?("/vendor/bundle/") || path.include?("/lib/ruby/")
+
+        if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+          root = ::Rails.root.to_s
+          if path.start_with?(root)
+            return false if path.start_with?("#{root}/vendor")
+
+            return true
+          end
+        end
+
+        nil
+      end
+
+      def stringify_keys(value)
+        EventBuilder.stringify_keys(value)
+      end
+
+      # Identity-safe claim set: WeakMap keys are the exception objects themselves.
+      # GC removes entries when exceptions are collected, so recycled object_ids cannot
+      # falsely suppress a distinct raise. Still cleared at request/job boundaries.
+      module Deduper
+        class << self
+          def claim!(error)
+            map = store
+            return false if map.key?(error)
+
+            map[error] = true
+            true
+          end
+
+          def claimed?(error)
+            store.key?(error)
+          rescue StandardError
+            false
+          end
+
+          def clear!
+            Thread.current[:auditea_exception_claims] = ObjectSpace::WeakMap.new
+          end
+
+          private
+
+          def store
+            Thread.current[:auditea_exception_claims] ||= ObjectSpace::WeakMap.new
+          end
+        end
+      end
     end
   end
 end

data/lib/auditea/instrumentation/structural_request.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Instrumentation
+    # Derive scalar request/controller fields from Rails ErrorReporter context.
+    # Never retains controller/request objects; never reads params/body/cookies/session.
+    module StructuralRequest
+      module_function
+
+      def from_reporter_context(context)
+        hash = context.is_a?(Hash) ? context : {}
+        controller = hash[:controller] || hash["controller"]
+
+        rails = {}
+        http = {}
+        event_context = {}
+
+        if controller && !controller.is_a?(String) && controller.respond_to?(:class)
+          rails["controller"] = controller.class.name
+          if controller.respond_to?(:action_name)
+            action = controller.action_name
+            rails["action"] = action.to_s if present?(action)
+          end
+
+          request = safe_request(controller)
+          if request
+            method = safe_request_method(request)
+            http["method"] = method if present?(method)
+
+            path = safe_path(request)
+            http["path"] = path if present?(path)
+
+            request_id = safe_request_id(request)
+            event_context["request_id"] = request_id if present?(request_id)
+          end
+
+          status = safe_status(controller)
+          http["status"] = status unless status.nil?
+        end
+
+        {
+          "evidence" => {
+            "rails" => compact_hash(rails),
+            "http" => compact_hash(http)
+          }.compact,
+          "context" => compact_hash(event_context)
+        }
+      rescue StandardError
+        { "evidence" => {}, "context" => {} }
+      end
+
+      def safe_request(controller)
+        return nil unless controller.respond_to?(:request)
+
+        request = controller.request
+        return nil if request.nil?
+        return nil unless request.respond_to?(:request_method) || request.respond_to?(:path)
+
+        request
+      rescue StandardError
+        nil
+      end
+
+      def safe_request_method(request)
+        return request.request_method.to_s if request.respond_to?(:request_method)
+
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def safe_path(request)
+        raw =
+          if request.respond_to?(:path)
+            request.path
+          elsif request.respond_to?(:fullpath)
+            request.fullpath
+          end
+        return nil unless present?(raw)
+
+        raw.to_s.split("?", 2).first
+      rescue StandardError
+        nil
+      end
+
+      def safe_request_id(request)
+        if request.respond_to?(:request_id)
+          value = request.request_id
+          return value.to_s if present?(value)
+        end
+
+        if request.respond_to?(:env)
+          env = request.env
+          if env.is_a?(Hash)
+            value = env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"]
+            return value.to_s if present?(value)
+          end
+        end
+
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def safe_status(controller)
+        return nil unless controller.respond_to?(:response)
+
+        response = controller.response
+        return nil unless response
+        return nil unless response.respond_to?(:status)
+
+        status = response.status
+        return nil unless status.is_a?(Integer)
+        return nil unless status.between?(100, 599)
+
+        # Unhandled failures often still have the default 200 before rendering;
+        # only keep status when the response looks finalized or already erroneous.
+        committed = response.respond_to?(:committed?) && response.committed?
+        return status if committed || status >= 400
+
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def compact_hash(hash)
+        cleaned = hash.compact
+        cleaned.empty? ? nil : cleaned
+      end
+
+      def present?(value)
+        !(value.nil? || (value.respond_to?(:empty?) && value.empty?))
+      end
+    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

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