rack-libinjection 0.1.0

data/samples/README.md

@@ -0,0 +1,67 @@
+# Hot-path samples
+
+These files are diagnostic profiling loops, not release benchmarks. They are
+meant to be run while capturing a macOS `sample` profile and then narrowing the
+call tree with `filtercalltree`, following the same workflow as the other native
+hot-path samples in this workspace.
+
+Run from the repository root after compiling the extension:
+
+```sh
+bundle exec rake compile
+bundle exec ruby samples/libinjection_detect_raw_hot_path.rb
+bundle exec ruby samples/rack_query_hot_path.rb
+bundle exec ruby samples/rack_params_hot_path.rb
+bundle exec ruby samples/rack_all_surfaces_hot_path.rb
+```
+
+Each script prints:
+
+- current PID;
+- exact hot call being looped;
+- payload/request shape;
+- one-line `sample + filtercalltree` capture command;
+- expected native/Ruby symbols;
+- ops/sec or requests/sec;
+- GC allocation delta.
+
+## Scripts
+
+| Script | Hot path |
+| --- | --- |
+| `libinjection_detect_raw_hot_path.rb` | raw native `LibInjection.detect_raw(payload)` primitive used by middleware |
+| `rack_query_hot_path.rb` | `scan: [:query]`, raw query string plus native decoded variants, no Rack nested params parser and no `Rack::Request` allocation |
+| `rack_params_hot_path.rb` | `scan: [:params]`, Rack query parsing, nested param walk, native scan per string/key |
+| `rack_all_surfaces_hot_path.rb` | path decode, headers, cookies, params, recursive walk, native scan |
+
+Useful env knobs:
+
+```sh
+PAYLOAD=clean|sqli|xss
+DURATION=20
+SLEEP_BEFORE_HOT_LOOP=7
+PREHEAT_ITERATIONS=100
+DISABLE_GC=0|1
+THREATS=sqli,xss|sqli|xss
+```
+
+Native-only knobs:
+
+```sh
+INPUT_BYTES=128      # small input, GVL path
+INPUT_BYTES=2048     # large input, no-GVL path
+```
+
+Query/path native decoding knobs:
+
+```sh
+PATH_DECODE_DEPTH=2
+```
+
+All-surfaces knobs:
+
+```sh
+SCAN_COOKIE_NAMES=0|1
+```
+
+Results captured by the printed command are written under `samples/results/`.

