trackguard 0.15.1

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

@@ -0,0 +1,17 @@
+module Trackguard
+  module Admin
+    class DashboardsController < BaseController
+      def show
+        @total_today  = PageView.today.count
+        @total_week   = PageView.this_week.count
+        @total_month  = PageView.this_month.count
+
+        @top_pages     = PageView.last_30.group(:path).order("count_all DESC").limit(5).count
+        @top_referrers = PageView.last_30.with_referrer.group(:referer).order("count_all DESC").limit(5).count
+        @top_sources   = PageView.last_30.with_source.group(:source).order("count_all DESC").limit(5).count
+
+        @recent = PageView.order(created_at: :desc).limit(20).includes(visitor: :whitelisted_ip)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+module Trackguard
+  module Admin
+    class VisitorsController < BaseController
+      skip_before_action :verify_authenticity_token, if: :valid_api_token?
+      before_action :set_visitor
+
+      rescue_from ActiveRecord::RecordNotFound do
+        respond_to do |format|
+          format.html { redirect_to dashboard_path, alert: "Visitor not found." }
+          format.json { render json: { error: "Visitor not found" }, status: :not_found }
+        end
+      end
+
+      def flag
+        if @visitor.update(
+          flagged_at: Time.current,
+          flag_reason: params[:flag_reason].presence,
+          flagged_by: params[:flagged_by].presence || Visitor::FLAGGED_BY.first
+        )
+          respond_to do |format|
+            format.html { redirect_back_or_to dashboard_path }
+            format.json { render json: { status: "ok", ip: @visitor.ip, flagged_at: @visitor.flagged_at } }
+          end
+        else
+          respond_to do |format|
+            format.html { redirect_back_or_to dashboard_path, alert: @visitor.errors.full_messages.join(", ") }
+            format.json { render json: { errors: @visitor.errors.full_messages }, status: :unprocessable_entity }
+          end
+        end
+      end
+
+      def unflag
+        @visitor.update!(flagged_at: nil, flag_reason: nil, flagged_by: nil)
+        respond_to do |format|
+          format.html { redirect_back_or_to dashboard_path }
+          format.json { render json: { status: "ok", ip: @visitor.ip } }
+        end
+      end
+
+      private
+
+      def authenticate_admin!
+        return if valid_api_token?
+
+        super
+      end
+
+      def set_visitor
+        @visitor = if params[:ip].present?
+                     Visitor.find_by!(ip: params[:ip])
+                   else
+                     Visitor.find(params[:id])
+                   end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Trackguard
+  module Admin
+    class VisitsController < BaseController
+      PER_PAGE = 20
+
+      def index
+        @page   = [ (params[:page] || 1).to_i, 1 ].max
+        @total  = PageView.count
+        @pages  = (@total.to_f / PER_PAGE).ceil
+        @visits = PageView.order(created_at: :desc)
+                          .limit(PER_PAGE)
+                          .offset((@page - 1) * PER_PAGE)
+                          .includes(visitor: :whitelisted_ip)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+module Trackguard
+  module Admin
+    class WhitelistedIpsController < BaseController
+      skip_before_action :verify_authenticity_token, if: :valid_api_token?
+      before_action :set_visitor
+
+      rescue_from ActiveRecord::RecordNotFound do
+        respond_to do |format|
+          format.html { redirect_to dashboard_path, alert: "Visitor not found." }
+          format.json { render json: { error: "Visitor not found" }, status: :not_found }
+        end
+      end
+
+      def create
+        record = WhitelistedIp.find_or_initialize_by(ip: @visitor.ip)
+        record.visitor    = @visitor
+        record.expires_at = params[:expires_at].presence || 7.days.from_now
+        record.save!
+        respond_to do |format|
+          format.html { redirect_back_or_to dashboard_path }
+          format.json { render json: { status: "ok", ip: @visitor.ip, expires_at: record.expires_at } }
+        end
+      rescue ActiveRecord::RecordInvalid => e
+        respond_to do |format|
+          format.html { redirect_back_or_to dashboard_path, alert: e.message }
+          format.json { render json: { status: "error", message: e.message }, status: :unprocessable_entity }
+        end
+      end
+
+      def destroy
+        record = @visitor.whitelisted_ip
+
+        if record
+          record.destroy!
+          respond_to do |format|
+            format.html { redirect_back_or_to dashboard_path }
+            format.json { render json: { status: "ok", ip: @visitor.ip } }
+          end
+        else
+          respond_to do |format|
+            format.html { redirect_back_or_to dashboard_path, alert: "No whitelist entry found." }
+            format.json { render json: { error: "Not whitelisted" }, status: :not_found }
+          end
+        end
+      end
+
+      private
+
+      def authenticate_admin!
+        return if valid_api_token?
+
+        super
+      end
+
+      def set_visitor
+        @visitor = if params[:ip].present?
+                     Visitor.find_by!(ip: params[:ip])
+                   else
+                     Visitor.find(params[:id])
+                   end
+      end
+    end
+  end
+end

