auditea 0.1.0.beta.2 → 0.1.0.beta.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42597f9a8f1014e6c58655f23f96fea08309ceeebfd1537bb346b3a418124279
-  data.tar.gz: 8a360c4240d9c1a7b38ec9ff834074e8ed7edcf91ba52628fcfc28a00f85f3ec
+  metadata.gz: 5459c8f22551f101e1aa2f32689bf47623c3ec2890f448ff5dd92c4980ee8c91
+  data.tar.gz: 2fb620c50bc457db6f85df2d1745b1c761e3141571a14451caef9080db109e7c
 SHA512:
-  metadata.gz: cb4e6b2cb6444448ef2391a0a5321b9441e7522a0e1220a4cea089d154a66f58577a13ec245af1dfec7cd7b676bb2a2d525520a3831f4eb0bbef9e297591b995
-  data.tar.gz: 787fa69e8fb02fafbe35bcba69b8e592fafa146f76b9cc87b3f7fc7f0e675b7d7b3660f9290ee4a475da6857a3d6e1022bb38966abbf0ebc7827760d78e05c62
+  metadata.gz: faf9f0876938d536fe4aad106bba8b13ee72031ecb78c14d259a9a313eb046c84601b2b0ec3af9cb510d0b9581c7eb142aea169170f364e813b79ef7ae65f32d
+  data.tar.gz: df66f3cab946bb98383c903d550f4f7cf842386e4fea0b2fb11b6d037b4c0a2beee1d652c3381199e9c35a30c743a17039844b68c78494429fc64d04448fbc96

data/CHANGELOG.md

@@ -1,6 +1,50 @@
 # Changelog
 
-## 0.1.0.beta.2 (unreleased)
+## 0.1.0.beta.4 (unreleased)
+
+### Platform component inventory (AUD-PLATFORM-INVENTORY01)
+
+- Additive optional `evidence.inventory.components[]` on `runtime.inventory` and `host.inventory` (schema_version remains 1)
+- Component fields: `product`, `version`, `scope`, `observation_method`, optional `package` / `evidence`
+- Scopes: `application_runtime`, `application_server`, `database_server`, `linked_library`, `host_os`, `host_component`, `reverse_proxy`, `externally_observed`
+- Runtime: promote Ruby/Rails/Bundler/RubyGems/linked OpenSSL; promote Puma (and peers) from packages; PostgreSQL server via fail-open `SHOW server_version` (never host-attached)
+- Host: OS/kernel components; allowlisted detectors (`openssl version`, `apache2`/`httpd -v`, `nginx -v`) with timeout, bounded I/O, no shell, no sudo
+- Absent reverse proxies are simply not observed (never claimed “not installed”)
+
+### FIX01 hardening
+
+- Detectors resolve allowlisted basenames from fixed trusted system directories only (realpath boundary); never `ENV["PATH"]`
+- Detector evidence is basename + observation metadata only — no raw stdout/stderr
+- Aggregate detector wall-clock budget; hanging children are process-group killed and reaped
+- Rails `after_initialize` schedules existing background inventory refresh (does not block boot)
+- PostgreSQL version uses `connection_pool.with_connection` and releases the checkout
+
+### FIX02 executable trust
+
+- After realpath containment, require root-owned (uid 0) directory and executable
+- Reject group/world-writable directories or executables; reject app-UID-owned material
+- Ordinary `/bin` → `/usr/bin` realpath equivalence remains supported; symlink escapes fail open as not observed
+
+### FIX03 process lifecycle
+
+- After `Process.spawn`, every exit path terminates/reaps the child (ensure-owned cleanup; not timeout-only)
+- Fail-open cleanup tolerates ESRCH / ECHILD / EINTR; no double-wait escape
+
+## 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.4** (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.4"
 ```
 
 ```bash
