beskar 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c5db4a97c58f47e443a19facccd9eaf9a14894558b220a43ce52735c9ea3ed2
-  data.tar.gz: d3c74aa51d0ce7bbce34deba20368ffeb9049b799d6cf5b08ed26aabd2605c5c
+  metadata.gz: 025703c477080d31ed167a7012be2cd390d3d73b2447b61624bffd3243f1aa6b
+  data.tar.gz: a056e8c20364351e9f96734836991be7949a92b279dfba05a6b327dad0b3d823
 SHA512:
-  metadata.gz: 56fe1bdf96313ce84bd8818f6c795993eb031c38e5a5e0f29934875b45224eb250ed305c6a60ca8076ae6b4eb326228ea6625a10d4d986c4a922e6519371bda5
-  data.tar.gz: c5875b70720fc3ac65448f430a9f0a8a4c5c505f8e1c049ae5c1177da188a00127002aeed48ab1ebc737178a6297bb838f9e5a30d6273d182cc038de37c1945c
+  metadata.gz: 1a70b96954525ebdf9867fcc1656b5313e111a0fd6c4e2e31f111d3d8c9320a156f5d29ed582ee06c5d418f26c7c04601147d749c7825747b601ae1975855211
+  data.tar.gz: 6523638cd97d91b78779f5fd8cf6276e5d07c39f3ba87ec342abae007ffed99dd505adf346917ed3601be0085d81ff247c874feed92effe27b34e94d523ab7c5

data/CHANGELOG.md