data/app/controllers/trackguard/page_views_controller.rb

@@ -0,0 +1,18 @@
+module Trackguard
+  class PageViewsController < ApplicationController
+    def create
+      PageViewRecorder.call(
+        path: params[:path].to_s,
+        ip: request.remote_ip,
+        user_agent: request.user_agent.to_s,
+        referer: request.referer,
+        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
+      )
+
+      head :no_content
+    end
+  end
+end

data/app/helpers/trackguard/application_helper.rb

@@ -0,0 +1,10 @@
+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")
+    end
+  end
+end

data/app/jobs/trackguard/detect_suspicious_visitors_job.rb

@@ -0,0 +1,130 @@
+module Trackguard
+  class DetectSuspiciousVisitorsJob < ApplicationJob
+    queue_as :default
+
+    HARD_FLAG_THRESHOLD  = 50
+    HIGH_VOLUME_MIN      = 20
+    MEDIUM_VOLUME_MIN    = 10
+    FLAG_SCORE_THRESHOLD = 6
+    MIN_VIEWS            = 3
+
+    WEIGHTS = {
+      high_volume: 4,
+      medium_volume: 2,
+      no_session: 3,
+      no_referer: 2
+    }.freeze
+
+    def perform
+      recent_cutoff = 24.hours.ago
+
+      flag_shared_trace_id_visitors(recent_cutoff)
+
+      views_by_visitor = PageView
+                         .where(created_at: recent_cutoff..)
+                         .joins(:visitor)
+                         .merge(Visitor.unflagged)
+                         .preload(visitor: :whitelisted_ip)
+                         .select(:visitor_id, :session_id, :referer, :path, :trace_id)
+                         .group_by(&:visitor)
+
+      return if views_by_visitor.empty?
+
+      views_by_visitor.each do |visitor, views|
+        analyze_visitor(visitor, views)
+      end
+    end
+
+    private
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+    def analyze_visitor(visitor, views)
+      count = views.size
+      return if count.zero?
+      return if visitor.whitelisted_ip&.active?
+
+      if count >= HARD_FLAG_THRESHOLD
+        flag!(visitor, "#{count} page views in 24h (hard flag threshold)")
+        return
+      end
+
+      if (reason = ua_flag_reason(visitor.user_agent))
+        flag!(visitor, reason)
+        return
+      end
+
+      # Don't flag casual visitors with very few views — on a single-page site,
+      # legitimate users naturally hit only "/" once or twice.
+      return if count < MIN_VIEWS
+
+      if views.all? { |pv| pv.session_id.nil? && pv.referer.nil? && pv.path == "/" }
+        flag!(visitor, "no session, no referrer, single root hit")
+        return
+      end
+
+      score   = 0
+      reasons = []
+
+      if count >= HIGH_VOLUME_MIN
+        score += WEIGHTS[:high_volume]
+        reasons << "#{count} page views in 24h"
+      elsif count >= MEDIUM_VOLUME_MIN
+        score += WEIGHTS[:medium_volume]
+        reasons << "#{count} page views in 24h"
+      end
+
+      if blank_ratio(views, :session_id) > 0.8
+        score += WEIGHTS[:no_session]
+        reasons << "#{pct(views, :session_id)}% of views had no session"
+      end
+
+      if blank_ratio(views, :referer) > 0.0
+        score += WEIGHTS[:no_referer]
+        reasons << "#{pct(views, :referer)}% of views had no referer"
+      end
+
+      return if score < FLAG_SCORE_THRESHOLD
+
+      flag!(visitor, reasons.join("; "))
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+    def flag_shared_trace_id_visitors(cutoff)
+      shared = PageView
+               .where(created_at: cutoff..)
+               .where.not(trace_id: nil)
+               .group(:trace_id)
+               .having("COUNT(DISTINCT visitor_id) > 1")
+               .pluck(:trace_id)
+
+      return if shared.empty?
+
+      Visitor
+        .unflagged
+        .joins("LEFT OUTER JOIN trackguard_whitelisted_ips wi ON wi.visitor_id = trackguard_visitors.id")
+        .joins(:page_views)
+        .where(trackguard_page_views: { trace_id: shared, created_at: cutoff.. })
+        .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)")
+        end
+    end
+
+    def ua_flag_reason(user_agent)
+      "blank or minimal user-agent" if user_agent.blank? || user_agent.to_s.length < 10
+    end
+
+    def flag!(visitor, reason)
+      visitor.update!(flagged_at: Time.current, flag_reason: reason, flagged_by: "claw:auto")
+    end
+
+    def blank_ratio(views, attr)
+      views.count { |v| v.public_send(attr).blank? }.to_f / views.size
+    end
+
+    def pct(views, attr)
+      (blank_ratio(views, attr) * 100).round
+    end
+  end
+end

