beskar 0.0.1 → 0.1.0

data/lib/generators/beskar/install/install_generator.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module Beskar
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc "Creates a Beskar initializer and runs migrations"
+
+      def self.next_migration_number(path)
+        if @prev_migration_nr
+          @prev_migration_nr += 1
+        else
+          @prev_migration_nr = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+        end
+        @prev_migration_nr.to_s
+      end
+
+      def copy_initializer
+        template "initializer.rb.tt", "config/initializers/beskar.rb"
+      end
+
+      def mount_engine
+        route_text = "mount Beskar::Engine => '/beskar'"
+
+        # Check if the route already exists
+        if File.read("config/routes.rb").include?(route_text)
+          say "Route already mounted, skipping...", :yellow
+        else
+          route route_text
+          say "Mounted Beskar engine at /beskar", :green
+        end
+      end
+
+      def copy_migrations
+        # Copy migrations from the engine to the host app
+        migration_source = File.expand_path("../../../../../db/migrate", __dir__)
+
+        if Dir.exist?(migration_source)
+          Dir.glob("#{migration_source}/*.rb").each do |migration|
+            migration_name = File.basename(migration).sub(/^\d+_/, '')
+
+            # Check if migration already exists
+            if migration_already_exists?(migration_name)
+              say "Migration #{migration_name} already exists, skipping...", :yellow
+            else
+              migration_template migration, "db/migrate/#{migration_name}"
+            end
+          end
+        end
+
+        say "Migrations copied. Run 'rails db:migrate' to create the tables.", :green
+      end
+
+      # CSS Zero is no longer required - styles are embedded in the dashboard
+      # def install_css_zero
+      #   # Removed - dashboard now uses embedded styles
+      # end
+
+      def show_readme
+        readme_content = <<~README
+
+          ===============================================================================
+          🛡️  Beskar Installation Complete!
+          ===============================================================================
+
+          Next steps:
+
+          1. Run migrations to create the security tables:
+             $ rails db:migrate
+
+          2. Configure authentication for the dashboard in config/initializers/beskar.rb
+
+             For Devise users:
+             config.authenticate_admin = proc do
+               authenticate_admin!
+             end
+
+             For custom authentication:
+             config.authenticate_admin = proc do
+               redirect_to main_app.root_path unless current_user&.admin?
+             end
+
+          3. Add Beskar concerns to your User model (or authentication model):
+
+             class User < ApplicationRecord
+               include Beskar::Models::SecurityTrackable
+
+               # For Devise users, also add:
+               include Beskar::Models::SecurityTrackableDevise
+             end
+
+          4. Access the security dashboard at:
+             http://localhost:3000/beskar
+
+          5. Optional: Configure additional settings in config/initializers/beskar.rb
+             - IP whitelist
+             - WAF rules
+             - Rate limiting
+             - Geolocation
+             - Risk-based locking
+
+          ===============================================================================
+          📚 Documentation
+          ===============================================================================
+
+          Dashboard Guide: https://github.com/humadroid-io/beskar/blob/main/DASHBOARD.md
+          Configuration: https://github.com/humadroid-io/beskar/blob/main/README.md
+
+          ===============================================================================
+          ⚠️  Important for Production
+          ===============================================================================
+
+          1. ALWAYS configure authentication for the dashboard
+          2. Set monitor_only = false when ready to block threats
+          3. Configure your IP whitelist to prevent locking yourself out
+          4. Set up database indexes for large-scale deployments:
+
+             $ rails generate beskar:indexes
+             $ rails db:migrate
+
+          ===============================================================================
+          💡 Quick Tips
+          ===============================================================================
+
+          - Start with monitor_only = true to observe without blocking
+          - Use the dashboard to review security events before enabling blocking
+          - Configure email notifications for high-risk events
+          - Export security data regularly for analysis
+          - Consider implementing custom risk scoring for your use case
+
+          ===============================================================================
+
+        README
+
+        say readme_content, :green
+      end
+
+      private
+
+      def migration_already_exists?(migration_name)
+        Dir.glob("db/migrate/*_#{migration_name}").any?
+      end
+
+      def migration_template(source, destination)
+        migration_number = self.class.next_migration_number(nil)
+        file_name = "#{migration_number}_#{destination}"
+
+        copy_file source, file_name
+      end
+    end
+  end
+end

