ariadna 1.3.0 → 2.0.0

data/data/skills/rails-security/AUDIT.md

@@ -0,0 +1,118 @@
+---
+name: rails-security-audit
+description: Security audit checklist with grep patterns and file globs for systematic code review. Referenced from SKILL.md.
+---
+
+# Rails Security Audit Checklist
+
+Systematic checklist for verifying security after each development phase. Each check includes a severity, grep pattern, and file scope so an agent or reviewer can scan changed files methodically.
+
+---
+
+## How to Use
+
+### Step 1: Identify changed files
+
+```bash
+git diff --name-only HEAD~1
+# For a full phase: git diff <phase-start-sha>..HEAD --name-only
+```
+
+### Step 2: Map files to applicable checks
+
+| Changed file pattern | Applicable checks |
+|---|---|
+| `app/models/**/*.rb` | 1.1a, 1.1b, 1.4a, 2.2c, 3.1b, 3.2c, 4.3a, 4.3b |
+| `app/controllers/**/*.rb` | 1.1c, 1.1d, 1.2e, 2.1a, 2.2a, 2.2b, 2.3a, 3.1a, 3.1c, 3.2a, 3.2b, 3.2d, 3.3a |
+| `app/views/**/*.erb` | 1.2a, 1.2b, 1.2c, 1.2d, 2.1b |
+| `app/controllers/api/**/*.rb` | 5.2a, 5.2b, 5.2c |
+| `config/routes.rb` | 2.1c, 2.3a |
+| `config/environments/production.rb` | 4.1c, 5.1a |
+| `config/initializers/**/*.rb` | 3.3b, 3.3c, 4.2a, 5.1b, 5.1c |
+| `app/models/session.rb` | 3.3a, 3.3c |
+| `db/migrate/**/*.rb` | 3.1b |
+| `lib/**/*.rb` | 1.1b, 1.3a, 1.3b |
+| `Gemfile` / `Gemfile.lock` | 5.3a |
+| `package.json` / `yarn.lock` | 5.3b |
+| `app/javascript/**/*.js` | 1.2d, 2.1b |
+
+### Step 3: Report format
+
+```
+PASS: CHECK 1.1a — No string interpolation in SQL (scanned 3 files)
+FAIL: CHECK 3.2a — Unscoped find in app/controllers/boards_controller.rb:15
+SKIP: CHECK 4.3a — No file upload changes in this phase
+```
+
+---
+
+## Full Checklist
+
+| Check | Name | Severity | Grep pattern | Files |
+|---|---|---|---|---|
+| **1.1a** | No SQL string interpolation | Critical | `\.where\(["'].*#\{` | `app/models/**/*.rb`, `app/controllers/**/*.rb` |
+| **1.1b** | Parameterized raw SQL | Critical | `\.execute\(["'].*#\{` | `app/models/**/*.rb`, `lib/**/*.rb` |
+| **1.1c** | Allowlisted order/group columns | High | `\.order\(params` | `app/controllers/**/*.rb` |
+| **1.1d** | Scoped find for user lookups | High | `\.find\(params\[` | `app/controllers/**/*.rb` |
+| **1.2a** | No raw/html_safe on user input | Critical | `\.html_safe\|raw(` | `app/views/**/*.erb`, `app/helpers/**/*.rb` |
+| **1.2b** | Sanitized rich text output | High | `\.to_s\.html_safe` | `app/views/**/*.erb` |
+| **1.2c** | Safe link_to href values | High | `link_to.*params\[` | `app/views/**/*.erb` |
+| **1.2d** | JSON escaped in script tags | High | `<script>.*to_json` | `app/views/**/*.erb` |
+| **1.2e** | Content-Type for non-HTML responses | Medium | `render plain:` | `app/controllers/**/*.rb` |
+| **1.3a** | No user input in shell calls | Critical | `system\(["'].*#\{` | `app/**/*.rb`, `lib/**/*.rb` |
+| **1.3b** | Shellwords for unavoidable shell use | High | `Shellwords\.escape` | `app/**/*.rb`, `lib/**/*.rb` |
+| **1.4a** | `\A`/`\z` not `^`/`$` in regex | High | `format:.*\/\^` | `app/models/**/*.rb`, `app/validators/**/*.rb` |
+| **2.1a** | CSRF protection enabled | Critical | `skip_before_action :verify_authenticity` | `app/controllers/**/*.rb` |
+| **2.1b** | Authenticity token in forms | High | `<form[^>]*method` | `app/views/**/*.erb` |
+| **2.1c** | Non-GET for state-changing routes | High | `get.*destroy\|get.*delete\|get.*create` | `config/routes.rb` |
+| **2.2a** | Strong parameters — no permit! | Critical | `params\.permit!` | `app/controllers/**/*.rb` |
+| **2.2b** | No admin/role attrs in permit | High | `permit.*:admin\|permit.*:role` | `app/controllers/**/*.rb` |
+| **2.2c** | Nested attributes scoped | Medium | `accepts_nested_attributes_for` | `app/models/**/*.rb` |
+| **2.3a** | No open redirects from params | High | `redirect_to params\[` | `app/controllers/**/*.rb` |
+| **2.3b** | External redirect allowlists | Medium | `allow_other_host: true` | `app/controllers/**/*.rb` |
+| **3.1a** | Auth required on all controllers | Critical | `skip_before_action :authenticate` | `app/controllers/**/*.rb` |
+| **3.1b** | Secure password storage | Critical | `Digest::MD5\|Digest::SHA1` | `app/models/**/*.rb` |
+| **3.1c** | Timing-safe token comparison | High | `==.*token\|==.*secret` | `app/controllers/**/*.rb`, `app/models/**/*.rb` |
+| **3.1d** | Rate limiting on auth endpoints | High | `rate_limit` | `app/controllers/sessions_controller.rb` |
+| **3.2a** | Scoped resource lookups | Critical | `\.find\(params\[:id\]\)` | `app/controllers/**/*.rb` |
+| **3.2b** | Authz check on destructive actions | High | `def destroy` | `app/controllers/**/*.rb` |
+| **3.2c** | Tenant isolation in queries | Critical | `Current\.account` | `app/models/**/*.rb`, `app/controllers/**/*.rb` |
+| **3.2d** | Nested resource scoped to parent | High | `Comment\.find\|\.find\(params\[:id\]\)` | `app/controllers/**/*.rb` |
+| **3.3a** | Session regeneration after login | High | `reset_session` | `app/controllers/sessions_controller.rb` |
+| **3.3b** | Secure cookie configuration | High | `session_store.*secure` | `config/environments/production.rb`, `config/initializers/**/*.rb` |
+| **3.3c** | Session expiration configured | Medium | `expire_after` | `config/initializers/**/*.rb`, `app/models/session.rb` |
+| **4.1a** | No hardcoded secrets | Critical | `API_KEY\|SECRET\|password.*=.*["']` | `app/**/*.rb`, `config/**/*.rb` |
+| **4.1b** | Credentials encrypted, not committed | High | `secrets\.yml\|\.env` | `config/**/*.yml`, `.gitignore` |
+| **4.1c** | Secret key base from credentials/env | Critical | `secret_key_base` | `config/environments/production.rb` |
+| **4.2a** | All sensitive params filtered | High | `filter_parameters` | `config/initializers/filter_parameter_logging.rb` |
+| **4.2b** | No PII/tokens in logs | High | `logger.*token\|logger.*password\|logger.*email` | `app/**/*.rb`, `lib/**/*.rb` |
+| **4.3a** | File upload content type validated | High | `content_type:` | `app/models/**/*.rb` |
+| **4.3b** | File upload size limited | High | `size:.*less_than` | `app/models/**/*.rb` |
+| **4.3c** | Safe file download path | Critical | `send_file.*params` | `app/controllers/**/*.rb` |
+| **4.3d** | No uploads in public directory | High | `public.*uploads` | `app/controllers/**/*.rb`, `config/storage.yml` |
+| **5.1a** | Force SSL enabled in production | Critical | `force_ssl` | `config/environments/production.rb` |
+| **5.1b** | CSP configured and restrictive | High | `content_security_policy` | `config/initializers/**/*.rb` |
+| **5.1c** | Security headers set | Medium | `Referrer-Policy\|Permissions-Policy` | `config/initializers/**/*.rb` |
+| **5.2a** | API authentication on all endpoints | Critical | `before_action.*authenticate` | `app/controllers/api/**/*.rb` |
+| **5.2b** | API responses tenant-scoped | High | `Current\.account` | `app/controllers/api/**/*.rb` |
+| **5.2c** | API rate limiting configured | Medium | `rate_limit\|Rack::Attack` | `app/controllers/api/**/*.rb`, `config/initializers/**/*.rb` |
+| **5.3a** | No vulnerable gems | High | `bundle audit check --update` | `Gemfile.lock` |
+| **5.3b** | No vulnerable JS packages | High | `yarn audit` | `package.json`, `yarn.lock` |
+
+---
+
+## Step 4: Automated Tools
+
+Run after manual checks:
+
+```bash
+# Dependency audits
+bundle audit check --update
+yarn audit
+
+# Static analysis
+brakeman --no-pager -q
+
+# Check for accidentally committed secrets/keys
+git log --diff-filter=A --name-only -- "*.key" "*.pem" ".env*"
+```