data/app/jobs/trackguard/track_page_view_job.rb

@@ -0,0 +1,29 @@
+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)
+      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:)
+              .find_or_create_by!(path:, user_agent:, session_id: hashed_session_id, trace_id:, visitor:)
+    end
+  end
+end

data/app/models/trackguard/blocked_user_agent.rb

@@ -0,0 +1,16 @@
+module Trackguard
+  class BlockedUserAgent < ApplicationRecord
+    self.table_name = "trackguard_blocked_user_agents"
+
+    CACHE_KEY = "trackguard/blocked_user_agent_patterns".freeze
+
+    validates :pattern, presence: true, uniqueness: true
+
+    def self.blocked?(user_agent)
+      patterns = Rails.cache.fetch(CACHE_KEY, expires_in: 10.minutes) do
+        pluck(:pattern)
+      end
+      patterns.any? { |p| user_agent.to_s.downcase.include?(p.downcase) }
+    end
+  end
+end

data/app/models/trackguard/page_view.rb

@@ -0,0 +1,17 @@
+module Trackguard
+  class PageView < ApplicationRecord
+    self.table_name = "trackguard_page_views"
+
+    belongs_to :visitor, class_name: "Trackguard::Visitor"
+
+    validates :path, presence: true
+
+    scope :today,         -> { where(created_at: Time.current.beginning_of_day..) }
+    scope :this_week,     -> { where(created_at: 1.week.ago..) }
+    scope :this_month,    -> { where(created_at: 1.month.ago..) }
+    scope :last_30,       -> { where(created_at: 30.days.ago..) }
+    scope :last_24h,      -> { where(created_at: 24.hours.ago..) }
+    scope :with_referrer, -> { where.not(referer: [ nil, "" ]) }
+    scope :with_source,   -> { where.not(source: [ nil, "" ]) }
+  end
+end

data/app/models/trackguard/visitor.rb

@@ -0,0 +1,24 @@
+module Trackguard
+  class Visitor < ApplicationRecord
+    self.table_name = "trackguard_visitors"
+
+    FLAGGED_BY = [ "User", "claw:auto" ].freeze
+    CACHE_KEY = "trackguard/flagged_ips".freeze
+
+    validates :flagged_by, inclusion: { in: FLAGGED_BY }, allow_blank: true
+
+    has_many :page_views, class_name: "Trackguard::PageView", 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) }
+
+    def self.flagged?(ip)
+      flagged_ips = Rails.cache.fetch(CACHE_KEY, expires_in: 5.minutes) do
+        flagged.pluck(:ip)
+      end
+
+      flagged_ips.include?(ip)
+    end
+  end
+end

data/app/models/trackguard/whitelisted_ip.rb

@@ -0,0 +1,26 @@
+module Trackguard
+  class WhitelistedIp < ApplicationRecord
+    self.table_name = "trackguard_whitelisted_ips"
+
+    CACHE_KEY = "trackguard/whitelisted_ips".freeze
+
+    belongs_to :visitor, class_name: "Trackguard::Visitor", optional: true
+
+    validates :ip,         presence: true, uniqueness: true
+    validates :expires_at, presence: true
+
+    scope :active, -> { where(expires_at: Time.current..) }
+
+    def self.whitelisted?(ip)
+      active_ips = Rails.cache.fetch(CACHE_KEY, expires_in: 10.minutes) do
+        active.pluck(:ip)
+      end
+
+      active_ips.include?(ip)
+    end
+
+    def active?
+      expires_at > Time.current
+    end
+  end
+end

data/app/services/trackguard/application_service.rb

@@ -0,0 +1,7 @@
+module Trackguard
+  class ApplicationService
+    def self.call(...)
+      new(...).call
+    end
+  end
+end

data/app/services/trackguard/page_view_recorder.rb

