trackguard 0.27.1 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e9860b115149813503e2063f8ed18c86fe82510c392a12a15eec6ecda39abbc
-  data.tar.gz: 34f0816d3a6193f71b985336fec9076e8c7889ff583c60165b0ddbcfc7a118da
+  metadata.gz: 1372d974514748b7cb553b4299b14de6345339c00947e24102be03ec7ac0be0d
+  data.tar.gz: 142f9a999003624989fa47ad7a422a5bc76c504dbb8666a8e676d49970490775
 SHA512:
-  metadata.gz: 8bccd308249f6c1dc2413abeb2b4c0e133736b3e75bd8f325ca64d042e9989c6b6c826d2959d92912965974062cb73b031f74413587bb2439b48dc1eef5e1a50
-  data.tar.gz: 5d56636a21dd20f458b48047ea2749ad54994e11db96c70574148b267440a0da0bd05706cd6ca9d22e1192b1d7f7b498c0733a75bed260a088978e08886f152e
+  metadata.gz: e3f01bd73d5701b53f8e7a3ef37ab3c3a43b016dc72e9388c8b8f9db225412380889b8fd13ae1df8783231fcdb6fde828f7f6807854c6ef9fa0ee6a4924dc774
+  data.tar.gz: 9ff260dc894d2cbc70e69062bb878d394be1913faf4edd61dad5b9c10c41db2e68805985832ba8f4b7762af6a6483e0b6a0d9690447993d0c3f5ea542d8eb98c

data/app/assets/javascripts/controllers/page_tracker_controller.js

@@ -11,8 +11,7 @@ export default class extends Controller {
     window.addEventListener("hashchange", this.boundHash)
 
     // Cover initial load if turbo:load already fired before connect()
-    // Pass initial=true so the job can deduplicate/enrich against the server-side record
-    this.trackCurrent(true)
+    this.trackCurrent()
   }
 
   disconnect() {
@@ -20,14 +19,14 @@ export default class extends Controller {
     window.removeEventListener("hashchange", this.boundHash)
   }
 
-  trackCurrent(initial = false) {
+  trackCurrent() {
     const path = window.location.pathname + window.location.hash
     if (path === this.lastTracked) return
     this.lastTracked = path
-    this.track(path, initial)
+    this.track(path)
   }
 
-  track(path, initial = false) {
+  track(path) {
     const token = document.querySelector('meta[name="csrf-token"]')?.content
     const traceId = document.querySelector('meta[name="trace-id"]')?.content
     const url = this.urlValue || document.querySelector('meta[name="trackguard-url"]')?.content
@@ -35,7 +34,7 @@ export default class extends Controller {
     fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json", "X-CSRF-Token": token || "" },
-      body: JSON.stringify({ path, trace_id: traceId, ref, initial })
+      body: JSON.stringify({ path, trace_id: traceId, ref })
     })
   }
 }

data/app/assets/stylesheets/trackguard/admin.css

@@ -240,6 +240,7 @@
 /* ── Table ─────────────────────────────────────────────────────────── */
 .tg-table {
   width: 100%;
+  table-layout: fixed;
   border-collapse: collapse;
   font-size: 0.875rem;
   margin-bottom: 2rem;
@@ -269,6 +270,14 @@
   text-align: right;
   color: #9ca3af;
   font-weight: 400;
+  white-space: nowrap;
+  width: 3.5rem;
+}
+
+.tg-td--label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
 .tg-td--break { word-break: break-all; }
@@ -291,6 +300,10 @@
   background: rgba(239, 68, 68, 0.05);
 }
 
+.tg-row--suspicious {
+  background: rgba(251, 191, 36, 0.1);
+}
+
 .tg-row--whitelisted {
   background: rgba(34, 197, 94, 0.05);
 }
@@ -352,6 +365,14 @@
   font-size: 0.875rem;
 }
 
+.tg-summary__layer {
+  width: 2.5rem;
+  text-align: center;
+  flex-shrink: 0;
+  color: #d1d5db;
+  font-size: 0.875rem;
+}
+
 .tg-summary__time {
   font-size: 0.8125rem;
   color: #9ca3af;
@@ -366,6 +387,13 @@
   vertical-align: middle;
 }
 
+.tg-suspicious-icon {
+  width: 1rem;
+  height: 1rem;
+  color: #f59e0b;
+  vertical-align: middle;
+}
+
 .tg-whitelist-icon {
   width: 1rem;
   height: 1rem;
@@ -373,6 +401,27 @@
   vertical-align: middle;
 }
 
