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 +4 -4
- data/README.md +112 -5
- data/app/controllers/bro_hub/audit_events_controller.rb +56 -0
- data/app/helpers/bro_hub/application_helper.rb +24 -0
- data/app/models/bro_hub/application_record.rb +5 -0
- data/app/models/bro_hub/audit_event.rb +44 -0
- data/app/views/bro_hub/audit_events/index.html.erb +38 -0
- data/app/views/bro_hub/audit_events/show.html.erb +54 -0
- data/app/views/layouts/bro_hub/application.html.erb +10 -1
- data/config/routes.rb +4 -0
- data/db/migrate/20261116000000_create_bro_hub_audit_events.rb +35 -0
- data/lib/bro_hub/audit.rb +48 -0
- data/lib/bro_hub/registry.rb +5 -0
- data/lib/bro_hub/section.rb +11 -1
- data/lib/bro_hub/testing.rb +45 -0
- data/lib/bro_hub/version.rb +1 -1
- data/lib/bro_hub.rb +1 -0
- data/lib/generators/bro_hub/install/install_generator.rb +8 -2
- metadata +13 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 4e8d9cfb095f79b5ea95e8deec476ac616aba2c0fe7f13d7d82729bd70eca0a3
|
|
4
|
+
data.tar.gz: bd8d3a62facfe12d4a8e5a8d0256e89decb3bc67df3b6e7f2dc4a57076ce7215
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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+.
|
|
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.
|
|
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
|
-
**
|
|
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,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
|
-
<%
|
|
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
|
data/lib/bro_hub/registry.rb
CHANGED
|
@@ -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
|
data/lib/bro_hub/section.rb
CHANGED
|
@@ -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
|
data/lib/bro_hub/version.rb
CHANGED
data/lib/bro_hub.rb
CHANGED
|
@@ -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.
|
|
78
|
-
2.
|
|
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.
|
|
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: []
|