fiber_audit 0.1.0 → 0.2.1

data/lib/fiber_audit/configuration.rb

@@ -4,13 +4,34 @@ require 'yaml'
 require 'pathname'
 require_relative 'errors'
 require_relative 'findings/severity'
+require_relative 'runtime/policy'
+require_relative 'runtime/watchdog_policy'
 
 module FiberAudit
+  # rubocop:disable Metrics/ClassLength
   class Configuration
-    KNOWN_TOP_LEVEL_KEYS = %w[static rules report].freeze
+    KNOWN_TOP_LEVEL_KEYS = %w[static rules report runtime].freeze
     KNOWN_STATIC_KEYS = %w[include exclude suppressions_path].freeze
     KNOWN_REPORT_KEYS = %w[formats min_severity].freeze
     KNOWN_RULE_KEYS = %w[enabled severity].freeze
+    KNOWN_RUNTIME_KEYS = %w[redaction sampling overhead watchdog fail_open].freeze
+    KNOWN_REDACTION_KEYS = %w[mode].freeze
+    KNOWN_SAMPLING_KEYS = %w[rate].freeze
+    KNOWN_OVERHEAD_KEYS = %w[
+      max_events_per_second max_events_per_session max_record_bytes max_session_bytes
+    ].freeze
+    KNOWN_WATCHDOG_KEYS = %w[
+      enabled heartbeat_interval_ms stall_threshold_ms max_frames
+    ].freeze
+    RUNTIME_POLICY_PATHS = {
+      'redaction' => 'runtime.redaction.mode',
+      'sampling_rate' => 'runtime.sampling.rate',
+      'max_events_per_second' => 'runtime.overhead.max_events_per_second',
+      'max_events_per_session' => 'runtime.overhead.max_events_per_session',
+      'max_record_bytes' => 'runtime.overhead.max_record_bytes',
+      'max_session_bytes' => 'runtime.overhead.max_session_bytes',
+      'fail_open' => 'runtime.fail_open'
+    }.freeze
     VALID_FORMATS = %w[text json].freeze
 
     DEFAULT_STATIC_INCLUDE = %w[
@@ -28,7 +49,8 @@ module FiberAudit
     ].freeze
 
     attr_reader :static_include, :static_exclude, :rules_config,
-                :report_formats, :min_severity, :suppressions_path
+                :report_formats, :min_severity, :suppressions_path,
+                :runtime_policy, :runtime_watchdog_policy
 
     def initialize(
       static_include: DEFAULT_STATIC_INCLUDE,
@@ -36,11 +58,14 @@ module FiberAudit
       rules_config: {},
       report_formats: %w[text],
       min_severity: :low,
-      suppressions_path: nil
+      suppressions_path: nil,
+      runtime_policy: Runtime::Policy.new,
+      runtime_watchdog_policy: Runtime::WatchdogPolicy.new
     )
       validate_types!(
         static_include, static_exclude, rules_config,
-        report_formats, min_severity, suppressions_path
+        report_formats, min_severity, suppressions_path, runtime_policy,
+        runtime_watchdog_policy
       )
 
       @static_include = static_include
@@ -49,6 +74,8 @@ module FiberAudit
       @report_formats = report_formats
       @min_severity = coerce_severity(min_severity, 'report.min_severity')
       @suppressions_path = suppressions_path
+      @runtime_policy = runtime_policy
+      @runtime_watchdog_policy = runtime_watchdog_policy
     end
 
     def rule_enabled?(rule_id)
@@ -76,6 +103,7 @@ module FiberAudit
         static = yaml['static'] || {}
         rules = yaml['rules'] || {}
         report = yaml['report'] || {}
+        runtime = yaml['runtime'] || {}
 
         new(
           static_include: static['include'] || DEFAULT_STATIC_INCLUDE,
@@ -83,7 +111,9 @@ module FiberAudit
           rules_config: rules,
           report_formats: report['formats'] || %w[text],
           min_severity: report.fetch('min_severity', :low),
-          suppressions_path: static['suppressions_path']
+          suppressions_path: static['suppressions_path'],
+          runtime_policy: runtime_policy_from(runtime),
+          runtime_watchdog_policy: runtime_watchdog_policy_from(runtime)
         )
       end
 
