scryer 0.3.0 → 1.1.1

data/lib/scryer/rspec.rb

@@ -0,0 +1,55 @@
+# Opt-in RSpec integration — require this file yourself (e.g. `require
+# "scryer/rspec"` in spec_helper.rb) rather than it loading automatically
+# with the gem, since RSpec itself is never a Scryer runtime dependency (see
+# scryer.gemspec's zero-runtime-dependency design) and this file references
+# RSpec::Matchers, which only exists once RSpec has already been loaded by
+# the host app. Requiring "scryer" alone never pulls this in.
+#
+# Turns "did this app's own security scan stay clean" into a normal RSpec
+# expectation, so a regression (a new critical finding, or a specific
+# previously-fixed rule firing again) fails the test suite the same way any
+# other regression would, instead of only showing up the next time someone
+# remembers to run `scryer` by hand or a separate CI step notices it.
+#
+#   RSpec.describe "security" do
+#     it "has no critical findings" do
+#       expect(Scryer.scan(root: Rails.root.to_s)).to have_no_critical_findings
+#     end
+#
+#     it "never reintroduces the mass-assignment bug fixed in PR #123" do
+#       expect(Scryer.scan(root: Rails.root.to_s)).to have_no_findings_for("mass_assignment")
+#     end
+#   end
+#
+# Both matchers work against a Scryer::Scanner::Result (what Scryer.scan/
+# Scanner#call returns) — style/performance findings are deliberately
+# excluded from have_no_critical_findings (only security findings carry
+# real security risk; a slow app isn't a "critical" security finding), but
+# have_no_findings_for checks all three categories, since a rule regressing
+# is worth catching regardless of which category it's filed under.
+require "rspec/expectations"
+
+RSpec::Matchers.define :have_no_critical_findings do
+  match do |result|
+    @criticals = result.security_findings.select { |f| f.severity == "critical" }
+    @criticals.empty?
+  end
+
+  failure_message do
+    lines = @criticals.map { |f| "  - #{f.rule_id} at #{f.file}:#{f.line} — #{f.message}" }
+    "expected no critical security findings, but got #{@criticals.size}:\n#{lines.join("\n")}"
+  end
+end
+
+RSpec::Matchers.define :have_no_findings_for do |rule_id|
+  match do |result|
+    @matches = (result.security_findings + result.performance_findings + result.style_findings)
+               .select { |f| f.rule_id == rule_id.to_s }
+    @matches.empty?
+  end
+
+  failure_message do
+    lines = @matches.map { |f| "  - #{f.file}:#{f.line} — #{f.message}" }
+    "expected no findings for rule #{rule_id.inspect}, but got #{@matches.size}:\n#{lines.join("\n")}"
+  end
+end

data/lib/scryer/rule.rb

@@ -5,7 +5,24 @@ module Scryer
   # the relative file path (for reporting).
   class Rule
     class << self
-      attr_accessor :rule_id, :category, :default_severity, :title
+      attr_accessor :rule_id, :category, :default_severity, :title, :cwe, :owasp_category
+
+      # "high"/"medium"/"low" — Scryer's own best-effort estimate of how
+      # often *this specific rule's* pattern-match actually reflects a real
+      # issue, independent of `severity` (how bad it is *if* real). A rule
+      # can be both high-severity and low-confidence at once (idor is the
+      # clearest example: a real IDOR is serious, but this rule's heuristic
+      # — no visible authorization call anywhere in the controller class —
+      # is the least precise in the gem). Defaults to "medium" so every
+      # rule doesn't have to set it explicitly; only rules with a clearly
+      # different precision (idor's documented false-positive risk, or a
+      # narrow literal-match rule with very little room for ambiguity) set
+      # this themselves. Not derived from anything measured at runtime —
+      # this is a static per-rule estimate, same as `default_severity`.
+      def confidence
+        @confidence || "medium"
+      end
+      attr_writer :confidence
 
       def inherited(subclass)
         super
@@ -27,11 +44,14 @@ module Scryer
 
     private
 
