CrowdSec Web UI

A self-hosted dashboard for CrowdSec: investigate alerts, manage decisions, monitor runtime metrics, and send notifications from one responsive UI.

Features

Screenshots

Quick Start

You need a running CrowdSec LAPI. Connect the Web UI using either watcher password authentication or agent mTLS.

1. Register the Web UI

Watcher password

openssl rand -hex 32
docker exec crowdsec cscli machines add crowdsec-web-ui --password 'replace-with-generated-password' -f /dev/null

# For local installations
sudo cscli machines add crowdsec-web-ui --password 'replace-with-generated-password' -f /dev/null

Replace replace-with-generated-password with the value printed by openssl.

[!IMPORTANT] Keep -f /dev/null. It registers the machine without overwriting the CrowdSec container's existing credentials file.

Agent mTLS

Configure LAPI TLS authentication and create a client certificate/key pair using the CrowdSec TLS authentication guide.

2. Start with Docker Compose

services:
  crowdsec-web-ui:
    image: ghcr.io/theduffman85/crowdsec-web-ui:latest
    container_name: crowdsec_web_ui
    ports:
      - "3000:3000"
    # For local CrowdSec instances
    # extra_hosts:
      # - "host.docker.internal:host-gateway"
    environment:
      CONFIG_INSTANCE_LAPI_URL: http://crowdsec:8080
      # For local CrowdSec instances
      # CONFIG_INSTANCE_LAPI_URL: http://host.docker.internal:8080
      CONFIG_INSTANCE_LAPI_AUTH_USERNAME: crowdsec-web-ui
      CONFIG_INSTANCE_LAPI_AUTH_PASSWORD: your-crowdsec-password
    volumes:
      - ./data:/app/data
    restart: unless-stopped

A ready-to-use docker-compose.yml is included. Add the generated password, make sure the Web UI can reach CrowdSec on the same Docker network, then start it.

docker compose up -d

Open http://localhost:3000 and create the initial administrator account.

Docker Run Alternative

docker pull ghcr.io/theduffman85/crowdsec-web-ui:latest
mkdir -p data
docker run -d \
  --name crowdsec_web_ui \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  -e CONFIG_INSTANCE_LAPI_URL=http://crowdsec:8080 \
  -e CONFIG_INSTANCE_LAPI_AUTH_USERNAME=crowdsec-web-ui \
  -e CONFIG_INSTANCE_LAPI_AUTH_PASSWORD=your-crowdsec-password \
  --network your_crowdsec_network \
  ghcr.io/theduffman85/crowdsec-web-ui:latest

Current images use Node.js and do not have the former Bun/AVX-specific x64 limitation.

mTLS Compose Alternative

services:
  crowdsec-web-ui:
    image: ghcr.io/theduffman85/crowdsec-web-ui:latest
    container_name: crowdsec_web_ui
    ports:
      - "3000:3000"
    environment:
      CONFIG_INSTANCE_LAPI_URL: https://crowdsec:8080
      CONFIG_INSTANCE_LAPI_AUTH_TYPE: mtls
      CONFIG_INSTANCE_LAPI_AUTH_CERT_FILE: /certs/agent.pem
      CONFIG_INSTANCE_LAPI_AUTH_KEY_FILE: /certs/agent-key.pem
      # CONFIG_INSTANCE_LAPI_TLS_CA_FILE: /certs/ca.pem
    volumes:
      - ./data:/app/data
      - /path/on/host/agent.pem:/certs/agent.pem:ro
      - /path/on/host/agent-key.pem:/certs/agent-key.pem:ro
      # - /path/on/host/ca.pem:/certs/ca.pem:ro
    restart: unless-stopped

Adjust the URL and certificate paths. Enable CONFIG_INSTANCE_LAPI_TLS_CA_FILE and its volume when LAPI uses a private CA.

[!CAUTION] Use HTTPS and a hardened reverse proxy for public deployments. Built-in authentication protects the UI and API, but TLS terminates outside the application. OIDC integrations include Authentik, Authelia, and Keycloak. Migrated installations that predate authentication remain unauthenticated until explicitly enabled.

