mirror of
https://github.com/netbirdio/docs.git
synced 2026-08-24 16:51:26 +02: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
@@ -156,6 +156,10 @@ export const docsNavigation = [
|
||||
href: '/manage/access-control/posture-checks',
|
||||
isOpen: false,
|
||||
links: [
|
||||
{
|
||||
title: 'Understanding Posture Checks',
|
||||
href: '/manage/access-control/posture-checks',
|
||||
},
|
||||
{
|
||||
title: 'Disable route when in the office',
|
||||
href: '/manage/access-control/posture-checks/connecting-from-the-office',
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -344,7 +344,7 @@ Recommended posture checks per policy:
|
||||
- Require your EDR (Endpoint Detection and Response) or RMM (Remote Monitoring and Management) agent process to be running before granting access to sensitive resources. This ensures security tools are active on the device.
|
||||
|
||||
<Note>
|
||||
On iOS and Android, the **Peer Network Range (CIDR)** posture check cannot evaluate the device's local network interfaces, so ranges intended to match local LANs (e.g. `192.168.1.0/24`) will not match. Ranges that target the peer's **public connection IP** (e.g. `203.0.113.10/32` or a public CIDR like `1.0.0.0/24`) still work on mobile, because the management server observes that source IP itself. For mobile-only deployments that need country-level restrictions, **Geolocation** remains a good alternative.
|
||||
On Android, the **Peer Network Range (CIDR)** posture check cannot evaluate the device's local network interfaces, so ranges intended to match local LANs (e.g. `192.168.1.0/24`) will not match. The same applies to iOS clients older than 0.69.0. Ranges that target the peer's **public connection IP** (e.g. `203.0.113.10/32` or a public CIDR like `1.0.0.0/24`) still work on every platform, because the management server observes that source IP itself. For mobile-only deployments that need country-level restrictions, **Geolocation** remains a good alternative. See [Peer Network Range Check on Android](/manage/access-control/posture-checks#peer-network-range-check-on-android) for details.
|
||||
</Note>
|
||||
|
||||
Example posture combinations:
|
||||
|
||||
Reference in New Issue
Block a user