CrowdSec Monitor API

A RESTful API to monitor and query data from CrowdSec LAPI (Local API) using Express.js, SQLite3 (or PostgreSQL), and Sequelize with TypeScript.

iOS version

Android version

CrowdSec Monitor API provides a persistent storage layer and query interface for CrowdSec security alerts and decisions. It automatically syncs data from your CrowdSec LAPI instance and stores it in a local SQLite database, allowing you to query historical data, generate statistics, and monitor your security posture over time.

• Incremental Database: All CrowdSec data is stored permanently in a database
• Automatic Synchronization: Only new alerts are added, preventing duplicates
• TypeScript: Strong typing for improved security and maintainability
• Rate Limiting: Protection against API abuse (optional)
• PostgreSQL support: You can use PostgreSQL instead of SQLite if you prefer it.

CrowdSec Monitor API has an integrated blocklists management system, so you don't need to use extra tools. You can add a blocklist using an URL, and this service will automatically fetch the list and block that IP addresses on CrowdSec. It will also refresh the blocklists after a certain period of time.

Instructions on the wiki page.

Configure DATA_RETENTION to automatically delete old alerts and decisions:

• 1d - Keep only last 24 hours
• 7d - Keep only last 7 days
• 2w - Keep only last 2 weeks
• 1m - Keep only last 30 days
• 3m - Keep only last 90 days
• 1y - Keep only last year

If not set, data is retained indefinitely.

You can optionally secure your API with a password using the API_PASSWORD environment variable:

• If API_PASSWORD is not set: API endpoints are accessible without authentication
• If API_PASSWORD is set: All alert and decision endpoints require Bearer token authentication

Example request with authentication:

curl -H "Authorization: Bearer your_password_here" \
  http://localhost:3000/api/v1/alerts

Security Note: This is a basic authentication mechanism intended for simple deployments. For production environments, consider implementing more robust authentication methods such as:

• Basic Auth with HTTPS
• OAuth2 / OpenID Connect
• External Identity Provider (Auth0, Keycloak, etc.)
• API Gateway with advanced authentication

The /api/v1/health endpoint is always accessible without authentication.

You can optionally configure rate limiting using the RATE_LIMIT environment variable:

• If RATE_LIMIT is not set: Rate limiting is disabled
• If RATE_LIMIT is set: API endpoints are rate-limited based on the configured value

Format: <requests>/<minutes>

Examples:

• 100/15 - 100 requests per 15 minutes (recommended default)
• 60/1 - 60 requests per minute
• 1000/60 - 1000 requests per hour
• 50/5 - 50 requests per 5 minutes

docker run -d \
  -e RATE_LIMIT=100/15 \
  ...

The generated decisions will expire after 24 hours, but if you want to remove the blocklists now you can do this:

1. Run cscli alerts list to get the list of alerts
2. Identify the alerts related with the blocklists. On the reason column, check the entries that begin with external/blocklist.
3. Run cscli alerts delete -s <reason> to remove all the alerts with that reason.

The API automatically syncs data from CrowdSec LAPI based on the configured SYNC_INTERVAL_SECONDS interval:

1. Connects to CrowdSec LAPI using Watcher credentials
2. Fetches new alerts from LAPI
3. Checks if alerts already exist (by alert ID)
4. Inserts only new alerts and their decisions
5. Overwrites existing alerts to keep track of updates
6. Cleans up old data based on DATA_RETENTION (if configured)
7. Tracks last successful sync timestamp for monitoring

The database is not a cache - it's a permanent incremental storage. Configure DATA_RETENTION to automatically remove old data and prevent the database from growing indefinitely.

This process is repeated for each blocklist added to the database.

1. Retrieves the list of blocked IPs or ranges of that list
2. Fetches the list of IPs that are already banned from CrowdSec
3. Compares the list of IPs to ban with the list of already banned IPs to avoid duplications
4. Creates the decisions list and pushes them to CrowdSec in batches
5. Repeats this process based on the BLOCKLISTS_REFRESH_TIME env variable

• Optional Authentication: Bearer token authentication with API_PASSWORD (optional)
• Rate Limiting: Configurable rate limiting with RATE_LIMIT (optional)
• Helmet: Security headers configured
• CORS: Cross-origin requests controlled
• Input Validation: express-validator on all query parameters
• Environment Variables: Sensitive data stored securely

See API.md for complete response schemas and examples.

This is a third party software that is not related in any way with the official CrowdSec software or with the CrowdSec team.

If you like the project and you want to contribute with the development, you can become a sponsor on GitHub, or you can donate using PayPal.

Created by JGeek00