auditea 0.1.0.beta.4 → 0.1.0.beta.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5459c8f22551f101e1aa2f32689bf47623c3ec2890f448ff5dd92c4980ee8c91
-  data.tar.gz: 2fb620c50bc457db6f85df2d1745b1c761e3141571a14451caef9080db109e7c
+  metadata.gz: 8ed0a68e5bfed09c0f764146e65c9b995d11c7070224a19fc6e682367626d0d1
+  data.tar.gz: cfdc642f25cab8125b3c8479b9aacbbaa13613650fa12a9b8160e21d92c2881f
 SHA512:
-  metadata.gz: faf9f0876938d536fe4aad106bba8b13ee72031ecb78c14d259a9a313eb046c84601b2b0ec3af9cb510d0b9581c7eb142aea169170f364e813b79ef7ae65f32d
-  data.tar.gz: df66f3cab946bb98383c903d550f4f7cf842386e4fea0b2fb11b6d037b4c0a2beee1d652c3381199e9c35a30c743a17039844b68c78494429fc64d04448fbc96
+  metadata.gz: 35cd56bc10b1010767e8078d5719639e12a056bc13aacd9472d1cda46d9679ddefba7519988af49faa26f7efd8ee664bdb1fe3f78eb27655b74c391a556406b6
+  data.tar.gz: 7911d88e0322ceba880eaeb09f0825d74079107612022aa60fbfff1e6e974a43a44b31d386ee304a5ff1d855d17ea1ca657198c4c3637eb7db6700ac2cb03dd6

data/CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 
-## 0.1.0.beta.4 (unreleased)
+## 0.1.0.beta.5 (unreleased)
+
+### SDK readiness diagnostic
+
+- `Auditea.diagnostic` returns a machine-readable readiness snapshot (config flags, endpoint, token presence, release, transport health, queue counters, warnings) — never the token value
+- `Auditea.emit_diagnostic!` emits the snapshot as a `diagnostic.sdk_ready` event (category `diagnostic`)
+- Rails boot emits one automatic **boot/startup diagnostic observation** when configured, in asynchronous mode only (fail-open, non-blocking). In synchronous mode the automatic emission is skipped so boot never performs inline network retry work; explicit user-requested synchronous delivery is unchanged. This is not a heartbeat and does not prove ongoing process liveness.
+- The snapshot describes transport state **before** the delivery of the diagnostic event that carries it; the first received diagnostic therefore has no prior delivery result.
+- `Transport::Queue` now tracks `delivered` count and last delivery `outcome`/`error` (`Client#health` / `Client#stats`); batched delivery is aggregated truthfully (all-accepted vs partial/failed)
+
+## 0.1.0.beta.4
 
 ### Platform component inventory (AUD-PLATFORM-INVENTORY01)
 

data/README.md

