Posture checks allow you to verify that devices meet your security requirements before they can access network resources. NetBird evaluates device state and configuration to ensure compliance with your security policies.
Overview Posture checks enable zero-trust security by continuously validating device security posture. Only devices that pass all configured checks can access protected resources.
Posture checks are evaluated in real-time. If a device falls out of compliance, network access is automatically restricted.
Available Posture Check Types NetBird supports five types of posture checks:
NetBird Version Ensure peers run a minimum NetBird client version
OS Version Require minimum operating system or kernel versions
Geolocation Allow or deny access based on geographic location
Peer Network Range Restrict based on the peer’s local network address
Process Running Verify specific security software is running
NetBird Version Check Ensure all peers are running a minimum version of the NetBird client.
Configuration { "Name" : "Minimum NetBird Version" , "Description" : "Require NetBird 0.24.0 or higher" , "Checks" : { "NBVersionCheck" : { "MinVersion" : "0.24.0" } } }
Use Cases
Enforce security patches and bug fixes
Ensure compatibility with new features
Phase out deprecated client versions
Maintain consistent security capabilities
Version strings must be valid semantic versions (e.g., 0.24.0). Pre-release tags like -dev or -alpha are automatically sanitized during comparison.
OS Version Check Require minimum operating system or kernel versions across different platforms.
Supported Operating Systems Android
iOS
macOS
Linux
Windows
{ "OSVersionCheck" : { "Android" : { "MinVersion" : "11.0" } } }
Checks Android OS version (e.g., Android 11, 12, 13). { "OSVersionCheck" : { "Ios" : { "MinVersion" : "15.0" } } }
Checks iOS version (e.g., iOS 15, 16, 17). { "OSVersionCheck" : { "Darwin" : { "MinVersion" : "12.0" } } }
Checks macOS version (Darwin kernel version corresponds to macOS release). { "OSVersionCheck" : { "Linux" : { "MinKernelVersion" : "5.10" } } }
Checks Linux kernel version. The version before the first hyphen is used (e.g., 5.10.0-21-generic → 5.10.0). { "OSVersionCheck" : { "Windows" : { "MinKernelVersion" : "10.0.19041" } } }
Checks Windows kernel version (e.g., 10.0.19041 for Windows 10 version 2004). You can specify requirements for multiple platforms in a single check:
{ "Name" : "Minimum OS Versions" , "Description" : "Enforce modern OS versions across all platforms" , "Checks" : { "OSVersionCheck" : { "Android" : { "MinVersion" : "11.0" }, "Ios" : { "MinVersion" : "15.0" }, "Darwin" : { "MinVersion" : "12.0" }, "Linux" : { "MinKernelVersion" : "5.10" }, "Windows" : { "MinKernelVersion" : "10.0.19041" } } } }
At least one OS must be specified. Peers running operating systems not listed in the check will be denied access.
Geolocation Check Control access based on the peer’s geographic location using country codes and city names.
Configuration { "Name" : "Allowed Locations" , "Description" : "Only allow access from specific countries" , "Checks" : { "GeoLocationCheck" : { "Action" : "allow" , "Locations" : [ { "CountryCode" : "US" }, { "CountryCode" : "GB" , "CityName" : "London" }, { "CountryCode" : "DE" , "CityName" : "Berlin" } ] } } }
Actions Allow action grants access only to peers in specified locations:{ "Action" : "allow" , "Locations" : [ { "CountryCode" : "US" } ] }
Peers in listed locations: Access granted
Peers in other locations: Access denied
Deny action blocks access from specified locations:{ "Action" : "deny" , "Locations" : [ { "CountryCode" : "CN" }, { "CountryCode" : "RU" } ] }
Peers in listed locations: Access denied
Peers in other locations: Access granted
Location Specification Country Code (required):
2-letter ISO 3166-1 alpha-2 format
Examples: US, GB, DE, JP, AU
City Name (optional):
Commonly used English city name
When specified, both country and city must match
Example: "CountryCode": "US", "CityName": "New York"
Peers must have location information available. If location cannot be determined, access is denied for security.
Peer Network Range Check Restrict access based on the peer’s local network address ranges.
Configuration { "Name" : "Corporate Network Only" , "Description" : "Allow only devices on corporate networks" , "Checks" : { "PeerNetworkRangeCheck" : { "Action" : "allow" , "Ranges" : [ "10.0.0.0/8" , "172.16.0.0/12" , "192.168.1.0/24" ] } } }
Actions Grant access only to peers on specified networks: { "Action" : "allow" , "Ranges" : [ "192.168.1.0/24" ] }
Peer on 192.168.1.x: Access granted
Peer on other networks: Access denied
Block access from specified networks: { "Action" : "deny" , "Ranges" : [ "10.99.0.0/16" ] }
Peer on 10.99.x.x: Access denied
Peer on other networks: Access granted
Use Cases
Require VPN or office network connectivity
Block access from public WiFi networks
Enforce network segmentation policies
Prevent access from untrusted network ranges
Network ranges are specified using CIDR notation (e.g., 192.168.1.0/24). The check compares the peer’s local network addresses against the masked prefixes.
Process Check Verify that specific security software or processes are running on the peer device.
Configuration { "Name" : "Required Security Software" , "Description" : "Ensure endpoint protection is active" , "Checks" : { "ProcessCheck" : { "Processes" : [ { "LinuxPath" : "/usr/bin/antivirus-daemon" , "MacPath" : "/Applications/SecuritySoftware.app/Contents/MacOS/daemon" , "WindowsPath" : "C: \\ Program Files \\ SecuritySoftware \\ agent.exe" } ] } } }
Process Specification Each process can have platform-specific paths:
| Platform | Field | Example |
|----------|-------|---------||
| Linux | LinuxPath | /usr/sbin/security-agent |
| macOS | MacPath | /Library/Application Support/Security/agent |
| Windows | WindowsPath | C:\\Program Files\\Security\\agent.exe |
Use double backslashes (\\) for Windows paths in JSON configuration.
Multiple Processes Require multiple security tools to be running:
{ "ProcessCheck" : { "Processes" : [ { "LinuxPath" : "/usr/bin/antivirus" , "MacPath" : "/Applications/Antivirus.app/Contents/MacOS/antivirus" , "WindowsPath" : "C: \\ Program Files \\ Antivirus \\ av.exe" }, { "LinuxPath" : "/usr/sbin/firewall-daemon" , "MacPath" : "/Library/Firewall/daemon" , "WindowsPath" : "C: \\ Windows \\ System32 \\ firewall.exe" }, { "LinuxPath" : "/opt/edr/agent" , "MacPath" : "/Applications/EDR.app/Contents/MacOS/agent" , "WindowsPath" : "C: \\ Program Files \\ EDR \\ agent.exe" } ] } }
All specified processes must be running for the check to pass. At least one platform path must be specified per process.
Combining Multiple Checks Create comprehensive security policies by combining multiple posture check types:
{ "Name" : "Production Access Requirements" , "Description" : "Strict security requirements for production environment access" , "Checks" : { "NBVersionCheck" : { "MinVersion" : "0.24.0" }, "OSVersionCheck" : { "Windows" : { "MinKernelVersion" : "10.0.19041" }, "Darwin" : { "MinVersion" : "12.0" }, "Linux" : { "MinKernelVersion" : "5.10" } }, "GeoLocationCheck" : { "Action" : "allow" , "Locations" : [ { "CountryCode" : "US" }, { "CountryCode" : "GB" } ] }, "PeerNetworkRangeCheck" : { "Action" : "allow" , "Ranges" : [ "10.0.0.0/8" , "192.168.0.0/16" ] }, "ProcessCheck" : { "Processes" : [ { "LinuxPath" : "/usr/bin/endpoint-security" , "MacPath" : "/Applications/Security.app/Contents/MacOS/security" , "WindowsPath" : "C: \\ Program Files \\ Security \\ endpoint.exe" } ] } } }
When multiple check types are defined, all checks must pass for the peer to gain access. This creates an AND relationship between checks.
Managing Posture Checks Creating a Posture Check
Define Requirements
Identify the security requirements for your environment.
Create Check Configuration
Use the API or UI to create a posture check with your requirements.
Test with Limited Scope
Apply the check to a small group first to verify it works as expected.
Monitor Compliance
Review which peers pass or fail the check.
Roll Out
Apply the check to broader peer groups or network policies.
Validation Rules Posture checks must meet these requirements:
Name : Cannot be emptyChecks : At least one check type must be definedVersion formats : Must be valid semantic versionsCountry codes : Must be 2-letter ISO 3166-1 alpha-2 formatNetwork ranges : Must be valid CIDR notationProcess paths : At least one platform path required per process
Troubleshooting
Peer Failing Unexpected Checks
Diagnosis:
Check peer metadata to see reported values
Review peer logs for check evaluation details
Verify check configuration matches intent
Common causes:
Outdated peer information
Incorrect version format or comparison
Location data not available
Process path mismatch
Possible issues:
Peer location not being determined
GeoIP database out of date
Peer behind VPN/proxy obscuring location
Solutions:
Verify peer has valid external IP
Update GeoIP database if self-hosted
Consider network range checks instead for VPN users
Process Check Always Failing
Verification steps:
Check exact process path on target system
Ensure process is actually running
Verify path formatting (especially Windows backslashes)
Check file permissions for NetBird to query processes
Platform-specific:
Linux : Process must be visible in peer’s process listmacOS : May require additional permissions for process enumerationWindows : Ensure correct case and escaped backslashes Best Practices
Start Permissive
Begin with lenient requirements and gradually tighten based on compliance data.
Layer Defenses
Use multiple complementary check types for defense in depth.
Plan for Exceptions
Have a process for temporary exceptions during incidents or maintenance.
Monitor Continuously
Set up alerting for sudden drops in compliance rates.
Communicate Changes
Notify users before enforcing new posture requirements.
Document Requirements
Maintain clear documentation of why each check exists and what it protects.
Next Steps
Access Policies Apply posture checks to network policies
Quantum Resistance Enable post-quantum cryptography
