ZZ / CrowdSec-Install.md

CrowdSec terms to know before installing, configuring, and monitoring this Fail2Ban alternative service.

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 - https://docs.crowdsec.net/
• 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

docker compose exec crowdsec cscli scenarios list
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
SCENARIOS
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Name                                              📦 Status   Version  Local Path
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
crowdsecurity/apache_log4j2_cve-2021-44228        ✔  enabled  0.7      /etc/crowdsec/scenarios/apache_log4j2_cve-2021-44228.yaml
crowdsecurity/CVE-2017-9841                       ✔  enabled  0.2      /etc/crowdsec/scenarios/CVE-2017-9841.yaml
crowdsecurity/CVE-2019-18935                      ✔  enabled  0.2      /etc/crowdsec/scenarios/CVE-2019-18935.yaml
crowdsecurity/CVE-2022-26134                      ✔  enabled  0.4      /etc/crowdsec/scenarios/CVE-2022-26134.yaml
crowdsecurity/CVE-2022-35914                      ✔  enabled  0.2      /etc/crowdsec/scenarios/CVE-2022-35914.yaml
crowdsecurity/CVE-2022-37042                      ✔  enabled  0.2      /etc/crowdsec/scenarios/CVE-2022-37042.yaml
crowdsecurity/CVE-2022-40684                      ✔  enabled  0.3      /etc/crowdsec/scenarios/CVE-2022-40684.yaml
crowdsecurity/CVE-2022-41082                      ✔  enabled  0.4      /etc/crowdsec/scenarios/CVE-2022-41082.yaml
crowdsecurity/CVE-2022-41697                      ✔  enabled  0.2      /etc/crowdsec/scenarios/CVE-2022-41697.yaml
crowdsecurity/CVE-2022-42889                      ✔  enabled  0.3      /etc/crowdsec/scenarios/CVE-2022-42889.yaml
crowdsecurity/CVE-2022-44877                      ✔  enabled  0.4      /etc/crowdsec/scenarios/CVE-2022-44877.yaml
crowdsecurity/CVE-2022-46169                      ✔  enabled  0.3      /etc/crowdsec/scenarios/CVE-2022-46169.yaml
crowdsecurity/CVE-2023-22515                      ✔  enabled  0.1      /etc/crowdsec/scenarios/CVE-2023-22515.yaml
crowdsecurity/CVE-2023-22518                      ✔  enabled  0.3      /etc/crowdsec/scenarios/CVE-2023-22518.yaml
crowdsecurity/CVE-2023-49103                      ✔  enabled  0.3      /etc/crowdsec/scenarios/CVE-2023-49103.yaml
crowdsecurity/CVE-2024-0012                       ✔  enabled  0.1      /etc/crowdsec/scenarios/CVE-2024-0012.yaml
crowdsecurity/CVE-2024-38475                      ✔  enabled  0.1      /etc/crowdsec/scenarios/CVE-2024-38475.yaml
crowdsecurity/CVE-2024-9474                       ✔  enabled  0.1      /etc/crowdsec/scenarios/CVE-2024-9474.yaml
crowdsecurity/f5-big-ip-cve-2020-5902             ✔  enabled  0.3      /etc/crowdsec/scenarios/f5-big-ip-cve-2020-5902.yaml
crowdsecurity/fortinet-cve-2018-13379             ✔  enabled  0.4      /etc/crowdsec/scenarios/fortinet-cve-2018-13379.yaml
crowdsecurity/grafana-cve-2021-43798              ✔  enabled  0.3      /etc/crowdsec/scenarios/grafana-cve-2021-43798.yaml
crowdsecurity/http-admin-interface-probing        ✔  enabled  0.5      /etc/crowdsec/scenarios/http-admin-interface-probing.yaml
crowdsecurity/http-backdoors-attempts             ✔  enabled  0.7      /etc/crowdsec/scenarios/http-backdoors-attempts.yaml
crowdsecurity/http-bad-user-agent                 ✔  enabled  1.2      /etc/crowdsec/scenarios/http-bad-user-agent.yaml
crowdsecurity/http-crawl-non_statics              ✔  enabled  0.7      /etc/crowdsec/scenarios/http-crawl-non_statics.yaml
crowdsecurity/http-cve-2021-41773                 ✔  enabled  0.3      /etc/crowdsec/scenarios/http-cve-2021-41773.yaml
crowdsecurity/http-cve-2021-42013                 ✔  enabled  0.3      /etc/crowdsec/scenarios/http-cve-2021-42013.yaml
crowdsecurity/http-cve-probing                    ✔  enabled  0.6      /etc/crowdsec/scenarios/http-cve-probing.yaml
crowdsecurity/http-generic-bf                     ✔  enabled  0.9      /etc/crowdsec/scenarios/http-generic-bf.yaml
crowdsecurity/http-generic-test                   ✔  enabled  0.2      /etc/crowdsec/scenarios/http-generic-test.yaml
crowdsecurity/http-open-proxy                     ✔  enabled  0.5      /etc/crowdsec/scenarios/http-open-proxy.yaml
crowdsecurity/http-path-traversal-probing         ✔  enabled  0.4      /etc/crowdsec/scenarios/http-path-traversal-probing.yaml
crowdsecurity/http-probing                        ✔  enabled  0.4      /etc/crowdsec/scenarios/http-probing.yaml
crowdsecurity/http-sap-interface-probing          ✔  enabled  0.1      /etc/crowdsec/scenarios/http-sap-interface-probing.yaml
crowdsecurity/http-sensitive-files                ✔  enabled  0.4      /etc/crowdsec/scenarios/http-sensitive-files.yaml
crowdsecurity/http-sqli-probing                   ✔  enabled  0.4      /etc/crowdsec/scenarios/http-sqli-probing.yaml
crowdsecurity/http-technology-probing             ✔  enabled  0.1      /etc/crowdsec/scenarios/http-technology-probing.yaml
crowdsecurity/http-wordpress-scan                 ✔  enabled  0.4      /etc/crowdsec/scenarios/http-wordpress-scan.yaml
crowdsecurity/http-xss-probing                    ✔  enabled  0.4      /etc/crowdsec/scenarios/http-xss-probing.yaml
crowdsecurity/jira_cve-2021-26086                 ✔  enabled  0.4      /etc/crowdsec/scenarios/jira_cve-2021-26086.yaml
crowdsecurity/netgear_rce                         ✔  enabled  0.4      /etc/crowdsec/scenarios/netgear_rce.yaml
crowdsecurity/pulse-secure-sslvpn-cve-2019-11510  ✔  enabled  0.4      /etc/crowdsec/scenarios/pulse-secure-sslvpn-cve-2019-11510.yaml
crowdsecurity/spring4shell_cve-2022-22965         ✔  enabled  0.3      /etc/crowdsec/scenarios/spring4shell_cve-2022-22965.yaml
crowdsecurity/ssh-bf                              ✔  enabled  0.3      /etc/crowdsec/scenarios/ssh-bf.yaml
crowdsecurity/ssh-cve-2024-6387                   ✔  enabled  0.2      /etc/crowdsec/scenarios/ssh-cve-2024-6387.yaml
crowdsecurity/ssh-generic-test                    ✔  enabled  0.3      /etc/crowdsec/scenarios/ssh-generic-test.yaml
crowdsecurity/ssh-refused-conn                    ✔  enabled  0.1      /etc/crowdsec/scenarios/ssh-refused-conn.yaml
crowdsecurity/ssh-slow-bf                         ✔  enabled  0.4      /etc/crowdsec/scenarios/ssh-slow-bf.yaml
crowdsecurity/ssh-time-based-bf                   ✔  enabled  0.3      /etc/crowdsec/scenarios/ssh-time-based-bf.yaml
crowdsecurity/thinkphp-cve-2018-20062             ✔  enabled  0.7      /etc/crowdsec/scenarios/thinkphp-cve-2018-20062.yaml
crowdsecurity/vmware-cve-2022-22954               ✔  enabled  0.3      /etc/crowdsec/scenarios/vmware-cve-2022-22954.yaml
crowdsecurity/vmware-vcenter-vmsa-2021-0027       ✔  enabled  0.3      /etc/crowdsec/scenarios/vmware-vcenter-vmsa-2021-0027.yaml
ltsich/http-w00tw00t                              ✔  enabled  0.3      /etc/crowdsec/scenarios/http-w00tw00t.yaml
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────