@@ -2,7 +2,7 @@
 
 Ruby / Rails SDK for [AudiTea](https://github.com/reznis/AudiTea) event collection.
 
-Version: **0.1.0.beta.4** (not published yet)
+Version: **0.1.0.beta.5** (proposed, not yet published)
 
 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.4"
+gem "auditea", "0.1.0.beta.5"
 ```
 
 ```bash

data/RELEASE.md

@@ -1,4 +1,4 @@
-# Release: auditea 0.1.0.beta.4
+# Release: auditea 0.1.0.beta.5
 
 Authoritative runbook for controlled beta publication of the Ruby SDK.
 
@@ -29,6 +29,22 @@ If AudiTea `main` advances after strict interop and before publication in a way
 
 ---
 
+## Ruby SDK setup catalog (AudiTea Source page)
+
+Any auditea-ruby release that changes the recommended gem version, configuration
+keys (ENV names), defaults, or capture capabilities **MUST** evaluate — and, when
+required, update — AudiTea's Ruby SDK setup catalog
+(`config/auditea_sdks/ruby.yml` in `reznis/AudiTea`) before that release is
+considered fully rollout-ready.
+
+The catalog is the single source of truth for the setup instructions rendered on
+the AudiTea Source page. A release whose advertised settings diverge from the
+catalog produces stale or misleading customer onboarding instructions. Updating
+the recommended supported version remains an intentional release action — never a
+runtime RubyGems query.
+
+---
+
 ## Two interoperability gates (do not conflate)
 
 ### Gate A — pinned AudiTea envelope compatibility
@@ -153,10 +169,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.4
+# confirm VERSION and CHANGELOG still say 0.1.0.beta.5
 gem build auditea.gemspec
 # inspect package once more
-gem push auditea-0.1.0.beta.4.gem
+gem push auditea-0.1.0.beta.5.gem
 ```
 
 Then mark CHANGELOG released with the publication date in a follow-up commit.
@@ -166,9 +182,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.4 --pre
+gem install auditea -v 0.1.0.beta.5 --pre
 ruby -rauditea -e 'puts Auditea::VERSION'
-# expect: 0.1.0.beta.4
+# expect: 0.1.0.beta.5
 ```
 
 Prefer installing the RubyGems artifact (not a git branch) into the controlled TEST app.

data/examples/support/windows_smoke_gate.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Gate logic for examples/windows_inventory_smoke.rb — extracted so the exit
+# behavior can be unit-tested without running a real Windows host.
+module WindowsSmokeGate
+  module_function
+
+  Result = Data.define(:label, :ok)
+
+  # platform: the inventory "platform" hash (os_name / os_version).
+  # components: the inventory "components" array.
+  # require_edition: when set, the os_name must equal this exact edition.
+  # require_products: product names that MUST be present in components.
+  def checks(platform:, components:, require_edition: nil, require_products: [])
+    platform = {} unless platform.is_a?(Hash)
+    components = Array(components)
+
+    results = []
+    results << Result.new(label: "windows edition detected", ok: edition_ok?(platform["os_name"].to_s, require_edition))
+    results << Result.new(label: "os build present", ok: !platform["os_version"].to_s.strip.empty?)
+
+    Array(require_products).each do |product|
+      results << Result.new(label: "product detected: #{product}", ok: components.any? { |c|
+        c["product"].to_s == product.to_s
+      })
+    end
+
+    results
+  end
+
+  def edition_ok?(edition, require_edition)
+    return false if edition.empty?
+    return false if edition == "Windows_NT" # kernel-only: edition unknown
+
+    return edition == require_edition if require_edition && !require_edition.to_s.empty?
+
+    true
+  end
+
+  def failed?(results)
+    Array(results).any? { |result| !result.ok }
+  end
+end

data/examples/windows_inventory_smoke.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Windows host-inventory smoke — run ON the Windows host (e.g. IRCM). No server needed.
+#
+# Validates the full detection path end-to-end:
+#   Gem.win_platform? -> windows? -> reg.exe -> parse -> components + OS edition.
+#
+# NEVER transmits anything to AudiTea: it calls Collector directly and prints
+# only. Do not require AUDITEA_CAPTURE_HOST_INVENTORY=1 to run it.
+#
+# Usage (from an auditea-ruby checkout):
+#   bundle exec ruby examples/windows_inventory_smoke.rb
+#
+# Gate (exit 1 when a required expectation fails):
+#   REQUIRE_EDITION="Windows Server 2016 Standard" \
+#   REQUIRE_PRODUCTS="Apache HTTP Server,OpenSSL" \
+#   bundle exec ruby examples/windows_inventory_smoke.rb
+#
+# Expected on IRCM:
+#   platform.os_name    == "Windows Server 2016 Standard"  (NOT "Windows_NT")
+#   platform.os_version == "10.0.14393"                    (NOT "unknown")
+#   a component { "product" => "Apache HTTP Server", "scope" => "reverse_proxy", ... }
+#   a component { "product" => "OpenSSL", "scope" => "host_component", ... }
+
+require "auditea"
+require "json"
+require_relative "support/windows_smoke_gate"
+
+inventory = Auditea::HostInventory::Collector.collect
+
+platform = inventory["platform"] || {}
+components = inventory["components"] || []
+
+puts "== platform =="
+puts JSON.pretty_generate(platform)
+
+puts "== sdk =="
+puts JSON.pretty_generate(inventory["sdk"])
+
+puts "== components (#{components.size}) =="
+components.each { |component| puts JSON.pretty_generate(component) }
+puts "(no components)" if components.empty?
+
+require_edition = ENV["REQUIRE_EDITION"].to_s.strip
+require_products = ENV["REQUIRE_PRODUCTS"].to_s.split(",").map(&:strip).reject(&:empty?)
+
+results = WindowsSmokeGate.checks(
+  platform: platform,
+  components: components,
+  require_edition: require_edition.empty? ? nil : require_edition,
+  require_products: require_products
+)
+
+puts
+puts "== checks =="
+results.each do |result|
+  puts format("%-40<label>s %<verdict>s", label: result.label, verdict: (result.ok ? "PASS" : "FAIL"))
+end
+
+if WindowsSmokeGate.failed?(results)
+  warn "smoke gate FAILED — see checks above."
+  exit 1
+end
+
+puts "smoke gate passed."

data/lib/auditea/client.rb

@@ -25,6 +25,16 @@ module Auditea
       queue.shutdown
     end
 
+    # Queue depth/drop/inflight counters (see Transport::Queue#stats).
+    def stats
+      queue.stats
+    end
+
+    # Recent transport health: last delivery outcome + error (see Transport::Queue#health).
+    def health
+      queue.health
+    end
+
     def reset!
       shutdown
       rebuild!

data/lib/auditea/configuration.rb

@@ -20,7 +20,7 @@ module Auditea
                   :open_timeout, :write_timeout, :max_retries, :logger, :release, :sdk_name,
                   :capture_requests, :capture_exceptions, :capture_request_params,
                   :capture_active_job, :capture_runtime_inventory, :capture_host_inventory,
-                  :inventory_refresh_interval, :host_key, :host_label,
+                  :emit_boot_diagnostic, :inventory_refresh_interval, :host_key, :host_label,
                   :message_max_bytes, :nesting_max_depth
 
     def initialize
@@ -47,6 +47,7 @@ module Auditea
       @capture_runtime_inventory = truthy?(ENV.fetch("AUDITEA_CAPTURE_RUNTIME_INVENTORY", "false"))
       # Opt-in: host/platform inventory (opaque node id + OS facts).
       @capture_host_inventory = truthy?(ENV.fetch("AUDITEA_CAPTURE_HOST_INVENTORY", "false"))
+      @emit_boot_diagnostic = truthy?(ENV.fetch("AUDITEA_EMIT_BOOT_DIAGNOSTIC", "true"))
       @host_key = ENV.fetch("AUDITEA_HOST_KEY", nil)
       @host_label = ENV.fetch("AUDITEA_HOST_LABEL", nil)
       @inventory_refresh_interval = float_env(
@@ -98,6 +99,12 @@ module Auditea
       host = normalize_host(uri.host)
       return false if host.empty?
 
+      # A base endpoint has no legitimate userinfo (credentials), query, or
+      # fragment. Reject these dangerous URL forms rather than silently
+      # supporting them — they can embed secrets in a place the generic key
+      # sanitizer cannot reach.
+      return false if uri.userinfo || uri.query || uri.fragment
+
       case uri
       when URI::HTTPS
         true

data/lib/auditea/diagnostic.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Auditea
+  # Builds a machine-readable readiness snapshot for the SDK: what is configured,
+  # what is missing, and recent transport health.
+  #
+  # Never includes the source token value — only its presence. Intended both for
+  # direct inspection (`Auditea.diagnostic`) and for transport as event metadata
+  # (`Auditea.emit_diagnostic!` → `diagnostic.sdk_ready`).
+  class Diagnostic
+    def self.call
+      new.call
+    end
+
+    def call
+      cfg = Auditea.configuration
+      {
+        gem_version: VERSION,
+        configured: cfg.configured?,
+        endpoint: safe_endpoint(cfg.endpoint),
+        token_present: token_present?(cfg),
+        release: presence(cfg.release),
+        enabled: cfg.enabled?,
+        async: cfg.async?,
+        raise_errors: cfg.raise_errors,
+        capture_exceptions: cfg.capture_exceptions,
+        capture_runtime_inventory: cfg.capture_runtime_inventory?,
+        capture_host_inventory: cfg.capture_host_inventory?,
+        capture_requests: cfg.capture_requests,
+        capture_request_params: cfg.capture_request_params,
+        capture_active_job: cfg.capture_active_job,
+        valid: valid?(cfg),
+        transport: Auditea.client.health,
+        queue: Auditea.client.stats,
+        warnings: warnings(cfg)
+      }
+    end
+
+    private
+
+    def token_present?(cfg)
+      !cfg.source_token.to_s.strip.empty?
+    end
+
+    # Endpoint representation safe-by-construction: strips userinfo (credentials),
+    # query, and fragment so secrets embedded in the URL never enter the snapshot.
+    # Returns nil for an unparseable endpoint (nothing sensitive is exposed).
+    def safe_endpoint(value)
+      uri = URI.parse(value.to_s)
+      return nil if uri.host.to_s.empty?
+
+      uri.user = nil
+      uri.password = nil
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s
+    rescue URI::InvalidURIError, ArgumentError
+      nil
+    end
+
+    def valid?(cfg)
+      cfg.validate!
+      true
+    rescue ConfigurationError
+      false
+    end
+
+    def warnings(cfg)
+      [].tap do |warnings|
+        warnings << "source_token unset" unless token_present?(cfg)
+        warnings << "release unset — events will lack a release" if presence(cfg.release).nil?
+        if cfg.endpoint.to_s == Configuration::DEFAULT_ENDPOINT
+          warnings << "endpoint is the SDK default (#{Configuration::DEFAULT_ENDPOINT})"
+        end
+        warnings << "runtime inventory disabled" unless cfg.capture_runtime_inventory?
+        warnings << "host inventory disabled" unless cfg.capture_host_inventory?
+        warnings << "raise_errors enabled — SDK errors may raise in the application" if cfg.raise_errors
+        warnings << "SDK disabled" unless cfg.enabled?
+      end
+    end
+
+    def presence(value)
+      value.to_s.strip.empty? ? nil : value.to_s.strip
+    end
+  end
+end

data/lib/auditea/host_inventory/collector.rb

@@ -70,7 +70,7 @@ module Auditea
             product: product,
             version: version,
             scope: "host_os",
-            observation_method: "os_release"
+            observation_method: host_os_provenance(platform)
           )
         end
 
@@ -88,6 +88,14 @@ module Auditea
         list
       end
 
+      # The OS-edition row's provenance differs by platform: /etc/os-release on
+      # Linux, the Windows registry ProductName on Windows. Never claim os_release
+      # for a Windows host.
+      def host_os_provenance(platform)
+        platform["os_family"].to_s == "windows" ? "windows.registry" : "os_release"
+      end
+      private_class_method :host_os_provenance
+
       def resolve_host_key!
         configured = Auditea.configuration.host_key.to_s.strip
         configured = ENV.fetch("AUDITEA_HOST_KEY", "").to_s.strip if configured.empty?
@@ -172,6 +180,14 @@ module Auditea
           }
         end
 