@@ -115,6 +145,8 @@ module FiberAudit
           check_unknown_keys(report, KNOWN_REPORT_KEYS, 'report')
         end
 
+        validate_runtime_structure!(yaml['runtime']) if yaml.key?('runtime')
+
         return unless yaml.key?('rules')
 
         rules = yaml['rules']
@@ -124,6 +156,64 @@ module FiberAudit
               "rules must be a mapping, got #{rules.class}"
       end
 
+      def validate_runtime_structure!(runtime)
+        unless runtime.is_a?(Hash)
+          raise ConfigurationError,
+                "runtime must be a mapping, got #{runtime.class}"
+        end
+        check_unknown_keys(runtime, KNOWN_RUNTIME_KEYS, 'runtime')
+        validate_runtime_mapping!(runtime, 'redaction', KNOWN_REDACTION_KEYS)
+        validate_runtime_mapping!(runtime, 'sampling', KNOWN_SAMPLING_KEYS)
+        validate_runtime_mapping!(runtime, 'overhead', KNOWN_OVERHEAD_KEYS)
+        validate_runtime_mapping!(runtime, 'watchdog', KNOWN_WATCHDOG_KEYS)
+      end
+
+      def validate_runtime_mapping!(runtime, key, allowed)
+        return unless runtime.key?(key)
+
+        value = runtime[key]
+        unless value.is_a?(Hash)
+          raise ConfigurationError,
+                "runtime.#{key} must be a mapping, got #{value.class}"
+        end
+        check_unknown_keys(value, allowed, "runtime.#{key}")
+      end
+
+      def runtime_policy_from(runtime)
+        defaults = Runtime::Policy::DEFAULTS
+        redaction = runtime.fetch('redaction', {})
+        sampling = runtime.fetch('sampling', {})
+        overhead = runtime.fetch('overhead', {})
+        Runtime::Policy.new(
+          redaction: redaction.fetch('mode', defaults[:redaction]),
+          sampling_rate: sampling.fetch('rate', defaults[:sampling_rate]),
+          max_events_per_second: overhead.fetch('max_events_per_second', defaults[:max_events_per_second]),
+          max_events_per_session: overhead.fetch('max_events_per_session', defaults[:max_events_per_session]),
+          max_record_bytes: overhead.fetch('max_record_bytes', defaults[:max_record_bytes]),
+          max_session_bytes: overhead.fetch('max_session_bytes', defaults[:max_session_bytes]),
+          fail_open: runtime.fetch('fail_open', defaults[:fail_open])
+        )
+      rescue RuntimeContractError => e
+        field = e.message.split.first
+        path = RUNTIME_POLICY_PATHS.fetch(field, 'runtime')
+        raise ConfigurationError, "#{path} is invalid: #{e.message}"
+      end
+
+      def runtime_watchdog_policy_from(runtime)
+        values = runtime.fetch('watchdog', {})
+        defaults = Runtime::WatchdogPolicy::DEFAULTS
+        Runtime::WatchdogPolicy.new(
+          enabled: values.fetch('enabled', defaults[:enabled]),
+          heartbeat_interval_ms: values.fetch('heartbeat_interval_ms', defaults[:heartbeat_interval_ms]),
+          stall_threshold_ms: values.fetch('stall_threshold_ms', defaults[:stall_threshold_ms]),
+          max_frames: values.fetch('max_frames', defaults[:max_frames])
+        )
+      rescue RuntimeContractError => e
+        field = e.message.split.first
+        path = field == 'enabled' ? 'runtime.watchdog.enabled' : "runtime.watchdog.#{field}"
+        raise ConfigurationError, "#{path} is invalid: #{e.message}"
+      end
+
       def check_unknown_keys(hash, allowed, path)
         unknown = hash.keys - allowed
         return if unknown.empty?