@@ -48,6 +48,19 @@ Without a Source token (and with the SDK enabled), capture is skipped (`not_conf
 | `capture_host_inventory` | `true` only if multi-host/container identity matters | Default OFF; enable per environment decision |
 | `capture_requests` | `false` initially | Avoid high-volume request spam on first connect |
 
+Example environment (replace the secret and release id; never commit real tokens):
+
+```text
+AUDITEA_ENDPOINT=https://auditea.ca
+AUDITEA_SOURCE_TOKEN=<secret>
+AUDITEA_RELEASE=<actual deployed SHA>
+AUDITEA_CAPTURE_EXCEPTIONS=true
+AUDITEA_CAPTURE_RUNTIME_INVENTORY=true
+AUDITEA_CAPTURE_HOST_INVENTORY=true
+AUDITEA_RAISE_ERRORS=false
+```
+
+
 ### Optional
 
 Async tuning (`AUDITEA_ASYNC`, batch/flush/queue/timeouts), `AUDITEA_INVENTORY_REFRESH_INTERVAL`, `AUDITEA_HOST_KEY` / `AUDITEA_HOST_LABEL`, `capture_request_params`, `raise_errors` (debug only).
@@ -114,9 +127,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
@@ -147,7 +168,7 @@ AUDITEA_CAPTURE_RUNTIME_INVENTORY=true
 # optional: AUDITEA_INVENTORY_REFRESH_INTERVAL=86400
 ```
 
-With Rails, when capture is enabled, the Railtie may emit once after `after_initialize`. Opportunistic Rack refresh only **schedules** a single-flight background job when due — collection/delivery are never inline on the request path.
+With Rails, when capture is enabled, the Railtie **schedules** a single-flight background inventory refresh after `after_initialize` (boot is not blocked on detectors or database work). Opportunistic Rack refresh uses the same scheduler when due — collection/delivery are never inline on the request path.
 
 Enabling inventory reveals internal gem names to AudiTea. Keep it off unless that is intentional.
 

data/RELEASE.md

@@ -1,4 +1,4 @@
-# Release: auditea 0.1.0.beta.2
+# Release: auditea 0.1.0.beta.4
 
 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.4
 gem build auditea.gemspec
 # inspect package once more
-gem push auditea-0.1.0.beta.2.gem
+gem push auditea-0.1.0.beta.4.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.4 --pre
 ruby -rauditea -e 'puts Auditea::VERSION'
-# expect: 0.1.0.beta.2
+# expect: 0.1.0.beta.4
 ```
 
 Prefer installing the RubyGems artifact (not a git branch) into the controlled TEST app.

data/lib/auditea/host_inventory/collector.rb

@@ -6,6 +6,8 @@ require "rbconfig"
 require "socket"
 require_relative "../inventory/string_bound"
 require_relative "../inventory/digest"
+require_relative "../inventory/components"
+require_relative "component_detectors"
 
 module Auditea
   module HostInventory
@@ -17,7 +19,7 @@ module Auditea
       MAX_FIELD_BYTES = 128
       MAX_HOST_KEY = 128
       HOST_KEY_FORMAT = /\A[A-Za-z0-9._:-]{8,128}\z/
-      MAX_INVENTORY_BYTES = 8_192
+      MAX_INVENTORY_BYTES = 16_384
       OS_RELEASE_PATH = "/etc/os-release"
 
       module_function
@@ -38,11 +40,54 @@ module Auditea
         label = configured_label
         inventory["label"] = label if label
 
+        components = Inventory::Components.compact_list(
+          host_os_components(inventory["platform"]) + ComponentDetectors.collect
+        )
+        inventory["components"] = components unless components.empty?
+
         inventory = enforce_size_bound(inventory)
         inventory["digest"] = Inventory::DigestComputer.compute(inventory)
         inventory
       end
 
+      def host_os_components(platform)
+        list = []
+        os_name = platform["os_name"]
+        os_version = platform["os_version"]
+        if present?(os_name) || present?(os_version)
+          product =
+            if os_name.to_s.match?(/ubuntu/i)
+              "Ubuntu"
+            elsif os_name.to_s.match?(/debian/i)
+              "Debian"
+            elsif present?(os_name)
+              os_name
+            else
+              "Host OS"
+            end
+          version = present?(os_version) ? os_version : "unknown"
+          list << Inventory::Components.build(
+            product: product,
+            version: version,
+            scope: "host_os",
+            observation_method: "os_release"
+          )
+        end
+
+        kernel_name = platform["kernel_name"]
+        kernel_release = platform["kernel_release"]
+        if present?(kernel_release)
+          list << Inventory::Components.build(
+            product: present?(kernel_name) ? "#{kernel_name} kernel" : "Linux kernel",
+            version: kernel_release,
+            scope: "host_os",
+            observation_method: "uname"
+          )
+        end
+
+        list
+      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?
@@ -224,6 +269,7 @@ module Auditea
         # Drop optional fields first; keep identity + required platform.
         trimmed = inventory.dup
         trimmed.delete("label")
+        trimmed.delete("components")
         trimmed["hardware"] = {}
         trimmed["runtime_context"] = {}
         trimmed

data/lib/auditea/host_inventory/component_detectors.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Auditea
+  module HostInventory
+    # Allowlisted local component detectors.
+    # Fixed argv only — no shell, no sudo, no PATH search, no caller-supplied paths.
+    module ComponentDetectors
+      # Wall-clock budget for the entire collect pass (all detectors/candidates).
+      AGGREGATE_TIMEOUT_SECONDS = 2.5
+      # Per-command cap; also clipped by remaining aggregate budget.
+      PER_COMMAND_TIMEOUT_SECONDS = 1.0
+      MAX_OUTPUT_BYTES = 2_048
+      ALLOWED_BASENAMES = %w[openssl apache2 httpd nginx].freeze
+
+      # Fixed trusted system directories only — never ENV["PATH"] or writable app/tmp dirs.
+      TRUSTED_BIN_DIRS = %w[
+        /usr/bin
+        /bin
+        /usr/sbin
+        /sbin
+        /usr/local/bin
+        /usr/local/sbin
+      ].freeze
+
+      DETECTORS = [
+        {
+          product: "OpenSSL",
+          scope: "host_component",
+          observation_method: "host.openssl_version",
+          candidates: [%w[openssl version]],
+          parser: :parse_openssl
+        },
+        {
+          product: "Apache HTTP Server",
+          scope: "reverse_proxy",
+          observation_method: "host.apache_v",
+          candidates: [%w[apache2 -v], %w[httpd -v]],
+          parser: :parse_apache
+        },
+        {
+          product: "nginx",
+          scope: "reverse_proxy",
+          observation_method: "host.nginx_v",
+          candidates: [%w[nginx -v]],
+          parser: :parse_nginx
+        }
+      ].freeze
+
+      module_function
+
+      def collect
+        deadline = monotonic_now + AGGREGATE_TIMEOUT_SECONDS
+        DETECTORS.filter_map { |detector| detect(detector, deadline: deadline) }
+      rescue StandardError
+        []
+      end
+
+      def detect(detector, deadline: monotonic_now + AGGREGATE_TIMEOUT_SECONDS)
+        detector.fetch(:candidates).each do |argv|
+          break if monotonic_now >= deadline
+
+          output = capture(argv, deadline: deadline)
+          next if output.nil?
+
+          version = send(detector.fetch(:parser), output)
+          next if version.nil? || version.empty?
+
+          return Inventory::Components.build(
+            product: detector.fetch(:product),
+            version: version,
+            scope: detector.fetch(:scope),
+            observation_method: detector.fetch(:observation_method),
+            evidence: {
+              "command" => argv.first.to_s
+            }
+          )
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      # Resolve basename from trusted directories only; execute absolute path + fixed args.
+      def capture(argv, deadline: monotonic_now + AGGREGATE_TIMEOUT_SECONDS)
+        basename = argv.first.to_s
+        return nil unless ALLOWED_BASENAMES.include?(basename)
+
+        remaining = deadline - monotonic_now
+        return nil if remaining <= 0
+
+        executable = resolve_executable(basename)
+        return nil unless executable
+
+        full_argv = [executable] + argv.drop(1).map(&:to_s)
+        timeout_seconds = [PER_COMMAND_TIMEOUT_SECONDS, remaining].min
+        return nil if timeout_seconds <= 0
+
+        run_bounded(full_argv, timeout_seconds)
+      rescue StandardError
+        nil
+      end
+
+      def resolve_executable(basename)
+        return nil unless ALLOWED_BASENAMES.include?(basename)
+        return nil if basename.include?("/") || basename.include?("\\") || basename.include?("\0")
+
+        TRUSTED_BIN_DIRS.each do |dir|
+          next if dir.empty? || dir.include?("\0")
+
+          candidate = File.join(dir, basename)
+          next unless File.file?(candidate)
+          next unless File.executable?(candidate)
+
+          real_dir = begin
+            File.realpath(dir)
+          rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+            next
+          end
+
+          real_file = begin
+            File.realpath(candidate)
+          rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+            next
+          end
+
+          # Symlinks must not escape the trusted real directory boundary
+          # (supports ordinary /bin -> /usr/bin realpath equivalence).
+          next unless File.dirname(real_file) == real_dir
+          next unless trusted_material?(real_dir, real_file)
+
+          return real_file
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      # Trust is ownership + mode on the resolved real paths — not directory-name
+      # membership alone. Fail open (reject) when trust cannot be established.
+      #
+      # Policy:
+      # - material must be root-owned (uid 0); app-UID ownership is never enough
+      # - directory and executable must not be group- or world-writable
+      # - caller-configurable paths are never accepted
+      def trusted_material?(real_dir, real_file)
+        dir_stat = stat_path(real_dir)
+        file_stat = stat_path(real_file)
+        return false unless dir_stat && file_stat
+
+        trusted_stats?(dir_stat, file_stat)
+      rescue StandardError
+        false
+      end
+
+      def trusted_stats?(dir_stat, file_stat)
+        return false unless root_owned?(dir_stat) && root_owned?(file_stat)
+        return false if group_or_world_writable?(dir_stat)
+        return false if group_or_world_writable?(file_stat)
+        return false if app_user_owned_untrusted?(dir_stat)
+        return false if app_user_owned_untrusted?(file_stat)
+
+        true
+      end
+
+      def root_owned?(stat)
+        stat.uid.zero?
+      end
+
+      # Root-owned system material remains trusted even when the process euid is 0.
+      # Non-root owners (including the effective application user) are rejected.
+      def app_user_owned_untrusted?(stat)
+        return false if stat.uid.zero?
+
+        stat.uid == Process.euid
+      end
+
+      def group_or_world_writable?(stat)
+        (stat.mode & 0o022).nonzero?
+      end
+
+      def stat_path(path)
+        File.stat(path)
+      rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+        nil
+      end
+
+      def run_bounded(full_argv, timeout_seconds)
+        out_r, out_w = IO.pipe
+        err_r, err_w = IO.pipe
+        pid = nil
+
+        begin
+          pid = Process.spawn(
+            *full_argv,
+            in: :close,
+            out: out_w,
+            err: err_w,
+            pgroup: true,
+            close_others: true
+          )
+          out_w.close
+          err_w.close
+          out_w = err_w = nil
+
+          stdout = ""
+          stderr = ""
+          status = nil
+
+          Timeout.timeout(timeout_seconds) do
+            stdout = out_r.read(MAX_OUTPUT_BYTES).to_s
+            stderr = err_r.read(MAX_OUTPUT_BYTES).to_s
+            _pid, status = Process.wait2(pid)
+            pid = nil
+          end
+
+          combined = "#{stdout}\n#{stderr}".byteslice(0, MAX_OUTPUT_BYTES).to_s
+          return nil if combined.strip.empty?
+          return nil if status && !status.success? && combined !~ /version|Server version|nginx/i
+
+          combined
+        rescue Timeout::Error
+          nil
+        ensure
+          # Any post-spawn exit path (timeout, other exceptions, early return after wait)
+          # must account for the child while pid remains owned by this method.
+          if pid
+            begin
+              reap_process_group(pid)
+            rescue StandardError
+              nil
+            end
+            pid = nil
+          end
+
+          begin
+            out_w&.close
+          rescue StandardError
+            nil
+          end
+          begin
+            err_w&.close
+          rescue StandardError
+            nil
+          end
+          begin
+            out_r.close
+          rescue StandardError
+            nil
+          end
+          begin
+            err_r.close
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      def reap_process_group(pid)
+        return unless pid
+
+        begin
+          Process.kill("KILL", -pid)
+        rescue Errno::ESRCH, Errno::EPERM
+          begin
+            Process.kill("KILL", pid)
+          rescue Errno::ESRCH, Errno::EPERM
+            nil
+          end
+        end
+
+        loop do
+          Process.waitpid(pid)
+          break
+        rescue Errno::ECHILD
+          break
+        rescue Errno::EINTR
+          # Child may still be exiting; retry wait.
+          next
+        end
+      rescue StandardError
+        nil
+      end
+
+      def parse_openssl(output)
+        # OpenSSL 3.0.2 15 Mar 2022
+        if (match = output.match(/OpenSSL\s+([0-9][^\s]*)/i))
+          match[1]
+        end
+      end
+
+      def parse_apache(output)
+        # Server version: Apache/2.4.52 (Ubuntu)
+        if (match = output.match(%r{Apache/([0-9][^\s)]*)}i))
+          match[1]
+        end
+      end
+
+      def parse_nginx(output)
+        # nginx version: nginx/1.18.0 (Ubuntu)
+        if (match = output.match(%r{nginx/([0-9][^\s)]*)}i))
+          match[1]
+        end
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

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