-
Notifications
You must be signed in to change notification settings - Fork 90
Add bypass docs #577
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
mlsmaycon
wants to merge
5
commits into
main
Choose a base branch
from
add-force-approval
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+192
−1
Open
Add bypass docs #577
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
Binary file added
BIN
+72.7 KB
...ntrol/endpoint-detection-and-response/bypass-compliance/batch-bypass-button.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+292 KB
...cess-control/endpoint-detection-and-response/bypass-compliance/batch-bypass.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+64.5 KB
...ndpoint-detection-and-response/bypass-compliance/batch-revoke-bypass-button.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+291 KB
...ntrol/endpoint-detection-and-response/bypass-compliance/batch-revoke-bypass.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+77.8 KB
...ess-control/endpoint-detection-and-response/bypass-compliance/bypass-button.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+189 KB
...s-control/endpoint-detection-and-response/bypass-compliance/bypassed-filter.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+243 KB
...cess-control/endpoint-detection-and-response/bypass-compliance/general-view.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+71.3 KB
...ess-control/endpoint-detection-and-response/bypass-compliance/revoke-bypass.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
167 changes: 167 additions & 0 deletions
167
...ges/manage/access-control/endpoint-detection-and-response/bypass-compliance.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,167 @@ | ||
| # Bypass Compliance for Non-Compliant Peers | ||
|
|
||
| In some situations, you may need to grant network access to a peer that fails EDR or MDM compliance checks. NetBird provides a **compliance bypass** mechanism that allows administrators to override compliance rejections on a per-peer basis. | ||
|
|
||
| ## When to Use Compliance Bypass | ||
|
|
||
| Compliance bypass is useful in scenarios such as: | ||
|
|
||
| - **Temporary exceptions**: A device needs immediate network access while compliance issues are being resolved. | ||
| - **Testing and development**: Test devices that may not have EDR agents installed. | ||
| - **Legacy devices**: Older devices that cannot run the required EDR agent but still need limited network access. | ||
| - **False positives**: When the EDR platform incorrectly flags a compliant device. | ||
|
|
||
| <Note> | ||
| Compliance bypass should be used sparingly and only when necessary. It bypasses security controls designed to protect your network. | ||
| </Note> | ||
|
|
||
| ## How Compliance Bypass Works | ||
|
|
||
| When you bypass compliance for a peer: | ||
|
|
||
| 1. The peer immediately gains network access, regardless of its compliance status. | ||
| 2. The bypass remains active until: | ||
| - An administrator manually revokes it, OR | ||
| - The device becomes naturally compliant in the EDR system (bypass is automatically removed) | ||
| 3. All bypass actions are logged in the [Activity Events](/manage/activity-events) for audit purposes. | ||
|
|
||
| ## Bypass Compliance for a Peer | ||
|
|
||
| To bypass compliance for a non-compliant peer: | ||
|
|
||
| 1. Navigate to the [Peers](https://app.netbird.io/peers) page in the NetBird dashboard | ||
| 2. Locate the peer showing `Non-compliant` status (red badge) | ||
| 3. Hover over the **Bypass** button to see which integration's compliance check will be bypassed | ||
| <p> | ||
| <img src="/docs-static/img/manage/access-control/endpoint-detection-and-response/bypass-compliance/general-view.png" alt="Bypass view" className="imagewrapper-big"/> | ||
| </p> | ||
| 4. Click the **Bypass** button and confirm the action in the dialog | ||
|
|
||
| <p> | ||
| <img src="/docs-static/img/manage/access-control/endpoint-detection-and-response/bypass-compliance/bypass-button.png" alt="Bypass confirm button" className="imagewrapper"/> | ||
| </p> | ||
|
|
||
| The peer will immediately gain network access and the non-compliant status will be replaced with a green `Bypassed` badge. | ||
|
|
||
| ## View Bypassed Peers | ||
|
|
||
| To see all peers that have compliance bypassed: | ||
|
|
||
| 1. Navigate to the [Peers](https://app.netbird.io/peers) page | ||
| 2. Click the **Bypassed** filter button (shows a count badge with the number of bypassed peers) | ||
|
|
||
| <p> | ||
| <img src="/docs-static/img/manage/access-control/endpoint-detection-and-response/bypass-compliance/bypassed-filter.png" alt="Bypassed filter button" className="imagewrapper-big"/> | ||
| </p> | ||
|
|
||
| The filter can be combined with connection status filters: | ||
| - Click **Online** + **Bypassed** to see only online bypassed peers | ||
| - Click **Offline** + **Bypassed** to see only offline bypassed peers | ||
|
|
||
| Hovering over the filter buttons shows helpful tooltips: | ||
| - **Non-Compliant**: "Peers that failed compliance checks and need attention" | ||
| - **Bypassed**: "Peers with compliance checks bypassed by an administrator" | ||
|
|
||
| ## Revoke Compliance Bypass | ||
|
|
||
| To revoke a bypass and return a peer to normal compliance validation: | ||
|
|
||
| 1. Navigate to the [Peers](https://app.netbird.io/peers) page | ||
| 2. Click on the peer with bypassed compliance | ||
| 3. Click the **Revoke** button next to the "Bypassed" badge | ||
| 4. Confirm the action | ||
|
|
||
| <p> | ||
| <img src="/docs-static/img/manage/access-control/endpoint-detection-and-response/bypass-compliance/revoke-bypass.png" alt="Revoke compliance bypass" className="imagewrapper"/> | ||
| </p> | ||
|
|
||
| Once revoked, the peer will be subject to normal compliance checks. If the device is still non-compliant, it will lose network access and show the `Non-compliant` status again. | ||
|
|
||
| ## Batch Operations | ||
|
|
||
| You can bypass compliance or revoke bypass for multiple peers at once: | ||
|
|
||
| ### Batch Bypass | ||
|
|
||
| 1. Navigate to the [Peers](https://app.netbird.io/peers) page | ||
| 2. Select multiple peers using the checkboxes (peers must have non-compliant status) | ||
| <p> | ||
| <img src="/docs-static/img/manage/access-control/endpoint-detection-and-response/bypass-compliance/batch-bypass.png" alt="Batch bypass" className="imagewrapper-big"/> | ||
| </p> | ||
| 3. In the action bar that appears at the bottom, click the **Bypass Compliance** button (shield icon) | ||
| 4. Confirm the action in the dialog | ||
|
|
||
| <p> | ||
| <img src="/docs-static/img/manage/access-control/endpoint-detection-and-response/bypass-compliance/batch-bypass-button.png" alt="Batch bypass confirm" className="imagewrapper"/> | ||
| </p> | ||
|
|
||
| The button shows a count of how many selected peers will have compliance bypassed. | ||
|
|
||
| ### Batch Revoke Bypass | ||
|
|
||
| 1. Navigate to the [Peers](https://app.netbird.io/peers) page | ||
| 2. Select multiple bypassed peers using the checkboxes | ||
| <p> | ||
| <img src="/docs-static/img/manage/access-control/endpoint-detection-and-response/bypass-compliance/batch-revoke-bypass.png" alt="Batch revoke bypass" className="imagewrapper-big"/> | ||
| </p> | ||
| 3. In the action bar that appears at the bottom, click the **Revoke Compliance Bypass** button (shield-off icon) | ||
| 4. Confirm the action in the dialog | ||
|
|
||
| <p> | ||
| <img src="/docs-static/img/manage/access-control/endpoint-detection-and-response/bypass-compliance/batch-revoke-bypass-button.png" alt="Batch revoke bypass confirm" className="imagewrapper"/> | ||
| </p> | ||
|
|
||
| <Note> | ||
| Batch operation buttons only appear when you have an EDR integration enabled and have selected peers that can have compliance bypassed or revoked. | ||
| </Note> | ||
|
|
||
| ## Automatic Removal of Bypass | ||
|
|
||
| Compliance bypass is automatically removed when a device becomes naturally compliant in your EDR platform. This ensures that: | ||
|
|
||
| - Devices don't retain unnecessary administrative overrides | ||
| - Your security posture improves as devices become compliant | ||
| - You don't need to manually clean up bypasses | ||
|
|
||
| For example, if you bypass compliance for a peer because its EDR agent was temporarily offline, the bypass will be automatically removed once the agent reconnects and the device passes compliance checks. | ||
|
|
||
| ## Activity Logging | ||
|
|
||
| All compliance bypass actions are recorded in the activity log: | ||
|
|
||
| | Event | Description | | ||
| |-------|-------------| | ||
| | `Peer compliance bypassed by admin` | An administrator bypassed compliance for a peer | | ||
| | `Peer compliance bypass revoked` | An administrator or the system removed the bypass | | ||
|
|
||
| You can view these events in the [Activity Events](/manage/activity-events) page, including details about which administrator performed the action and the original rejection reason. | ||
|
|
||
| ## API Access | ||
|
|
||
| Compliance bypass can also be managed via the NetBird API: | ||
|
|
||
| ```bash | ||
| # Bypass compliance for a peer | ||
| curl -X POST "https://api.netbird.io/api/peers/{peer-id}/edr/bypass" \ | ||
| -H "Authorization: Token <your-api-token>" | ||
|
|
||
| # Revoke compliance bypass | ||
| curl -X DELETE "https://api.netbird.io/api/peers/{peer-id}/edr/bypass" \ | ||
| -H "Authorization: Token <your-api-token>" | ||
|
|
||
| # List all bypassed peers | ||
| curl -X GET "https://api.netbird.io/api/peers/edr/bypassed" \ | ||
| -H "Authorization: Token <your-api-token>" | ||
| ``` | ||
|
|
||
| ## Best Practices | ||
|
|
||
| - **Document exceptions**: Keep a record of why each compliance bypass was granted. | ||
| - **Review regularly**: Periodically review bypassed peers and revoke bypasses that are no longer needed. | ||
| - **Use time-limited access**: Consider revoking bypasses after a defined period. | ||
| - **Monitor activity**: Watch for unusual patterns in bypass usage. | ||
| - **Prefer compliance**: Always aim to bring devices into compliance rather than relying on bypasses. | ||
|
|
||
| <Note> | ||
| Compliance bypass requires the `EDR Update` permission. Only users with appropriate roles can bypass compliance or revoke bypasses. | ||
| </Note> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add a new one: when yo uwant to combine automated and manual approval