+.tg-layer-badge {
+  display: inline-block;
+  font-size: 0.625rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  border-radius: 3px;
+  padding: 0.125rem 0.3rem;
+  line-height: 1.4;
+}
+
+.tg-layer-badge--js {
+  background: #d1fae5;
+  color: #065f46;
+}
+
+.tg-layer-badge--backend {
+  background: #ffedd5;
+  color: #c2410c;
+}
+
 /* ── Detail panel ──────────────────────────────────────────────────── */
 .tg-detail {
   padding: 0 1rem 1rem 1rem;
@@ -428,6 +477,8 @@
 
 .tg-dl__def--flagged { color: #dc2626; }
 
+.tg-dl__def--suspicious { color: #d97706; }
+
 .tg-dl__def--muted { color: #9ca3af; }
 
 .tg-dl__def--whitelisted { color: #059669; }

data/app/controllers/concerns/trackguard/page_tracker.rb

@@ -15,7 +15,7 @@ module Trackguard
     private
 
     def set_trace_id
-      @trace_id = SecureRandom.uuid
+      @trace_id = request.env["trackguard.trace_id"]
     end
 
     def track_page_view
@@ -30,11 +30,18 @@ module Trackguard
         session_id: session.id.to_s,
         trace_id: @trace_id,
         source: extract_source,
-        initial: false,
-        http_method: request.request_method
+        tracking_layer: "backend",
+        http_method: request.request_method,
+        prefetch: turbo_prefetch?
       )
     end
 
+    def turbo_prefetch?
+      request.headers["Purpose"] == "prefetch" ||
+        request.headers["Sec-Purpose"]&.start_with?("prefetch") ||
+        request.headers["X-Sec-Purpose"]&.start_with?("prefetch")
+    end
+
     def extract_source
       raw = params[:ref].presence || params[:utm_source].presence
       raw && raw.strip.downcase.first(64)

data/app/controllers/trackguard/admin/analytics_controller.rb

@@ -64,6 +64,7 @@ module Trackguard
         {
           path: view.path,
           ip: view.visitor&.ip,
+          suspicious_state: view.visitor.suspicious_state,
           flagged_at: view.visitor.flagged_at,
           flagged_by: view.visitor.flagged_by,
           whitelisted: view.visitor.whitelisted_ip&.active? || false,

data/app/controllers/trackguard/admin/base_controller.rb

@@ -12,7 +12,7 @@ module Trackguard
       end
 
       def valid_api_token?
-        expected = Trackguard.api_token
+        expected = Trackguard.local_api_token
         return false unless expected.present?
 
         token = request.headers["Authorization"]&.then { |h| h[/\ABearer (.+)\z/, 1] }

data/app/controllers/trackguard/admin/visitors_controller.rb

@@ -16,9 +16,11 @@ module Trackguard
       # rubocop:disable Metrics/AbcSize
       def flag
         if @visitor.update(
+          suspicious_state: "blocked",
           flagged_at: Time.current,
           flag_reason: params[:flag_reason].presence,
           flagged_by: params[:flagged_by].presence || Visitor::FLAGGED_BY.first,
+          suspicious_since_at: nil,
           name: params[:name].presence || BlockedUserAgent.matching_pattern(@visitor.user_agent)
         )
           respond_to do |format|
@@ -35,7 +37,8 @@ module Trackguard
       # rubocop:enable Metrics/AbcSize
 
       def unflag
-        @visitor.update!(flagged_at: nil, flag_reason: nil, flagged_by: nil)
+        @visitor.update!(suspicious_state: "normal", suspicious_since_at: nil,
+                         flagged_at: nil, flag_reason: nil, flagged_by: nil)
         respond_to do |format|
           format.html { redirect_back_or_to after_action_path }
           format.json { render json: { status: "ok", ip: @visitor.ip } }

data/app/controllers/trackguard/page_views_controller.rb

@@ -9,7 +9,7 @@ module Trackguard
         session_id: session.id.to_s,
         trace_id: params[:trace_id].to_s.presence,
         source: params[:ref].to_s.strip.downcase.first(64).presence,
-        initial: params[:initial] == true,
+        tracking_layer: "js",
         http_method: "GET"
       )
 

data/app/helpers/trackguard/application_helper.rb

@@ -1,10 +1,18 @@
 module Trackguard
   module ApplicationHelper
-    def trackguard_meta_tags
-      safe_join([
-                  tag.meta(name: "trackguard-url", content: trackguard.page_views_path),
-                  tag.meta(name: "trace-id", content: @trace_id)
-                ], "\n")
+    def trackguard_header_tags
+      tags = [ tag.meta(name: "trace-id", content: @trace_id) ]
+
+      case Trackguard.adapter
+      when Trackguard::Adapters::Local
+        tags << tag.meta(name: "trackguard-url", content: trackguard.page_views_path)
+      when Trackguard::Adapters::Hub
+        if Rails.env.production?
+          tags << tag.script(src: "#{Trackguard.hub_url}/track.js", data: { api_key: Trackguard.hub_api_key })
+        end
+      end
+
+      safe_join(tags, "\n")
     end
 
     def trackguard_nav_links

data/app/jobs/trackguard/detect_suspicious_visitors_job.rb

@@ -24,7 +24,7 @@ module Trackguard
                          .joins(:visitor)
                          .merge(Visitor.unflagged)
                          .preload(visitor: :whitelisted_ip)
-                         .select(:visitor_id, :session_id, :referer, :path, :trace_id)
+                         .select(:visitor_id, :session_id, :referer, :path, :trace_id, :tracking_layer)
                          .group_by(&:visitor)
 
       return if views_by_visitor.empty?
@@ -44,18 +44,29 @@ module Trackguard
 
       name = name_from_ua(visitor.user_agent)
 
+      if visitor.suspicious?
+        new_views = PageView
+                    .where(visitor: visitor)
+                    .where("created_at > ?", visitor.suspicious_since_at)
+                    .select(:tracking_layer, :trace_id)
+        result = evaluate_suspicious_escalation(visitor, new_views)
+        return if %i[blocked recovered].include?(result)
+      elsif views.any?(&:backend_layer?) && views.none?(&:js_layer?)
+        mark_suspicious!(visitor, name)
+      end
+
       if count >= HARD_FLAG_THRESHOLD
-        flag!(visitor, "#{count} page views in 24h (hard flag threshold)", name: name)
+        mark_blocked!(visitor, "#{count} page views in 24h (hard flag threshold)", name: name)
         return
       end
 
       if (reason = ua_flag_reason(visitor.user_agent))
-        flag!(visitor, reason, name: name)
+        mark_blocked!(visitor, reason, name: name)
         return
       end
 
       if (path = probe_path_hit(views))
-        flag!(visitor, "probe path hit: #{path}", name: name)
+        mark_blocked!(visitor, "probe path hit: #{path}", name: name)
         return
       end
 
@@ -64,7 +75,7 @@ module Trackguard
       return if count < MIN_VIEWS
 
       if views.all? { |pv| pv.session_id.nil? && pv.referer.nil? } && views.map(&:path).uniq.size == 1
-        flag!(visitor, "no session, no referrer, single path hit", name: name)
+        mark_blocked!(visitor, "no session, no referrer, single path hit", name: name)
         return
       end
 
@@ -86,10 +97,34 @@ module Trackguard
 
       return if score < FLAG_SCORE_THRESHOLD
 
-      flag!(visitor, reasons.join("; "), name: name)
+      mark_blocked!(visitor, reasons.join("; "), name: name)
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
+    def evaluate_suspicious_escalation(visitor, new_views)
+      return :unchanged if new_views.empty?
+
+      js_ids = new_views.select { |pv| pv.tracking_layer == "js" }.map(&:trace_id).compact
+
+      if any_unpaired_backend?(new_views, js_ids)
+        mark_blocked!(visitor, "continued backend-only visits since suspicious flag")
+        :blocked
+      elsif paired_backend_trace_ids(new_views, js_ids).any?
+        mark_normal!(visitor)
+        :recovered
+      else
+        :unchanged
+      end
+    end
+
+    def any_unpaired_backend?(views, js_trace_ids)
+      views.any? { |pv| pv.backend_layer? && !js_trace_ids.include?(pv.trace_id) }
+    end
+
+    def paired_backend_trace_ids(views, js_trace_ids)
+      views.select(&:backend_layer?).map(&:trace_id).compact & js_trace_ids
+    end
+
     def flag_shared_trace_id_visitors(cutoff)
       shared = PageView
                .where(created_at: cutoff..)
@@ -108,8 +143,8 @@ module Trackguard
         .where("wi.id IS NULL OR wi.expires_at <= ?", Time.current)
         .distinct
         .each do |visitor|
-          flag!(visitor, "trace_id shared across multiple visitors (cross-visitor bot detected)",
-                name: name_from_ua(visitor.user_agent))
+          mark_blocked!(visitor, "trace_id shared across multiple visitors (cross-visitor bot detected)",
+                        name: name_from_ua(visitor.user_agent))
         end
     end
 
@@ -125,8 +160,27 @@ module Trackguard
       "malformed user-agent (duplicate)" if user_agent.scan("Mozilla/5.0").size > 1
     end
 
-    def flag!(visitor, reason, name: nil)
-      visitor.update!(flagged_at: Time.current, flag_reason: reason, flagged_by: "claw:auto", name: name)
+    def mark_suspicious!(visitor, name)
+      return if visitor.suspicious? || visitor.blocked?
+
+      visitor.update!(suspicious_state: "suspicious", suspicious_since_at: Time.current, name: name)
+    end
+
+    def mark_normal!(visitor)
+      return if visitor.normal? || visitor.blocked?
+
+      visitor.update!(suspicious_state: "normal", suspicious_since_at: nil)
+    end
+
+    def mark_blocked!(visitor, reason, name: nil)
+      visitor.update!(
+        suspicious_state: "blocked",
+        flagged_at: Time.current,
+        flag_reason: reason,
+        flagged_by: "Recurring Job",
+        suspicious_since_at: nil,
+        name: name
+      )
     end
 
     def name_from_ua(user_agent)

data/app/jobs/trackguard/hub/submit_blocked_request_job.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Trackguard
+  module Hub
+    class SubmitBlockedRequestJob < ApplicationJob
+      queue_as :default
+
+      def perform(ip:, user_agent:, path:, http_method:, block_reason:)
+        uri  = URI("#{Trackguard.hub_url}/api/backend/blocked_requests")
+        body = {
+          blocked_request: {
+            ip: ip, user_agent: user_agent, path: path,
+            http_method: http_method, block_reason: block_reason
+          }
+        }.to_json
+
+        req                  = Net::HTTP::Post.new(uri)
+        req["X-Api-Key"]     = Trackguard.hub_api_key
+        req["Authorization"] = "Bearer #{Trackguard.hub_secret_key}"
+        req["Content-Type"]  = "application/json"
+        req.body             = body
+
+        opts     = { use_ssl: uri.scheme == "https", open_timeout: 3, read_timeout: 5 }
+        response = Net::HTTP.start(uri.hostname, uri.port, **opts) { |http| http.request(req) }
+
+        unless response.is_a?(Net::HTTPSuccess)
+          Rails.logger.warn(
+            "[Trackguard::Hub::SubmitBlockedRequestJob] Unexpected response #{response.code} for path=#{path}"
+          )
+        end
+      rescue StandardError => e
+        Rails.logger.warn("[Trackguard::Hub::SubmitBlockedRequestJob] Failed to submit blocked request: #{e.message}")
+      end
+    end
+  end
+end

data/app/jobs/trackguard/hub/submit_page_view_job.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Trackguard
+  module Hub
+    class SubmitPageViewJob < ApplicationJob
+      queue_as :default
+
+      def perform(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:, http_method:, **)
+        uri  = URI("#{Trackguard.hub_url}/api/backend/page_views")
+        body = {
+          page_view: {
+            path: path, referer: referer, session_id: session_id, trace_id: trace_id,
+            source: source, http_method: http_method, ip: ip, user_agent: user_agent
+          }
+        }.to_json
+
+        req                  = Net::HTTP::Post.new(uri)
+        req["X-Api-Key"]     = Trackguard.hub_api_key
+        req["Authorization"] = "Bearer #{Trackguard.hub_secret_key}"
+        req["Content-Type"]  = "application/json"
+        req.body             = body
+
+        opts     = { use_ssl: uri.scheme == "https", open_timeout: 3, read_timeout: 5 }
+        response = Net::HTTP.start(uri.hostname, uri.port, **opts) { |http| http.request(req) }
+
+        unless response.is_a?(Net::HTTPSuccess)
+          Rails.logger.warn(
+            "[Trackguard::Hub::SubmitPageViewJob] Unexpected response #{response.code} for path=#{path}"
+          )
+        end
+      rescue StandardError => e
+        Rails.logger.warn("[Trackguard::Hub::SubmitPageViewJob] Failed to submit page view: #{e.message}")
+      end
+    end
+  end
+end

data/app/jobs/trackguard/track_blocked_request_job.rb

@@ -5,20 +5,7 @@ module Trackguard
     queue_as :default
 
     def perform(ip:, user_agent:, path:, http_method:, block_reason:)
-      visitor = Visitor.find_or_create_by!(ip: ip) do |v|
-        v.user_agent    = user_agent
-        v.first_seen_at = Time.current
-        v.last_seen_at  = Time.current
-      end
-      visitor.update!(last_seen_at: Time.current, user_agent: user_agent)
-
-      BlockedRequest.create!(
-        path: path,
-        user_agent: user_agent,
-        http_method: http_method,
-        block_reason: block_reason,
-        visitor: visitor
-      )
+      TrackBlockedRequest.call(ip:, user_agent:, path:, http_method:, block_reason:)
     end
   end
 end

data/app/jobs/trackguard/track_page_view_job.rb

@@ -2,29 +2,10 @@ module Trackguard
   class TrackPageViewJob < ApplicationJob
     queue_as :default
 
-    def perform(path:, ip:, user_agent:, referer:, session_id: nil, trace_id: nil, source: nil, initial: false,
-                http_method: nil)
-      hashed_session_id = Digest::SHA256.hexdigest(session_id) if session_id.present?
-
-      visitor = Visitor.find_or_create_by!(ip: ip) do |v|
-        v.user_agent    = user_agent
-        v.first_seen_at = Time.current
-        v.last_seen_at  = Time.current
-      end
-      visitor.update!(last_seen_at: Time.current, user_agent: user_agent)
-
-      if initial && trace_id.present?
-        existing = PageView.find_by(trace_id: trace_id, visitor: visitor)
-        if existing
-          if path.include?("#") && !existing.path.include?("#") && path.start_with?("#{existing.path}#")
-            existing.update!(path: path)
-          end
-          return
-        end
-      end
-
-      PageView.create_with(source:, referer:, http_method:)
-              .find_or_create_by!(path:, user_agent:, session_id: hashed_session_id, trace_id:, visitor:)
+    def perform(path:, ip:, user_agent:, referer:, session_id: nil, trace_id: nil, source: nil,
+                tracking_layer: nil, http_method: nil)
+      TrackPageView.call(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:, tracking_layer:,
+                         http_method:)
     end
   end
 end

data/app/models/trackguard/page_view.rb

@@ -6,5 +6,8 @@ module Trackguard
     scope :this_month,    -> { where(created_at: 1.month.ago..) }
     scope :with_referrer, -> { where.not(referer: [ nil, "" ]) }
     scope :with_source,   -> { where.not(source: [ nil, "" ]) }
+
+    def js_layer?      = tracking_layer == "js"
+    def backend_layer? = tracking_layer == "backend"
   end
 end

data/app/models/trackguard/visitor.rb

@@ -2,17 +2,25 @@ module Trackguard
   class Visitor < ApplicationRecord
     self.table_name = "trackguard_visitors"
 
-    FLAGGED_BY = [ "User", "claw:auto" ].freeze
-    CACHE_KEY = "trackguard/flagged_ips".freeze
+    FLAGGED_BY        = [ "User", "claw:auto", "Recurring Job", "Internal Automation", "External Automation" ].freeze
+    SUSPICIOUS_STATES = %w[normal suspicious blocked].freeze
+    CACHE_KEY         = "trackguard/flagged_ips".freeze
 
     validates :flagged_by, inclusion: { in: FLAGGED_BY }, allow_blank: true
+    validates :suspicious_state, inclusion: { in: SUSPICIOUS_STATES }
 
     has_many :page_views,       class_name: "Trackguard::PageView", foreign_key: "visitor_id"
     has_many :blocked_requests, class_name: "Trackguard::BlockedRequest",  foreign_key: "visitor_id"
     has_one  :whitelisted_ip,   class_name: "Trackguard::WhitelistedIp",   foreign_key: "visitor_id"
 
-    scope :unflagged, -> { where(flagged_at: nil) }
-    scope :flagged,   -> { where.not(flagged_at: nil) }
+    scope :unflagged,           -> { where(flagged_at: nil) }
+    scope :flagged,             -> { where.not(flagged_at: nil) }
+    scope :suspicious_visitors, -> { where(suspicious_state: "suspicious") }
+    scope :blocked,             -> { where(suspicious_state: "blocked") }
+
+    def normal?     = suspicious_state == "normal"
+    def suspicious? = suspicious_state == "suspicious"
+    def blocked?    = suspicious_state == "blocked"
 
     def self.flagged?(ip)
       flagged_ips = Rails.cache.fetch(CACHE_KEY, expires_in: 5.minutes) do

data/app/services/trackguard/track_blocked_request.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Trackguard
+  class TrackBlockedRequest < ApplicationService
+    def initialize(ip:, user_agent:, path:, http_method:, block_reason:, visitor_scope: {})
+      @ip           = ip
+      @user_agent   = user_agent
+      @path         = path
+      @http_method  = http_method
+      @block_reason = block_reason
+      @visitor_scope = visitor_scope
+    end
+
+    def call
+      visitor = Visitor.find_or_create_by!(ip: @ip, **@visitor_scope) do |v|
+        v.user_agent    = @user_agent
+        v.first_seen_at = Time.current
+        v.last_seen_at  = Time.current
+      end
+      visitor.update!(last_seen_at: Time.current, user_agent: @user_agent)
+
+      BlockedRequest.create!(
+        path: @path,
+        user_agent: @user_agent,
+        http_method: @http_method,
+        block_reason: @block_reason,
+        visitor: visitor,
+        **@visitor_scope
+      )
+    end
+  end
+end

data/app/services/trackguard/track_page_view.rb

@@ -0,0 +1,35 @@
+module Trackguard
+  class TrackPageView < ApplicationService
+    def initialize(path:, ip:, user_agent:, referer:, session_id: nil, trace_id: nil,
+                   source: nil, tracking_layer: nil, http_method: nil, visitor_scope: {})
+      @path           = path
+      @ip             = ip
+      @user_agent     = user_agent
+      @referer        = referer
+      @session_id     = session_id
+      @trace_id       = trace_id
+      @source         = source
+      @tracking_layer = tracking_layer
+      @http_method    = http_method
+      @visitor_scope  = visitor_scope
+    end
+
+    def call
+      hashed_session_id = Digest::SHA256.hexdigest(@session_id) if @session_id.present?
+
+      visitor = Visitor.find_or_create_by!(ip: @ip, **@visitor_scope) do |v|
+        v.user_agent    = @user_agent
+        v.first_seen_at = Time.current
+        v.last_seen_at  = Time.current
+      end
+      visitor.update!(last_seen_at: Time.current, user_agent: @user_agent)
+
+      PageView.create!(
+        path: @path, user_agent: @user_agent, session_id: hashed_session_id,
+        trace_id: @trace_id, source: @source, referer: @referer,
+        http_method: @http_method, tracking_layer: @tracking_layer,
+        visitor: visitor, **@visitor_scope
+      )
+    end
+  end
+end

data/app/views/trackguard/admin/_stats_panel.html.erb

@@ -15,7 +15,7 @@
       <tbody>
         <% rows.each do |label, count| %>
           <tr>
-            <td class="tg-td"><%= label %></td>
+            <td class="tg-td tg-td--label"><%= label %></td>
             <td class="tg-td tg-td--num"><%= count %></td>
           </tr>
         <% end %>

data/app/views/trackguard/admin/_visit_row.html.erb

@@ -1,7 +1,8 @@
 <% visitor     = pv.visitor %>
-<% flagged     = visitor&.flagged_at.present? %>
+<% flagged     = visitor&.blocked? %>
+<% suspicious  = visitor&.suspicious? %>
 <% whitelisted = visitor&.whitelisted_ip&.active? %>
-<% row_classes = [ ("tg-row--flagged" if flagged), ("tg-row--whitelisted" if whitelisted) ].compact.join(" ") %>
+<% row_classes = [ ("tg-row--flagged" if flagged), ("tg-row--suspicious" if suspicious), ("tg-row--whitelisted" if whitelisted) ].compact.join(" ") %>
 <tr class="<%= row_classes %>">
   <td class="tg-td--bare">
     <details>
@@ -11,9 +12,13 @@
         <span class="tg-summary__path"><%= pv.path %></span>
         <span class="tg-summary__flag">
           <% if flagged %>
-            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="tg-flag-icon" title="Flagged">
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="tg-flag-icon" title="Blocked">
               <path fill-rule="evenodd" d="M8.485 2.495c.673-1.167 2.357-1.167 3.03 0l6.28 10.875c.673 1.167-.17 2.625-1.516 2.625H3.72c-1.347 0-2.189-1.458-1.515-2.625L8.485 2.495zM10 5a.75.75 0 01.75.75v3.5a.75.75 0 01-1.5 0v-3.5A.75.75 0 0110 5zm0 9a1 1 0 100-2 1 1 0 000 2z" clip-rule="evenodd" />
             </svg>
+          <% elsif suspicious %>
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="tg-suspicious-icon" title="Suspicious">
+              <path fill-rule="evenodd" d="M18 10a8 8 0 1 1-16 0 8 8 0 0 1 16 0Zm-8-5a.75.75 0 0 1 .75.75v4.5a.75.75 0 0 1-1.5 0v-4.5A.75.75 0 0 1 10 5Zm0 10a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z" clip-rule="evenodd" />
+            </svg>
           <% else %>
             —
           <% end %>
@@ -27,6 +32,15 @@
             —
           <% end %>
         </span>
+        <span class="tg-summary__layer">
+          <% if pv.tracking_layer == "js" %>
+            <span class="tg-layer-badge tg-layer-badge--js">js</span>
+          <% elsif pv.tracking_layer == "backend" %>
+            <span class="tg-layer-badge tg-layer-badge--backend">srv</span>
+          <% else %>
+            —
+          <% end %>
+        </span>
         <span class="tg-summary__time"><%= pv.created_at.strftime("%b %-d, %H:%M") %></span>
       </summary>
       <div class="tg-detail">
@@ -46,7 +60,7 @@
                     class: "tg-btn tg-btn--whitelist",
                     data: { confirm: "Whitelist #{visitor.ip} for 7 days?" } %>
             <% end %>
-            <% if flagged %>
+            <% if flagged || suspicious %>
               <%= button_to "Unflag", _actions[:unflag][:url],
                     method: _actions[:unflag][:method],
                     params: _actions[:unflag][:params],
@@ -88,15 +102,19 @@
                 <span class="tg-dl__def"><%= visitor&.name.presence || "—" %></span>
               </div>
               <div class="tg-dl__row">
-                <span class="tg-dl__term">Flag status</span>
+                <span class="tg-dl__term">Status</span>
                 <% if flagged %>
                   <span class="tg-dl__def tg-dl__def--flagged">
-                    Flagged <%= visitor.flagged_at.strftime("%b %-d %Y, %H:%M") %>
+                    Blocked <%= visitor.flagged_at.strftime("%b %-d %Y, %H:%M") %>
                     <% if visitor.flagged_by.present? %> by <strong><%= visitor.flagged_by %></strong><% end %>
                     <% if visitor.flag_reason.present? %> — <%= visitor.flag_reason %><% end %>
                   </span>
+                <% elsif suspicious %>
+                  <span class="tg-dl__def tg-dl__def--suspicious">
+                    Suspicious since <%= visitor.suspicious_since_at.strftime("%b %-d %Y, %H:%M") %>
+                  </span>
                 <% else %>
-                  <span class="tg-dl__def tg-dl__def--muted">Not flagged</span>
+                  <span class="tg-dl__def tg-dl__def--muted">Normal</span>
                 <% end %>
               </div>
               <div class="tg-dl__row">
@@ -130,6 +148,15 @@
                 <span class="tg-dl__term">Source</span>
                 <span class="tg-dl__def"><%= pv.source.presence || "—" %></span>
               </div>
+              <div class="tg-dl__row">
+                <span class="tg-dl__term">Layer</span>
+                <span class="tg-dl__def">
+                  <% if pv.tracking_layer == "js" %>JS (client)
+                  <% elsif pv.tracking_layer == "backend" %>Backend (server)
+                  <% else %><span class="tg-dl__def--muted">—</span>
+                  <% end %>
+                </span>
+              </div>
             </div>
           </div>
         </div>

data/config/importmap.rb

@@ -1 +1,3 @@
-pin_all_from File.expand_path("../app/assets/javascripts/controllers", __dir__), under: "controllers"
+if Trackguard.adapter.is_a?(Trackguard::Adapters::Local)
+  pin_all_from File.expand_path("../app/assets/javascripts/controllers", __dir__), under: "controllers"
+end

data/lib/generators/trackguard/install_generator.rb

@@ -18,6 +18,10 @@ module Trackguard
       migration_template "create_trackguard_blocked_user_agents.rb",
                          "db/migrate/create_trackguard_blocked_user_agents.rb"
       migration_template "create_trackguard_blocked_paths.rb", "db/migrate/create_trackguard_blocked_paths.rb"
+      migration_template "add_tracking_layer_to_trackguard_visits.rb",
+                         "db/migrate/add_tracking_layer_to_trackguard_visits.rb"
+      migration_template "add_suspicious_state_to_trackguard_visitors.rb",
+                         "db/migrate/add_suspicious_state_to_trackguard_visitors.rb"
     end
 
     def print_next_steps

data/lib/generators/trackguard/templates/add_suspicious_state_to_trackguard_visitors.rb

@@ -0,0 +1,12 @@
+class AddSuspiciousStateToTrackguardVisitors < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :trackguard_visitors, :suspicious_state, :string, null: false, default: "normal"
+    add_column :trackguard_visitors, :suspicious_since_at, :datetime
+
+    reversible do |dir|
+      dir.up do
+        execute "UPDATE trackguard_visitors SET suspicious_state = 'blocked' WHERE flagged_at IS NOT NULL"
+      end
+    end
+  end
+end

data/lib/generators/trackguard/templates/add_tracking_layer_to_trackguard_visits.rb

@@ -0,0 +1,5 @@
+class AddTrackingLayerToTrackguardVisits < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :trackguard_visits, :tracking_layer, :string
+  end
+end

data/lib/generators/trackguard/templates/create_trackguard_visits.rb

@@ -10,6 +10,7 @@ class CreateTrackguardVisits < ActiveRecord::Migration[<%= ActiveRecord::Migrati
       t.string    :source
       t.string    :block_reason
       t.string    :http_method
+      t.string    :tracking_layer
       t.references :visitor,     null: false, foreign_key: { to_table: :trackguard_visitors }
       t.datetime  :created_at,   null: false
     end

data/lib/trackguard/adapters/base.rb

@@ -8,7 +8,8 @@ module Trackguard
       def whitelisted_ip?(ip)             = raise NotImplementedError, "#{self.class}#whitelisted_ip?"
       def flagged_visitor?(ip)            = raise NotImplementedError, "#{self.class}#flagged_visitor?"
 
-      def track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:, initial:, http_method:)
+      def track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:, tracking_layer:,
+                          http_method:, prefetch: false)
         return if blocked_user_agent?(user_agent)
         return if blocked_path?(path)
         return if path.blank? || path.start_with?(Trackguard.admin_path)
@@ -16,7 +17,7 @@ module Trackguard
         perform_track_page_view(
           path: path, ip: ip, user_agent: user_agent, referer: referer,
           session_id: session_id, trace_id: trace_id, source: source,
-          initial: initial, http_method: http_method
+          tracking_layer: tracking_layer, http_method: http_method, prefetch: prefetch
         )
       end
 
@@ -26,8 +27,8 @@ module Trackguard
 
       protected
 
-      def perform_track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:, initial:,
-                                  http_method:)
+      def perform_track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:,
+                                  tracking_layer:, http_method:, prefetch: false)
         raise NotImplementedError, "#{self.class}#perform_track_page_view"
       end
     end

data/lib/trackguard/adapters/hub.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Trackguard
+  module Adapters
+    class Hub < Base
+      CACHE_KEY = "trackguard/hub_rules"
+      STALE_KEY = "trackguard/hub_rules/stale"
+      ETAG_KEY  = "trackguard/hub_rules/etag"
+
+      def blocked_user_agent?(user_agent)
+        rules.fetch(:blocked_user_agents, []).any? do |p|
+          user_agent.to_s.downcase.include?(p.downcase)
+        end
+      end
+
+      def blocked_path?(path)
+        rules.fetch(:blocked_paths, []).any? do |p|
+          path.to_s.downcase.include?(p.downcase)
+        end
+      end
+
+      def whitelisted_ip?(ip)
+        rules.fetch(:whitelisted_ips, []).include?(ip)
+      end
+
+      def flagged_visitor?(ip)
+        rules.fetch(:flagged_ips, []).include?(ip)
+      end
+
+      def track_blocked_request(ip:, user_agent:, path:, http_method:, block_reason:)
+        Trackguard::Hub::SubmitBlockedRequestJob.perform_later(
+          ip: ip, user_agent: user_agent, path: path, http_method: http_method, block_reason: block_reason
+        )
+      end
+
+      protected
+
+      def perform_track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:,
+                                  tracking_layer:, http_method:, prefetch: false)
+        return if prefetch
+
+        Trackguard::Hub::SubmitPageViewJob.perform_later(
+          path: path, ip: ip, user_agent: user_agent, referer: referer,
+          session_id: session_id, trace_id: trace_id, source: source,
+          tracking_layer: tracking_layer, http_method: http_method
+        )
+      end
+
+      private
+
+      def rules
+        Rails.cache.fetch(CACHE_KEY, expires_in: Trackguard.hub_rules_ttl, race_condition_ttl: 10) do
+          fresh = fetch_rules_from_hub
+          Rails.cache.write(STALE_KEY, fresh, expires_in: 24.hours)
+          fresh
+        end
+      rescue StandardError => e
+        Rails.logger.warn("[Trackguard::Adapters::Hub] Failed to fetch rules: #{e.message}")
+        Rails.cache.read(STALE_KEY) || {}
+      end
+
+      def fetch_rules_from_hub
+        uri = URI("#{Trackguard.hub_url}/api/backend/rules")
+        response = execute_http(uri, build_request(uri))
+
+        return Rails.cache.read(STALE_KEY) || {} if response.is_a?(Net::HTTPNotModified)
+
+        raise "HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        fresh = JSON.parse(response.body, symbolize_names: true)
+        Rails.cache.write(ETAG_KEY, response["ETag"], expires_in: 24.hours) if response["ETag"]
+        fresh
+      end
+
+      def build_request(uri)
+        req = Net::HTTP::Get.new(uri)
+        req["Authorization"] = "Bearer #{Trackguard.hub_secret_key}"
+        req["X-Api-Key"] = Trackguard.hub_api_key
+        req["Accept"] = "application/json"
+        etag = Rails.cache.read(ETAG_KEY)
+        req["If-None-Match"] = etag if etag
+        req
+      end
+
+      def execute_http(uri, request)
+        opts = { use_ssl: uri.scheme == "https", open_timeout: 3, read_timeout: 5 }
+        Net::HTTP.start(uri.hostname, uri.port, **opts) { |http| http.request(request) }
+      end
+    end
+  end
+end

