Skip to main content
Version: Next

Concepts

Global overview​

This page defines the core CrowdSec concepts and how the components interact. It focuses on how detection is done, where data is stored, and where remediation is enforced.

Security Engine​

The Security Engine is the CrowdSec software you install (an IDS: Intrusion Detection System). It detects threats and produces alerts. The Local API can turn alerts into decisions using profiles. Threat prevention (blocking) is enforced by Remediation Components (bouncers). Internally, the Security Engine is made of two main components: the Log Processor (detection) and the Local API (storage and decision distribution).

A Security Engine can run standalone (Log Processor + Local API on the same host) or in a distributed setup (multiple Log Processors sending alerts to a shared Local API). This lets you adapt CrowdSec to your infrastructure and constraints.

In a distributed setup, detection content (collections/parsers/scenarios) runs on the Log Processor machines, while the Local API focuses on storing data and serving decisions. See the multi-server setup guide for a concrete deployment pattern.

Log Processor (LP)​

The Log Processor is the part of the Security Engine in charge of detecting malicious behavior based on your logs and HTTP traffic.

The Log Processor (abbreviated as LP) detects malicious behavior in two main ways:

When a scenario or an AppSec rule is triggered, the Log Processor sends an alert to the LAPI.

Related documentation:

Local API (LAPI)​

The Local API is the part of the Security Engine that stores alerts/decisions and acts as the middleman between Log Processors, Remediation Components, and the Central API.

The Local API (abbreviated as LAPI) has several roles:

  • Receive alerts from Log Processors and (optionally) create decisions based on configured profiles.
  • Expose decisions to Remediation Components so they can enforce them.
  • Interact with the Central API to share signals and receive community blocklists.

For implementation details, see:

Glossary​

Quick definitions of terms used throughout the documentation and in tools like cscli:

  • Collections: bundles of parsers, scenarios, and other items installed together. See Collections and Hub management.
  • Scenarios: behavior detections evaluated by the Log Processor. See Scenarios.
  • AppSec rules: WAF rules evaluated by the AppSec component. See AppSec.
  • Alerts: records created when a scenario/AppSec rule triggers; stored in the Local API. See cscli alerts.
  • Decisions: remediation instructions (for example ban, sometimes other types depending on your setup) created by Local API profiles or manually via cscli; consumed by bouncers. See cscli decisions and Bouncers API.

Remediation Components (Bouncers)​

The Remediation Components (also called Bouncers) are external components in charge of enforcing decisions.

Remediation Components rely on the Local API to receive decisions about malicious IPs to be blocked (or other remediation types such as CAPTCHA, supported by some bouncers).
Note that they also support CrowdSec's Blocklist as a Service.

Those decisions can come from detections made by the LP or from blocklists.

Remediation Components leverage existing parts of your infrastructure to block malicious IPs where it matters most (firewall, reverse proxy, web server, ...). You can find them on our Remediation Components Hub.

Central API (CAPI)​

The Central API (CAPI) serves as the gateway for network participants to connect and communicate with CrowdSec's network.

The Central API (abbreviated as CAPI) receives attack signals from participating Security Engines and signal partners. It then redistributes curated community decisions (the Community Blocklist).

The Central API is also at the heart of CrowdSec centralized blocklist services.

For details about what data is sent (and when), see the Central API introduction. If you want to disable sharing to the Central API, see how to disable the Central API.

Console​

The CrowdSec Console is a web-based interface for reporting, alerting, and management across your CrowdSec products (from your fleet of Security Engines to CTI-related actions).

The Console allows you to:

To connect an instance to the Console, see Console enrollment and the cscli command reference: cscli console enroll.

Example: from a log line to a block​

This is a typical flow for a log-based scenario (for example, SSH brute-force):

  1. Install detection content: you typically install a collection from the Hub (parsers + scenarios) using cscli (see Hub management).
  2. Acquire: the Log Processor reads your service logs via an acquisition configuration (for example, a file tail on /var/log/auth.log).
  3. Parse + enrich: parsers extract fields (source IP, service, status, ...) and enrichers add context (GeoIP/ASN, ...).
  4. Detect: a scenario correlates events over time (for example, many failed logins from the same IP) and triggers an alert.
  5. Store + decide: the Log Processor sends the alert to the LAPI. The LAPI applies your profiles to create a decision (for example, ban for a given duration).
  6. Enforce: a Remediation Component (bouncer) pulls decisions from the LAPI and enforces them where it matters (firewall, reverse proxy, web server, ...).