+        if os_family == "windows"
+          return {
+            name: first_present(WindowsComponents.product_name, uname[:sysname], "Windows"),
+            # Windows kernel release doubles as the OS build (e.g. "10.0.14393").
+            version: first_present(uname[:release])
+          }
+        end
+
         {
           name: first_present(uname[:sysname], RbConfig::CONFIG["host_os"]),
           # Never substitute kernel build metadata (uname.version) as product OS version.

data/lib/auditea/host_inventory/component_detectors.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "timeout"
+require_relative "windows_components"
 
 module Auditea
   module HostInventory
@@ -51,6 +52,8 @@ module Auditea
       module_function
 
       def collect
+        return WindowsComponents.collect if WindowsComponents.windows?
+
         deadline = monotonic_now + AGGREGATE_TIMEOUT_SECONDS
         DETECTORS.filter_map { |detector| detect(detector, deadline: deadline) }
       rescue StandardError

data/lib/auditea/host_inventory/windows_components.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "../inventory/components"
+
+module Auditea
+  module HostInventory
+    # Windows-only host component detection via read-only registry queries.
+    #
+    # Windows binaries live in untrusted app-specific directories, so we never
+    # execute the installed product itself. Instead we read the uninstall registry
+    # (fixed `reg.exe query` argv — no shell, no PATH search, no caller paths) to
+    # observe installed products, and read the OS ProductName for edition identity.
+    module WindowsComponents
+      AGGREGATE_TIMEOUT_SECONDS = 2.5
+      PER_COMMAND_TIMEOUT_SECONDS = 1.0
+      # Total accumulated bytes we retain per stream. Output beyond this is still
+      # drained (so the child never blocks on a full pipe) but not accumulated.
+      # A real uninstall tree can exceed a few KiB; 1 MiB is ample headroom while
+      # still keeping the reader's memory bounded.
+      REG_MAX_OUTPUT = 1_048_576
+      REG_READ_CHUNK = 8_192
+      REG_DIRS = ["C:\\Windows\\System32", "C:\\Windows\\SysWOW64"].freeze
+      PRODUCT_NAME_KEY = 'HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion'
+      # Single canonical key; access both 32-bit and 64-bit registry views
+      # explicitly instead of relying on implicit WOW64 redirection.
+      UNINSTALL_KEY = 'HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall'
+      UNINSTALL_VIEWS = %w[/reg:64 /reg:32].freeze
+
+      # DisplayName → canonical component. Read-only: never executes the product binary.
+      PRODUCT_MATCHERS = [
+        {
+          pattern: /\Aapache\s+http\s+server/i,
+          product: "Apache HTTP Server",
+          scope: "reverse_proxy",
+          method: "windows.uninstall_registry"
+        },
+        {
+          pattern: /\Anginx/i,
+          product: "nginx",
+          scope: "reverse_proxy",
+          method: "windows.uninstall_registry"
+        },
+        {
+          pattern: /\Aopenssl/i,
+          product: "OpenSSL",
+          scope: "host_component",
+          method: "windows.uninstall_registry"
+        }
+      ].freeze
+
+      # Generic Windows software channel. We observe "installed in the Windows
+      # uninstall registry" — the specific installer technology (MSI/Chocolatey/
+      # winget) is unknown, so we claim only the generic Windows ecosystem and let
+      # the server route it to the Windows vendor channel.
+      WINDOWS_PACKAGE = { "ecosystem" => "windows" }.freeze
+
+      module_function
+
+      def windows?
+        Gem.win_platform? || RbConfig::CONFIG["host_os"].to_s.match?(/mswin|mingw|cygwin/i)
+      end
+
+      # Deterministic read-only query plan: the canonical uninstall key under
+      # both explicit registry views. Exposed for testing and dedup guarantees.
+      def uninstall_queries
+        UNINSTALL_VIEWS.map { |view| ["query", UNINSTALL_KEY, "/s", view] }
+      end
+
+      def collect(deadline: monotonic_now + AGGREGATE_TIMEOUT_SECONDS)
+        seen = {}
+        uninstall_queries.each do |argv|
+          remaining = deadline - monotonic_now
+          break if remaining <= 0
+
+          output = run_reg(argv, timeout: [PER_COMMAND_TIMEOUT_SECONDS, remaining].min)
+          next if output.nil?
+
+          parse_uninstall(output).each do |(name, version)|
+            matcher = PRODUCT_MATCHERS.find { |m| name.to_s.match?(m[:pattern]) }
+            next unless matcher
+
+            # Dedup only identical observations. Key on product + version + scope
+            # so multiple installed versions of the same product are all preserved
+            # (the hidden one may be the vulnerable one); a repeated identical
+            # version across the 32/64-bit views collapses to a single component.
+            key = [matcher[:product], version, matcher[:scope]]
+            next if seen.key?(key)
+
+            seen[key] = Inventory::Components.build(
+              product: matcher[:product],
+              version: version,
+              scope: matcher[:scope],
+              observation_method: matcher[:method],
+              package: WINDOWS_PACKAGE,
+              evidence: { "command" => "reg.exe" }
+            )
+          end
+        end
+        seen.values
+      end
+
+      def parse_uninstall(output)
+        entries = []
+        name = nil
+        version = nil
+        output.to_s.each_line do |line|
+          stripped = line.strip
+          if stripped.start_with?("HKEY_")
+            entries << [name, version] if name && version
+            name = nil
+            version = nil
+            next
+          end
+
+          if (match = stripped.match(/\ADisplayName\s+REG_\S+\s+(.+)\z/i))
+            name = match[1].to_s.strip
+          elsif (match = stripped.match(/\ADisplayVersion\s+REG_\S+\s+(.+)\z/i))
+            version = match[1].to_s.strip
+          end
+        end
+        entries << [name, version] if name && version
+        entries
+      end
+
+      # ProductName from HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion
+      # (e.g. "Windows Server 2016 Standard"). Fails open → nil when absent.
+      def product_name
+        read_value(PRODUCT_NAME_KEY, "ProductName")
+      end
+
+      def read_value(key, name)
+        return nil unless windows?
+
+        output = run_reg(["query", key, "/v", name])
+        return nil if output.nil?
+
+        parse_value(output, name)
+      end
+
+      def parse_value(output, name)
+        pattern = /\A\s*#{Regexp.escape(name)}\s+REG_\S+\s+(.+)\z/i
+        output.to_s.each_line do |line|
+          if (match = line.strip.match(pattern))
+            return match[1].to_s.strip
+          end
+        end
+        nil
+      end
+
+      # reg.exe lives in a fixed trusted system directory; argv is fixed and
+      # read-only (`query`). No PATH search, no shell, no caller-supplied paths.
+      # Fail-open: any registry-execution failure (missing exe, EACCES/AppLocker,
+      # spawn failure) yields nil so host inventory never breaks.
+      def run_reg(args, timeout: PER_COMMAND_TIMEOUT_SECONDS)
+        reg = resolve_reg_exe
+        return nil unless reg
+        return nil if timeout.to_f <= 0
+
+        run_bounded([reg] + Array(args).map(&:to_s), timeout)
+      rescue StandardError
+        nil
+      end
+
+      def resolve_reg_exe
+        REG_DIRS.each do |dir|
+          candidate = File.join(dir, "reg.exe")
+          return candidate if File.file?(candidate)
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      # Executes the fixed argv and returns combined stdout/stderr, draining BOTH
+      # streams concurrently to EOF so a large uninstall tree cannot block the
+      # child on a full pipe. Accumulated memory is bounded at REG_MAX_OUTPUT per
+      # stream; beyond that we keep draining (discard) so the child still exits.
+      # Returns nil on timeout, non-zero exit, empty output, or spawn failure.
+      def run_bounded(full_argv, timeout_seconds)
+        out_r, out_w = IO.pipe
+        err_r, err_w = IO.pipe
+        pid = nil
+        readers = []
+
+        begin
+          pid = spawn_process(full_argv, out_w, err_w)
+          out_w.close
+          err_w.close
+          out_w = err_w = nil
+
+          stdout = +"".b
+          stderr = +"".b
+          readers = [
+            Thread.new { stdout = drain_io(out_r) },
+            Thread.new { stderr = drain_io(err_r) }
+          ]
+
+          status = nil
+          Timeout.timeout(timeout_seconds) do
+            _pid, status = Process.wait2(pid)
+            pid = nil
+          end
+          readers.each(&:join)
+
+          combined = "#{stdout}\n#{stderr}"
+          return nil if combined.strip.empty?
+          return nil if status && !status.success?
+
+          combined
+        rescue Timeout::Error, SystemCallError, IOError
+          nil
+        ensure
+          if pid
+            reap(pid)
+            pid = nil
+          end
+
+          close_io(out_w)
+          close_io(err_w)
+          close_io(out_r)
+          close_io(err_r)
+          readers.each { |reader| reader.join(0.1) }
+        end
+      end
+
+      # Reads a stream to EOF in bounded chunks, retaining at most REG_MAX_OUTPUT
+      # bytes but continuing to drain the rest so the writer never blocks.
+      def drain_io(io)
+        out = +"".b
+        loop do
+          chunk = io.read(REG_READ_CHUNK)
+          break if chunk.nil?
+          next if out.bytesize >= REG_MAX_OUTPUT
+
+          out << chunk
+          out = out.byteslice(0, REG_MAX_OUTPUT) if out.bytesize > REG_MAX_OUTPUT
+        end
+        out
+      rescue IOError, Errno::EIO, Errno::EBADF
+        out
+      end
+
+      # Windows spawns in a new process group (`new_pgroup:`), POSIX uses `pgroup:`.
+      # The POSIX branch also allows the Windows reader to be integration-tested on
+      # Linux against a fixture executable.
+      def spawn_process(full_argv, out_w, err_w)
+        if windows?
+          Process.spawn(*full_argv, in: :close, out: out_w, err: err_w, new_pgroup: true)
+        else
+          Process.spawn(*full_argv, in: :close, out: out_w, err: err_w, pgroup: true)
+        end
+      end
+
+      def reap(pid)
+        begin
+          Process.kill("KILL", pid)
+        rescue StandardError
+          nil
+        end
+
+        loop do
+          Process.waitpid(pid)
+          break
+        rescue Errno::ECHILD
+          break
+        rescue Errno::EINTR
+          next
+        end
+      rescue StandardError
+        nil
+      end
+
+      def close_io(io)
+        io&.close
+      rescue StandardError
+        nil
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/auditea/railtie.rb

@@ -31,6 +31,33 @@ module Auditea
       rescue StandardError => error
         Auditea.handle_error(error)
       end
+
+      begin
+        # One automatic boot/startup diagnostic observation when configured.
+        # Never crash boot: fully fail-open (swallow, log, continue) regardless of
+        # raise_errors.
+        Auditea::Railtie.emit_boot_diagnostic!
+      rescue StandardError => error
+        Rails.logger&.warn("[auditea] boot diagnostic skipped: #{error.class}: #{error.message.to_s.byteslice(0, 200)}")
+      end
+    end
+
+    # Emits a single automatic boot/startup diagnostic observation when the SDK is
+    # configured and the flag is enabled.
+    #
+    # Emitted only in asynchronous mode. In synchronous mode the automatic
+    # observation is skipped entirely: enqueue would perform inline HTTP (including
+    # retries/timeouts), adding an external-network dependency to Rails startup.
+    # This does NOT weaken explicit user-requested synchronous delivery
+    # (Auditea.emit_diagnostic! / capture with async:false still deliver inline);
+    # it only gates the automatic boot path. The local snapshot
+    # (Auditea.diagnostic) remains available regardless.
+    def self.emit_boot_diagnostic!
+      cfg = Auditea.configuration
+      return unless cfg.configured? && cfg.emit_boot_diagnostic
+      return unless cfg.async?
+
+      Auditea.emit_diagnostic!(flush: false)
     end
   end
 end

data/lib/auditea/sanitizer.rb

@@ -16,8 +16,37 @@ module Auditea
       otp otp_secret session_id credit_card card_number cvv ssn
     ].freeze
 