data/data/skills/rails-security/SKILL.md

@@ -0,0 +1,422 @@
+---
+name: rails-security
+description: Ruby on Rails security conventions — authentication, authorization, OWASP protections, CSRF, input validation. Use when implementing auth, handling sensitive data, or reviewing security.
+---
+
+# Rails Security Conventions
+
+Opinionated security conventions for Rails applications. Covers the most critical OWASP risks and Rails-specific pitfalls. For a full audit checklist with grep patterns, see [AUDIT.md](AUDIT.md).
+
+---
+
+## Part 1: Input Handling & Injection
+
+### SQL Injection — Always parameterize
+
+Never interpolate or concatenate user input into SQL. ActiveRecord's hash and placeholder syntax handles this automatically.
+
+**UNSAFE:**
+```ruby
+User.where("name = '#{params[:name]}'")
+User.order("#{params[:sort]} #{params[:direction]}")
+ActiveRecord::Base.connection.execute("UPDATE users SET name = '#{name}'")
+```
+
+**SAFE:**
+```ruby
+User.where(name: params[:name])
+User.where("name = ?", params[:name])
+ActiveRecord::Base.connection.exec_query("UPDATE users SET name = $1", "SQL", [name])
+```
+
+For `order`/`group`, allowlist the column before use:
+
+```ruby
+ALLOWED_SORT_COLUMNS = %w[name created_at updated_at].freeze
+
+scope :sorted_by, ->(col) {
+  order(ALLOWED_SORT_COLUMNS.include?(col) ? col : :created_at)
+}
+```
+
+### XSS — Rails escapes by default; do not bypass it
+
+ERB auto-escapes `<%= %>`. Never call `.html_safe` or `raw()` on user-supplied or database content.
+
+**UNSAFE:**
+```erb
+<%= params[:query].html_safe %>
+<%= raw(@user.bio) %>
+<%= @card.description.to_s.html_safe %>
+<script>var data = <%= @data.to_json %>;</script>
+```
+
+**SAFE:**
+```erb
+<%= params[:query] %>
+<%= sanitize(@user.bio) %>
+<%= @card.description %>
+<script>var data = <%= json_escape(@data.to_json) %>;</script>
+```
+
+Validate URL protocols before rendering user-supplied links:
+```erb
+<%= link_to "Website", @user.website_url if @user.website_url&.match?(%r{\Ahttps?://}) %>
+```
+
+Use `\A` / `\z` in regex validations — not `^` / `$` (line vs. string boundaries):
+```ruby
+validates :slug, format: { with: /\A[a-z0-9-]+\z/ }  # SAFE
+validates :slug, format: { with: /^[a-z0-9-]+$/ }    # UNSAFE — allows newline injection
+```
+
+### Command Injection — Use array form for shell calls
+
+```ruby
+# UNSAFE — single string passes through the shell
+system("convert #{params[:file]} output.png")
+
+# SAFE — array form bypasses shell interpretation
+system("convert", uploaded_file.path, "output.png")
+stdout, _s = Open3.capture2("grep", "-r", query, "/data")
+
+# If a shell string is unavoidable, escape the argument
+system("tar -czf archive.tar.gz #{Shellwords.escape(directory)}")
+```
+
+---
+
+## Part 2: Request Integrity
+
+### CSRF — Never skip `verify_authenticity_token` for browser controllers
+
+Rails enables CSRF protection by default via `ApplicationController`. Only API controllers using token-based auth should opt out.
+
+```ruby
+# UNSAFE — disables CSRF on a browser controller
+class PaymentsController < ApplicationController
+  skip_before_action :verify_authenticity_token
+end
+
+# SAFE — inherits CSRF from ApplicationController
+class PaymentsController < ApplicationController
+end
+
+# Correct — ActionController::API excludes CSRF; authenticate with tokens instead
+class Api::V1::BaseController < ActionController::API
+  before_action :authenticate_api_token
+end
+```
+
+Always use `form_with` (never hand-craft `<form>` tags without CSRF token). State-changing actions must use non-GET HTTP methods:
+
+```ruby
+# UNSAFE
+get "posts/:id/publish", to: "posts#publish"
+
+# SAFE
+resource :publication, only: [:create, :destroy]
+```
+
+### Strong Parameters — Always allowlist, never permit!
+
+```ruby
+# UNSAFE
+@user = User.create(params[:user])
+@user.update(params.permit!)
+
+# SAFE
+def user_params
+  params.require(:user).permit(:name, :email)
+end
+```
+
+Never include privilege-escalation attributes (`admin`, `role`, `account_id`, `verified`) in permit lists — set them explicitly with authorization checks. Scope nested attributes:
+
+```ruby
+def project_params
+  params.require(:project).permit(:name,
+    tasks_attributes: [:id, :title, :done, :_destroy])
+end
+```
+
+### Open Redirects — Validate redirect targets
+
+```ruby
+# UNSAFE
+redirect_to params[:return_to]
+
+# SAFE — only allow same-host redirects
+def safe_redirect?(url)
+  uri = URI.parse(url.to_s)
+  uri.host.nil? || uri.host == request.host
+rescue URI::InvalidURIError
+  false
+end
+
+# For external redirects, use an explicit allowlist
+ALLOWED_REDIRECT_HOSTS = %w[accounts.example.com auth.example.com].freeze
+```
+
+---
+
+## Part 3: Authentication & Authorization
+
+### Authentication — Required by default, opt-out explicitly
+
+Every controller inheriting from `ApplicationController` must require authentication. Use `allow_unauthenticated_access` only for intentionally public actions.
+
+```ruby
+# ApplicationController
+class ApplicationController < ActionController::Base
+  before_action :authenticate
+end
+
+# Only public actions opt out explicitly
+class SessionsController < ApplicationController
+  allow_unauthenticated_access only: [:new, :create]
+end
+```
+
+**Password storage:** Always use `has_secure_password` (bcrypt). Never MD5, SHA1, or plain text.
+
+**Token comparison:** Use `ActiveSupport::SecurityUtils.secure_compare` to prevent timing attacks:
+```ruby
+if ActiveSupport::SecurityUtils.secure_compare(actual_token, expected_token)
+  process_webhook
+end
+```
+
+**Rate limiting on auth endpoints:**
+```ruby
+class SessionsController < ApplicationController
+  rate_limit to: 10, within: 3.minutes, only: :create,
+    with: -> { redirect_to new_session_path, alert: "Try again later." }
+end
+```
+
+### Authorization & IDOR — Always scope through the current user/account
+
+Never look up records by raw ID without scoping:
+
+```ruby
+# UNSAFE — any user can access any board
+@board = Board.find(params[:id])
+
+# SAFE — scoped through current user
+@board = Current.user.boards.find(params[:id])
+@card  = Current.user.accessible_cards.find_by!(number: params[:card_id])
+```
+
+For multi-tenant applications, scope through `Current.account` at every query layer — including model scopes:
+
+```ruby
+class Card < ApplicationRecord
+  scope :recent, -> {
+    where(account: Current.account).order(created_at: :desc).limit(10)
+  }
+end
+```
+
+Nested resource controllers must chain the scope to the parent — never look up child records globally:
+
+```ruby
+# UNSAFE — any comment, not scoped to card
+@comment = Comment.find(params[:id])
+
+# SAFE
+@card    = Current.user.accessible_cards.find_by!(number: params[:card_id])
+@comment = @card.comments.find(params[:id])
+```
+
+Destructive actions need explicit authorization checks beyond authentication:
+
+```ruby
+def destroy
+  @board = Current.user.boards.find(params[:id])
+  if Current.user.can_administer_board?(@board)
+    @board.destroy
+  else
+    head :forbidden
+  end
+end
+```
+
+### Session Security
+
+```ruby
+# Regenerate session after login to prevent session fixation
+def create
+  if user = User.authenticate_by(email: params[:email], password: params[:password])
+    reset_session
+    session[:user_id] = user.id
+  end
+end
+```
+
+Production session store configuration:
+```ruby
+Rails.application.config.session_store :cookie_store,
+  key: "_app_session",
+  secure: Rails.env.production?,
+  httponly: true,
+  same_site: :lax,
+  expire_after: 12.hours
+```
+
+---
+
+## Part 4: Data Protection
+
+### Secrets — Never hardcode; always use Rails credentials or ENV
+
+```ruby
+# UNSAFE
+API_KEY = "sk_live_abc123xyz"
+
+# SAFE
+API_KEY = Rails.application.credentials.stripe[:api_key]
+# Or: ENV.fetch("STRIPE_API_KEY")
+```
+
+Production secret_key_base must come from credentials or env — never from the development value.
+
+### Log Filtering — Filter all sensitive fields
+
+```ruby
+# config/initializers/filter_parameter_logging.rb
+Rails.application.config.filter_parameters += [
+  :password, :password_confirmation,
+  :token, :api_key, :secret,
+  :credit_card, :card_number, :cvv,
+  :ssn, :social_security
+]
+```
+
+Never log user PII, tokens, or payment data. Log IDs, not values:
+```ruby
+Rails.logger.info "User login: user_id=#{user.id}"  # SAFE
+Rails.logger.info "User login: #{user.email}, token: #{user.auth_token}"  # UNSAFE
+```
+
+### File Uploads — Validate type, size, and storage location
+
+```ruby
+class Document < ApplicationRecord
+  has_one_attached :file
+
+  validates :file,
+    content_type: %w[application/pdf image/png image/jpeg],
+    size: { less_than: 10.megabytes }
+
+  validate :reject_dangerous_content_types
+
+  private
+    def reject_dangerous_content_types
+      dangerous = %w[text/html application/javascript application/x-httpd-php]
+      errors.add(:file, "type not allowed") if file.attached? && dangerous.include?(file.content_type)
+    end
+end
+```
+
+Use ActiveStorage (files stored outside `public/`). Never store uploads directly in `public/uploads/`. Prevent path traversal in download endpoints:
+
+```ruby
+def download
+  filename = File.basename(params[:filename])
+  path = Rails.root.join("uploads", filename)
+  path.to_s.start_with?(Rails.root.join("uploads").to_s) ? send_file(path) : head(:forbidden)
+end
+```
+
+---
+
+## Part 5: Infrastructure Security
+
+### Force SSL and configure security headers
+
+```ruby
+# config/environments/production.rb
+config.force_ssl = true  # Enables HSTS, redirects HTTP→HTTPS, marks cookies as secure
+```
+
+Content Security Policy (avoid `unsafe-inline`/`unsafe-eval`):
+```ruby
+Rails.application.configure do
+  config.content_security_policy do |policy|
+    policy.default_src :self
+    policy.script_src  :self
+    policy.style_src   :self, :unsafe_inline
+    policy.img_src     :self, :data, "https://storage.example.com"
+    policy.connect_src :self
+  end
+  config.content_security_policy_nonce_generator = ->(req) { req.session.id.to_s }
+end
+```
+
+Additional headers:
+```ruby
+# config/initializers/default_headers.rb
+Rails.application.config.action_dispatch.default_headers.merge!(
+  "Referrer-Policy"   => "strict-origin-when-cross-origin",
+  "Permissions-Policy" => "camera=(), microphone=(), geolocation=()",
+  "X-Content-Type-Options" => "nosniff"
+)
+```
+
+### API Security
+
+Token authentication on the base API controller, tenant-scoped responses:
+
+```ruby
+class Api::V1::BaseController < ActionController::API
+  before_action :authenticate_api_token
+
+  private
+    def authenticate_api_token
+      token = request.headers["Authorization"]&.remove("Bearer ")
+      head :unauthorized unless token && ApiToken.active.exists?(token: token)
+    end
+end
+```
+
+Rate-limit API endpoints via Rails built-in or Rack::Attack:
+```ruby
+# Rails built-in (7.1+)
+rate_limit to: 100, within: 1.minute
+
+# Rack::Attack
+Rack::Attack.throttle("api/requests", limit: 100, period: 1.minute) do |req|
+  req.env["HTTP_AUTHORIZATION"]&.remove("Bearer ") if req.path.start_with?("/api/")
+end
+```
+
+### Dependency Auditing
+
+Run in CI on every build:
+```bash
+bundle audit check --update  # Ruby gems
+yarn audit                   # JavaScript packages
+brakeman --no-pager -q       # Static analysis
+```
+
+---
+
+## Quick Reference: Severity Map
+
+| Risk | Severity | Convention |
+|---|---|---|
+| SQL string interpolation | Critical | Use parameterized queries |
+| XSS via `.html_safe` | Critical | Never bypass ERB escaping |
+| CSRF disabled | Critical | Never skip `verify_authenticity_token` |
+| `params.permit!` | Critical | Always allowlist params |
+| Unscoped `find(params[:id])` | Critical | Scope through current user/account |
+| Force SSL off | Critical | `config.force_ssl = true` in production |
+| Hardcoded secrets | Critical | Use Rails credentials or ENV |
+| Path traversal in uploads | Critical | Use ActiveStorage; never user-controlled paths |
+| Command injection | Critical | Array form for shell calls |
+| No rate limiting on auth | High | `rate_limit` on sessions controller |
+| Timing attacks on tokens | High | `secure_compare` not `==` |
+| Session fixation | High | `reset_session` before login |
+
+For the full checklist with grep patterns and file globs, see [AUDIT.md](AUDIT.md).

