A Claude Code plugin that audits a Rails application's security configuration and produces a **severity-grouped, actionable report** grounded in Rails 8.0–8.2 defaults. Optionally applies fixes for any finding. --- ## What Is This? A Claude Code agent that: - **Scans** your Rails config: production environment, initializers, controllers, Gemfile, and CI workflows - **Detects** your Rails version from `Gemfile.lock` and adjusts expectations accordingly - **Runs** 10 categories of security checks against current Rails defaults - **Groups** findings by severity (Critical, High, Medium, Informational) - **Explains** each finding in plain language — what it is, why it matters, how to fix it - **Applies** fixes on request — single finding, all Critical, or all findings The agent runs autonomously: it reads the files it needs, produces the full report, and pauses to offer fixes. --- ## Quick Start ### 1. Add the Marketplace ```bash /plugin marketplace add maquina-app/rails-claude-code ``` ### 2. Install the Plugin ```bash /plugin install rails-security-auditor@maquina ``` ### 3. Run the Audit ``` > /audit-security ``` Or simply ask: ``` > Audit my Rails app's security configuration > Check if my CSRF setup is correct > Am I missing any security headers? ``` --- ## What It Checks Ten check categories, drawn from the full catalog in `references/checks.md`: | Category | Scope | |----------|-------| | **PROD** | `force_ssl`, `assume_ssl`, log level, `filter_parameters`, trusted proxies | | **CSRF** | `protect_from_forgery`, strategy, per-form tokens | | **HDR** | `X-Frame-Options`, `X-Content-Type-Options`, `X-XSS-Protection`, `Referrer-Policy` | | **CSP** | Content Security Policy initializer and directives | | **SESS** | Session cookie `SameSite`, `expire_after`, `httponly` | | **RATE** | `rate_limit` macro, Rack::Attack throttles and safelists | | **AUTH** | Authorization gem, tenant scoping, `allow_unauthenticated_access` | | **GEM** | Brakeman, bundler-audit, Rails CVEs | | **CI** | Security scanning in CI pipeline | | **FWKD** | Rails 8.2 framework defaults (CSRF header strategy, transaction-aware jobs) | Plus: column-level encryption (`encrypts`) and hardcoded secrets scans. --- ## How Findings Are Reported Each finding follows a consistent structure: ``` ### [PROD-01] force_ssl missing in production File: config/environments/production.rb Found: config.force_ssl is not set Why this matters: Without force_ssl, users on HTTP don't get redirected to HTTPS. Cookies and sessions can travel in the clear on public networks. How to fix it: config.force_ssl = true Offer: Would you like me to apply this fix? ``` Severity counts go at the top of the report: | Severity | Meaning | |----------|---------| | ❌ Critical | Active vulnerability — fix immediately | | ⚠️ High | Important gap — fix soon | | 🔶 Medium | Hardening — recommended | | ℹ️ Informational | Optional improvement | | ✅ Passed | Already configured correctly | --- ## Audit Principles The auditor is designed to minimize noise: - **Intentional configuration isn't flagged.** If `assume_ssl` is set alongside `force_ssl`, the agent recognizes it as a Cloudflare/Kamal setup and doesn't mark `force_ssl` redirect as missing. - **Version-aware.** A Rails 7.1 app isn't expected to have 8.2 defaults; checks adapt to the detected version. - **Missing files are findings.** No `rack_attack.rb` → finding. No `content_security_policy.rb` → finding. - **Ambiguous intent surfaces as "Verify:"** rather than an assertion of wrongness. - **Severity is guidance, not a verdict.** The agent adjusts when the app's context makes a finding materially more or less risky. --- ## Applying Fixes After the report, you can fix findings one at a time, all Critical findings at once, or everything: ``` > Fix all Critical findings > Apply the CSP fix only > Create the missing rack_attack.rb initializer ``` For each fix the agent reads the current file, applies the minimal change needed, shows a before/after diff, and confirms the write. When a fix requires creating a new initializer from scratch, it generates the full file. --- ## Package Contents ``` rails-security-auditor/ ├── agents/rails-security-auditor.md # Main agent └── references/ └── checks.md # Full check catalog with fixes ``` --- ## Team Installation Add to your project's `.claude/settings.json`: ```json { "extraKnownMarketplaces": { "maquina": { "source": { "source": "github", "repo": "maquina-app/rails-claude-code" } } }, "enabledPlugins": [ "rails-security-auditor@maquina" ] } ``` Wire `/audit-security` into your release checklist so every major deploy starts with a clean report. --- ## Next Steps

GitHub Repository

View source code and contribute.

Rails Upgrade Assistant

Pair with upgrades to pick up new security defaults.

Rails Simplifier

Clean up code patterns discovered during an audit.