data/lib/generators/beskar/install/templates/initializer.rb.tt

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+Beskar.configure do |config|
+  # ============================================================================
+  # DASHBOARD AUTHENTICATION (REQUIRED)
+  # ============================================================================
+  # Configure how to authenticate access to the Beskar security dashboard.
+  # This is REQUIRED for all environments.
+  #
+  # The authenticate_admin callback receives the request object and is executed
+  # in the controller context, giving you access to all controller methods
+  # (cookies, session, authenticate_or_request_with_http_basic, etc.).
+  # The block should return truthy value to allow access, falsey to deny.
+
+  # Option 1: Using Devise with admin role (recommended for production)
+  # config.authenticate_admin = ->(request) do
+  #   user = request.env['warden']&.authenticate(scope: :user)
+  #   user&.admin?
+  # end
+
+  # Option 2: HTTP Basic Authentication (uses controller method)
+  # config.authenticate_admin = ->(request) do
+  #   authenticate_or_request_with_http_basic("Beskar Admin") do |username, password|
+  #     username == ENV['BESKAR_ADMIN_USERNAME'] &&
+  #     password == ENV['BESKAR_ADMIN_PASSWORD']
+  #   end
+  # end
+
+  # Option 3: Token-based authentication
+  # config.authenticate_admin = ->(request) do
+  #   request.headers['Authorization'] == "Bearer #{ENV['BESKAR_ADMIN_TOKEN']}"
+  # end
+
+  # Option 4: Cookie-based authentication (uses controller cookies)
+  # config.authenticate_admin = ->(request) do
+  #   cookies.signed[:admin_token] == ENV['BESKAR_ADMIN_TOKEN']
+  # end
+
+  # Option 5: Using CanCanCan (uses controller method)
+  # config.authenticate_admin = ->(request) do
+  #   authorize! :manage, :beskar_dashboard
+  # end
+
+  # Option 6: Using Pundit (uses controller method)
+  # config.authenticate_admin = ->(request) do
+  #   authorize :beskar_dashboard, :access?
+  # end
+
+  # Option 7: For development/testing ONLY (NOT for production!)
+  # config.authenticate_admin = ->(request) do
+  #   Rails.env.development? || Rails.env.test?
+  # end
+
+  # ============================================================================
+  # MONITOR-ONLY MODE
+  # ============================================================================
+  # When enabled, Beskar will log all security events but won't actually block
+  # any requests. Useful for testing or initial deployment.
+  config.monitor_only = <%= Rails.env.development? ? 'true' : 'false' %>
+
+  # ============================================================================
+  # IP WHITELIST
+  # ============================================================================
+  # IPs that should never be blocked (your office, monitoring services, etc.)
+  config.ip_whitelist = [
+    # '192.168.1.0/24',  # Local network
+    # '10.0.0.0/8',      # Private network
+    # '127.0.0.1',       # Localhost
+  ]
+
+  # ============================================================================
+  # WAF (WEB APPLICATION FIREWALL) - Score-Based Blocking
+  # ============================================================================
+  # Enable WAF to protect against common attacks and vulnerability scans.
+  # Uses score-based blocking with exponential decay for intelligent threat detection.
+  config.waf[:enabled] = true
+
+  # Optionally customize WAF settings (these are the defaults):
+  # config.waf[:auto_block] = true                 # Automatically block IPs after threshold
+  # config.waf[:score_threshold] = 150             # Cumulative risk score before blocking
+  # config.waf[:violation_window] = 6.hours        # Maximum time window to track violations
+  # config.waf[:block_durations] = [1.hour, 6.hours, 24.hours, 7.days] # Escalating durations
+  # config.waf[:permanent_block_after] = 500       # Permanent block when cumulative score reaches this
+  # config.waf[:create_security_events] = true     # Create SecurityEvent records
+  #
+  # === Exponential Decay Configuration ===
+  # Violations decay over time based on severity (reduces false positives)
+  # config.waf[:decay_enabled] = true
+  # config.waf[:decay_rates] = {                   # Half-life in minutes
+  #   critical: 360,  # 6 hour half-life (config files, path traversal)
+  #   high: 120,      # 2 hour half-life (WordPress, PHP admin scans)
+  #   medium: 45,     # 45 minute half-life (unknown formats)
+  #   low: 15         # 15 minute half-life (RecordNotFound/404s)
+  # }
+  # config.waf[:max_violations_tracked] = 50       # Maximum violations to track per IP
+  #
+  # === RecordNotFound Exclusions ===
+  # Exclude legitimate 404-prone paths from triggering violations
+  # config.waf[:record_not_found_exclusions] = [
+  #   %r{/posts/.*},              # Blog posts with slugs
+  #   %r{/products/[\w-]+},       # Product URLs with slugs
+  #   %r{/public/.*}              # Public content
+  # ]
+  #
+  # === Pre-configured Profiles ===
+  # See WAF_CONFIGURATION_PROFILES.md for complete profile examples:
+  # - STRICT: score_threshold = 100 (high-security)
+  # - BALANCED: score_threshold = 150 (recommended default)
+  # - PERMISSIVE: score_threshold = 200 (high-traffic sites)
+
+  # ============================================================================
+  # SECURITY TRACKING
+  # ============================================================================
+  # Security tracking is enabled by default. To disable or customize:
+  # config.security_tracking[:enabled] = false
+  # config.security_tracking[:track_successful_logins] = true
+  # config.security_tracking[:track_failed_logins] = true
+  # config.security_tracking[:auto_analyze_patterns] = true
+
+  # ============================================================================
+  # RATE LIMITING
+  # ============================================================================
+  # Rate limiting is configured by default. To customize:
+  # config.rate_limiting[:ip_attempts][:limit] = 10
+  # config.rate_limiting[:ip_attempts][:period] = 1.hour
+  # config.rate_limiting[:ip_attempts][:exponential_backoff] = true
+  #
+  # config.rate_limiting[:account_attempts][:limit] = 5
+  # config.rate_limiting[:account_attempts][:period] = 15.minutes
+  # config.rate_limiting[:account_attempts][:exponential_backoff] = true
+  #
+  # config.rate_limiting[:global_attempts][:limit] = 100
+  # config.rate_limiting[:global_attempts][:period] = 1.minute
+  # config.rate_limiting[:global_attempts][:exponential_backoff] = false
+
+  # ============================================================================
+  # RISK-BASED ACCOUNT LOCKING
+  # ============================================================================
+  # Risk-based locking is disabled by default. To enable:
+  # config.risk_based_locking[:enabled] = true
+  # config.risk_based_locking[:immediate_signout] = false  # Sign out users immediately when locked
+  # config.risk_based_locking[:risk_threshold] = 75        # Risk score threshold for locking
+  # config.risk_based_locking[:auto_unlock_time] = 1.hour  # How long to lock the account
+  # config.risk_based_locking[:notify_user] = true         # Notify user on lock
+  # config.risk_based_locking[:log_lock_events] = true     # Log lock events
+
+  # ============================================================================
+  # GEOLOCATION
+  # ============================================================================
+  # Geolocation uses a mock provider by default. To use MaxMind:
+  # 1. Download GeoLite2-City database from maxmind.com
+  # 2. Place it in config/GeoLite2-City.mmdb
+  # 3. Configure:
+  # config.geolocation[:provider] = :maxmind
+  # config.geolocation[:maxmind_city_db_path] = Rails.root.join('config', 'GeoLite2-City.mmdb').to_s
+  # config.geolocation[:cache_ttl] = 4.hours
+
+  # ============================================================================
+  # AUTHENTICATION MODELS
+  # ============================================================================
+  # Authentication models are auto-detected by default. To customize:
+  # config.authentication_models[:auto_detect] = false  # Disable auto-detection
+  # config.authentication_models[:devise] = [:user, :admin]
+  # config.authentication_models[:rails_auth] = [:customer]
+
+  # ============================================================================
+  # EMERGENCY PASSWORD RESET
+  # ============================================================================
+  # Emergency password reset is disabled by default. To enable:
+  # config.emergency_password_reset[:enabled] = true
+  # config.emergency_password_reset[:impossible_travel_threshold] = 3
+  # config.emergency_password_reset[:suspicious_device_threshold] = 5
+  # config.emergency_password_reset[:total_locks_threshold] = 5
+  # config.emergency_password_reset[:send_notification] = true
+  # config.emergency_password_reset[:notify_security_team] = true
+  # config.emergency_password_reset[:require_manual_unlock] = false
+end

