scryer 1.0.0 → 1.2.0

data/docs/rules.md

@@ -0,0 +1,310 @@
+# What Scryer Detects
+
+[← Back to Scryer — Ruby on Rails Security Auditor](../README.md)
+
+## What Scryer detects
+
+**Security**
+
+* SQL injection
+* Mass assignment
+* Command injection
+* Hardcoded secrets (and hardcoded HTTP Basic Auth credentials)
+* Unsafe deserialization
+* XSS-prone HTML
+* CSRF gaps
+* Weak cryptography
+* Open redirects
+* Server-side request forgery (SSRF)
+* Path traversal
+* Insecure direct object references (IDOR) — the least precise check in the gem; see
+  [comparison table](./architecture.md#scryer-vs-rubocop-vs-brakeman-vs-bundler-audit) for the false-positive tradeoff.
+  Correctly examines namespaced controllers too (`Admin::PostsController`,
+  `Api::V1::UsersController`) — an earlier version silently skipped any namespaced class here
+* A `create`/`update`/`destroy` action with no authorization check anywhere in its controller
+  (broader than IDOR — catches write actions that don't call `.find` at all)
+* A Pundit-using controller's `index` action querying a model directly instead of through
+  `policy_scope` (the common "remembered `authorize`, forgot `policy_scope`" gotcha)
+* Authentication filters explicitly skipped (`skip_before_action`) — also correctly examines
+  namespaced controllers, same fix as IDOR above
+* Rails security configuration: disabled HTTPS enforcement, session cookies missing the secure
+  flag, the Marshal cookie serializer, disabled default security headers (`X-Frame-Options`,
+  `X-Content-Type-Options`, Content-Security-Policy), Action Cable request forgery protection
+  disabled, a hardcoded `secret_key_base`
+* Active Storage attachments without a content-type allowlist, or served with inline disposition
+* CORS misconfiguration (wildcard origin combined with `credentials: true`)
+* Insecure JWT usage (`JWT.decode` with signature verification disabled, `algorithm: 'none'`, or a
+  hardcoded secret)
+* Background jobs (`perform_async`/`perform_later`/`perform_now`) passed raw `params` — risks
+  leaking request data into Sidekiq/ActiveJob logs, Redis, or the Sidekiq web UI
+* GraphQL schemas with no query depth/complexity limit (`max_depth`/`max_complexity`)
+* Rails config audit: `config.consider_all_requests_local = true` left on in
+  `config/environments/production.rb` (shows full debug error pages — backtrace, local variables,
+  request params — to anyone who triggers an exception), `config.log_level = :debug` in production
+  (logs full request params and SQL bind values), `config.hosts.clear` (disables the Host-header
+  allowlist that protects against DNS-rebinding/Host-header-injection). All three are Rails
+  defaults in development/test where they're completely normal — only flagged where they're
+  actually risky.
+
+Every security finding also carries a **CWE ID**, an **OWASP Top 10 (2021) category**, and a
+**confidence level** (`high`/`medium`/`low`) — all three appear in every report format (JSON, CSV,
+HTML, SARIF) and in the OWASP Top 10 coverage scorecard (console summary + a dedicated HTML
+section). Two things worth being precise about:
+
+- **Confidence is a different axis from severity.** Severity is "how bad is this if real";
+  confidence is "how often does this specific rule's pattern-match actually reflect a real issue."
+  `idor` is a good example of the split: a real IDOR is serious (`warning` severity, arguably
+  understating it), but the rule's own heuristic — no visible authorization call anywhere in the
+  controller class — is the least precise in the gem, so it's tagged `low` confidence. Most rules
+  are `medium`; the narrowest, most literal-match rules (a hardcoded string literal, an explicit
+  `= false` config assignment) are `high`.
+- **The CWE/OWASP mapping is Scryer's own best-effort categorization**, chosen for practitioner
+  convenience (a quick answer to "does our tooling cover OWASP category X" in a compliance
+  conversation) — it is not an OWASP-endorsed mapping and hasn't been independently audited. A
+  handful of the 31 assignments involved a real judgment call where a rule's issue doesn't map
+  cleanly onto exactly one OWASP category (e.g. `job_raw_params`, which is as much a data-exposure
+  concern as a logging one). Treat it as a useful pointer, not a certification.
+
+**Code quality**
+
+* Near-duplicate code
+* Repeated logic
+* Potentially problematic code patterns
+* Missing `frozen_string_literal` magic comment (the one deliberate, narrow style check — see
+  [comparison table](./architecture.md#scryer-vs-rubocop-vs-brakeman-vs-bundler-audit) for why not more)
+
+**Performance**
+
+* N+1 queries
+* Missing pagination
+* Inefficient per-record saves
+* Unbounded full-table iteration
+
+**Dependencies**
+
+* Known dependency vulnerabilities via OSV.dev
+* Insecure gem sources
+* Ruby version end-of-life (no more security patches published for it, for any issue)
+* `config/master.key` present on disk with no matching `.gitignore` entry
+
+**Runtime** (opt-in, needs a running app — see [Runtime query watcher](./rails-integration.md#runtime-query-watcher) and
+[Runtime authorization watcher](./rails-integration.md#runtime-authorization-watcher))
+
+* N+1 queries and unused eager loading, as they actually happen
+* A write action that completed with no Pundit/CanCanCan authorization check actually invoked
+  during that request — a live, false-positive-resistant companion to the static `idor`/
+  `missing_authorization`/`missing_policy_scope` rules above
+
+## Example findings
+
+Real output — three lines of deliberately flawed Rails code, scanned with plain `scryer`:
+
+```ruby
+def create
+  @invoice = Invoice.create(params[:invoice])
+end
+```
+
+```
+[CRITICAL] mass_assignment — app/controllers/invoices_controller.rb:3
+`create` receives `params` (or a subscript of it) directly, with no `.permit(...)` call — every
+attribute in the request can be set, including ones the form/API was never meant to expose (e.g.
+`admin`, `role_id`).
+
+fix: Wrap the params in a strong-parameters method, e.g. `create(order_params)` with
+`def order_params; params.require(:order).permit(:status, :total); end` — only the explicitly
+permitted keys get through.
+```
+
+```ruby
+Invoice.where("customer_name = '#{name}'")
+```
+
+```
+[CRITICAL] sql_injection — app/controllers/invoices_controller.rb:9
+`where` is called with a string built via interpolation, which lets user-controlled input change
+the SQL executed.
+
+fix: Use a parameterized form instead, e.g. `where("column = ?", value)` or the hash form
+`where(column: value)` — both let Active Record escape the value safely instead of interpolating
+it directly into SQL.
+```
+
+```ruby
+@invoices = Invoice.where(status: "open")
+@invoices.each { |invoice| invoice.account.name }
+```
+
+```
+[WARNING] n_plus_one_query — app/controllers/invoices_controller.rb:14
+`invoice.account` is called inside a loop — if `account` is an association, this issues a separate
+query per iteration instead of one batched query (a classic N+1).
+
+fix: Eager-load the association on the base query before the loop, e.g.
+`invoices = Model.includes(:account).where(...)` (or add `:account` to an existing `.includes(...)`
+call), so Rails fetches it in one extra query instead of one per record.
+```
+
+Every finding follows this shape, whichever category it's in: exactly where the issue is, why it
+matters, and a fix written against your actual code — not a generic paragraph you have to
+translate into your own file.
+
+## Reports
+
+Generate detailed JSON or self-contained HTML reports:
+
+```bash
+scryer -o report.json -o report.html
+```
+
+The HTML report leads with a [security score](./architecture.md#security-score) badge and a severity distribution
+chart, then Overview/Summary/OWASP coverage, collapsed-by-default reference tables (every rule
+that *can* fire, not a wall of always-expanded detail), and the Findings section itself — Top
+priorities first, then a text filter box (rule/file/message, no page reload) above the full
+severity-grouped, accordion-collapsed list. Each finding also shows its CWE ID, OWASP category, and
+confidence level as small tags; clicking a count in the OWASP coverage table jumps to Findings with
+that exact category pre-filled into the search box, so "how many `A01` findings are there" and
+"which ones, specifically" are one click apart instead of two different views.
+
+#### JSON output
+
+`report.json`'s `security_findings`/`performance_findings`/`style_findings`/`dependency_findings`
+arrays are plain objects (`Scryer::Finding#to_h`) — one real entry, unedited:
+
+```json
+{
+  "rule_id": "mass_assignment",
+  "category": "security",
+  "severity": "critical",
+  "confidence": "medium",
+  "cwe": "CWE-915",
+  "owasp_category": "A08:2021-Software and Data Integrity Failures",
+  "file": "app/controllers/orders_controller.rb",
+  "line": 3,
+  "code_snippet": "Order.new(params[:order])",
+  "message": "`new` receives `params` (or a subscript of it) directly, with no `.permit(...)` call — every attribute in the request can be set, including ones the form/API was never meant to expose (e.g. `admin`, `role_id`).",
+  "suggested_fix": "Wrap the params in a strong-parameters method, e.g. `new(order_params)` with `def order_params; params.require(:order).permit(:status, :total); end` — only the explicitly permitted keys get through.",
+  "fix_verified": null
+}
+```
+
+`fix_verified` is `null` unless an [`ai_client`](./fix-mode.md#ai-assisted-fix-suggestions) is configured (then
+`true`/`false`/`null` — see [Verifying a fix](./fix-mode.md#verifying-a-fix) for what each means).
+
+#### SARIF output
+
+`report.sarif` (SARIF 2.1.0) maps the same finding into a `results[]` entry GitHub Code Scanning
+and similar dashboards understand natively:
+
+```json
+{
+  "ruleId": "mass_assignment",
+  "level": "error",
+  "rank": 75,
+  "message": { "text": "`new` receives `params` (or a subscript of it) directly, with no `.permit(...)` call — every attribute in the request can be set, including ones the form/API was never meant to expose (e.g. `admin`, `role_id`)." },
+  "locations": [{ "physicalLocation": { "artifactLocation": { "uri": "app/controllers/orders_controller.rb" }, "region": { "startLine": 3 } } }],
+  "properties": { "confidence": "medium", "cwe": "CWE-915", "owasp_category": "A08:2021-Software and Data Integrity Failures" }
+}
+```
+
+`level` follows severity (`critical`→`error`, `warning`→`warning`, `info`→`note`); `rank` combines
+severity and confidence into one prioritization number for dashboards that sort on it. See
+[CI/CD integration](./usage.md#cicd-integration) for wiring this into `github/codeql-action/upload-sarif`.
+
+## Developer-friendly suggestions
+
+Every finding includes a human-reviewable suggested fix. Scryer never automatically modifies your source code.
+
+## Runtime analysis
+
+Scryer can optionally monitor ActiveRecord queries at runtime to detect N+1 queries and unused eager loading.
+
+## Designed for Ruby
+
+Scryer uses Ruby's standard-library `Ripper` parser, allowing source analysis without requiring Rails or Bundler to run the static scan itself.
+
+Several more things live alongside the static scan, each documented in its own section below:
+
+- **Skipping rules** ([Skipping rules](./usage.md#skipping-rules)): silence a specific rule by `rule_id`
+  (config-wide via `c.skip_rules`, or one-off via `--skip`) without editing or deleting it.
+- A **dependency audit** ([Dependency audit](#dependency-audit)), on by default, that checks
+  `Gemfile.lock` against [OSV.dev](https://osv.dev) for known-vulnerable gem versions and insecure
+  sources — the same broad goal as [bundler-audit](https://github.com/rubysec/bundler-audit), built
+  independently on a different data source. Pass `--no-deps` (or the `nodeps` rake arg) for a fast,
+  fully offline run instead.
+- **AI-assisted fix suggestions** ([AI-assisted fix suggestions](./fix-mode.md#ai-assisted-fix-suggestions)),
+  optional, provider-agnostic: rewrites each finding's `suggested_fix` against its actual code
+  using an LLM you configure — any LLM, not a specific vendor.
+
+**Nothing is auto-applied.** A security or performance fix needs a human's judgment about the
+surrounding code; this gem's job is to point at the issue and explain it clearly, not to rewrite
+your files. This holds whether `suggested_fix` came from a rule's static template or from the
+optional AI enrichment below — either way, it's text for a human to read and act on.
+
+
+## Dependency audit
+
+`Scryer::DependencyAudit` checks `Gemfile.lock` for the same broad concerns
+[bundler-audit](https://github.com/rubysec/bundler-audit) targets — known-vulnerable gem versions
+and insecure dependency sources — built independently on a different data source and a different
+lockfile parser: rather than bundler-audit's local clone of the `ruby-advisory-db` git repo, this
+queries [OSV.dev](https://osv.dev) (Google's Open Source Vulnerabilities database) live, one
+lookup per gem+version, over a small stdlib-only thread pool; `Gemfile.lock` is read with a small
+hand-rolled parser (see `DependencyAudit.parse_lockfile`) instead of depending on the `bundler`
+library, so it works the same whether or not this happens to run under Bundler. No bundler-audit
+source was read or copied to build this.
+
+```bash
+bin/rails scryer:audit_dependencies   # inside a Rails app — dependency audit only, no static scan
+```
+
+This is the one part of Scryer that needs a live network connection (to reach OSV.dev), and it
+runs automatically as part of every `scryer`/`scryer:report` scan — pass `--no-deps` (CLI) or the
+`nodeps` arg (rake) for a fast, fully offline run instead. `scryer:audit_dependencies` above (and
+`scryer --audit-deps` below) are for when you want *only* the dependency audit, the same way
+`bundle-audit check` is a separate, standalone command from your test suite. Either way it exits
+non-zero if anything is found, so it can gate CI.
+
+Three checks run, and any of them can be called on its own as a library:
+
+```ruby
+Scryer::DependencyAudit.insecure_sources(Rails.root.to_s)  # offline — no network needed
+Scryer::DependencyAudit.vulnerable_gems(Rails.root.to_s)   # needs network (OSV.dev)
+Scryer::DependencyAudit.ruby_eol_check(Rails.root.to_s)    # offline — checked against a small embedded table
+```
+
+- **Insecure sources**: flags any `GIT`/`PATH` block in `Gemfile.lock` whose `remote:` is
+  unencrypted (`git://` or plain `http://`) — the same supply-chain concern bundler-audit's
+  insecure-source check targets.
+- **Vulnerable gems**: for every RubyGems-sourced gem (git/path-sourced gems are skipped — their
+  version string doesn't necessarily correspond to the same code as the published gem of that
+  name, so checking them against RubyGems advisories could misattribute or miss vulnerabilities),
+  queries OSV.dev for known vulnerabilities affecting that exact version. Each finding carries the
+  advisory id, title, a severity bucketed from OSV's own severity level, a link to the advisory,
+  and the fixed version(s) to upgrade to. This is also where Rails-framework CVEs surface —
+  `rails`/`actionview`/`activestorage`/etc. are just gems in `Gemfile.lock` like any other.
+- **Ruby EOL**: checks the Ruby version pinned in `Gemfile.lock`'s `RUBY VERSION` section against
+  Ruby's own [published end-of-life dates](https://www.ruby-lang.org/en/downloads/branches/) — once
+  a series is EOL, no security patches are published for it at all, for any issue, regardless of
+  how up to date every gem is. Unlike the two checks above, this doesn't call OSV.dev: EOL dates
+  are announced years in advance and essentially never change, so a small embedded table
+  (`DependencyAudit::RUBY_EOL_DATES`) is a one-time/occasional-update cost rather than a live feed
+  — deliberately not a general Ruby-interpreter CVE database, which would mean maintaining exactly
+  the kind of stale bundled knowledge base this gem avoids elsewhere (OSV.dev has no queryable
+  Ruby-interpreter ecosystem to query live instead).
+
+**From the `scryer` executable** (outside a Rails app, or in CI): `scryer --audit-deps` runs the
+same three checks standalone (no static scan), same output/exit-code behavior as the rake task above.
+Plain `scryer` already folds them into the normal `-o` report — one HTML/JSON/CSV file covering
+static findings *and* dependency findings together — so `--audit-deps` is only for when you want
+dependency findings *without* the static scan. And for a single gem, without touching
+`Gemfile.lock` at all:
+
+```bash
+scryer --check-gem rack            # every advisory ever filed against rack, any version
+scryer --check-gem rack:2.0.8      # only advisories affecting exactly this version
+```
+
+This is the same OSV.dev client `vulnerable_gems` uses, exposed as a one-off lookup — useful for
+"is this gem I'm about to add actually fine" before it's even in your `Gemfile.lock`.
+

data/docs/usage.md

@@ -0,0 +1,301 @@
+# Usage & Configuration
+
+[← Back to Scryer — Ruby on Rails Security Auditor](../README.md)
+
+## Install
+
+Scryer is a development-time analysis tool, not something a running production process needs —
+scope it to the `:development` group so a production deploy (typically `bundle install --without
+development`, or `BUNDLE_WITHOUT=development` in CI) never installs it at all:
+
+```ruby
+# Gemfile
+group :development do
+  gem "scryer"
+end
+```
+
+```bash
+bundle install
+bin/rails generate scryer:install
+```
+
+This drops a commented `config/initializers/scryer.rb` into your app — see
+[Generators](./rails-integration.md#generators) below for exactly what it does and what each setting controls. Scryer
+is entirely local: there is nothing to point at a server and nothing to authenticate, so the
+generator's only job is letting you override the defaults (project name, which directories get
+scanned, the branch label).
+
+## Running a scan
+
+```bash
+bin/rails scryer:report   # writes tmp/scryer_report.{json,html}
+```
+
+By default this writes both `tmp/scryer_report.json` and `tmp/scryer_report.html`, and includes a
+dependency audit against `Gemfile.lock` (needs network — see [Dependency audit](./rules.md#dependency-audit);
+pass the `nodeps` arg for a fast, fully offline run instead). Format and output path are
+configurable via task args — any mix of `json`, `html`, `csv`, `sarif` plus at most one path (quote
+the whole thing so your shell doesn't eat the brackets/commas, e.g.
+`bin/rails 'scryer:report[json,doc/security_report.json]'`). Rake splits bracket args on every
+comma, so each format is its own item in the list rather than one comma-joined string
+(`scryer:report[json,html]` is two args, not `"json,html"` as one). At most one non-format,
+non-`nodeps` token is accepted per call; giving two raises an error rather than guessing which one
+you meant.
+
+Outside a Rails app (or in CI, or anywhere you don't want a rake task), the gem also ships a
+`scryer` executable — same idea as `brakeman -o report.json`, with `-o` repeatable and format
+inferred per-file from its extension:
+
+```bash
+scryer                                    # scans ., writes tmp/scryer_report.{json,html}
+scryer -o report.json                     # just one file, exact path, format from extension
+scryer -o report.json -o report.html      # as many outputs as you like, one -o each
+scryer -p /path/to/app -o /tmp/out.html   # -p sets the root to scan (default: cwd)
+scryer --no-deps                          # skip the dependency audit for a fast offline run
+scryer --help                             # full option list (--project-name, --branch, --version, ...)
+```
+
+Console output is a summary box across every category — see the box in the intro above for a real
+example — followed by where each report was written.
+
+**Color.** The summary box, top priorities, and `scryer fix`/`scryer verify` output are colored
+automatically at a real terminal — severity labels (`critical`/`warning`/`info` → red/yellow/cyan),
+the security score's letter grade (A/B green, C yellow, D/F red), fixed/skipped status lines, and
+so on. Off automatically whenever it would be wrong to color: piped/redirected output (e.g. `-o -`
+to a file, or piped to `less` without `-R`), [`NO_COLOR`](https://no-color.org) set, or
+`TERM=dumb`. `--color`/`--no-color` force it either way regardless of any of that — e.g. `scryer
+--color | less -R` to keep color through a pager. Inside a Rails app: `SCRYER_COLOR=1`/
+`SCRYER_NO_COLOR=1` (env vars, same precedence as the CLI flags). No new dependency — a small
+hand-rolled ANSI helper (`Scryer::Colorizer`), consistent with the zero-runtime-dependency design.
+
+See [Exit codes](#exit-codes) for what `0`/`1`/`2` mean here and for `scryer verify`/`scryer fix`.
+
+Or use the scanning engine directly as a library:
+
+```ruby
+require "scryer"
+result = Scryer::Scanner.new(root: "/path/to/app").call
+puts result.security_findings.size
+```
+
+Open `tmp/scryer_report.html` in a browser — it's a single self-contained file (inline CSS, no
+external assets, works offline) with an overview, a summary of counts by severity, the full list
+of checks that ran, a breakdown of warnings by type, every finding in detail, and duplicate-code
+groups — laid out similarly to a Brakeman report. `tmp/scryer_report.json` has the same data in
+machine-readable form, for feeding into your own dashboard or CI gate. `.csv`
+(`scryer -o report.csv` / `rails 'scryer:report[csv]'`) is a flat one-row-per-finding table
+(security + performance findings, plus dependency findings unless `--no-deps`/`nodeps` was used) —
+handy for dropping into a spreadsheet or importing into a ticketing tool; it skips duplicate-code
+groups, which don't reduce to a single actionable row. `.sarif` (`scryer -o report.sarif` /
+`rails 'scryer:report[sarif]'`) is for feeding into a CI security dashboard instead — see
+[CI/CD integration](#cicd-integration).
+
+## Exit codes
+
+| Command | `0` | `1` | `2` |
+|---|---|---|---|
+| `scryer` (scan) | Clean — no security or dependency findings | At least one security or dependency finding | Usage error (bad flag, unrecognized output extension) |
+| `scryer verify --rule ID --file PATH` | The rule no longer fires on that file | The rule still fires (findings printed) | Usage error (unknown rule_id, missing file, unparseable source) |
+| `scryer fix` | Everything matched was fixed (or nothing matched) | At least one finding still needs manual review after this run | Usage error (no `ai_client` and nothing mechanically fixable, bad flag, ...) |
+
+Every non-zero exit is deliberate and stable across versions, so any of these can gate a CI job
+directly (`scryer -o report.json || exit 1`, or just let the process's own exit code fail the
+step) — this is the same contract `brakeman -o report.json` and `bundle-audit check` already use,
+so swapping Scryer into an existing security-gate step doesn't change how the pipeline reacts to
+it.
+
+## CI/CD integration
+
+`scryer -o report.sarif` writes a [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/)
+report — the format GitHub Code Scanning, Azure DevOps, and most CI security dashboards ingest
+natively, turning findings into inline pull-request annotations and Security-tab entries instead
+of a report file nobody opens. It's a pure mapping of the same data every other format has —
+security, performance, and style findings (each mapped from `Scryer::Rule.rule_id`/`severity`) plus
+dependency findings (mapped from `kind`, located at `Gemfile.lock`) — so nothing behaves any
+differently than it does in HTML/JSON/CSV.
+
+### Option A: the bundled `action.yml`
+
+[`action.yml`](../action.yml) in this repo wraps the whole thing — install, scan, SARIF upload, and
+correctly ordering all three so the upload still happens even when findings were reported (see the
+`continue-on-error` explanation below for why that ordering matters):
+
+```yaml
+# .github/workflows/scryer.yml
+name: Scryer
+on: [push, pull_request]
+
+jobs:
+  scryer:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write   # required to upload SARIF
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ramlaxmanyadav/scryer@v1.2.0
+        with:
+          ruby-version: "3.3"
+```
+
+All inputs are optional — `path` (default `.`), `scryer-version` (default: latest), `extra-args`
+(e.g. `--skip idor --no-deps`), `fail-on-findings` (default `true`), `upload-sarif` (default
+`true`). Outputs: `sarif-path`, `json-path`, `exit-code`. See [action.yml](../action.yml) for the full
+input/output reference.
+
+`@v1.2.0` above needs a matching git tag pushed to GitHub before `uses:` can resolve it — replace
+it with whatever version tag you actually push (or `@main` to always track the latest commit,
+accepting that it can change under you).
+
+### Option B: hand-written steps
+
+For full control over the individual steps (a different Ruby setup, extra caching, a different
+job structure):
+
+```yaml
+# .github/workflows/scryer.yml
+name: Scryer
+on: [push, pull_request]
+
+jobs:
+  scryer:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write   # required to upload SARIF
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+      - run: gem install scryer
+      - run: scryer -o scryer.sarif
+        continue-on-error: true   # let the upload step run even on a non-zero exit; see below
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: scryer.sarif
+```
+
+`continue-on-error: true` on the scan step matters: `scryer` exits non-zero when it finds anything
+(see [Running a scan](#running-a-scan)), which would otherwise skip the upload step entirely on
+the run where you most want to see the results. If you want the job to still fail the build overall
+on findings, check `scryer`'s own exit code in a separate step, or drop `continue-on-error` and
+accept that the SARIF upload only happens on clean runs. `action.yml` (Option A) handles this
+ordering for you automatically.
+
+### Rails apps: `bin/rails scryer:ci`
+
+Inside a Rails app (rather than the standalone `scryer` executable above), `scryer:ci` is a
+memorable shortcut for the same CI-sensible defaults — JSON + SARIF under `tmp/`, dependency audit
+on, same `SCRYER_BASELINE` support and same fail-the-build-on-findings behavior as `scryer:report`
+— without needing to remember the bracket-arg syntax:
+
+```bash
+bin/rails scryer:ci   # same as bin/rails 'scryer:report[json,sarif]'
+```
+
+
+## What gets scanned
+
+By default: `app/`, `lib/`, `config/`, `db/` (relative to the app root) — configurable via
+`c.dirs` in the initializer. `vendor/`, `node_modules/`, `tmp/`, `log/`, `.git/`, `spec/`, `test/`
+are always skipped.
+
+## Branch reporting
+
+By default the `git_branch` recorded in the report comes from `git rev-parse --abbrev-ref HEAD` in
+the app root. Set `c.branch` in the initializer to override this — useful in CI, where checkouts
+often land in a detached-HEAD state and there's no real branch name to detect:
+
+```ruby
+Scryer.configure do |c|
+  c.branch = ENV["CI_COMMIT_BRANCH"]
+end
+```
+
+This only changes the label shown in the report; it does not check out a different branch or
+restrict which branch can be scanned.
+
+## Skipping rules
+
+Every rule is heuristic, so an occasional false positive on your specific codebase is expected
+(see "A note on how this gem was actually verified" above) — `skip_rules` silences one by
+`rule_id` without editing or deleting the rule itself, so it still runs (and could still catch a
+real issue) on every other codebase that uses this gem:
+
+```ruby
+# config/initializers/scryer.rb
+Scryer.configure do |c|
+  c.skip_rules = ["mass_assignment"]   # rule_id, from the finding's `rule_id` field
+end
+```
+
+The `scryer` executable's `--skip RULE_ID` flag (repeatable) adds to this list for a single run
+without touching the initializer — useful for a one-off "does this go away without rule X" check:
+
+```bash
+scryer --skip mass_assignment --skip weak_crypto
+```
+
+## Duplicate-code detection
+
+Method/query/cache-key similarity detection across models, controllers, helpers, and concerns
+(see "What Scryer detects" for how it works) runs by default. Unlike the security/performance/
+style checks, it isn't a `Scryer::Rule` with its own `rule_id`, so `skip_rules` can't address it —
+`c.detect_duplicates` is its own on/off switch instead:
+
+```ruby
+# config/initializers/scryer.rb
+Scryer.configure do |c|
+  c.detect_duplicates = false   # too noisy or too slow for this codebase
+end
+```
+
+For a one-off run without touching the initializer: the standalone executable's `--no-duplicates`
+flag, or the rake task's `noduplicates` bracket token (alongside `nodeps`) — either only turns
+detection off for that run, never back on if `c.detect_duplicates` is already `false`:
+
+```bash
+scryer --no-duplicates
+```
+
+```ruby
+rails 'scryer:report[html,noduplicates]'
+```
+
+## Baseline mode
+
+`--skip` silences a rule everywhere, permanently. Baseline mode is for the more common real-world
+situation: an existing app has genuine pre-existing findings you're not going to fix today, but you
+still want CI to fail on anything *new* from here on:
+
+```bash
+# Once: snapshot the current state
+scryer --save-baseline tmp/scryer_baseline.json
+
+# Every run after that: only new findings show up, count toward the exit code,
+# and appear in -o reports — everything already in the baseline is suppressed
+scryer --baseline tmp/scryer_baseline.json -o scryer.sarif
+```
+
+```
+Baseline: tmp/scryer_baseline.json — showing new findings only (2 fixed since baseline).
+
+Security Score: 96/100 (A)
+
+Security                 1 finding
+...
+```
+
+Findings are matched by a **fingerprint** (`rule_id` + file + the offending source text), not
+file:line — an unrelated edit earlier in the same file shifting every following line number
+wouldn't otherwise make an existing finding look simultaneously "new" and "fixed" on every commit.
+"Fixed since baseline" counts findings that were in the baseline but aren't in this scan anymore
+(across every category — security, performance, style, dependencies); duplicate-code groups aren't
+part of baseline mode (they don't fit the same fingerprint shape) and always show in full.
+
+Rails/rake equivalents: `rails 'scryer:save_baseline[tmp/scryer_baseline.json]'` to save, and
+`SCRYER_BASELINE=tmp/scryer_baseline.json rails scryer:report` to compare (an env var, since rake's
+bracket-arg parsing is already stretched thin between format tokens, `nodeps`, and an output path).
+

data/lib/generators/scryer/USAGE

@@ -28,13 +28,21 @@ Description:
                          useful. Leave unset to use the actual checked-out
                          branch.
 
-    Two more things ship in this gem but aren't controlled by the
-    initializer — see the README for both:
+    A few more things ship in this gem but aren't controlled by the
+    initializer — see the README for each:
 
       - Scryer::QueryWatcher: an opt-in runtime instrumentation for N+1
         queries and unused eager loading (README: "Runtime query watcher").
       - `bin/rails scryer:audit_dependencies`: a Gemfile.lock vulnerability
         + insecure-source audit against OSV.dev (README: "Dependency audit").
+      - `bin/rails scryer:ci`: a CI-friendly shortcut for
+        `scryer:report[json,sarif]` — JSON + SARIF output, dependency audit
+        on, same SCRYER_BASELINE support (README: "CI/CD integration").
+      - `require "scryer/rspec"` / `require "scryer/minitest"`: opt-in
+        matchers/assertions (`have_no_critical_findings`,
+        `assert_no_critical_scryer_findings`, ...) for asserting this app's
+        own scan stays clean as part of its normal test suite (README:
+        "Testing Scryer results in your own test suite").
 
 Example:
     bin/rails generate scryer:install

data/lib/generators/scryer/templates/scryer_initializer.rb

@@ -14,6 +14,21 @@ Scryer.configure do |c|
   # where checkouts often land in detached-HEAD state). Leave blank to use
   # the actual checked-out branch:
   # c.branch = ENV["CI_COMMIT_BRANCH"]
+
+  # Silence a specific rule by rule_id (repeatable) — a known false positive
+  # on this codebase, or a check that doesn't apply here. Prefer this over
+  # deleting/editing the rule itself; run `bin/rails scryer:report` once and
+  # check tmp/scryer_report.html's "Checks performed" section for the full
+  # list of rule_ids:
+  # c.skip_rules = %w[idor]
+
+  # Any object/Proc responding to #call(prompt) (or #complete(prompt)) that
+  # returns a String — opts into rewriting every finding's suggested_fix
+  # against its actual code via that LLM. Off by default: no network calls,
+  # no provider assumed. See the README's "AI-assisted fix suggestions" and
+  # "AI-verified remediation" sections for what this does and how the
+  # (optional) re-scan-to-confirm-the-fix-works verification works:
+  # c.ai_client = ->(prompt) { MyLlmClient.complete(prompt) }
 end
 
 # Runtime query watcher (N+1 / unused eager loading — see README's "Runtime