maquina-generators 0.5.0 → 0.7.0

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

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

@@ -0,0 +1,112 @@
+# What the backstage Security page shows: the last `window` of Rack::Attack refusals,
+# summarised to the top `limit` of each thing worth knowing. A briefing, not a
+# log viewer — no filters, no pagination; the recent list is the drill-down.
+#
+# `banned:` answers whether an address is banned right now, and `scanner_path:`
+# whether a path is one the scanner ban counts. Both default to Rack::Attack's
+# own answer and are kwargs so a test can hand in a Set.
+class Security::AbuseReport
+  Address = Data.define(:ip, :count, :rules, :last_seen)
+  BlockedAddress = Data.define(:ip, :count, :first_banned_at, :banned_now) do
+    alias_method :banned_now?, :banned_now
+
+    def banned? = first_banned_at.present?
+  end
+  Path = Data.define(:path, :count, :addresses)
+  Host = Data.define(:host, :count)
+  Day = Data.define(:date, :throttled, :blocked, :banned) do
+    def total = throttled + blocked + banned
+  end
+
+  RECENT_LIMIT = 20
+  SIGN_IN_RULE = "login/ip"
+
+  attr_reader :window, :limit
+
+  def initialize(window: 7.days, limit: 5, banned: ->(ip) { Rack::Attack.banned?(ip) },
+    scanner_path: ->(path) { Rack::Attack.scanner_path?(path) })
+    @window = window
+    @limit = limit
+    @banned = banned
+    @scanner_path = scanner_path
+  end
+
+  def events = Security::AbuseEvent.within(window)
+
+  def empty? = events.none?
+
+  def total = events.count
+
+  def throttled_total = events.throttled.count
+
+  def blocked_total = events.blocked.count
+
+  def addresses_total = events.distinct.count(:ip)
+
+  # Addresses the general and sign-in throttles refused, busiest first.
+  def throttled_addresses = addresses(events.throttled)
+
+  # Addresses refused on the sign-in path — the throttle with a security
+  # meaning, kept apart so scanner noise never buries it.
+  def sign_in_throttles = addresses(events.where(rule: SIGN_IN_RULE))
+
+  # Addresses a blocklist refused, busiest first: the banned ones with when the
+  # ban was written, and those still short of a ban (a strike or two on the
+  # scanner rule) without it.
+  def blocked_addresses
+    events.blocked.group(:ip).order(Arel.sql("COUNT(*) DESC, MAX(created_at) DESC")).limit(limit)
+      .pluck(:ip, Arel.sql("COUNT(*)"), Arel.sql("MIN(CASE WHEN kind = 'banned' THEN created_at END)"))
+      .map { |ip, count, first| BlockedAddress.new(ip:, count:, first_banned_at: parse_time(first), banned_now: @banned.call(ip)) }
+  end
+
+  # What the scanners were after. A banned address is refused on every path,
+  # its ordinary requests (`/`, `/up`) included, so the paths are kept to the
+  # ones the scanner rule counts. That is a Ruby test, not SQL, so every blocked
+  # path is read and the first `limit` scanner paths kept.
+  def scanner_paths
+    events.blocked.group(:path).order(Arel.sql("COUNT(*) DESC, path ASC"))
+      .pluck(:path, Arel.sql("COUNT(*)"), Arel.sql("COUNT(DISTINCT ip)"))
+      .select { |path, _, _| @scanner_path.call(path) }.first(limit)
+      .map { |path, count, addresses| Path.new(path:, count:, addresses:) }
+  end
+
+  # Which hostnames took the refusals.
+  def targeted_hosts
+    events.where.not(host: nil).group(:host).order(Arel.sql("COUNT(*) DESC, host ASC")).limit(limit)
+      .pluck(:host, Arel.sql("COUNT(*)"))
+      .map { |host, count| Host.new(host:, count:) }
+  end
+
+  # One row per day of the window, today last, zeros kept so a spike reads
+  # against its neighbours.
+  def by_day
+    counts = events.group(:kind, Arel.sql("date(created_at)")).count
+    days = (window.ago.to_date..Date.current).to_a.last((window / 1.day).ceil)
+
+    days.map do |date|
+      key = date.iso8601
+      Day.new(date:, throttled: counts.fetch(["throttled", key], 0),
+        blocked: counts.fetch(["blocked", key], 0), banned: counts.fetch(["banned", key], 0))
+    end
+  end
+
+  def recent = events.recent.limit(RECENT_LIMIT)
+
+  private
+
+  # The rules come from a second query rather than GROUP_CONCAT, which only
+  # SQLite and MySQL spell that way.
+  def addresses(scope)
+    rows = scope.group(:ip).order(Arel.sql("COUNT(*) DESC, MAX(created_at) DESC")).limit(limit)
+      .pluck(:ip, Arel.sql("COUNT(*)"), Arel.sql("MAX(created_at)"))
+    rules = scope.where(ip: rows.map(&:first)).distinct.order(:rule).pluck(:ip, :rule)
+      .group_by(&:first).transform_values { |pairs| pairs.map(&:last) }
+
+    rows.map { |ip, count, last| Address.new(ip:, count:, rules: rules.fetch(ip, []), last_seen: parse_time(last)) }
+  end
+
+  # SQLite hands an aggregate over a datetime column back as a string.
+  def parse_time(value)
+    value.is_a?(String) ? Time.zone.parse(value) : value
+  end
+end

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

