sitegoose 0.3.3

data/lib/sitegoose/small_modules.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+# The modules with little of their own: forms, audit, flags, maintenance and
+# the security headers.
+
+require "securerandom"
+
+module SiteGoose
+  # Form protection module: checks a form your server received before you
+  # accept it (POST /collectanalytics/shield/verify, the same check as spam
+  # protection's). It reads the hidden "analytics-shield" answer the tracker
+  # puts in protected forms, and checks the email, name and text for fake
+  # sign-ups. Spam lands in the site's spam folder (Leads -> Spam). Passwords,
+  # card numbers and tokens are never sent. Fails open: when the check can't
+  # be made, the form is accepted (checked false).
+  class Forms
+    PRIVATE_FIELD = /pass|card|cvc|cvv|secret|token|ssn|iban|csrf|analytics-shield/i.freeze
+    MAX_FIELDS = 50
+    ANSWER = "analytics-shield"
+
+    # Rails and Rack nest "user[email]" as {"user" => {"email" => ...}}: put
+    # back as the form named them, so a label is what the visitor saw.
+    def self.flat(fields, prefix = nil, out = {}, depth = 0)
+      (fields || {}).each do |label, value|
+        name = prefix ? "#{prefix}[#{label}]" : label.to_s
+        if value.is_a?(Hash)
+          flat(value, name, out, depth + 1) if depth < 3
+        else
+          out[name] = value
+        end
+        break if out.size >= MAX_FIELDS * 2
+      end
+      out
+    end
+
+    def self.plain_fields(fields)
+      out = {}
+      flat(fields).first(MAX_FIELDS).each do |label, value|
+        next if label.to_s.match?(PRIVATE_FIELD)
+
+        value = value.select { |v| v.is_a?(String) }.join(", ") if value.is_a?(Array)
+        out[SiteGoose.text(label, 100)] = SiteGoose.text(value, 2000) if value.is_a?(String)
+      end
+      out
+    end
+
+    def initialize(core, **_)
+      @core = core
+    end
+
+    # fields: the form as a hash. -> {ok:, spam:, reasons:, checked:}.
+    def check(fields, ip = "", email = nil, name = nil, form = nil)
+      return { ok: true, spam: false, reasons: [], checked: false } unless @core.on?("forms")
+
+      unchecked = { ok: true, spam: false, reasons: ["unchecked"], checked: false }
+      fields = (fields || {}).to_h { |k, v| [k.to_s, v] }
+      token = fields[ANSWER]
+      token = token.first if token.is_a?(Array)
+      body = { "token" => token.is_a?(String) ? token : "", "fields" => Forms.plain_fields(fields), "ip" => ip.to_s }
+      { "email" => email, "name" => name, "form" => form }.each { |k, v| body[k] = v if v.is_a?(String) }
+      res = @core.request("forms", "/collectanalytics/shield/verify", body: body)
+      if res.nil? || res.status >= 500 || [403, 429].include?(res.status)
+        @core.log("forms", "the site secret was refused; forms aren't checked") if res&.status == 403
+        return unchecked
+      end
+      data = res.json
+      data = {} unless data.is_a?(Hash)
+      spam = data["success"] == false
+      { ok: !spam, spam: spam, reasons: Array(data["reasons"]), checked: true }
+    end
+
+    def flush; end
+
+    def close; end
+  end
+
+  # Audit log module: who did what on your site, sent to POST /events/audit
+  # in small batches in the background (Security -> Audit log). What goes in
+  # (names, emails) is up to you. Devise's logins and logouts are recorded on
+  # their own.
+  class Audit
+    BATCH = 100
+    QUEUE_MAX = 1000
+    FLUSH_EVERY = 5
+
+    attr_reader :queue
+
+    def initialize(core, **_)
+      @core = core
+      @queue = []
+      @lock = Mutex.new
+      @job = core.valid? ? Periodic.new(FLUSH_EVERY) { flush; FLUSH_EVERY } : nil
+      Forking.register(self)
+    end
+
+    def after_fork_in_child
+      @lock = Mutex.new
+      @queue = []
+    end
+
+    def record(action, actor = "", target = "", details = nil, actor_ip = "", session_id = "")
+      return if !@core.on?("audit") || !action.is_a?(String) || action.empty?
+
+      entry = {
+        "at" => SiteGoose.iso_now, "action" => action[0, 64], "actor" => SiteGoose.text(actor, 200),
+        "target" => SiteGoose.text(target, 300), "details" => details, "actor_ip" => actor_ip.to_s,
+        "session_id" => session_id.to_s
+      }
+      full = @lock.synchronize do
+        return if @queue.size >= QUEUE_MAX
+
+        @queue << entry
+        @queue.size >= BATCH
+      end
+      @job&.run_now if full
+    end
+
+    def flush
+      waiting = @lock.synchronize do
+        taken = @queue
+        @queue = []
+        taken
+      end
+      waiting.each_slice(BATCH) { |batch| @core.request("audit", "/events/audit", body: { "entries" => batch }) }
+    end
+
+    def close
+      @job&.stop
+      Forking.unregister(self)
+      flush
+    end
+  end
+
+  # Feature flags module: turn features of your app on or off from the
+  # dashboard (Site settings -> Server), for everyone, a share of users, or
+  # listed user IDs. enabled?() answers from memory; the flags come with the
+  # module switches (core), about once a minute.
+  class Flags
+    # FNV-1a over "key:user", 0-99: the same as the Node, PHP and Python packages.
+    def self.bucket(key, user)
+      h = 0x811C9DC5
+      "#{key}:#{user}".each_byte do |byte|
+        h ^= byte
+        h = (h * 0x01000193) & 0xFFFFFFFF
+      end
+      h % 100
+    end
+
+    def self.evaluate(flag, key, user)
+      return false unless flag["on"]
+
+      uid = user.nil? ? "" : user.to_s
+      return true if !uid.empty? && Array(flag["users"]).map(&:to_s).include?(uid)
+
+      rollout = flag.key?("rollout") ? flag["rollout"].to_i : 100
+      return true if rollout >= 100
+      return false if rollout <= 0 || uid.empty?
+
+      bucket(key, uid) < rollout
+    end
+
+    def initialize(core, **_)
+      @core = core
+    end
+
+    def enabled?(key, user = nil, default = false)
+      flag = @core.on?("flags") ? @core.flags[key.to_s] : nil
+      flag.is_a?(Hash) ? Flags.evaluate(flag, key.to_s, user) : default
+    rescue StandardError
+      default
+    end
+
+    def flush; end
+
+    def close; end
+  end
+
+  # Maintenance mode module: while it's on (Site settings -> Server), visitors
+  # get a "back soon" page (503, so search engines know it's temporary),
+  # except allowed addresses and whoever opened the preview link
+  # (?site_preview=<code>, remembered for a day in a cookie).
+  class Maintenance
+    COOKIE = "site_preview"
+    ESCAPES = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;", "'" => "&#x27;" }.freeze
+
+    def self.escape(text)
+      SiteGoose.text(text).gsub(/[&<>"']/, ESCAPES)
+    end
+
+    def self.page(message)
+      text = escape(message.to_s.empty? ? "We're doing some maintenance. Please check back in a few minutes." : message)
+      "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">" \
+        "<title>Back soon</title><style>body{margin:0;min-height:100vh;display:grid;place-items:center;font:16px/1.5 system-ui,sans-serif;" \
+        "background:#f8fafc;color:#0f172a}main{max-width:32rem;padding:2rem;text-align:center}h1{font-size:1.6rem;margin:0 0 .5rem}" \
+        "p{color:#475569;margin:0}@media(prefers-color-scheme:dark){body{background:#0f172a;color:#e2e8f0}p{color:#94a3b8}}</style></head>" \
+        "<body><main><h1>Back soon</h1><p>#{text}</p></main></body></html>"
+    end
+
+    def self.query_value(query, name)
+      query.to_s.split("&").each do |pair|
+        k, v = pair.split("=", 2)
+        return RequestRules.decode_once(v.to_s) if RequestRules.decode_once(k.to_s) == name
+      end
+      ""
+    end
+
+    # Options: skip (->(path) { true } lets a request through: health checks).
+    def initialize(core, skip: nil, **_)
+      @core = core
+      @skip = skip
+      @allow_for = nil
+      @allow = IpSet.new([])
+    end
+
+    # nil to let the request through, [:pass, headers] to let it through and
+    # remember the preview link, else [status, headers, body].
+    # secure: the request came over HTTPS (the cookie is then Secure).
+    def decide(ip, path, query, cookie_header, secure: false)
+      m = @core.on?("maintenance") ? @core.maintenance : nil
+      return nil if !m.is_a?(Hash) || !m["on"] || (@skip && @skip.call(path))
+
+      unless @allow_for.equal?(m["allow"])
+        @allow_for = m["allow"]
+        @allow = IpSet.new(Array(m["allow"]))
+      end
+      key = IP.key(ip)
+      return nil if key && @allow.has?(key)
+
+      code = m["bypass"].to_s
+      unless code.empty?
+        if Challenge.secure_compare(Maintenance.query_value(query, COOKIE), code)
+          return [:pass, { "set-cookie" => "#{COOKIE}=#{code}; Path=/; Max-Age=86400; HttpOnly; SameSite=Lax#{secure ? '; Secure' : ''}" }]
+        end
+        return nil if Challenge.cookie_values(cookie_header, COOKIE).any? { |value| Challenge.secure_compare(value, code) }
+      end
+      [503, { "content-type" => "text/html; charset=utf-8", "retry-after" => "600", "cache-control" => "no-store" }, Maintenance.page(m["message"])]
+    end
+
+    def flush; end
+
+    def close; end
+  end
+
+  # The security headers module: the headers come with the module switches (core).
+  class Headers
+    def flush; end
+
+    def close; end
+  end
+end

data/lib/sitegoose/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SiteGoose
+  VERSION = "0.3.3"
+end

data/lib/sitegoose.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+# One package for a site's Ruby server, run from the analytics dashboard:
+# firewall, error monitoring and server analytics. Each module is separate:
+# one failing never stops the others, and the firewall never waits on
+# reporting. A loaded module can also be switched off in the dashboard
+# (Security -> Server package).
+#
+#     # Rails: the Railtie puts the middleware first; config in an initializer.
+#     SiteGoose.configure(site_id: "...", secret: ENV["ANALYTICS_SITE_SECRET"], endpoint: "https://...")
+#
+#     # Sinatra, Hanami, Roda, any Rack app:
+#     use SiteGoose::Middleware, site_id: "...", secret: ENV["ANALYTICS_SITE_SECRET"], endpoint: "https://..."
+#
+# A module is on with true (or its options as a hash) and off with false.
+# Standard library only, and rack; Ruby 3.0+.
+
+require_relative "sitegoose/version"
+require_relative "sitegoose/core"
+require_relative "sitegoose/ip"
+require_relative "sitegoose/challenge"
+require_relative "sitegoose/request_rules"
+require_relative "sitegoose/firewall"
+require_relative "sitegoose/performance"
+require_relative "sitegoose/errors"
+require_relative "sitegoose/query_text"
+require_relative "sitegoose/queries"
+require_relative "sitegoose/crawlers"
+require_relative "sitegoose/analytics"
+require_relative "sitegoose/small_modules"
+require_relative "sitegoose/inventory"
+require_relative "sitegoose/posture"
+require_relative "sitegoose/resources"
+require_relative "sitegoose/proxy"
+require_relative "sitegoose/platform"
+require_relative "sitegoose/middleware"
+
+module SiteGoose
+  @lock = Mutex.new
+  @options = nil
+  @defaults = {}
+  @platform = nil
+  @created = []
+  @created_lock = Mutex.new
+  @when_made = []
+
+  # The options a block sets: SiteGoose.configure { |c| c.site_id = "..." }.
+  class Config
+    def initialize(values = {})
+      @values = SiteGoose.symbolize(values)
+    end
+
+    def to_h
+      @values.dup
+    end
+
+    def [](key)
+      @values[key.to_sym]
+    end
+
+    def []=(key, value)
+      @values[key.to_sym] = value
+    end
+
+    def method_missing(name, *args)
+      key = name.to_s
+      if key.end_with?("=") && args.size == 1
+        @values[key.chomp("=").to_sym] = args[0]
+      elsif args.empty?
+        @values[name]
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(_name, _private = false)
+      true
+    end
+  end
+
+  class << self
+    # Sets the options the platform is made from; it is made on first use
+    # (the first request, job or call), so a Puma or Unicorn master that only
+    # forks workers starts no threads of its own. Options already given (the
+    # Rails config, credentials, the environment) are kept unless named again.
+    def configure(**options)
+      config = Config.new(options)
+      yield config if block_given?
+      @lock.synchronize do
+        @options = (@options || {}).merge(config.to_h)
+        if @platform
+          warn "[analytics-platform] configure after the platform was made: the new options apply after SiteGoose.reset"
+        end
+      end
+      nil
+    end
+
+    # Options under what configure() gives (the Railtie's, from the Rails
+    # config and credentials), over the environment's.
+    def defaults(**options)
+      @lock.synchronize { @defaults = @defaults.merge(SiteGoose.symbolize(options)) }
+      nil
+    end
+
+    # Runs the block with the platform once it is made (now, if it is).
+    def when_made(&block)
+      made = @lock.synchronize do
+        @when_made << block
+        @platform
+      end
+      block.call(made) if made
+      nil
+    end
+
+    # Options from the environment, under what configure() gives.
+    def env_options
+      out = {}
+      out[:site_id] = ENV["ANALYTICS_SITE_ID"] if ENV["ANALYTICS_SITE_ID"]
+      out[:secret] = ENV["ANALYTICS_SITE_SECRET"] if ENV["ANALYTICS_SITE_SECRET"]
+      endpoint = ENV["ANALYTICS_ENDPOINT"] || ENV["ANALYTICS_FIREWALL_ENDPOINT"]
+      out[:endpoint] = endpoint if endpoint
+      out[:server_name] = ENV["ANALYTICS_SERVER_NAME"] if ENV["ANALYTICS_SERVER_NAME"]
+      trust = ENV["ANALYTICS_TRUST_PROXY"]
+      out[:trust_proxy] = trust.match?(/\A\d+\z/) ? trust.to_i : trust if trust && !trust.empty?
+      out
+    end
+
+    def options
+      env_options.merge(@defaults).merge(@options || {})
+    end
+
+    def configured?
+      !@options.nil? || !@defaults.empty? || !env_options.empty?
+    end
+
+    # The platform, made on first use from configure(), the Rails config and
+    # credentials, and the environment; nil when nothing configures it, or
+    # with enabled: false (the middleware then passes every request).
+    def platform
+      return @platform if @platform
+
+      hooks = nil
+      made = @lock.synchronize do
+        return @platform if @platform
+        return nil unless configured?
+
+        given = options
+        return nil if given.delete(:enabled) == false
+
+        hooks = @when_made.dup
+        @platform = Platform.new(**given)
+      end
+      hooks&.each do |hook|
+        hook.call(made)
+      rescue StandardError => e
+        warn "[analytics-platform] #{e.class}: #{e.message}"
+      end
+      made
+    end
+
+    # Uses this platform as the one everything else reaches (tests, or a
+    # platform you made yourself).
+    def platform=(value)
+      @lock.synchronize { @platform = value }
+    end
+
+    # Closes the platform and forgets it and its options.
+    def reset
+      made = @lock.synchronize do
+        taken = @platform
+        @platform = nil
+        @options = nil
+        @defaults = {}
+        taken
+      end
+      made&.close
+      nil
+    end
+
+    def created(platform)
+      @created_lock.synchronize { @created << platform }
+    end
+
+    # At exit: the exception that is ending the program is sent, then every
+    # platform sends what's waiting and stops its threads.
+    # All of it within EXIT_DEADLINE seconds: a container's grace period is
+    # longer than that, and what wasn't sent by then waits in the errors file.
+    def at_exit_hook(error, seconds = EXIT_DEADLINE)
+      platforms = @created_lock.synchronize { @created.dup }
+      within(seconds) do
+        platforms.each do |made|
+          next if made.closed?
+
+          made.errors&.capture_exit(error)
+          made.close
+        rescue StandardError
+          nil
+        end
+      end
+    end
+
+    # ---- The platform's API, on the module ----
+
+    def track(name, fields = nil, session_id: "")
+      platform&.track(name, fields, session_id: session_id) || ""
+    end
+
+    def identify(user_id, session_id: "")
+      platform ? platform.identify(user_id, session_id: session_id) : false
+    end
+
+    def lead(fields, session_id: "")
+      platform&.lead(fields, session_id: session_id)
+    end
+
+    def capture_exception(error, request: nil, status: 0, kind: "handled")
+      platform&.capture_exception(error, request: request, status: status, kind: kind)
+    end
+
+    def add_breadcrumb(text)
+      platform&.add_breadcrumb(text)
+    end
+
+    def audit(action, actor: "", target: "", details: nil, request: nil)
+      platform&.audit(action, actor: actor, target: target, details: details, request: request)
+    end
+
+    def enabled?(key, user: nil, default: false)
+      made = platform
+      made ? made.enabled?(key, user: user, default: default) : default
+    end
+
+    def check_form(request = nil, **options)
+      made = platform
+      made ? made.check_form(request, **options) : { ok: true, spam: false, reasons: [], checked: false }
+    end
+
+    def login_failed(request_or_ip)
+      platform&.login_failed(request_or_ip)
+    end
+
+    def session_id(request)
+      made = platform
+      made ? made.session_id(request) : ""
+    end
+
+    def job(name, report: nil, &block)
+      made = platform
+      made ? made.job(name, report: report, &block) : yield
+    end
+
+    def flush
+      @created_lock.synchronize { @created.dup }.each(&:flush)
+      nil
+    end
+  end
+
+  at_exit { SiteGoose.at_exit_hook($!) }
+end
+
+require_relative "sitegoose/railtie" if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: sitegoose
+version: !ruby/object:Gem::Version
+  version: 0.3.3
+platform: ruby
+authors:
+- steviec87
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+description: 'Rack middleware and a Railtie: a firewall with rate limits, shared blocks,
+  attack patterns and a browser check; error monitoring (Rails.error, Sidekiq); server
+  speed per route; crawler counts; server-side events, leads and audit log; feature
+  flags and maintenance mode; and the gems, settings and machine figures the Security
+  check needs. Standard library and rack only.'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/sitegoose.rb
+- lib/sitegoose/analytics.rb
+- lib/sitegoose/challenge.rb
+- lib/sitegoose/core.rb
+- lib/sitegoose/crawlers.rb
+- lib/sitegoose/errors.rb
+- lib/sitegoose/firewall.rb
+- lib/sitegoose/inventory.rb
+- lib/sitegoose/ip.rb
+- lib/sitegoose/middleware.rb
+- lib/sitegoose/performance.rb
+- lib/sitegoose/platform.rb
+- lib/sitegoose/posture.rb
+- lib/sitegoose/proxy.rb
+- lib/sitegoose/queries.rb
+- lib/sitegoose/query_text.rb
+- lib/sitegoose/railtie.rb
+- lib/sitegoose/request_rules.rb
+- lib/sitegoose/resources.rb
+- lib/sitegoose/sidekiq.rb
+- lib/sitegoose/small_modules.rb
+- lib/sitegoose/version.rb
+homepage: https://sitegoose.com
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Firewall, error monitoring and server analytics for your Ruby server, run
+  from your SiteGoose dashboard.
+test_files: []