data/lib/trackguard/adapters/local.rb

@@ -31,8 +31,8 @@ module Trackguard
 
       protected
 
-      def perform_track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:, initial:,
-                                  http_method:)
+      def perform_track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:,
+                                  tracking_layer:, http_method:, prefetch: false)
         TrackPageViewJob.perform_later(
           path: path,
           ip: ip,
@@ -41,7 +41,7 @@ module Trackguard
           session_id: session_id,
           trace_id: trace_id,
           source: source,
-          initial: initial,
+          tracking_layer: tracking_layer,
           http_method: http_method
         )
       end

data/lib/trackguard/engine.rb

@@ -4,10 +4,8 @@ module Trackguard
   class Engine < ::Rails::Engine
     isolate_namespace Trackguard
 
-    initializer "trackguard.helpers" do
-      ActiveSupport.on_load(:action_controller) do
-        helper Trackguard::ApplicationHelper
-      end
+    config.to_prepare do
+      ActionController::Base.helper Trackguard::ApplicationHelper
     end
 
     initializer "trackguard.assets" do |app|
@@ -18,6 +16,10 @@ module Trackguard
       app.config.importmap.paths << root.join("config/importmap.rb") if app.config.respond_to?(:importmap)
     end
 
+    initializer "trackguard.trace_id_middleware" do |app|
+      app.middleware.use Trackguard::TraceIdMiddleware
+    end
+
     config.after_initialize do
       Trackguard::RackAttack.configure
     end