@@ -0,0 +1,143 @@
+# Changelog
+
+All notable changes to Beskar will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### ⚠️ BREAKING CHANGES
+
+- **Monitor-only mode refactored to top-level configuration**
+  - `config.waf[:monitor_only]` has been **removed**
+  - Use `config.monitor_only = true/false` at the configuration root level instead
+  - The method `Beskar.configuration.waf_monitor_only?` has been **removed**
+  - Use `Beskar.configuration.monitor_only?` instead
+  - See [BREAKING_CHANGES.md](BREAKING_CHANGES.md) for detailed migration guide
+
+- **Dashboard authentication now required in all environments**
+  - Previous behavior: Dashboard allowed access in development/test without authentication
+  - New behavior: `config.authenticate_admin` must be explicitly configured for all environments
+  - **Why this change**: Prevents production security surprises by requiring explicit authentication setup
+  - **Migration**: Add `config.authenticate_admin` proc to your initializer (see examples in template)
+  - Developers who want to bypass auth in development must explicitly configure it
+
+### Added
+
+- Ban records (`Beskar::BannedIp`) are now created even in monitor-only mode
+  - Provides full visibility into what would be blocked
+  - Allows querying `Beskar::BannedIp.active` to see potential blocks
+  - Makes verification and testing much more reliable
+- Global monitor-only mode affecting all blocking features (WAF, rate limiting, IP bans)
+- **Centralized logging system** (`Beskar::Logger`)
+  - Consistent log formatting with automatic `[Beskar]` or `[Beskar::Component]` prefixes
+  - Component name aliasing for cleaner output (e.g., `Beskar::Services::Waf` → `WAF`)
+  - Configurable log levels and output backends
+  - Include module support for automatic component detection in classes
+  - Single point of configuration for all logging
+- **Security Dashboard** - Mountable web interface for monitoring and managing security
+  - Real-time security event monitoring with advanced filtering and pagination
+  - IP ban management with bulk actions, extend, and unban capabilities
+  - Statistics overview with risk distribution and threat analysis
+  - Export functionality for security events and banned IPs (CSV/JSON)
+  - Stripe-inspired minimalist design with embedded styles (no CSS dependencies)
+  - Custom pagination and filtering (no Kaminari/Pagy dependency)
+  - Configurable authentication via `config.authenticate_admin` proc
+  - Rails 7+ compatible with built-in CSRF protection
+  - Install generator for easy setup (`rails generate beskar:install`)
+  - Full documentation in [DASHBOARD.md](DASHBOARD.md)
+- **WAF Rails Exception Detection** - Enhanced security through Rails exception analysis
+  - Detects `ActionController::UnknownFormat` exceptions (e.g., `/users/1.exe`) as potential scanning attempts
+  - Detects `ActionDispatch::RemoteIp::IpSpoofAttackError` as critical IP spoofing attacks
+  - Detects `ActiveRecord::RecordNotFound` as potential record enumeration scans
+  - Configurable exclusion patterns for `RecordNotFound` to prevent false positives
+  - New configuration: `config.waf[:record_not_found_exclusions]` accepts regex patterns
+  - Different severity levels: Critical (IP spoofing), Medium (UnknownFormat), Low (RecordNotFound)
+  - Exception-based violations count toward auto-blocking thresholds
+  - Works seamlessly alongside existing WAF vulnerability patterns
+- **Enhanced Dashboard Authentication System**
+  - Helpful error messages with configuration examples when authentication not configured
+  - Clear, actionable guidance shows 4 authentication strategy examples (Devise, token-based, HTTP Basic, development bypass)
+  - Error response includes properly formatted code examples in initializer format
+  - Authentication configuration prominently documented at top of initializer template
+  - Support for any authentication strategy via flexible proc-based configuration
+
+### Changed
+
+- **Refactored ApplicationController authentication for better maintainability**
+  - Simplified authentication flow from deeply nested conditionals to flat, single-responsibility methods
+  - Reduced method complexity: main `authenticate_admin!` is now 4 lines (was 20+ lines with 3-4 nesting levels)
+  - Extracted authentication logic into focused methods:
+    - `authenticate_admin!`: Routes to appropriate strategy (configuration check + delegation)
+    - `handle_custom_authentication`: Executes configured authentication with error handling
+    - `handle_missing_authentication_configuration`: Shows helpful error with examples
+  - All authentication paths now explicitly return `true` (allow) or `false` (deny)
+  - Consistent error handling for both HTML and JSON responses
+  - Improved exception handling with detailed error logging
+  - Added comprehensive test suite: 42 tests with 122 assertions covering all authentication scenarios
+
+- Monitor-only mode is now a system-wide concept rather than WAF-specific
+- Ban records are created but not enforced when `monitor_only = true`
+- Security events include `monitor_only_mode` metadata flag
+- All blocking decisions (WAF, rate limiting, authentication abuse) respect global monitor-only setting
+- Improved logging with clear "MONITOR-ONLY" indicators
+- Better separation of ban creation from ban enforcement
+- All internal logging now uses `Beskar::Logger` instead of direct `Rails.logger` calls
+- Log messages no longer require manual prefix formatting
+
+### Fixed
+
+- Monitor-only mode now provides actual data for verification (ban records exist)
+- Consistent behavior across all security features
+- Clearer semantics for what monitor-only mode means
+
+### Security
+
+- **Dashboard authentication hardening**: Removed environment-based authentication defaults
+  - Eliminates risk of accidentally deploying without authentication configured
+  - Forces explicit security decisions during initial setup
+  - All environments (development, test, production) now require authentication configuration
+  - Provides clear, immediate feedback when authentication is missing
+  - Reduces attack surface by failing secure (deny by default)
+
+### Documentation
+
+- Updated README with new configuration structure
+- Enhanced MONITOR_ONLY_MODE.md with examples of querying ban records
+- Added migration guide in BREAKING_CHANGES.md
+- Created PROJECT_DOCUMENTATION.md for development reference
+- Updated PROJECT_DOCUMENTATION.md with comprehensive dashboard authentication section
+  - Documented authentication flow and architecture
+  - Added configuration examples and design principles
+  - Included test coverage details
+- Updated initializer template (`lib/beskar/templates/beskar_initializer.rb`) with prominent authentication documentation
+  - Dashboard Authentication section moved to top (REQUIRED)
+  - Four complete authentication strategy examples
+  - Clear warnings about development-only bypass patterns
+
+
+### Versioning Policy
+
+- **Major version (X.0.0)**: Breaking changes that require code changes
+- **Minor version (0.X.0)**: New features, backward compatible
+- **Patch version (0.0.X)**: Bug fixes and minor improvements
+
+### Upgrade Guide
+
+When upgrading between versions with breaking changes:
+
+1. Read the [BREAKING_CHANGES.md](BREAKING_CHANGES.md) file
+2. Update your configuration according to the migration guide
+3. Run any new migrations: `rails db:migrate`
+4. Test in development/staging before deploying to production
+5. Start with `monitor_only = true` to verify behavior
+
+### Support
+
+- GitHub Issues: https://github.com/humadroid-io/beskar/issues
+- Documentation: https://humadroid.io/beskar
+
+---
+
+[Unreleased]: https://github.com/humadroid-io/beskar/compare/v0.0.2...HEAD