mirror of
https://github.com/netbirdio/docs.git
synced 2026-10-26 22:49:04 +01:00
Update posture checks video and navigation (#926)
* Update video and fix nav * Quick edits (Coderabbits Findings) * Releases to docs audit * peer network range mobile fix
This commit is contained in:
Brandon Hopkins
@@ -3,16 +3,15 @@ Posture Checks is a security feature that enhances network protection by impleme
|
||||
|
||||
In this regard, NetBird posture checks verify various aspects of a connecting device, offering granular control over network access. These checks include **verifying the NetBird client version**, allowing you to restrict access to peers with specific versions of the client software. Additionally, you can implement **geographical restrictions** based on country or region, giving you control over where connections can originate from.
|
||||
|
||||
<YouTube videoId="nk7XM8oi-4Y" title="Understanding Posture Checks" />
|
||||
|
||||
The feature also allows for network-level restrictions by enabling you to **allow or block specific peer network ranges**. Furthermore, you can set constraints based on the operating system of the connecting device, **ensuring that only approved OS versions can gain access**. For an even more detailed level of control, Posture Checks can examine the running processes on a peer device, **allowing or denying access based on the presence of specific applications or services**.
|
||||
|
||||
By using these diverse checking capabilities, NetBird empowers you to create a robust and finely-tuned security posture for your network, significantly reducing the risk of unauthorized access and potential security breaches.
|
||||
|
||||
## Setting Up Posture Checks
|
||||
|
||||
Setting up posture checks in NetBird is straightforward, you can follow the example in the video below:
|
||||
<YouTube videoId="-KlJUBuZrpo" />
|
||||
|
||||
Or follow the guide with other examples below:
|
||||
Setting up posture checks in NetBird is straightforward. Follow the guide and examples below:
|
||||
|
||||
Log in to your NetBird dashboard and navigate to `Access Control` > `Posture Checks` in the left menu. Click `Create Posture Check` or edit an existing one.
|
||||
|
||||
@@ -30,7 +29,7 @@ Restrict access to peers with specific NetBird client versions, thus ensuring th
|
||||
|
||||
|
||||
### Country and Region
|
||||
Limit network access based on geographical location, helping comply with data regulations or restrict access from high-risk areas. Note that you have two tabs available for this: `Allow` (green) and `Block` (red), making it easy to set up your preferred access rules..
|
||||
Limit network access based on geographical location, helping comply with data regulations or restrict access from high-risk areas. Note that you have two tabs available for this: `Allow` (green) and `Block` (red), making it easy to set up your preferred access rules.
|
||||
|
||||
|
||||
<Note>
|
||||
@@ -46,7 +45,7 @@ The check evaluates a peer against two sources of address information:
|
||||
- **The peer's local network interfaces** — the IP addresses configured on the device's NICs (e.g. the office LAN `192.168.1.0/24` the device is plugged into).
|
||||
- **The peer's public connection IP** — the source IP the NetBird management server observes when the peer connects (i.e. the egress / NAT'd IP).
|
||||
|
||||
A configured range matches when it contains any of these addresses, so the same check covers both private subnets and public CIDRs. Both IPv4 and IPv6 are supported. A few examples:
|
||||
A configured range matches when it fully contains one of these, so the same check covers both private subnets and public CIDRs. Note that a local interface contributes its whole subnet (e.g. a `/24`), not a single address, so a configured range must be no more specific than that subnet to match it. A `/32` rule will not match a NIC sitting in a `/24`, though it does match the connection IP, which is compared as a single host. Both IPv4 and IPv6 are supported. A few examples:
|
||||
|
||||
- Block a single office public IPv4: `203.0.113.10/32`
|
||||
- Allow a public ISP/office block: `1.0.0.0/24` or `3.0.0.0/23`
|
||||
@@ -99,7 +98,7 @@ You'll notice a gray dot to the left of the posture check name, indicating it's
|
||||
|
||||
To apply a posture check:
|
||||
|
||||
* [Create or edit an access control policy](https://docs.netbird.io/access-control).
|
||||
* [Create or edit an access control policy](/manage/access-control).
|
||||
* Find the `Posture Checks` tab within the policy settings.
|
||||
* Choose `Browse Checks` to select an existing check or `New Posture Check` to create one.
|
||||
|
||||
@@ -119,38 +118,43 @@ Following these steps, you can effectively implement and manage NetBird's Postur
|
||||
|
||||
## When Posture Checks Are Evaluated
|
||||
|
||||
NetBird evaluates posture checks when a peer connects or logs in. The check result is computed at connection time and is not re-evaluated continuously for the duration of an active session.
|
||||
NetBird evaluates posture checks when a peer connects or logs in. Checks are also re-evaluated during an active session whenever a peer reports changed system metadata. The management server replays each check against the peer's previous and current metadata, and when a check's verdict flips, it recomputes the network map and distributes the update to the affected peers.
|
||||
|
||||
When you add or change a posture check on a policy, the updated configuration is distributed to connected peers immediately. A peer that is already connected is evaluated against the new check on its next connection. There is no periodic redistribution interval; distribution is driven by configuration changes, not a timer. For more on how changes reach peers, see [How Policy Changes Are Distributed](/manage/access-control#how-policy-changes-are-distributed).
|
||||
When you add or change a posture check on a policy, the updated configuration is distributed to connected peers immediately. A peer that is already connected is evaluated against the new check on its next connection. There is no periodic redistribution interval; distribution is driven by configuration changes and peer metadata changes, not a timer. For more on how changes reach peers, see [How Policy Changes Are Distributed](/manage/access-control#how-policy-changes-are-distributed).
|
||||
|
||||
<Note>
|
||||
Because evaluation happens at connection time, a peer that passes a posture check and later changes state during a long-lived session (for example an operating system downgrade or a required process being stopped) is not re-evaluated until it reconnects. If you require enforcement to react to a peer changing state mid-session, account for this connection-time evaluation model in your design.
|
||||
Mid-session re-evaluation requires a NetBird management server running [0.74.0](https://github.com/netbirdio/netbird/releases) or newer, and is driven by the peer reporting a metadata change rather than by a continuous poll. A peer that passes a posture check and later changes state during a long-lived session (for example an operating system downgrade or a required process stopping) is re-evaluated on its next metadata sync. On management servers older than 0.74.0, that state change is not picked up until the peer reconnects.
|
||||
</Note>
|
||||
|
||||
## Known Limitations
|
||||
|
||||
### Peer Network Range Check on Mobile Platforms
|
||||
### Peer Network Range Check on Android
|
||||
|
||||
iOS and Android do not allow applications to enumerate the device's local network interfaces, so ranges intended to match a peer's **local NIC IPs** (e.g. an office LAN like `192.168.1.0/24`) cannot be evaluated on those platforms.
|
||||
The Android client does not report the device's local network interfaces to the management server, so ranges intended to match a peer's **local NIC IPs** (e.g. an office LAN like `192.168.1.0/24`) cannot be evaluated on that platform.
|
||||
|
||||
Ranges that target the **public connection IP** still work on mobile, because the management server observes that source IP itself — it does not depend on anything the client reports. So public CIDRs (e.g. `203.0.113.10/32`, `1.0.0.0/24`) and public-IP-based deny/allow rules behave the same on mobile as on desktop.
|
||||
Ranges that target the **public connection IP** still work on Android, because the management server observes that source IP itself and does not depend on anything the client reports. So public CIDRs (e.g. `203.0.113.10/32`, `1.0.0.0/24`) and public-IP-based deny/allow rules behave the same on Android as on desktop.
|
||||
|
||||
**Affected platforms:**
|
||||
- iOS
|
||||
- Android
|
||||
<Note>
|
||||
iOS was affected by this limitation in earlier releases. Local network ranges are reported and evaluated correctly on iOS from NetBird client [0.69.0](https://github.com/netbirdio/netbird/releases) onward.
|
||||
</Note>
|
||||
|
||||
**Impact:**
|
||||
|
||||
If a policy's Peer Network Range posture check relies on local NIC ranges, the check cannot match on mobile clients and routes gated by that policy may become unavailable on those devices — even when the device is outside the blocked local range.
|
||||
A local NIC range never matches on Android, so the outcome depends on the check's action:
|
||||
|
||||
- An **Allow** check built on local NIC ranges is never satisfied by an Android peer. Those peers fail the check, and routes gated by that policy become unavailable to them.
|
||||
- A **Deny** check built on local NIC ranges is never triggered by an Android peer, so those peers always pass it. The block silently does not apply on those devices.
|
||||
|
||||
Checks built on the public connection IP are unaffected and behave on Android exactly as they do on desktop.
|
||||
|
||||
**Recommendation:**
|
||||
|
||||
If your deployment includes iOS or Android clients and you need to gate on local network membership, consider one of the following:
|
||||
If your deployment includes Android clients and you need to gate on local network membership, consider one of the following:
|
||||
|
||||
- Create separate policies for mobile clients that do not include local-NIC-based Peer Network Range posture checks
|
||||
- Use alternative posture checks (such as Geo Location) that are supported on mobile platforms
|
||||
- Create separate policies for Android clients that do not include local-NIC-based Peer Network Range posture checks
|
||||
- Use alternative posture checks (such as Geo Location) that are supported on every platform
|
||||
- Use Peer Network Range checks based on the **public connection IP**, which work on every platform
|
||||
- Apply local-NIC-based Peer Network Range posture checks only to policies targeting desktop platforms (Windows, macOS, Linux)
|
||||
- Apply local-NIC-based Peer Network Range posture checks only to policies targeting platforms that report them (Windows, macOS, Linux, and iOS 0.69.0+)
|
||||
|
||||
## Get started with NetBird
|
||||
<div>
|
||||
@@ -160,4 +164,4 @@ If your deployment includes iOS or Android clients and you need to gate on local
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
|
||||
- Follow us [on X](https://x.com/netbird)
|
||||
- Join our [Slack Channel](/slack-url)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
|
||||
Reference in New Issue
Block a user