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.
• CONFIG_AUTH_OIDC_CLIENT_ID parses YAML scalars as strings, preserving numeric identifiers and leading zeros. For example, CONFIG_AUTH_OIDC_CLIENT_ID=123456789012345678901 keeps every digit; YAML-quoted values also work. In config.yaml or whole-section CONFIG_AUTH overrides, quote numeric client IDs (for example clientId: "123456789012345678901").
• Arrays use zero-based contiguous indexes: CONFIG_AUTH_OIDC_ADMIN_GROUPS_0, CONFIG_INSTANCES_0_ID, CONFIG_INSTANCES_0_METRICS_0_URL.
• OIDC role groups require YAML arrays (for example CONFIG_AUTH_OIDC_ADMIN_GROUPS='[crowdsec_admins]' and CONFIG_AUTH_OIDC_READ_ONLY_GROUPS='[crowdsec_users]') or indexed variables, even for a single group.
• 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.

Settings managed by configuration

Some values can be set either in Settings or in the application config: the refresh interval, manual refresh, password login, and all OIDC fields. A value set in config.yaml or through its CONFIG_* variable takes precedence and is locked in Settings, marked with a lock icon whose tooltip names the CONFIG_* variable or config path that sets it. Leave it unset to manage it in Settings. Manual decision scenarios from the config are always offered and can't be removed in Settings, but more can be added there.

To manage a locked value in Settings again, remove it from both the environment and config.yaml, then restart; the last value saved in Settings applies again. CONFIG_* values are written into config.yaml when the file is first created, and on every start with CONFIG_PERSIST_OVERRIDES: "true", so removing the variable alone may not unlock the setting.

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) and user management changes (user.create, user.update, user.password-reset, user.mfa-reset, user.delete) 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","scenario":"manual/web-ui","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.

Manual decisions

The Add Decision form always offers manual/web-ui and selects it by default. With no other scenarios available, the scenario field is hidden and manual/web-ui is used; additional scenarios turn it into a dropdown. Admins can also add and remove scenarios under Settings → General → Manual decisions; those are stored in the database, offered for every instance on top of the configured list, and take effect without a restart. Scenarios from config.yaml or CONFIG_ variables are shown there as read-only. When All instances targets instances with different lists, only manual/web-ui is used and the field is hidden. These lists only shape the form: POST /api/decisions accepts any author/name scenario. If crowdsec.alertFilters.legacy.extraScenarios is used to show manual decisions, add the configured scenarios there too.

CrowdSec LAPI does not check allowlists for decisions sent with an alert, which is how the Web UI adds them. Like cscli decisions add, the Web UI therefore checks the target instances' allowlists first and refuses an allowlisted IP or range until Bypass allowlist is confirmed. Instances whose LAPI predates allowlists (CrowdSec 1.6.5) or cannot be checked do not block the decision.

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 under Settings → Profile. A new password must differ from the current one.
• Optional TOTP enrollment through a QR code, mobile setup link, or manual key.
• An enrolled TOTP seed overrides the optional base32 auth.totpSeed fallback.
• Enabling or disabling TOTP signs out the account's other sessions. Disabling it requires a current authenticator code.
• Local sessions last up to 30 days. Logging out revokes the session on the server, so a copied session cookie stops working too.
• Administrators can disable password login under Settings → Authentication, or pin it from deployment config:

auth:
  passwordLogin:
    enabled: false # CONFIG_AUTH_PASSWORD_LOGIN_ENABLED=false

When auth.passwordLogin.enabled is set, it overrides the Settings value and the toggle is shown as managed by configuration. Removing it restores the last value saved in Settings. To avoid a lockout, false only takes effect while OIDC or an administrator's passkey is configured; otherwise password login stays enabled and a warning is logged. Password hashes are kept, so setting enabled: true and restarting restores password login if the identity provider is unreachable.

Personal settings

Every user has a Settings → Profile tab with their language, font, and Metrics and Allowlists sidebar visibility, plus their own password, TOTP, and passkeys. The display preferences are saved for the account and follow the user to other browsers; without dashboard authentication they apply to the whole instance. Profile remains editable in read-only mode, including when dashboard authentication is disabled. Read-only users only see Profile, because they cannot change anything else; General, Authentication (password login and OIDC), Users, and Branding are shown to administrators.

Users

Administrators manage accounts under Settings → Users:

• Create local users with a username, an initial password, and the admin or read-only role. Read-only users have the same permissions as OIDC users in a read-only group.
• Change a local user's role, or disable and re-enable the account. Disabling ends the user's sessions.
• Reset a local user's password. By default, the user must choose a new password at the next password sign-in before using anything else; new users start the same way.
• Reset a local user's TOTP and passkeys, for example after a lost phone. The user's sessions end and both can be set up again.
• Delete users. OIDC users are listed after their first sign-in; their role comes from the identity provider, so they can only be deleted. A deleted OIDC user is added again on the next sign-in if the identity provider still allows it.

Administrators cannot change, disable, or delete their own account there, and the last active administrator cannot be demoted, disabled, or deleted. While passkeys are the only sign-in method (password login disabled, no OIDC), changes that would leave no enabled administrator with a passkey are rejected. A user with a pending password change cannot register passkeys or set up TOTP until the password is changed. Changes are written to the audit log.

