fiber_audit 0.1.0

data/lib/fiber_audit/static/execution_context_resolver.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require_relative '../execution_context'
+
+module FiberAudit
+  module Static
+    # Resolves execution context for call sites based on semantic ancestry,
+    # path heuristics, and callback DSL patterns.
+    #
+    # Resolution priority:
+    # 1. Semantic inheritance (outranks path)
+    # 2. Path-based fallback
+    # 3. Callback DSL sniff
+    # 4. :unknown
+    #
+    # Never raises; always returns a Context symbol.
+    class ExecutionContextResolver
+      # Semantic ancestry signals mapped to contexts
+      SEMANTIC_SIGNALS = {
+        'ActionController::Base' => Context::REQUEST,
+        'ActionController::API' => Context::REQUEST,
+        'ActionJob::Base' => Context::JOB, # typo tolerance
+        'ActiveJob::Base' => Context::JOB,
+        'ActionCable::Channel::Base' => Context::WEBSOCKET,
+        'ActionView::Base' => Context::VIEW
+      }.freeze
+
+      # Callback model ancestors (ActiveRecord/model ancestry only)
+      CALLBACK_ANCESTORS = %w[
+        ActiveRecord::Base
+      ].freeze
+
+      # @param workspace [Object] responds to ancestors_of(name) OR exposes semantic_index
+      def initialize(workspace:)
+        @workspace = workspace
+        @ancestor_cache = {}
+      end
+
+      # Resolve context for a single call site
+      # @param call_site [CallSite] a call site with path, enclosing_symbol, nesting
+      # @return [Symbol] one of Context::ALL
+      def resolve(call_site:)
+        path = call_site.path
+        enclosing = call_site.enclosing_symbol
+        nesting = Array(call_site.nesting)
+
+        # Try semantic inheritance first (outranks path)
+        semantic = resolve_from_semantics(enclosing, nesting)
+        return semantic if semantic
+
+        # Path-based fallback
+        path_ctx = resolve_from_path(path, enclosing)
+        return path_ctx if path_ctx
+
+        # Callback DSL sniff
+        callback_ctx = resolve_callback(enclosing, nesting)
+        return callback_ctx if callback_ctx
+
+        Context::UNKNOWN
+      rescue StandardError
+        Context::UNKNOWN
+      end
+
+      # Resolve contexts for all call sites, returning new CallSite objects
+      # with execution_context populated. Does not mutate originals.
+      #
+      # @param call_sites [Array<CallSite>]
+      # @return [Array<CallSite>] new array in original order
+      # Never silently returns an unchanged object when copying fails—
+      # unknown is still populated where compatible.
+      def resolve_all(call_sites:)
+        Array(call_sites).map do |cs|
+          ctx = resolve(call_site: cs)
+          copy_with_context(cs, ctx)
+        end
+      rescue StandardError
+        # If batch fails, try individually with :unknown.
+        # If copy itself fails (not a Data type), let it propagate—
+        # never silently return an unchanged object.
+        Array(call_sites).map do |cs|
+          copy_with_context(cs, Context::UNKNOWN)
+        end
+      end
+
+      private
+
+      # Extract enclosing class name from enclosing_symbol
+      # "ClassName#method" or "ClassName.method" → "ClassName"
+      # "Namespace::Class#method" → "Namespace::Class"
+      def extract_class(enclosing_symbol)
+        return nil if enclosing_symbol.nil? || enclosing_symbol.empty?
+
+        # Split on # or . and take the class part
+        if enclosing_symbol.include?('#')
+          enclosing_symbol.split('#', 2).first
+        elsif enclosing_symbol.include?('.')
+          enclosing_symbol.split('.', 2).first
+        end
+      end
+
+      # Extract method name from enclosing_symbol
+      # "ClassName#method" → "method"
+      # "ClassName.method" → "method"
+      def extract_method(enclosing_symbol)
+        return nil if enclosing_symbol.nil? || enclosing_symbol.empty?
+
+        if enclosing_symbol.include?('#')
+          enclosing_symbol.split('#', 2).last
+        elsif enclosing_symbol.include?('.')
+          enclosing_symbol.split('.', 2).last
+        end
+      end
+
+      # Try to resolve from semantic ancestry with transitive traversal
+      def resolve_from_semantics(enclosing_symbol, nesting)
+        # Try enclosing class first
+        klass = extract_class(enclosing_symbol)
+        if klass
+          result = check_semantic_ancestors_transitive(klass)
+          return result if result
+        end
+
+        # Try nesting (innermost first)
+        nesting.reverse_each do |name|
+          result = check_semantic_ancestors_transitive(name)
+          return result if result
+        end
+
+        nil
+      end
+
+      # Check class name and its transitive ancestors with cycle detection
+      # @param class_name [String] the class name to check
+      # @param visited [Hash] names already visited during cycle detection
+      # @return [Symbol, nil] the context if found, nil otherwise
+      def check_semantic_ancestors_transitive(class_name, visited = {})
+        return nil unless class_name
+        return nil if visited.key?(class_name)
+
+        visited[class_name] = true
+
+        # Match the class itself first (known class signal, even if ancestors empty)
+        signal = SEMANTIC_SIGNALS[class_name]
+        return signal if signal
+
+        # Get ancestors
+        ancestors = safe_ancestors_of(class_name)
+        return nil if ancestors.empty?
+
+        # Check each ancestor and recurse transitively
+        ancestors.each do |ancestor_name|
+          # Check if this ancestor is a known signal
+          ancestor_signal = SEMANTIC_SIGNALS[ancestor_name]
+          return ancestor_signal if ancestor_signal
+
+          # Recurse transitively with cycle detection
+          result = check_semantic_ancestors_transitive(ancestor_name, visited)
+          return result if result
+        end
+
+        nil
+      end
+
+      # Resolve from path segments with contiguous boundary-safe sequences
+      def resolve_from_path(path, enclosing_symbol)
+        return nil unless path
+
+        # Normalize Windows backslashes to forward slashes
+        normalized = path.tr('\\', '/')
+        segments = normalized.split('/')
+
+        # Contiguous boundary-safe sequences
+        # config/initializers → boot
+        return Context::BOOT if contiguous_pair?(segments, 'config', 'initializers')
+
+        # lib/tasks → rake_task
+        return Context::RAKE_TASK if contiguous_pair?(segments, 'lib', 'tasks')
+
+        # basename Rakefile → rake_task
+        return Context::RAKE_TASK if File.basename(normalized) == 'Rakefile'
+
+        # app/views → view
+        return Context::VIEW if contiguous_pair?(segments, 'app', 'views')
+
+        # spec or test segment → test (exact segment match, not substring)
+        return Context::TEST if segments.include?('spec') || segments.include?('test')
+
+        # config.ru requires enclosing instance #call specifically
+        # Must be instance method (#call), not class method (.call)
+        # Must be exactly 'call', not a substring like 'callback'
+        if File.basename(normalized) == 'config.ru'
+          method = extract_method(enclosing_symbol)
+          return Context::MIDDLEWARE if enclosing_symbol&.include?('#') && method == 'call'
+        end
+
+        nil
+      end
+
+      # Check if two segments appear contiguously in the path
+      # @param segments [Array<String>] path segments
+      # @param first [String] first segment
+      # @param second [String] second segment
+      # @return [Boolean] true when first is immediately followed by second
+      def contiguous_pair?(segments, first, second)
+        segments.each_cons(2).any? do |left, right|
+          left == first && right == second
+        end
+      end
+
+      # Resolve callback DSL
+      def resolve_callback(enclosing_symbol, nesting)
+        method = extract_method(enclosing_symbol)
+        return nil unless method
+
+        # Method starts with before_/after_/around_
+        return nil unless method.start_with?('before_', 'after_', 'around_')
+
+        # Check if any enclosing class has ActiveRecord/model ancestry
+        klass = extract_class(enclosing_symbol)
+        candidate_classes = [klass, *nesting].compact
+
+        candidate_classes.each do |name|
+          ancestors = safe_ancestors_of(name)
+          return Context::CALLBACK if ancestors.any? { |a| CALLBACK_ANCESTORS.include?(a) }
+        end
+
+        nil
+      end
+
+      # Get ancestors from workspace safely, never raises
+      # Tries workspace.ancestors_of or workspace.semantic_index.ancestors_of
+      def safe_ancestors_of(name)
+        return [] unless name
+        return @ancestor_cache[name] if @ancestor_cache.key?(name)
+
+        ancestors = if @workspace.respond_to?(:ancestors_of)
+                      @workspace.ancestors_of(name)
+                    elsif @workspace.respond_to?(:semantic_index) &&
+                          @workspace.semantic_index.respond_to?(:ancestors_of)
+                      @workspace.semantic_index.ancestors_of(name)
+                    else
+                      []
+                    end
+        @ancestor_cache[name] = Array(ancestors).dup.freeze
+      rescue StandardError
+        @ancestor_cache[name] = [].freeze
+      end
+
+      # Create a new CallSite with execution_context populated
+      # Does not mutate the original
+      # Never silently returns the unchanged object
+      def copy_with_context(call_site, context)
+        klass = call_site.class
+        unless klass.respond_to?(:members)
+          # Cannot copy immutably - raise instead of silently returning unchanged
+          raise TypeError, "Cannot immutably copy #{klass}: not a Data type"
+        end
+
+        attrs = {}
+        klass.members.each { |m| attrs[m] = call_site.send(m) }
+        attrs[:execution_context] = context
+        klass.new(**attrs)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require_relative '../../findings/severity'
+require_relative '../../findings/confidence'
+
+module FiberAudit
+  module Static
+    module Rules
+      # Base class for all static analysis rules.
+      #
+      # Subclasses use the class-level DSL to declare metadata:
+      #
+      #   class BlockingSubprocess < Base
+      #     id 'FA1001'
+      #     severity :high
+      #     confidence :high
+      #     description 'Blocking subprocess call in the fiber scheduler path'
+      #
+      #     def analyze(call_sites:)
+      #       # ...
+      #     end
+      #   end
+      #
+      # Severity resolution flow (monotonic):
+      #   1. Start with the rule's default_severity
+      #   2. Apply configuration.severity_override (replaces default if present)
+      #   3. Apply context ceiling: if the resulting severity is less severe
+      #      than the ceiling for the execution context, raise to the ceiling.
+      #      Never lower a severity that is already more severe than the ceiling.
+      #
+      class Base
+        # Context severity ceiling table.
+        #
+        # For each execution context, the ceiling is the minimum severity
+        # (maximum urgency) that a finding must reach. If the rule's base
+        # severity is already at or above the ceiling, it is left unchanged.
+        # A nil ceiling (unknown context) means no upgrade is applied.
+        #
+        CONTEXT_CEILING = {
+          request: :critical,
+          middleware: :critical,
+          websocket: :critical,
+          callback: :high,
+          view: :high,
+          job: :high,
+          boot: :medium,
+          console: :info,
+          test: :info,
+          rake_task: :low,
+          unknown: nil
+        }.freeze
+
+        class << self
+          # Get or set the rule identifier.
+          # Coerces the value to a frozen String.
+          def id(value = nil)
+            return @rule_id unless value
+
+            @rule_id = value.to_s.freeze
+          end
+
+          # Get or set the default severity.
+          # When setting, validates via Severity.coerce.
+          # Accepts Symbol or String values; Strings are normalized to Symbols.
+          def severity(value = nil)
+            return @default_severity unless value
+
+            normalized = value.is_a?(String) ? value.to_sym : value
+            @default_severity = Severity.coerce(normalized)
+          end
+
+          # Alias: getter for the default severity.
+          # Also accepts a value for DSL symmetry (delegates to severity).
+          def default_severity(value = nil)
+            return @default_severity unless value
+
+            severity(value)
+          end
+
+          # Get or set the default confidence.
+          # When setting, validates via Confidence.coerce.
+          # Accepts Symbol or String values; Strings are normalized to Symbols.
+          def confidence(value = nil)
+            return @default_confidence unless value
+
+            normalized = value.is_a?(String) ? value.to_sym : value
+            @default_confidence = Confidence.coerce(normalized)
+          end
+
+          # Alias: getter for the default confidence.
+          # Also accepts a value for DSL symmetry (delegates to confidence).
+          def default_confidence(value = nil)
+            return @default_confidence unless value
+
+            confidence(value)
+          end
+
+          # Get or set the human-readable description.
+          def description(value = nil)
+            return @description unless value
+
+            @description = value.to_s.freeze
+          end
+        end
+
+        # Construct a rule instance with its dependencies.
+        #
+        # @param workspace [Object] the analysis workspace
+        # @param context_resolver [Object] resolves call-site execution contexts
+        # @param configuration [FiberAudit::Configuration] audit configuration
+        def initialize(workspace:, context_resolver:, configuration:)
+          @workspace = workspace
+          @context_resolver = context_resolver
+          @configuration = configuration
+        end
+
+        # Analyze call sites and return an array of findings.
+        # Subclasses MUST override this method.
+        #
+        # @param call_sites [Array<FiberAudit::Static::CallSite>]
+        # @return [Array<FiberAudit::Finding>]
+        # @raise [NotImplementedError]
+        def analyze(call_sites:)
+          raise NotImplementedError,
+                "#{self.class.name}#analyze must be implemented by the subclass"
+        end
+
+        protected
+
+        # @return [Object] the analysis workspace
+        attr_reader :workspace
+
+        # @return [Object] the execution-context resolver
+        attr_reader :context_resolver
+
+        # @return [FiberAudit::Configuration] the audit configuration
+        attr_reader :configuration
+
+        private
+
+        # Compute the final severity for a finding.
+        #
+        # Resolution order:
+        #   1. configuration.severity_override(rule_id) replaces the default
+        #   2. Context ceiling monotonically raises (never lowers)
+        #
+        # @param default_sev [Symbol, String] rule's default severity
+        # @param context [Symbol, nil] execution context (nil → :unknown)
+        # @return [Symbol] the resolved severity
+        def severity_for(default_sev, context)
+          # Normalize String to Symbol defensively
+          default_sev = default_sev.to_sym if default_sev.is_a?(String)
+
+          # Step 1: configuration override (replaces default entirely)
+          base = configuration.severity_override(self.class.id) || default_sev
+
+          # Step 2: context ceiling (monotonic raise only)
+          ctx = context || :unknown
+          ceiling = CONTEXT_CEILING.fetch(ctx) do
+            CONTEXT_CEILING[:unknown]
+          end
+
+          return base if ceiling.nil?
+
+          # If the base severity is less severe than the ceiling (higher index),
+          # raise it to the ceiling. Otherwise keep it (never lower).
+          if Severity.index(base) > Severity.index(ceiling)
+            ceiling
+          else
+            base
+          end
+        end
+
+        # Severity index helper — delegates to Severity.index.
+        # Lower index = more severe (0 = :critical, 4 = :info).
+        #
+        # @param severity [Symbol] a severity level
+        # @return [Integer] the numeric index
+        def severity_index(severity)
+          Severity.index(severity)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# 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 BlockingSubprocess < Base
+        id 'FA1001'
+        severity :high
+        default_confidence :high
+        description 'Blocking subprocess call in the fiber scheduler path'
+
+        TARGETS = {
+          'Kernel' => %i[system exec spawn].freeze,
+          'Open3' => %i[capture2 capture2e capture3 pipeline].freeze,
+          'IO' => %i[popen].freeze,
+          'Process' => %i[waitall detach].freeze
+        }.freeze
+
+        BARE_KERNEL_METHODS = %i[system exec spawn].freeze
+
+        MESSAGE = 'Subprocess operation may block the thread running the fiber scheduler.'
+        REMEDIATION = 'Move long-running subprocess work outside the request path, or verify scheduler behaviour under load.'
+
+        def analyze(call_sites:)
+          call_sites.filter_map do |site|
+            next unless (match = match_call_site(site))
+
+            build_finding(site, match)
+          end
+        end
+
+        private
+
+        def match_call_site(site)
+          receiver = site.receiver_constant
+          method = site.method_name
+
+          if receiver.nil? && site.receiver_source.nil? && BARE_KERNEL_METHODS.include?(method)
+            return { constant: 'Kernel', method: method, confidence: :unknown }
+          end
+
+          return nil unless receiver && TARGETS.key?(receiver)
+          return nil unless TARGETS[receiver].include?(method)
+          return nil if shadowed?(receiver, site.nesting)
+
+          { constant: receiver, method: method, confidence: site.confidence }
+        end
+
+        def shadowed?(constant_name, nesting)
+          sem = workspace.semantic_index if workspace.respond_to?(:semantic_index)
+          sem ||= workspace if workspace.respond_to?(:resolve_constant)
+          return false unless sem.respond_to?(:resolve_constant)
+
+          resolved = sem.resolve_constant(constant_name, nesting: nesting || [])
+          !resolved.nil?
+        rescue StandardError
+          false
+        end
+
+        def build_finding(site, match)
+          operation = "#{match[:constant]}.#{match[:method]}"
+          context = site.execution_context || :unknown
+          sev = severity_for(self.class.severity, context)
+
+          Finding.new(
+            rule_id: self.class.id,
+            title: 'Blocking subprocess call',
+            category: :subprocess,
+            severity: sev,
+            confidence: match[:confidence],
+            location: site.location,
+            symbol: site.enclosing_symbol,
+            operation: operation,
+            execution_context: context,
+            message: MESSAGE,
+            evidence: [
+              Evidence.new(
+                source: :static,
+                message: "Matched #{operation}",
+                details: { receiver: match[:constant], method: match[:method] }
+              )
+            ],
+            remediation: REMEDIATION
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'registry'
+require_relative 'blocking_subprocess'
+require_relative 'thread_join'
+require_relative 'synchronization'
+require_relative 'thread_current_state'
+require_relative 'io_select'
+require_relative 'direct_socket'
+require_relative 'net_http_in_request'
+
+module FiberAudit
+  module Static
+    module Rules
+      module BuiltIns
+        RULES = [
+          BlockingSubprocess,
+          ThreadJoin,
+          Synchronization,
+          ThreadCurrentState,
+          IOSelect,
+          DirectSocket,
+          NetHTTPInRequest
+        ].freeze
+
+        module_function
+
+        def registry(workspace: nil, context_resolver: nil)
+          Registry.new(workspace: workspace, context_resolver: context_resolver).tap do |registry|
+            RULES.each { |rule_class| registry.register(rule_class) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# 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
+      # FA1006 – Detects direct socket creation that may bypass
+      # scheduler-aware networking and block the scheduler thread.
+      class DirectSocket < Base
+        id 'FA1006'
+        severity :medium
+        default_confidence :high
+        description 'Detects direct socket creation that may bypass scheduler-aware networking.'
+
+        TITLE    = 'Direct socket creation'
+        CATEGORY = :network
+
+        EXACT = %w[
+          TCPSocket TCPServer UDPSocket UNIXSocket UNIXServer Socket IPSocket
+        ].freeze
+
+        MESSAGE = 'Direct socket use may bypass scheduler-aware networking ' \
+                  'and block the scheduler thread.'
+        REMEDIATION = 'Use scheduler-aware networking APIs or verify the ' \
+                      'socket operations cooperate with the active Fiber scheduler.'
+
+        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 == :new
+
+          const = site.receiver_constant
+          return unless const
+
+          if EXACT.include?(const)
+            return if shadowed?(const, site.nesting)
+
+            return build_finding(site, const)
+          end
+
+          return unless ip_socket_subclass?(const)
+
+          build_finding(site, const)
+        end
+
+        def shadowed?(name, nesting)
+          sem = semantic_index
+          return false unless sem
+
+          !sem.resolve_constant(name, nesting: nesting || []).nil?
+        rescue StandardError
+          false
+        end
+
+        def ip_socket_subclass?(name)
+          sem = semantic_index
+          return false unless sem
+
+          sem.ancestors_of(name).include?('IPSocket')
+        rescue StandardError
+          false
+        end
+
+        def semantic_index
+          index = workspace.semantic_index if workspace.respond_to?(:semantic_index)
+          index || workspace
+        rescue StandardError
+          nil
+        end
+
+        def build_finding(site, const)
+          operation = "#{const}.new"
+          ctx = site.execution_context || :unknown
+
+          Finding.new(
+            rule_id: self.class.id,
+            title: self.class.title,
+            category: self.class.category,
+            severity: severity_for(:medium, ctx),
+            confidence: site.confidence,
+            location: site.location,
+            symbol: site.enclosing_symbol,
+            operation: operation,
+            execution_context: ctx,
+            message: MESSAGE,
+            evidence: [
+              Evidence.new(
+                source: 'static_analysis',
+                message: "Direct socket creation: #{operation}",
+                details: { receiver_constant: const, method: :new }
+              )
+            ],
+            remediation: REMEDIATION
+          )
+        end
+      end
+    end
+  end
+end