data/lib/trackguard/trace_id_middleware.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Trackguard
+  class TraceIdMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      env["trackguard.trace_id"] = SecureRandom.uuid
+      @app.call(env)
+    end
+  end
+end

data/lib/trackguard/version.rb

@@ -1,3 +1,3 @@
 module Trackguard
-  VERSION = "0.27.1".freeze
+  VERSION = "0.29.0".freeze
 end

data/lib/trackguard.rb

@@ -3,13 +3,16 @@
 require "trackguard/version"
 require "trackguard/engine"
 require "trackguard/rack_attack"
+require "trackguard/trace_id_middleware"
 require "trackguard/adapters/base"
 require "trackguard/adapters/local"
+require "trackguard/adapters/hub"
 
 module Trackguard
   class << self
-    attr_writer :authenticate_admin_with, :admin_layout, :admin_path, :back_label, :api_token, :throttle_limit,
-                :throttle_period
+    attr_writer :authenticate_admin_with, :admin_layout, :admin_path, :back_label, :local_api_token, :throttle_limit,
+                :throttle_period, :hub_secret_key, :hub_api_key, :hub_rules_ttl
+    attr_accessor :hub_url
 
     def authenticate_admin_with
       @authenticate_admin_with ||= proc {}
@@ -27,8 +30,8 @@ module Trackguard
       @back_label ||= "Back to app"
     end
 
