maquina-generators 0.5.0 → 0.6.0

data/lib/generators/maquina/rack_attack/templates/config/initializers/rack_attack.rb.tt

@@ -2,6 +2,12 @@
 
 # Rack::Attack configuration
 # https://github.com/rack/rack-attack
+#
+# Coarse scanner-blocking only; per-action throttling belongs in controllers
+# via `rate_limit`. Counters and bans live in Rails.cache (Solid Cache in
+# production), so `SolidCache::Entry.where("key LIKE '%rack::attack%'")` is
+# the forensic record — the middleware answers before Rails, so nothing here
+# reaches the request log except through the subscriber at the bottom.
 
 # Safelist localhost
 Rack::Attack.safelist("allow-localhost") do |req|
@@ -9,66 +15,124 @@ Rack::Attack.safelist("allow-localhost") do |req|
 end
 
 # ---------------------------------------------------------------------------
-# Blocklists — common vulnerability scanner paths
+# Blocklist — common vulnerability scanner paths, with a ban
 # ---------------------------------------------------------------------------
+#
+# A scanner sprays hundreds of guesses in a couple of minutes (a thousand
+# WordPress REST probes in under five minutes from one address is ordinary).
+# Refusing the matching path alone lets every other guess through to routing
+# until the general throttle catches up, so the third scanner path bans the IP
+# for a week — long enough to outlast a rented scanner host, short enough that
+# a reassigned cloud address is not refused for the next tenant.
+#
+# Backup-archive guesses count as scanner paths too (`/<word>.zip` by the
+# hundred in a few seconds). Files the app really serves live under
+# /rails/active_storage, so that prefix is exempt.
 
-# Block PHP file requests
-Rack::Attack.blocklist("block-php") do |req|
-  req.path.match?(/\.php\d?$/i)
-end
+class Rack::Attack
+  # PHP file requests
+  PHP_PATH = /\.php\d?$/i
+
+  # Backup and dump guesses (`/backup.zip`, `/db.sql.gz`, `/site.tar.gz`)
+  ARCHIVE_PATH = /\.(zip|rar|7z|tar|tgz|gz|bz2|xz|sql|bak|backup|old)$/i
+
+  # WordPress paths
+  WORDPRESS_PATHS = %w[
+    /wp-admin
+    /wp-login
+    /wp-content
+    /wp-includes
+    /wp-json
+    /xmlrpc.php
+    /wp-config
+    /wp-cron
+  ].freeze
+
+  # Sensitive file access — anywhere in the path, since scanners probe them behind
+  # prefixes too (`/@fs/.env`, `/wp/.git/config`)
+  SENSITIVE_PATTERNS = %w[
+    /.env
+    /.git
+    /.htaccess
+    /.htpasswd
+    /.aws
+    /.ssh
+    /.svn
+  ].freeze
+
+  # Common scanner targets
+  SCANNER_PATHS = %w[
+    /cgi-bin
+    /phpmyadmin
+    /pma
+    /myadmin
+    /phpinfo
+    /mysqladmin
+    /admin/config.php
+    /solr/
+    /actuator
+    /telescope/requests
+    /debug
+    /_ignition
+    /vendor/phpunit
+  ].freeze
+
+  # The scanner ban's three knobs.
+  SCANNER_MAXRETRY = 3
+  SCANNER_FINDTIME = 10.minutes
+  SCANNER_BANTIME = 7.days
+
+  # An address still sending at twice the general throttle's limit has ignored
+  # every 429 since it hit the limit: banned for a day. A day rather than the
+  # scanner's week because a shared address (office, carrier NAT) can land here.
+  GENERAL_LIMIT = 300
+  GENERAL_PERIOD = 5.minutes
+  FLOOD_MAXRETRY = GENERAL_LIMIT * 2
+  FLOOD_BANTIME = 1.day
+
+  # Sign-in throttle.
+  LOGIN_PATH = "<%= options[:login_path] %>"
+  LOGIN_LIMIT = 5
+  LOGIN_PERIOD = 20.seconds
+
+  def self.scanner_path?(path)
+    path = path.downcase.squeeze("/")
+    return false if path.start_with?("/rails/active_storage")
 
