Laravel Crowdsec Laravel Package

Technical Evaluation

Architecture fit This package is a Laravel-native security layer that plugs into the request lifecycle via middleware, with supporting service-provider bindings, config, migrations, scheduled cleanup, a dashboard, and a REST API. For a TPM, the architectural appeal is that it delivers WAF-style inspection, IP reputation/blocking, audit logging, and operational controls without introducing a separate gateway or sidecar. v1.7.0 strengthens fit for modern threat coverage and production operations: JNDI/Log4Shell detection, broader header inspection, manual crowdsec:block/unblock commands, configurable retention, export filters, Laravel 13 support, and significant security hardening around dashboard/API authorization and CIDR matching.

Integration feasibility Integration is conventional for a Laravel package: Composer install, publish config/migrations, run migrations, register schedules, expose/protect dashboard and API routes, and optionally tune scenarios. The main feasibility concern in v1.7.0 is not installation but production hardening. The package now enforces viewCrowdSec and manageCrowdSec gates outside local; without application-defined gates, dashboard and API access returns 403. That is a deliberate security improvement but a deployment-blocking change for existing installations. Published configs also retain api.middleware, so the new throttle:60,1 default must be added manually. Laravel 10 applications using app/Console/Kernel.php must add the new crowdsec:cleanup --audit-logs schedule to preserve audit retention. The MySQL/MariaDB whitelisted_ips.expires_at change from TIMESTAMP to DATETIME is low-code but schema-sensitive.

Technical risk Primary risks are operational and behavioral, not architectural. Gate enforcement can break dashboards/API consumers on upgrade if roles are not defined and communicated. The GET /api/crowdsec/check/{ip} response is intentionally reduced to behavior counters, which may break API consumers expecting the full row. Route names changed to crowdsec.api.*, so any hardcoded route references need updating. The jwt_privilege_escalation default changing from enforce to monitor reduces false blocking of legitimate admins but changes detection posture. The CIDR fix changes whitelist matching semantics—correctly preventing IPv4/IPv6 cross-family matches—but existing whitelist entries should be regression-tested. Migrations that add/drop indexes and widen a column may require a maintenance window on large tables. Retention cleanup now deletes rows, so misconfigured retention values could remove data faster than intended. WAF evasion fixes improve coverage but increase inspection work: overlapping 8 KB chunks up to 64 KB, 32-level body flattening, additional decoding layers, and header inspection all add CPU cost on large or malicious requests. The security fixes are strong, but the release should be treated as production-impacting despite the minor version number.

Key questions

• Which Laravel/PHP versions are in the fleet, and is Laravel 13 adoption planned?
• Who owns authorization policy for viewCrowdSec and manageCrowdSec, and what roles map to those gates?
• Are there existing dashboard/API consumers that depend on the old check/{ip} payload or unnamed routes?
• What are the current table sizes for security_events, blocked_ips, whitelisted_ips, and ip_behaviors, and can migrations run online?
• What retention policy is appropriate for events, behavior, blocked IPs, and block-count reset?
• Is intl available for NFKC normalization, and are there latency budgets for WAF inspection?
• What is the rollback plan if gate enforcement or migrations cause production issues?

Integration Approach

Stack fit The package fits Laravel applications from Laravel 10 through Laravel 13, with CI covering Laravel 13 on PHP 8.3–8.5, Laravel 12 on PHP 8.5, and a --prefer-lowest job on PHP 8.1/Laravel 10. It supports MySQL 8.4, PostgreSQL 16, and SQLite in test coverage. For a TPM, this is a good fit for teams already standardized on Laravel and relational storage, especially where a lightweight in-app security control is preferable to a separate WAF appliance. The package is less suitable where request inspection must be centralized outside the application or where the team cannot own gate definitions and scheduled maintenance.

Migration path Treat this as a controlled security upgrade, not a routine minor bump:

1. Define viewCrowdSec and manageCrowdSec gates in AppServiceProvider::boot() or equivalent before deploying to non-local environments.
2. Add throttle:60,1 or a custom limiter to the published api.middleware config.
3. Run the new migrations in staging first, then production: composite index on security_events (event_type, severity), index cleanup, and MySQL/MariaDB DATETIME widening for whitelisted_ips.expires_at.
4. Add crowdsec:cleanup --audit-logs to Laravel 10 schedules; verify withoutOverlapping() and onOneServer() behavior for all cleanup tasks.
5. Review and set retention.* values and corresponding CROWDSEC_*_RETENTION_DAYS environment variables.
6. Update any API consumers for named routes and the reduced check/{ip} response.
7. Validate JNDI/header inspection, CIDR whitelist behavior, JWT monitor default, manual block/unblock, and export filters.