data/data/skills/rails-testing/FIXTURES.md

@@ -0,0 +1,78 @@
+# Fixtures — Test Data Management
+
+Part of the [Rails Testing Skill](SKILL.md).
+
+---
+
+## Fixtures Over Factories
+
+Use **YAML fixtures**, not FactoryBot. Fixtures are deterministic, fast (loaded once per suite in a transaction), and explicit. Same records every test run — no random IDs.
+
+---
+
+## File Location and Format
+
+```
+test/fixtures/
+  cards.yml
+  sessions.yml
+  boards.yml
+```
+
+```yaml
+# test/fixtures/cards.yml
+logo:
+  title: "Logo Design"
+  board: writebook
+  state: open
+
+header:
+  title: "Header Redesign"
+  board: writebook
+  state: closed
+```
+
+Use descriptive symbolic names (`logo`, `header`) — never generic names like `one`, `two`.
+
+---
+
+## Accessing Fixtures
+
+```ruby
+card = cards(:logo)
+session = sessions(:david)
+board = boards(:writebook)
+```
+
+For associations, use the fixture name in YAML — Rails resolves the foreign key automatically.
+
+---
+
+## Current.session and Sessions Fixtures
+
+The sessions fixture drives the entire Current context cascade:
+
+```ruby
+setup do
+  Current.session = sessions(:david)
+  # Sets Current.session → Current.user → Current.account
+end
+```
+
+One line sets tenant scope, user context, and event tracking defaults. Define at least one named session per user persona.
+
+---
+
+## Adding New Fixtures
+
+1. Create `test/fixtures/<table_name>.yml`
+2. Add named records with meaningful names and all required attributes
+3. Reference in tests via `model_name(:fixture_name)`
+
+Avoid `Model.create!` inside tests for arrangement — use existing fixtures. Reserve `create!` calls for tests that specifically verify creation behavior.
+
+---
+
+## Fixture Isolation
+
+Each test wraps in a transaction that rolls back after completion. Fixture records persist for the full suite run but mutations are rolled back between tests. Use `record.reload` to pick up database changes within the same test.