-# Block WordPress paths
-WORDPRESS_PATHS = %w[
-  /wp-admin
-  /wp-login
-  /wp-content
-  /wp-includes
-  /xmlrpc.php
-  /wp-config
-  /wp-cron
-].freeze
-
-Rack::Attack.blocklist("block-wordpress") do |req|
-  WORDPRESS_PATHS.any? { |path| req.path.downcase.start_with?(path) }
+    path.match?(PHP_PATH) ||
+      path.match?(ARCHIVE_PATH) ||
+      WORDPRESS_PATHS.any? { |prefix| path.start_with?(prefix) } ||
+      SENSITIVE_PATTERNS.any? { |dotfile| path.include?(dotfile) } ||
+      path.include?("/etc/passwd") ||
+      path.include?("/etc/shadow") ||
+      SCANNER_PATHS.any? { |prefix| path.start_with?(prefix) }
+  end
+
+  # What the general throttle and the flood ban count: every request but
+  # assets and Active Storage, by IP.
+  def self.counted_ip(req)
+    req.ip unless req.path.start_with?("/assets", "/rails/active_storage")
+  end
+
+  def self.banned?(ip)
+    Fail2Ban.banned?("scanner:#{ip}") || Allow2Ban.banned?("flood:#{ip}")
+  end
 end
 
-# Block sensitive file access
-SENSITIVE_PATTERNS = %w[
-  /.env
-  /.git
-  /.htaccess
-  /.htpasswd
-  /.aws
-  /.ssh
-  /.svn
-].freeze
-
-Rack::Attack.blocklist("block-sensitive-files") do |req|
-  path = req.path.downcase
-  SENSITIVE_PATTERNS.any? { |pattern| path.start_with?(pattern) } ||
-    path.include?("/etc/passwd") ||
-    path.include?("/etc/shadow")
+Rack::Attack.blocklist("fail2ban/scanners") do |req|
+  Rack::Attack::Fail2Ban.filter("scanner:#{req.ip}",
+    maxretry: Rack::Attack::SCANNER_MAXRETRY, findtime: Rack::Attack::SCANNER_FINDTIME, bantime: Rack::Attack::SCANNER_BANTIME) do
+    Rack::Attack.scanner_path?(req.path)
+  end
 end
 
-# Block common scanner targets
-SCANNER_PATHS = %w[
-  /cgi-bin
-  /phpmyadmin
-  /pma
-  /myadmin
-  /phpinfo
-  /mysqladmin
-  /admin/config.php
-  /solr/
-  /actuator
-  /telescope/requests
-  /debug
-  /_ignition
-  /vendor/phpunit
-].freeze
-
-Rack::Attack.blocklist("block-scanner-targets") do |req|
-  SCANNER_PATHS.any? { |path| req.path.downcase.start_with?(path) }
+# Blocklists run before throttles, so this counts the requests the throttle
+# goes on to refuse as well.
+Rack::Attack.blocklist("allow2ban/flood") do |req|
+  if (ip = Rack::Attack.counted_ip(req))
+    Rack::Attack::Allow2Ban.filter("flood:#{ip}",
+      maxretry: Rack::Attack::FLOOD_MAXRETRY, findtime: Rack::Attack::GENERAL_PERIOD, bantime: Rack::Attack::FLOOD_BANTIME) { true }
+  end
 end
 
 # ---------------------------------------------------------------------------
@@ -76,13 +140,17 @@ end
 # ---------------------------------------------------------------------------
 
 # General rate limit: 300 requests per 5 minutes per IP
-Rack::Attack.throttle("req/ip", limit: 300, period: 5.minutes) do |req|
-  req.ip unless req.path.start_with?("/assets")
+#
+# Active Storage is exempt alongside /assets. A page of proxied images is dozens
+# of requests, and a refusal there renders as a broken image. Every one of those
+# requests is already gated by an unguessable signed id.
+Rack::Attack.throttle("req/ip", limit: Rack::Attack::GENERAL_LIMIT, period: Rack::Attack::GENERAL_PERIOD) do |req|
+  Rack::Attack.counted_ip(req)
 end
 
 # Login throttle: 5 attempts per 20 seconds per IP
-Rack::Attack.throttle("login/ip", limit: 5, period: 20.seconds) do |req|
-  req.ip if req.path == "/session" && req.post?
+Rack::Attack.throttle("login/ip", limit: Rack::Attack::LOGIN_LIMIT, period: Rack::Attack::LOGIN_PERIOD) do |req|
+  req.ip if req.path == Rack::Attack::LOGIN_PATH && req.post?
 end
 
 # ---------------------------------------------------------------------------
