auditea 0.1.0.beta.2 → 0.1.0.beta.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42597f9a8f1014e6c58655f23f96fea08309ceeebfd1537bb346b3a418124279
-  data.tar.gz: 8a360c4240d9c1a7b38ec9ff834074e8ed7edcf91ba52628fcfc28a00f85f3ec
+  metadata.gz: 587d3b57a35018f55c5e82c15a485715913e911a714971797a47fde50d788251
+  data.tar.gz: beae506f6609e933baa4d4513e9015cc7b11c919a75ed83ba912eeb546aae0e5
 SHA512:
-  metadata.gz: cb4e6b2cb6444448ef2391a0a5321b9441e7522a0e1220a4cea089d154a66f58577a13ec245af1dfec7cd7b676bb2a2d525520a3831f4eb0bbef9e297591b995
-  data.tar.gz: 787fa69e8fb02fafbe35bcba69b8e592fafa146f76b9cc87b3f7fc7f0e675b7d7b3660f9290ee4a475da6857a3d6e1022bb38966abbf0ebc7827760d78e05c62
+  metadata.gz: 16e6ebde275b1f03f12028ca1c746fdedd9efb907706560ecae52b1fed188e90944f0e827c40e7a1cb909742d381fe37d26deb385ee66d82965c8185444ac99f
+  data.tar.gz: e0c7097c1f146d724befdaf2df850e30a556c670a06406f459003b46a2b52fc77687b36d3fa366d3db4662e13718ddf70ea12698480555858bf51650ee9781c8

data/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
-## 0.1.0.beta.2 (unreleased)
+## 0.1.0.beta.3 (unreleased)
+
+### Exception capture parity (AUD-ERROR-PARITY01)
+
+- Public `Auditea.capture_exception(error, handled:, mechanism:, context:, metadata:)` → `exception.raised`
+- Rails `ErrorReporter` subscriber via public `subscribe` API (Rails 7.2 / 8.1); graceful no-op when absent
+- Identity-safe WeakMap dedupe of exception objects (no integer `object_id` reuse false negatives); cleared at request/job boundaries
+- When `CurrentContext` is already cleared (post-unwind `application.action_dispatch`), derive method/path/request_id/controller/action from the ErrorReporter controller/request via public APIs only
+- `process_action.action_controller` remains as fallback when ErrorReporter is not installed
+- Structured evidence: type, message, bounded frames (≤40) with deterministic `in_app` when knowable, `handled`, `mechanism`, HTTP path/method (no query secrets), controller/action when available
+- ActiveJob: ErrorReporter sources matching `active_job` are skipped when `capture_active_job` is enabled (dedicated `job.failed` path unchanged)
+- Real Rails 7.2 / 8.1 integration coverage for unhandled/handled controller exceptions and ActiveJob no-duplicate behavior
+- Provenance unchanged: sdk/ruby/rails versions + configured `release`
+
+## 0.1.0.beta.2
 
 ### Runtime / dependency inventory (opt-in, default OFF)
 

data/README.md