Architecture

Configuration

Configuration files

Use CONFIG_FILE only to select another existing file. config.example.yaml contains the complete commented YAML reference.

Configuration lifecycle

Environment overrides

• Values are parsed as YAML and validated.
• Arrays use zero-based contiguous indexes: CONFIG_AUTH_OIDC_ADMIN_GROUPS_0, CONFIG_INSTANCES_0_ID, CONFIG_INSTANCES_0_METRICS_0_URL.
• Whole sections accept YAML through CONFIG_SERVER, CONFIG_STORAGE, CONFIG_UI, CONFIG_AUTH, CONFIG_NOTIFICATIONS, CONFIG_AUDIT, CONFIG_UPDATES, CONFIG_CROWDSEC, or CONFIG_INSTANCES.
• CONFIG_INSTANCE_* addresses instance 0: CONFIG_INSTANCE_NAME equals CONFIG_INSTANCES_0_NAME. Metrics index 0 may also be omitted: CONFIG_INSTANCES_0_METRICS_URL equals CONFIG_INSTANCES_0_METRICS_0_URL, and CONFIG_INSTANCE_METRICS_URL applies both shorthands. Do not set equivalent forms together.
• Secrets accept a direct string or exactly one env: NAME / file: PATH reference. Secret overrides also accept _FILE.
• Initial direct secret overrides are stored as environment references, never plaintext. Persisted secret references still require their environment variable.

Server, storage, UI, and updates

Date patterns require one day, month, and year token in any order: d/dd (day), m/mm (numeric month), mmm/mmmm (localized month name), and yy/yyyy (year). Punctuation and spaces are literal; wrap words in single quotes, for example d 'of' mmmm yyyy. Date patterns affect full dates and timestamps; compact chart labels keep their own display format. Set ui.timeFormat separately for a 12 or 24 hour clock.

Authentication

Notifications

Audit log

User actions that change CrowdSec state (adding decisions, deleting decisions and alerts, and per-IP cleanup) are recorded as single [audit] lines in the application log. Each entry is a JSON object with the timestamp, acting user and role, action, target (IP, range, or entity IDs), and outcome:

[audit] {"time":"2026-08-17T01:30:00.000Z","user":"tommy","role":"admin","action":"decision.add","ip":"192.0.2.10","type":"ban","duration":"4h","reason":"manual","instances":["CrowdSec"],"outcome":"success"}

Outcomes are success, partial, failure, or queued. Alert deletions handled by the persistent deletion queue are recorded as queued, because CrowdSec may complete them after the HTTP request returns. Multi-target actions include target_results or instance_results so successful, failed, and queued targets remain distinguishable.

Alert handling

Omitting crowdsec.alertFilters uses the standard non-CAPI feed. Setting any explicit filter field enables explicit filtering.

Global synchronization

Synchronization durations accept ms, s, m, h, or d, for example 500ms, 30s, 5m, or 7d. The lookback fields accept only m, h, or d.

Instances and LAPI

• <INDEX> is zero-based.
• ID defaults to the index; name defaults to Instance <INDEX>; authentication type is inferred from credentials.
• Inferred values appear as comments in initial YAML unless compatibility requires an explicit identity.
• Explicit IDs use lowercase letters, digits, _, and -. Keep them stable after importing data.

[!IMPORTANT] Configure exactly one credential shape:

• Password auth: set username and password
• mTLS auth: set certFile and keyFile

type is optional and inferred from these fields. Set it explicitly to none, password, or mtls when desired. Do not mix password and mTLS credentials.

Plaintext secrets are supported, but mounted secret files are recommended so credentials do not end up in source control, backups, or configuration-management logs.

Metrics endpoints

• <INDEX> selects the instance; zero-based <METRIC_INDEX> selects its endpoint.
• Endpoint ID defaults to <METRIC_INDEX> and name to Metrics <METRIC_INDEX>.
• Endpoint icons are optional short text or emoji values and appear in the metrics source selector.
• Inferred values appear as comments in initial YAML.