OIDC

Configure OIDC in Settings or YAML. Fields set in YAML are locked in Settings; see Settings managed by configuration.

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
    endSession: true
    backchannelLogout: true
    autoLogin: false

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. Personal preferences under Profile (language, font, and Metrics and Allowlists sidebar visibility) 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.

Logout

With auth.oidc.endSession: true or the matching Settings toggle, logging out of the dashboard also ends the SSO user's session at the identity provider (OpenID Connect RP-initiated logout), so the next SSO sign-in asks for credentials again. It is off by default because the provider may reject the redirect until the URI below is registered. Installations that already used OIDC when upgrading keep the earlier default of on unless the configuration or Settings sets a value. This requires the provider to advertise an end_session_endpoint; otherwise only the dashboard session is cleared. Register this post-logout redirect URI with the identity provider:

https://<crowdsec-web-ui-host>/login

Include the base path when one is configured, for example https://<host>/crowdsec/login. Leave it off to only clear the dashboard session.

Back-channel logout

To end dashboard sessions when a user signs out at the identity provider, enable auth.oidc.backchannelLogout or the matching Settings toggle and register this back-channel logout URI with the provider (OpenID Connect Back-Channel Logout):

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

Include the base path when one is configured. While the setting is off, logout notifications are rejected. The provider must be able to reach the dashboard directly, and logout tokens must be signed with a key from the provider's JWKS or, for HMAC tokens, with the client secret. A logout token with a session ID (sid) ends only the sessions from that provider sign-in, even when it also names the user (sub); if it names the user, it also ends that user's sessions that carry no sid, such as sessions from before the upgrade. Without sid, it ends all dashboard sessions for the named user. Repeated notifications with the same issuer and token ID (jti) are acknowledged without revoking later sign-ins; this protection survives restarts.

Auto-login

With auth.oidc.autoLogin: true or the matching Settings toggle, the login page redirects straight to the identity provider. It only applies while OIDC is configured and password login is disabled; otherwise the setting stays inactive and the server logs why. After a logout, the login page is shown once instead of redirecting, so users are not signed straight back in. Open /login?local=1 to reach the login page anyway, for example to sign in with a passkey.

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:.

Branding

Administrators can replace the application name, logo, and colors from Settings > Branding. The name is used in the sidebar, browser tab title, web app manifest, sign-in and setup pages, TOTP issuer, passkey relying-party name, test and application update notifications, and the {{event.app_name}} webhook template variable. The logo replaces the sidebar, sign-in, and setup logos as well as the browser favicon and home screen icon.

• Names are limited to 60 characters; leave the field empty to restore CrowdSec Web UI.
• Logos may be PNG, JPEG, GIF, WebP, or SVG images up to 512 KB. The image type is detected from the file content, and SVG logos are served with a sandboxed Content Security Policy.
• An optional dark mode logo replaces the sidebar, sign-in, and setup logos while the dark theme is active. Without one, the main logo is used in both themes. The favicon and home screen icon always use the main logo.
• Colors can be set separately for light and dark mode: an accent color, from which the full accent palette is generated, and a neutral tone (gray, slate, zinc, neutral, or stone) for backgrounds, borders, and text. Dark mode uses the light mode colors unless it has its own. Status colors such as red for bans stay unchanged. The settings page previews both modes and warns when the accent has low contrast.
• The server injects the branded title, icons, and colors into the page shell, so the page is branded before JavaScript loads.
• Branding is stored in the application database and requires admin mode to change.

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, rule_type, and app_name (the configured branding name). 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 state.db.
• notifications.allowPrivateAddresses: false blocks private, loopback, and link-local destinations; default: true. Hostnames are checked when the connection is made, so a DNS change cannot point a destination at a blocked address. IPv4 addresses embedded in IPv6 forms (for example ::ffff:7f00:1) are blocked like their IPv4 equivalents.
• Apprise, Gotify, and ntfy follow only same-origin 307/308 redirects, and each redirect target is checked again.
• Telegram is not supported natively; use Apprise to reach it. 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

Data is split into two SQLite files:

Mount the directories, not single files: WAL mode also uses cache.db-wal and cache.db-shm.

volumes:
  - ./data:/app/data

To keep the cache on fast node-local storage while state.db and config.yaml stay on backed-up or network storage, set storage.cacheDir to a separate mount. The container only fixes ownership of /app/data, so a cache mount elsewhere must be writable by the container user. state.db uses a rollback journal and is written rarely, so it works on network filesystems that do not support WAL.

Upgrading from a version that used a single crowdsec.db copies its durable data into state.db on the first start and then deletes crowdsec.db. Cached alerts and decisions are not copied; the first start runs a full synchronization of crowdsec.sync.lookback. Back up the data directory before upgrading. Older versions cannot read the new files.

• 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

cache.db uses SQLite incremental auto-vacuum by default and reclaims free pages while idle. A cache created with storage.incrementalVacuumEnabled: false keeps that format. If startup reports reclaimable space, stop CrowdSec Web UI, delete cache.db, cache.db-wal, and cache.db-shm, and start it again. The cache is recreated with incremental auto-vacuum and refilled by a full synchronization.

Documentation

Star History

Related Projects

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