+    # URI credential forms are stripped from diagnostic value strings (endpoint,
+    # transport errors, warnings). This is a bounded field-specific redaction for
+    # the diagnostic contract, NOT a general secret scanner.
+    URI_USERINFO_RE = %r{(https?://)[^/\s@]+@}i
+    SENSITIVE_QUERY_RE = /
+      ([?&]
+        (?:token|password|passwd|secret|api_?key|access_token|refresh_token|
+           auth|authorization|key|signature|sig|credential)
+        =
+      )
+      [^&\s]*
+    /ix
+
     module_function
 
+    # Scrub URI userinfo (`scheme://user:pass@host`) and sensitive query values
+    # from a free-form diagnostic string, then bound its length.
+    def sanitize_diagnostic_string(value, max_bytes:)
+      return nil if value.nil?
+
+      scrub_uri_credentials(value.to_s).byteslice(0, max_bytes)
+    end
+
+    # Remove `user:password@` from any embedded http(s) URL and redact the value
+    # of sensitive query parameters. Field-specific: only URI credential shapes.
+    def scrub_uri_credentials(text)
+      text.to_s
+          .gsub(URI_USERINFO_RE) { Regexp.last_match(1) }
+          .gsub(SENSITIVE_QUERY_RE) { "#{Regexp.last_match(1)}[REDACTED]" }
+    end
+
     def sanitize_event(event)
       redacted = []
       sanitized = deep_sanitize(event, depth: 0, path: nil, redacted: redacted)

data/lib/auditea/transport/queue.rb

@@ -18,7 +18,10 @@ module Auditea
         @buffer = []
         @stopped = false
         @dropped = 0
+        @delivered = 0
         @inflight = 0
+        @last_outcome = nil
+        @last_error = nil
         @thread = nil
         @owner_pid = nil
       end
@@ -95,7 +98,22 @@ module Auditea
 
       def stats
         ensure_process!
-        @mutex.synchronize { { size: @buffer.size, dropped: @dropped, inflight: @inflight, pid: @owner_pid } }
+        @mutex.synchronize do
+          {
+            size: @buffer.size,
+            dropped: @dropped,
+            delivered: @delivered,
+            inflight: @inflight,
+            pid: @owner_pid
+          }
+        end
+      end
+
+      # Recent transport health for diagnostics: what happened to the last delivery
+      # attempt (accepted / unauthorized / exhausted / error / …) and, on failure, why.
+      def health
+        ensure_process!
+        @mutex.synchronize { { last_outcome: @last_outcome, last_error: @last_error } }
       end
 
       private
@@ -106,10 +124,15 @@ module Auditea
           if @owner_pid.nil?
             @owner_pid = pid
           elsif @owner_pid != pid
-            # Child after fork: drop inherited buffer/worker; do not deliver parent data.
+            # Child after fork: drop inherited buffer/worker; do not deliver parent
+            # data. Also reset the diagnostic transport counters/state so the child
+            # describes its own process, not the one it forked from.
             @buffer = []
             @inflight = 0
             @dropped = 0
+            @delivered = 0
+            @last_outcome = nil
+            @last_error = nil
             @stopped = false
             @thread = nil
             @owner_pid = pid
@@ -183,9 +206,11 @@ module Auditea
             else
               @http.post_batch(events)
             end
+          record_delivery(result)
           handle_result(events, result)
           result
         rescue StandardError => error
+          record_delivery_error(error)
           @configuration.logger&.warn("[auditea] delivery failed: #{error.class}: #{error.message.to_s.byteslice(0,
                                                                                                                  200)}")
           raise if @configuration.raise_errors
@@ -220,6 +245,57 @@ module Auditea
         nil
       end
 
+      def record_delivery(result)
+        delivered, outcome, error = aggregate_delivery(result)
+        @mutex.synchronize do
+          @last_outcome = outcome
+          @last_error = error
+          @delivered += delivered
+        end
+      end
+
+      def record_delivery_error(error)
+        @mutex.synchronize do
+          @last_outcome = "error"
+          @last_error = Sanitizer.sanitize_diagnostic_string("#{error.class}: #{error.message}", max_bytes: 200)
+        end
+      end
+
+      # Truthful aggregate outcome for a single-event or batch DeliveryResult.
+      # `delivered` counts only events the server accepted/treated as success.
+      def aggregate_delivery(result)
+        return [0, "accepted", nil] unless result.is_a?(DeliveryResult)
+
+        if result.results
+          rows = result.results
+          delivered = rows.count { |row| row["ok"] }
+          [delivered, aggregate_batch_outcome(rows), aggregate_batch_error(rows)]
+        else
+          delivered = result.ok? ? 1 : 0
+          error = result.ok? ? nil : Sanitizer.sanitize_diagnostic_string(result.message, max_bytes: 200)
+          [delivered, result.outcome.to_s, error]
+        end
+      end
+
+      def aggregate_batch_outcome(rows)
+        return "error" if rows.empty?
+
+        ok = rows.count { |row| row["ok"] }
+        return "accepted" if ok == rows.size
+
+        bad_outcomes = rows.reject { |row| row["ok"] }.map { |row| row["outcome"] }.compact.uniq
+        return "partial_failure" if ok.positive?
+
+        # Total failure: surface the single uniform outcome, else a generic error.
+        bad_outcomes.size == 1 ? bad_outcomes.first : "error"
+      end
+
+      def aggregate_batch_error(rows)
+        return nil if rows.all? { |row| row["ok"] }
+
+        Sanitizer.sanitize_diagnostic_string("mixed_batch_results", max_bytes: 200)
+      end
+
       def log_drop(event_id, reason)
         @configuration.logger&.warn("[auditea] event_id=#{event_id} reason=#{reason}")
       end

data/lib/auditea/version.rb

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

data/lib/auditea.rb

@@ -22,6 +22,7 @@ require_relative "auditea/event_builder"
 require_relative "auditea/actor"
 require_relative "auditea/target"
 require_relative "auditea/current_context"
+require_relative "auditea/diagnostic"
 require_relative "auditea/transport/limits"
 require_relative "auditea/transport/delivery_result"
 require_relative "auditea/transport/http"
@@ -142,6 +143,21 @@ module Auditea
       HostInventory.maybe_capture!
     end
 
+    # Machine-readable readiness snapshot (config + transport health + warnings).
+    # Never includes the source token value.
+    def diagnostic
+      Diagnostic.call
+    end
+
+    # Emit the readiness snapshot as a `diagnostic.sdk_ready` event, then flush.
+    # Returns the capture result (fail-open: { ok: false, skipped: true, reason: … }
+    # when disabled or not configured).
+    def emit_diagnostic!(flush: true)
+      result = capture("diagnostic.sdk_ready", category: "diagnostic", severity: "info", metadata: Diagnostic.call)
+      flush(timeout: 10) if flush
+      result
+    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.4
+  version: 0.1.0.beta.5
 platform: ruby
 authors:
 - AudiTea
@@ -24,17 +24,21 @@ files:
 - RELEASE.md
 - auditea.gemspec
 - examples/manual_capture.rb
+- examples/support/windows_smoke_gate.rb
+- examples/windows_inventory_smoke.rb
 - lib/auditea.rb
 - lib/auditea/actor.rb
 - lib/auditea/client.rb
 - lib/auditea/configuration.rb
 - lib/auditea/current_context.rb
+- lib/auditea/diagnostic.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/component_detectors.rb
 - lib/auditea/host_inventory/emitter.rb
+- lib/auditea/host_inventory/windows_components.rb
 - lib/auditea/instrumentation/active_job.rb
 - lib/auditea/instrumentation/error_subscriber.rb
 - lib/auditea/instrumentation/exception.rb