Protect the dashboard with CrowdSec AppSec
Updated
This guide shows how to protect a self-hosted NetBird dashboard with CrowdSec AppSec when NetBird is deployed with the internal Traefik reverse proxy.
The configuration reuses the CrowdSec LAPI container created by the NetBird quickstart when you enable the NetBird Proxy CrowdSec integration. NetBird Proxy and Traefik use separate bouncer keys against the same CrowdSec service.
For the NetBird Proxy IP reputation integration, see CrowdSec IP Reputation.
For updates to Traefik, CrowdSec, or the bouncer plugin, see Upgrading Traefik and CrowdSec.
Prerequisites
- A self-hosted NetBird deployment using the internal Traefik reverse proxy.
- NetBird Proxy enabled with CrowdSec IP reputation blocking.
- A Linux host reachable on TCP
80and443, and UDP3478. - A domain such as
netbird.example.compointing to the host. - A wildcard record such as
*.netbird.example.compointing to the same host if you use NetBird Proxy. - Docker with Compose v2.
curl,jq, andopenssl.
Before changing an existing deployment, follow the Backup guide to back up both the install directory and the netbird_data and crowdsec_db Docker volumes. Copying the install directory alone does not preserve the Management database or CrowdSec state. On an install created by getting-started-enterprise.sh, the CrowdSec volumes are netbird_crowdsec_config and netbird_crowdsec_data.
Set these shell variables before running the commands in this guide:
export NETBIRD_INSTALL_DIR="/path/to/netbird/install"
export NETBIRD_DOMAIN="netbird.example.com"
NETBIRD_INSTALL_DIR is the directory that contains the generated docker-compose.yml, proxy.env, dashboard.env, and crowdsec/ files.
Deploy NetBird with Traefik and CrowdSec
For a new deployment, follow the Self-hosting Quickstart Guide. When the quickstart asks for deployment options, choose:
Reverse proxy: 0, Traefik
Enable proxy: y
Enable CrowdSec IP reputation blocking: y
Enable AppSec: y
Enabling CrowdSec creates a local crowdsec service, registers a netbird-proxy bouncer, and writes NB_PROXY_CROWDSEC_API_URL and NB_PROXY_CROWDSEC_API_KEY to proxy.env.
Answering yes to AppSec writes the rest of this guide: the dashboard bouncer key in .env (mode 600), crowdsec/acquis.d/appsec.yaml, the Traefik plugin at v1.7.1, the middleware, a router for /api and /oauth2 at priority 110, and a health check that waits for port 7422. The middleware definition is placed on the Traefik service, so a dashboard restart does not drop it. The dashboard router and the API router reference that middleware. Relay, gRPC, and the proxy TCP passthrough do not. Continue at Verify protection.
If you leave AppSec off, add it later with the steps from Add a dashboard bouncer key through Apply the change. Rerunning the quickstart does not add AppSec to an install that already exists.
The enterprise script asks the same question when it is adding the proxy and you enable CrowdSec. It does not add CrowdSec or AppSec to a proxy that is already running. Follow the manual steps below only when the enterprise stack already has the crowdsec service and NetBird Proxy is configured to use it. There is currently no documented in-place path for adding CrowdSec to an enterprise install whose proxy is already running.
After adding AppSec manually to an enterprise install, add this line to .env:
NETBIRD_CROWDSEC_APPSEC_ENABLED=yes
Set it before the next run with --enable-proxy or --enable-traffic-events. The script rebuilds docker-compose.yml from the feature flags in .env; without this line, it treats AppSec as disabled and proposes removing its Compose configuration.
If you already have a self-hosted NetBird deployment without NetBird Proxy, follow Enable Reverse Proxy Feature first.
This CrowdSec dashboard protection setup requires the combined container
setup. If your deployment uses the
separate-container architecture (management, signal, relay, and
coturn), migrate to the combined container setup before enabling NetBird
Proxy.
Add a dashboard bouncer key
Create a dedicated bouncer key for the Traefik plugin and store it in the Compose project .env file:
cd "$NETBIRD_INSTALL_DIR"
umask 077
if ! grep -q '^CROWDSEC_DASHBOARD_BOUNCER_KEY=.' .env 2>/dev/null; then
CROWDSEC_DASHBOARD_BOUNCER_KEY=$(openssl rand -hex 32) || exit 1
if [ -z "$CROWDSEC_DASHBOARD_BOUNCER_KEY" ]; then
echo "Failed to generate a dashboard bouncer key." >&2
exit 1
fi
printf 'CROWDSEC_DASHBOARD_BOUNCER_KEY=%s\n' "$CROWDSEC_DASHBOARD_BOUNCER_KEY" >> .env || exit 1
fi
chmod 600 .env
Rerunning this command preserves an existing non-empty key. chmod 600 restricts .env to its owner, since the file now holds the bouncer key.
Add CrowdSec AppSec acquisition
Create the AppSec acquisition file:
mkdir -p "$NETBIRD_INSTALL_DIR/crowdsec/acquis.d"
cat >"$NETBIRD_INSTALL_DIR/crowdsec/acquis.d/appsec.yaml" <<'EOF'
appsec_configs:
- crowdsecurity/appsec-default
labels:
type: appsec
listen_addr: 0.0.0.0:7422
source: appsec
EOF
Update docker-compose.yml
Start from the docker-compose.yml generated by the quickstart with proxy CrowdSec enabled. The file already includes a crowdsec service, and proxy.env already points NetBird Proxy to http://crowdsec:8080.
Enterprise install differences
For an install created by getting-started-enterprise.sh, adapt the quickstart examples below:
-
Keep
image: traefik:${NETBIRD_TRAEFIK_TAG}andimage: crowdsecurity/crowdsec:${NETBIRD_CROWDSEC_TAG}. If upgrading an image, update the corresponding tag in.env. -
Keep
services.crowdsec.environmentin list form and preserve any other entries. Replace the existingCOLLECTIONSentry and add the dashboard bouncer key as follows:environment: - "COLLECTIONS=crowdsecurity/linux crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules" - BOUNCER_KEY_netbird_dashboard=${CROWDSEC_DASHBOARD_BOUNCER_KEY} -
Keep the named volumes
netbird_crowdsec_configandnetbird_crowdsec_data, including their top-level declarations. Skip thecrowdsec_dbdeclaration below. Add only./crowdsec/acquis.d:/etc/crowdsec/acquis.d:roto the service's existing volume mounts. -
Set the dashboard and
netbird-dashboard-apirouter middleware lists tonetbird-dashboard-crowdsec@docker,nb-security@docker. Keep the gRPC and relay routers onnb-security@dockeralone so the enterprise security headers remain in place. -
After manual setup, set
NETBIRD_CROWDSEC_APPSEC_ENABLED=yesin.envbefore rerunning the enterprise script with--enable-proxyor--enable-traffic-events.
For quickstart installs, set the Traefik image to v3.7.18. Add the header handling and bouncer plugin arguments to the existing services.traefik.command list:
services:
traefik:
image: traefik:v3.7.18
command:
- '--entrypoints.web.http.aliasHeadersStrategy=delete'
- '--entrypoints.websecure.http.aliasHeadersStrategy=delete'
- '--experimental.plugins.bouncer.modulename=github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin'
- '--experimental.plugins.bouncer.version=v1.7.1'
The header settings remove request headers with names containing characters other than letters, digits, and hyphens. If you use custom headers or already set underscoreHeadersStrategy, review Traefik header handling before applying them.
Verify that the existing --providers.docker.network value matches the actual Docker network name, which can include a Compose project prefix. Follow Traefik Docker network to check it and replace a mismatched value. Update the existing flag rather than adding a second copy.
Under services.traefik.depends_on, make Traefik wait until CrowdSec is healthy:
services:
traefik:
depends_on:
crowdsec:
condition: service_healthy
Under services.dashboard.labels, add the CrowdSec middleware to the existing dashboard router:
services:
dashboard:
labels:
- traefik.http.routers.netbird-dashboard.middlewares=netbird-dashboard-crowdsec@docker
Under services.traefik.labels, define the middleware. This is where the install scripts place it, and keeping the definition on the Traefik service means a dashboard restart cannot drop it. Traefik runs with exposedbydefault=false, so the traefik.enable=true label is needed before it reads labels from its own container:
services:
traefik:
labels:
- traefik.enable=true
- traefik.http.middlewares.netbird-dashboard-crowdsec.plugin.bouncer.enabled=true
- traefik.http.middlewares.netbird-dashboard-crowdsec.plugin.bouncer.crowdsecMode=stream
- traefik.http.middlewares.netbird-dashboard-crowdsec.plugin.bouncer.crowdsecLapiScheme=http
- traefik.http.middlewares.netbird-dashboard-crowdsec.plugin.bouncer.crowdsecLapiHost=crowdsec:8080
- traefik.http.middlewares.netbird-dashboard-crowdsec.plugin.bouncer.crowdsecLapiKey=${CROWDSEC_DASHBOARD_BOUNCER_KEY}
- traefik.http.middlewares.netbird-dashboard-crowdsec.plugin.bouncer.crowdsecAppsecEnabled=true
- traefik.http.middlewares.netbird-dashboard-crowdsec.plugin.bouncer.crowdsecAppsecHost=crowdsec:7422
- traefik.http.middlewares.netbird-dashboard-crowdsec.plugin.bouncer.crowdsecAppsecFailureBlock=true
- traefik.http.middlewares.netbird-dashboard-crowdsec.plugin.bouncer.crowdsecAppsecUnreachableBlock=true
Under services.netbird-server.labels, replace the existing netbird-backend.rule with the rule below and keep its other labels. Add the higher-priority netbird-dashboard-api router for dashboard API and embedded IdP paths in the same list:
services:
netbird-server:
labels:
- traefik.http.routers.netbird-backend.rule=Host(`netbird.example.com`) && (PathPrefix(`/relay`) || PathPrefix(`/ws-proxy/`))
- traefik.http.routers.netbird-dashboard-api.rule=Host(`netbird.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/oauth2`))
- traefik.http.routers.netbird-dashboard-api.entrypoints=websecure
- traefik.http.routers.netbird-dashboard-api.tls=true
- traefik.http.routers.netbird-dashboard-api.tls.certresolver=letsencrypt
- traefik.http.routers.netbird-dashboard-api.service=netbird-server
- traefik.http.routers.netbird-dashboard-api.middlewares=netbird-dashboard-crowdsec@docker
- traefik.http.routers.netbird-dashboard-api.priority=110
Replace netbird.example.com with your NetBird domain. Traefik labels do not read the NETBIRD_DOMAIN shell variable used in the command examples.
With AppSec enabled, /api and /oauth2 must use the protected API router. Restricting netbird-backend to /relay and /ws-proxy/ prevents those requests from reaching an uninspected backend if the protected router is unavailable. Both install scripts apply this restriction when AppSec is enabled.
Leave the NetBird Proxy TCP passthrough labels unchanged. Do not attach this
middleware to the proxy-passthrough TCP router, or to the relay and gRPC
routers.
Merge these fields into services.crowdsec, using the enterprise differences above where applicable. The quickstart example sets the validated image version, adds the AppSec collections, registers the dashboard bouncer key, and updates the health check so CrowdSec reports healthy only after both LAPI and AppSec are available. Keep the other generated fields, including container_name, restart, networks, labels, logging, and volumes.
When AppSec was left off, the installer-created health check only verifies the CrowdSec Local API:
healthcheck:
test: ['CMD', 'cscli', 'lapi', 'status']
interval: 10s
timeout: 5s
retries: 15
Dashboard protection also needs the AppSec listener on port 7422, so replace the installer-created health check with the one below.
| Field | Purpose |
|---|---|
crowdsecurity/linux | Keeps the base Linux collection created by the installer. |
crowdsecurity/appsec-virtual-patching | Adds virtual patching rules for common web application attack patterns. |
crowdsecurity/appsec-generic-rules | Adds generic AppSec detection rules used by the AppSec engine. |
BOUNCER_KEY_netbird_dashboard | Registers a separate Traefik dashboard bouncer key without reusing the NetBird Proxy bouncer key. |
healthcheck.test | Replaces the installer LAPI-only check with a check for both LAPI and the AppSec listener on 7422. |
services:
crowdsec:
image: crowdsecurity/crowdsec:v1.8.1
environment:
COLLECTIONS: "crowdsecurity/linux crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules"
BOUNCER_KEY_netbird_dashboard: "${CROWDSEC_DASHBOARD_BOUNCER_KEY}"
healthcheck:
test: ["CMD-SHELL", "cscli lapi status >/dev/null 2>&1 && bash -c '</dev/tcp/127.0.0.1/7422'"]
interval: 10s
timeout: 5s
retries: 15
start_period: 30s
For quickstart installs, keep the installer-created CrowdSec volume in the top-level volumes section:
volumes:
crowdsec_db:
Apply the change
Validate the Compose file without printing the resolved configuration, which contains the dashboard bouncer key:
cd "$NETBIRD_INSTALL_DIR"
docker compose config --quiet
Start the updated stack:
docker compose up -d
docker compose ps
Verify protection
Open https://$NETBIRD_DOMAIN in a browser and confirm the dashboard loads. Then verify the status codes from the NetBird host or another machine that can reach the dashboard.
Normal dashboard and OIDC requests should return 200:
curl -ks -A 'Mozilla/5.0 NetBirdDashboardCheck' -o /dev/null -w '%{http_code}\n' "https://$NETBIRD_DOMAIN"
curl -ks -A 'Mozilla/5.0 NetBirdDashboardCheck' -o /dev/null -w '%{http_code}\n' "https://$NETBIRD_DOMAIN/oauth2/.well-known/openid-configuration"
A known malicious probe should return 403:
curl -ks -A 'Mozilla/5.0 NetBirdDashboardCheck' -o /dev/null -w '%{http_code}\n' "https://$NETBIRD_DOMAIN/.env"
Use only the /.env and /api/.env probes when testing from your admin IP. Triggering two different AppSec rules within about a minute can ban that IP for 4 hours, blocking the dashboard, /api, and /oauth2. To lift a ban, recover access over SSH.
The default crowdsecurity/whitelists parser exempts loopback and private IPv4 ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) from this ban. Requests from those addresses are still blocked individually with 403, so testing from a LAN client does not show whether a public IP would be banned.
Check AppSec metrics and bouncer registration:
docker compose exec -T crowdsec cscli metrics show appsec
docker compose exec -T crowdsec cscli bouncers list
A healthy deployment shows AppSec requests being processed, the netbird-proxy bouncer from the quickstart, and the netbird_dashboard bouncer used by Traefik.
Test manual IP blocks
You can test that the Traefik bouncer blocks dashboard access by adding a temporary CrowdSec decision for your own public IP.
First, get your public IPv4 address from the same client you will use to test dashboard access:
curl -4s ifconfig.me
Run this command through the same network path as the dashboard test. NAT or proxies can change the source IP that Traefik sees.
This test blocks the dashboard, /api, and /oauth2 for your IP for the duration of the decision. If you can't remove the decision, see Recovering from a dashboard lockout.
On the NetBird host, add a short test ban:
cd "$NETBIRD_INSTALL_DIR"
TEST_IP="<your-public-ipv4>"
docker compose exec -T crowdsec cscli decisions add --ip "$TEST_IP" --duration 3m --reason "dashboard bouncer test"
If your IP is on a CrowdSec allowlist, cscli decisions add refuses the decision. Add --bypass-allowlist to the command to test anyway.
Wait up to 60 seconds because the Traefik bouncer runs in stream mode and refreshes decisions periodically. Then open your NetBird dashboard in a browser from the blocked IP. The dashboard request should be blocked.
Alternatively, verify the block with curl:
curl -ks -A 'Mozilla/5.0 NetBirdDashboardCheck' -o /dev/null -w '%{http_code}\n' "https://$NETBIRD_DOMAIN"
The response should be 403.
Confirm the decision exists:
docker compose exec -T crowdsec cscli decisions list
Remove the decision when done:
docker compose exec -T crowdsec cscli decisions delete --ip "$TEST_IP"
Wait up to 60 seconds for the bouncer to refresh, then verify access returns:
curl -ks -A 'Mozilla/5.0 NetBirdDashboardCheck' -o /dev/null -w '%{http_code}\n' "https://$NETBIRD_DOMAIN"
The response should be 200.
Verifying the middleware stays attached
If you followed an earlier version of this guide, move the netbird-dashboard-crowdsec middleware definition from services.dashboard.labels to services.traefik.labels and add traefik.enable=true there. Remove the old definition from the dashboard service, keeping the router middleware references. Also apply the restricted netbird-backend rule from Update docker-compose.yml. Without these updates, stopping the dashboard can disable the protected API router and let /api and /oauth2 reach the backend without AppSec inspection.
Apply both changes with docker compose up -d traefik dashboard netbird-server, then run the probes below.
The middleware definition lives on the traefik service, and the routers on dashboard and netbird-server reference it. If that definition is missing or invalid, Traefik logs a configuration error and does not enable routers that still reference it. The restricted backend rule above prevents /api and /oauth2 from falling back to the uninspected backend router.
Removing the middleware reference from a router leaves that router without AppSec inspection. Container health alone does not confirm that protection is attached.
After changing labels, recreate the containers whose labels changed with docker compose up -d. docker compose restart does not apply label changes. For the two router attachments, recreate dashboard and netbird-server and re-run both probes from an IP outside any CrowdSec allowlist:
docker compose up -d dashboard netbird-server
curl -ks -A 'Mozilla/5.0 NetBirdDashboardCheck' -o /dev/null -w '%{http_code}\n' "https://$NETBIRD_DOMAIN/.env"
curl -ks -A 'Mozilla/5.0 NetBirdDashboardCheck' -o /dev/null -w '%{http_code}\n' "https://$NETBIRD_DOMAIN/api/.env"
Both probes should return 403, and the normal dashboard and OIDC requests in Verify protection should still succeed. A 404 alone does not identify the cause: check the router labels and Traefik logs for middleware configuration errors.
To surface this automatically, monitor the same probe from outside the deployment and treat 403 as the healthy response. The middleware is attached to the two routers separately, so probe both. A check on /.env alone exercises only the dashboard router and would still return 403 if the middleware were detached from the API router. Point an uptime monitor or a cron job at each of:
https://<your-domain>/.env
https://<your-domain>/api/.env
Alert when either response is anything other than 403. Monitor normal dashboard and OIDC requests separately so an outage or an IP ban is not mistaken for working protection.
Do not enable the Traefik API (--api.insecure=true) for this purpose. The
API serves the full dynamic configuration without authentication, including
middleware plugin settings such as crowdsecLapiKey. Even with port 8080
unpublished, every container on the Docker network could then read the
CrowdSec bouncer key.
These probes do not restore enforcement automatically. Investigate unexpected responses, correct the router labels or middleware configuration, and recreate the affected containers.
Recovering from a dashboard lockout
If AppSec or an IP decision blocks you from the dashboard, the block also covers /api and /oauth2, so it cannot be lifted from the UI. All recovery is performed over SSH on the host.
In your SSH session, change to the NetBird install directory. Replace the path below with the directory containing your docker-compose.yml:
cd "/path/to/netbird/install"
First identify which of the two mechanisms is blocking you, because they are handled differently:
docker compose exec -T crowdsec cscli decisions list
If your address is listed, an IP decision is blocking you. This includes bans created by the crowdsecurity/appsec-vpatch scenario after repeated AppSec matches, which appear with that reason. If it is not, the block is an AppSec match on the request itself: an individual AppSec match does not create a decision, so cscli decisions delete has no effect in that case. Confirm with cscli metrics show appsec and cscli alerts list, where AppSec matches appear with kind set to waf.
Allowlisting the address resolves both cases. cscli allowlists add fails with allowlist '<name>' not found if the list does not already exist, so create it first if you have not set one up:
docker compose exec -T crowdsec cscli allowlists create netbird-admins -d "Addresses that should never be blocked"
docker compose exec -T crowdsec cscli allowlists add netbird-admins <your-ip> -d "admin"
Adding an address that currently carries a decision expires that decision immediately. Allowlisted addresses are also exempted from AppSec blocking. AppSec refreshes its allowlists every minute, so allow up to a minute for that exemption to take effect. See Allowlisting addresses for details.
If an IP decision is present and you want it gone without allowlisting the address permanently, delete it directly:
docker compose exec -T crowdsec cscli decisions delete --ip <your-ip>
For example, removing one matching decision logs:
1 decision(s) deleted
The Traefik bouncer runs in stream mode and refreshes periodically, so allow up to a minute for access to return.
If the dashboard is still unreachable and you need immediate access, detach the middleware. It is attached to two routers and both must be removed from the request path. The middleware definition on the traefik service stays. Comment out the router lines below, not that definition. On an enterprise install, set those two lines back to nb-security@docker instead of removing them, so the security headers stay:
services:
dashboard:
labels:
# - traefik.http.routers.netbird-dashboard.middlewares=netbird-dashboard-crowdsec@docker
netbird-server:
labels:
# - traefik.http.routers.netbird-dashboard-api.middlewares=netbird-dashboard-crowdsec@docker
docker compose up -d dashboard netbird-server
Commenting out only the dashboard label leaves the dashboard reachable while
/api and /oauth2 continue to return 403. The interface loads but cannot
authenticate or fetch data, which is easily mistaken for a different fault.
Detach both labels, or neither.
Restore both labels once the underlying issue is resolved, recreate the containers, and confirm with the /.env and /api/.env probes in Verifying the middleware stays attached. Run these probes from an IP outside netbird-admins and any other CrowdSec allowlist, because allowlisted IPs bypass AppSec checks.
If you use the IP you allowlisted during recovery, first remove it from netbird-admins on the NetBird host:
docker compose exec -T crowdsec cscli allowlists remove netbird-admins <your-ip>
Wait up to one minute for AppSec to refresh its allowlists, then run both probes from that IP and confirm that each returns 403.
Troubleshooting
If all dashboard requests return 403 immediately after startup, Traefik may have started before CrowdSec LAPI and AppSec were ready. Confirm that the CrowdSec health check is present and that Traefik uses depends_on.condition: service_healthy.
If CrowdSec is stopped or unreachable while crowdsecAppsecUnreachableBlock=true is set, all dashboard requests are denied by design.
Separately, a reverse proxy service in enforce mode denies all connections while its bouncer has not completed its initial sync, for example when the proxy starts with the LAPI unavailable. See Enforcement modes.
If Traefik logs warnings about a missing Docker network, follow Traefik Docker network to correct the configured name.
If AppSec metrics do not increment, confirm that the middleware is attached to both the netbird-dashboard and netbird-dashboard-api routers and that Traefik can reach crowdsec:8080 and crowdsec:7422.

