Vigie Bundle Laravel Package

Technical Evaluation

Architecture fit

• IQ2i/vigie-bundle v0.3.0 is a threat-signal bridge: it emits log records to a local/remote sink and reconciles "threat decisions" (add/remove) with a CrowdSec-style decision store. That is an infrastructure/edge concern, not typical Laravel domain logic.
• Fit is therefore strongest for teams already running CrowdSec (or an equivalent) in front of the app tier, and weakest for teams expecting an in-process Laravel security middleware. This package complements a WAF/bouncer; it does not replace one.
• The v0.3.0 output.syslog option moves it from a single local-file integration to a dual-transport integration (file or syslog). That broadens fit with existing SIEM/log-pipeline investments but introduces a network dependency into the request/logging path.
• Naming and terminology ("bundle", "emitting kernel") strongly suggest a Symfony bundle rather than a native Laravel package. Architecture fit for Laravel must be confirmed before any design work — see Key Questions.

Integration feasibility

• Low-to-moderate for the default file handler: publish config, point at a path, ensure log rotation, done.
• Moderate for the new syslog output: requires a reachable collector, a CrowdSec parser deployed on the receiving side (newly shipped in this release, PR #11), and a CrowdSec profile installed (PR #10 adds an idempotent snippet — useful for repeatable provisioning).
• Two upstream prerequisites are documented, not enforced: record.ip_address must be true on the emitting kernel (PR #8), and host.hostname resolves to the container ID under Docker (PR #9). Both are silent misconfiguration sources — the package will run and produce degraded or uncorrelatable data rather than failing loudly.
• The store-backed enrichment of removed decisions (PR #7) implies an additional persistence read on the removal path; feasibility depends on store availability and retention exceeding decision TTL.

Technical risk

• Pre-1.0 API surface. 0.x semver permits breaking changes in minor bumps. Treat every upgrade as a potential breaking change; pin exactly.
• Config schema drift. Introducing an output.syslog key "next to the default file handler" hints at an output.* config namespace that may have restructured existing keys. Any republished config risks overwriting local customisation.
• Metric discontinuity. PR #6 fixes duplicate reporting of removed threat decisions. Downstream dashboards, alert thresholds, or CrowdSec API call-volume budgets baselined on the buggy (inflated) counts will shift after upgrade. This is a behavioural change disguised as a fix.
• Silent truncation over syslog. PR #13 only warns when a datagram exceeds max_length. Multi-KB payloads (stack traces, long user agents) will be truncated and forwarded; truncated JSON may be dropped by the parser. Warning-only, no drop/no fail-closed policy.
• Container identity. Documented as expected behaviour that host.hostname is the container ID under Docker. Decisions and alerts keyed to an ephemeral ID break correlation across restarts and replica churn.
• Enrichment failure mode unknown. No indication of behaviour when the store is unreachable during a removal event — fail open, fail closed, or drop the decision are all plausible and have very different security consequences.

Key questions

1. Is this a Symfony bundle only, or is there a supported Laravel service provider/bridge? If Symfony-only, what is the integration cost?
2. Supported PHP and framework version matrix, and the CrowdSec version range the shipped parser/profile target?
3. Does the output.syslog change alter or rename existing config keys? Is a migration guide or upgrade note provided?
4. Which syslog transport is supported — UDP, TCP, or TLS? What is the default max_length, and what happens to oversized messages beyond the warning?
5. Are removed-decision enrichments required or best-effort? What is the behaviour on store timeout or unavailability?
6. Is the store a hard dependency, and what retention window is assumed?
7. Licence, release cadence, maintainer count, CI/test coverage, and whether the shipped CrowdSec parser is versioned with the package or the CrowdSec release?
8. Does the file handler have bounded growth/rotation guarantees, or is that entirely the operator's responsibility?

Integration Approach

Stack fit

• Treat as an edge/observability integration, not application code. Owned by platform/DevOps, consumed by app teams via configuration only.
• File handler: fits any Laravel deployment with persistent local disk. Lowest-risk entry point.
• Syslog output: fits environments that already operate a collector (rsyslog/syslog-ng/Vector/Fluent Bit) and CrowdSec acquisition. Do not stand up a collector for this package alone without a broader logging case.
• If the package is Symfony-only, budget for a thin Laravel adapter or a sidecar process rather than assuming a drop-in install.

Migration path

1. Pin the currently deployed version exactly; do not float constraints.
2. In non-production, install v0.3.0, diff the published config against the existing one, and reconcile manually — never blind-republish.
3. Satisfy prerequisites first: set record.ip_address: true on the emitting side, and set an explicit stable host.hostname override for containers (do not rely on the container-ID default).
4. Enable output.syslog alongside the existing file handler in a shadow period; deploy the CrowdSec parser (PR #11) and profile (PR #10) to the collector before any traffic.
5. Compare parsed events in the collector against the file output for a representative window; check for truncation warnings and for host-identity collisions across replicas.
6. Cut over, keep the file handler as fallback for one release cycle.

Compatibility

• Pre-1.0: assume config and behavioural incompatibility on every minor bump. Record the exact version in the deployment manifest.
• The duplicate-report fix (PR #6) is backward-incompatible at the data layer even if the API is unchanged — coordinate with whoever owns security dashboards and CrowdSec rate-limit budgets.
• Validate parser/collector versions against the package before rollout; a mismatched CrowdSec version is the most likely cause of "installed but no decisions appear."

Sequencing

• Phase 1 (week 1): read-only evaluation — confirm framework support, licence, transport options; file-handler spike in a sandbox.
• Phase 2: prerequisite config hardening (record.ip_address, explicit hostname) — these are independently valuable and low risk.
• Phase 3: collector-side prerequisites (parser + profile) deployed to staging via the idempotent snippet.
• Phase 4: shadow syslog + file dual-write, comparison and baseline reset for decision counts.
• Phase 5: syslog primary, file fallback retained.
• Explicit gate: do not proceed past Phase 3 until the truncation and enrichment-failure questions are answered.

Operational Impact

Maintenance

• Low ongoing effort for file-output-only deployments; the surface is a config file and a log path.
• Syslog deployments take on a two-sided maintenance burden: the package on the app side and the parser/profile on the collector side. These can drift independently across upgrades — version-lock them together.
• Pre-1.0 status means planned upgrade work each minor release, not opportunistic upgrades. Budget a recurring slot.
• Duplicated parser/profile artifacts deployed outside the app (a yaml on the collector) are easy to forget during incident review; record them in the same runbook as the app config.

Support

• Support load will concentrate in three predictable areas: no events reaching the collector (network/parser/version mismatch), missing or wrong client IPs (the record.ip_address prerequisite), and unreadable hostnames in Docker.
• The new truncation warning (PR #13) is helpful diagnostically but will become a routine noise source for apps logging large payloads; operators need a documented policy (raise max_length, switch transport, or filter before emit) or they will suppress the warning.
• Because the two prerequisites are documented rather than validated, first-line support cannot distinguish misconfiguration from malfunction without manual inspection. Add explicit checks to the on-call runbook and, if cheap, a startup assertion.
• Ramp-up for a competent PHP/platform engineer: roughly half a day for file output, one to two days for syslog plus CrowdSec collector integration. Cross-team coordination (app + platform + security) is the real cost, not the code.

Scaling

• File handler scales with disk and rotation discipline; unbounded growth is an operator responsibility and a common incident cause.
• Syslog over UDP scales easily but degrades invisibly: datagram truncation and unreliability at volume. At high emit rates, assume loss unless TCP/TLS or a local buffering agent is in the path.
• Decision enrichment (PR #7) adds a store read per removal event; at scale this is a new hot dependency on the removal path, and store latency becomes logging-path latency unless emission is decoupled/buffered.
• Under Docker/Kubernetes, horizontal scaling multiplies distinct host.hostname values. Alert correlation and per-host decision management degrade unless a stable identity is injected (pod name plus a stable service label, or a per-node aggregation layer).

Failure modes

• Collector unreachable: unknown whether events buffer, drop, or block. Must be determined before production; blocking on logging is unacceptable for request-path code.
• Store unavailable on removal: decision may not be enriched, reported unenriched, or silently dropped. Highest-severity unknown — a dropped removal means a mitigation outlives its justification.
• Oversized datagram: truncated and forwarded; parser may discard. Detection is warning-based only.
• Container restart: new hostname, orphaned decisions and split alert history.
• Upgrade with republished config: silent loss of local overrides; symptoms appear as absent telemetry days later.
• Duplicate-report fix applied without baseline reset: apparent drop in removed decisions read as a security regression during review.

Ramp-up

• Assume a short, well-documented learning curve for the happy path and a long tail of environment-specific prerequisites.
• Onboarding checklist worth producing internally: framework compatibility confirmed, version pinned, prerequisites set, collector parser/profile version-matched, transport chosen with truncation policy, fallback handler retained, dashboards rebaselined, failure-mode behaviour confirmed for collector-down and store-down.
• Given pre-1.0 maturity and the number of environment-dependent unknowns in this release, recommend limited adoption behind a fallback rather than broad rollout; revisit at 1.0 or after the failure-mode questions are answered in writing.