@@ -93,3 +161,17 @@ end
 Rack::Attack.blocklisted_responder = lambda do |_request|
   [403, {"content-type" => "text/plain"}, ["Forbidden\n"]]
 end
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+
+# Every refused request is logged with its IP — the only trace it leaves in the
+# app's log. Safelist matches stay silent.
+ActiveSupport::Notifications.subscribe("rack.attack") do |_name, _start, _finish, _id, payload|
+  req = payload[:request]
+  match_type = req.env["rack.attack.match_type"]
+  next unless %i[blocklist throttle].include?(match_type)
+
+  Rails.logger.warn "[ATTACK] #{match_type} #{req.env["rack.attack.matched"]} #{req.ip} #{req.request_method} #{req.path}"
+end

data/lib/generators/maquina/security/USAGE

@@ -0,0 +1,15 @@
+Description:
+  Records every Rack::Attack refusal as a Security::AbuseEvent in its own
+  `security` database and shows the last week on a backstage page.
+
+  Installs the maquina:rack_attack rules unless the initializer already
+  defines Rack::Attack.banned?, plus the recording subscriber, models,
+  db/security_schema.rb, the `security` database entries, a daily purge in
+  config/recurring.yml, and the controller, layout, views, route and admin
+  navigation tab. The page is behind the backstage Basic Auth and answers
+  503 until credentials are set.
+
+Examples:
+  rails g maquina:security --prefix /admin
+  rails g maquina:security --prefix /admin --login-path /sign_in
+  rails g maquina:security --prefix /admin --no-copy-views

data/lib/generators/maquina/security/security_generator.rb