@@ -0,0 +1,6 @@
+# Base for everything in the `security` database (db/security_schema.rb).
+class Security::Record < ActiveRecord::Base
+  self.abstract_class = true
+
+  connects_to database: {writing: :security}
+end

data/lib/generators/maquina/security/templates/app/views/backstage/security/_addresses.html.erb

@@ -0,0 +1,37 @@
+<%# locals: (title:, description:, addresses:, empty:) %>
+<%= render "components/card" do %>
+  <%= render "components/card/header" do %>
+    <%= render "components/card/title", text: title %>
+    <%= render "components/card/description", text: description %>
+  <% end %>
+  <%= render "components/card/content", spacing: :full do %>
+    <% if addresses.empty? %>
+      <%= empty_state(title: empty, icon: :check_circle, size: :compact) %>
+    <% else %>
+      <div class="overflow-x-auto">
+        <%= render "components/table", container: false, "aria-label": title do %>
+          <%= render "components/table/header" do %>
+            <%= render "components/table/row" do %>
+              <%= render "components/table/head", text: "Address" %>
+              <%= render "components/table/head", text: "Refused", css_classes: "text-right" %>
+              <%= render "components/table/head", text: "Rules" %>
+              <%= render "components/table/head", text: "Last seen" %>
+            <% end %>
+          <% end %>
+          <%= render "components/table/body" do %>
+            <% addresses.each do |address| %>
+              <%= render "components/table/row" do %>
+                <%= render "components/table/cell", css_classes: "font-mono", text: address.ip %>
+                <%= render "components/table/cell", css_classes: "text-right tabular-nums", text: number_with_delimiter(address.count) %>
+                <%= render "components/table/cell", text: address.rules.join(", ") %>
+                <%= render "components/table/cell" do %>
+                  <%= render "backstage/security/utc_time", time: address.last_seen %>
+                <% end %>
+              <% end %>
+            <% end %>
+          <% end %>
+        <% end %>
+      </div>
+    <% end %>
+  <% end %>
+<% end %>

data/lib/generators/maquina/security/templates/app/views/backstage/security/_blocked.html.erb

