Guard Core Php Laravel Package

Product Decisions This Supports

• Build vs. buy for application-layer detection. This package is a Laravel adapter over a detection engine, and 4.4.0 ships in lockstep with the core engines at 4.4.0. That parity cadence is the strongest buy signal: we are buying maintained detection behavior plus Laravel integration, not just a wrapper. It reduces the “abandoned dependency” risk that usually argues for building in-house.
• Shipping detection in latency-sensitive request paths. detectionMaxScanSeconds (default 10.0, range 0.1–60.0) caps summed regex scan CPU time per request and records a weighted pattern_timeout threat when exhausted. This gives us a concrete performance envelope to test against and tune per environment. It also prevents padding a request to skip detection. Note the cap applies to engine request scans, not direct detect() calls.
• Runtime security operations instead of release-bound config. dynamicRuleInterval (default 300, minimum 60) gates dynamic rule fetches, and dynamic rules now apply over the base config: ip_blacklist becomes a timed ban through the ban manager, ip_whitelist unbans, country/cloud-provider/user-agent/rate-limit rules replace base values, failed applies keep the previously active version, expiry restores base, and duplicate patterns are not re-added. This supports on-call/security teams changing posture without a deploy.
• Response customization as a product surface. GuardEngine::applyResponseModifier() and customResponseModifier provide a sanctioned seam applied once, after security headers and before CORS, with exceptions leaving the response unmodified. This supports multi-tenant block pages, branded responses, compliance messaging, and adapter behavior without forking the package.
• Tuning false positives without weakening regex coverage. excludedSemanticDetectionHeaders is opt-in and semantic-only; listed headers still get regex scanning. Useful for headers that legitimately carry rich content while retaining XSS/SQLi/CRLF coverage.
• Security observability and incident review. processResponse emits response_time, request_count, and error_rate when an agent handler with sendMetric is attached and agentEnableMetrics is on. Passive-mode suspicious logs now retain Reason: <reason>, and cookie scanning is per name=value pair, which should cut false positives on ordinary authenticated traffic while still detecting XSS, SQLi, and CRLF inside a single cookie.
• Correctness of bans, allowlists, and rate limits. 4.4.0 fixes client identity resolution (X-Forwarded-For port stripping, empty-entry handling, proxy-depth fallback, zoned/mapped addresses, malformed CIDRs, trustedProxies unix token, spoof detection) and IP list precedence (global whitelist decides alone; blacklist only when no whitelist; route whitelist skips global lists; route blacklist only when route has no whitelist). This directly affects whether a ban or allowlist entry actually matches the client, which is a product-trust issue, not just a bug fix.
• Roadmap prioritization. Treat 4.4.0 as a behavior-change release, not a routine patch. Plan a migration and regression-test workstream for proxy chains, IPv4-mapped IPv6, CIDRs, whitelist/blacklist route behavior, and agent-dependent configuration. Also plan the agent handler dependency if metrics or dynamic rules are on the roadmap.

When to Consider This Package

• Consider it when:
  • You run Laravel and want in-app, engine-backed detection and blocking without operating a separate WAF service.
  • You need a defensible per-request CPU budget for detection; detectionMaxScanSeconds gives you a tuning knob and a threat record when the budget is spent.
  • You need runtime-adjustable rules, timed IP bans, emergency mode, and versioned rule application operated by security/on-call rather than engineering deploys.
  • You can attach an agent handler. enableAgent is now required for enableDynamicRules and enableEnrichment to validate, and dynamic rule initialization depends on an agent handler with getDynamicRules().
  • You need a supported response-modification seam for branded, tenant-specific, or compliance-driven block responses.
  • Client identity behind proxies/CDNs matters to you. The 4.4.0 parity fixes change which client a ban, rate limit, or list entry matches.
• Look elsewhere or defer when:
  • You need edge or pre-PHP WAF protection. This runs in-app and consumes request CPU; an edge WAF or reverse proxy may be the better primary control.
  • You cannot attach the agent handler or cannot accept the new enableAgent prerequisite. Configs that enabled dynamic rules or enrichment without the agent will no longer validate; this is a migration gate.
  • You cannot absorb behavioral shifts in client identity and IP-list precedence. Bans, rate limits, and allow/deny outcomes can change on upgrade; treat this as a regression-testing release.
  • You have no owner for rule tuning and false-positive triage. Regex and semantic scanning need ongoing curation.
  • You require a commercial SLA or vendor support contract. Confirm the support model before making this a control in a compliance narrative.
  • You need guaranteed metrics out of the box. Metrics require an attached agent handler with sendMetric and agentEnableMetrics enabled.

How to Pitch It (Stakeholders)

• Executives: “We can add application-layer detection and response to our Laravel services without building or operating a separate WAF. The 4.4.0 release gives us a per-request CPU budget so security does not become a latency or availability risk, runtime-adjustable rules for incident response, and a supported response hook for customer-facing block pages. The main cost is configuration ownership and a coordinated upgrade, because client-identity and IP-list behavior change to match the reference engine.”
• Engineering: “It is a Laravel adapter in lockstep with the core engines at 4.4.0. Plan for: detectionMaxScanSeconds default 10.0 (tune per route; direct detect() calls are uncapped), enableAgent now required for enableDynamicRules and enableEnrichment to validate, dynamicRuleInterval default 300 with a floor of 60, and an applyResponseModifier seam applied once after security headers and before CORS. Client IP resolution and IP-list precedence now match the reference, so expect ban, rate-limit, and allowlist decisions to shift. Regression-test proxy chains, trustedProxies, CIDRs, IPv4-mapped IPv6, zoned addresses, and route/global whitelist-blacklist behavior. Metrics only flow with an agent handler exposing sendMetric and agentEnableMetrics on.”
• Security and on-call: “Dynamic rules now apply over the base config with clean versioning: a failed apply keeps the previous version, expiry restores the base, and patterns already in the pool are not duplicated. ip_blacklist is a timed ban through the ban manager, ip_whitelist unbans, and emergency mode halves the auto-ban threshold once. Passive-mode suspicious logs retain the reason, and cookie scanning is per name=value pair, which should reduce false positives on normal authenticated traffic while keeping XSS, SQLi, and CRLF detection inside a single cookie. A forwarded header from an untrusted peer raises spoofing_detected once with a redacted chain.”