@@ -0,0 +1,278 @@
+require "rails/generators"
+require "generators/maquina/rack_attack/rack_attack_generator"
+
+module Maquina
+  module Generators
+    class SecurityGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      ENVIRONMENTS = %w[development test production].freeze
+      # The end of the Jobs tab in the generated admin navigation: a new tab
+      # goes after it.
+      JOBS_TAB_END = %r{<span>Jobs</span>\n\s*<% end %>\n}
+
+      class_option :prefix, type: :string, required: true,
+        desc: "Base path prefix (e.g. /admin)"
+      class_option :user_env_var, type: :string, default: "SECURITY_USER",
+        desc: "Environment variable for HTTP auth username"
+      class_option :password_env_var, type: :string, default: "SECURITY_PASSWORD",
+        desc: "Environment variable for HTTP auth password"
+      class_option :login_path, type: :string, default: "/session",
+        desc: "Path whose POSTs the login throttle counts"
+      class_option :copy_views, type: :boolean, default: true,
+        desc: "Copy the Security dashboard views to the host app"
+      class_option :quiet, type: :boolean, default: false,
+        desc: "Suppress post-install instructions"
+
+      # 1. BackstageController
+      def create_backstage_controller
+        backstage_path = "app/controllers/backstage_controller.rb"
+        return if File.exist?(File.join(destination_root, backstage_path))
+
+        template "app/controllers/backstage_controller.rb.tt", backstage_path
+      end
+
+      # 2. Rack::Attack rules (maquina:rack_attack) and the recording subscriber
+      def install_rack_attack
+        initializer = File.join(destination_root, "config/initializers/rack_attack.rb")
+        current = File.exist?(initializer) ? File.read(initializer) : nil
+
+        unless current&.include?("def self.banned?")
+          @replaced_rack_attack = !current.nil?
+          invoke RackAttackGenerator, [],
+            login_path: options[:login_path], quiet: true, force: @replaced_rack_attack
+        end
+
+        copy_file "config/initializers/rack_attack_events.rb",
+          "config/initializers/rack_attack_events.rb"
+      end
+
+      # 3. Models
+      def create_models
+        %w[record abuse_event abuse_report].each do |name|
+          copy_file "app/models/security/#{name}.rb", "app/models/security/#{name}.rb"
+        end
+      end
+
+      # 4. Schema for the security database
+      def create_schema
+        template "db/security_schema.rb.tt", "db/security_schema.rb"
+      end
+
+      # 5. database.yml (and its example) gain a security database
+      def configure_database
+        %w[config/database.yml config/database.yml.example].each do |path|
+          add_security_database(path)
+        end
+      end
+
+      # 6. Daily purge of expired events
+      def add_recurring_purge
+        path = File.join(destination_root, "config/recurring.yml")
+        content = File.exist?(path) ? File.read(path) : ""
+        return if content.include?("purge_abuse_events")
+
+        if content.match?(/^production:\n/)
+          inject_into_file "config/recurring.yml", recurring_entry, after: /^production:\n/
+        else
+          @recurring_pending = true
+        end
+      end
+
+      # 7. Add gem to Gemfile
+      def add_gem
+        gemfile_path = File.join(destination_root, "Gemfile")
+        if File.exist?(gemfile_path)
+          content = File.read(gemfile_path)
+          unless content.include?('gem "rack-attack"')
+            append_to_file "Gemfile", "\ngem \"rack-attack\"\n"
+          end
+        end
+      end
+
+      # 8. Controller
+      def create_controller
+        template "app/controllers/backstage/security_controller.rb.tt",
+          "app/controllers/backstage/security_controller.rb"
+      end
+
+      # 9. Routes
+      def add_route
+        route %(get "#{options[:prefix]}/security", to: "backstage/security#show", as: :backstage_security)
+      end
+
+      # 10. Admin navigation
+      def create_admin_navigation
+        nav_path = "app/views/layouts/_admin_navigation.html.erb"
+        full_path = File.join(destination_root, nav_path)
+
+        unless File.exist?(full_path)
+          template "app/views/layouts/_admin_navigation.html.erb.tt", nav_path
+          return
+        end
+
+        content = File.read(full_path)
+        return if content.include?("#{options[:prefix]}/security")
+
+        if content.match?(JOBS_TAB_END)
+          inject_into_file nav_path, security_tab, after: JOBS_TAB_END
+        else
+          @nav_pending = true
+        end
+      end
+
+      # 11. Layout
+      def copy_layout
+        copy_file "app/views/layouts/backstage/security.html.erb",
+          "app/views/layouts/backstage/security.html.erb"
+      end
+
+      # 11b. Backstage dashboard — the Overview tab of the admin navigation.
+      #      Shared with solid_errors and mission_control_jobs, so every step
+      #      is guarded for when more than one of them runs.
+      def create_backstage_dashboard
+        install_backstage_dashboard
+      end
+
+      # 12. Views
+      def copy_views
+        return unless options[:copy_views]
+
+        view_files.each { |f| copy_file f, f }
+      end
+
+      # 13. Bundle install
+      def run_bundle_install
+        return unless rails_app?
+
+        Bundler.with_unbundled_env do
+          system("bundle install", chdir: destination_root)
+        end
+      end
+
+      # 14. Post-install message
+      def show_post_install
+        return if options[:quiet]
+
+        say ""
+        say "Security dashboard has been installed!", :green
+        say ""
+        say "Next steps:", :yellow
+        say "  - Create the security database: bin/rails db:prepare"
+        say "  - Set credentials: bin/rails credentials:edit"
+        say "    backstage:"
+        say "      username: your_user"
+        say "      password: your_password"
+        say "  - Or set ENV vars: #{options[:user_env_var]}, #{options[:password_env_var]}"
+        say "  - Visit #{options[:prefix]}/security"
+        if @replaced_rack_attack
+          say ""
+          say "config/initializers/rack_attack.rb was replaced with the maquina:rack_attack rules.", :yellow
+        end
+        if @recurring_pending
+          say ""
+          say "Add to config/recurring.yml under your production (or shared) key:", :yellow
+          say recurring_entry
+        end
+        if @database_pending
+          say ""
+          say "Add a `security` database to each environment in config/database.yml (migrations_paths: db/security_migrate).", :yellow
+        end
+        if @nav_pending
+          say ""
+          say "Add a Security tab linking to #{options[:prefix]}/security in app/views/layouts/_admin_navigation.html.erb", :yellow
+        end
+        say ""
+      end
+
+      private
+
+      def rails_app?
+        File.exist?(File.join(destination_root, "bin/rails"))
+      end
+
+      # Idempotent install of the shared backstage dashboard (controller, layout,
+      # prefix-aware view, and the prefix-root route). Safe to run from this
+      # generator, solid_errors and mission_control_jobs.
+      def install_backstage_dashboard
+        unless File.exist?(File.join(destination_root, "app/controllers/backstage_dashboard_controller.rb"))
+          copy_file "app/controllers/backstage_dashboard_controller.rb",
+            "app/controllers/backstage_dashboard_controller.rb"
+        end
+
+        unless File.exist?(File.join(destination_root, "app/views/layouts/admin.html.erb"))
+          copy_file "app/views/layouts/admin.html.erb", "app/views/layouts/admin.html.erb"
+        end
+
+        unless File.exist?(File.join(destination_root, "app/views/backstage_dashboard/index.html.erb"))
+          template "app/views/backstage_dashboard/index.html.erb.tt",
+            "app/views/backstage_dashboard/index.html.erb"
+        end
+
+        routes_path = File.join(destination_root, "config/routes.rb")
+        if File.exist?(routes_path) && !File.read(routes_path).include?("backstage_dashboard#index")
+          route %(get "#{options[:prefix]}" => "backstage_dashboard#index", as: :backstage_dashboard)
+        end
+      end
+
+      def view_files
+        views_dir = File.join(self.class.source_root, "app/views/backstage/security")
+        Dir.glob("**/*.erb", base: views_dir).map do |file|
+          File.join("app/views/backstage/security", file)
+        end
+      end
+
+      def recurring_entry
+        <<~YAML.gsub(/^/, "  ")
+          purge_abuse_events:
+            command: "Security::AbuseEvent.expired.delete_all"
+            schedule: every day at 4am
+        YAML
+      end
+
+      def security_tab
+        <<-ERB
+
+          <%= link_to "#{options[:prefix]}/security",
+              class: "inline-flex items-center gap-1.5 whitespace-nowrap px-1 py-3 text-sm font-medium \#{request.path.start_with?('#{options[:prefix]}/security') ? 'border-b-2 border-primary text-primary' : 'text-muted-foreground hover:text-foreground'}" do %>
+            <%= icon_for(:slash, class: "size-4") %>
+            <span>Security</span>
+          <% end %>
+        ERB
+      end
+
+      # Appends a `security:` entry to each environment. A single-database
+      # SQLite environment (Rails' default for development and test) is first
+      # nested under `primary:`, which is the same database under a name.
+      # Any other adapter is left for the app to configure.
+      def add_security_database(path)
+        full_path = File.join(destination_root, path)
+        return unless File.exist?(full_path)
+
+        ENVIRONMENTS.each do |env|
+          content = File.read(full_path)
+          block = content[/^#{env}:\n(?:(?: .*)?\n)*?(?=\n*(?:^\S|\z))/]
+          next if block.nil? || block.include?("  security:")
+
+          if block.include?("  primary:")
+            inject_into_file path, security_entry(env), after: block
+          elsif content.include?("adapter: sqlite3")
+            primary = block.sub(/\A#{env}:\n/, "").gsub(/^(?=.)/, "  ")
+            gsub_file(path, block) { "#{env}:\n  primary:\n#{primary}#{security_entry(env)}" }
+          else
+            @database_pending = true
+          end
+        end
+      end
+
+      def security_entry(env)
+        <<~YAML.gsub(/^/, "  ")
+          security:
+            <<: *default
+            database: storage/#{env}_security.sqlite3
+            migrations_paths: db/security_migrate
+        YAML
+      end
+    end
+  end
+end

data/lib/generators/maquina/security/templates/app/controllers/backstage/security_controller.rb.tt

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Rack::Attack's last week, read from the `security` database. Behind the same
+# backstage Basic Auth as Solid Errors and Mission Control Jobs, and closed
+# (503) until those credentials are configured, so it is never left open.
+class Backstage::SecurityController < BackstageController
+  layout "backstage/security"
+
+  before_action :require_backstage_credentials
+  before_action :authenticate
+
+  def show
+    @report = Security::AbuseReport.new
+  end
+
+  private
+
+  def authenticate
+    authenticate_or_request_with_http_basic("Backstage") do |user, pass|
+      secure_match?(user, backstage_username) & secure_match?(pass, backstage_password)
+    end
+  end
+
+  def require_backstage_credentials
+    return if backstage_username.present? && backstage_password.present?
+
+    head :service_unavailable
+  end
+
+  def secure_match?(given, expected)
+    ActiveSupport::SecurityUtils.secure_compare(given.to_s, expected.to_s)
+  end
+
+  def backstage
+    @backstage ||= Rails.application.credentials.backstage || {}
+  end
+
+  def backstage_username
+    backstage[:username] || ENV["<%= options[:user_env_var] %>"]
+  end
+
+  def backstage_password
+    backstage[:password] || ENV["<%= options[:password_env_var] %>"]
+  end
+end

data/{test/tmp/app/controllers/backstage_controller.rb → lib/generators/maquina/security/templates/app/controllers/backstage_controller.rb.tt}

@@ -4,5 +4,4 @@ class BackstageController < ActionController::Base
   helper MaquinaComponents::IconsHelper
   helper MaquinaComponents::EmptyHelper
   helper MaquinaComponentsHelper
-  helper SolidErrorsHelper
 end

data/lib/generators/maquina/security/templates/app/controllers/backstage_dashboard_controller.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Admin overview — a backstage surface alongside the SolidErrors and Mission
+# Control Jobs engines, under the same backstage Basic auth.
+#
+# Out of the box it shows the installed engine entry points and an empty metrics
+# area. Populate @metrics in #index with aggregate, non-sensitive counts for
+# your app — counts, not names or per-record detail.
+class BackstageDashboardController < BackstageController
+  layout "admin"
+
+  before_action :require_backstage_credentials
+  before_action :authenticate_backstage
+
+  def index
+    @generated_at = Time.current
+
+    # Add overview metrics here. Each entry renders as a card:
+    #
+    #   @metrics = [
+    #     {label: "Accounts", icon: :folder, value: Account.count, hint: "tenants"},
+    #     {label: "Users", icon: :user, value: User.count, hint: "members"}
+    #   ]
+    #
+    # Keep them aggregate-only. :total and :hint are optional.
+    @metrics = []
+  end
+
+  private
+
+  # Closed (503) until credentials.backstage is set. Without this an unset
+  # username and password are both "", and an empty Basic header matches them.
+  def require_backstage_credentials
+    backstage = Rails.application.credentials.backstage || {}
+    head :service_unavailable if backstage[:username].blank? || backstage[:password].blank?
+  end
+
+  # Same backstage credentials the engines use.
+  def authenticate_backstage
+    authenticate_or_request_with_http_basic("Admin") do |username, password|
+      backstage = Rails.application.credentials.backstage || {}
+
+      ActiveSupport::SecurityUtils.secure_compare(username.to_s, backstage[:username].to_s) &
+        ActiveSupport::SecurityUtils.secure_compare(password.to_s, backstage[:password].to_s)
+    end
+  end
+end

data/lib/generators/maquina/security/templates/app/models/security/abuse_event.rb

@@ -0,0 +1,36 @@
+# One refused request, as Rack::Attack saw it. Rows are written by the
+# `rack.attack` subscriber in config/initializers/rack_attack_events.rb and never
+# updated — the table is the record of who was throttled or blocked, which
+# the middleware otherwise leaves nowhere (it answers ahead of Rails, so the
+# request log never sees these, and the cache's counters expire in minutes).
+#
+# `kind` is decided at write time: a throttle is `throttled`; a scanner path is
+# `blocked` until the address's ban is written (Fail2Ban's third strike within
+# its window), after which every refused request from it is `banned` — so the
+# set of banned addresses is exact, not inferred from counts.
+class Security::AbuseEvent < Security::Record
+  # Read from here everywhere the retention is stated (config/recurring.yml
+  # sweeps `expired`), so the promise and the clock cannot drift.
+  RETENTION = 30.days
+
+  KINDS = %w[throttled blocked banned].freeze
+
+  PATH_LIMIT = 1024
+  USER_AGENT_LIMIT = 512
+
+  validates :kind, inclusion: {in: KINDS}
+  validates :rule, :ip, :request_method, :path, presence: true
+
+  scope :recent, -> { order(created_at: :desc, id: :desc) }
+  scope :within, ->(window) { where(created_at: window.ago..) }
+  scope :expired, -> { where(created_at: ...RETENTION.ago) }
+  scope :throttled, -> { where(kind: "throttled") }
+  scope :blocked, -> { where(kind: %w[blocked banned]) }
+  scope :banned, -> { where(kind: "banned") }
+
+  def self.record!(kind:, rule:, ip:, request_method:, path:, host: nil, user_agent: nil)
+    create!(kind:, rule:, ip:, request_method:, host:,
+      path: path.to_s.truncate(PATH_LIMIT, omission: ""),
+      user_agent: user_agent&.truncate(USER_AGENT_LIMIT, omission: ""))
+  end
+end