rack-libinjection 0.1.0

data/README.md

@@ -0,0 +1,68 @@
+# rack-libinjection
+
+`rack-libinjection` is a small native Ruby binding plus Rack middleware for
+[libinjection](https://github.com/libinjection/libinjection).
+
+It adds a tokenizer/fingerprint-based SQLi/XSS **signal layer** to Rack and
+Rails applications. It is report-only by default.
+
+## Important scope note
+
+This is not a full WAF. The middleware scans only the configured Rack surfaces.
+The default is:
+
+- parsed Rack params (`scan: [:params]`)
+
+Optional surfaces are available for raw query strings, path, headers, and cookies:
+
+- `scan: [:query]` for a fast raw query-string signal that avoids Rack nested params parsing
+- `scan: [:params, :path, :headers, :cookies]` for semantic params plus other Rack surfaces
+
+The middleware can scan both SQLi and XSS signals by default, or only one class through `threats: [:sqli]` / `threats: [:xss]`. Path and raw-query values are decoded up to `path_decode_depth` times for detection inside the native extension, avoiding Ruby `gsub`/regex allocation on this hot path. Query/path/header-only configurations are scanned directly from the Rack env without constructing `Rack::Request`; params and cookies still use Rack parsers. Header
+scanning skips common low-signal protocol/browser headers by default through
+`ignore_headers`. Cookie values are scanned when `:cookies` is enabled; cookie
+names are skipped unless `scan_cookie_names: true` is configured. In `mode: :block`, native/Rack parser errors fail closed by default through `parser_errors: :auto`, and values skipped by `max_value_bytes` / `max_depth` fail closed by default through `skipped_inputs: :auto`.
+
+Raw JSON body scanning is not part of the current middleware. JSON bodies,
+large request bodies, multipart file contents, and application-specific decoding
+need separate design. See [GET_STARTED.md](GET_STARTED.md) before deploying.
+
+## Usage
+
+All installation, middleware configuration, low-level API examples, vendoring,
+system-library mode, GVL notes, threat model, and operational guidance live in
+[GET_STARTED.md](GET_STARTED.md).
+
+## What this is
+
+- A native binding to vendored `libinjection` `v4.0.0`.
+- A Rack/Rails middleware that emits attack signals for configured request
+  surfaces.
+- A diagnostic API for SQLi fingerprints, parser contexts, SQL tokens, XSS
+  contexts, and HTML5 tokens.
+- A small signal layer that can feed logs, notifications, or `Rack::Attack`-style
+  scoring.
+
+## What this is not
+
+- Not a full WAF.
+- Not a replacement for Rails escaping, bind params, CSP, authorization, or
+  upstream WAF/rate-limit protections.
+- Not a promise to catch every SQLi/XSS payload.
+- Not enabled in blocking mode by default.
+- Not a JSON-body scanner yet.
+
+## Native dependency
+
+The default build uses pinned, vendored `libinjection` sources. Source checkouts
+can regenerate or verify the vendored tree through `script/vendor_libs.rb`; see
+[GET_STARTED.md](GET_STARTED.md) for commands and system-library mode.
+
+## Security policy
+
+Report suspected vulnerabilities privately. See [SECURITY.md](SECURITY.md).
+
+## License
+
+The Ruby gem is MIT-licensed. The vendored upstream `libinjection` sources are
+BSD-3-Clause licensed and included as `LICENSE-libinjection.txt`.

data/SECURITY.md

@@ -0,0 +1,65 @@
+# Security policy
+
+`rack-libinjection` is a security signal layer, so vulnerability reports are
+welcome even for edge cases that look minor.
+
+## Supported versions
+
+The project is pre-1.0. Security fixes are applied to the latest released
+version only until a stable compatibility policy exists.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a suspected vulnerability.
+
+Send a report to:
+
+- `romanhajdarov@gmail.com`
+
+Include:
+
+- affected version / commit;
+- Ruby, Rack, and OS versions;
+- minimal reproduction;
+- whether the issue is in the native binding, Rack middleware, vendoring, or
+  documentation;
+- expected vs actual behavior.
+
+## Scope
+
+Useful reports include:
+
+- crashes or memory-safety issues in the native extension;
+- incorrect use of vendored libinjection sources;
+- middleware bypasses caused by this gem's Rack integration;
+- false claims in documentation that can lead to unsafe deployment;
+- unsafe default behavior around notifications, blocking mode, or skipped input.
+
+Bypasses in upstream `libinjection` itself should also be reported upstream, but
+it is still useful to notify this project when the Rack integration makes them
+worse or hides the limitation.
+
+## Native hardening expectations
+
+The native extension is expected to tolerate empty strings, binary strings,
+invalid UTF-8 byte sequences, null bytes, and large inputs without crashing.
+Public low-level scans copy large inputs before releasing the GVL, so the C
+scanner does not read directly from a Ruby `String` buffer while Ruby code may
+mutate the same object from another thread. Copied native buffers are released
+through `rb_ensure` cleanup paths.
+
+The project includes a `security:smoke` task with random/binary inputs and a CI
+sanitizer job for AddressSanitizer/UBSan builds. These checks are not a
+replacement for upstream libinjection fuzzing, but regressions in the Ruby
+binding or middleware integration should be caught here.
+
+The binding scans bytes. It does not perform Unicode normalization or transcode
+UTF-16/UTF-32 payloads into UTF-8. Applications that accept non-UTF-8 text must
+normalize before scanning if they expect semantic text detection rather than raw
+byte scanning.
+
+## Fail-closed behavior in blocking mode
+
+Vendored libinjection v4 can return parser errors, and Rack can raise parameter/cookie parser errors before values are available for semantic scanning. The middleware exposes `parser_errors:` so applications can choose report, block, or raise behavior. The default `:auto` policy reports parser errors in report mode and blocks them in block mode.
+
+Inputs beyond `max_value_bytes` or deeper than `max_depth` are not scanned. The middleware exposes `skipped_inputs:` so applications can choose report, block, or allow behavior. The default `:auto` policy reports skipped input in report mode and blocks it in block mode.

data/ext/libinjection/extconf.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rbconfig"
+
+USE_SYSTEM = arg_config("--use-system-libinjection") || ENV["LIBINJECTION_USE_SYSTEM"] == "1"
+
+EXT_DIR            = __dir__
+PRIMARY_VENDOR_DIR = File.join(EXT_DIR, "vendor", "libinjection")
+
+REQUIRED_VENDOR_FILES = %w[
+  src/libinjection.h
+  src/libinjection_error.h
+  src/libinjection_sqli.h
+  src/libinjection_sqli_data.h
+  src/libinjection_xss.h
+  src/libinjection_html5.h
+  src/libinjection_sqli.c
+  src/libinjection_xss.c
+  src/libinjection_html5.c
+].freeze
+
+
+def compiler_version
+  cc = RbConfig::CONFIG.fetch("CC", "cc")
+  `#{cc} --version 2>&1`
+rescue StandardError
+  ""
+end
+
+def gcc_without_clang?
+  version = compiler_version.downcase
+  version.include?("gcc") && !version.include?("clang")
+end
+def vendor_ready?(dir)
+  File.file?(File.join(dir, ".vendored")) && REQUIRED_VENDOR_FILES.all? { |path| File.file?(File.join(dir, path)) }
+end
+
+def abort_missing_vendor!
+  abort <<~MSG
+    libinjection vendored sources are missing.
+
+    Run:
+      ruby script/vendor_libs.rb
+
+    Security note: extconf.rb does not auto-download native sources during build.
+  MSG
+end
+
+def find_vendor_dir
+  candidates = [PRIMARY_VENDOR_DIR]
+
+  dir = __dir__
+  6.times do
+    candidates << File.join(dir, "ext", "libinjection", "vendor", "libinjection")
+    dir = File.dirname(dir)
+  end
+
+  candidates.map! { |path| File.expand_path(path) }
+  candidates.uniq!
+
+  abort_missing_vendor! unless vendor_ready?(PRIMARY_VENDOR_DIR)
+  candidates.find { |path| vendor_ready?(path) }
+end
+
+def configure_system!
+  puts "Building with SYSTEM libinjection"
+
+  if find_executable("pkg-config")
+    cflags = `pkg-config --cflags libinjection 2>/dev/null`.strip
+    libs   = `pkg-config --libs   libinjection 2>/dev/null`.strip
+    $CPPFLAGS << " #{cflags}" unless cflags.empty?
+    $libs     << " #{libs}"   unless libs.empty?
+  end
+
+  abort "libinjection.h is required"        unless have_header("libinjection.h")
+  abort "libinjection_sqli.h is required"   unless have_header("libinjection_sqli.h")
+  abort "libinjection_xss.h is required"    unless have_header("libinjection_xss.h")
+  abort "libinjection library is required"  unless have_library("injection", "libinjection_sqli")
+  abort "libinjection_version() is required" unless have_func("libinjection_version")
+end
+
+def configure_vendored!(vendor_dir)
+  abort "libinjection vendored sources are missing" unless vendor_dir
+
+  versions = File.read(File.join(vendor_dir, ".vendored"))
+  puts "Building with VENDORED libinjection from #{vendor_dir}"
+  puts "  #{versions.tr("\n", ", ")}"
+
+  src_dir = File.join(vendor_dir, "src")
+  $CPPFLAGS << " -I#{src_dir}"
+  $srcs  = %w[libinjection_ext.c libinjection_sqli.c libinjection_xss.c libinjection_html5.c]
+  $VPATH = [EXT_DIR, src_dir]
+end
+
+$CFLAGS    << " -std=c99 -Wall -Wextra -O3"
+$CFLAGS    << " -Wno-unused-function -Wno-unused-parameter"
+
+if ENV["LIBINJECTION_SANITIZE"] == "1"
+  $CFLAGS  << " -O1 -g -fsanitize=address,undefined -fno-omit-frame-pointer"
+  $LDFLAGS << " -fsanitize=address,undefined"
+end
+
+$CFLAGS    << " -Wno-enum-int-mismatch" if gcc_without_clang?
+$warnflags  = ""
+
+unless $CFLAGS.include?("LI_NOGVL_THRESHOLD")
+  $CFLAGS << " -DLI_NOGVL_THRESHOLD=1024"
+end
+
+USE_SYSTEM ? configure_system! : configure_vendored!(find_vendor_dir)
+
+create_makefile("libinjection/libinjection_native")