ZZ / CrowdSec-Install.md

Crowdsec terms to know before installing, configuring, and monitoring CrowdSec. Core Architecture Concepts - `LAPI` (Local API) - The local coordinate center of CrowdSec. It accepts signals from parsers and informs bouncers who to block. The air traffic control tower running on your server. - `CAPI` (Central API) - CrowdSec’s global network. It collects anonymous attack metadata from all users and pushes down curated community blocklists. The global threat intelligence hub sharing notes with your server. - `Watcher` (Agent) - The background service engine that actively reads logs, extracts data, and tracks local server metrics. The security guard reading the facility log books. - `Bouncer` (Remediation) - Software plugins attached to firewalls or web servers (like Caddy, Nginx, or Cloudflare) that execute the actual blocking. The bouncer at the door physically stopping bad actors from entering. Configuration & Data Flow - `Acquisition` - (acquis.yaml) The configuration file where you declare exactly which log files CrowdSec should watch and what application type they belong to. A reading list telling the guard exactly which files to look at. - `Parser` - Code configurations that translate raw text strings from application logs into clean, structured data payloads. A translator converting messy paragraphs into clean spreadsheets. - `Scenario` - The specific behavioral heuristic rules or thresholds that define what constitutes an attack (e.g., 5 failed logins in 10 seconds). The security rulebook detailing when an activity becomes illegal. - `Decision` - The resulting mandate generated when a scenario is broken. It contains an IP address, an action (ban/captcha), and an expiration time. The arrest warrant or temporary ban order. - `Alert` - The formal administrative record created when a decision is triggered, containing the complete event context. The incident report filed for the archive. Essential `cscli` Monitoring Commands - `cscli metrics` - Shows real-time tables of log processing, API hits, parser efficiency, and active bouncer checking frequencies. Use this first to troubleshoot if logs are actually being read or if bouncers are active. - `cscli alerts list` - Displays a historical index of triggered attacks, matching scenarios, source IPs, and timestamps. Use this to audit what malicious activity has historically hit your system. - `cscli decisions list` - Shows the active, live ban list currently being enforced by your firewall or web bouncer. Use this to see who is currently blocked from your server right this second. - `cscli decisions add` - Allows you to manually ban an IP address, range, or username directly from the terminal. Use this to immediately block a known rogue IP yourself (--ip 1.2.3.4). - `cscli decisions delete` - Unbans a specific IP address or flush an active ban record completely. Use this if you accidentally ban yourself or need to whitelist a false positive. - `cscli bouncers list` - Lists all remediation plugins connected to your system, showing their API keys and last active check-in times. Use this to verify that tools like your Caddy bouncer are successfully communicating. Links - CrowdSec - Docker Install - https://docs.crowdsec.net/u/getting_started/installation/docker/ - CrowdSec - Open-source IDS/IPS, WAF and bot detection for Linux, Windows, Docker and Kubernetes, with a crowdsourced blocklist of malicious IPs. - https://github.com/crowdsecurity/crowdsec - CrowdSecurity/example-docker-compose - Example integration of CrowdSec in docker-compose - https://github.com/crowdsecurity/example-docker-compose