@@ -139,7 +229,7 @@ module FiberAudit
 
     def validate_types!(
       include_patterns, exclude_patterns, rules,
-      formats, _severity, suppressions
+      formats, _severity, suppressions, runtime_policy, watchdog_policy
     )
       unless include_patterns.is_a?(Array) &&
              include_patterns.all?(String)
@@ -158,6 +248,15 @@ module FiberAudit
       validate_rules!(rules)
       validate_report_formats!(formats)
 
+      unless runtime_policy.is_a?(Runtime::Policy)
+        raise ConfigurationError,
+              'runtime_policy must be a FiberAudit::Runtime::Policy'
+      end
+      unless watchdog_policy.is_a?(Runtime::WatchdogPolicy)
+        raise ConfigurationError,
+              'runtime_watchdog_policy must be a FiberAudit::Runtime::WatchdogPolicy'
+      end
+
       return if suppressions.nil? || suppressions.is_a?(String)
 
       raise ConfigurationError,
@@ -233,4 +332,5 @@ module FiberAudit
             "#{path} is not a valid severity: #{value.inspect}"
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/fiber_audit/errors.rb

@@ -5,4 +5,6 @@ module FiberAudit
   class EmptyEvidenceError < StandardError; end
   class ReporterError < StandardError; end
   class ProjectError < StandardError; end
+  class RuntimeContractError < ArgumentError; end
+  class RuntimeSafetyError < StandardError; end
 end

data/lib/fiber_audit/operation_vocabulary.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  # Canonical operation names shared by static findings and runtime evidence.
+  module OperationVocabulary
+    FA1001_TARGETS = {
+      'Kernel' => %i[system exec spawn].freeze,
+      'Open3' => %i[capture2 capture2e capture3 pipeline].freeze,
+      'IO' => %i[popen].freeze,
+      'Process' => %i[waitall detach].freeze
+    }.freeze
+    FA1001_KERNEL_METHODS = %i[system exec spawn].freeze
+
+    FA1002_METHODS = %i[join value].freeze
+    FA1002_OPERATIONS = %w[Thread.join Thread.value].freeze
+
+    FA1003_TARGETS = {
+      'Mutex' => %i[lock synchronize try_lock].freeze,
+      'ConditionVariable' => %i[wait].freeze,
+      'Monitor' => %i[synchronize].freeze,
+      'MonitorMixin' => %i[synchronize].freeze
+    }.freeze
+
+    FA1004_THREAD_VARIABLE_METHODS = %i[thread_variable_get thread_variable_set].freeze
+    FA1004_INDEX_METHODS = %i[[] []=].freeze
+
+    FA1005_TARGETS = {
+      'IO' => :select,
+      'Kernel' => :select
+    }.freeze
+
+    FA1006_EXACT = %w[
+      TCPSocket TCPServer UDPSocket UNIXSocket UNIXServer Socket IPSocket
+    ].freeze
+
+    FA1007_NET_HTTP_METHODS = %i[get get_response start request].freeze
+    FA1007_URI_METHODS = {
+      'URI' => :open,
+      'OpenURI' => :open_uri
+    }.freeze
+  end
+end

data/lib/fiber_audit/reporters/text.rb

@@ -11,7 +11,7 @@ module FiberAudit
     # Calls Schema.build then Schema.validate! to enforce the contract.
     #
     # Exact contract:
-    # - Header: `FiberAudit 0.1.0 — static analysis`
+    # - Header: `FiberAudit <version> — static analysis`
     # - Summary counts, suppressed, status
     # - Disclaimer under status
     # - Findings: RULE  SEVERITY  path:line

