beskar 0.0.2 → 0.1.0

data/README.md

@@ -2,6 +2,29 @@
 
 **Beskar** is a comprehensive, Rails-native security engine designed to provide multi-layered, proactive protection for modern web applications. It defends against common threats, bot activity, and account takeovers without requiring external dependencies, integrating seamlessly into your application as a natural extension of the framework.
 
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+  - [Quick Start](#quick-start)
+  - [Dashboard Authentication (REQUIRED)](#dashboard-authentication-required)
+  - [Add to Your User Model](#add-to-your-user-model)
+- [Configuration](#configuration)
+- [Usage](#usage)
+  - [Risk-Based Account Locking](#risk-based-account-locking-with-devise-lockable)
+  - [Rate Limiting](#rate-limiting)
+  - [IP Whitelisting](#ip-whitelisting)
+  - [Web Application Firewall (WAF)](#web-application-firewall-waf)
+  - [IP Blocking and Banning](#ip-blocking-and-banning)
+  - [Security Events](#security-events)
+  - [Middleware Integration](#middleware-integration)
+- [WAF Pattern Reference](#waf-pattern-reference)
+- [Security Best Practices](#security-best-practices)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Features
 
 -   **Devise Integration:** Seamless integration with Devise authentication for automatic login tracking and security analysis.
@@ -10,14 +33,14 @@
 -   **Brute Force Detection:** Advanced pattern recognition to detect single account attacks vs credential stuffing attempts, with automatic IP banning.
 -   **IP Whitelisting:** Allow trusted IPs (office networks, partners, security scanners) to bypass blocking while maintaining full audit logs. Supports individual IPs and CIDR notation.
 -   **Persistent IP Blocking:** Hybrid cache + database blocking system that survives application restarts. Auto-bans IPs after authentication abuse or excessive rate limiting violations.
--   **Web Application Firewall (WAF):** Real-time detection and blocking of vulnerability scanning attempts across 7 attack categories (WordPress, PHP admin panels, config files, path traversal, framework debug, CMS detection, common exploits). Includes escalating ban durations and monitor-only mode.
+-   **Web Application Firewall (WAF):** Real-time detection and blocking of vulnerability scanning attempts across 12 attack categories including Rails exception analysis (WordPress scans, WordPress static files, PHP admin panels, config files, path traversal, framework debug, CMS detection, common exploits, UnknownFormat, IP spoofing, InvalidType, RecordNotFound enumeration). Includes escalating ban durations, monitor-only mode, and configurable exclusion patterns.
 -   **Security Event Tracking:** Comprehensive logging of authentication events with risk scoring and metadata extraction.
 -   **IP Geolocation:** MaxMind GeoLite2-City database integration for country/city location, coordinates, timezone, and enhanced risk scoring (configurable, database not included due to licensing).
 -   **Geographic Anomaly Detection:** Haversine-based impossible travel detection and location-based risk assessment.
 -   **Advanced Bot Detection:** Multi-layered defense using JavaScript challenges and invisible honeypots to filter out malicious bots while allowing legitimate ones.
 -   **Modular Architecture:** Devise-specific code is isolated in separate services for maintainability and extensibility.
 -   **Rails-Native Architecture:** Built as a mountable `Rails::Engine`, it leverages `ActiveJob` and `Rails.cache` for high performance and low overhead.
--   **Real-Time Dashboard (Coming Soon):** A mountable dashboard to visualize security events and monitor threats as they happen.
+-   **Security Dashboard:** A mountable web interface for monitoring security events, managing IP bans, and viewing statistics. Features configurable authentication, real-time filtering, and export capabilities. See [Dashboard Authentication](#dashboard-authentication) section below.
 
 ## Installation
 
@@ -52,22 +75,98 @@ bin/rails db:migrate
 
 ### Quick Start
 
+**1. Configure Dashboard Authentication (Required)**
+
+Before using Beskar, you must configure authentication for the dashboard. See the [Dashboard Authentication](#dashboard-authentication) section below for details and examples.
+
+**2. Enable WAF Monitoring**
+
 By default, Beskar enables the **Web Application Firewall (WAF) in monitor-only mode**. This means:
 - ✅ Vulnerability scans are detected and logged
-- ✅ Security events are created for analysis  
+- ✅ Security events are created for analysis
 - ⚠️ No requests are blocked yet (safe to enable in production)
 
 After monitoring for 24-48 hours, review the logs and disable monitor-only mode to enable active blocking:
 
 ```ruby
 # config/initializers/beskar.rb
-config.waf = {
-  enabled: true,
-  monitor_only: false,  # Change this to enable blocking
+Beskar.configure do |config|
+  config.monitor_only = true # Change this to false to enable blocking
+  config.waf[:enabled] = true
   # ... rest of configuration
-}
+end
+```
+
+### Dashboard Authentication (REQUIRED)
+
+**⚠️ IMPORTANT: Dashboard authentication must be configured for all environments.**
+
+The Beskar dashboard requires authentication to prevent unauthorized access. You must configure how users authenticate to access the dashboard by setting up the `authenticate_admin` callback:
+
+```ruby
+# config/initializers/beskar.rb
+Beskar.configure do |config|
+  # REQUIRED: Configure dashboard authentication
+  # The block is executed in the controller context and receives the request object.
+  # You have access to all controller methods (cookies, session, etc.) and helpers.
+  config.authenticate_admin = ->(request) do
+    # Return truthy to allow access, falsey to deny
+
+    # Example 1: Devise with admin role (recommended for production)
+    user = request.env['warden']&.authenticate(scope: :user)
+    user&.admin?
+  end
+end
 ```
 
+**Why this is required:** Previous versions allowed unauthenticated access in development/test environments, which could lead to production security issues. Now, authentication must be explicitly configured for all environments to prevent accidental exposure.
+
+**Other Authentication Strategies:**
+
+```ruby
+# Token-based authentication
+config.authenticate_admin = ->(request) do
+  request.headers['Authorization'] == "Bearer #{ENV['BESKAR_ADMIN_TOKEN']}"
+end
+
+# HTTP Basic Auth (uses controller method)
+config.authenticate_admin = ->(request) do
+  authenticate_or_request_with_http_basic do |username, password|
+    username == ENV['BESKAR_USERNAME'] && password == ENV['BESKAR_PASSWORD']
+  end
+end
+
+# Cookie-based authentication (uses controller cookies)
+config.authenticate_admin = ->(request) do
+  cookies.signed[:admin_token] == ENV['BESKAR_ADMIN_TOKEN']
+end
+
+# Development/Testing bypass (use with caution!)
+config.authenticate_admin = ->(request) do
+  Rails.env.development? || Rails.env.test?
+end
+```
+
+**Accessing the Dashboard:**
+
+After configuring authentication, mount the engine in your routes:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount Beskar::Engine => "/beskar"
+end
+```
+
+Then visit `http://localhost:3000/beskar` to access the dashboard.
+
+**Dashboard Features:**
+- 📊 Security event monitoring with filtering and search
+- 🚫 IP ban management (view, extend, unban)
+- 📈 Statistics and risk distribution analysis
+- 📥 Export capabilities (CSV/JSON)
+- 🔒 CSRF protection and secure by default
+
 ### Add to Your User Model
 
 Include the `SecurityTrackable` concern in your Devise user model:
@@ -75,8 +174,8 @@ Include the `SecurityTrackable` concern in your Devise user model:
 ```ruby
 # app/models/user.rb
 class User < ApplicationRecord
-  include Beskar::SecurityTrackable
-  
+  include Beskar::Models::SecurityTrackable
+
   devise :database_authenticatable, :registerable,
          :recoverable, :rememberable, :validatable
   # ... other Devise modules
@@ -85,11 +184,20 @@ end
 
 ## Configuration
 
-You can configure Beskar in the initializer file created by the installer:
+You can configure Beskar in the initializer file created by the installer.
+
+> **Note:** Dashboard authentication setup is covered in the [Dashboard Authentication](#dashboard-authentication-required) section above.
 
 ```ruby
 # config/initializers/beskar.rb
 Beskar.configure do |config|
+  # === Dashboard Authentication (REQUIRED) ===
+  # See "Dashboard Authentication" section above for examples and details
+  config.authenticate_admin = ->(request) do
+    user = request.env['warden']&.authenticate(scope: :user)
+    user&.admin?
+  end
+
   # === Security Tracking ===
   # Controls what security events are tracked and analyzed
   config.security_tracking = {
@@ -119,27 +227,28 @@ Beskar.configure do |config|
   }
 
   # === IP Whitelisting ===
-  # Allow trusted IPs to bypass all blocking (bans, rate limits, WAF)
-  # while still logging all 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
-    "2001:db8::/32"       # IPv6 support
-  ]
+  # See "IP Whitelisting" section below for detailed examples
+  config.ip_whitelist = []  # Add trusted IPs here (supports CIDR notation)
 
   # === Web Application Firewall (WAF) ===
-  # Real-time detection and blocking of vulnerability scanning attempts
-  config.waf = {
-    enabled: true,                        # Master switch for WAF
-    auto_block: true,                     # Automatically ban IPs after threshold
-    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
-    create_security_events: true,         # Log WAF violations to SecurityEvent table
-    monitor_only: false                   # If true, log violations but never block
-  }
+  # See "Web Application Firewall" section below for production examples
+  # Defaults shown here - use [:key] syntax to preserve other defaults
+  config.waf[:enabled] = true                        # Master switch for WAF
+  # config.waf[:auto_block] = true                   # Default: true
+  # config.waf[:score_threshold] = 150               # Default: 150 (cumulative risk score before blocking)
+  # config.waf[:violation_window] = 6.hours          # Default: 6 hours (max time to track violations)
+  # config.waf[:block_durations] = [1.hour, 6.hours, 24.hours, 7.days] # Escalating bans
+  # config.waf[:permanent_block_after] = 500         # Permanent after cumulative score reaches 500
+  # config.waf[:create_security_events] = true       # Log to SecurityEvent table
+  # config.waf[:record_not_found_exclusions] = []    # Regex patterns for false positives
+  # config.waf[:decay_enabled] = true                # Enable exponential decay of violation scores
+  # config.waf[:decay_rates] = {                     # Decay rates by severity (half-life in minutes)
+  #   critical: 360,  # 6 hour half-life
+  #   high: 120,      # 2 hour half-life
+  #   medium: 45,     # 45 minute half-life
+  #   low: 15         # 15 minute half-life
+  # }
+  # config.waf[:max_violations_tracked] = 50         # Maximum violations to track per IP
 
   # === Risk-Based Account Locking ===
   # Automatically lock accounts when authentication risk score exceeds threshold
@@ -163,32 +272,11 @@ Beskar.configure do |config|
   }
 end
 
-# Security Tracking Configuration Details
-The security tracking system respects all configuration settings:
-
-- **`enabled: false`** - Completely disables all security event tracking
-- **`track_successful_logins: false`** - Stops tracking successful login events
-- **`track_failed_logins: false`** - Stops tracking failed login attempts  
-- **`auto_analyze_patterns: false`** - Disables automatic threat pattern analysis
-
-When tracking is disabled via configuration, no `SecurityEvent` records are created and no background analysis jobs are queued.
 ```
 
 ## Usage
 
-### Basic Setup
-
-Once installed and configured, Beskar works automatically with Devise. Add the `SecurityTrackable` module to your User model:
-
-```ruby
-class User < ApplicationRecord
-  devise :database_authenticatable, :registerable,
-         :recoverable, :rememberable, :validatable
-  
-  # Add Beskar security tracking
-  include Beskar::Models::SecurityTrackable
-end
-```
+> **Note:** If you haven't already, see the [Add to Your User Model](#add-to-your-user-model) section in Quick Start for setting up `SecurityTrackable`.
 
 ### Risk-Based Account Locking (with Devise Lockable)
 
@@ -203,7 +291,7 @@ class User < ApplicationRecord
   devise :database_authenticatable, :registerable,
          :recoverable, :rememberable, :validatable,
          :lockable  # Add this for risk-based locking
-  
+
   include Beskar::Models::SecurityTrackable
 end
 ```
@@ -351,7 +439,7 @@ attack_type = rate_limiter.attack_pattern_type
 case attack_type
 when :brute_force_single_account
   # Single IP attacking one account
-when :distributed_single_account  
+when :distributed_single_account
   # Multiple IPs attacking one account
 when :single_ip_multiple_accounts
   # One IP attacking multiple accounts (credential stuffing)
@@ -394,56 +482,156 @@ Beskar::Services::IpWhitelist.clear_cache!
 
 ### Web Application Firewall (WAF)
 
-Beskar's WAF detects and blocks vulnerability scanning attempts across 7 attack categories:
+Beskar's WAF uses a **score-based blocking system with exponential decay** to intelligently detect and block vulnerability scanning attempts across 12 attack categories:
 
 **Attack Categories Detected:**
-1. **WordPress Scans** (High Severity) - `/wp-admin`, `/wp-login.php`, `/xmlrpc.php`
-2. **PHP Admin Panels** (High Severity) - `/phpmyadmin`, `/admin.php`, `/phpinfo.php`
-3. **Config Files** (Critical Severity) - `/.env`, `/.git`, `/database.yml`
-4. **Path Traversal** (Critical Severity) - `/../../../etc/passwd`, URL encoded variants
-5. **Framework Debug** (Medium Severity) - `/rails/info/routes`, `/__debug__`, `/telescope`
-6. **CMS Detection** (Medium Severity) - `/joomla`, `/drupal`, `/magento`
-7. **Common Exploits** (Critical Severity) - `/shell.php`, `/c99.php`, `/webshell`
+1. **WordPress Scans** (High: 80 points) - `/wp-admin`, `/wp-login.php`, `/wp-content/*.php`, `/xmlrpc.php`
+2. **WordPress Static Files** (Low: 30 points) - `/wp-content/*.css`, `/wp-content/*.js`, `/wp-content/*.jpg` (broken links, not attacks)
+3. **PHP Admin Panels** (High: 80 points) - `/phpmyadmin`, `/admin.php`, `/phpinfo.php`
+4. **Config Files** (Critical: 95 points) - `/.env`, `/.git`, `/database.yml`
+5. **Path Traversal** (Critical: 95 points) - `/../../../etc/passwd`, URL encoded variants
+6. **Framework Debug** (Medium: 60 points) - `/rails/info/routes`, `/__debug__`, `/telescope`
+7. **CMS Detection** (Medium: 60 points) - `/joomla`, `/drupal`, `/magento`
+8. **Common Exploits** (Critical: 95 points) - `/shell.php`, `/c99.php`, `/webshell`
+9. **ActionController::UnknownFormat** (Medium: 60 points) - Detects requests for unusual formats like `/users/1.exe`, `/api/data.bat` that trigger Rails format exceptions, indicating potential scanning
+10. **ActionDispatch::RemoteIp::IpSpoofAttackError** (Critical: 95 points) - Detects IP spoofing attempts when conflicting IP headers are present
+11. **ActionDispatch::Http::MimeNegotiation::InvalidType** (Medium: 60 points) - Detects invalid MIME type requests like `GET "../../../../../../../../etc/passwd{{"` that indicate scanner activity
+12. **ActiveRecord::RecordNotFound** (Low: 30 points) - Detects potential record enumeration scans like `/admin/users/999999`, with configurable exclusions to prevent false positives
+
+**How Score-Based Blocking Works:**
+
+Instead of counting violations (1, 2, 3...), Beskar tracks a **cumulative risk score** that decays over time:
+
+- Each violation adds points based on severity (Critical=95, High=80, Medium=60, Low=30)
+- Violations **decay exponentially** based on severity (critical threats persist longer)
+- IP is blocked when cumulative score reaches threshold (default: 150 points)
+- Lower-severity violations decay faster, reducing false positives from legitimate 404s
+
+**Example Scenarios:**
+```ruby
+# Scenario 1: Legitimate user hitting 404s
+10 × RecordNotFound (30 points each) = 300 cumulative
+BUT: Low severity decays with 15-minute half-life
+→ Score drops quickly, no ban triggered
+
+# Scenario 2: Attacker scanning config files
+2 × /.env access (95 points each) = 190 points
+→ Exceeds threshold (150) → Immediate ban
+→ Critical severity persists for 6 hours
+
+# Scenario 3: Mixed attack pattern
+1 × WordPress scan (80) + 1 × Config access (95) = 175
+→ Exceeds threshold → Ban triggered
+→ Different decay rates for each violation type
+```
 
-**Configuration Examples:**
+**Configuration Profiles:**
 
 ```ruby
-# Production - Aggressive protection
+# 🔥 STRICT - High-security environment (financial, healthcare)
 Beskar.configure do |config|
-  config.waf = {
-    enabled: true,
-    auto_block: true,
-    block_threshold: 2,              # Block after just 2 violations
-    violation_window: 30.minutes,
-    block_durations: [6.hours, 24.hours, 7.days, 30.days],
-    permanent_block_after: 4,
-    create_security_events: true
+  config.waf[:enabled] = true
+  config.waf[:auto_block] = true
+  config.waf[:score_threshold] = 100           # Lower threshold = faster blocking
+  config.waf[:violation_window] = 12.hours     # Longer memory
+  config.waf[:permanent_block_after] = 300     # Permanent ban at 300 cumulative score
+  config.waf[:block_durations] = [6.hours, 24.hours, 7.days, 30.days]
+
+  # Slower decay = violations persist longer
+  config.waf[:decay_rates] = {
+    critical: 720,  # 12 hour half-life (very persistent)
+    high: 360,      # 6 hour half-life
+    medium: 120,    # 2 hour half-life
+    low: 30         # 30 minute half-life
   }
+
+  # Exclude legitimate 404-prone paths
+  config.waf[:record_not_found_exclusions] = [
+    %r{/posts/.*}, %r{/articles/\d+}, %r{/public/.*}
+  ]
+end
+
+# ⚖️ BALANCED - Default production (recommended for most apps)
+Beskar.configure do |config|
+  config.waf[:enabled] = true
+  config.waf[:auto_block] = true
+  config.waf[:score_threshold] = 150           # Default threshold
+  config.waf[:violation_window] = 6.hours      # Standard window
+  config.waf[:permanent_block_after] = 500     # Permanent at 500 cumulative
+  config.waf[:decay_enabled] = true
+  # Uses default decay rates (critical: 360, high: 120, medium: 45, low: 15)
+
+  config.waf[:record_not_found_exclusions] = [
+    %r{/posts/.*}, %r{/products/[\\w-]+}
+  ]
 end
 
-# Development - Monitor only
+# 🧪 PERMISSIVE - High-traffic public site with many 404s
 Beskar.configure do |config|
-  config.waf = {
-    enabled: true,
-    monitor_only: true,              # Log but never block
-    create_security_events: true
+  config.waf[:enabled] = true
+  config.waf[:auto_block] = true
+  config.waf[:score_threshold] = 200           # Higher tolerance
+  config.waf[:violation_window] = 3.hours      # Shorter memory
+  config.waf[:permanent_block_after] = 800     # Rare permanent bans
+
+  # Faster decay = violations forgotten quickly
+  config.waf[:decay_rates] = {
+    critical: 180,  # 3 hour half-life
+    high: 60,       # 1 hour half-life
+    medium: 20,     # 20 minute half-life
+    low: 5          # 5 minute half-life (very forgiving)
   }
-  
-  config.ip_whitelist = ["127.0.0.1", "::1"]  # Whitelist localhost
+
+  # Extensive exclusions for public content
+  config.waf[:record_not_found_exclusions] = [
+    %r{/posts/.*}, %r{/articles/.*}, %r{/tags/.*},
+    %r{/search/.*}, %r{/public/.*}, %r{/assets/.*}
+  ]
+end
+
+# 🔍 MONITOR ONLY - Testing/staging (recommended before going live)
+Beskar.configure do |config|
+  config.monitor_only = true                   # Log violations but NEVER block
+  config.waf[:enabled] = true
+  config.waf[:create_security_events] = true
+  config.ip_whitelist = ["127.0.0.1", "::1"]   # Whitelist localhost
 end
 ```
 
 **Blocking Behavior:**
-- **First violation**: Logged, violation count incremented
-- **Threshold reached** (default 3): IP automatically banned for 1 hour
-- **Repeat violations**: Ban duration escalates: 1h → 6h → 24h → 7d → **permanent**
-- **Permanent block**: After 5 violations (configurable), IP is permanently banned
-- **Monitor mode**: Logs all violations but never blocks (useful for tuning)
+
+With **default settings** (score_threshold: 150):
+- **Violations accumulate**: Each violation adds points based on severity
+- **Score threshold reached**: IP automatically banned when cumulative score ≥ 150
+- **Exponential decay**: Violations lose impact over time based on severity
+- **Ban duration escalates**: Based on total score accumulated:
+  - 150-300 points → 1 hour ban
+  - 300-450 points → 6 hour ban
+  - 450-600 points → 24 hour ban
+  - 600+ points → 7 day ban
+  - 500+ cumulative score → **permanent ban**
+
+**Key Advantages:**
+- **Fewer false positives**: Low-severity violations (404s) decay quickly
+- **Faster response to serious threats**: Critical violations persist longer
+- **Adaptive blocking**: Mixed attack patterns properly weighted
+- **Monitor mode compatible**: Set `config.monitor_only = true` to log without blocking
+
+> **Production Tip:** Start with monitor mode for 24-48 hours to observe your traffic patterns, then adjust thresholds and exclusions before enabling blocking.
 
 **Check WAF status:**
 ```ruby
-# Check if WAF detected threats
+# Get current risk score (with decay applied)
+current_score = Beskar::Services::Waf.get_current_score(ip_address)
+# => 145.3 (below threshold, not blocked)
+
+# Get number of violations tracked
 violation_count = Beskar::Services::Waf.get_violation_count(ip_address)
+# => 3 (number of violations being tracked)
+
+# Get detailed violation records
+violations = Beskar::Services::Waf.get_violations(ip_address)
+# => [{timestamp: ..., score: 95, severity: :critical, category: :config_files}, ...]
 
 # Reset violations (admin action)
 Beskar::Services::Waf.reset_violations(ip_address)
@@ -461,12 +649,15 @@ end
 
 Beskar uses a hybrid cache + database blocking system that persists across application restarts.
 
-**Automatic IP Banning:**
+**Automatic IP Banning Thresholds:**
+
+| Trigger | Threshold | Time Window | Ban Duration | Configurable |
+|---------|-----------|-------------|--------------|--------------|
+| **Failed Authentication** | 10 attempts | 1 hour | 1 hour (escalating) | Via rate_limiting config |
+| **Rate Limit Violations** | 5 violations | 1 hour | 1 hour (escalating) | Via rate_limiting config |
+| **WAF Violations** | 3 violations | 1 hour | 1 hour (escalating) | Via waf[:block_threshold] |
 
-IPs are automatically banned for:
-1. **Authentication abuse** - 10+ failed login attempts in 1 hour
-2. **Rate limit violations** - 5+ rate limit violations in 1 hour
-3. **WAF violations** - 3+ vulnerability scan attempts (configurable)
+> **Note:** All ban durations escalate on repeat offenses: 1h → 6h → 24h → 7d → permanent
 
 **Manual IP Management:**
 
@@ -574,10 +765,10 @@ class SecurityCleanupJob < ApplicationJob
     # Remove expired bans from database
     removed = Beskar::BannedIp.cleanup_expired!
     Rails.logger.info "Cleaned up #{removed} expired IP bans"
-    
+
     # Archive old security events (optional)
     Beskar::SecurityEvent.where('created_at < ?', 90.days.ago).delete_all
-    
+
     # Generate security report (example)
     report = {
       active_bans: Beskar::BannedIp.active.count,
@@ -587,7 +778,7 @@ class SecurityCleanupJob < ApplicationJob
         created_at: 24.hours.ago..Time.current
       ).count
     }
-    
+
     # Send to monitoring service
     Rails.logger.info "Security Report: #{report}"
   end
@@ -611,10 +802,7 @@ Every request passes through these security checks in order:
 **Features:**
 - **Early exit** - Banned IPs are blocked immediately for performance
 - **Whitelist bypass** - Trusted IPs bypass all blocking but activity is logged
-- **Auto-blocking** - Automatic IP banning after:
-  - 10+ failed authentication attempts (authentication abuse)
-  - 5+ rate limit violations in 1 hour (rate limit abuse)
-  - 3+ WAF violations (configurable, vulnerability scanning)
+- **Auto-blocking** - See [Automatic IP Banning Thresholds](#ip-blocking-and-banning) section for details
 - **Custom error pages** - Returns helpful 403/429 error responses
 - **Response headers** - Adds `X-Beskar-Blocked` and `X-Beskar-Rate-Limited` headers
 - **Graceful degradation** - Continues working if cache is unavailable
@@ -637,13 +825,18 @@ Security events are logged to the `beskar_security_events` table for analysis an
 
 | Category | Severity | Example Patterns | Risk Score |
 |----------|----------|------------------|------------|
-| WordPress Scans | High | `/wp-admin`, `/wp-login.php`, `/xmlrpc.php` | 80 |
+| WordPress Scans | High | `/wp-admin`, `/wp-login.php`, `/wp-content/*.php` | 80 |
+| WordPress Static Files | Low | `/wp-content/*.css`, `/wp-content/*.jpg` | 30 |
 | PHP Admin Panels | High | `/phpmyadmin`, `/admin.php`, `/phpinfo.php` | 80 |
 | Config Files | **Critical** | `/.env`, `/.git`, `/database.yml`, `/config.php` | **95** |
 | Path Traversal | **Critical** | `/../../../etc/passwd`, `%2e%2e/` | **95** |
 | Framework Debug | Medium | `/rails/info/routes`, `/__debug__`, `/telescope` | 60 |
 | CMS Detection | Medium | `/joomla`, `/drupal`, `/magento` | 60 |
 | Common Exploits | **Critical** | `/shell.php`, `/c99.php`, `/webshell` | **95** |
+| UnknownFormat Exception | Medium | `/users/1.exe`, `/api/data.bat` | 60 |
+| IP Spoofing Exception | **Critical** | Conflicting IP headers | **95** |
+| Invalid MIME Type Exception | Medium | `GET "../../../../etc/passwd{{"` | 60 |
+| RecordNotFound Exception | Low | `/admin/users/999999` | 30 |
 
 **Pattern matching is:**
 - Case-insensitive
@@ -658,21 +851,17 @@ Security events are logged to the `beskar_security_events` table for analysis an
 When first enabling WAF, use monitor-only mode to tune thresholds:
 
 ```ruby
-config.waf = {
-  enabled: true,
-  monitor_only: true,  # Log but don't block
-  create_security_events: true
-}
+config.monitor_only = true  # Log but don't block
+config.waf[:enabled] = true
+config.waf[:create_security_events] = true
 ```
 
 After reviewing logs for false positives, enable blocking:
 
 ```ruby
-config.waf = {
-  enabled: true,
-  monitor_only: false,
-  auto_block: true
-}
+config.monitor_only = false
+config.waf[:enabled] = true
+config.waf[:auto_block] = true
 ```
 
 ### 2. Whitelist Carefully
@@ -773,7 +962,7 @@ config.ip_whitelist = ["user.ip.address.here"]
 **Solution:** Enable monitor-only mode and review patterns:
 
 ```ruby
-config.waf[:monitor_only] = true
+config.monitor_only = true  # This is a global setting, not WAF-specific
 
 # Review what's being flagged
 Beskar::SecurityEvent.where(event_type: 'waf_violation').last(20).each do |event|
@@ -853,7 +1042,7 @@ $ bin/rails test
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at [https://github.com/prograis/beskar](https://github.com/prograils/beskar). 
+Bug reports and pull requests are welcome on GitHub at [https://github.com/prograis/beskar](https://github.com/prograils/beskar).
 
 ## License
 
@@ -862,4 +1051,3 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Just be nice to each other.
-