-    def api_token
-      @api_token.to_s
+    def local_api_token
+      @local_api_token.to_s
     end
 
     def throttle_limit
@@ -39,6 +42,10 @@ module Trackguard
       @throttle_period ||= 60
     end
 
+    def hub_secret_key = @hub_secret_key.to_s
+    def hub_api_key    = @hub_api_key.to_s
+    def hub_rules_ttl = @hub_rules_ttl ||= 5.minutes
+
     def adapter
       @adapter ||= Trackguard::Adapters::Local.new
     end

data/trackguard.gemspec

@@ -15,4 +15,5 @@ Gem::Specification.new do |s|
   s.add_dependency "rack-attack"
   s.add_dependency "rails", ">= 8.1"
   s.metadata["rubygems_mfa_required"] = "true"
+  s.metadata["changelog_uri"]         = "https://github.com/riggy/trackguard/blob/main/CHANGELOG.md"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trackguard
 version: !ruby/object:Gem::Version
-  version: 0.27.1
+  version: 0.29.0
 platform: ruby
 authors:
 - Krzysztof Rygielski
@@ -59,6 +59,8 @@ files:
 - app/controllers/trackguard/page_views_controller.rb
 - app/helpers/trackguard/application_helper.rb
 - app/jobs/trackguard/detect_suspicious_visitors_job.rb