Per-instance synchronization overrides

Every field inherits its corresponding global value when omitted.

Multiple CrowdSec instances

Use zero-based CONFIG_INSTANCES_<INDEX>_* overrides to define each instance. Indexes must be contiguous, starting at 0.

services:
  crowdsec-web-ui:
    image: ghcr.io/theduffman85/crowdsec-web-ui:latest
    environment:
      CONFIG_INSTANCES_0_ID: eu-prod
      CONFIG_INSTANCES_0_NAME: EU Production
      CONFIG_INSTANCES_0_LAPI_URL: http://crowdsec-eu:8080
      CONFIG_INSTANCES_0_LAPI_AUTH_USERNAME: crowdsec-web-ui
      CONFIG_INSTANCES_0_LAPI_AUTH_PASSWORD_FILE: /run/secrets/eu-lapi-password
      CONFIG_INSTANCES_0_METRICS_0_ID: lapi
      CONFIG_INSTANCES_0_METRICS_0_NAME: EU LAPI
      CONFIG_INSTANCES_0_METRICS_0_URL: http://crowdsec-eu:6060/metrics

      CONFIG_INSTANCES_1_ID: us-prod
      CONFIG_INSTANCES_1_NAME: US Production
      CONFIG_INSTANCES_1_LAPI_URL: http://crowdsec-us:8080
      CONFIG_INSTANCES_1_LAPI_AUTH_USERNAME: crowdsec-web-ui
      CONFIG_INSTANCES_1_LAPI_AUTH_PASSWORD_FILE: /run/secrets/us-lapi-password

      # For mTLS, replace instance 1's URL and password credentials above with:
      # CONFIG_INSTANCES_1_LAPI_URL: https://crowdsec-us:8080
      # CONFIG_INSTANCES_1_LAPI_AUTH_TYPE: mtls
      # CONFIG_INSTANCES_1_LAPI_AUTH_CERT_FILE: /certs/us-client-cert.pem
      # CONFIG_INSTANCES_1_LAPI_AUTH_KEY_FILE: /run/secrets/us-client-key.pem
      # CONFIG_INSTANCES_1_LAPI_TLS_CA_FILE: /certs/us-ca.pem
    volumes:
      - ./secrets/eu-lapi-password:/run/secrets/eu-lapi-password:ro
      - ./secrets/us-lapi-password:/run/secrets/us-lapi-password:ro
      # Mount these files when using the commented mTLS configuration:
      # - ./certs/us-client-cert.pem:/certs/us-client-cert.pem:ro
      # - ./secrets/us-client-key.pem:/run/secrets/us-client-key.pem:ro
      # - ./certs/us-ca.pem:/certs/us-ca.pem:ro

• Use indexed variables for every instance in a multi-instance setup; reserve the CONFIG_INSTANCE_* shorthand for single-instance deployments.
• Each instance needs a stable ID, unique display name, LAPI URL, and one authentication method.
• Add metrics endpoints with CONFIG_INSTANCES_<INDEX>_METRICS_<METRIC_INDEX>_*.
• Mount password files read-only. When using the optional mTLS configuration, mount its private keys and certificates read-only as well, then restart the container.

YAML alternative

Add entries to the top-level instances array. Each entry defines one LAPI connection and zero or more metrics endpoints.

