scryer 0.1.0

data/lib/scryer/scanner.rb

@@ -0,0 +1,129 @@
+require "ripper"
+require "set"
+
+module Scryer
+  # Ties parsing + rules + duplicate detection together across a directory
+  # tree. This is the one entry point both the `sentinel:scan` rake task and
+  # any generator/CLI should call — everything else in this gem is a building
+  # block this class composes.
+  class Scanner
+    DEFAULT_GLOB_DIRS = %w[app lib config db].freeze
+    SKIP_DIR_SEGMENTS = %w[vendor node_modules tmp log .git spec test].freeze
+
+    # Duplicate-code detection only makes sense within hand-written business
+    # logic. Migrations in particular are mostly boilerplate (create_table /
+    # t.string / t.integer calls) that normalize to near-identical token
+    # streams and drown out real duplicates with false positives — so unlike
+    # the security/performance rules (which still scan every file under
+    # DEFAULT_GLOB_DIRS), duplicate detection is restricted to models,
+    # controllers, helpers, and concerns (wherever they're nested).
+    DUPLICATE_DETECTION_APP_SUBDIRS = %w[models controllers helpers].freeze
+
+    # Query and cache-value duplicates use a slightly higher bar than whole
+    # methods: they're much shorter fragments, so a coincidental match at the
+    # method threshold (0.6) is more likely — see DuplicateDetector's shingle
+    # comment for why short token streams are more sensitive to this.
+    QUERY_SIMILARITY_THRESHOLD = 0.7
+    CACHE_SIMILARITY_THRESHOLD = 0.7
+
+    Result = Struct.new(:security_findings, :performance_findings, :duplicate_groups, :files_scanned, :parse_errors, keyword_init: true)
+
+    # `skip_rules` silences specific checks by rule_id (e.g. a known false
+    # positive on this codebase) without editing/removing the rule itself —
+    # accepts strings or symbols, matched against Rule.rule_id.
+    def initialize(root:, dirs: DEFAULT_GLOB_DIRS, skip_rules: [])
+      @root = File.expand_path(root)
+      @dirs = dirs
+      @skip_rules = Set.new(skip_rules.map(&:to_s))
+    end
+
+    def call
+      files = collect_files
+      all_methods = []
+      all_queries = []
+      all_cache_calls = []
+      security_findings = []
+      performance_findings = []
+      parse_errors = []
+
+      files.each do |abs_path|
+        rel_path = abs_path.sub(/\A#{Regexp.escape(@root)}\/?/, "")
+        source = File.read(abs_path)
+
+        sexp = begin
+          Ripper.sexp(source)
+        rescue StandardError => e
+          parse_errors << { file: rel_path, error: e.message }
+          nil
+        end
+
+        if sexp.nil?
+          parse_errors << { file: rel_path, error: "Ripper could not parse this file (possibly a syntax error, or Ruby syntax newer than this gem's Ruby runtime supports)" } unless parse_errors.any? { |pe| pe[:file] == rel_path }
+          next
+        end
+
+        RuleSet.all.each do |rule_class|
+          next if @skip_rules.include?(rule_class.rule_id.to_s)
+
+          bucket =
+            case rule_class.category
+            when "security" then security_findings
+            when "performance" then performance_findings
+            end
+          next unless bucket
+
+          bucket.concat(rule_class.new(file: rel_path, source: source, sexp: sexp).scan)
+        end
+
+        if duplicate_detection_target?(rel_path)
+          all_methods.concat(MethodExtractor.extract(file: rel_path, source: source, sexp: sexp))
+          all_queries.concat(QueryExtractor.extract(file: rel_path, source: source, sexp: sexp))
+          all_cache_calls.concat(CacheExtractor.extract(file: rel_path, source: source, sexp: sexp))
+        end
+      end
+
+      # Same computed value cached under the same key from multiple call
+      # sites is normal (just reusing the cache). Only flag it when the
+      # *keys* differ too — that's either a redundant cache entry or a key
+      # that drifted out of sync with a copy-pasted sibling.
+      cache_groups = DuplicateDetector.call(all_cache_calls, threshold: CACHE_SIMILARITY_THRESHOLD, kind: "cache_duplicate")
+                                       .select { |g| g.members.map(&:cache_key).uniq.size > 1 }
+
+      duplicate_groups =
+        DuplicateDetector.call(all_methods, kind: "method_duplicate") +
+        DuplicateDetector.call(all_queries, threshold: QUERY_SIMILARITY_THRESHOLD, kind: "query_duplicate") +
+        cache_groups
+
+      Result.new(
+        security_findings: security_findings,
+        performance_findings: performance_findings,
+        duplicate_groups: duplicate_groups,
+        files_scanned: files.size,
+        parse_errors: parse_errors
+      )
+    end
+
+    private
+
+    def duplicate_detection_target?(relative_path)
+      segments = relative_path.split("/")
+      return true if segments.include?("concerns")
+
+      segments[0] == "app" && DUPLICATE_DETECTION_APP_SUBDIRS.include?(segments[1])
+    end
+
+    def collect_files
+      @dirs.flat_map { |dir| Dir.glob(File.join(@root, dir, "**", "*.rb")) }
+           .reject do |path|
+             # Only check segments of the path *relative to @root* — checking
+             # the full absolute path would wrongly exclude a project simply
+             # because some ancestor directory outside the project happens to
+             # be named e.g. "tmp" or "test".
+             relative = path.sub(/\A#{Regexp.escape(@root)}\/?/, "")
+             SKIP_DIR_SEGMENTS.any? { |seg| relative.split("/").include?(seg) }
+           end
+           .sort
+           .uniq
+    end
+  end
+end

data/lib/scryer/version.rb

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

data/lib/scryer.rb

@@ -0,0 +1,65 @@
+require "scryer/version"
+require "scryer/ast"
+require "scryer/finding"
+require "scryer/rule_set"
+require "scryer/rule"
+require "scryer/method_extractor"
+require "scryer/query_extractor"
+require "scryer/cache_extractor"
+require "scryer/duplicate_detector"
+require "scryer/scanner"
+require "scryer/report_renderer"
+require "scryer/dependency_audit"
+require "scryer/ai_client"
+require "scryer/ai_fix_suggester"
+
+Dir[File.join(__dir__, "scryer", "rules", "*.rb")].sort.each { |f| require f }
+Dir[File.join(__dir__, "scryer", "performance_rules", "*.rb")].sort.each { |f| require f }
+
+module Scryer
+  class Configuration
+    # `branch`, when set, overrides the git_branch value recorded in the
+    # report (instead of the actual checked-out branch from `git rev-parse
+    # --abbrev-ref HEAD`) — set this when the branch you want tracked isn't
+    # necessarily the one the scan happens to run on (e.g. a CI runner in
+    # detached-HEAD state, or you always want releases attributed to "main").
+    #
+    # `ai_client`, when set, opts into rewriting every finding's
+    # `suggested_fix` via an LLM (see README's "AI-assisted fix
+    # suggestions") — any object or Proc responding to #call(prompt) (or
+    # #complete(prompt)). nil by default: off, no network calls, no
+    # provider assumed.
+    #
+    # `skip_rules` silences specific checks by rule_id (e.g. a known false
+    # positive on this codebase) without editing/removing the rule itself —
+    # strings or symbols, matched against each Rule's rule_id. Empty by
+    # default: every registered rule runs. The `scryer` executable's
+    # `--skip RULE_ID` flag adds to this list for a single run rather than
+    # replacing it.
+    attr_accessor :project_name, :dirs, :branch, :ai_client, :skip_rules
+
+    def initialize
+      @dirs = Scryer::Scanner::DEFAULT_GLOB_DIRS
+      @skip_rules = []
+    end
+  end
+
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+end
+
+# QueryWatcher instruments a *running* app (ActiveRecord query notifications,
+# association reader hooks) rather than the one-shot static scan the rest of
+# this file wires up, and is opt-in (Scryer::QueryWatcher.enable!) — so it
+# isn't required eagerly here to avoid loading active_support/notifications
+# machinery for the (default) case where nobody asked for it. Require it
+# yourself where you call .enable! (see README's "Runtime query watcher").
+
+require "scryer/railtie" if defined?(Rails::Railtie)

data/lib/tasks/scryer.rake

@@ -0,0 +1,172 @@
+require "json"
+require "fileutils"
+
+# Deliberately does NOT depend on the Rails `:environment` task — the
+# scanning engine itself needs no Rails/bundler to run, so this task works
+# equally via `bin/rails scryer:report` inside a Rails app or plain
+# `bundle exec rake -f <this file> scryer:report` outside one. Avoids
+# ActiveSupport methods (`.presence`/`.blank?`) for the same reason — plain
+# Ruby nil-or-empty checks only.
+namespace :scryer do
+  desc "Run Scryer and write a report. Args are any mix of json/html/csv (which formats " \
+       "to write — default json,html), the token 'deps' (fold a dependency audit — OSV.dev " \
+       "vulnerable gems + insecure git/http sources, same checks as scryer:audit_dependencies " \
+       "— into this report instead of running it separately), plus at most one path (a " \
+       "directory when writing more than one format, or an exact file for a single format). " \
+       "Rake splits bracket args on every comma, so pass each token as its own item rather " \
+       "than one comma-joined string. e.g. rails scryer:report, rails 'scryer:report[html]', " \
+       "rails 'scryer:report[json,doc/security.json]', rails 'scryer:report[json,html]', " \
+       "rails 'scryer:report[html,deps]', rails 'scryer:report[csv]'"
+  task :report, [:format] do |_, args|
+    root = defined?(Rails) ? Rails.root.to_s : Dir.pwd
+    dirs = Scryer.configuration.dirs
+
+    # Ignore the declared :format name and read every positional value Rake
+    # was given (args.to_a) — the whole point is accepting a variable number
+    # of format/deps tokens plus one path, which a single named param can't do.
+    formats, path_arg, include_deps = parse_report_args(args.to_a)
+
+    skip_rules = Scryer.configuration.skip_rules
+    puts "Scryer: skipping #{skip_rules.join(', ')}." if skip_rules.any?
+
+    result = Scryer::Scanner.new(root: root, dirs: dirs, skip_rules: skip_rules).call
+
+    dependency_findings = []
+    if include_deps
+      puts "Scryer: checking Gemfile.lock sources (offline)..."
+      puts "Scryer: querying OSV.dev for known vulnerabilities (needs network)..."
+      dependency_findings = Scryer::DependencyAudit.insecure_sources(root) + Scryer::DependencyAudit.vulnerable_gems(root)
+    end
+
+    if Scryer.configuration.ai_client
+      puts "Scryer: rewriting suggested fixes via the configured AI client..."
+      Scryer::AiFixSuggester.enhance_result!(result)
+      Scryer::AiFixSuggester.enhance_many!(dependency_findings) unless dependency_findings.empty?
+    end
+
+    renderer = Scryer::ReportRenderer.new(
+      result: result,
+      project_name: blank_to_nil(Scryer.configuration.project_name) || File.basename(root),
+      release_label: ScryerTasks.git_release_label,
+      git_commit_sha: ScryerTasks.git_commit_sha,
+      git_branch: blank_to_nil(Scryer.configuration.branch) || ScryerTasks.git_branch,
+      dependency_findings: dependency_findings
+    )
+
+    paths = output_paths(root: root, formats: formats, path_arg: path_arg)
+
+    paths.each do |format, path|
+      FileUtils.mkdir_p(File.dirname(path))
+      content = case format
+                when "json" then renderer.as_json
+                when "csv" then renderer.as_csv
+                else renderer.as_html
+                end
+      File.write(path, content)
+    end
+
+    puts "Scryer: #{result.files_scanned} files scanned, " \
+         "#{result.security_findings.size} security findings, " \
+         "#{result.performance_findings.size} performance findings, " \
+         "#{result.duplicate_groups.size} duplicate groups" \
+         "#{include_deps ? ", #{dependency_findings.size} dependency findings" : ""}."
+    puts "Report written to #{paths.values.join(', ')}"
+  end
+
+  desc "Check Gemfile.lock for known-vulnerable gem versions (via OSV.dev — needs network) " \
+       "and insecure git/http gem sources (offline). Exits non-zero if anything is found, so " \
+       "this can gate CI the same way `bundle-audit check` does."
+  task :audit_dependencies do
+    root = defined?(Rails) ? Rails.root.to_s : Dir.pwd
+
+    puts "Scryer: checking Gemfile.lock sources (offline)..."
+    insecure = Scryer::DependencyAudit.insecure_sources(root)
+
+    puts "Scryer: querying OSV.dev for known vulnerabilities (needs network)..."
+    vulnerable = Scryer::DependencyAudit.vulnerable_gems(root)
+
+    (insecure + vulnerable).each do |f|
+      label = f.kind == "insecure_source" ? "[#{f.severity.upcase}] #{f.message}" : "[#{f.severity.upcase}] #{f.gem_name} #{f.installed_version} - #{f.advisory_id}: #{f.title}"
+      puts label
+      puts "  fix: #{f.suggested_fix}"
+    end
+
+    total = insecure.size + vulnerable.size
+    puts "\nScryer: #{total} dependency finding(s) (#{insecure.size} insecure source, #{vulnerable.size} vulnerable gem)."
+    abort("Scryer: dependency audit failed.") if total.positive?
+  end
+
+  VALID_FORMATS = %w[json html csv].freeze
+  EXTENSION_FOR_FORMAT = { "json" => "json", "html" => "html", "csv" => "csv" }.freeze
+  DEPS_TOKEN = "deps".freeze
+
+  # tokens is every bracket arg Rake was given, e.g. %w[json doc/security.json] or
+  # %w[json html] or %w[html deps] or []. Returns [formats, path_arg,
+  # include_deps] — any token matching a known format is a format, the
+  # literal "deps" token opts into folding a dependency audit into the
+  # report, and at most one other token is allowed, which is the path.
+  def parse_report_args(tokens)
+    tokens = tokens.map { |t| blank_to_nil(t) }.compact
+    include_deps = tokens.any? { |t| t.downcase == DEPS_TOKEN }
+    tokens = tokens.reject { |t| t.downcase == DEPS_TOKEN }
+
+    format_tokens, other_tokens = tokens.partition { |t| VALID_FORMATS.include?(t.downcase) }
+
+    if other_tokens.size > 1
+      abort "Scryer: only one path is allowed — got #{other_tokens.join(', ')}."
+    end
+
+    formats = format_tokens.map(&:downcase).uniq
+    formats = %w[json html] if formats.empty?
+
+    [formats, other_tokens.first, include_deps]
+  end
+
+  # No path given: default filenames under tmp/. A path given with a single
+  # format whose extension matches that format is treated as an exact file
+  # target; otherwise the path is treated as a directory (created if needed)
+  # and each format gets its default filename inside it.
+  def output_paths(root:, formats:, path_arg:)
+    default_names = formats.each_with_object({}) { |f, h| h[f] = "scryer_report.#{EXTENSION_FOR_FORMAT[f]}" }
+    return default_names.transform_values { |name| File.join(root, "tmp", name) } if path_arg.nil?
+
+    resolved = File.absolute_path?(path_arg) ? path_arg : File.join(root, path_arg)
+    ext = File.extname(resolved).delete_prefix(".").downcase
+
+    if formats.size == 1 && ext == formats.first
+      { formats.first => resolved }
+    else
+      formats.each_with_object({}) { |f, h| h[f] = File.join(resolved, default_names[f]) }
+    end
+  end
+
+  def blank_to_nil(value)
+    return nil if value.nil?
+
+    str = value.to_s.strip
+    str.empty? ? nil : str
+  end
+end
+
+module ScryerTasks
+  module_function
+
+  def git_commit_sha
+    shell_out("git rev-parse HEAD")
+  end
+
+  def git_branch
+    shell_out("git rev-parse --abbrev-ref HEAD")
+  end
+
+  def git_release_label
+    shell_out("git describe --tags --always")
+  end
+
+  def shell_out(cmd)
+    output = `#{cmd} 2>/dev/null`.strip
+    output.empty? ? nil : output
+  rescue StandardError
+    nil
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: scryer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ram Laxman Yadav
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-08-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  Scans a Rails app's own source with Ruby's stdlib Ripper parser (no Rails/bundler needed to
+  run the scan itself) and reports: security findings (SQL injection, mass assignment, command
+  injection, hardcoded secrets, unsafe deserialization, XSS-prone unescaped HTML, CSRF gaps,
+  weak crypto, open redirects), near-duplicate code (token-normalized similarity across
+  methods), and performance heuristics (N+1 queries, missing pagination, inefficient per-record
+  save loops, unbounded full-table iteration). Every finding includes a human-reviewable
+  suggested fix — nothing is auto-applied. Writes a detailed report as JSON and/or
+  self-contained HTML (tmp/scryer_report.{json,html}). Ships a `scryer` executable for
+  running outside a Rails app too, e.g. `scryer -o report.json -o report.html`. Also includes a
+  runtime query watcher (N+1 / unused-eager-load detection via ActiveRecord instrumentation,
+  opt-in) and a dependency vulnerability + insecure-source audit against OSV.dev.
+email:
+executables:
+- scryer
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- exe/scryer
+- lib/generators/scryer/USAGE
+- lib/generators/scryer/install_generator.rb
+- lib/generators/scryer/templates/scryer_initializer.rb
+- lib/scryer.rb
+- lib/scryer/ai_client.rb
+- lib/scryer/ai_fix_suggester.rb
+- lib/scryer/ast.rb
+- lib/scryer/cache_extractor.rb
+- lib/scryer/cli.rb
+- lib/scryer/dependency_audit.rb
+- lib/scryer/duplicate_detector.rb
+- lib/scryer/finding.rb
+- lib/scryer/method_extractor.rb
+- lib/scryer/performance_rules/inefficient_save_loop_rule.rb
+- lib/scryer/performance_rules/missing_pagination_rule.rb
+- lib/scryer/performance_rules/n_plus_one_query_rule.rb
+- lib/scryer/performance_rules/unbounded_table_scan_rule.rb
+- lib/scryer/query_extractor.rb
+- lib/scryer/query_watcher.rb
+- lib/scryer/railtie.rb
+- lib/scryer/report_renderer.rb
+- lib/scryer/rule.rb
+- lib/scryer/rule_set.rb
+- lib/scryer/rules/command_injection_rule.rb
+- lib/scryer/rules/csrf_protection_rule.rb
+- lib/scryer/rules/hardcoded_secret_rule.rb
+- lib/scryer/rules/mass_assignment_rule.rb
+- lib/scryer/rules/open_redirect_rule.rb
+- lib/scryer/rules/sql_injection_rule.rb
+- lib/scryer/rules/unsafe_deserialization_rule.rb
+- lib/scryer/rules/weak_crypto_rule.rb
+- lib/scryer/rules/xss_unsafe_html_rule.rb
+- lib/scryer/scanner.rb
+- lib/scryer/version.rb
+- lib/tasks/scryer.rake
+homepage: https://github.com/ramlaxmanyadav/scryer
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: 'Static code analysis for Rails apps: security vulnerabilities, duplicate
+  code, and performance heuristics.'
+test_files: []