bro_hub 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b1fbd1cddc86bdf0bc203daff3dbe7eab88f49d7046c2f7444b215b8a24ddee1
4
- data.tar.gz: 80a631c65cf8f57fca41e6c67b059a978aef763aa9fcdc1d386634b0bae43de7
3
+ metadata.gz: 4e8d9cfb095f79b5ea95e8deec476ac616aba2c0fe7f13d7d82729bd70eca0a3
4
+ data.tar.gz: bd8d3a62facfe12d4a8e5a8d0256e89decb3bc67df3b6e7f2dc4a57076ce7215
5
5
  SHA512:
6
- metadata.gz: 5fc326ddbfcb13bbb77adae1928de8a1cbbdff6ab454c1b8896ea81a3d8c0d08ff3ecea53ed75af1e47f5eecb0c9cbf8a2691066d6ffe66a76560234af9ac022
7
- data.tar.gz: 3cc2551c4d6cdf13fce248f5b18991bdfd9c1c54cc39bfa4983e815898ddeb322da844880e469a760e094d47974357b11a9968ff8a99c2835f0db6c8945f18f2
6
+ metadata.gz: 864864457131f346931a13f3f0b201a0f8909b9496e8a38f7f60c17dfbf246899d3ea244af8dab6f9d523e1f290327399406478e490bac667e08d1fc231599ef
7
+ data.tar.gz: 954605adda26754b49835be5187d452e82459478fa6d8b28e95e920b77bf56dbd77e10116cc45a8f19eda676f19730e5158ac07c6f878b50cc0071281a1433ea
data/README.md CHANGED
@@ -1,15 +1,16 @@
1
1
  # BroHub
2
2
 