instances:
  - id: eu-prod
    name: EU Production
    icon: 🇪🇺
    lapi:
      url: http://crowdsec-eu:8080
      auth:
        type: password
        username: crowdsec-web-ui
        password:
          file: /run/secrets/eu-lapi-password

    metrics:
      - id: lapi
        name: EU LAPI
        icon: 🧠
        url: http://crowdsec-eu:6060/metrics
        auth:
          type: bearer
          token:
            file: /run/secrets/eu-metrics-token

      - id: edge-engine
        name: EU Edge Engine
        icon: 🛡️
        url: http://crowdsec-edge:6060/metrics

    sync:
      requestTimeout: 45s
      alertSyncChunk: 6h

  - id: us-prod
    name: US Production
    icon: 🇺🇸
    lapi:
      url: http://crowdsec-us:8080
      auth:
        type: password
        username: crowdsec-web-ui
        password:
          file: /run/secrets/us-lapi-password
      # For mTLS, replace url and auth above with:
      # url: https://crowdsec-us:8080
      # auth:
      #   type: mtls
      #   certFile: /run/secrets/us-client-cert
      #   keyFile: /run/secrets/us-client-key
      # tls:
      #   caFile: /run/secrets/us-ca

Configuration rules

• Instance and endpoint IDs are unique, URL-safe, and immutable database identities. They are 1–63 characters long, start with a lowercase letter or digit, use only lowercase letters, digits, _, or -, and must never be reused for another LAPI.
• Display names are unique but editable. icon accepts up to eight Unicode code points of text or emoji without control characters; omitted icons use colored squares and Combined uses a grid.
• Password secrets accept a direct value or exactly one env/file source. mTLS requires both certFile and keyFile; tls.caFile controls server trust.
• Metrics authentication supports none, basic, and bearer; metrics TLS supports caFile plus an optional complete client certificate/key pair.
• Embedded URL credentials, URL fragments, ambiguous secret sources, partial certificate pairs, unreadable files, and TLS verification bypasses fail validation. LAPI base URLs also reject paths.
• Prefer mounted secret files. Restart after configuration, certificate, or secret changes.

Multi-instance behavior

Authentication

Authentication covers the browser UI and protected APIs; /api/health remains public.

Upgraded installations

Enable authentication explicitly on installations migrated from older releases.

auth:
  enabled: true

Local accounts

• Password changes and passkey registration/removal from Settings.
• Optional TOTP enrollment through a QR code, mobile setup link, or manual key.
• An enrolled TOTP seed overrides the optional base32 auth.totpSeed fallback.
• Administrators can disable password login.

OIDC

Configure OIDC in Settings or YAML.

auth:
  enabled: true
  oidc:
    issuerUrl: https://idp.example.com/application/o/crowdsec-web-ui/
    clientId: crowdsec-web-ui
    clientSecret:
      file: /run/secrets/oidc_client_secret
    scope: openid profile email
    groupsClaim: groups
    adminGroups: [crowdsec-admins, secops]
    readOnlyGroups: [crowdsec-viewers]
    unmatchedRole: deny

Callback URL

Register this callback URI with the identity provider.

https://<crowdsec-web-ui-host>/api/auth/oidc/callback

Requirements and roles

• The callback must exactly match the public scheme, host, port, and base path. For basePath: /crowdsec, use https://<host>/crowdsec/api/auth/oidc/callback.
• Reverse proxies must forward Host or X-Forwarded-Host and X-Forwarded-Proto.
• Saved Settings override YAML. Scopes must include openid; add provider-specific scopes such as groups only when required.
• Admin-group matches have full access; read-only-group matches can view data and keep permitted preferences; unmatched users follow auth.oidc.unmatchedRole (deny by default).
• Set an unmatched fallback role only when every user who can sign in should receive it.
• ui.readOnly: true overrides all roles for the deployment. It blocks CrowdSec writes, refresh changes, notification destination/rule management, test sends, and notification deletion. Language changes and marking notifications read remain available. This is not per-user RBAC.
• Identities use stable issuer and subject claims. Username collisions with local accounts remain separate.
• Sessions have a 24-hour absolute lifetime. OIDC-only users cannot add local passkeys; password-backed local accounts retain passkey support.
• Existing OIDC rows migrate on their next successful SSO login.

Deployment and Security

Trusted IPs for Alert Deletion

[!IMPORTANT] CrowdSec only permits alert deletion when the request comes from loopback or an address listed in api.server.trusted_ips. Registering the Web UI as a CrowdSec machine authenticates it, but does not grant this IP-based permission.

