Download the PHP package kanopi/firewall without Composer

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.

📖 Documentation

Start at the documentation index.

This README is a short introduction. Everything else — the complete configuration reference, every plugin, the shipped presets, platform integration, and the contribution guide — is in docs/, and published at kanopi.github.io/firewall.

The docs source is the docs/ directory in this repository. See Writing Documentation to contribute a change.

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

Requirements

• PHP 8.1 or higher
• Composer
• Symfony components 6.4, 7.3, or 8.1 (Composer picks whichever line your PHP version and application allow)
• Optional: MaxMind GeoIP2 databases for geolocation features
• Optional: Redis for distributed rate limiting

Installation

Quick Start

Place the following in your application's entry point (index.php, wp-config.php, or Drupal's settings.php):

⚠️ Configure trusted proxies before calling Firewall::create()

Every plugin evaluates $request->getClientIp(). Symfony only honors X-Forwarded-For / Forwarded / X-Real-IP when you have called Request::setTrustedProxies(...). If your application sits behind a load balancer, CDN, or reverse proxy and you skip this, attackers can spoof their source IP and bypass IP allow-lists, block-lists, and per-IP rate limits.

See Trusted Proxies.

Create a config/firewall.yml:

Want a preset instead of writing rules by hand?

Continue with the Quick Start or the five-minute Test Drive.

Local Development

To preview the documentation site locally:

Contributing

We welcome contributions. See the Contributing Guide for development setup, branch and commit conventions, testing requirements, and the PR checklist.

Support

• Documentation: kanopi.github.io/firewall (source in docs/)
• Issues: github.com/kanopi/firewall/issues
• Discussions: github.com/kanopi/firewall/discussions

License

This project is licensed under the MIT License. See the LICENSE file for details.

Credits

Lite Firewall is developed and maintained by Kanopi Studios.

Special thanks to:

• The Symfony team for the excellent HttpFoundation component
• MaxMind for the GeoIP2 databases
• The Monolog team for the flexible logging library