data/lib/tasks/beskar_tasks.rake

@@ -1,4 +1,121 @@
-# desc "Explaining what the task does"
-# task :beskar do
-#   # Task goes here
-# end
+# frozen_string_literal: true
+
+namespace :beskar do
+  desc "Install Beskar: copy migrations and create initializer"
+  task install: :environment do
+    puts "=" * 80
+    puts "Installing Beskar Security..."
+    puts "=" * 80
+    puts
+
+    # Copy migrations
+    puts "📦 Copying migrations..."
+    begin
+      Rake::Task["beskar:install:migrations"].invoke
+    rescue RuntimeError
+      # In development/test within the gem, this task might not exist
+      # In a real app using the gem, it will work fine
+      puts "   (Skipping migration copy in gem development mode)"
+    end
+    puts "✓ Migrations ready"
+    puts
+
+    # Create initializer
+    initializer_path = Rails.root.join("config/initializers/beskar.rb")
+    
+    if File.exist?(initializer_path)
+      puts "⚠️  Initializer already exists at config/initializers/beskar.rb"
+      print "   Overwrite? (y/N): "
+      response = $stdin.gets.chomp.downcase
+      
+      unless response == 'y' || response == 'yes'
+        puts "   Skipping initializer creation"
+        puts
+        next_steps
+        exit
+      end
+    end
+
+    puts "📝 Creating initializer..."
+    template_path = File.expand_path("../generators/beskar/install/templates/initializer.rb.tt", __dir__)
+
+    # Read the template and process ERB (Rails will be available in the rake task context)
+    template_content = File.read(template_path)
+    erb = ERB.new(template_content, trim_mode: '-')
+
+    # Evaluate the ERB template in a context where Rails is available
+    processed_content = erb.result(binding)
+
+    # Write the processed initializer
+    File.write(initializer_path, processed_content)
+    puts "✓ Created config/initializers/beskar.rb"
+    puts
+
+    next_steps
+  end
+
+  def next_steps
+    puts "=" * 80
+    puts "Beskar Security has been installed!"
+    puts "=" * 80
+    puts
+    puts "Next steps:"
+    puts
+    puts "1. Run migrations to create the security tables:"
+    puts
+    puts "   bin/rails db:migrate"
+    puts
+    puts "2. Add the SecurityTrackable concern to your User model:"
+    puts
+    puts "   # app/models/user.rb"
+    puts "   class User < ApplicationRecord"
+    puts "     include Beskar::SecurityTrackable"
+    puts "     "
+    puts "     devise :database_authenticatable, :registerable,"
+    puts "            :recoverable, :rememberable, :validatable"
+    puts "     # ... rest of your Devise modules"
+    puts "   end"
+    puts
+    puts "3. Review the configuration file:"
+    puts
+    puts "   config/initializers/beskar.rb"
+    puts
+    puts "   By default, WAF is enabled in MONITOR-ONLY MODE. This means:"
+    puts "   - Vulnerability scans are detected and logged"
+    puts "   - No requests are blocked yet"
+    puts "   - Security events are created for analysis"
+    puts
+    puts "4. Monitor WAF activity (recommended for 24-48 hours):"
+    puts
+    puts "   # View all WAF logs"
+    puts "   tail -f log/production.log | grep \"Beskar::WAF\""
+    puts "   "
+    puts "   # Check what would be blocked"
+    puts "   rails console"
+    puts "   > Beskar::SecurityEvent.where(event_type: 'waf_violation')"
+    puts "       .where(\"metadata->>'would_be_blocked' = ?\", 'true').count"
+    puts
+    puts "5. When ready to enable blocking:"
+    puts
+    puts "   # config/initializers/beskar.rb"
+    puts "   config.waf = {"
+    puts "     enabled: true,"
+    puts "     monitor_only: false,  # <-- Change this to false"
+    puts "     # ... rest of config"
+    puts "   }"
+    puts
+    puts "6. Optional: Add IP whitelist for trusted sources:"
+    puts
+    puts "   # config/initializers/beskar.rb"
+    puts "   config.ip_whitelist = ["
+    puts "     \"YOUR_OFFICE_IP\","
+    puts "     \"YOUR_MONITORING_SERVICE_IP\""
+    puts "   ]"
+    puts
+    puts "=" * 80
+    puts "Documentation:"
+    puts "  - README: https://github.com/humadroid-io/beskar"
+    puts "  - WAF Monitor Mode: See MONITOR_ONLY_MODE.md"
+    puts "=" * 80
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: beskar
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Maciej Litwiniuk
@@ -23,6 +23,104 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 8.0.0
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: maxminddb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: devise
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |-
   Rails Security Shield is a comprehensive, Rails-native security engine designed to provide multi-layered protection for modern web applications. It actively defends against common threats by integrating a powerful Web Application Firewall (WAF) to block attacks like SQLi and XSS, an advanced bot detection system using JavaScript challenges and honeypots, and robust account takeover prevention to stop brute-force and credential stuffing attacks.
 