When the Web UI runs in Docker, add the Web UI container's source IP or, preferably, its Docker network CIDR to CrowdSec's /etc/crowdsec/config.yaml. This is not the browser's IP or the Docker host's public IP. Without this entry, decision operations can still work while alert deletion fails with 403 Forbidden.

api:
  server:
    trusted_ips:
      - 127.0.0.1
      - ::1
      - 172.16.0.0/12  # Docker default bridge network

Use the narrowest CIDR that contains the Web UI container and LAPI network. Container IPs can change when containers are recreated, so the Docker network CIDR is usually more reliable than one container IP. Restart CrowdSec after updating the file. The current CrowdSec container does not provide a TRUSTED_IPS environment override. See the CrowdSec configuration reference.

Local or Custom LAPI Certificate

A self-signed certificate or internal CA may produce the following error.

Login failed: unable to get local issuer certificate

Mount the CA certificate and configure it for the LAPI instance.

services:
  crowdsec-web-ui:
    image: ghcr.io/theduffman85/crowdsec-web-ui:latest
    container_name: crowdsec_web_ui
    ports:
      - "3000:3000"
    environment:
      CONFIG_INSTANCE_LAPI_URL: https://crowdsec:8080
      CONFIG_INSTANCE_LAPI_AUTH_USERNAME: crowdsec-web-ui
      CONFIG_INSTANCE_LAPI_AUTH_PASSWORD_FILE: /run/secrets/crowdsec_password
      CONFIG_INSTANCE_LAPI_TLS_CA_FILE: /certs/root_ca.crt
    secrets:
      - crowdsec_password
    volumes:
      - ./data:/app/data
      - /path/on/host/root_ca.crt:/certs/root_ca.crt:ro
    restart: unless-stopped

secrets:
  crowdsec_password:
    file: ./secrets/crowdsec_password.txt

Keep the CA mount read-only. CONFIG_INSTANCE_LAPI_TLS_CA_FILE maps to instances[0].lapi.tls.caFile; no image rebuild is needed.

HTTPS Reverse Proxy

CrowdSec Web UI listens for HTTP on port 3000 and does not obtain or terminate TLS certificates itself. Put a reverse proxy in front of it for HTTPS deployments and keep port 3000 private to the proxy.

HTTPS is required for passkeys because browsers expose WebAuthn only in a secure context. http://localhost is suitable for local testing, but a remote deployment needs a stable hostname and a certificate trusted by the browser. Passkeys registered for one hostname cannot be used from a different hostname.

The proxy must preserve Host (or set X-Forwarded-Host) and set X-Forwarded-Proto to the original scheme. The application uses these headers for WebAuthn origins, secure session cookies, OIDC callback URLs, and mutation-origin checks.

Traefik example

This minimal example assumes Traefik already has a websecure entrypoint, a Let's Encrypt resolver named letsencrypt, and an external Docker network named proxy. Add the labels and proxy network to the existing Web UI service, replacing the hostname and CrowdSec settings.

services:
  crowdsec-web-ui:
    image: ghcr.io/theduffman85/crowdsec-web-ui:latest
    expose:
      - "3000"
    environment:
      CONFIG_INSTANCE_LAPI_URL: http://crowdsec:8080
      CONFIG_INSTANCE_LAPI_AUTH_USERNAME: crowdsec-web-ui
      CONFIG_INSTANCE_LAPI_AUTH_PASSWORD: your-crowdsec-password
      # For https://crowdsec.example.com/crowdsec/:
      # CONFIG_SERVER_BASE_PATH: /crowdsec
    volumes:
      - ./data:/app/data
    labels:
      - traefik.enable=true
      - traefik.docker.network=proxy
      # For /crowdsec/, append: && PathPrefix(`/crowdsec`)
      - 'traefik.http.routers.crowdsec-web-ui.rule=Host(`crowdsec.example.com`)'
      - traefik.http.routers.crowdsec-web-ui.entrypoints=websecure
      - traefik.http.routers.crowdsec-web-ui.tls.certresolver=letsencrypt
      - traefik.http.services.crowdsec-web-ui.loadbalancer.server.port=3000
    networks:
      - proxy
      - crowdsec
    restart: unless-stopped

networks:
  proxy:
    external: true
  crowdsec:
    external: true
    name: your_crowdsec_network

Traefik supplies the forwarded headers and WebSocket upgrade handling automatically. See the Traefik ACME documentation if the letsencrypt resolver is not configured yet.

Nginx example

This equivalent example assumes Nginx already terminates HTTPS and the Web UI port is published only on loopback, for example 127.0.0.1:3000:3000.

# For https://crowdsec.example.com/crowdsec/, set
# CONFIG_SERVER_BASE_PATH=/crowdsec and replace both `/` paths below
# with `/crowdsec/`.
location / {
    proxy_pass http://localhost:3000/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Proxy requirements

• The base path starts with / and has no trailing slash.
• / redirects to it; APIs, assets, and navigation follow it automatically.
• With Traefik on a shared hostname, add CONFIG_SERVER_BASE_PATH: /crowdsec and use a router rule such as Host(`example.com`) && PathPrefix(`/crowdsec`). Do not configure StripPrefix; the application expects to receive the base path.
• The backend checks browser mutation origins, applies a Content Security Policy, limits API bodies to 1 MiB, and marks API responses private, no-store.
• Command-line and service clients without browser Origin and Sec-Fetch-Site headers remain compatible.
• Configure HSTS at the TLS-terminating proxy; the application does not emit it.

Health Check

The public endpoint is GET /api/health. Startup does not wait for LAPI: bootstrap retries in the background, so the container can become healthy before synchronization completes.

curl http://localhost:3000/api/health
# {"status":"ok"}

The built-in check runs every 30 seconds with a five-second timeout, a 10-second start period, and three retries.

docker inspect --format='{{.State.Health.Status}}' crowdsec_web_ui

server.basePath does not affect the internal check at localhost:3000/api/health. If server.port changes, update the health-check command and port mapping.

Runtime Behavior

Prometheus Metrics Page

• Reads a configured raw CrowdSec Prometheus endpoint. The Web UI does not configure one by default; CrowdSec normally exposes its local scrape at http://127.0.0.1:6060/metrics.
• Shows remediation-component and log-processor LAPI activity, AppSec, parsers and datasources, scenarios, LAPI latency, parsing time, and whitelist hits. Log-processor activity uses POST /v1/alerts; CrowdSec builds that expose an exact last-heartbeat timestamp also provide the processor health badge.
• When the current instance scope has multiple endpoints, Combined is selected by default. Headline totals sum successful sources, detailed rows retain their instance and endpoint, and unavailable endpoints produce a partial-data warning instead of hiding healthy sources.
• Combined counters are cumulative across processes that may have different start times. Configuring the same Prometheus scrape more than once counts it more than once; endpoint roles and automatic duplicate detection are not applied.
• Alert and decision analytics remain on the main dashboard.

Enable full metrics in CrowdSec's /etc/crowdsec/config.yaml.

prometheus:
  enabled: true
  level: full
  listen_addr: 127.0.0.1
  listen_port: 6060

For separate containers, bind listen_addr: 0.0.0.0 on a trusted network, then configure the matching Web UI instance.

environment:
  CONFIG_INSTANCE_METRICS_URL: http://crowdsec:6060/metrics

AppSec and latency sections appear only when CrowdSec emits those metrics. Time-window-only rate()/increase() metrics are intentionally omitted. See the CrowdSec Prometheus documentation.

Display Preferences

• crowdsec.simulationsEnabled: true fetches non-remediating simulation alerts/decisions and shows badges, filters, and dashboard counts. Default: false.
• Alerts and Decisions column layouts persist per browser profile in local storage.
• ID, Machine, and Origin are hidden by default. Machine prefers machine_alias, then machine_id; multiple alert decision origins display as Mixed.
• Hidden columns remain searchable through fields such as id:, machine:, and origin:.

Quick Filters

Dashboard, Alerts, and Decisions share one count-aware Quick Filters drawer. Its trigger shows the number of active selections, and the clear control in the drawer header resets all stored quick filters.

Instance and machine options use stable IDs for filtering while displaying their configured names or aliases. Country, instance, and machine searches match the displayed label as well as the stored value. Alerts with several origins or targets contribute to each distinct facet option instead of exposing a combined bucket.

• Filter selections, date range, and simulation mode persist in local storage for the current browser profile and are restored when navigating between the three pages.
• Changing a structured search field updates the matching quick-filter selection, and changing a quick filter updates the structured search. A field supplied explicitly in a page URL takes precedence over its stored value; stored values fill fields that are absent.
• Dashboard top countries, scenarios, AS numbers, targets, the world map, and the Activity History range update the same shared state. Changes made in the drawer update those widgets in return.
• Filtered Dashboard alert and active-decision counts use the same indexed predicates as the Alerts and Decisions lists. The alert card links with the alert-compatible query, while the decision card links with the decision-compatible query.
• The drawer follows each table's configured column order. Filters for hidden columns are grouped under Hidden columns.
• Page-only filters remain visible under Unavailable when another page cannot apply them. Alerts lists Action, Status, and Alert there; Decisions lists Decision; Dashboard lists all four. Their stored selections are preserved for the page that supports them and can be cleared from any drawer.
• Facet selections use exact equality. Selecting the target tausend.me generates target=tausend.me and does not include bw.tausend.me. Manually entering target:tausend.me remains a broader contains search.
• Each facet reports counts after the other active filters have been applied. Use the facet search control to find values beyond the initially loaded list.

Dashboard applies the shared fields Country, Scenario, Kind, AS, IP / Range, Target, ID, Instance, Region, City, Machine, and Origin. Filters that depend on decision-only or alert-list-only data are retained in Unavailable instead of being silently discarded.

Active decisions are deduplicated by instance, value, and simulation mode. When filters exclude the globally preferred decision, the best matching decision is promoted so enabling Hide duplicates cannot make an otherwise matching duplicate group disappear.

Saved and Recent Filters

Use the bookmark button beside search on Dashboard, Alerts, or Decisions to save the current valid query under a name. The menu lets you apply, rename, and delete saved filters, reuse the five most recently used queries, or clear recent history. Queries are shared across these pages; Apply is disabled when a query is not valid for the current page. Applying one changes the search query while keeping the selected instance and other page settings.

Saved filters and recent history are stored on the server for the signed-in user, so they are available on other devices. Read-only users can manage their own filters. If authentication is disabled, everyone using the installation shares one list. Valid nonempty queries enter recent history after a brief pause, including searches opened from bookmarked URLs. Quick Filter queries enter recent history only after the Quick Filters drawer closes.

Search Syntax

The : operator performs a case-insensitive contains match, while = matches the complete field value. Quick Filter selections use =. Date fields support <, >, <=, >=, and =>. A bare field name is free text unless followed by :. Quote literal AND, OR, or NOT. The search Info button lists page-specific fields and examples.

Examples

Alert Source Filtering

Limit the local cache by origin when CrowdSec ingests automation, blocklists, or community feeds.

crowdsec:
  alertFilters:
    includeOrigins: [crowdsec, cscli-import]
    excludeOrigins: [cscli]
    includeCapi: true
    includeOriginEmpty: true
    excludeOriginEmpty: false

Behavior

• No explicit filters fetches the normal non-CAPI/non-lists feed.
• Includes are pushed upstream where possible. Generic excludes and empty-origin handling run locally because LAPI lacks those filters.
• includeCapi: true adds CAPI to the default feed; includeOrigins: [CAPI] selects only CAPI.
• If any origin is excluded, the whole alert is dropped.
• Origins prefer associated decisions, then blocklist/list source scopes for alerts without decisions.
• includeOriginEmpty retains origin-less alerts alongside includes; excludeOriginEmpty removes them.
• Because Decisions is built from synchronized alerts, filters also change which imported decisions appear.

Examples

Notifications

Rules run against locally cached CrowdSec data, create in-app notifications, record delivery status, and optionally deliver outbound messages.

Rules

Every rule has a name, severity (info, warning, critical), incident deduplication, and destination channels. Alert rules filter scenario, target, and simulation state; the scenario filter can include or exclude matching names. IP Ban and New Alert/Decision also accept exact IP/CIDR filters. Window Minutes sets the rolling lookback for each rule evaluation; Alert Spike also compares it with the preceding period of equal length. It does not set how often rules are evaluated.

Multi-instance behavior

Instance-backed titles and metadata identify the contributing instance or instances.

[!NOTE] The Recent CVE rule queries the NVD API to determine when a CVE was published. If outbound access to services.nvd.nist.gov is blocked, recent-CVE notifications may be skipped.

The CrowdSec Update rule requires a configured Prometheus endpoint with a cs_info version metric and outbound access to the CrowdSec GitHub release API. It checks the latest stable release and notifies once per outdated endpoint and target version.

Destinations

Destinations are independently enabled and reusable across rules. Send Test validates saved settings immediately; results are stored as delivered or failed.

Payloads and security

• MQTT JSON contains title, message, severity, metadata, sent_at, channel_id, channel_name, channel_type, rule_id, rule_name, and rule_type. Tests use rule_id=test, rule_name=Test notification, and rule_type=test.
• Webhook templates expose dotted event.* fields for title, message, severity, metadata, sent_at, channel_name, rule_id, rule_name, and rule_type. Each has a *Json variant; nullable rule fields also have OrUnknown and OrUnknownJson aliases.
• Failed webhooks store HTTP status and a truncated response. notifications.debugPayloads: true also logs a truncated rendered body with sensitive form fields redacted; enable it only while troubleshooting.
• Destination secrets are masked and encrypted by notifications.secretKey, or an auto-generated key stored in application metadata.
• notifications.allowPrivateAddresses: false blocks private, loopback, and link-local destinations; default: true.
• Telegram, Home Assistant discovery/state, and inbound MQTT commands are not supported.

Kubernetes

A Helm chart for CrowdSec Web UI is maintained by zekker6.

Persistence and Alert History

SQLite data lives under /app/data. Mount the directory—not only crowdsec.db—because WAL mode also uses crowdsec.db-wal and crowdsec.db-shm.

volumes:
  - ./data:/app/data

• History survives restarts, merges with new LAPI data, and expires after crowdsec.sync.lookback (default: seven days).
• Initial imports and reconciliation retry in smaller windows after timeouts.
• During LAPI outages, the application serves its available cache and retries in the background; partial imports are marked.

Use POST /api/cache/clear for a full cache reset. Synchronization internals are documented in DEVELOPMENT.md.

SQLite database maintenance

New databases use SQLite incremental auto-vacuum by default. Existing databases keep their current format to avoid a potentially long, disk-intensive migration. If startup reports reclaimable space, migrate during a maintenance window:

1. Back up the entire data directory, including crowdsec.db, crowdsec.db-wal, and crowdsec.db-shm when present.

2. Stop CrowdSec Web UI and confirm that no process is using the database. Ensure free disk space is at least the current database size.

3. Open crowdsec.db with SQLite and run:

   PRAGMA wal_checkpoint(TRUNCATE);
   PRAGMA auto_vacuum = INCREMENTAL;
   VACUUM;
   

4. Close SQLite, restart the app, and verify the migration with PRAGMA auto_vacuum;. A result of 2 means incremental auto-vacuum is enabled.

VACUUM rewrites the database and may take significant time for large installations. Do not interrupt it. The application never runs this migration automatically.

Documentation

Star History

Related Projects

Linux Update Dashboard A self-hosted dashboard for checking and applying Linux package updates across multiple servers.