+- app/jobs/trackguard/hub/submit_blocked_request_job.rb
+- app/jobs/trackguard/hub/submit_page_view_job.rb
 - app/jobs/trackguard/track_blocked_request_job.rb
 - app/jobs/trackguard/track_page_view_job.rb
 - app/models/trackguard/blocked_path.rb
@@ -70,6 +72,8 @@ files:
 - app/models/trackguard/whitelisted_ip.rb
 - app/services/trackguard/analytics_query.rb
 - app/services/trackguard/application_service.rb
+- app/services/trackguard/track_blocked_request.rb
+- app/services/trackguard/track_page_view.rb
 - app/views/layouts/trackguard/admin.html.erb
 - app/views/trackguard/admin/_nav.html.erb
 - app/views/trackguard/admin/_stats_panel.html.erb
@@ -82,6 +86,8 @@ files:
 - config/importmap.rb
 - config/routes.rb
 - lib/generators/trackguard/install_generator.rb
+- lib/generators/trackguard/templates/add_suspicious_state_to_trackguard_visitors.rb
+- lib/generators/trackguard/templates/add_tracking_layer_to_trackguard_visits.rb
 - lib/generators/trackguard/templates/create_trackguard_blocked_paths.rb
 - lib/generators/trackguard/templates/create_trackguard_blocked_user_agents.rb
 - lib/generators/trackguard/templates/create_trackguard_visitors.rb
@@ -90,9 +96,11 @@ files:
 - lib/tasks/trackguard.rake
 - lib/trackguard.rb
 - lib/trackguard/adapters/base.rb
+- lib/trackguard/adapters/hub.rb
 - lib/trackguard/adapters/local.rb
 - lib/trackguard/engine.rb
 - lib/trackguard/rack_attack.rb
+- lib/trackguard/trace_id_middleware.rb
 - lib/trackguard/version.rb
 - trackguard.gemspec
 homepage: https://github.com/riggy/trackguard
@@ -100,6 +108,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  changelog_uri: https://github.com/riggy/trackguard/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib