Lite Firewall¶

Lite Firewall is a powerful, extensible request-evaluation library for PHP-based systems. It analyzes HTTP requests and applies configurable rules to allow, challenge, or block access based on IP addresses, geolocation, user agents, URLs, ASN (Autonomous System Numbers), rate limits, vulnerability scoring, and the OWASP Core Rule Set.

It is framework agnostic — it works with Drupal, WordPress, Symfony, Laravel, or any standalone PHP application.

composer require kanopi/firewall

require_once __DIR__ . '/vendor/autoload.php';

\Kanopi\Firewall\Firewall::create([__DIR__ . '/config/firewall.yml'])->evaluate();

Features¶

• Flexible Plugin System: Modular architecture allows for easy extension and customization
• Multiple Storage Backends: In-memory, file-based, and database storage for blocked clients, plus in-memory, file, database, PSR-6 cache, and Redis backends for rate-limit counters — or bring your own
• Comprehensive Request Analysis: Evaluate requests based on IP, location, ASN, user agent, URL patterns, and more
• OWASP Core Rule Set: Real CRS rules (SQLi, XSS, LFI/RFI, RCE, scanners) with tunable paranoia levels
• IP Reputation: Turn away addresses reported to AbuseIPDB, cached to stay inside the free tier and failing open when the service is unreachable
• Vulnerability Scoring: Advanced risk assessment based on multiple factors with configurable thresholds
• Rate Limiting: Built-in rate limiting with configurable storage backends
• Challenge Responses: Serve a proof-of-effort interstitial instead of a hard block, with HMAC-signed, IP-bound pass tokens
• GeoIP Integration: Full support for MaxMind GeoIP2 databases (both local and web service)
• Advanced Conditional Logic: Support for simple, complex, and grouped conditional rules
• Escalating Bans: Repeat offenders can be banned for progressively longer, up to permanently
• Remote Configuration Support: Load configuration files from remote URLs with local caching
• PSR-3 Compatible Logging: Integration with Monolog for flexible logging, with sensitive headers redacted by default
• Framework Agnostic: Works with any PHP application or framework — block, log-only, or throw exceptions for your framework to handle

How a request flows¶

flowchart TD
    A[Incoming request] --> B{mode: disabled?}
    B -->|yes| Z[Allow]
    B -->|no| C{On the storage blocklist?}
    C -->|yes| Y[Block]
    C -->|no| D[allow plugins, by weight]
    D -->|match| Z
    D -->|no match| E[challenge plugins, by weight]
    E -->|match, no valid pass token| X[Serve interstitial]
    E -->|no match, or valid token| F[block plugins, by weight]
    F -->|match| Y
    F -->|no match| Z

Allow plugins short-circuit everything. A valid challenge pass token skips the challenge bucket but never suppresses a block. See Plugin Architecture for the full ordering rules and Challenge Responses for the interstitial flow.

Where to go next¶

Requirements¶

• PHP 8.1 or higher
• Composer
• Optional: MaxMind GeoIP2 databases for geolocation features
• Optional: Redis for distributed rate limiting

Support¶

• Issues: github.com/kanopi/firewall/issues
• Source: github.com/kanopi/firewall
• Package: packagist.org/packages/kanopi/firewall

License¶

Released under the MIT License. Developed and maintained by Kanopi Studios.