sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-09-28 01:39:05 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add CrowdSec IP reputation documentation (#698)

Browse Source
This commit is contained in:
Viktor Liu
2026-04-16 18:06:43 +02:00
committed by GitHub
parent 6f88f3fea8
commit b2602add87
7 changed files with 229 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/pages/manage/reverse-proxy/access-logs.mdx
+8
View File
@@ -66,6 +66,14 @@ The following deny reasons can appear for both HTTP and L4 services:
| `ip_restricted` | The client IP was blocked by a CIDR access restriction |
| `country_restricted` | The client's country was blocked by a country access restriction |
| `geo_unavailable` | Country restrictions are configured but the GeoIP database is unavailable (fail-closed) |
| `crowdsec_ban` | The client IP has a CrowdSec ban decision |
| `crowdsec_captcha` | The client IP has a CrowdSec captcha decision |
| `crowdsec_throttle` | The client IP has a CrowdSec throttle decision |
| `crowdsec_unavailable` | CrowdSec enforce mode is active but the bouncer has not completed its initial sync (fail-closed) |
All CrowdSec decision types (ban, captcha, throttle) result in a connection denial in enforce mode. The proxy does not serve captcha challenges or apply rate limiting: the decision type is recorded for informational purposes only.
When CrowdSec is in **observe** mode, the verdict appears in the log metadata but the deny reason field is empty (the connection is allowed). This lets you audit what CrowdSec would block without affecting traffic.
## Use cases
src/pages/manage/reverse-proxy/authentication.mdx
+47 -4
View File
@@ -131,9 +131,9 @@ Common combinations include:
## Access restrictions
Access restrictions control which connections are allowed to reach your service based on the client's IP address or geographic location. Unlike authentication methods, access restrictions operate at the connection level and work for both HTTP and L4 services.
Access restrictions control which connections are allowed to reach your service based on the client's IP address, geographic location, or IP reputation. Unlike authentication methods, access restrictions operate at the connection level and work for both HTTP and L4 services.
Access restrictions are evaluated **before** authentication. If a connection is blocked by an IP or country rule, it is rejected immediately without any authentication check.
Access restrictions are evaluated **before** authentication. If a connection is blocked by an access restriction rule, it is rejected immediately without any authentication check.
<p>
<img src="/docs-static/img/manage/reverse-proxy/authentication/access-restrictions-geo-ip.png" alt="Authentication tab showing all available authentication methods" className="imagewrapper"/>
@@ -172,12 +172,30 @@ The evaluation logic mirrors CIDR restrictions: if an allowed list is present, t
GeoIP accuracy depends on the database quality and the client's IP address. VPN and proxy users may appear from a different country than their physical location.
</Note>
### CrowdSec IP reputation
[CrowdSec](https://www.crowdsec.net) is an open-source security engine that maintains a community-curated database of known malicious IP addresses. When enabled, the proxy checks every incoming client IP against a local cache of CrowdSec decisions and blocks connections from flagged addresses.
CrowdSec operates in one of three modes per service:
| Mode | Behavior |
|------|----------|
| **Off** | CrowdSec checks are disabled for this service (default). |
| **Enforce** | Connections from flagged IPs are denied immediately. If the CrowdSec bouncer has not completed its initial sync, all connections are denied (fail-closed). |
| **Observe** | Connections from flagged IPs are logged in [access logs](/manage/reverse-proxy/access-logs) but not blocked. Use this to evaluate the impact before switching to enforce. |
CrowdSec decisions include different remediation types (ban, captcha, throttle). The proxy treats all types as connection denials in enforce mode: there is no captcha challenge or rate limiting. The specific decision type is recorded in the [access logs](/manage/reverse-proxy/access-logs) so you can distinguish between them when reviewing traffic.
<Note>
CrowdSec is only available when the proxy cluster has CrowdSec configured. If the cluster does not support CrowdSec, the option will not appear in the Access Control tab. For self-hosted deployments, see the [CrowdSec setup guide](/selfhosted/maintenance/crowdsec) to enable it.
</Note>
### Combining restrictions with authentication
Access restrictions and authentication methods are independent layers:
1. **Connection arrives** at the proxy.
2. **Access restrictions** are evaluated first: IP CIDRs, then country. If the connection is blocked, it is rejected with no further processing.
2. **Access restrictions** are evaluated first: IP CIDRs, then country, then CrowdSec. If the connection is blocked at any layer, it is rejected with no further processing.
3. **Authentication** is evaluated next (for HTTP services): SSO, password, PIN, or header auth.
4. If both layers pass, the request is forwarded to the backend.
@@ -250,12 +268,36 @@ Authentication and access control are configured in separate tabs of the service
4. To restrict by country:
- Select countries in the **Allowed Countries** field to create a country allowlist.
- Select countries in the **Blocked Countries** field to create a country blocklist.
5. Click **Save** (or **Save Changes** when editing).
5. To enable CrowdSec IP reputation (when available):
- Set the **CrowdSec IP Reputation** dropdown to **Enforce** or **Observe**.
6. Click **Save** (or **Save Changes** when editing).
<Note>
Access restrictions apply immediately to new connections. Existing connections that were established before the restriction was added are not affected until they reconnect.
</Note>
### Restriction evaluation order
Access restrictions are evaluated as a pipeline. Each layer can only further restrict: a denial at any layer is final and short-circuits later layers. No layer can relax a denial from an earlier one.
| Layer | What it checks | On deny |
|-------|----------------|---------|
| 1. CIDR | Allowlist/blocklist by IP range | Stops here, country and CrowdSec are skipped |
| 2. Country | Allowlist/blocklist by geolocation | Stops here, CrowdSec is skipped |
| 3. CrowdSec | IP reputation against decision cache | Blocks (enforce) or logs (observe) |
**Examples:**
| Config | Client IP | Result | Reason |
|--------|-----------|--------|--------|
| Allow `10.0.0.0/8` + CrowdSec enforce | `10.1.2.3` (CrowdSec banned) | Denied | `crowdsec_ban` |
| Allow `10.0.0.0/8` + CrowdSec enforce | `10.2.3.4` (clean) | Allowed | Passed all layers |
| Allow `10.0.0.0/8` + CrowdSec enforce | `192.168.1.1` | Denied | `ip_restricted` (CIDR deny, CrowdSec never runs) |
| Block `10.1.0.0/16` + CrowdSec enforce | `10.1.2.3` (CrowdSec banned) | Denied | `ip_restricted` (CIDR deny takes precedence) |
| Allow country US + CrowdSec enforce | `1.2.3.4` US (CrowdSec banned) | Denied | `crowdsec_ban` |
| Allow country US + CrowdSec enforce | `5.6.7.8` CN | Denied | `country_restricted` (country deny, CrowdSec never runs) |
| Allow `10.0.0.0/8` + CrowdSec observe | `10.1.2.3` (CrowdSec banned) | Allowed | Ban logged but not enforced |
### Removing authentication
To remove an authentication method from a service:
@@ -284,3 +326,4 @@ Authenticated sessions for reverse proxy services are managed using JWT (JSON We
- [Single Sign-On](/manage/team/single-sign-on) - configure your identity provider for SSO across NetBird
- [Provision Users and Groups](/manage/team/idp-sync) - sync users and groups from your identity provider
- [Geolocation Database](/selfhosted/geo-support) - configure MaxMind GeoLite2 for country-based access restrictions (self-hosted)
- [CrowdSec Setup](/selfhosted/maintenance/crowdsec) - enable CrowdSec IP reputation on a self-hosted proxy
src/pages/manage/reverse-proxy/index.mdx
+6 -5
View File
@@ -39,7 +39,7 @@ A service is the core configuration unit of the Reverse Proxy. Each service maps
- **Domain** - the public URL where the service is reachable
- **Targets** - one or more backend destinations that handle incoming requests
- **Authentication** - optional SSO, password, PIN, or header-based protection
- **Access restrictions** - optional IP CIDR and country-based access control
- **Access restrictions** - optional IP CIDR, country, and CrowdSec IP reputation access control
- **Settings** - advanced options (varies by service mode)
- **Enabled/Disabled toggle** - turn the service on or off without deleting it
@@ -57,7 +57,7 @@ The service mode determines how the proxy handles traffic between clients and yo
L4 services (TCP, UDP, TLS) listen on a dedicated port on the proxy cluster. Depending on the cluster, the port may be auto-assigned or you can specify one manually. The proxy cluster's `supports_custom_ports` capability determines whether manual port selection is available.
<Note>
L4 services do not support browser-based authentication (SSO, password, PIN) or header authentication because there is no HTTP layer. You can use [access restrictions](/manage/reverse-proxy/authentication#access-restrictions) (IP CIDR and country rules) to protect L4 services.
L4 services do not support browser-based authentication (SSO, password, PIN) or header authentication because there is no HTTP layer. You can use [access restrictions](/manage/reverse-proxy/authentication#access-restrictions) (IP CIDR, country, and CrowdSec rules) to protect L4 services.
</Note>
### Targets
@@ -126,7 +126,7 @@ You can protect a service with one or more authentication methods. When multiple
| **Password** | Yes | No | Protect with a shared password. |
| **PIN Code** | Yes | No | Protect with a numeric PIN code. |
| **Header Authentication** | Yes | No | Validate a static header value (API key, Bearer token, Basic auth). Useful for programmatic access. |
| **Access Restrictions** | Yes | Yes | Restrict access by IP CIDR range or country. Works at the connection level, so it applies to all service modes. |
| **Access Restrictions** | Yes | Yes | Restrict access by IP CIDR range, country, or CrowdSec IP reputation. Works at the connection level, so it applies to all service modes. |
<Note>
If you save a service with no authentication or access restrictions configured, the dashboard will display a warning. Public services are accessible to anyone on the internet who knows the URL.
@@ -268,12 +268,13 @@ Switch to the **Authentication** tab to configure how users are authenticated be
### Step 3b: Configure access control
Switch to the **Access Control** tab to restrict access by IP address or country. This tab is available for all service modes (HTTP and L4).
Switch to the **Access Control** tab to restrict access by IP address, country, or IP reputation. This tab is available for all service modes (HTTP and L4).
- Add **allowed CIDRs** or **blocked CIDRs** to restrict by IP range.
- Add **allowed countries** or **blocked countries** to restrict by geographic location.
- Set **CrowdSec IP Reputation** to **enforce** or **observe** to block or monitor known malicious IPs (when available on the proxy cluster).
Access restrictions are evaluated before authentication: if a connection is blocked by an IP or country rule, it is rejected before any authentication check.
Access restrictions are evaluated before authentication: if a connection is blocked by an access restriction rule, it is rejected before any authentication check.
### Step 4: Configure advanced settings