beskar 0.0.1 → 0.0.2

data/lib/beskar/templates/beskar_initializer.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+Beskar.configure do |config|
+  # ============================================================================
+  # Web Application Firewall (WAF) - ENABLED IN MONITOR MODE BY DEFAULT
+  # ============================================================================
+  # Detects and logs vulnerability scanning attempts (WordPress, phpMyAdmin, etc.)
+  # Start in monitor-only mode to observe patterns before enabling blocking.
+  #
+  config.waf = {
+    enabled: true,                        # Master switch for WAF
+    monitor_only: true,                   # LOG ONLY - does not block (recommended to start)
+    auto_block: true,                     # Auto-block IPs after threshold (when monitor_only=false)
+    block_threshold: 3,                   # Number of violations before blocking
+    violation_window: 1.hour,             # Time window for counting violations
+    block_durations: [1.hour, 6.hours, 24.hours, 7.days], # Escalating ban durations
+    permanent_block_after: 5,             # Permanent ban after N violations (nil = never)
+    create_security_events: true          # Log violations to SecurityEvent table
+  }
+  
+  # After monitoring for 24-48 hours, review logs and disable monitor_only:
+  # config.waf[:monitor_only] = false
+  
+  # View WAF activity in logs:
+  # tail -f log/production.log | grep "Beskar::WAF"
+  
+  # Query violations that would be blocked:
+  # Beskar::SecurityEvent.where(event_type: 'waf_violation')
+  #   .where("metadata->>'would_be_blocked' = ?", 'true').count
+
+  # ============================================================================
+  # IP Whitelisting (RECOMMENDED)
+  # ============================================================================
+  # Trusted IPs bypass all blocking (bans, rate limits, WAF) while still
+  # logging activity for audit purposes.
+  #
+  # config.ip_whitelist = [
+  #   "192.168.1.100",      # Single IP address
+  #   "10.0.0.0/24",        # CIDR notation - entire subnet
+  #   "172.16.0.0/16"       # Larger CIDR range
+  #   # Add your office IPs, monitoring services, trusted partners, etc.
+  # ]
+
+  # ============================================================================
+  # Security Event Tracking (OPTIONAL)
+  # ============================================================================
+  # Track authentication events for risk analysis and threat detection.
+  # Disable if you don't need historical security event data.
+  #
+  # config.security_tracking = {
+  #   enabled: true,                    # Master switch for all tracking
+  #   track_successful_logins: true,    # Track successful authentications
+  #   track_failed_logins: true,        # Track failed authentication attempts
+  #   auto_analyze_patterns: true       # Enable automatic pattern analysis
+  # }
+
+  # ============================================================================
+  # Rate Limiting (OPTIONAL)
+  # ============================================================================
+  # Protect against brute force attacks by limiting authentication attempts.
+  #
+  # config.rate_limiting = {
+  #   ip_attempts: {
+  #     limit: 10,                    # Max attempts per IP
+  #     period: 1.hour,               # Time window
+  #     exponential_backoff: true     # Increase delay after each attempt
+  #   },
+  #   account_attempts: {
+  #     limit: 5,                     # Max attempts per account
+  #     period: 15.minutes,
+  #     exponential_backoff: true
+  #   },
+  #   global_attempts: {
+  #     limit: 100,                   # System-wide limit (DDoS protection)
+  #     period: 1.minute,
+  #     exponential_backoff: false
+  #   }
+  # }
+
+  # ============================================================================
+  # Risk-Based Account Locking (OPTIONAL)
+  # ============================================================================
+  # Automatically lock accounts when authentication risk score is too high.
+  # Requires Devise :lockable module.
+  #
+  # config.risk_based_locking = {
+  #   enabled: false,                 # Disabled by default
+  #   risk_threshold: 75,             # Lock if risk score >= this (0-100)
+  #   lock_strategy: :devise_lockable, # Strategy: :devise_lockable, :custom, :none
+  #   auto_unlock_time: 1.hour,       # Time until automatic unlock
+  #   notify_user: true,              # Send notification on lock
+  #   log_lock_events: true           # Create security events for locks
+  # }
+
+  # ============================================================================
+  # IP Geolocation (OPTIONAL)
+  # ============================================================================
+  # Enhance risk assessment with geographic information.
+  # Requires MaxMind GeoLite2-City database (free with registration).
+  # Download from: https://dev.maxmind.com/geoip/geolite2-free-geolocation-data
+  #
+  # config.geolocation = {
+  #   provider: :maxmind,
+  #   maxmind_city_db_path: Rails.root.join('db', 'geoip', 'GeoLite2-City.mmdb').to_s,
+  #   cache_ttl: 4.hours
+  # }
+end

data/lib/beskar/version.rb

@@ -1,3 +1,3 @@
 module Beskar
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/beskar.rb

@@ -1,6 +1,36 @@
 require "beskar/version"
+require "beskar/configuration"
+require "beskar/middleware"
+require "beskar/middleware/request_analyzer"
+require "beskar/models/security_trackable_generic"
+require "beskar/models/security_trackable_devise"
+require "beskar/models/security_trackable_authenticable"
+require "beskar/models/security_trackable"
+require "beskar/services/rate_limiter"
+require "beskar/services/device_detector"
+require "beskar/services/geolocation_service"
+require "beskar/services/account_locker"
+require "beskar/services/ip_whitelist"
+require "beskar/services/waf"
 require "beskar/engine"
 
 module Beskar
-  # Your code goes here...
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  # Convenience method to access the rate limiter
+  def self.rate_limiter
+    Services::RateLimiter
+  end
+
+  # Check if a request should be rate limited
+  def self.rate_limited?(request, user = nil)
+    Services::RateLimiter.is_rate_limited?(request, user)
+  end
 end

data/lib/tasks/beskar_tasks.rake

@@ -1,4 +1,112 @@
-# 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("../beskar/templates/beskar_initializer.rb", __dir__)
+    FileUtils.cp(template_path, initializer_path)
+    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.0.2
 platform: ruby
 authors:
 - Maciej Litwiniuk
@@ -23,6 +23,90 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 8.0.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: 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'
+- !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'
 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.
 
@@ -38,22 +122,42 @@ files:
 - Rakefile
 - app/assets/stylesheets/beskar/application.css
 - app/controllers/beskar/application_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/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/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/templates/beskar_initializer.rb
 - lib/beskar/version.rb
 - 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
 rdoc_options: []
 require_paths:
 - lib