fiber_audit 0.1.0

data/lib/fiber_audit/static/rules/io_select.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../../findings/evidence'
+require_relative '../../correlation/fingerprint'
+require_relative '../../findings/finding'
+
+module FiberAudit
+  module Static
+    module Rules
+      # FA1005: Detects explicit IO.select calls that may bypass
+      # scheduler-aware I/O and block the scheduler thread.
+      class IOSelect < Base
+        id 'FA1005'
+        severity :medium
+        default_confidence :high
+        description 'Explicit IO.select call that may bypass scheduler-aware I/O'
+
+        TITLE    = 'Explicit IO.select call'
+        CATEGORY = :blocking_io
+
+        MESSAGE = 'IO.select may bypass scheduler-aware I/O and block the thread running the fiber scheduler.'
+        REMEDIATION = 'Use scheduler-aware I/O APIs or allow the active Fiber scheduler to manage readiness.'
+
+        TARGETS = {
+          'IO' => :select,
+          'Kernel' => :select
+        }.freeze
+
+        class << self
+          def title = TITLE
+          def category = CATEGORY
+        end
+
+        def analyze(call_sites:)
+          call_sites.filter_map { |site| match(site) }
+        end
+
+        private
+
+        def match(site)
+          return unless site.method_name == :select
+
+          receiver = site.receiver_constant
+
+          if receiver.nil? && site.receiver_source.nil?
+            # Bare select() call — treat as Kernel.select with unknown confidence
+            return build_finding(site, 'Kernel', :unknown)
+          end
+
+          canonical = TARGETS[receiver]
+          return unless canonical == :select
+          return if shadowed?(receiver, site.nesting)
+
+          build_finding(site, receiver, site.confidence)
+        end
+
+        def shadowed?(constant_name, nesting)
+          sem = semantic_index
+          return false unless sem
+
+          !sem.resolve_constant(constant_name, nesting: nesting || []).nil?
+        rescue StandardError
+          false
+        end
+
+        def semantic_index
+          index = workspace.semantic_index if workspace.respond_to?(:semantic_index)
+          return index if index
+
+          workspace if workspace.respond_to?(:resolve_constant)
+        rescue StandardError
+          nil
+        end
+
+        def build_finding(site, constant, confidence)
+          operation = "#{constant}.select"
+          context = site.execution_context || :unknown
+
+          Finding.new(
+            rule_id: self.class.id,
+            title: TITLE,
+            category: CATEGORY,
+            severity: severity_for(:medium, context),
+            confidence: confidence,
+            location: site.location,
+            symbol: site.enclosing_symbol,
+            operation: operation,
+            execution_context: context,
+            message: MESSAGE,
+            evidence: [
+              Evidence.new(
+                source: 'static_analysis',
+                message: "Explicit IO.select: #{operation}",
+                details: { receiver: constant, method: :select }
+              )
+            ],
+            remediation: REMEDIATION
+          )
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/static/rules/net_http_in_request.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../../findings/evidence'
+require_relative '../../correlation/fingerprint'
+require_relative '../../findings/finding'
+
+module FiberAudit
+  module Static
+    module Rules
+      # FA1007: Detects blocking HTTP calls in request-like contexts.
+      # Targets Net::HTTP.{get,get_response,start,request}, URI.open, OpenURI.open_uri.
+      # Excludes Net::HTTP.get_print. Emits only for request/middleware/websocket/callback.
+      class NetHTTPInRequest < Base
+        id 'FA1007'
+        severity :high
+        default_confidence :high
+        description 'Blocking HTTP call in request path'
+
+        TITLE = 'Blocking HTTP call in request path'
+        CATEGORY = :network
+        MESSAGE = 'Synchronous HTTP activity in a request-like context may block the thread running the fiber scheduler.'
+        REMEDIATION = 'Use a scheduler-aware HTTP client, or move outbound HTTP work outside the request path.'
+
+        NET_HTTP_METHODS = %i[get get_response start request].freeze
+        URI_METHODS = {
+          'URI' => :open,
+          'OpenURI' => :open_uri
+        }.freeze
+        EMIT_CONTEXTS = %i[request middleware websocket callback].freeze
+
+        def analyze(call_sites:)
+          call_sites.filter_map { |site| analyze_call_site(site) }
+        rescue StandardError
+          []
+        end
+
+        private
+
+        def analyze_call_site(site)
+          return unless eligible_context?(site) && (match = match_call_site(site))
+
+          build_finding(site, match)
+        end
+
+        def eligible_context?(site)
+          EMIT_CONTEXTS.include?(site.execution_context)
+        end
+
+        def match_call_site(site)
+          receiver = site.receiver_constant
+          method = site.method_name
+          return unless receiver && method
+
+          if receiver == 'Net::HTTP' && NET_HTTP_METHODS.include?(method)
+            return if shadowed?(receiver, site.nesting)
+
+            { type: :net_http, operation: "Net::HTTP.#{method}" }
+          elsif URI_METHODS[receiver] == method
+            return if shadowed?(receiver, site.nesting) || non_http_literal?(site.arguments&.first)
+
+            { type: :uri, operation: "#{receiver}.#{method}" }
+          end
+        end
+
+        def shadowed?(const_name, nesting)
+          index = workspace.semantic_index if workspace.respond_to?(:semantic_index)
+          index ||= workspace if workspace.respond_to?(:resolve_constant)
+          return false unless index.respond_to?(:resolve_constant)
+
+          !index.resolve_constant(const_name, nesting: nesting || []).nil?
+        rescue StandardError
+          false
+        end
+
+        def non_http_literal?(argument)
+          match = argument&.match(/\A(["'])(.*)\1\z/m)
+          return false unless match
+
+          scheme = match[2][/\A([a-z][a-z0-9+.-]*):/i, 1]
+          scheme && !%w[http https].include?(scheme.downcase)
+        end
+
+        def build_finding(site, match)
+          context = site.execution_context
+          sev, conf = if match[:type] == :net_http
+                        [severity_for(:high, context), site.confidence]
+                      else
+                        %i[medium low]
+                      end
+
+          FiberAudit::Finding.new(
+            rule_id: self.class.id,
+            title: TITLE,
+            category: CATEGORY,
+            severity: sev,
+            confidence: conf,
+            location: site.location,
+            symbol: site.enclosing_symbol,
+            operation: match[:operation],
+            execution_context: context,
+            message: MESSAGE,
+            evidence: [
+              FiberAudit::Evidence.new(
+                source: 'static_analysis',
+                message: "Blocking HTTP call detected: #{match[:operation]}",
+                details: { receiver: site.receiver_constant, method: site.method_name, context: context }
+              )
+            ],
+            remediation: REMEDIATION
+          )
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/static/rules/registry.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module FiberAudit
+  module Static
+    module Rules
+      # Registry for managing rule classes.
+      #
+      # The registry holds rule classes (not instances) and can instantiate them
+      # with the appropriate dependencies for a given configuration.
+      #
+      # Usage:
+      #   registry = Registry.new(workspace: ws, context_resolver: resolver)
+      #   registry.register(BlockingSubprocess)
+      #   registry.register(ThreadJoin)
+      #
+      #   # Find a rule class by ID
+      #   rule_class = registry['FA1001']
+      #
+      #   # Get all enabled rule instances for a configuration
+      #   instances = registry.enabled_for(configuration)
+      #   instances.each do |rule|
+      #     findings = rule.analyze(call_sites: call_sites)
+      #   end
+      #
+      class Registry
+        include Enumerable
+
+        # @param workspace [Object, nil] the analysis workspace
+        # @param context_resolver [Object, nil] resolves execution contexts
+        def initialize(workspace: nil, context_resolver: nil)
+          @workspace = workspace
+          @context_resolver = context_resolver
+          @rules = []
+        end
+
+        # Register a rule class.
+        #
+        # @param rule_class [Class] must be a subclass of Base with an id set
+        # @return [self] for chaining
+        # @raise [ArgumentError] if rule_class is not a Base subclass, has no id, or id is duplicate
+        def register(rule_class)
+          validate_rule_class!(rule_class)
+
+          rule_id = rule_class.id
+          if @rules.any? { |r| r.id == rule_id }
+            raise ArgumentError,
+                  "Rule with id '#{rule_id}' is already registered"
+          end
+
+          @rules << rule_class
+          self
+        end
+
+        # Find a rule class by ID (string or symbol).
+        #
+        # @param id [String, Symbol] the rule identifier
+        # @return [Class, nil] the rule class, or nil if not found
+        def [](id)
+          id_str = id.to_s
+          @rules.find { |r| r.id == id_str }
+        end
+
+        # Alias for []
+        alias find []
+
+        # Return all registered rule classes in insertion order.
+        #
+        # @return [Array<Class>] array of rule classes
+        def list
+          @rules.dup
+        end
+
+        # Iterate over registered rule classes.
+        #
+        # @yieldparam rule_class [Class] each registered rule class
+        # @return [Enumerator] if no block given
+        def each(&)
+          @rules.each(&)
+        end
+
+        # Instantiate all enabled rules for the given configuration.
+        #
+        # Filters rules by configuration.rule_enabled?(id) and returns instances
+        # initialized with the registry's workspace, context_resolver, and the
+        # provided configuration.
+        #
+        # @param configuration [FiberAudit::Configuration] audit configuration
+        # @return [Array<Base>] array of instantiated rule objects
+        def enabled_for(configuration)
+          @rules.filter_map do |rule_class|
+            next unless configuration.rule_enabled?(rule_class.id)
+
+            rule_class.new(
+              workspace: @workspace,
+              context_resolver: @context_resolver,
+              configuration: configuration
+            )
+          end
+        end
+
+        private
+
+        # Validate that a rule class meets the requirements for registration.
+        #
+        # @param rule_class [Class] the class to validate
+        # @raise [ArgumentError] if validation fails
+        def validate_rule_class!(rule_class)
+          unless rule_class.is_a?(Class) && rule_class < Base
+            raise ArgumentError,
+                  "rule_class must be a subclass of Base, got #{rule_class.inspect}"
+          end
+
+          return unless rule_class.id.nil? || rule_class.id.empty?
+
+          raise ArgumentError,
+                'rule_class must have an id set via the DSL'
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/static/rules/synchronization.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../../findings/evidence'
+require_relative '../../correlation/fingerprint'
+require_relative '../../findings/finding'
+
+module FiberAudit
+  module Static
+    module Rules
+      class Synchronization < Base
+        id 'FA1003'
+        severity :medium
+        default_confidence :high
+        description 'Thread synchronization primitives that may block the fiber scheduler thread'
+
+        RULE_TITLE = 'Thread synchronization'
+        RULE_CATEGORY = :synchronization
+        TARGETS = {
+          'Mutex' => %i[lock synchronize try_lock],
+          'ConditionVariable' => %i[wait],
+          'Monitor' => %i[synchronize],
+          'MonitorMixin' => %i[synchronize]
+        }.freeze
+        TRY_LOCK_MSG = 'Mutex.try_lock is non-blocking but may indicate ' \
+                       'thread-oriented synchronization in fiber-scheduled code.'
+        NORMAL_MSG = 'Synchronization operation may block the thread running the fiber scheduler.'
+        REMEDIATION = 'Use scheduler-aware synchronization primitives, or verify ' \
+                      'contention and scheduler behaviour under load.'
+
+        def analyze(call_sites:)
+          explicit_monitor_mixins = explicit_monitor_mixin_classes(call_sites)
+          call_sites.filter_map { |site| check(site, explicit_monitor_mixins) }
+        rescue StandardError
+          []
+        end
+
+        private
+
+        def check(site, explicit_monitor_mixins)
+          if site.receiver_source.nil? && site.receiver_constant.nil? && site.method_name == :synchronize
+            klass = extract_class_name(site.enclosing_symbol)
+            semantic_match = klass && monitor_mixin_ancestor?(klass)
+            return unless semantic_match || explicit_monitor_mixins.include?(klass)
+            return if workspace_shadow?('MonitorMixin', site.nesting)
+
+            return build_finding(site, 'MonitorMixin', :synchronize)
+          end
+
+          target = site.receiver_constant
+          return unless target && TARGETS.fetch(target, []).include?(site.method_name)
+          return if workspace_shadow?(target, site.nesting) || site.receiver_source == target
+
+          build_finding(site, target, site.method_name)
+        rescue StandardError
+          nil
+        end
+
+        def workspace_shadow?(target, nesting)
+          index = workspace_index
+          return false unless index.respond_to?(:resolve_constant)
+
+          !index.resolve_constant(target, nesting: nesting || []).nil?
+        rescue StandardError
+          false
+        end
+
+        def workspace_index
+          index = workspace.semantic_index if workspace.respond_to?(:semantic_index)
+          index || (workspace if workspace.respond_to?(:resolve_constant))
+        rescue StandardError
+          nil
+        end
+
+        def extract_class_name(symbol)
+          return unless symbol
+
+          separator = symbol.include?('#') ? '#' : '.'
+          symbol.split(separator, 2).first if symbol.include?(separator)
+        end
+
+        def monitor_mixin_ancestor?(class_name)
+          adapters = [workspace]
+          adapters << workspace.semantic_index if workspace.respond_to?(:semantic_index)
+          adapters.compact.uniq.any? do |adapter|
+            adapter.respond_to?(:ancestors_of) &&
+              Array(adapter.ancestors_of(class_name)).include?('MonitorMixin')
+          rescue StandardError
+            false
+          end
+        end
+
+        def explicit_monitor_mixin_classes(call_sites)
+          call_sites.filter_map do |site|
+            next unless site.receiver_source.nil? && site.method_name == :include
+            next unless Array(site.arguments).any? { |argument| argument.to_s.delete_prefix('::') == 'MonitorMixin' }
+
+            Array(site.nesting).last
+          end.uniq
+        end
+
+        def build_finding(site, target, method)
+          try_lock = target == 'Mutex' && method == :try_lock
+          operation = "#{target}##{method}"
+          severity = try_lock ? :info : severity_for(:medium, site.execution_context)
+          confidence = try_lock ? :high : site.confidence
+          message = try_lock ? TRY_LOCK_MSG : NORMAL_MSG
+          evidence = Evidence.new(source: operation, message: message,
+                                  details: { receiver: site.receiver_source, method: method.to_s, constant: target })
+
+          Finding.new(
+            rule_id: self.class.id, title: RULE_TITLE, category: RULE_CATEGORY,
+            severity: severity, confidence: confidence, location: site.location,
+            symbol: site.enclosing_symbol, operation: operation,
+            execution_context: site.execution_context, message: message,
+            evidence: [evidence], remediation: REMEDIATION
+          )
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/static/rules/thread_current_state.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../../findings/evidence'
+require_relative '../../correlation/fingerprint'
+require_relative '../../findings/finding'
+
+module FiberAudit
+  module Static
+    module Rules
+      # Detect thread-variable and Thread.current index state.
+      class ThreadCurrentState < Base
+        id 'FA1004'
+        severity :high
+        confidence :high
+        description 'Thread-local state in fiber code may be shared across fibers and leak request-local data'
+
+        TITLE = 'Thread-local state in fiber code'
+        CATEGORY = :thread_local
+        MESSAGE = 'Thread-local state may be shared across fibers and leak request-local data.'
+        REMEDIATION = 'Use fiber-local or framework-provided request-local state instead of Thread thread variables.'
+
+        THREAD_VARIABLE_METHODS = %i[thread_variable_get thread_variable_set].freeze
+        INDEX_METHODS = %i[[] []=].freeze
+
+        def analyze(call_sites:)
+          findings = []
+          call_sites.each do |site|
+            next if skip?(site)
+
+            finding = match_thread_variable(site) || match_index_op(site)
+            findings << finding if finding
+          end
+          findings
+        rescue StandardError
+          []
+        end
+
+        private
+
+        def skip?(site)
+          defer_current_attributes?(site) ||
+            direct_thread_class?(site) ||
+            workspace_thread_shadowed?(site)
+        end
+
+        def defer_current_attributes?(site)
+          site.receiver_source.to_s.include?('CurrentAttributes')
+        end
+
+        def direct_thread_class?(site)
+          site.receiver_source == 'Thread'
+        end
+
+        def workspace_thread_shadowed?(site)
+          index = workspace.semantic_index if workspace.respond_to?(:semantic_index)
+          index ||= workspace if workspace.respond_to?(:resolve_constant)
+          return false unless index.respond_to?(:resolve_constant)
+
+          !index.resolve_constant('Thread', nesting: site.nesting || []).nil?
+        rescue StandardError
+          false
+        end
+
+        def match_thread_variable(site)
+          return unless THREAD_VARIABLE_METHODS.include?(site.method_name)
+
+          instance_match = site.receiver_constant == 'Thread' && site.receiver_source != 'Thread'
+          current_match = site.receiver_source == 'Thread.current'
+
+          return unless instance_match || current_match
+
+          build_finding(site, :high, :high, operation(site))
+        end
+
+        def match_index_op(site)
+          return unless INDEX_METHODS.include?(site.method_name)
+          return unless site.receiver_source == 'Thread.current'
+
+          build_finding(site, :medium, :high, operation(site))
+        end
+
+        def operation(site)
+          if INDEX_METHODS.include?(site.method_name)
+            "Thread.current.#{site.method_name}"
+          else
+            "Thread.#{site.method_name}"
+          end
+        end
+
+        def build_finding(site, default_sev, conf, operation)
+          context = site.execution_context
+          severity = severity_for(default_sev, context)
+
+          Finding.new(
+            rule_id: self.class.id,
+            title: TITLE,
+            category: CATEGORY,
+            severity: severity,
+            confidence: conf,
+            location: site.location,
+            symbol: site.enclosing_symbol,
+            operation: operation,
+            execution_context: context,
+            message: MESSAGE,
+            evidence: [Evidence.new(source: site.receiver_source, message: "Thread-local access via #{site.method_name}")],
+            remediation: REMEDIATION
+          )
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/static/rules/thread_join.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../../findings/evidence'
+require_relative '../../correlation/fingerprint'
+require_relative '../../findings/finding'
+
+module FiberAudit
+  module Static
+    module Rules
+      # FA1002: Thread#join / Thread#value may block the fiber-scheduler thread.
+      #
+      # Matches join/value on Thread instances whose receiver_constant is
+      # 'Thread' but whose receiver_source is not the bare literal 'Thread'.
+      # Covers direct constructor chains (Thread.new.join), assigned receivers
+      # (t = Thread.new; t.join), and the exact syntactic Thread.current form.
+      #
+      # Skips direct Thread.join/value, arbitrary worker.join, wrong methods,
+      # and workspace-shadowed Thread (checked via workspace or
+      # workspace.semantic_index resolve_constant seam). Adapter errors from
+      # those seams are swallowed — they never raise.
+      class ThreadJoin < Base
+        id 'FA1002'
+        severity :high
+        confidence :high
+        description 'Waiting for a thread may block the thread running the fiber scheduler.'
+
+        TITLE    = 'Thread wait'
+        CATEGORY = :synchronization
+        MESSAGE  = 'Waiting for a thread may block the thread running the fiber scheduler.'
+        REMEDIATION = 'Replace thread waits with scheduler-aware coordination, ' \
+                      'or move the work outside the fiber-scheduled path.'
+        TARGET_METHODS  = %i[join value].freeze
+        CANONICAL_OPS   = %w[Thread.join Thread.value].freeze
+        DIRECT_CLASS_SOURCE = 'Thread'
+
+        def analyze(call_sites:)
+          call_sites.filter_map { |site| match(site) }
+        end
+
+        private
+
+        def match(site)
+          return unless TARGET_METHODS.include?(site.method_name)
+          return unless thread_instance?(site)
+          return if shadowed_thread?(site)
+
+          build_finding(site)
+        end
+
+        # Receiver must resolve to Thread but not be the bare literal.
+        def thread_instance?(site)
+          return true if site.receiver_source == 'Thread.current'
+
+          site.receiver_constant == 'Thread' && site.receiver_source != DIRECT_CLASS_SOURCE
+        rescue StandardError
+          false
+        end
+
+        # Check workspace / semantic_index resolve_constant seam.
+        # Adapter errors are swallowed.
+        def shadowed_thread?(site)
+          index = workspace.semantic_index if workspace.respond_to?(:semantic_index)
+          index ||= workspace if workspace.respond_to?(:resolve_constant)
+          return false unless index.respond_to?(:resolve_constant)
+
+          !index.resolve_constant('Thread', nesting: site.nesting || []).nil?
+        rescue StandardError
+          false
+        end
+
+        def build_finding(site)
+          loc  = site.location
+          op   = "Thread.#{site.method_name}"
+          sev  = severity_for(self.class.severity, site.execution_context)
+          conf = site.receiver_source == 'Thread.current' ? :high : site.confidence
+
+          Finding.new(
+            rule_id: self.class.id, title: TITLE, category: CATEGORY,
+            severity: sev, confidence: conf, location: loc,
+            symbol: site.enclosing_symbol, operation: op,
+            execution_context: site.execution_context,
+            message: MESSAGE,
+            evidence: [Evidence.new(
+              source: 'static_analysis',
+              message: "#{op} on #{site.receiver_source}",
+              details: { operation: op, receiver: site.receiver_source,
+                         canonical_operations: CANONICAL_OPS }
+            )],
+            remediation: REMEDIATION
+          )
+        end
+      end
+    end
+  end
+end