therealmkadmi / laravel-citadel
A passive survaillance and firewall package for laravel to protect your public facing endpoints.
Fund package maintenance!
TheRealMkadmi
Requires
- php: ^8.4
- illuminate/contracts: ^10.0||^11.0||^12.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^2.9||^3.0
- laravel/pint: ^1.14
- nunomaduro/collision: ^8.1.1||^7.10.0
- orchestra/testbench: ^10.0.0||^9.0.0||^8.22.0
- pestphp/pest: ^3.0
- pestphp/pest-plugin-arch: ^3.0
- pestphp/pest-plugin-laravel: ^3.0
- phpstan/extension-installer: ^1.3||^2.0
- phpstan/phpstan-deprecation-rules: ^1.1||^2.0
- phpstan/phpstan-phpunit: ^1.3||^2.0
- spatie/laravel-ray: ^1.35
README
Introduction
Laravel Citadel is a passive surveillance package designed to protect your public-facing endpoints. It provides a robust firewall system that analyzes incoming requests, detects anomalies, and blocks malicious traffic. The package is highly configurable and integrates seamlessly with Laravel applications.
Installation
- Install the package via Composer:
composer require therealmkadmi/laravel-citadel
- Publish the configuration file:
php artisan vendor:publish --provider="TheRealMkadmi\\Citadel\\CitadelServiceProvider"
- Add the middleware to your routes or global middleware stack as needed.
Configuration
The configuration file is located at config/citadel.php. Below are the available settings:
General Settings
- version: Current version of Laravel Citadel.
Geofencing Settings
- enabled: Enable or disable geofencing.
- mode:
allow(whitelist) orblock(blacklist). - countries: Comma-separated ISO-3166-1 alpha-2 country codes.
Device Analyzer Settings
- smartphone_score: Score for smartphone devices.
- tablet_score: Score for tablet devices.
- desktop_score: Score for desktop devices.
- bot_score: Score for bots or automated tools.
IP Analyzer Settings
- weights: Weights for different IP characteristics (e.g.,
bogon,datacenter,tor, etc.).
Burstiness Analyzer Settings
- min_interval: Minimum interval between requests (in milliseconds).
- window_size: Sliding window size (in milliseconds).
- max_requests_per_window: Maximum requests allowed in the window.
Payload Analyzer Settings
- required_fields: Fields required in the payload.
- max_size: Maximum payload size (in bytes).
- max_params: Maximum number of parameters allowed.
- suspicious_patterns: Patterns to detect malicious payloads.
Spamminess Analyzer Settings
- weights: Weights for spam-related anomalies (e.g., gibberish text, repetitive content).
Ban Settings
- ban_ttl: Default time-to-live for bans (in seconds).
- cache_key: Key prefix for storing banned IPs or fingerprints.
- message: Message displayed to banned users.
API Settings
- enabled: Enable or disable API endpoints.
- token: Secret token for API authentication.
- prefix: Prefix for API routes.
Middleware Groups
Laravel Citadel provides three middleware groups that you can use in your application:
1. Passive Monitoring Only (citadel-passive)
The passive middleware group only runs analyzers that don't make external requests. It provides monitoring and logging without blocking any requests, ideal for gathering intelligence about traffic patterns.
Route::middleware(['citadel-passive'])->group(function () { // These routes will be monitored but never blocked Route::get('/public-content', 'ContentController@index'); });
2. Active Protection (citadel-active)
The active middleware group runs analyzers that may make external requests (such as IP intelligence lookups) and will block malicious traffic. This includes geofencing and ban checking.
Route::middleware(['citadel-active'])->group(function () { // These routes get full protection with external API calls Route::post('/login', 'AuthController@login'); Route::post('/register', 'AuthController@register'); });
3. Complete Protection (citadel-protect)
For maximum security, the complete protection middleware group combines both active and passive analyzers. This is the original middleware group and provides backward compatibility.
Route::middleware(['citadel-protect'])->group(function () { // These routes get complete protection with all analyzers Route::post('/checkout', 'PaymentController@processPayment'); });
Configuration
You can enable or disable each middleware group independently in your configuration:
// In config/citadel.php 'middleware' => [ 'enabled' => env('CITADEL_ENABLED', true), // Global on/off switch 'passive_enabled' => env('CITADEL_PASSIVE_ENABLED', true), // Enable passive monitoring 'active_enabled' => env('CITADEL_ACTIVE_ENABLED', true), // Enable active protection ],
This configuration also applies to your .env file:
CITADEL_ENABLED=true
CITADEL_PASSIVE_ENABLED=true
CITADEL_ACTIVE_ENABLED=true
Middleware
ProtectRouteMiddleware
Analyzes incoming requests using registered analyzers and blocks requests exceeding the configured threshold.
ApiAuthMiddleware
Authenticates API requests using a token.
GeofenceMiddleware
Blocks requests based on geographical location.
BanMiddleware
Checks if a request originates from a banned IP or fingerprint.
Analyzers
BurstinessAnalyzer
Detects rapid consecutive requests and suspicious patterns in request timing.
DeviceAnalyzer
Analyzes the User-Agent header to determine the type of device making the request.
IpAnalyzer
Analyzes the IP address for characteristics like being a datacenter, Tor exit node, or VPN.
PayloadAnalyzer
Analyzes the request payload for anomalies, missing fields, and malicious patterns.
SpamminessAnalyzer
Detects spam-like behavior in request payloads.
API Endpoints
Ban Endpoint
POST /api/citadel/ban
Parameters:
identifier(string, required): The IP or fingerprint to ban.type(string, required):iporfingerprint.duration(integer, optional): Duration of the ban in minutes.
Response:
success(boolean): Whether the operation was successful.message(string): Description of the result.
Unban Endpoint
POST /api/citadel/unban
Parameters:
identifier(string, required): The IP or fingerprint to unban.type(string, required):iporfingerprint.
Response:
success(boolean): Whether the operation was successful.message(string): Description of the result.
Status Endpoint
GET /api/citadel/status
Response:
status(string):okif the API is accessible.version(string): Current version of the package.timestamp(string): Current server timestamp.
Commands
CitadelBanCommand
Bans a user by IP or fingerprint from the command line.
Usage:
php artisan citadel:ban {identifier} --type={ip|fingerprint|auto} --duration={minutes}
CitadelUnbanCommand
Unbans a user by IP or fingerprint from the command line.
Usage:
php artisan citadel:unban {identifier} --type={ip|fingerprint|auto}
CitadelCommand
Displays general information about the Citadel package.
Usage:
php artisan laravel-citadel
Usage Examples
Protecting Routes
Add the citadel-protect middleware group to your routes:
Route::middleware(['citadel-protect'])->group(function () { Route::get('/protected', function () { return 'This route is protected by Citadel.'; }); });
Using the API
Enable the API in the configuration file and set a token:
'api' => [ 'enabled' => true, 'token' => env('CITADEL_API_TOKEN', 'your-secret-token'), 'prefix' => 'api/citadel', ],
Make a request to ban an IP:
curl -X POST \
-H "Authorization: Bearer your-secret-token" \
-d "identifier=192.168.1.1&type=ip&duration=60" \
http://your-app.test/api/citadel/ban
Customizing Analyzers
You can create custom analyzers by implementing the IRequestAnalyzer interface and registering them in the service provider.
Logging
Citadel logs various events, such as bans, unbans, and detected threats. You can configure the log channel in the citadel.php configuration file.
Testing
Run the test suite using PHPUnit:
vendor/bin/phpunit
Contributing
Contributions are welcome! Please follow the Laravel coding standards and submit a pull request.
License
Laravel Citadel is open-sourced software licensed under the MIT license.