@@ -33,27 +131,62 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - MIT-LICENSE
 - README.md
 - Rakefile
 - app/assets/stylesheets/beskar/application.css
 - app/controllers/beskar/application_controller.rb
+- app/controllers/beskar/banned_ips_controller.rb
+- app/controllers/beskar/dashboard_controller.rb
+- app/controllers/beskar/security_events_controller.rb
+- app/controllers/concerns/beskar/controllers/security_tracking.rb
 - app/helpers/beskar/application_helper.rb
 - app/jobs/beskar/application_job.rb
 - app/mailers/beskar/application_mailer.rb
 - app/models/beskar/application_record.rb
+- app/models/beskar/banned_ip.rb
+- app/models/beskar/security_event.rb
+- app/services/beskar/banned_ip_manager.rb
+- app/views/beskar/banned_ips/edit.html.erb
+- app/views/beskar/banned_ips/index.html.erb
+- app/views/beskar/banned_ips/new.html.erb
+- app/views/beskar/banned_ips/show.html.erb
+- app/views/beskar/dashboard/index.html.erb
+- app/views/beskar/security_events/index.html.erb
+- app/views/beskar/security_events/show.html.erb
 - app/views/layouts/beskar/application.html.erb
+- config/locales/en.yml
 - config/routes.rb