-    def finding(line:, message:, suggested_fix:, severity: self.class.default_severity)
+    def finding(line:, message:, suggested_fix:, severity: self.class.default_severity, confidence: self.class.confidence)
       Finding.new(
         rule_id: self.class.rule_id,
         category: self.class.category,
         severity: severity,
+        confidence: confidence,
+        cwe: self.class.cwe,
+        owasp_category: self.class.owasp_category,
         file: file,
         line: line,
         code_snippet: Ast.source_line(source, line),

data/lib/scryer/rules/action_cable_forgery_protection_rule.rb

@@ -0,0 +1,50 @@
+module Scryer
+  module Rules
+    # Flags `config.action_cable.disable_request_forgery_protection = true`
+    # — an explicit opt-out of Action Cable's default check that a
+    # WebSocket connection's request `Origin` header matches the app's own
+    # allowed origins, which otherwise blocks cross-site WebSocket hijacking.
+    # Same shape/reasoning as ForceSslRule: only the explicit opt-in to the
+    # insecure behavior is flagged, not its absence.
+    class ActionCableForgeryProtectionRule < Rule
+      self.rule_id = "action_cable_forgery_protection_disabled"
+      self.category = "security"
+      self.default_severity = "critical"
+      self.title = "Action Cable request forgery protection explicitly disabled"
+      self.cwe = "CWE-352"
+      self.owasp_category = "A01:2021-Broken Access Control"
+      self.confidence = "high"
+
+      def scan
+        findings = []
+
+        Ast.each_node(sexp) do |node|
+          next unless Ast.tagged?(node, :assign)
+
+          target = node[1]
+          next unless Ast.tagged?(target, :field)
+          next unless Ast.ident_text(target[3]) == "disable_request_forgery_protection"
+
+          value = node[2]
+          next unless Ast.true_literal?(value)
+
+          line = Ast.line_of(node)
+          findings << finding(
+            line: line,
+            message: "`config.action_cable.disable_request_forgery_protection = true` explicitly " \
+                      "disables Action Cable's default check that a WebSocket connection's " \
+                      "`Origin` header matches an allowed origin — without it, another site can " \
+                      "open a WebSocket connection to this app in a visitor's browser and act as " \
+                      "that visitor (cross-site WebSocket hijacking).",
+            suggested_fix: "Remove this override and set `config.action_cable.allowed_request_origins` " \
+                            "to the app's real origin(s) instead, unless request forgery protection is " \
+                            "deliberately being handled some other way — if so, leave a comment " \
+                            "explaining that."
+          )
+        end
+
+        findings
+      end
+    end
+  end
+end

data/lib/scryer/rules/active_storage_inline_disposition_rule.rb

@@ -0,0 +1,50 @@
+module Scryer
+  module Rules
+    # Flags an explicit `disposition: "inline"`/`:inline` on a blob/variant
+    # URL helper (`rails_blob_path`, `rails_blob_url`, `url_for`, a
+    # `.variant(...)` chain). Serving user-uploaded content inline (rendered
+    # directly in the browser, rather than downloaded) can lead to stored
+    # XSS if the uploaded file's content-type isn't tightly restricted — an
+    # uploaded SVG or HTML file executes in the page's own origin.
+    class ActiveStorageInlineDispositionRule < Rule
+      self.rule_id = "active_storage_inline_disposition"
+      self.category = "security"
+      self.default_severity = "warning"
+      self.title = "Active Storage content served with inline disposition"
+      self.cwe = "CWE-79"
+      self.owasp_category = "A03:2021-Injection"
+      self.confidence = "medium"
+
+      def scan
+        findings = []
+
+        Ast.each_node(sexp) do |node|
+          next unless Ast.tagged?(node, :method_add_arg, :command, :command_call)
+
+          inner = Ast.tagged?(node, :method_add_arg) ? node[1] : node
+          name_pair = Ast.call_name(inner)
+          next unless name_pair
+
+          args = Ast.call_arguments(node)
+          disposition = Ast.keyword_arg(args, "disposition")
+          next unless disposition && Ast.literal_text(disposition) == "inline"
+
+          line = Ast.line_of(node)
+          findings << finding(
+            line: line,
+            message: "`disposition: \"inline\"` renders this attachment's content directly in " \
+                      "the browser instead of downloading it — if the attachment's content-type " \
+                      "isn't tightly restricted, a user-uploaded SVG or HTML file served this way " \
+                      "executes as if it were part of the site.",
+            suggested_fix: "Prefer the default `disposition: \"attachment\"` (or drop the option " \
+                            "entirely) unless inline rendering is genuinely required — and if it " \
+                            "is, make sure the attachment has a strict `content_type:` allowlist " \
+                            "(e.g. image types only) so nothing executable can reach this code path."
+          )
+        end
+
+        findings
+      end
+    end
+  end
+end

data/lib/scryer/rules/active_storage_missing_content_type_validation_rule.rb

@@ -0,0 +1,79 @@
+module Scryer
+  module Rules
+    # Flags `has_one_attached`/`has_many_attached :name` with no
+    # `validates :name, content_type: [...]` anywhere in the same class —
+    # without a content-type allowlist, a user can upload anything (an SVG
+    # or HTML file that executes script when served, an executable, ...),
+    # not just the file type the feature was built for.
+    class ActiveStorageMissingContentTypeValidationRule < Rule
+      self.rule_id = "active_storage_missing_content_type_validation"
+      self.category = "security"
+      self.default_severity = "warning"
+      self.title = "Active Storage attachment without a content-type validation"
+      self.cwe = "CWE-434"
+      self.owasp_category = "A04:2021-Insecure Design"
+      self.confidence = "medium"
+
+      ATTACHMENT_METHODS = %w[has_one_attached has_many_attached].freeze
+
+      def scan
+        findings = []
+
+        Ast.each_node(sexp) do |node|
+          next unless Ast.tagged?(node, :class)
+
+          body = node[3]
+          validated_names = each_content_type_validated_names(body)
+
+          each_attachment(body).each do |call_node, name|
+            next if validated_names.include?(name)
+
+            line = Ast.line_of(call_node)
+            findings << finding(
+              line: line,
+              message: "`:#{name}` is attached via Active Storage with no `content_type:` " \
+                        "validation anywhere in this class — any file type can be uploaded, " \
+                        "including ones that execute in a browser if ever served back (e.g. SVG, " \
+                        "HTML) or aren't safe to store at all.",
+              suggested_fix: "Add an explicit allowlist: `validates :#{name}, content_type: " \
+                              "['image/png', 'image/jpeg']` (whatever types this feature actually " \
+                              "needs) so anything else is rejected at upload time."
+            )
+          end
+        end
+
+        findings
+      end
+
+      private
+
+      def each_attachment(body)
+        Ast.each_node(body).filter_map do |n|
+          next unless Ast.tagged?(n, :command, :command_call, :method_add_arg)
+
+          inner = Ast.tagged?(n, :method_add_arg) ? n[1] : n
+          name_pair = Ast.call_name(inner)
+          next unless name_pair && ATTACHMENT_METHODS.include?(name_pair[1])
+
+          name = Ast.call_arguments(n).filter_map { |a| Ast.literal_text(a) }.first
+          [n, name] if name
+        end
+      end
+
+      def each_content_type_validated_names(body)
+        Ast.each_node(body).filter_map do |n|
+          next unless Ast.tagged?(n, :command, :command_call, :method_add_arg)
+
+          inner = Ast.tagged?(n, :method_add_arg) ? n[1] : n
+          name_pair = Ast.call_name(inner)
+          next unless name_pair && name_pair[1] == "validates"
+
+          args = Ast.call_arguments(n)
+          next unless Ast.keyword_arg(args, "content_type")
+
+          Ast.literal_text(args.first)
+        end
+      end
+    end
+  end
+end

data/lib/scryer/rules/authentication_bypass_rule.rb

@@ -0,0 +1,95 @@
+module Scryer
+  module Rules
+    # Flags a controller class that calls `skip_before_action`/
+    # `skip_action_callback` naming a common authentication filter
+    # (`authenticate_user!`, `authenticate!`, ...) — same shape and reasoning
+    # as CsrfProtectionRule, just for auth filters instead of CSRF: skipping
+    # one is sometimes correct (a public endpoint, a webhook) but is also a
+    # common way to accidentally leave an action reachable without login,
+    # especially with a broad `except:`/no scoping at all.
+    class AuthenticationBypassRule < Rule
+      self.rule_id = "authentication_bypass"
+      self.category = "security"
+      self.default_severity = "warning"
+      self.title = "Authentication filter explicitly skipped"
+      self.cwe = "CWE-287"
+      self.owasp_category = "A07:2021-Identification and Authentication Failures"
+      self.confidence = "medium"
+
+      SKIP_METHODS = %w[skip_before_action skip_action_callback skip_before_filter].freeze
+      AUTH_FILTER_NAMES = %w[
+        authenticate_user! authenticate! authenticate_admin! authenticate_account!
+        require_login require_authentication authorize_request
+      ].freeze
+
+      def scan
+        findings = []
+
+        Ast.each_node(sexp) do |node|
+          next unless Ast.tagged?(node, :class)
+
+          class_name = Ast.class_name(node[1])
+          next unless class_name.to_s.end_with?("Controller")
+
+          each_skip_call(node[3]).each do |skip_node, filter_name, args|
+            line = Ast.line_of(skip_node)
+            # A skip already scoped with `only: [...]` is the exact mitigation this
+            # rule's own suggested_fix recommends (see below) — that's the common,
+            # often entirely legitimate "public read-only actions on an otherwise
+            # authenticated controller" pattern (an index/show page, a webhook
+            # receiver), not evidence of a mistake. We still surface it (whether
+            # each named action is *actually* meant to be public is app-specific
+            # judgment this per-file rule can't verify), but the wording shouldn't
+            # read as "this is wrong" the way the unscoped/`except:` case does.
+            scoped = !Ast.keyword_arg(args, "only").nil?
+            message =
+              if scoped
+                "`#{class_name}` skips the `#{filter_name}` authentication filter, scoped with " \
+                  "`only:` (`#{skip_call_method(skip_node)} :#{filter_name}`) — this is a common, " \
+                  "often legitimate pattern for public-facing read actions (an index/show page, a " \
+                  "webhook) on an otherwise authenticated controller. Worth a quick human check " \
+                  "that every named action is genuinely meant to be public, not a signal that " \
+                  "this is a bug on its own."
+              else
+                "`#{class_name}` skips the `#{filter_name}` authentication filter " \
+                  "(`#{skip_call_method(skip_node)} :#{filter_name}`) with no `only:` scoping — " \
+                  "every action this applies to is reachable without logging in unless something " \
+                  "else in this controller re-checks authentication."
+              end
+            findings << finding(
+              line: line,
+              message: message,
+              suggested_fix: "If this is genuinely a public action (a webhook, a login/signup " \
+                              "page), scope the skip tightly with `only: [:action_name]` rather " \
+                              "than leaving it unscoped or using a broad `except:`. If it's not " \
+                              "meant to be public, remove the skip."
+            )
+          end
+        end
+
+        findings
+      end
+
+      private
+
+      def each_skip_call(body)
+        Ast.each_node(body).filter_map do |n|
+          next unless Ast.tagged?(n, :method_add_arg, :command, :command_call)
+
+          inner = Ast.tagged?(n, :method_add_arg) ? n[1] : n
+          name_pair = Ast.call_name(inner)
+          next unless name_pair && SKIP_METHODS.include?(name_pair[1])
+
+          args = Ast.call_arguments(n)
+          filter_name = args.filter_map { |a| Ast.literal_text(a) }.find { |v| AUTH_FILTER_NAMES.include?(v) }
+          [n, filter_name, args] if filter_name
+        end
+      end
+
+      def skip_call_method(node)
+        inner = Ast.tagged?(node, :method_add_arg) ? node[1] : node
+        Ast.call_name(inner)&.last
+      end
+    end
+  end
+end

data/lib/scryer/rules/command_injection_rule.rb

@@ -9,6 +9,9 @@ module Scryer
       self.category = "security"
       self.default_severity = "critical"
       self.title = "Possible command injection via shell call"
+      self.cwe = "CWE-78"
+      self.owasp_category = "A03:2021-Injection"
+      self.confidence = "high"
 
       SHELL_METHODS = %w[system exec popen spawn].freeze
 

data/lib/scryer/rules/consider_all_requests_local_rule.rb

@@ -0,0 +1,51 @@
+module Scryer
+  module Rules
+    # Flags `config.consider_all_requests_local = true` specifically in
+    # config/environments/production.rb. This setting is Rails' own default
+    # in development.rb and test.rb (it's what shows the full backtrace/
+    # debug page on an unhandled exception instead of a generic error page)
+    # — completely normal there, and NOT flagged there; only an explicit
+    # `true` in the production environment file is a real information-
+    # disclosure risk (stack traces, local variable values, and request
+    # params rendered straight to whoever triggered the error).
+    class ConsiderAllRequestsLocalRule < Rule
+      self.rule_id = "consider_all_requests_local_production"
+      self.category = "security"
+      self.default_severity = "critical"
+      self.title = "Debug error pages enabled in production"
+      self.cwe = "CWE-209"
+      self.owasp_category = "A05:2021-Security Misconfiguration"
+      self.confidence = "high"
+
+      PRODUCTION_ENV_FILE = "config/environments/production.rb"
+
+      def scan
+        return [] unless file.to_s.end_with?(PRODUCTION_ENV_FILE)
+
+        findings = []
+
+        Ast.each_node(sexp) do |node|
+          next unless Ast.tagged?(node, :assign)
+
+          target = node[1]
+          next unless Ast.tagged?(target, :field)
+          next unless Ast.ident_text(target[3]) == "consider_all_requests_local"
+          next unless Ast.true_literal?(node[2])
+
+          findings << finding(
+            line: Ast.line_of(node),
+            message: "`config.consider_all_requests_local = true` in #{PRODUCTION_ENV_FILE} shows " \
+                      "the full Rails debug error page (backtrace, local variables, request " \
+                      "params) to anyone who triggers an unhandled exception in production.",
+            suggested_fix: "Remove this line or set it to `false` in production — let " \
+                            "`config.consider_all_requests_local` stay at Rails' own default " \
+                            "there (only true in development/test) and rely on " \
+                            "`public/500.html` (or an exception-tracking service) for production errors."
+          )
+        end
+
+        findings
+      end
+    end
+  end
+end

data/lib/scryer/rules/cors_misconfiguration_rule.rb

@@ -0,0 +1,100 @@
+module Scryer
+  module Rules
+    # Flags the well-known Rack::Cors antipattern: a wildcard origin
+    # (`origins '*'`) combined with `credentials: true` on a `resource` call.
+    # Per the CORS spec, browsers reject this combination in practice, but
+    # it's still the standard misconfiguration flagged in security reviews —
+    # either half alone (wildcard origin with no credentials, or credentials
+    # with a real origin allowlist) is fine.
+    #
+    # Scoped per `allow do ... end` block (Rack::Cors' own grouping
+    # construct — each `allow` block gets its own `origins`/`resource`
+    # pairing), not file-wide: a common, legitimate pattern is a public,
+    # unauthenticated API in one `allow` block (`origins '*'`, no
+    # credentials) and a separate authenticated partner API in another
+    # `allow` block in the same initializer (a real origin allowlist +
+    # `credentials: true`) — neither block alone is a misconfiguration, but
+    # an earlier file-wide "does '*' appear ANYWHERE AND does credentials:
+    # true appear ANYWHERE" check would flag the second block just because
+    # the first one happens to use a wildcard. Requiring both signals to
+    # come from the same `allow` block's own subtree fixes that without
+    # losing detection of the real antipattern (both signals still just
+    # need to appear somewhere *within* one block, not literally on the same
+    # `resource` call, since `origins` and `resource` are usually sibling
+    # statements in the same block rather than one call).
+    class CorsMisconfigurationRule < Rule
+      self.rule_id = "cors_misconfiguration"
+      self.category = "security"
+      self.default_severity = "critical"
+      self.title = "CORS wildcard origin combined with credentials"
+      self.cwe = "CWE-942"
+      self.owasp_category = "A05:2021-Security Misconfiguration"
+      self.confidence = "high"
+
+      def scan
+        findings = []
+
+        allow_blocks(sexp).each do |block|
+          next unless wildcard_origin_anywhere?(block)
+
+          each_credentialed_resource(block).each do |node|
+            findings << finding(
+              line: Ast.line_of(node),
+              message: "This `allow` block sets a wildcard origin (`origins '*'`) and this " \
+                        "`resource` call sets `credentials: true` — browsers won't honor that " \
+                        "combination for actual credentialed requests, and Rack::Cors handling it " \
+                        "inconsistently is the standard CORS misconfiguration flagged in reviews. " \
+                        "Either restrict origins to a real allowlist, or drop `credentials: true`.",
+              suggested_fix: "Replace the wildcard with an explicit origin allowlist wherever " \
+                              "`credentials: true` is set: `origins 'https://app.example.com'` " \
+                              "instead of `origins '*'` — a wildcard origin should only be paired " \
+                              "with `credentials: false` (the default)."
+            )
+          end
+        end
+
+        findings
+      end
+
+      private
+
+      # Every `allow do ... end` block in the file — Ripper parses it as a
+      # `method_add_block` wrapping an `fcall`/`vcall` named "allow" plus its
+      # `do_block` body. Rack::Cors configs are always structured this way
+      # (`Rack::Cors do allow do ... end end`), so scoping to these blocks
+      # rather than falling back to file-wide when none are found doesn't
+      # lose real detections in practice.
+      def allow_blocks(node)
+        Ast.each_node(node).select do |n|
+          next false unless Ast.tagged?(n, :method_add_block)
+
+          call_node = n[1]
+          inner = Ast.tagged?(call_node, :method_add_arg) ? call_node[1] : call_node
+          Ast.call_name(inner)&.last == "allow"
+        end
+      end
+
+      def wildcard_origin_anywhere?(node)
+        Ast.each_node(node).any? do |n|
+          next false unless Ast.tagged?(n, :method_add_arg, :command, :command_call)
+
+          inner = Ast.tagged?(n, :method_add_arg) ? n[1] : n
+          next false unless Ast.call_name(inner)&.last == "origins"
+
+          Ast.call_arguments(n).any? { |a| Ast.plain_string_value(a) == "*" }
+        end
+      end
+
+      def each_credentialed_resource(node)
+        Ast.each_node(node).select do |n|
+          next false unless Ast.tagged?(n, :method_add_arg, :command, :command_call)
+
+          inner = Ast.tagged?(n, :method_add_arg) ? n[1] : n
+          next false unless Ast.call_name(inner)&.last == "resource"
+
+          Ast.true_literal?(Ast.keyword_arg(Ast.call_arguments(n), "credentials"))
+        end
+      end
+    end
+  end
+end

data/lib/scryer/rules/csrf_protection_rule.rb

@@ -12,6 +12,9 @@ module Scryer
       self.category = "security"
       self.default_severity = "warning"
       self.title = "CSRF protection skipped without safeguards"
+      self.cwe = "CWE-352"
+      self.owasp_category = "A01:2021-Broken Access Control"
+      self.confidence = "medium"
 
       def scan
         findings = []
@@ -19,7 +22,7 @@ module Scryer
         Ast.each_node(sexp) do |node|
           next unless Ast.tagged?(node, :class)
 
-          class_name = Ast.ident_text(node[1].is_a?(Array) ? node[1][1] : nil)
+          class_name = Ast.class_name(node[1])
           next unless class_name.to_s.end_with?("Controller")
 
           body = node[3]
@@ -34,16 +37,9 @@ module Scryer
           line = Ast.line_of(skip_node)
           findings << finding(
             line: line,
-            message: "`#{class_name}` skips CSRF token verification (`skip_before_action " \
-                      ":verify_authenticity_token`) without declaring its own " \
-                      "`protect_from_forgery` policy — if this controller renders any HTML forms " \
-                      "or is reachable with a browser session cookie, this leaves it open to " \
-                      "cross-site request forgery.",
-            suggested_fix: "If this is a true JSON/API-only controller, make that explicit with " \
-                            "`protect_from_forgery with: :null_session` (or inherit from a base " \
-                            "class that does) rather than bypassing verification silently. If it's " \
-                            "not API-only, remove the `skip_before_action` and let the app's normal " \
-                            "CSRF handling apply."
+            severity: scoped_to_specific_actions?(skip_node) ? "info" : self.class.default_severity,
+            message: scoped_message(class_name, skip_node),
+            suggested_fix: scoped_suggested_fix(skip_node)
           )
         end
 
@@ -52,6 +48,59 @@ module Scryer
 
       private
 
+      # `skip_before_action :verify_authenticity_token, only: [:webhook]` —
+      # narrowed with an `only:` list to specific actions — is a very common,
+      # often entirely legitimate pattern: external callback endpoints
+      # (Stripe/PayPal/other payment or webhook providers) can't carry a
+      # session-cookie CSRF token because the request never originates from
+      # a browser on this site, so verify_authenticity_token would just
+      # reject every legitimate call. That's a materially different, lower
+      # risk shape than skipping it for the *whole* controller (no `only:`
+      # at all), which is the actual dangerous case this rule targets (e.g.
+      # a controller that also renders normal HTML forms). We still report
+      # the `only:`-scoped case — skipping CSRF is still worth a second look
+      # to confirm the endpoint verifies the caller some other way (a
+      # provider signature header, a shared secret) rather than not at
+      # all — just at "info" severity with wording that doesn't read as
+      # "this is unconditionally wrong," instead of the same "warning" we
+      # give an unscoped, controller-wide skip.
+      def scoped_to_specific_actions?(skip_node)
+        args = Ast.call_arguments(skip_node)
+        !Ast.keyword_arg(args, "only").nil?
+      end
+
+      def scoped_message(class_name, skip_node)
+        if scoped_to_specific_actions?(skip_node)
+          "`#{class_name}` skips CSRF token verification (`skip_before_action " \
+            ":verify_authenticity_token`) scoped to specific actions via `only:` — a common, " \
+            "often legitimate pattern for endpoints that can't carry a browser session token " \
+            "(e.g. external webhook callbacks from a payment provider). Worth double-checking " \
+            "those actions verify the caller some other way (a provider signature header, a " \
+            "shared secret) rather than skipping verification with nothing in its place."
+        else
+          "`#{class_name}` skips CSRF token verification (`skip_before_action " \
+            ":verify_authenticity_token`) without declaring its own " \
+            "`protect_from_forgery` policy — if this controller renders any HTML forms " \
+            "or is reachable with a browser session cookie, this leaves it open to " \
+            "cross-site request forgery."
+        end
+      end
+
+      def scoped_suggested_fix(skip_node)
+        if scoped_to_specific_actions?(skip_node)
+          "If the scoped action(s) are external provider callbacks, verify the request some " \
+            "other way instead of CSRF (e.g. `Stripe::Webhook.construct_event` and its signature " \
+            "check, or comparing a shared secret/header the provider sends). If they're not " \
+            "callback endpoints, reconsider whether skipping CSRF here is actually needed."
+        else
+          "If this is a true JSON/API-only controller, make that explicit with " \
+            "`protect_from_forgery with: :null_session` (or inherit from a base " \
+            "class that does) rather than bypassing verification silently. If it's " \
+            "not API-only, remove the `skip_before_action` and let the app's normal " \
+            "CSRF handling apply."
+        end
+      end
+
       def find_skip_verify(node)
         Ast.each_node(node).find do |n|
           next false unless Ast.tagged?(n, :method_add_arg, :command, :command_call)