@@ -0,0 +1,53 @@
+<%# locals: (addresses:) %>
+<%# "Banned now" is Rack::Attack's own answer at render time; the rows are the
+    refusals recorded by a blocklist, so an expired ban still shows here for
+    the week with its badge flipped, and an address short of a ban shows as
+    not banned. %>
+<%= render "components/card" do %>
+  <%= render "components/card/header" do %>
+    <%= render "components/card/title", text: "Blocked addresses" %>
+    <%= render "components/card/description", text: "#{Rack::Attack::SCANNER_MAXRETRY} scanner paths in #{Rack::Attack::SCANNER_FINDTIME.inspect} bans an address for #{Rack::Attack::SCANNER_BANTIME.inspect}; #{Rack::Attack::FLOOD_MAXRETRY} requests in #{Rack::Attack::GENERAL_PERIOD.inspect}, for #{Rack::Attack::FLOOD_BANTIME.inspect}." %>
+  <% end %>
+  <%= render "components/card/content", spacing: :full do %>
+    <% if addresses.empty? %>
+      <%= empty_state(title: "No address has been blocked.", icon: :check_circle, size: :compact) %>
+    <% else %>
+      <div class="overflow-x-auto">
+        <%= render "components/table", container: false, "aria-label": "Blocked addresses" do %>
+          <%= render "components/table/header" do %>
+            <%= render "components/table/row" do %>
+              <%= render "components/table/head", text: "Address" %>
+              <%= render "components/table/head", text: "Refused", css_classes: "text-right" %>
+              <%= render "components/table/head", text: "Banned" %>
+              <%= render "components/table/head", text: "Since" %>
+            <% end %>
+          <% end %>
+          <%= render "components/table/body" do %>
+            <% addresses.each do |address| %>
+              <%= render "components/table/row" do %>
+                <%= render "components/table/cell", css_classes: "font-mono", text: address.ip %>
+                <%= render "components/table/cell", css_classes: "text-right tabular-nums", text: number_with_delimiter(address.count) %>
+                <%= render "components/table/cell" do %>
+                  <% if address.banned_now? %>
+                    <%= render "components/badge", variant: :destructive, size: :sm do %>Banned now<% end %>
+                  <% elsif address.banned? %>
+                    <%= render "components/badge", variant: :outline, size: :sm do %>Expired<% end %>
+                  <% else %>
+                    <%= render "components/badge", variant: :secondary, size: :sm do %>Not banned<% end %>
+                  <% end %>
+                <% end %>
+                <%= render "components/table/cell" do %>
+                  <% if address.banned? %>
+                    <%= render "backstage/security/utc_time", time: address.first_banned_at %>
+                  <% else %>
+                    <span class="text-muted-foreground">—</span>
+                  <% end %>
+                <% end %>
+              <% end %>
+            <% end %>
+          <% end %>
+        <% end %>
+      </div>
+    <% end %>
+  <% end %>
+<% end %>

data/lib/generators/maquina/security/templates/app/views/backstage/security/_by_day.html.erb

@@ -0,0 +1,33 @@
+<%# locals: (days:) %>
+<%= render "components/card" do %>
+  <%= render "components/card/header" do %>
+    <%= render "components/card/title", text: "By day" %>
+    <%= render "components/card/description", text: "Zeros kept, so a spike reads against its neighbours." %>
+  <% end %>
+  <%= render "components/card/content", spacing: :full do %>
+    <div class="overflow-x-auto">
+      <%= render "components/table", container: false, "aria-label": "Refusals by day" do %>
+        <%= render "components/table/header" do %>
+          <%= render "components/table/row" do %>
+            <%= render "components/table/head", text: "Day" %>
+            <%= render "components/table/head", text: "Throttled", css_classes: "text-right" %>
+            <%= render "components/table/head", text: "Blocked", css_classes: "text-right" %>
+            <%= render "components/table/head", text: "Banned", css_classes: "text-right" %>
+          <% end %>
+        <% end %>
+        <%= render "components/table/body" do %>
+          <% days.each do |day| %>
+            <%= render "components/table/row" do %>
+              <%= render "components/table/cell" do %>
+                <time datetime="<%= day.date.iso8601 %>"><%= day.date.strftime("%a %-d %b") %></time>
+              <% end %>
+              <%= render "components/table/cell", css_classes: "text-right tabular-nums", text: number_with_delimiter(day.throttled) %>
+              <%= render "components/table/cell", css_classes: "text-right tabular-nums", text: number_with_delimiter(day.blocked) %>
+              <%= render "components/table/cell", css_classes: "text-right tabular-nums", text: number_with_delimiter(day.banned) %>
+            <% end %>
+          <% end %>
+        <% end %>
+      <% end %>
+    </div>
+  <% end %>
+<% end %>

