auditea 0.1.0.beta.3 → 0.1.0.beta.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 587d3b57a35018f55c5e82c15a485715913e911a714971797a47fde50d788251
-  data.tar.gz: beae506f6609e933baa4d4513e9015cc7b11c919a75ed83ba912eeb546aae0e5
+  metadata.gz: 8ed0a68e5bfed09c0f764146e65c9b995d11c7070224a19fc6e682367626d0d1
+  data.tar.gz: cfdc642f25cab8125b3c8479b9aacbbaa13613650fa12a9b8160e21d92c2881f
 SHA512:
-  metadata.gz: 16e6ebde275b1f03f12028ca1c746fdedd9efb907706560ecae52b1fed188e90944f0e827c40e7a1cb909742d381fe37d26deb385ee66d82965c8185444ac99f
-  data.tar.gz: e0c7097c1f146d724befdaf2df850e30a556c670a06406f459003b46a2b52fc77687b36d3fa366d3db4662e13718ddf70ea12698480555858bf51650ee9781c8
+  metadata.gz: 35cd56bc10b1010767e8078d5719639e12a056bc13aacd9472d1cda46d9679ddefba7519988af49faa26f7efd8ee664bdb1fe3f78eb27655b74c391a556406b6
+  data.tar.gz: 7911d88e0322ceba880eaeb09f0825d74079107612022aa60fbfff1e6e974a43a44b31d386ee304a5ff1d855d17ea1ca657198c4c3637eb7db6700ac2cb03dd6

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 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)
+
+- 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)

data/README.md

@@ -2,7 +2,7 @@
 
 Ruby / Rails SDK for [AudiTea](https://github.com/reznis/AudiTea) event collection.
 
-Version: **0.1.0.beta.3** (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.3"
+gem "auditea", "0.1.0.beta.5"
 ```
 
 ```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).
@@ -155,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.3
+# 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.3
+# 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.3.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.3 --pre
+gem install auditea -v 0.1.0.beta.5 --pre
 ruby -rauditea -e 'puts Auditea::VERSION'
-# expect: 0.1.0.beta.3
+# 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

@@ -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,62 @@ 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: host_os_provenance(platform)
+          )
+        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
+
+      # 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?
@@ -127,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.
@@ -224,6 +285,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