@@ -0,0 +1,39 @@
+module Trackguard
+  class PageViewRecorder < ApplicationService
+    BOT_REGEX = /
+      Googlebot|Bingbot|Slurp|DuckDuckBot|Baidu|YandexBot|
+      facebookexternalhit|Twitterbot|LinkedInBot|
+      curl|wget|python-requests|python-urllib|
+      Go-http-client|libwww|Java|Ruby|
+      bot|crawl|spider
+    /ix
+
+    def initialize(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source: nil, initial: false)
+      @path       = path.to_s
+      @ip         = ip
+      @user_agent = user_agent.to_s
+      @referer    = referer
+      @session_id = session_id
+      @trace_id   = trace_id
+      @source     = source.presence
+      @initial    = initial
+    end
+
+    def call
+      return if BOT_REGEX.match?(@user_agent)
+      return if BlockedUserAgent.blocked?(@user_agent)
+      return if @path.blank? || @path.start_with?("/admin")
+
+      TrackPageViewJob.perform_later(
+        path: @path,
+        ip: @ip,
+        user_agent: @user_agent,
+        referer: @referer,
+        session_id: @session_id,
+        trace_id: @trace_id,
+        source: @source,
+        initial: @initial
+      )
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title><%= content_for?(:title) ? yield(:title) : "Trackguard" %></title>
+  <%= stylesheet_link_tag "trackguard/admin", media: "all" %>
+</head>
+<body class="tg-body">
+  <header class="tg-header">
+    <div class="tg-container">
+      <div class="tg-header__inner">
+        <span class="tg-brand">
+          <svg class="tg-brand__logo" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 22" aria-hidden="true">
+            <defs>
+              <linearGradient id="tg-shield-grad" x1="0" y1="0" x2="0" y2="1">
+                <stop offset="0%" stop-color="#1e3a5f"/>
+                <stop offset="100%" stop-color="#0d1f3c"/>
+              </linearGradient>
+            </defs>
+            <!-- Shield -->
+            <path d="M10 1L19 4.5V11.5C19 16.4 15 20.3 10 21.5C5 20.3 1 16.4 1 11.5V4.5Z"
+                  fill="url(#tg-shield-grad)" stroke="#3b82f6" stroke-width="1.25" stroke-linejoin="round"/>
+            <!-- Left rail -->
+            <line x1="7.5" y1="6" x2="7.5" y2="17" stroke="#60a5fa" stroke-width="1.6" stroke-linecap="round"/>
+            <!-- Right rail -->
+            <line x1="12.5" y1="6" x2="12.5" y2="17" stroke="#60a5fa" stroke-width="1.6" stroke-linecap="round"/>
+            <!-- Cross-tie 1 -->
+            <line x1="6.25" y1="8"    x2="13.75" y2="8"    stroke="#3b82f6" stroke-width="1.25" stroke-linecap="round"/>
+            <!-- Cross-tie 2 -->
+            <line x1="6.25" y1="11.5" x2="13.75" y2="11.5" stroke="#3b82f6" stroke-width="1.25" stroke-linecap="round"/>
+            <!-- Cross-tie 3 -->
+            <line x1="6.25" y1="15"   x2="13.75" y2="15"   stroke="#3b82f6" stroke-width="1.25" stroke-linecap="round"/>
+          </svg>
+          Trackguard
+        </span>
+
+        <a class="tg-back-link" href="<%= Trackguard.back_url %>">
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" aria-hidden="true">
+            <path stroke="currentColor" stroke-width="1.5" stroke-linecap="round"
+                  stroke-linejoin="round" fill="none" d="M10.5 3.5L5.5 8l5 4.5"/>
+          </svg>
+          <%= Trackguard.back_label %>
+        </a>
+      </div>
+    </div>
+  </header>
+  <nav class="tg-nav">
+    <div class="tg-container">
+      <a href="<%= dashboard_path %>" class="tg-nav__link<%= ' tg-nav__link--active' if request.path == dashboard_path %>">Dashboard</a>
+      <a href="<%= visits_path %>" class="tg-nav__link<%= ' tg-nav__link--active' if request.path.start_with?(visits_path) %>">All Visits</a>
+    </div>
+  </nav>
+  <main class="tg-main">
+    <div class="tg-container">
+      <%= yield %>
+    </div>
+  </main>
+  <script>
+    (function () {
+      var key = 'tg-scroll';
+      var saved = sessionStorage.getItem(key);
+      if (saved !== null) { window.scrollTo(0, parseInt(saved, 10)); sessionStorage.removeItem(key); }
+      document.addEventListener('submit', function () { sessionStorage.setItem(key, window.scrollY); });
+    })();
+  </script>
+</body>
+</html>