data/lib/generators/maquina/security/templates/app/views/backstage/security/_hosts.html.erb

@@ -0,0 +1,31 @@
+<%# locals: (hosts:) %>
+<%= render "components/card" do %>
+  <%= render "components/card/header" do %>
+    <%= render "components/card/title", text: "Targeted hosts" %>
+    <%= render "components/card/description", text: "Which hostnames the refused requests were aimed at." %>
+  <% end %>
+  <%= render "components/card/content", spacing: :full do %>
+    <% if hosts.empty? %>
+      <%= empty_state(title: "No host recorded.", icon: :check_circle, size: :compact) %>
+    <% else %>
+      <div class="overflow-x-auto">
+        <%= render "components/table", container: false, "aria-label": "Targeted hosts" do %>
+          <%= render "components/table/header" do %>
+            <%= render "components/table/row" do %>
+              <%= render "components/table/head", text: "Host" %>
+              <%= render "components/table/head", text: "Refused", css_classes: "text-right" %>
+            <% end %>
+          <% end %>
+          <%= render "components/table/body" do %>
+            <% hosts.each do |host| %>
+              <%= render "components/table/row" do %>
+                <%= render "components/table/cell", css_classes: "font-mono", text: host.host %>
+                <%= render "components/table/cell", css_classes: "text-right tabular-nums", text: number_with_delimiter(host.count) %>
+              <% end %>
+            <% end %>
+          <% end %>
+        <% end %>
+      </div>
+    <% end %>
+  <% end %>
+<% end %>

data/lib/generators/maquina/security/templates/app/views/backstage/security/_paths.html.erb

@@ -0,0 +1,33 @@
+<%# locals: (paths:) %>
+<%= render "components/card" do %>
+  <%= render "components/card/header" do %>
+    <%= render "components/card/title", text: "Most requested blocked paths" %>
+    <%= render "components/card/description", text: "What the scanners were after." %>
+  <% end %>
+  <%= render "components/card/content", spacing: :full do %>
+    <% if paths.empty? %>
+      <%= empty_state(title: "No scanner path was requested.", icon: :check_circle, size: :compact) %>
+    <% else %>
+      <div class="overflow-x-auto">
+        <%= render "components/table", container: false, "aria-label": "Most requested blocked paths" do %>
+          <%= render "components/table/header" do %>
+            <%= render "components/table/row" do %>
+              <%= render "components/table/head", text: "Path" %>
+              <%= render "components/table/head", text: "Requests", css_classes: "text-right" %>
+              <%= render "components/table/head", text: "Addresses", css_classes: "text-right" %>
+            <% end %>
+          <% end %>
+          <%= render "components/table/body" do %>
+            <% paths.each do |path| %>
+              <%= render "components/table/row" do %>
+                <%= render "components/table/cell", css_classes: "font-mono whitespace-normal break-all", text: path.path %>
+                <%= render "components/table/cell", css_classes: "text-right tabular-nums", text: number_with_delimiter(path.count) %>
+                <%= render "components/table/cell", css_classes: "text-right tabular-nums", text: number_with_delimiter(path.addresses) %>
+              <% end %>
+            <% end %>
+          <% end %>
+        <% end %>
+      </div>
+    <% end %>
+  <% end %>
+<% end %>

data/lib/generators/maquina/security/templates/app/views/backstage/security/_recent.html.erb

@@ -0,0 +1,37 @@
+<%# locals: (events:) %>
+<%= render "components/card" do %>
+  <%= render "components/card/header" do %>
+    <%= render "components/card/title", text: "Recent refusals" %>
+    <%= render "components/card/description", text: "The last #{Security::AbuseReport::RECENT_LIMIT}, newest first." %>
+  <% end %>
+  <%= render "components/card/content", spacing: :full do %>
+    <div class="overflow-x-auto">
+      <%= render "components/table", container: false, "aria-label": "Recent refusals" do %>
+        <%= render "components/table/header" do %>
+          <%= render "components/table/row" do %>
+            <%= render "components/table/head", text: "When" %>
+            <%= render "components/table/head", text: "Kind" %>
+            <%= render "components/table/head", text: "Address" %>
+            <%= render "components/table/head", text: "Request" %>
+          <% end %>
+        <% end %>
+        <%= render "components/table/body" do %>
+          <% events.each do |event| %>
+            <%= render "components/table/row" do %>
+              <%= render "components/table/cell" do %>
+                <%= render "backstage/security/utc_time", time: event.created_at %>
+              <% end %>
+              <%= render "components/table/cell" do %>
+                <%= render "components/badge", variant: {"banned" => :destructive, "blocked" => :warning}.fetch(event.kind, :secondary), size: :sm do %><%= event.kind %><% end %>
+              <% end %>
+              <%= render "components/table/cell", css_classes: "font-mono", text: event.ip %>
+              <%= render "components/table/cell", css_classes: "font-mono whitespace-normal break-all" do %>
+                <span class="text-muted-foreground"><%= event.request_method %></span> <%= event.path %>
+              <% end %>
+            <% end %>
+          <% end %>
+        <% end %>
+      <% end %>
+    </div>
+  <% end %>
+<% end %>

data/lib/generators/maquina/security/templates/app/views/backstage/security/_utc_time.html.erb

@@ -0,0 +1,2 @@
+<%# locals: (time:) %>
+<time datetime="<%= time.utc.iso8601 %>" title="<%= time.utc.iso8601 %>" class="whitespace-nowrap tabular-nums"><%= time.utc.strftime("%-d %b %H:%M") %></time>

data/lib/generators/maquina/security/templates/app/views/backstage/security/show.html.erb

@@ -0,0 +1,47 @@
+<% content_for :title, "Security" %>
+<%# Rack::Attack's last week, top five of each. Every number is read from
+    Security::AbuseEvent through Security::AbuseReport; the page holds no
+    arithmetic of its own. Times are UTC: a log reads better in one clock. %>
+<div class="py-8 space-y-8">
+  <div>
+    <h1 class="text-2xl text-foreground">Security</h1>
+    <p class="mt-1 text-sm text-muted-foreground">
+      Requests Rack::Attack refused in the last <%= @report.window.inspect %>, kept for <%= Security::AbuseEvent::RETENTION.inspect %>. Times are UTC.
+    </p>
+  </div>
+
+  <% if @report.empty? %>
+    <%= empty_state(title: "Nothing refused this week",
+          description: "No request has been throttled or blocked in the last #{@report.window.inspect}.",
+          icon: :check_circle, size: :default) %>
+  <% else %>
+    <%# Built-in icon names only: the stats card renders through
+        `builtin_icon_for`, which never consults the app's override set. %>
+    <%= render "components/stats/stats_grid", columns: 4, cards: [
+          {title: "Refused requests", value: number_with_delimiter(@report.total), icon: :slash},
+          {title: "Throttled", value: number_with_delimiter(@report.throttled_total), icon: :clock},
+          {title: "Blocked or banned", value: number_with_delimiter(@report.blocked_total), icon: :triangle_alert},
+          {title: "Addresses", value: number_with_delimiter(@report.addresses_total), icon: :users}
+        ] %>
+
+    <div class="grid grid-cols-1 gap-6 lg:grid-cols-2">
+      <%= render "backstage/security/addresses", title: "Throttled addresses",
+            description: "Over the general and sign-in limits, busiest first.",
+            addresses: @report.throttled_addresses, empty: "No address was throttled." %>
+
+      <%= render "backstage/security/blocked", addresses: @report.blocked_addresses %>
+
+      <%= render "backstage/security/paths", paths: @report.scanner_paths %>
+
+      <%= render "backstage/security/addresses", title: "Sign-in throttles",
+            description: "Addresses refused on POST #{Rack::Attack::LOGIN_PATH} — #{Rack::Attack::LOGIN_LIMIT} attempts in #{Rack::Attack::LOGIN_PERIOD.inspect}.",
+            addresses: @report.sign_in_throttles, empty: "No one has been throttled on sign-in." %>
+
+      <%= render "backstage/security/hosts", hosts: @report.targeted_hosts %>
+
+      <%= render "backstage/security/by_day", days: @report.by_day %>
+    </div>
+
+    <%= render "backstage/security/recent", events: @report.recent %>
+  <% end %>
+</div>

data/lib/generators/maquina/security/templates/app/views/backstage_dashboard/index.html.erb.tt

@@ -0,0 +1,93 @@
+<div class="py-8">
+  <!-- Header -->
+  <div class="mb-6 flex items-end justify-between border-b border-border pb-4">
+    <h1 class="text-2xl font-bold text-foreground">Overview</h1>
+    <%% if @generated_at %>
+      <p class="font-mono text-[11px] tabular-nums text-muted-foreground">as of <%%= @generated_at.strftime("%H:%M %Z") %></p>
+    <%% end %>
+  </div>
+
+  <!-- Metrics: populate @metrics in BackstageDashboardController#index. Aggregate-only. -->
+  <%% if @metrics.present? %>
+    <div class="grid grid-cols-2 gap-4 lg:grid-cols-4">
+      <%% @metrics.each do |metric| %>
+        <%%= render "components/card" do %>
+          <div class="px-5 py-4">
+            <div class="mb-2 flex items-center gap-1.5 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
+              <%% if metric[:icon] %><%%= icon_for(metric[:icon], class: "size-3.5") %><%% end %>
+              <%%= metric[:label] %>
+            </div>
+            <div class="font-display text-4xl font-semibold tabular-nums text-foreground">
+              <%%= number_with_delimiter(metric[:value]) %><%% if metric[:total] %><span class="text-xl text-muted-foreground">/<%%= number_with_delimiter(metric[:total]) %></span><%% end %>
+            </div>
+            <%% if metric[:hint] %>
+              <div class="mt-1 text-[11px] tabular-nums text-muted-foreground"><%%= metric[:hint] %></div>
+            <%% end %>
+          </div>
+        <%% end %>
+      <%% end %>
+    </div>
+  <%% else %>
+    <%%= empty_state(
+      title: "No metrics yet",
+      description: "Add aggregate counts in BackstageDashboardController#index to populate this overview.",
+      icon: :layout_dashboard,
+      size: :default
+    ) %>
+  <%% end %>
+
+  <!-- Operations: entry points to the installed engines -->
+  <h2 class="mt-10 mb-3 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">Operations</h2>
+  <div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
+    <%% if defined?(SolidErrors::Engine) %>
+      <%%= link_to "<%= options[:prefix] %>/errors", class: "group block" do %>
+        <%%= render "components/card", css_classes: "transition-shadow hover:shadow-md" do %>
+          <div class="flex items-center gap-4 px-5 py-4">
+            <span class="inline-flex size-10 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
+              <%%= icon_for(:triangle_alert, class: "size-5") %>
+            </span>
+            <div class="min-w-0 flex-1">
+              <div class="font-semibold text-foreground">Errors</div>
+              <div class="text-sm text-muted-foreground">Exceptions, backtraces, and resolution</div>
+            </div>
+            <%%= icon_for(:arrow_right, class: "size-4 text-muted-foreground transition-transform group-hover:translate-x-0.5") %>
+          </div>
+        <%% end %>
+      <%% end %>
+    <%% end %>
+
+    <%% if defined?(MissionControl::Jobs::Engine) %>
+      <%%= link_to "<%= options[:prefix] %>/jobs", class: "group block" do %>
+        <%%= render "components/card", css_classes: "transition-shadow hover:shadow-md" do %>
+          <div class="flex items-center gap-4 px-5 py-4">
+            <span class="inline-flex size-10 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
+              <%%= icon_for(:inbox, class: "size-5") %>
+            </span>
+            <div class="min-w-0 flex-1">
+              <div class="font-semibold text-foreground">Background jobs</div>
+              <div class="text-sm text-muted-foreground">Queues, workers, and recurring tasks</div>
+            </div>
+            <%%= icon_for(:arrow_right, class: "size-4 text-muted-foreground transition-transform group-hover:translate-x-0.5") %>
+          </div>
+        <%% end %>
+      <%% end %>
+    <%% end %>
+
+    <%% if defined?(Security::AbuseEvent) %>
+      <%%= link_to "<%= options[:prefix] %>/security", class: "group block" do %>
+        <%%= render "components/card", css_classes: "transition-shadow hover:shadow-md" do %>
+          <div class="flex items-center gap-4 px-5 py-4">
+            <span class="inline-flex size-10 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
+              <%%= icon_for(:slash, class: "size-5") %>
+            </span>
+            <div class="min-w-0 flex-1">
+              <div class="font-semibold text-foreground">Security</div>
+              <div class="text-sm text-muted-foreground">Throttled, blocked, and banned requests</div>
+            </div>
+            <%%= icon_for(:arrow_right, class: "size-4 text-muted-foreground transition-transform group-hover:translate-x-0.5") %>
+          </div>
+        <%% end %>
+      <%% end %>
+    <%% end %>
+  </div>
+</div>

data/lib/generators/maquina/security/templates/app/views/layouts/_admin_navigation.html.erb.tt

@@ -0,0 +1,40 @@
+<nav class="border-b border-border bg-background">
+  <div class="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+    <div class="flex items-center justify-between h-12">
+      <div class="flex items-center gap-6">
+        <span class="text-sm font-semibold text-foreground">Admin</span>
+        <div class="-mb-px flex items-center space-x-4">
+          <%%= link_to "<%= options[:prefix] %>",
+              class: "inline-flex items-center gap-1.5 whitespace-nowrap px-1 py-3 text-sm font-medium #{request.path == '<%= options[:prefix] %>' ? 'border-b-2 border-primary text-primary' : 'text-muted-foreground hover:text-foreground'}" do %>
+            <%%= icon_for(:layout_dashboard, class: "size-4") %>
+            <span>Overview</span>
+          <%% end %>
+
+          <%%= link_to "<%= options[:prefix] %>/errors",
+              class: "inline-flex items-center gap-1.5 whitespace-nowrap px-1 py-3 text-sm font-medium #{request.path.start_with?('<%= options[:prefix] %>/errors') ? 'border-b-2 border-primary text-primary' : 'text-muted-foreground hover:text-foreground'}" do %>
+            <%%= icon_for(:triangle_alert, class: "size-4") %>
+            <span>Errors</span>
+          <%% end %>
+
+          <%%= link_to "<%= options[:prefix] %>/jobs",
+              class: "inline-flex items-center gap-1.5 whitespace-nowrap px-1 py-3 text-sm font-medium #{request.path.start_with?('<%= options[:prefix] %>/jobs') ? 'border-b-2 border-primary text-primary' : 'text-muted-foreground hover:text-foreground'}" do %>
+            <%%= icon_for(:inbox, class: "size-4") %>
+            <span>Jobs</span>
+          <%% end %>
+
+          <%%= 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 %>
+        </div>
+      </div>
+
+      <%%= link_to main_app.root_path,
+          class: "inline-flex items-center gap-2 text-sm text-muted-foreground hover:text-foreground transition-colors" do %>
+        <%%= icon_for(:arrow_left, class: "size-4") %>
+        Back to app
+      <%% end %>
+    </div>
+  </div>
+</nav>