Compatibility Published configs pick up new top-level keys such as jndi_injection and retention, but they do not automatically receive the new API throttle middleware. Applications must manually add it. Route names are now crowdsec.api.*; any hardcoded URLs or route-name references should be audited. The check/{ip} response shape is a consumer-facing change. The gate enforcement is the largest compatibility break outside local. The JWT default-mode change is behaviorally safer but may alter expected enforcement results. The MySQL TIMESTAMP limitation fix is compatibility-positive, but the migration should be checked against existing 2038+ whitelist entries.

Sequencing Sequence the rollout as: security policy definition → config and middleware updates → staging migrations → application deploy → scheduler update → smoke tests → production migrations if not already applied → monitoring. Gate definition must precede production deployment to avoid a dashboard/API outage. Migration work should run in a low-traffic window, especially the index changes and DATETIME alteration. After deployment, validate dashboard access with both authorized and unauthorized users, API rate limiting, block/unblock commands, whitelist CIDR behavior across IPv4/IPv6, JNDI detection on headers and User-Agent, audit-log cleanup scheduling, and export streaming with filters. Only then enable retention deletion aggressively.

Operational Impact

Maintenance Maintenance load increases modestly but meaningfully. The package now has more migrations, more config keys, additional scheduled tasks, and data-retention responsibilities. The cleanup commands delete inactive blocked_ips rows and audit logs according to retention settings, so operators must understand what is deleted and when. The new composite index and dropped redundant indexes reduce some query overhead but require migration care. The metrics endpoint cache and batched cleanup reduce steady-state load. The TPM should ensure runbooks cover gate ownership, retention tuning, manual block/unblock, export usage, and upgrade notes for Laravel 10 scheduling.

Support Support burden will center on authorization and false positives. Outside local, users who previously had dashboard/API access will receive 403 until gates are defined; this needs proactive communication. API consumers may report missing fields from check/{ip} or broken route references. Security teams may see JNDI and header-injection findings on legitimate payloads containing ${jndi:...}-like strings, and the JWT default change to monitor may reduce blocks but increase monitoring noise. Support should be prepared to explain why admins with bearer tokens are no longer auto-blocked and how to tune scenario modes.

Scaling The release improves scaling in several areas: fewer queries per clean request, one PCRE-limit setup per WAF pass instead of per pattern, batched deletes, cached metrics output, chunked input scanning, and withoutOverlapping()/onOneServer() scheduling. However, header inspection, JNDI scanning, deeper body flattening, multiple decoding layers, and up-to-64 KB chunked scanning increase CPU cost for large or hostile requests. Retention deletion and index optimization help control database growth. The API rate limit protects the REST surface. TPMs should benchmark request latency under realistic traffic and large payloads, and monitor database size and cleanup duration.

Failure modes Key failure modes include: gate misconfiguration causing dashboard/API lockout; API consumers breaking on reduced response payloads or renamed routes; migrations failing or locking large tables; retention settings deleting data too aggressively; whitelist behavior changing after the CIDR fix; WAF false positives after new decoding/normalization; HoneypotTrap failing open by design when blocking fails; and scheduled cleanup overlap if withoutOverlapping()/onOneServer() are not supported by the cache/scheduler setup. The release fixes several dangerous prior behaviors—audit logs being deleted by --expired, shorter blocks overwriting longer ones, re-blocking after expiry, and whitelisted IPs being blocked by the honeypot—which materially improves operational safety.

Ramp-up Ramp-up requires coordination across application engineering, security, and operations. The TPM should run a short enablement session covering gate definitions, config changes, migration order, retention policy, manual block/unblock commands, export filters, and the changed API contract. Staging validation should include unauthorized dashboard access, API throttling, IPv4/IPv6 whitelist cases, JNDI/header payloads, JWT admin-token behavior, audit-log retention, and cleanup command behavior. After rollout, track 403 rates, blocked-IP counts, WAF latency, database growth, cleanup job duration, and support tickets related to false positives or API breakage.