+- db/migrate/20251016000001_create_beskar_security_events.rb
+- db/migrate/20251016000002_create_beskar_banned_ips.rb
 - lib/beskar.rb
+- lib/beskar/configuration.rb
 - lib/beskar/engine.rb
+- lib/beskar/logger.rb
+- lib/beskar/middleware.rb
+- lib/beskar/middleware/request_analyzer.rb
+- lib/beskar/models/security_trackable.rb
+- lib/beskar/models/security_trackable_authenticable.rb
+- lib/beskar/models/security_trackable_devise.rb
+- lib/beskar/models/security_trackable_generic.rb
+- lib/beskar/services/account_locker.rb
+- lib/beskar/services/device_detector.rb
+- lib/beskar/services/geolocation_service.rb
+- lib/beskar/services/ip_whitelist.rb
+- lib/beskar/services/rate_limiter.rb
+- lib/beskar/services/waf.rb
 - lib/beskar/version.rb
+- lib/generators/beskar/install/install_generator.rb
+- lib/generators/beskar/install/templates/initializer.rb.tt
 - lib/tasks/beskar_tasks.rake
-homepage: https://humadroid.io/
+homepage: https://humadroid.io/beskar
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://humadroid.io/
-  source_code_uri: https://github.com/prograils/beskar
+  homepage_uri: https://humadroid.io/beskar
+  source_code_uri: https://github.com/humadroid-io/beskar
+  changelog_uri: https://github.com/humadroid-io/beskar/blob/master/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -68,7 +201,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: An all-in-one security engine for Rails providing WAF, bot detection, and
   account takeover prevention.