3
- One dashboard shell for the Bro gems ([EnvBro](https://github.com/rubydevro/env_bro), [SafeBro](https://github.com/rubydevro/safe_bro), and whatever comes next).
3
+ One dashboard shell for the Bro gems ([EnvBro](https://github.com/rubydevro/env_bro), [SafeBro](https://github.com/rubydevro/safe_bro), [CacheBro](https://github.com/rubydevro/cache_bro), and whatever comes next).
4
4
 
5
5
  - **One mount point.** `/bro_hub/safe_bro`, `/bro_hub/env_bro`, ... BroHub mounts the gems' engines itself.
6
6
  - **One look.** Top bar, sidebar, breadcrumb bar and page styles are shared, so every gem feels the same.
7
7
  - **One sidebar.** Each gem registers its pages and shows up as a section. A section only appears for people allowed to use it.
8
8
  - **One place for "who is signed in".** Set it once for all gems.
9
+ - **One audit log.** Every Bro gem writes its audit trail to one table, and BroHub shows them together.
9
10
 
10
11
  It is a shell, not a security boundary: hiding a section is navigation. Every Bro gem still authorizes its own pages.
11
12
 
12
- Rails 7.1+, Ruby 3.2+. No database, no JavaScript, no asset pipeline.
13
+ Rails 7.1+, Ruby 3.2+. One table (the audit log), no JavaScript, no asset pipeline.
13
14
 
14
15
  ## Install
15
16
 
@@ -26,7 +27,7 @@ bin/rails generate bro_hub:install
26
27
 
27
28
  This sets up the whole dashboard in one go:
28
29
 
29
- 1. adds `config/initializers/bro_hub.rb`,
30
+ 1. adds `config/initializers/bro_hub.rb` and copies the audit table migration (run `bin/rails db:migrate` afterwards),
30
31
  2. mounts BroHub (it asks where, default `/bro_hub`; or `--mount-path=/ops/bro`):
31
32
  ```ruby
32
33
  mount BroHub::Engine => "/bro_hub"
@@ -56,6 +57,91 @@ end
56
57
 
57
58
  Opening `/bro_hub` sends people to the first section they may use.
58
59
 
60
+ ## The Bro gems
61
+
62
+ Each gem is a mountable Rails engine that registers itself with BroHub. Add the gems you want to your Gemfile and run
63
+ `bin/rails generate bro_hub:install`: BroHub finds every registered gem that ships an installer and runs it.
64
+
65
+ | Gem | Section | What it does |
66
+ | --- | --- | --- |
67
+ | [EnvBro](https://github.com/rubydevro/env_bro) | `/bro_hub/env_bro` | Credentials and environment values, with its own approval flow. |
68
+ | [SafeBro](https://github.com/rubydevro/safe_bro) | `/bro_hub/safe_bro` | Audits production console sessions: sessions, flagged commands, rules. |
69
+ | [CacheBro](https://github.com/rubydevro/cache_bro) | `/bro_hub/cache_bro` | Browse, inspect and purge the Rails Redis cache, with every action audited. |
70
+
71
+ ### How it fits together
72
+
73
+ 1. A gem calls `BroHub.register` in its engine, before routes are drawn. That adds its section to the sidebar and tells BroHub which engine to mount.
74
+ 2. BroHub mounts each registered engine under its own path (`<mount>/<key>`). You mount only `BroHub::Engine`.
75
+ 3. Gem controllers include `BroHub::ControllerBase` and name their section, so pages render inside the shared shell.
76
+ 4. Who is signed in comes from BroHub's `current_user` setting. Each gem keeps its own permissions, and a sidebar section only shows for people the gem allows.
77
+ 5. BroHub keeps one table, the shared audit log, in your app's database (its migration is copied by the installer). SafeBro also keeps its session tables.
78
+
79
+ ### CacheBro
80
+
81
+ ```ruby
82
+ gem "bro_hub"
83
+ gem "cache_bro"
84
+ ```
85
+
86
+ ```sh
87
+ bin/rails generate bro_hub:install # or: bin/rails generate cache_bro:install
88
+ bin/rails db:migrate # creates the audit table
89
+ ```
90
+
91
+ CacheBro works on a Redis cache store (`config.cache_store = :redis_cache_store`) and needs bro_hub 0.1.2 or newer. Give the store a `namespace:`: keys are shown without it, and Flush only works when there is one.
92
+
93
+ | Page | What you can do |
94
+ | --- | --- |
95
+ | Keys | Search by text or with `*` and `?`, see expiry and size, reveal a value, delete a key. |
96
+ | Purge | Delete every key matching a pattern, after a preview with the match count and a sample. |
97
+ | Flush | Delete every key in the store's namespace (type the store name to confirm). |
98
+ | Audit log | Every reveal, delete, purge and flush, with who, when, what and why. Filter and open any entry. |
99
+
100
+ Permissions are plain lambdas, all `false` until you set them (no Pundit needed):
101
+
102
+ ```ruby
103
+ # config/initializers/cache_bro.rb
104
+ CacheBro.configure do |config|
105
+ config.can_view_keys = ->(user) { user.developer? }
106
+ config.can_view_values = ->(user) { user.lead? } # values can hold personal data
107
+ config.can_delete = ->(user) { user.lead? }
108
+ config.can_purge = ->(user) { user.lead? }
109
+ config.can_flush = ->(user) { user.admin? }
110
+ config.can_audit = ->(user) { user.auditor? }
111
+ end
112
+ ```
113
+
114
+ A higher permission includes the lower ones: flush includes purge, purge includes delete, and any of them includes viewing keys. Viewing values and auditing stand alone.
115
+
116
+ How it stays safe:
117
+
118
+ - Keys are found with Redis `SCAN` (never `KEYS`), a page at a time.
119
+ - Everything is limited to the store's namespace, so a purge or flush cannot touch other keys in the same Redis.
120
+ - Revealing a value is a POST and is written to the audit log before the value is shown. If the audit write fails, nothing is revealed.
121
+ - Purge and flush ask for a reason by default, and a purge stops at 100,000 keys. A purge that fails partway is still logged, with the count so far.
122
+ - The audit log is append-only and records keys and patterns, never values.
123
+
124
+ See the [CacheBro README](https://github.com/rubydevro/cache_bro) for every setting.
125
+
126
+ ## The audit log
127
+
128
+ Every Bro gem that keeps an audit trail writes it to one table, `bro_hub_audit_events`, through `BroHub::Audit.record`.
129
+ BroHub shows them together under `<mount>/audit`: filter by gem, event, user or text, and open any entry. Each person
130
+ sees the rows of the gems they may audit, and nothing else. Entries are append-only and hold names and patterns, never
131
+ secret values. Gems without an audit trail (DeadBroHub) simply don't appear.
132
+
133
+ | Column | Meaning |
134
+ | --- | --- |
135
+ | `source` | the gem (`env_bro`, `safe_bro`, `cache_bro`) |
136
+ | `event`, `user_label`, `environment`, `created_at` | what happened, who did it, where, when |
137
+ | `context` | where it happened inside the gem: a cache store name, a console host |
138
+ | `target`, `count`, `reason`, `ip` | what it happened to, how many, why, from where |
139
+ | `reference`, `digest`, `parent_id` | links for gems that tie rows together (EnvBro: a proposal's token, its file's digest, its deployment) |
140
+ | `details` | anything else, as JSON |
141
+
142
+ Upgrading from 0.1: run `bin/rails g bro_hub:install` and `bin/rails db:migrate` to create the table. The gems that
143
+ use it (env_bro 0.3, safe_bro 0.3, cache_bro 0.2) need bro_hub 0.2.
144
+
59
145
  ## For gem authors: plugging in
60
146
 
61
147
  **1. Register your section** (in your engine file, so it runs before routes are drawn):
@@ -68,6 +154,7 @@ BroHub.register :safe_bro,
68
154
  engine: "SafeBro::Engine", # BroHub mounts it at /<key>
69
155
  order: 10, # lower comes first
70
156
  visible_to: ->(user) { SafeBro.config.can_audit.call(user) },
157
+ audit_visible_to: ->(user) { SafeBro.config.can_audit.call(user) }, # who sees your rows in the hub's audit log (leave out: none)
71
158
  items: [
72
159
  { label: "Sessions", path: "/", badge: -> { SafeBro::Session.pending.count } },
73
160
  { label: "Flagged commands", path: "/flagged" },
@@ -92,7 +179,27 @@ end
92
179
 
93
180
  `BroHub::ControllerBase` includes `BroHub::Layout` (the layout, and `bro_hub_user`), turns on CSRF protection and opts out of the host app's Pundit `verify_authorized` checks, so every Bro controller behaves the same under any host `ApplicationController`. Override it if your gem has its own idea of who is signed in.
94
181
 
95
- **3. Give your gem an installer** that sets up BroHub first, then itself. Name it `<section key>:install` so
182
+ **3. Write your audit trail to the shared table** (no migration of your own):
183
+
184
+ ```ruby
185
+ BroHub::Audit.record(source: :cache_bro, event: :keys_purged, user: "jane@example.com",
186
+ context: "Rails.cache", target: "posts/*", count: 12, reason: "stale", sample: [ "posts/1" ])
187
+ ```
188
+
189
+ It fails closed: when the row can't be written the error is raised, so an action that must not go unaudited stops.
190
+ To read your own rows, subclass the model with a default scope:
191
+
192
+ ```ruby
193
+ class CacheBro::AuditEvent < BroHub::AuditEvent
194
+ default_scope { where(source: "cache_bro") }
195
+ validates :event, inclusion: { in: %w[ keys_purged ] }
196
+ end
197
+ ```
198
+
199
+ In your tests: `require "bro_hub/testing"; BroHub::Testing.load_schema` creates the table, and
200
+ `BroHub::Testing.record_rails_commands` stubs BroHub's installer in generator tests.
201
+
202
+ **4. Give your gem an installer** that sets up BroHub first, then itself. Name it `<section key>:install` so
96
203
  `bro_hub:install` finds it:
97
204
 
98
205
  ```ruby
@@ -109,7 +216,7 @@ class SafeBro::Generators::InstallGenerator < Rails::Generators::Base
109
216
  end
110
217
  ```
111
218
 
112
- **4. Fill in the page:**
219
+ **5. Fill in the page:**
113
220
 
114
221
  ```erb
115
222
  <% bro_hub_crumb "Console sessions", "#5" %> <%# "SafeBro / Console sessions / #5" %>
@@ -0,0 +1,56 @@
1
+ module BroHub
2
+ # The audit trail of every Bro gem in one place. Each person sees the rows of the gems they may audit.
3
+ class AuditEventsController < ApplicationController
4
+ PER_PAGE = 50
5
+
6
+ before_action :require_auditor
7
+ helper_method :filter_params, :sections
8
+
9
+ def index
10
+ @filter = filter_params
11
+ @events = filtered.recent.limit(PER_PAGE).offset(page * PER_PAGE)
12
+ @total = filtered.count
13
+ @page = page
14
+ @counts = visible.group(:source).count
15
+ @event_names = visible.distinct.order(:event).pluck(:event)
16
+ end
17
+
18
+ def show
19
+ @event = visible.find(params[:id])
20
+ end
21
+
22
+ private
23
+ def require_auditor
24
+ render "bro_hub/shared/forbidden", status: :forbidden if sections.empty?
25
+ end
26
+
27
+ def sections
28
+ @sections ||= BroHub.registry.audited_by(bro_hub_user)
29
+ end
30
+
31
+ # Only the rows of gems this person may audit, and only the ones still installed.
32
+ def visible
33
+ AuditEvent.where(source: sections.map { |section| section.key.to_s })
34
+ end
35
+
36
+ def filtered
37
+ scope = visible
38
+ scope = scope.where(source: filter_params[:source]) if filter_params[:source].present?
39
+ scope = scope.where(event: filter_params[:event]) if filter_params[:event].present?
40
+ scope = scope.where(user_label: filter_params[:user]) if filter_params[:user].present?
41
+ if filter_params[:q].present?
42
+ like = "%#{AuditEvent.sanitize_sql_like(filter_params[:q])}%"
43
+ scope = scope.where("target LIKE :like OR reason LIKE :like", like: like)
44
+ end
45
+ scope
46
+ end
47
+
48
+ def filter_params
49
+ @filter_params ||= params.permit(:source, :event, :user, :q).to_h.symbolize_keys.compact_blank
50
+ end
51
+
52
+ def page
53
+ [ params[:page].to_i, 0 ].max
54
+ end
55
+ end
56
+ end
@@ -74,6 +74,30 @@ module BroHub
74
74
  stats: stats, extra: (capture(&block) if block)
75
75
  end
76
76
 
77
+ # "2026-11-16 09:30", in UTC, with the exact time on hover.
78
+ def bro_hub_time(time)
79
+ return "-" unless time
80
+
81
+ content_tag(:time, time.utc.strftime("%Y-%m-%d %H:%M"), datetime: time.iso8601, title: time.utc.to_s)
82
+ end
83
+
84
+ # What the sidebar's own "Bro Hub" group links to: [ label, path, active? ] for this person, or none.
85
+ def bro_hub_own_items
86
+ return [] unless bro_hub_root && bro_hub_user && BroHub.registry.audited_by(bro_hub_user).any?
87
+
88
+ [ [ "Audit log", "#{bro_hub_root}/audit", request.path.start_with?("#{bro_hub_root}/audit") && controller.try(:bro_hub_section_key).nil? ] ]
89
+ end
90
+
91
+ # "← Newer / Older →" for any list paged by a `page` param, counted from 0.
92
+ def bro_hub_pager(total:, page:, per_page:, noun: "event")
93
+ newer = link_to("← Newer", url_for(request.query_parameters.merge(page: page - 1))) if page > 0
94
+ older = link_to("Older →", url_for(request.query_parameters.merge(page: page + 1))) if (page + 1) * per_page < total
95
+ content_tag(:div, class: "bh-meta", style: "display:flex;justify-content:space-between;gap:16px;margin-top:14px") do
96
+ safe_join([ content_tag(:span, "#{number_with_delimiter(total)} #{total == 1 ? noun : noun.pluralize}"),
97
+ content_tag(:span, safe_join([ newer, older ].compact, " ")) ])
98
+ end
99
+ end
100
+
77
101
  # Inline <style> that works under a nonce-based Content Security Policy.
78
102
  def bro_hub_style_tag
79
103
  tag.style(BroHub.styles.html_safe, nonce: (content_security_policy_nonce if respond_to?(:content_security_policy_nonce)))
@@ -0,0 +1,5 @@
1
+ module BroHub
2
+ class ApplicationRecord < ActiveRecord::Base
3
+ self.abstract_class = true
4
+ end
5
+ end
@@ -0,0 +1,44 @@
1
+ module BroHub
2
+ # Who did what, in any Bro gem. Append-only: a saved row can't be changed.
3
+ #
4
+ # Gems write rows with BroHub::Audit.record and read their own through a small subclass that sets `source`:
5
+ #
6
+ # class CacheBro::AuditEvent < BroHub::AuditEvent
7
+ # default_scope { where(source: "cache_bro") }
8
+ # end
9
+ class AuditEvent < ApplicationRecord
10
+ # The subclasses share this table and are told apart by `source`, not by a type column.
11
+ self.inheritance_column = nil
12
+
13
+ # The column has no database default (MySQL refuses one on JSON), so the model supplies it.
14
+ attribute :details, default: -> { {} }
15
+
16
+ belongs_to :parent, class_name: "BroHub::AuditEvent", optional: true
17
+
18
+ validates :source, :event, :environment, presence: true
19
+
20
+ scope :recent, -> { order(created_at: :desc, id: :desc) }
21
+ scope :from_source, ->(source) { where(source: source.to_s) }
22
+
23
+ def readonly?
24
+ persisted? || super
25
+ end
26
+
27
+ # A sample of what a bulk action touched (see each gem's audit_sample_size).
28
+ def sample
29
+ Array(details["sample"])
30
+ end
31
+
32
+ def truncated?
33
+ details["truncated"] == true
34
+ end
35
+
36
+ def section
37
+ BroHub.registry[source]
38
+ end
39
+
40
+ def source_name
41
+ section&.name || source.to_s.humanize
42
+ end
43
+ end
44
+ end
@@ -0,0 +1,38 @@
1
+ <% bro_hub_crumb "Audit log" %>
2
+ <% content_for :bro_hub_crumb_actions do %>
3
+ <%= bro_hub_crumb_link "All", audit_path(@filter.except(:source)), active: @filter[:source].blank? %>
4
+ <% sections.each do |section| %>
5
+ <%= bro_hub_crumb_link section.name, audit_path(@filter.merge(source: section.key)), active: @filter[:source] == section.key.to_s %>
6
+ <% end %>
7
+ <% end %>
8
+
9
+ <%= bro_hub_hero eyebrow: "Audit log", title: number_with_delimiter(@total), subtitle: @total == 1 ? "event" : "events",
10
+ lead: "Who did what in every Bro gem you may audit. Entries can't be changed, and they hold names and patterns, never secret values.",
11
+ stats: sections.map { |section| [ @counts.fetch(section.key.to_s, 0), section.name.downcase, nil ] } %>
12
+
13
+ <%= form_with url: audit_path, method: :get, class: "bh-filters" do %>
14
+ <%= hidden_field_tag :source, @filter[:source] if @filter[:source] %>
15
+ <%= text_field_tag :q, @filter[:q], placeholder: "Search targets and reasons", class: "bh-input is-strong", "aria-label": "Search targets and reasons" %>
16
+ <%= text_field_tag :user, @filter[:user], placeholder: "User", class: "bh-input", "aria-label": "User" %>
17
+ <%= select_tag :event, options_for_select([ [ "Any event", "" ], *@event_names.map { |name| [ name.humanize, name ] } ], @filter[:event]), class: "bh-select", "aria-label": "Event" %>
18
+ <%= submit_tag "Filter", name: nil, class: "bh-chip" %>
19
+ <%= link_to "Reset", audit_path(source: @filter[:source]), class: "bh-link-quiet" %>
20
+ <% end %>
21
+
22
+ <div class="bh-table-wrap">
23
+ <div class="bh-table" style="--cols: 150px 150px 110px 150px minmax(220px,1fr) 70px; --min: 900px">
24
+ <div class="bh-row is-head"><span>When</span><span>User</span><span>Gem</span><span>Event</span><span>Target</span><span>Count</span></div>
25
+ <% @events.each do |event| %>
26
+ <%= link_to audit_event_path(event), class: "bh-row" do %>
27
+ <span class="bh-tone-violet"><%= bro_hub_time(event.created_at) %></span>
28
+ <span class="bh-cell-strong"><%= event.user_label %></span>
29
+ <span class="bh-cell-muted"><%= event.source_name %></span>
30
+ <span><span class="bh-tag"><%= event.event.humanize %></span></span>
31
+ <span class="bh-cell-text" style="overflow-wrap:anywhere"><%= truncate(event.target.to_s, length: 90) %></span>
32
+ <span><%= event.count %></span>
33
+ <% end %>
34
+ <% end %>
35
+ <% if @events.empty? %><div class="bh-empty">Nothing recorded.</div><% end %>
36
+ <%= bro_hub_pager(total: @total, page: @page, per_page: BroHub::AuditEventsController::PER_PAGE) %>
37
+ </div>
38
+ </div>
@@ -0,0 +1,54 @@
1
+ <% bro_hub_crumb "Audit log", "##{@event.id}" %>
2
+ <% content_for :bro_hub_crumb_actions do %>
3
+ <%= bro_hub_crumb_link "← Audit log", audit_path %>
4
+ <% end %>
5
+
6
+ <%= bro_hub_hero eyebrow: "#{@event.source_name} · #{@event.environment}", title: @event.event.humanize,
7
+ subtitle: (pluralize(@event.count, "item") if @event.count),
8
+ lead: safe_join([ content_tag(:strong, @event.user_label), " at #{@event.created_at.utc.strftime("%Y-%m-%d %H:%M UTC")}" ]) %>
9
+
10
+ <div class="bh-split">
11
+ <section class="bh-split-main">
12
+ <% if @event.target.present? %>
13
+ <div class="bh-block-head"><h2 class="bh-h2">Target</h2></div>
14
+ <pre class="bh-cmd-code" style="white-space:pre-wrap;overflow-wrap:anywhere"><%= @event.target %></pre>
15
+ <% end %>
16
+
17
+ <% if @event.sample.any? %>
18
+ <div class="bh-block-head" style="margin-top:24px">
19
+ <h2 class="bh-h2">Sample</h2>
20
+ <span class="bh-meta">a sample of <%= @event.sample.size %><%= " (more were touched)" if @event.count.to_i > @event.sample.size %></span>
21
+ </div>
22
+ <div class="bh-log">
23
+ <% @event.sample.each do |item| %>
24
+ <div class="bh-cmd"><pre class="bh-cmd-code" style="white-space:pre-wrap;overflow-wrap:anywhere"><%= item %></pre></div>
25
+ <% end %>
26
+ </div>
27
+ <% end %>
28
+
29
+ <% extra = @event.details.except("sample", "truncated") %>
30
+ <% if extra.any? %>
31
+ <div class="bh-block-head" style="margin-top:24px"><h2 class="bh-h2">Details</h2></div>
32
+ <pre class="bh-cmd-code" style="white-space:pre-wrap;overflow-wrap:anywhere"><%= JSON.pretty_generate(extra) %></pre>
33
+ <% end %>
34
+ </section>
35
+
36
+ <div class="bh-split-aside">
37
+ <section class="bh-block">
38
+ <h2 class="bh-h2">Entry</h2>
39
+ <dl class="bh-dl">
40
+ <dt>User</dt><dd><%= @event.user_label %></dd>
41
+ <dt>Gem</dt><dd><%= @event.source_name %></dd>
42
+ <dt>Event</dt><dd><span class="bh-tag"><%= @event.event.humanize %></span></dd>
43
+ <dt>When</dt><dd><%= bro_hub_time(@event.created_at) %></dd>
44
+ <dt>Environment</dt><dd><%= @event.environment %></dd>
45
+ <% if @event.context.present? %><dt>Context</dt><dd><%= @event.context %></dd><% end %>
46
+ <% if @event.ip.present? %><dt>IP</dt><dd><%= @event.ip %></dd><% end %>
47
+ <dt>Count</dt><dd><%= @event.count || "-" %></dd>
48
+ <dt>Reason</dt><dd><%= @event.reason.presence || "none given" %></dd>
49
+ <% if @event.details["completed"] == false %><dt>Outcome</dt><dd class="bh-tone-red">failed part way</dd><% end %>
50
+ <% if @event.truncated? %><dt>Limit</dt><dd class="bh-tone-amber">stopped at a limit</dd><% end %>
51
+ </dl>
52
+ </section>
53
+ </div>
54
+ </div>
@@ -24,7 +24,8 @@
24
24
 
25
25
  <div class="bh-body">
26
26
  <% sections = bro_hub_sections %>
27
- <% if sections.any? %>
27
+ <% own_items = bro_hub_own_items %>
28
+ <% if sections.any? || own_items.any? %>
28
29
  <nav class="bh-side" aria-label="Bro sections">
29
30
  <% sections.each do |section, base, current| %>
30
31
  <div class="bh-group" style="--accent: <%= section.accent %>">
@@ -38,6 +39,14 @@
38
39
  <% end %>
39
40
  </div>
40
41
  <% end %>
42
+ <% if own_items.any? %>
43
+ <div class="bh-group" style="--accent: <%= BroHub::Section::ACCENTS[:violet] %>">
44
+ <span class="bh-group-label">Bro Hub</span>
45
+ <% own_items.each do |label, path, active| %>
46
+ <%= link_to path, class: [ "bh-nav", ("is-active" if active) ] do %><span><%= label %></span><% end %>
47
+ <% end %>
48
+ </div>
49
+ <% end %>
41
50
  </nav>
42
51
  <% end %>
43
52
 
data/config/routes.rb CHANGED
@@ -1,6 +1,10 @@
1
1
  BroHub::Engine.routes.draw do
2
2
  root "home#index"
3
3
 
4
+ # Before the sections, so a gem can never shadow them.
5
+ get "audit", to: "audit_events#index", as: :audit
6
+ get "audit/:id", to: "audit_events#show", as: :audit_event
7
+
4
8
  # Every registered engine lives under the hub: /<mount>/<section key>/...
5
9
  BroHub.registry.each do |section|
6
10
  mount section.engine => "/#{section.key}", as: section.key if section.engine
@@ -0,0 +1,35 @@
1
+ # One audit table for every Bro gem. Each gem writes its own rows (the `source` column) through BroHub::Audit.
2
+ class CreateBroHubAuditEvents < ActiveRecord::Migration[7.1]
3
+ def change
4
+ create_table :bro_hub_audit_events do |t|
5
+ # The gem that wrote the row ("env_bro", "safe_bro", "cache_bro") and what happened.
6
+ t.string :source, null: false
7
+ t.string :event, null: false
8
+ t.string :user_label
9
+ t.string :environment, null: false
10
+ # Where it happened, when that is a thing: a cache store name, a console host.
11
+ t.string :context
12
+ # What it happened to: a key, a key pattern, a session.
13
+ t.text :target
14
+ t.integer :count
15
+ t.text :reason
16
+ t.string :ip
17
+ # Lookups for gems that link rows together: EnvBro keeps a proposal's token and the digest of its file here.
18
+ t.string :reference
19
+ t.string :digest
20
+ t.references :parent, foreign_key: { to_table: :bro_hub_audit_events }, index: false
21
+ # No column default: MySQL rejects defaults on JSON columns. BroHub::Audit.record always sets it.
22
+ t.json :details, null: false
23
+ t.datetime :created_at, null: false
24
+ end
25
+
26
+ add_index :bro_hub_audit_events, :created_at
27
+ add_index :bro_hub_audit_events, [ :source, :created_at ]
28
+ add_index :bro_hub_audit_events, [ :source, :event, :created_at ]
29
+ add_index :bro_hub_audit_events, [ :user_label, :created_at ]
30
+ add_index :bro_hub_audit_events, :reference
31
+ add_index :bro_hub_audit_events, :digest
32
+ # A row can have one follow-up of each kind (one deployment per proposal).
33
+ add_index :bro_hub_audit_events, [ :parent_id, :event ], unique: true
34
+ end
35
+ end
@@ -0,0 +1,48 @@
1
+ module BroHub
2
+ # The one place every Bro gem writes its audit trail.
3
+ #
4
+ # BroHub::Audit.record(source: :cache_bro, event: :keys_purged, user: "jane@example.com",
5
+ # context: "Rails.cache", target: "posts/*", count: 12, reason: "stale", sample: [ "posts/1" ])
6
+ #
7
+ # Never put secrets in it: keys, patterns and names, never values. It fails closed: when the row can't be
8
+ # written the error is logged and raised, so a caller that must not act unaudited (revealing a value) stops.
9
+ module Audit
10
+ module_function
11
+
12
+ # user: a String is stored as it is (a label, or a system actor like "deploy"). Anything else goes through
13
+ # BroHub.config.user_label. A gem with its own user_label turns the user into a String first.
14
+ # model: BroHub::AuditEvent, or a gem's own subclass when it validates its events.
15
+ # columns: raw attributes for the few things the named arguments don't cover (a gem's own link to another row).
16
+ # details: anything else, saved as JSON.
17
+ def record(source:, event:, user:, model: BroHub::AuditEvent, context: nil, target: nil, count: nil, reason: nil, ip: nil,
18
+ reference: nil, digest: nil, parent: nil, columns: {}, **details)
19
+ attributes = {
20
+ source: source.to_s,
21
+ event: event.to_s,
22
+ user_label: user.is_a?(String) ? user : BroHub.config.user_label.call(user).to_s,
23
+ environment: Rails.env.to_s,
24
+ context: context.presence&.to_s,
25
+ target: target,
26
+ count: count,
27
+ reason: reason.presence,
28
+ ip: ip.presence,
29
+ reference: reference,
30
+ digest: digest,
31
+ parent: parent,
32
+ details: details.deep_stringify_keys
33
+ }.merge(columns)
34
+ model.create!(**attributes)
35
+ rescue StandardError => error
36
+ # The action already happened (or, for a reveal, is about to be refused): at least leave a trace in the log.
37
+ Rails.logger&.error("BroHub: could not write the audit log (#{error.class}: #{error.message}). Entry: #{attributes.inspect}")
38
+ raise
39
+ end
40
+
41
+ # False until the migration has run: lets a gem show "run db:migrate" instead of an error page.
42
+ def ready?
43
+ BroHub::AuditEvent.table_exists?
44
+ rescue ActiveRecord::ActiveRecordError
45
+ false
46
+ end
47
+ end
48
+ end
@@ -22,6 +22,11 @@ module BroHub
22
22
  select { |section| section.visible_to?(user) }
23
23
  end
24
24
 
25
+ # The sections whose audit rows this person may see in the hub's audit log.
26
+ def audited_by(user)
27
+ select { |section| section.audited_by?(user) }
28
+ end
29
+
25
30
  def clear
26
31
  @sections.clear
27
32
  end
@@ -48,14 +48,18 @@ module BroHub
48
48
  # visible_to: ->(user) { true } } ]
49
49
  # visible_to: ->(user) { true } decides whether this person sees the section. Navigation only, not security:
50
50
  # every engine still authorizes its own pages.
51
+ # audit_visible_to: ->(user) { true } decides who may see this gem's rows in the hub's audit log. Leave it out
52
+ # when the gem keeps no audit trail: nothing of it shows there. Like everything else here it is a
53
+ # filter on what is listed, so the gem should check the same thing on its own audit pages.
51
54
  # order: lower comes first.
52
- def initialize(key, label:, items:, name: nil, accent: :violet, engine: nil, visible_to: nil, order: 100)
55
+ def initialize(key, label:, items:, name: nil, accent: :violet, engine: nil, visible_to: nil, audit_visible_to: nil, order: 100)
53
56
  @key = key.to_sym
54
57
  @label = label.to_s
55
58
  @name = (name || @label.split("·").first).to_s.strip
56
59
  @accent = resolve_accent(accent)
57
60
  @engine = engine
58
61
  @visible_to = visible_to
62
+ @audit_visible_to = audit_visible_to
59
63
  @order = order
60
64
  @items = Array(items).map { |item| Item.new(**item.symbolize_keys.slice(:label, :path, :badge, :match, :visible_to)) }
61
65
  raise ArgumentError, "BroHub section #{key} needs at least one item" if @items.empty?
@@ -71,6 +75,12 @@ module BroHub
71
75
  @visible_to ? !!@visible_to.call(user) : true
72
76
  end
73
77
 
78
+ def audited_by?(user)
79
+ return false unless user && @audit_visible_to
80
+
81
+ !!@audit_visible_to.call(user)
82
+ end
83
+
74
84
  def visible_items(user)
75
85
  items.select { |item| item.visible_to?(user) }
76
86
  end
@@ -0,0 +1,45 @@
1
+ require "bro_hub"
2
+
3
+ module BroHub
4
+ # For the test suites of Bro gems (and apps): creates the audit table in the test database.
5
+ #
6
+ # # test_helper.rb, after loading the Rails environment
7
+ # require "bro_hub/testing"
8
+ # BroHub::Testing.load_schema
9
+ module Testing
10
+ MIGRATION = File.expand_path("../../db/migrate/20261116000000_create_bro_hub_audit_events.rb", __dir__)
11
+
12
+ # What BroHub's installer would have run (`rails_command`), once record_rails_commands is on.
13
+ RAILS_COMMANDS = []
14
+
15
+ module RecordRailsCommands
16
+ def rails_command(command, *)
17
+ RAILS_COMMANDS << command
18
+ end
19
+ end
20
+
21
+ module_function
22
+
23
+ # For generator tests: BroHub's installer copies its migration with `bin/rails`, which an empty test app
24
+ # doesn't have. Call this once and read what it would have run from BroHub::Testing::RAILS_COMMANDS.
25
+ def record_rails_commands
26
+ require "generators/bro_hub/install/install_generator"
27
+ generator = BroHub::Generators::InstallGenerator
28
+ generator.prepend(RecordRailsCommands) unless generator < RecordRailsCommands
29
+ RAILS_COMMANDS
30
+ end
31
+
32
+ # Always rebuilds the table, so a stale one from an older version can't linger.
33
+ def load_schema
34
+ verbose = ActiveRecord::Migration.verbose
35
+ load MIGRATION unless defined?(::CreateBroHubAuditEvents)
36
+ ActiveRecord::Migration.verbose = false
37
+ connection = ActiveRecord::Base.connection
38
+ connection.drop_table(:bro_hub_audit_events, if_exists: true)
39
+ ::CreateBroHubAuditEvents.new.migrate(:up)
40
+ BroHub::AuditEvent.reset_column_information
41
+ ensure
42
+ ActiveRecord::Migration.verbose = verbose
43
+ end
44
+ end
45
+ end
@@ -1,3 +1,3 @@
1
1
  module BroHub
2
- VERSION = "0.1.2"
2
+ VERSION = "0.2.0"
3
3
  end
data/lib/bro_hub.rb CHANGED
@@ -5,6 +5,7 @@ require "bro_hub/registry"
5
5
  require "bro_hub/layout"
6
6
  require "bro_hub/controller_base"
7
7
  require "bro_hub/root_middleware"
8
+ require "bro_hub/audit"
8
9
  require "bro_hub/engine"
9
10
 
10
11
  # The shared admin shell for the Bro gems.
@@ -40,6 +40,11 @@ module BroHub
40
40
  end
41
41
  end
42
42
 
43
+ # The one audit table every Bro gem writes to. Copied once: running the installer again skips it.
44
+ def copy_migrations
45
+ rails_command "bro_hub:install:migrations", inline: true
46
+ end
47
+
43
48
  def mount_engine
44
49
  if routes_source.include?("BroHub::Engine")
45
50
  say_status :skip, "BroHub::Engine is already mounted", :yellow
@@ -74,8 +79,9 @@ module BroHub
74
79
  say <<~TEXT
75
80
 
76
81
  BroHub is installed. Next:
77
- 1. Check config/initializers/bro_hub.rb (how to find the signed-in user)
78
- 2. Visit #{mount_path}. Each Bro gem lives under #{mount_path}/<gem>
82
+ 1. bin/rails db:migrate (creates the audit table all the Bro gems share)
83
+ 2. Check config/initializers/bro_hub.rb (how to find the signed-in user)
84
+ 3. Visit #{mount_path}. Each Bro gem lives under #{mount_path}/<gem>, the combined audit log under #{mount_path}/audit
79
85
  TEXT
80
86
  end
81
87
 
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: bro_hub
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.2
4
+ version: 0.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Ruby Dev SRL
@@ -25,7 +25,8 @@ dependencies:
25
25
  version: '7.1'
26
26
  description: 'BroHub is the shared admin shell: one mount point, one layout, one sidebar
27
27
  and one place to configure who is signed in. Each Bro gem registers its pages and
28
- shows up as a section. Sections only appear for people who may use them.'
28
+ shows up as a section. Sections only appear for people who may use them. It also
29
+ keeps the one audit table every Bro gem writes to, with a combined audit log.'
29
30
  email:
30
31
  - office@rubydev.ro
31
32
  executables: []
@@ -36,13 +37,20 @@ files:
36
37
  - README.md
37
38
  - Rakefile
38
39
  - app/controllers/bro_hub/application_controller.rb
40
+ - app/controllers/bro_hub/audit_events_controller.rb
39
41
  - app/controllers/bro_hub/home_controller.rb
40
42
  - app/helpers/bro_hub/application_helper.rb
43
+ - app/models/bro_hub/application_record.rb
44
+ - app/models/bro_hub/audit_event.rb
45
+ - app/views/bro_hub/audit_events/index.html.erb
46
+ - app/views/bro_hub/audit_events/show.html.erb
41
47
  - app/views/bro_hub/shared/_hero.html.erb
42
48
  - app/views/bro_hub/shared/forbidden.html.erb
43
49
  - app/views/layouts/bro_hub/application.html.erb
44
50
  - config/routes.rb
51
+ - db/migrate/20261116000000_create_bro_hub_audit_events.rb
45
52
  - lib/bro_hub.rb
53
+ - lib/bro_hub/audit.rb
46
54
  - lib/bro_hub/configuration.rb
47
55
  - lib/bro_hub/controller_base.rb
48
56
  - lib/bro_hub/engine.rb
@@ -52,6 +60,7 @@ files:
52
60
  - lib/bro_hub/section.rb
53
61
  - lib/bro_hub/skull.png
54
62
  - lib/bro_hub/styles.css
63
+ - lib/bro_hub/testing.rb
55
64
  - lib/bro_hub/version.rb
56
65
  - lib/generators/bro_hub/install/install_generator.rb
57
66
  - lib/generators/bro_hub/install/templates/bro_hub.rb
@@ -81,5 +90,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
81
90
  requirements: []
82
91
  rubygems_version: 4.0.10
83
92
  specification_version: 4
84
- summary: One dashboard shell for the Bro gems (EnvBro, SafeBro, ...).
93
+ summary: One dashboard shell and one audit log for the Bro gems (EnvBro, SafeBro,
94
+ CacheBro, ...).
85
95
  test_files: []