Monitoring CrowdSec with Vigilmon

CrowdSec is an open-source security engine that analyses logs, detects attacks, and shares threat intelligence across a community of users. Unlike traditional IPS tools, CrowdSec separates detection (the agent) from enforcement (the bouncer) — and both rely on the CrowdSec Local API to communicate. If that API goes down, your bouncers stop receiving blocklist updates and new threats pass through unblocked. Vigilmon keeps continuous watch over CrowdSec so a silent failure never leaves your infrastructure exposed.

What You'll Set Up

• HTTP monitor for the CrowdSec Local API
• Health endpoint check via /v1/health
• TCP monitor for database connectivity
• SSL certificate alerts for TLS-enabled instances
• Heartbeat to confirm agent connectivity

Prerequisites

• CrowdSec installed and running (default LAPI port :8080)
• A free Vigilmon account

Step 1: Monitor the CrowdSec Local API

The CrowdSec Local API (LAPI) is the central hub that agents report to and bouncers poll for ban decisions. Monitor its availability:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your LAPI URL: http://your-server:8080 (or the configured LAPI URL in /etc/crowdsec/config.yaml).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200 or 404 — the root endpoint may return 404, which still confirms the API is alive.
6. Click Save.

For the most accurate check, use the dedicated health endpoint in Step 2 instead of the root URL.

Step 2: Check the /v1/health Endpoint

CrowdSec exposes a health endpoint at /v1/health that confirms the LAPI is operational:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-server:8080/v1/health
3. Set Expected HTTP status to 200.
4. Optionally set Expected response body contains to "ok".
5. Set interval to 1 minute.
6. Click Save.

This endpoint validates that the LAPI can accept agent registrations and serve bouncer decisions. If it fails, bouncers immediately fall back to their last cached ban list (or allow all traffic, depending on your bouncer configuration).

To confirm the health endpoint is reachable from your server:

curl -s http://localhost:8080/v1/health
# {"status":"ok"}

Step 3: Monitor Database Connectivity

CrowdSec stores alerts, decisions, and agent registrations in SQLite, PostgreSQL, or MySQL. Database failures cause the LAPI to start returning errors for decision queries even if the /v1/health endpoint appears healthy.

For SQLite (the default), monitor disk usage on the data directory:

# CrowdSec data directory
ls -lh /var/lib/crowdsec/data/

For PostgreSQL or MySQL backends, add a TCP port monitor in Vigilmon:

1. Click Add Monitor → TCP Port.
2. Enter the database host and port: your-db-host:5432 (PostgreSQL) or your-db-host:3306 (MySQL).
3. Set interval to 2 minutes.
4. Click Save.

A database TCP failure alongside a LAPI health failure confirms the root cause immediately.

Step 4: Monitor Agent Connectivity

CrowdSec agents (running on each protected server) register with the LAPI and push log-derived signals. If an agent disconnects, that server's traffic goes unanalyzed.

Check agent registration status from the command line:

cscli machines list

For continuous monitoring, set up a script that polls machine status and sends a Vigilmon heartbeat:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set interval to 10 minutes.
3. Copy the heartbeat URL.
4. Create a cron job on the LAPI host:

*/10 * * * * \
  cscli machines list --output json | \
  python3 -c "import sys,json; m=json.load(sys.stdin); exit(0 if all(x['isValidated'] for x in m) else 1)" && \
  curl -s https://vigilmon.online/heartbeat/YOUR_ID

If any registered machine loses validation, the heartbeat stops and Vigilmon alerts.

Step 5: Dashboard and Console Sync

If you use the CrowdSec Console (the cloud management UI), your local instance syncs decisions and metrics to https://app.crowdsec.net. A sync failure means your console view is stale, but more importantly it can indicate outbound network issues from your server.

Check sync status:

cscli console status

For continuous sync monitoring, add the Vigilmon heartbeat to a script that validates the last sync timestamp:

*/30 * * * * \
  cscli metrics --output json | \
  python3 -c "import sys,json; m=json.load(sys.stdin); print(m)" && \
  curl -s https://vigilmon.online/heartbeat/YOUR_SYNC_ID

Step 6: SSL Certificate Alerts

When CrowdSec LAPI is configured with TLS (recommended for multi-host deployments where agents and bouncers connect over the network), certificate expiry will break all agent and bouncer connectivity.

1. Open the CrowdSec LAPI HTTP monitor.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

Check the TLS configuration in /etc/crowdsec/config.yaml:

api:
  server:
    tls:
      cert_file: /etc/crowdsec/ssl/server.crt
      key_file: /etc/crowdsec/ssl/server.key

If you use a custom CA for mutual TLS between agents and the LAPI, monitor the CA certificate expiry separately with the same 21-day window.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP / LAPI | :8080 | API process down, not accepting connections | | Health endpoint | /v1/health | LAPI operational failure | | TCP / Database | :5432 or :3306 | Database unreachable | | SSL certificate | LAPI TLS cert | Agent/bouncer connectivity broken | | Cron heartbeat | Machine validation | Agent disconnected, unmonitored host |

CrowdSec's power comes from continuous, real-time threat sharing — but only while its Local API is healthy and agents are connected. With Vigilmon monitoring the LAPI health endpoint, database connectivity, agent registration, and TLS certificates, you get immediate alerts when the security layer protecting your infrastructure goes silent.