Download the PHP package therealmkadmi/laravel-citadel without Composer

A Passive Surveillance Package for Laravel to Protect Your Public Facing Endpoints

Laravel Citadel is an advanced, real-time firewall package for Laravel designed to protect your public-facing endpoints—especially those handling critical actions such as order placement. Using Redis and Laravel Octane's in-memory caching, Laravel Citadel performs multi-faceted analysis including rate limiting, payload integrity checks, failure tracking, device fingerprint verification, and referrer validation. Its weighted scoring system dynamically flags suspicious activity, enabling you to stop malicious human or automated abuse before it reaches your business logic.

Installation

You can install the package via Composer:

You can publish and run the migrations with:

You can publish the config file with:

This is the contents of the published config file:

Optionally, you can publish the views using:

Usage

Laravel Citadel works as a middleware. Here’s how you can integrate it into your routes:

1. Register the Middleware

Add the Citadel firewall middleware to your app/Http/Kernel.php:

2. Protect Critical Endpoints

Apply the middleware to your sensitive endpoints. For example, to protect the send-order endpoint:

3. Customize Behavior

Adjust settings in config/citadel.php to tailor the firewall to your needs. The configuration parameters include:

• Rate Limiting: Set the window, maximum requests, and burst thresholds.
• Payload Analysis: Define required fields, entropy limits, and weights for anomalies.
• Failure Tracking: Control failure weights and decay time.
• Device Fingerprint: Set additional weights for desktop or automated User-Agents.
• Referrer Validation: Whitelist your domain and adjust penalties for missing or invalid referers.
• Threshold: Set the overall suspect score above which requests are blocked.

How It Works

Laravel Citadel performs a series of checks on each incoming request:

1. Real-Time Frequency Tracking:

   • Uses Redis sorted sets to record and analyze request timestamps.
   • Removes entries outside a 60-second window and calculates the current request rate.
   • Enforces a minimum interval between requests to prevent burstiness.

2. Payload Anomaly Detection:

   • Validates that required fields (e.g., name, table, items) are present.
   • Analyzes text fields using regex and entropy calculations to detect gibberish or repetitive content.
   • Checks for extreme values and logical inconsistencies in numeric data (e.g., unrealistic quantities or price mismatches).

3. Failure Tracking:

   • Tracks failed attempts via a Redis counter with a TTL.
   • Increments the suspect score for each failure, decaying over time if the user ceases suspicious activity.

4. Device Fingerprint Analysis:

   • Examines the User-Agent header to determine if the request originates from a mobile device.
   • Assigns additional points for desktop browsers or known automation tools.

5. Referrer Verification:

   • Validates the HTTP referer against an expected domain.
   • Penalizes requests with a missing referer or one that originates from an unauthorized domain.
6. Weighted Scoring System:
   • Aggregates scores from frequency, payload, failure, device, and referrer analyses.
   • Compares the cumulative score against a configurable threshold.
   • Blocks the request if the threshold is exceeded, logging the event for further analysis.

Testing

You can run the tests via Composer:

Simulate various scenarios:

• Normal Traffic: Ensure legitimate orders (with proper payloads and mobile devices) pass.
• High-Frequency Abuse: Simulate a rapid succession of orders to trigger rate limiting.
• Payload Tampering: Send malformed payloads to test anomaly detection.
• Device & Referrer Variations: Use different User-Agents and referers to verify proper scoring.

Contributing

Contributions are welcome! Please open an issue or submit a pull request. For larger changes, consider discussing your ideas first.

Security Vulnerabilities

For information on reporting security vulnerabilities, contact me privately on wahibmkadmi16 [at] gmail [dot] com.

Credits

• Wahib
• All Contributors

License

Laravel Citadel is open-sourced software licensed under the MIT License.