data/samples/libinjection_detect_raw_hot_path.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+# Native hot-path sample for:
+#   LibInjection.detect_raw(payload)
+#
+# This is the primitive used by Rack::LibInjection#scan_string_into.
+# It is intentionally not a README benchmark: run it while capturing a macOS
+# `sample` profile to inspect native/Ruby hot symbols.
+#
+# Run:
+#   bundle exec ruby samples/libinjection_detect_raw_hot_path.rb
+#
+# Optional env:
+#   PAYLOAD=clean|sqli|xss INPUT_BYTES=2048 DURATION=25 PREHEAT_ITERATIONS=10 \
+#     bundle exec ruby samples/libinjection_detect_raw_hot_path.rb
+
+$stdout.sync = true
+$stderr.sync = true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "libinjection"
+
+payload_mode = ENV.fetch("PAYLOAD", "clean")
+input_bytes = Integer(ENV.fetch("INPUT_BYTES", "2048"))
+sleep_before_hot_loop = Float(ENV.fetch("SLEEP_BEFORE_HOT_LOOP", "7.0"))
+duration = Float(ENV.fetch("DURATION", "25.0"))
+preheat_iterations = Integer(ENV.fetch("PREHEAT_ITERATIONS", "10"))
+disable_gc = ENV.fetch("DISABLE_GC", "1") != "0"
+sample_name = "rack_libinjection_detect_raw_hot_path"
+native_grep = "LibInjection|libinjection|libinjection_native|rb_li_|li_input_|li_scan_|li_sqli_|li_xss_|libinjection_sqli|libinjection_xss|sqli|xss"
+
+raise ArgumentError, "INPUT_BYTES must be positive" unless input_bytes.positive?
+
+def monotonic
+  Process.clock_gettime(Process::CLOCK_MONOTONIC)
+end
+
+def gc_snapshot
+  stat = GC.stat
+
+  {
+    total_allocated_objects: stat.fetch(:total_allocated_objects),
+    minor_gc_count: stat.fetch(:minor_gc_count),
+    major_gc_count: stat.fetch(:major_gc_count)
+  }
+end
+
+def gc_delta(before, after)
+  before.each_with_object({}) do |(key, value), out|
+    out[key] = after.fetch(key) - value
+  end
+end
+
+def padded_payload(seed, input_bytes)
+  bytes = seed.b
+  return bytes.byteslice(0, input_bytes).b.freeze if bytes.bytesize >= input_bytes
+
+  filler = " AAAAA normal_token_12345".b
+  out = String.new(capacity: input_bytes, encoding: Encoding::BINARY)
+  out << bytes
+  out << filler while out.bytesize < input_bytes
+  out.byteslice(0, input_bytes).b.freeze
+end
+
+def payload_for(mode, input_bytes)
+  case mode
+  when "clean"
+    padded_payload("normal search term with harmless words", input_bytes)
+  when "sqli"
+    padded_payload("1 OR 1=1--", input_bytes)
+  when "xss"
+    padded_payload("<script>alert(1)</script>", input_bytes)
+  else
+    raise ArgumentError, "PAYLOAD must be one of: clean, sqli, xss"
+  end
+end
+
+def expected_type_for(mode)
+  case mode
+  when "clean" then nil
+  when "sqli" then :sqli
+  when "xss" then :xss
+  end
+end
+
+payload = payload_for(payload_mode, input_bytes)
+expected_type = expected_type_for(payload_mode)
+
+preheat_iterations.times do
+  result = LibInjection.detect_raw(payload)
+  actual_type = result && result[0]
+  raise "preheat: expected #{expected_type.inspect}, got #{result.inspect}" unless actual_type == expected_type
+end
+
+sample_seconds = (sleep_before_hot_loop + duration + 15).ceil
+sample_file = "/tmp/#{sample_name}.sample"
+txt_file = File.expand_path("results/#{sample_name}.txt", __dir__)
+txt_dir = File.dirname(txt_file)
+
+puts "pid=#{Process.pid}"
+puts "ruby=#{RUBY_DESCRIPTION}"
+puts "platform=#{RUBY_PLATFORM}"
+puts "mode=#{sample_name}"
+puts "call=LibInjection.detect_raw(payload)"
+puts "payload=#{payload_mode}"
+puts "input_bytes=#{payload.bytesize}"
+puts "disable_gc=#{disable_gc}"
+puts "duration=#{duration}"
+puts "preheat_iterations=#{preheat_iterations}"
+puts "sample_seconds=#{sample_seconds}"
+puts "sample_file=#{sample_file}"
+puts "txt_file=#{txt_file}"
+puts
+puts "Copy this one-line capture command:"
+puts %(mkdir -p "#{txt_dir}"; OUT="#{txt_file}"; SAMPLE="#{sample_file}"; { sample #{Process.pid} #{sample_seconds} -f "$SAMPLE"; echo; echo "===== focused native/Ruby symbols ====="; filtercalltree "$SAMPLE" | grep -E "#{native_grep}" | head -320; echo; echo "===== filtercalltree head -320 ====="; filtercalltree "$SAMPLE" | head -320; } 2>&1 | tee "$OUT")
+puts
+puts "Expected hot native symbols:"
+puts "  LibInjection.detect_raw -> rb_li_detect_raw"
+puts "  li_input_prepare / li_input_release"
+puts "  li_scan_run / li_scan_perform"
+puts "  li_scan_release_gvl / rb_nogvl path when INPUT_BYTES >= native threshold"
+puts "  libinjection_sqli / libinjection_xss"
+puts "  libinjection_sqli_init / libinjection_sqli_fingerprint / libinjection_sqli_check_fingerprint"
+puts
+puts "sleep=#{sleep_before_hot_loop} seconds before hot loop"
+puts
+
+begin
+  GC.start
+  GC.disable if disable_gc
+  before_gc = gc_snapshot
+  sleep sleep_before_hot_loop
+
+  count = 0
+  detected = 0
+  last_result = nil
+  started = monotonic
+  deadline = started + duration
+
+  while monotonic < deadline
+    last_result = LibInjection.detect_raw(payload)
+    detected += 1 if last_result
+    count += 1
+  end
+
+  actual_type = last_result && last_result[0]
+  raise "last_hot_loop: expected #{expected_type.inspect}, got #{last_result.inspect}" unless actual_type == expected_type
+
+  elapsed = monotonic - started
+  after_gc = gc_snapshot
+
+  puts "count=#{count}"
+  puts "detected=#{detected}"
+  puts "last_result=#{last_result.inspect}"
+  puts "elapsed=#{format('%.6f', elapsed)}"
+  puts "ops_per_sec=#{format('%.6f', count / elapsed)}"
+  puts "sec_per_op=#{format('%.9f', elapsed / [count, 1].max)}"
+  puts "gc_delta=#{gc_delta(before_gc, after_gc)}"
+ensure
+  GC.enable
+end

data/samples/rack_all_surfaces_hot_path.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+# Rack middleware hot-path sample for all currently supported scan surfaces:
+#   Rack::LibInjection.new(app, scan: [:params, :path, :headers, :cookies]).call(env)
+#
+# This path exercises path decoding, header filtering, cookie parsing, Rack params,
+# recursive param walking, notifier-free report mode, and the native detect_raw primitive.
+#
+# Run:
+#   bundle exec ruby samples/rack_all_surfaces_hot_path.rb
+#
+# Optional env:
+#   PAYLOAD=clean|sqli|xss PATH_DECODE_DEPTH=2 SCAN_COOKIE_NAMES=0 DURATION=20 \
+#     bundle exec ruby samples/rack_all_surfaces_hot_path.rb
+
+$stdout.sync = true
+$stderr.sync = true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "rack/mock"
+require "rack/libinjection"
+
+payload_mode = ENV.fetch("PAYLOAD", "sqli")
+path_decode_depth = Integer(ENV.fetch("PATH_DECODE_DEPTH", "2"))
+scan_cookie_names = ENV.fetch("SCAN_COOKIE_NAMES", "0") != "0"
+sleep_before_hot_loop = Float(ENV.fetch("SLEEP_BEFORE_HOT_LOOP", "7.0"))
+duration = Float(ENV.fetch("DURATION", "20.0"))
+preheat_iterations = Integer(ENV.fetch("PREHEAT_ITERATIONS", "100"))
+disable_gc = ENV.fetch("DISABLE_GC", "0") != "0"
+sample_name = "rack_libinjection_all_surfaces_hot_path"
+native_grep = "Rack::LibInjection|rack/libinjection|LibInjection|libinjection|rb_li_|li_input_|li_scan_|libinjection_sqli|libinjection_xss|scan_path|scan_headers|scan_cookies|scan_params|scan_url_encoded_string_into|scan_string_into|detect_url_encoded_raw|li_url_decode|header_name|walk_into|Rack::QueryParser|parse_nested_query|cookies"
+
+ATTACK_ENV_KEY = Rack::LibInjection::ATTACK_ENV_KEY
+
+def monotonic
+  Process.clock_gettime(Process::CLOCK_MONOTONIC)
+end
+
+def gc_snapshot
+  stat = GC.stat
+
+  {
+    total_allocated_objects: stat.fetch(:total_allocated_objects),
+    minor_gc_count: stat.fetch(:minor_gc_count),
+    major_gc_count: stat.fetch(:major_gc_count)
+  }
+end
+
+def gc_delta(before, after)
+  before.each_with_object({}) do |(key, value), out|
+    out[key] = after.fetch(key) - value
+  end
+end
+
+def payload_for(mode)
+  case mode
+  when "clean" then "normal-search-term"
+  when "sqli"  then "1 OR 1=1--"
+  when "xss"   then "<script>alert(1)</script>"
+  else
+    raise ArgumentError, "PAYLOAD must be one of: clean, sqli, xss"
+  end
+end
+
+def path_for(mode)
+  case mode
+  when "clean"
+    "/items/catalog/search"
+  when "sqli"
+    # Double-encoded SQLi path segment. With PATH_DECODE_DEPTH=2 it reaches:
+    #   /items/1 OR 1=1--
+    "/items/1%2520OR%25201%253D1--"
+  when "xss"
+    "/items/%253Cscript%253Ealert(1)%253C%252Fscript%253E"
+  end
+end
+
+def build_query(payload)
+  Rack::Utils.build_nested_query(
+    "q" => payload,
+    "profile" => {
+      "name" => "Roman",
+      "filters" => ["recent", payload, "safe"]
+    },
+    "page" => "1"
+  )
+end
+
+def expected_min_attacks(mode, scan_cookie_names)
+  return 0 if mode == "clean"
+
+  # At least: path, param q, nested param, custom header, cookie value.
+  # More may be reported because path is scanned as full path + segment and XSS/SQLi
+  # signatures can hit both raw and decoded values.
+  scan_cookie_names ? 5 : 4
+end
+
+payload = payload_for(payload_mode)
+query = build_query(payload)
+path = "#{path_for(payload_mode)}?#{query}"
+expected_min = expected_min_attacks(payload_mode, scan_cookie_names)
+base_env = Rack::MockRequest.env_for(
+  path,
+  "HTTP_X_ATTACK_PROBE" => payload,
+  "HTTP_USER_AGENT" => "rack-libinjection-hot-path-sample/1.0",
+  "HTTP_COOKIE" => "probe=#{Rack::Utils.escape(payload)}; session_id=abcdef123456"
+)
+
+app = ->(_env) { [204, {}, []] }
+middleware = Rack::LibInjection.new(
+  app,
+  mode: :report,
+  scan: %i[params path headers cookies],
+  path_decode_depth: path_decode_depth,
+  scan_cookie_names: scan_cookie_names,
+  notify_skipped: false
+)
+
+preheat_iterations.times do
+  env = base_env.dup
+  status, = middleware.call(env)
+  attacks = env.fetch(ATTACK_ENV_KEY)
+  raise "preheat: unexpected status #{status}" unless status == 204
+  raise "preheat: expected >= #{expected_min} attacks, got #{attacks.inspect}" if attacks.length < expected_min
+end
+
+sample_seconds = (sleep_before_hot_loop + duration + 15).ceil
+sample_file = "/tmp/#{sample_name}.sample"
+txt_file = File.expand_path("results/#{sample_name}.txt", __dir__)
+txt_dir = File.dirname(txt_file)
+
+puts "pid=#{Process.pid}"
+puts "ruby=#{RUBY_DESCRIPTION}"
+puts "platform=#{RUBY_PLATFORM}"
+puts "mode=#{sample_name}"
+puts "call=Rack::LibInjection.new(app, scan: %i[params path headers cookies]).call(env)"
+puts "payload=#{payload_mode}"
+puts "path_decode_depth=#{path_decode_depth}"
+puts "scan_cookie_names=#{scan_cookie_names}"
+puts "query_bytes=#{query.bytesize}"
+puts "path=#{path_for(payload_mode)}"
+puts "disable_gc=#{disable_gc}"
+puts "duration=#{duration}"
+puts "preheat_iterations=#{preheat_iterations}"
+puts "sample_seconds=#{sample_seconds}"
+puts "sample_file=#{sample_file}"
+puts "txt_file=#{txt_file}"
+puts
+puts "Copy this one-line capture command:"
+puts %(mkdir -p "#{txt_dir}"; OUT="#{txt_file}"; SAMPLE="#{sample_file}"; { sample #{Process.pid} #{sample_seconds} -f "$SAMPLE"; echo; echo "===== focused Rack/native symbols ====="; filtercalltree "$SAMPLE" | grep -E "#{native_grep}" | head -420; echo; echo "===== filtercalltree head -420 ====="; filtercalltree "$SAMPLE" | head -420; } 2>&1 | tee "$OUT")
+puts
+puts "Expected hot symbols:"
+puts "  Rack::LibInjection#call / #collect_attacks"
+puts "  #scan_path_into / #scan_path_value_into / #scan_url_encoded_string_into"
+puts "  #scan_headers_into / #header_name"
+puts "  #scan_cookies_into"
+puts "  #scan_params_into / #walk_into"
+puts "  #scan_url_encoded_string_into -> LibInjection.detect_url_encoded_raw -> rb_li_detect_url_encoded_raw"
+puts "  li_input_prepare / li_scan_run / li_scan_perform"
+puts "  libinjection_sqli / libinjection_xss"
+puts
+puts "sleep=#{sleep_before_hot_loop} seconds before hot loop"
+puts
+
+begin
+  GC.start
+  GC.disable if disable_gc
+  before_gc = gc_snapshot
+  sleep sleep_before_hot_loop
+
+  count = 0
+  total_attacks = 0
+  started = monotonic
+  deadline = started + duration
+
+  while monotonic < deadline
+    env = base_env.dup
+    status, = middleware.call(env)
+    raise "hot_loop: unexpected status #{status}" unless status == 204
+
+    attacks = env.fetch(ATTACK_ENV_KEY)
+    total_attacks += attacks.length
+    count += 1
+  end
+
+  elapsed = monotonic - started
+  after_gc = gc_snapshot
+
+  puts "count=#{count}"
+  puts "total_attacks=#{total_attacks}"
+  puts "attacks_per_request=#{format('%.6f', total_attacks.to_f / [count, 1].max)}"
+  puts "elapsed=#{format('%.6f', elapsed)}"
+  puts "requests_per_sec=#{format('%.6f', count / elapsed)}"
+  puts "sec_per_request=#{format('%.9f', elapsed / [count, 1].max)}"
+  puts "gc_delta=#{gc_delta(before_gc, after_gc)}"
+ensure
+  GC.enable
+end

data/samples/rack_params_hot_path.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+# Rack middleware hot-path sample for parsed params only:
+#   Rack::LibInjection.new(app, scan: [:params]).call(env)
+#
+# This path exercises Rack param parsing + recursive param walking +
+# LibInjection.detect_raw for each string/key.
+#
+# Run:
+#   bundle exec ruby samples/rack_params_hot_path.rb
+#
+# Optional env:
+#   PAYLOAD=clean|sqli|xss DURATION=20 PREHEAT_ITERATIONS=100 DISABLE_GC=0 \
+#     bundle exec ruby samples/rack_params_hot_path.rb
+
+$stdout.sync = true
+$stderr.sync = true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "rack/mock"
+require "rack/libinjection"
+
+payload_mode = ENV.fetch("PAYLOAD", "clean")
+sleep_before_hot_loop = Float(ENV.fetch("SLEEP_BEFORE_HOT_LOOP", "7.0"))
+duration = Float(ENV.fetch("DURATION", "20.0"))
+preheat_iterations = Integer(ENV.fetch("PREHEAT_ITERATIONS", "100"))
+disable_gc = ENV.fetch("DISABLE_GC", "0") != "0"
+sample_name = "rack_libinjection_params_hot_path"
+native_grep = "Rack::LibInjection|rack/libinjection|LibInjection|libinjection|rb_li_|li_input_|li_scan_|libinjection_sqli|libinjection_xss|scan_params_into|walk_into|scan_string_into|Rack::QueryParser|parse_nested_query"
+
+ATTACK_ENV_KEY = Rack::LibInjection::ATTACK_ENV_KEY
+
+def monotonic
+  Process.clock_gettime(Process::CLOCK_MONOTONIC)
+end
+
+def gc_snapshot
+  stat = GC.stat
+
+  {
+    total_allocated_objects: stat.fetch(:total_allocated_objects),
+    minor_gc_count: stat.fetch(:minor_gc_count),
+    major_gc_count: stat.fetch(:major_gc_count)
+  }
+end
+
+def gc_delta(before, after)
+  before.each_with_object({}) do |(key, value), out|
+    out[key] = after.fetch(key) - value
+  end
+end
+
+def payload_for(mode)
+  case mode
+  when "clean" then "normal search term"
+  when "sqli"  then "1 OR 1=1--"
+  when "xss"   then "<script>alert(1)</script>"
+  else
+    raise ArgumentError, "PAYLOAD must be one of: clean, sqli, xss"
+  end
+end
+
+def expected_min_attacks(mode)
+  mode == "clean" ? 0 : 1
+end
+
+def build_query(payload)
+  Rack::Utils.build_nested_query(
+    "q" => payload,
+    "profile" => {
+      "name" => "Roman",
+      "filters" => ["recent", payload, "safe"]
+    },
+    "page" => "1"
+  )
+end
+
+payload = payload_for(payload_mode)
+expected_min = expected_min_attacks(payload_mode)
+query = build_query(payload)
+path = "/search?#{query}"
+base_env = Rack::MockRequest.env_for(path)
+
+app = ->(_env) { [204, {}, []] }
+middleware = Rack::LibInjection.new(
+  app,
+  mode: :report,
+  scan: [:params],
+  notify_skipped: false
+)
+
+preheat_iterations.times do
+  env = base_env.dup
+  status, = middleware.call(env)
+  attacks = env.fetch(ATTACK_ENV_KEY)
+  raise "preheat: unexpected status #{status}" unless status == 204
+  raise "preheat: expected >= #{expected_min} attacks, got #{attacks.inspect}" if attacks.length < expected_min
+end
+
+sample_seconds = (sleep_before_hot_loop + duration + 15).ceil
+sample_file = "/tmp/#{sample_name}.sample"
+txt_file = File.expand_path("results/#{sample_name}.txt", __dir__)
+txt_dir = File.dirname(txt_file)
+
+puts "pid=#{Process.pid}"
+puts "ruby=#{RUBY_DESCRIPTION}"
+puts "platform=#{RUBY_PLATFORM}"
+puts "mode=#{sample_name}"
+puts "call=Rack::LibInjection.new(app, scan: [:params]).call(env)"
+puts "payload=#{payload_mode}"
+puts "query_bytes=#{query.bytesize}"
+puts "disable_gc=#{disable_gc}"
+puts "duration=#{duration}"
+puts "preheat_iterations=#{preheat_iterations}"
+puts "sample_seconds=#{sample_seconds}"
+puts "sample_file=#{sample_file}"
+puts "txt_file=#{txt_file}"
+puts
+puts "Copy this one-line capture command:"
+puts %(mkdir -p "#{txt_dir}"; OUT="#{txt_file}"; SAMPLE="#{sample_file}"; { sample #{Process.pid} #{sample_seconds} -f "$SAMPLE"; echo; echo "===== focused Rack/native symbols ====="; filtercalltree "$SAMPLE" | grep -E "#{native_grep}" | head -360; echo; echo "===== filtercalltree head -360 ====="; filtercalltree "$SAMPLE" | head -360; } 2>&1 | tee "$OUT")
+puts
+puts "Expected hot symbols:"
+puts "  Rack::LibInjection#call / #collect_attacks"
+puts "  Rack::LibInjection#scan_params_into / #walk_into / #scan_string_into"
+puts "  Rack query parsing frames for nested params"
+puts "  LibInjection.detect_raw -> rb_li_detect_raw"
+puts "  li_input_prepare / li_scan_run / li_scan_perform"
+puts "  libinjection_sqli / libinjection_xss"
+puts
+puts "sleep=#{sleep_before_hot_loop} seconds before hot loop"
+puts
+
+begin
+  GC.start
+  GC.disable if disable_gc
+  before_gc = gc_snapshot
+  sleep sleep_before_hot_loop
+
+  count = 0
+  total_attacks = 0
+  started = monotonic
+  deadline = started + duration
+
+  while monotonic < deadline
+    env = base_env.dup
+    status, = middleware.call(env)
+    raise "hot_loop: unexpected status #{status}" unless status == 204
+
+    attacks = env.fetch(ATTACK_ENV_KEY)
+    total_attacks += attacks.length
+    count += 1
+  end
+
+  elapsed = monotonic - started
+  after_gc = gc_snapshot
+
+  puts "count=#{count}"
+  puts "total_attacks=#{total_attacks}"
+  puts "attacks_per_request=#{format('%.6f', total_attacks.to_f / [count, 1].max)}"
+  puts "elapsed=#{format('%.6f', elapsed)}"
+  puts "requests_per_sec=#{format('%.6f', count / elapsed)}"
+  puts "sec_per_request=#{format('%.9f', elapsed / [count, 1].max)}"
+  puts "gc_delta=#{gc_delta(before_gc, after_gc)}"
+ensure
+  GC.enable
+end