@@ -2,7 +2,7 @@
 
 Ruby / Rails SDK for [AudiTea](https://github.com/reznis/AudiTea) event collection.
 
-Version: **0.1.0.beta.2** (not published yet)
+Version: **0.1.0.beta.3** (not published yet)
 
 Captures durable technical and business evidence. AudiTea **server** owns taxonomy, dictionary, human labels, vulnerability matching, correlation, and reinterpretation.
 
@@ -12,7 +12,7 @@ The SDK does **not** perform vulnerability scanning, OS package/CVE inventory, d
 
 ```ruby
 # Gemfile
-gem "auditea", "0.1.0.beta.2"
+gem "auditea", "0.1.0.beta.3"
 ```
 
 ```bash
@@ -114,9 +114,17 @@ Auditea.capture(
   evidence: { business: { from_status: "draft", to_status: "approved" } }
 )
 
+Auditea.capture_exception(
+  error,
+  handled: true,
+  mechanism: "application_rescue"
+)
+
 Auditea.log(:info, "Export finished", context: { export_id: export.id })
 ```
 
+Automatic Rails exception observation uses `Rails.error` (ErrorReporter) when available, with `process_action.action_controller` as fallback. Same-exception dedupe is request/thread-local by object id so ErrorReporter and controller notifications do not double-count.
+
 Wire format follows AudiTea **EVENT_CONTRACT_V1**:
 
 - Bearer Source credential authentication

data/RELEASE.md

@@ -1,4 +1,4 @@
-# Release: auditea 0.1.0.beta.2
+# Release: auditea 0.1.0.beta.3
 
 Authoritative runbook for controlled beta publication of the Ruby SDK.
 
@@ -153,10 +153,10 @@ PR status may say `READY FOR HUMAN PUBLICATION REVIEW` while still listing exter
 ```bash
 git checkout main
 git pull
-# confirm VERSION and CHANGELOG still say 0.1.0.beta.2
+# confirm VERSION and CHANGELOG still say 0.1.0.beta.3
 gem build auditea.gemspec
 # inspect package once more
-gem push auditea-0.1.0.beta.2.gem
+gem push auditea-0.1.0.beta.3.gem
 ```
 
 Then mark CHANGELOG released with the publication date in a follow-up commit.
@@ -166,9 +166,9 @@ Then mark CHANGELOG released with the publication date in a follow-up commit.
 ## Post-publication verification
 
 ```bash
-gem install auditea -v 0.1.0.beta.2 --pre
+gem install auditea -v 0.1.0.beta.3 --pre
 ruby -rauditea -e 'puts Auditea::VERSION'
-# expect: 0.1.0.beta.2
+# expect: 0.1.0.beta.3
 ```
 
 Prefer installing the RubyGems artifact (not a git branch) into the controlled TEST app.

data/lib/auditea/instrumentation/active_job.rb

@@ -23,10 +23,13 @@ module Auditea
         end
 
         ::ActiveJob::Base.around_perform do |job, block|
+          Auditea::Instrumentation::Exception::Deduper.clear!
           block.call
         rescue StandardError => error
           Auditea::Instrumentation::ActiveJob.report_unhandled(job, error)
           raise
+        ensure
+          Auditea::Instrumentation::Exception::Deduper.clear!
         end
       end
 

data/lib/auditea/instrumentation/error_subscriber.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Instrumentation
+    # Rails / ActiveSupport::ErrorReporter subscriber (public API only).
+    # Installed when Rails.error / ActiveSupport.error_reporter#subscribe exists.
+    class ErrorSubscriber
+      ACTIVE_JOB_SOURCE = /active_job/i
+
+      class << self
+        def install!
+          return if @installed
+
+          reporter = resolve_reporter
+          return unless reporter.respond_to?(:subscribe)
+
+          @subscriber = new
+          reporter.subscribe(@subscriber)
+          @installed = true
+          true
+        rescue StandardError => error
+          Auditea.handle_error(error)
+          false
+        end
+
+        def installed?
+          !!@installed
+        end
+
+        def reset_for_tests!
+          reporter = resolve_reporter
+          reporter.unsubscribe(@subscriber) if @subscriber && reporter.respond_to?(:unsubscribe)
+          @subscriber = nil
+          @installed = false
+        end
+
+        def resolve_reporter
+          if defined?(::Rails) && ::Rails.respond_to?(:error)
+            ::Rails.error
+          elsif defined?(::ActiveSupport) && ::ActiveSupport.respond_to?(:error_reporter)
+            ::ActiveSupport.error_reporter
+          end
+        end
+      end
+
+      # ActiveSupport::ErrorReporter subscriber contract — must never raise.
+      def report(error, handled:, severity: :error, context: {}, source: nil)
+        return unless Auditea.configuration.capture_exceptions
+        return if skip_active_job?(source)
+
+        structural = StructuralRequest.from_reporter_context(context)
+
+        Auditea::Instrumentation::Exception.capture(
+          error,
+          handled: handled,
+          mechanism: mechanism_for(source),
+          severity: map_severity(severity, handled),
+          evidence: structural["evidence"],
+          context: structural["context"],
+          metadata: {
+            "sdk_event_kind" => "auto_observed"
+          }
+        )
+      rescue StandardError => error
+        Auditea.handle_error(error)
+      end
+
+      private
+
+      def skip_active_job?(source)
+        return false unless source.to_s.match?(ACTIVE_JOB_SOURCE)
+        return true if Auditea.configuration.capture_active_job
+
+        false
+      end
+
+      def mechanism_for(source)
+        value = source.to_s.strip
+        value.empty? ? "rails.error_reporter" : value
+      end
+
+      def map_severity(severity, handled)
+        case severity.to_s
+        when "warning" then "warning"
+        when "info" then "info"
+        when "error" then "error"
+        else
+          handled ? "warning" : "error"
+        end
+      end
+    end
+  end
+end

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/middleware/context.rb

@@ -12,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"],
@@ -24,6 +25,7 @@ module Auditea
       ensure
         opportunistically_refresh_inventory
         CurrentContext.clear!
+        Instrumentation::Exception::Deduper.clear!
       end
 
       private

data/lib/auditea/railtie.rb

@@ -18,6 +18,7 @@ module Auditea
     initializer "auditea.instrumentation" do
       Auditea::Instrumentation::Request.install!
       Auditea::Instrumentation::ActiveJob.install!
+      Auditea::Instrumentation::ErrorSubscriber.install!
     end
 
     config.after_initialize do

data/lib/auditea/version.rb

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

data/lib/auditea.rb

@@ -32,6 +32,8 @@ 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"
@@ -94,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)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: auditea
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta.2
+  version: 0.1.0.beta.3
 platform: ruby
 authors:
 - AudiTea
@@ -35,9 +35,11 @@ files:
 - 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