Vigie Bundle Laravel Package

Getting Started

• Install with composer require iq2i/vigie-bundle. This is a Symfony bundle, not a Laravel package — it registers through config/bundles.php (or Symfony Flex auto-discovery). On Laravel you'll be wiring the services manually through a small service provider; budget for that instead of assuming php artisan vendor:publish will do anything.
• First place to look is the bundle's config reference. The two keys that decide whether anything works end-to-end are record.ip_address and output.*.
• Set record.ip_address: true on the emitting kernel (explicitly called out in the v0.3.0 docs). Without it, emitted decisions carry no source IP and CrowdSec has nothing to correlate against — this is the single most common "it runs but nothing happens" cause.
• First use case: keep the default file handler, point a CrowdSec file acquisition at the emitted log path, and install the CrowdSec profile/parser using the idempotent snippet now documented in the bundle. That gives you a working path from app event → decision → cscli decisions list in a few minutes.
• Verify with cscli decisions list and cscli metrics before writing any custom code.

Implementation Patterns

• File output (default). Treat the emitted file as the contract with CrowdSec. Keep the path stable, mount it as a volume in containers, and configure acquisition rather than tailing it yourself.
• Syslog output (new in v0.3.0). Use output.syslog when you're already shipping logs through rsyslog/syslog-ng or a collector. You must install the CrowdSec parser shipped with the bundle (added in this release) — the parser is what teaches CrowdSec to understand the syslog-encapsulated lines. File output and syslog can coexist, so you can migrate incrementally by running both and diffing cscli decisions list.
• Removed-decision reporting. v0.3.0 fixes duplicate reporting of a removed threat decision and enriches removed decisions from the store. Pattern: let the store be the source of truth for decision metadata, and treat the emitted "removed" event as a notification, not a payload — enrichment happens on the bundle side, so downstream consumers can rely on the same shape for add and remove.
• Provisioning/CI. Use the idempotent CrowdSec profile install snippet in your Dockerfile or bootstrap script; re-running it is safe, which means it can live in every deploy.
• Docker. host.hostname defaults to the container ID. If you group decisions by host anywhere (dashboards, alert routing), override it explicitly — either through config or by passing a stable name from your orchestrator.
• Backpressure on datagrams. Oversized syslog datagrams now produce a warning. Wire that warning into your existing log alerting so you catch a growing payload before CrowdSec starts silently dropping lines.

Gotchas and Tips

• record.ip_address must be true on the kernel that emits the record. Setting it on a different service in a multi-kernel app looks correct in config and does nothing.
• Syslog without the bundled parser is a silent failure mode: CrowdSec receives lines it can't parse and reports nothing useful. Confirm the parser is present with cscli parsers list.
• The new max_length warning is the only signal you get for truncation. RFC 5424 datagrams have a practical ceiling, and enrichment makes payloads larger — if you turned on removed-decision enrichment and started seeing these warnings, the two are related. Either raise max_length or shorten the enriched fields.
• Under Docker, host.hostname being the container ID means hostnames change on every redeploy. Anything keyed on hostname will fragment; pin it.
• Enrichment of removed decisions depends on the store still retaining the decision at removal time. If your store is pruned aggressively, removal events degrade to bare records — check retention before relying on the enriched fields.
• "Report a removed decision only once" changes emitted volume. If you had downstream dedupe compensating for the old behavior, remove it, otherwise you're now double-suppressing.
• Debugging order: tail -f the emitted file (or check journalctl for syslog) → confirm line shape matches the bundled parser → cscli metrics for parse/acquisition counters → cscli decisions list. That sequence isolates emission vs. parsing vs. decision-engine problems quickly.
• Extension point to watch: output handlers. The syslog option landing next to the file handler signals the output layer is being generalized — if you need a custom sink, that's the seam to target rather than post-processing the file.