data/lib/fiber_audit/runtime/active_operations.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative 'event'
+require_relative 'location'
+require_relative 'validation'
+
+module FiberAudit
+  module Runtime
+    # Bounded process-local registry shared by the watchdog and future probes.
+    class ActiveOperations
+      MAX_ENTRIES = 10_000
+      MAX_SNAPSHOT = 100
+
+      Handle = Data.define(:pid, :thread_id, :fiber_id, :sequence)
+      Entry = Data.define(
+        :thread_id,
+        :fiber_id,
+        :sequence,
+        :operation,
+        :location,
+        :execution_context,
+        :started_monotonic_ns
+      )
+
+      def initialize(pid_source: Process.method(:pid), capacity: MAX_ENTRIES, snapshot_limit: MAX_SNAPSHOT)
+        validate_source!(pid_source)
+        validate_limit!(capacity, 'capacity', MAX_ENTRIES)
+        validate_limit!(snapshot_limit, 'snapshot_limit', MAX_SNAPSHOT)
+        @pid_source = pid_source
+        @capacity = capacity
+        @snapshot_limit = snapshot_limit
+        reset_for_process!(current_pid)
+      end
+
+      def register(
+        operation:,
+        monotonic_ns:,
+        location: nil,
+        execution_context: :unknown,
+        thread: Thread.current,
+        fiber: Fiber.current
+      )
+        ensure_current_process!
+        values = normalize_entry(
+          operation: operation,
+          location: location,
+          execution_context: execution_context,
+          monotonic_ns: monotonic_ns,
+          thread: thread,
+          fiber: fiber
+        )
+
+        @mutex.synchronize do
+          return if @entries.size >= @capacity
+
+          @sequence += 1
+          entry = Entry.new(sequence: @sequence, **values)
+          handle = Handle.new(
+            pid: @owner_pid,
+            thread_id: entry.thread_id,
+            fiber_id: entry.fiber_id,
+            sequence: entry.sequence
+          )
+          @entries[handle] = entry
+          handle
+        end
+      end
+
+      def finish(handle)
+        ensure_current_process!
+        return unless handle.is_a?(Handle) && handle.pid == @owner_pid
+
+        @mutex.synchronize { @entries.delete(handle) }
+      end
+
+      def snapshot(thread_id: nil)
+        ensure_current_process!
+        normalized_thread_id = Validation.integer(thread_id, 'thread_id', allow_nil: true)
+        @mutex.synchronize do
+          entries = @entries.values
+          entries = entries.select { |entry| entry.thread_id == normalized_thread_id } if normalized_thread_id
+          entries.sort_by(&:sequence).first(@snapshot_limit).freeze
+        end
+      end
+
+      def size
+        ensure_current_process!
+        @mutex.synchronize { @entries.size }
+      end
+
+      private
+
+      def normalize_entry(operation:, location:, execution_context:, monotonic_ns:, thread:, fiber:)
+        canonical_operation = Validation.operation(operation)
+        unless location.nil? || location.is_a?(Location)
+          raise RuntimeContractError, 'location must be a FiberAudit::Runtime::Location or nil'
+        end
+
+        normalized_context = execution_context.to_sym if execution_context.is_a?(String) || execution_context.is_a?(Symbol)
+        raise RuntimeContractError, 'execution_context is invalid' unless Context::ALL.include?(normalized_context)
+
+        unless thread.respond_to?(:object_id) && fiber.respond_to?(:object_id)
+          raise RuntimeContractError, 'thread and fiber identities are invalid'
+        end
+
+        {
+          thread_id: Validation.integer(thread.object_id, 'thread_id'),
+          fiber_id: Validation.integer(fiber.object_id, 'fiber_id'),
+          operation: canonical_operation,
+          location: location,
+          execution_context: normalized_context,
+          started_monotonic_ns: Validation.integer(monotonic_ns, 'monotonic_ns')
+        }
+      end
+
+      def ensure_current_process!
+        pid = current_pid
+        reset_for_process!(pid) unless pid == @owner_pid
+      end
+
+      def reset_for_process!(pid)
+        @owner_pid = pid
+        @mutex = Mutex.new
+        @entries = {}
+        @sequence = 0
+      end
+
+      def current_pid
+        value = @pid_source.call
+        return value if value.is_a?(Integer) && value.positive?
+
+        raise RuntimeContractError, 'pid source must return a positive Integer'
+      end
+
+      def validate_source!(source)
+        raise RuntimeContractError, 'pid_source must respond to call' unless source.respond_to?(:call)
+      end
+
+      def validate_limit!(value, name, maximum)
+        return if value.is_a?(Integer) && value.between?(1, maximum)
+
+        raise RuntimeContractError, "#{name} must be an Integer in 1..#{maximum}"
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/boot.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'English'
+require_relative 'environment'
+require_relative 'lifecycle'
+
+module FiberAudit
+  module Runtime
+    module Boot
+      class << self
+        def activate_from_environment!(
+          environment: ENV,
+          clock: Clock.new,
+          session_id_source: SecureRandom.method(:uuid),
+          pid_source: Process.method(:pid),
+          writer_factory: JSONL::Writer.method(:open),
+          random: Sampler::RANDOM_SOURCE
+        )
+          return current if activated_for_current_process?
+
+          mode = Environment.failure_mode(environment)
+          return unless Environment.activated?(environment)
+
+          settings = Environment.load(environment)
+          watchdog_policy = if environment.key?(Environment::WATCHDOG_SETTINGS_KEY)
+                              Environment.load_watchdog_policy(environment)
+                            end
+          @lifecycle = Lifecycle.start(
+            settings: settings,
+            watchdog_policy: watchdog_policy,
+            probes_enabled: Environment.probes_enabled?(environment),
+            clock: clock,
+            session_id_source: session_id_source,
+            pid_source: pid_source,
+            writer_factory: writer_factory,
+            random: random
+          )
+          @pid_source = pid_source
+          @activation_pid = pid_source.call
+          install_shutdown_hook!
+          @lifecycle
+        rescue StandardError
+          raise if defined?(mode) && mode == :closed
+
+          nil
+        end
+
+        def current
+          return unless @lifecycle
+
+          @lifecycle.ensure_current_process!
+          @activation_pid = @pid_source.call
+          @lifecycle
+        end
+
+        def activated?
+          !current.nil?
+        end
+
+        def shutdown(exception: nil)
+          current&.shutdown(exception: exception)
+        end
+
+        private
+
+        def activated_for_current_process?
+          return false unless @lifecycle && @pid_source && @activation_pid
+
+          @activation_pid == @pid_source.call
+        end
+
+        def install_shutdown_hook!
+          return if @shutdown_hook_installed
+
+          at_exit { FiberAudit::Runtime::Boot.shutdown(exception: $ERROR_INFO) }
+          @shutdown_hook_installed = true
+        end
+      end
+    end
+  end
+end
+
+FiberAudit::Runtime::Boot.activate_from_environment! if ENV.key?(FiberAudit::Runtime::Environment::ACTIVATION_KEY)

data/lib/fiber_audit/runtime/clock.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'validation'
+
+module FiberAudit
+  module Runtime
+    class Clock
+      MAX_NANOSECONDS = 9_223_372_036_854_775_807
+      WALL_SOURCE = -> { Time.now }.freeze
+      MONOTONIC_SOURCE = lambda {
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+      }.freeze
+
+      def initialize(wall: WALL_SOURCE, monotonic: MONOTONIC_SOURCE)
+        raise RuntimeContractError, 'wall clock source must respond to call' unless wall.respond_to?(:call)
+        raise RuntimeContractError, 'monotonic clock source must respond to call' unless monotonic.respond_to?(:call)
+
+        @wall = wall
+        @monotonic = monotonic
+        freeze
+      end
+
+      def wall_time
+        Validation.utc_time(@wall.call, 'wall clock result')
+      end
+
+      def monotonic_ns
+        value = Validation.integer(@monotonic.call, 'monotonic clock result')
+        raise RuntimeSafetyError, 'monotonic clock result exceeds signed 64-bit range' if value > MAX_NANOSECONDS
+
+        value
+      end
+    end
+  end
+end