sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-10-19 03:59:05 +02:00
Code Issues Packages Projects Releases Wiki Activity

Restructuring Phase 3 (#492)

Browse Source
This commit is contained in:
Brandon Hopkins
2025-11-24 18:25:44 +01:00
committed by GitHub
parent c40c132caa
commit 0080ae97df
477 changed files with 800 additions and 564 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/pages/manage/activity/event-streaming/amazon-firehose.mdx
+69
View File
@@ -0,0 +1,69 @@
# Stream Network Activity to Amazon Data Firehose
[Amazon Data Firehose](https://docs.aws.amazon.com/firehose/) is a fully managed service for delivering real-time streaming data to destinations such as Amazon Simple Storage Service (Amazon S3), Amazon Redshift,
an other AWS services. You can use Amazon Data Firehose as a bridge between NetBird and other third-party providers that support Data Firehose
to ingest, transform and analyze your network activity events.
<Note>
This feature is only available in the cloud version of NetBird.
</Note>
## Prerequisites
Before you start creating and configuring an Amazon Data Firehose event streaming integration, ensure that you have the following:
- An AWS account with the permissions to create and manage Data Firehose delivery streams.
- Permissions to create and manage IAM users, roles and policies.
If you don't have the required permissions, ask your AWS administrator to grant them to you.
## Create a Data Firehose Stream
- Navigate to the [Data Firehose Dashboard](https://console.aws.amazon.com/firehose/home)
- Click `Create Firehose stream`
- As source select `Direct PUT` and the desired destination
- Give it a descriptive name like `netbird-activity-events` and configure the stream to your needs
## Create an IAM User
- Navigate to the [IAM Dashboard](https://console.aws.amazon.com/iam/home)
- Create an IAM User (for details see the [Amazon Docs](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html))
- Create a custom policy with the following permissions (replace the resource with the ARN of your delivery stream):
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"firehose:PutRecord",
"firehose:PutRecordBatch"
],
"Resource": "arn:aws:firehose:region:accountID:deliverystream/netbird-event-streaming"
}
]
}
```
- Attach the policy to the IAM user
- Select the user and navigate to the `Security credentials` tab
- Click `Create access key`
- Select `Third-party service` and click `Next`
- Give it a description
- Store `Access key` and `Secret access key` in a secure place. You will need these when configuring an integration in NetBird.
## Create an Integration in NetBird
- Navigate to the [Integrations &raquo; Event Streaming](https://preview.netbird.io/integrations) tab in the NetBird dashboard
<p>
<img src="/docs-static/img/manage/activity/event-streaming/event-streaming-integration.png" alt="event-streaming-integration" className="imagewrapper-big"/>
</p>
- Enable and configure the `Amazon Data Firehose` integration
- First select the region your Firehose stream is created in
<p>
<img src="/docs-static/img/manage/activity/event-streaming/amazon-firehose/firehose-region-select.png" alt="firehose-region-select" className="imagewrapper" />
</p>
- Then enter the Firehose stream name you created in [Step 1](#step-1-create-a-data-firehose-stream) and click `Next`
<p>
<img src="/docs-static/img/manage/activity/event-streaming/amazon-firehose/firehose-stream-name.png" alt="firehose-stream-name" className="imagewrapper" />
</p>
- Enter the `Access key` and `Secret access key` you created in [Step 2](#step-2-create-an-iam-user-2) and click `Connect`
<p>
<img src="/docs-static/img/manage/activity/event-streaming/amazon-firehose/firehose-iam-credentials.png" alt="firehose-iam-credentials" className="imagewrapper" />
</p>
src/pages/manage/activity/event-streaming/amazon-s3.mdx
+119
View File
@@ -0,0 +1,119 @@
# Stream Network Activity to Amazon S3
[Amazon Simple Storage Service (Amazon S3)](https://aws.amazon.com/s3/) is a scalable, high-speed, web-based cloud storage service.
You can use Amazon S3 to store and analyze large amounts of data, including network activity events from NetBird.
NetBird integrates with Amazon S3 and sends activity events to an S3 bucket in real-time once they occur. For every event,
NetBird creates a new object in the S3 bucket, which you can then analyze, filter, and query using Amazon tools.
Storing one event per object is not the most efficient way to save data in S3, therefore NetBird provides an
[alternative integration](/manage/activity/event-streaming/amazon-firehose) that uses Amazon Data Firehose for a more efficient
data ingestion.
<Note>
This feature is only available in the cloud version of NetBird.
</Note>
## Prerequisites
Before you start creating and configuring an Amazon S3 event streaming integration, ensure that you have the following:
- An AWS account with the permissions to create and manage S3 buckets.
- Permissions to create and manage IAM users, roles and policies.
If you don't have the required permissions, ask your AWS administrator to grant them to you.
## Create an S3 Bucket
- Navigate to the [S3 dashboard](https://console.aws.amazon.com/s3/home)
- Select the correct region in the top menu
- Click `Create bucket`
- Give it a descriptive name like `netbird-activity-events`
- (Optional) Change bucket configurations to your needs
- Click `Create bucket`
## Create an IAM User
- Navigate to the [IAM Dashboard](https://console.aws.amazon.com/iam/home)
- Create an IAM User (for details see the [Amazon Docs](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html))
- Create a custom policy with the following permissions:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::netbird-activity-events/*"
}
]
}
```
- Attach the policy to the IAM user
- Select the user and navigate to the `Security credentials` tab
- Click `Create access key`
- Select `Third-party service` and click `Next`
- Give it a description
- Store `Access key` and `Secret access key` in a secure place. You will need these when configuring an integration in NetBird.
## Create an Integration in NetBird
- Navigate to the [Integrations &raquo; Event Streaming](https://preview.netbird.io/integrations) tab in the NetBird dashboard
<p>
<img src="/docs-static/img/manage/activity/event-streaming/event-streaming-integration.png" alt="event-streaming-integration" className="imagewrapper-big"/>
</p>
- Enable and configure the `Amazon S3` integration
- First select the region your S3 bucket is created in
<p>
<img src="/docs-static/img/manage/activity/event-streaming/amazon-s3/s3-region-select.png" alt="s3-region-select" className="imagewrapper" />
</p>
- Then enter the S3 bucket name you created in [Step 1](#step-1-create-an-s3-bucket) and click `Next`
<p>
<img src="/docs-static/img/manage/activity/event-streaming/amazon-s3/s3-bucket-name.png" alt="s3-bucket-name" className="imagewrapper"/>
</p>
- Enter the `Access key` and `Secret access key` you created in [Step 2](#step-2-create-an-iam-user) and click `Connect`
<p>
<img src="/docs-static/img/manage/activity/event-streaming/amazon-s3/s3-iam-credentials.png" alt="s3-iam-credentials" className="imagewrapper" />
</p>
## Verify the Integration
After configuring the integration in NetBird, you can verify that the integration is working correctly by checking
the S3 bucket for newly created objects. If the integration is successful, you should see two `.json` files in your bucket
containing the following events:
- `integration test`
- `integration created`
<p>
<img src="/docs-static/img/manage/activity/event-streaming/amazon-s3/verify-amazon-s3-integration.png" alt="verify-amazon-s3-integration" className="imagewrapper-big" />
</p>
```json
{
"timestamp": "2024-04-11T19:01:05.381074+02:00",
"message": "integration test",
"id": 0,
"initiator_id": "netbird",
"target_id": "netbird",
"meta": null,
"reference": ""
}
```
```json
{
"timestamp": "2024-04-11T19:01:08.769292+02:00",
"message": "integration created",
"id": 0,
"initiator_id": "netbird",
"target_id": "netbird",
"meta": null,
"reference": ""
}
```
The integration test event is sent to validate whether the provided credentials are correct and NetBird can stream events.
The integration created event is sent when the integration is successfully created.
The integration is now set up and ready to stream network activity events to Amazon S3.
src/pages/manage/activity/event-streaming/datadog.mdx
+59
View File
@@ -0,0 +1,59 @@
# Stream Network Activity to Datadog Cloud SIEM
Datadog is a monitoring and analytics platform for cloud-scale applications. Datadog Cloud SIEM provides real-time threat
detection and security monitoring for cloud environments. By using the NetBird-Datadog integration, you can stream [network activity](/manage/activity/traffic-events-logging) to Datadog Cloud SIEM for real-time monitoring
and threat detection across your private network.
NetBird integrates with Datadog using the [Datadog Log Collection HTTP API](https://docs.datadoghq.com/api/latest/logs/#send-logs)
and sends activity events to Datadog in real-time once they occur. The events appear in the [Datadog Log Explorer](https://docs.datadoghq.com/logs/explorer/), where you can
search, filter, and analyze them right away.
<Note>
This feature is only available in the cloud version of NetBird.
</Note>
## Prerequisites
Before you start creating and configuring a Datadog event streaming integration, ensure that you have the following:
- A Datadog account with permissions to create and manage API keys. If you don't have the required permissions,
ask your Datadog administrator to grant them to you.
## Create a Datdog API Key
- Navigate to the [API Keys](https://app.datadoghq.eu/organization-settings/api-keys) page
- Click `+ New Key` at the top
- Give it a descriptive name like `NetBird Event Streaming`
- Click `Create Key`
- Copy the key. You will need this key when configuring an integration in NetBird.
## Create an Integration in NetBird
- Navigate to the [Integrations &raquo; Event Streaming](https://preview.netbird.io/integrations) tab in the NetBird Dashboard
<p>
<img src="/docs-static/img/manage/activity/event-streaming/event-streaming-integration.png" alt="event-streaming-integration" className="imagewrapper-big"/>
</p>
- Enable and configure the Datadog integration
- First select the region of your Datadog account (for more details see [Datadog Documentation](https://docs.datadoghq.com/getting_started/site/))
<p>
<img src="/docs-static/img/manage/activity/event-streaming/datadog/datadog-region-select.png" alt="datadog-region-select" className="imagewrapper" />
</p>
- Then enter the API key you created in [Step 1](#step-1-create-a-datdog-api-key) and click `Connect`
<p>
<img src="/docs-static/img/manage/activity/event-streaming/datadog/datadog-api-key.png" alt="datadog-api-key" className="imagewrapper" />
</p>
## Verify the Integration
After configuring the Datadog integration in NetBird, you can verify that the integration is working correctly by checking
the Datadog Log Explorer for incoming events. If the integration is successful, you should see two events from the netbird service
in the Log Explorer:
- `integration test`
- `integration created`
<p>
<img src="/docs-static/img/manage/activity/event-streaming/datadog/verify-datadog-integration.png" alt="verify-datadog-integration" className="imagewrapper"/>
</p>
The `integration test` event is sent to validate whether the provided credentials are correct and NetBird can stream events.
The `integration created` event is sent when the integration is successfully created.
The integration is now set up and ready to stream network activity events to Datadog.
src/pages/manage/activity/event-streaming/generic-http.mdx
+102
View File
@@ -0,0 +1,102 @@
# Stream Network Activity to a Generic HTTP Endpoint
The Generic HTTP integration allows you to stream your NetBird network activity events to any custom HTTP/S endpoint. This provides a flexible way to connect NetBird with a wide range of third-party systems, including custom SIEMs, log management tools like Grafana Loki, or any service that can receive POST requests.
For every event, NetBird will send a POST request to your configured endpoint. You have full control over the request's body format and headers, allowing for seamless integration with various APIs.
<Note>
This feature is only available in the cloud version of NetBird.
</Note>
## Prerequisites
Before you start, ensure you have an HTTP/S endpoint that is publicly accessible and ready to receive POST requests from NetBird. You will also need any necessary authentication details, such as an API key or credentials for Basic Authentication.
## Create an Integration in NetBird
1. Navigate to the **Integrations** tab in the NetBird dashboard and select **Event Streaming**.
2. Find the **Generic HTTP** option and click **Connect**.
3. A configuration panel will open with several tabs: **General**, **Headers**, **Body Template**, and **Danger Zone**.
### General Configuration
This tab is for the essential endpoint details.
<p>
<img src="/docs-static/img/manage/activity/event-streaming/generic-http/general-config.png" alt="Generic HTTP General Configuration" className="imagewrapper-big"/>
</p>
- **Endpoint URL**: Enter the full HTTPS or HTTP URL where NetBird should send the events. This field is mandatory.
- **Authentication**: Select the authentication method required by your endpoint.
- **No Authentication**: Sends requests without an `Authorization` header.
- **Bearer Token**: Adds an `Authorization: Bearer <your-token>` header to each request. You will need to provide your API key or token.
- **Basic Auth**: Adds an `Authorization: Basic <credentials>` header. You must provide the credentials in the format `username:password`.
- **Custom Authentication**: Allows you to specify a custom HTTP header for authentication. You will need to provide both the header name (e.g., `X-API-Key`) and its value.
<Note>
After saving the integration, the configured authentication details will be converted into an HTTP header and will appear in the **Headers** tab.
</Note>
### HTTP Headers (Optional)
You can add custom HTTP headers to every outgoing request in the **Headers** tab. This is useful for passing static tokens, setting a custom `Content-Type`, or other API requirements. By default, the `Content-Type` is `application/json`.
<p>
<img src="/docs-static/img/manage/activity/event-streaming/generic-http/headers-config.png" alt="Generic HTTP Headers Configuration" className="imagewrapper-big"/>
</p>
### Custom Body Template (Optional)
The **Body Template** tab gives you powerful control over the structure of the JSON payload sent to your endpoint.
<p>
<img src="/docs-static/img/manage/activity/event-streaming/generic-http/body-template-config.png" alt="Generic HTTP Body Template Configuration" className="imagewrapper-big"/>
</p>
If this option is disabled, NetBird sends a default JSON object for each event. When enabled, you can define your own payload structure using Go's `text/template` templating engine.
This is especially useful for integrating with services that expect a specific format, like Grafana Loki.
#### Available Template Variables
You can use the following variables from the `StreamEvent` object in your template:
| Variable | Type | Description | Example Usage |
|---------------|----------------------|--------------------------------------------------------------------------------------|-----------------------------------|
| `.ID` | `any` | The unique ID of the event. | `{"event_id": "{{.ID}}"}` |
| `.Timestamp` | `time.Time` | The timestamp of when the event occurred. Can be formatted. | `{{.Timestamp.UnixNano}}` / `{{.Timestamp.Format "2006-01-02T15:04:05.999Z07:00"}}` |
| `.Message` | `string` | A human-readable message describing the event. | `{"text": "{{.Message}}"}` |
| `.InitiatorID`| `string` | The ID of the object that initiated the event (e.g., a user or peer ID). | `{"user": "{{.InitiatorID}}"}` |
| `.TargetID` | `string` | The ID of the object that was affected by the event (e.g., a peer or group ID). | `{"resource": "{{.TargetID}}"}` |
| `.Meta` | `map[string]any` | A map containing additional metadata about the event. | `{"source": "{{.Meta.source}}"}` |
| `.Reference` | `string` | A URL to the event in the NetBird activity log for easy cross-referencing. | `{"ref": "{{.Reference}}"}` |
### Danger Zone
This tab allows you to delete the integration. This action is irreversible and will immediately stop events from being sent to your endpoint.
<p>
<img src="/docs-static/img/manage/activity/event-streaming/generic-http/danger-zone.png" alt="Generic HTTP Danger Zone" className="imagewrapper-big"/>
</p>
After configuring all settings, click **Save Changes**.
## Verify the Integration
Once you save the integration, NetBird sends a test event to your endpoint to confirm that the connection and authentication are successful.
Check the logs of your receiving service for a new POST request. You should find a JSON payload similar to this (if custom template wasn't set up):
```json
{
"ID": "test-event-1685635200",
"Timestamp": "2025-06-01T16:00:00Z",
"Message": "integration test event for generic http endpoint",
"InitiatorID": "netbird-test-system",
"TargetID": "target-id",
"Meta": {
"purpose": "configuration-test",
"source": "netbird-test"
},
"Reference": "netbird:test:generichttp"
}
src/pages/manage/activity/event-streaming/index.mdx
+25
View File
@@ -0,0 +1,25 @@
# Stream Network Activity to Third-Party SIEM Platforms
<p>
<img src="/docs-static/img/manage/activity/event-streaming/event-streaming-integration.png" alt="event-streaming-integration" className="imagewrapper-big"/>
</p>
Security Information and Event Management (SIEM) systems play a critical role in network security by monitoring,
detecting, and responding to security threats in real-time. By aggregating and analyzing activity across the network,
SIEMs help identify anomalous patterns and potential breaches, providing a centralized view of security events.
NetBird provides an event streaming feature that allows you to stream network [activity events](/manage/activity/traffic-events-logging)
to third-party SIEM systems, such as [Datadog](https://www.datadoghq.com/dg/security/siem-solution/), [Amazon S3](https://aws.amazon.com/s3/), [Amazon Data Firehose](https://aws.amazon.com/firehose/), and others through a generic HTTP integration.
<Note>
This feature is only available in the cloud version of NetBird.
</Note>
This documentation provides step-by-step guides and best practices for integrating NetBird activity event streaming with
supported third-party platforms. To get started, select one of the following integrations:
- [Datadog](/manage/activity/event-streaming/datadog)
- [Amazon S3](/manage/activity/event-streaming/amazon-s3)
- [Amazon Data Firehose](/manage/activity/event-streaming/amazon-firehose)
- [SentinelOne Data Lake](/manage/activity/event-streaming/sentinelone-data-lake)
- [Generic HTTP](/manage/activity/event-streaming/generic-http)
src/pages/manage/activity/event-streaming/sentinelone-data-lake.mdx
+77
View File
@@ -0,0 +1,77 @@
# Stream Network Activity to SentinelOne Singularity Data Lake
[SentinelOne Singularity Data Lake](https://www.sentinelone.com/platform/data-lake/) provides a centralized repository for storing and analyzing security data across your organization. By streaming NetBird network activity events to SentinelOne Data Lake, you can correlate network connectivity events with endpoint security data for comprehensive threat detection and investigation.
This integration leverages NetBird's Generic HTTP streaming capability with SentinelOne Singularity Data Lake-specific configurations to ensure seamless data ingestion into your Data Lake environment.
<Note>
This feature is only available in the cloud version of NetBird.
</Note>
## Prerequisites
Before you start creating and configuring a SentinelOne Singularity Data Lake event streaming integration, ensure that you have the following:
- A SentinelOne account with Singularity Data Lake access and appropriate permissions
- Administrative access to create API keys in your SentinelOne console
## Create a SentinelOne API Token
- Log in to your SentinelOne Management Console and navigate to **Visibility** from the left menu
- Click on your user email dropdown in the top right toolbar and select **API Keys**
- Under the **Log Access Keys** section, click **Add Key** dropdown menu and select **Add Write Key**
- A new API key will be created with access to write logs to Data Lake
- Click **Copy to Clipboard** and store this token securely. You will need this token when configuring the integration in NetBird.
<p>
<img src="/docs-static/img/manage/activity/event-streaming/sentinelone-data-lake/api-key-generation.png" alt="API Key Generation" className="imagewrapper-big"/>
</p>
## Get the HEC Ingestion URL
Navigate to `https://<your-tenant>.sentinelone.net/docs/en/http-event-collector--hec-.html#http-event-collector--hec-` (replace `<your-tenant>` with your actual SentinelOne tenant)
to find and copy the HTTP Event Collector base URL from the documentation page. The URL format will be `https://ingest.<region>.sentinelone.net` where `<region>` is your deployment region.
## Create an Integration in NetBird
- Navigate to the **Integrations** tab in the NetBird dashboard and select **Event Streaming**
- Find the **Generic HTTP** option and click **Connect Generic HTTP**
- Configure the endpoint URL by entering the full HEC endpoint URL: `https://ingest.<region>.sentinelone.net/services/collector/event`
- Select **Bearer Token** for authentication and provide the API token you created earlier
<p>
<img src="/docs-static/img/manage/activity/event-streaming/sentinelone-data-lake/general-settings.png" alt="General Settings Configuration" className="imagewrapper-big"/>
</p>
- Enable the custom body template and use the following template optimized for SentinelOne Singularity Data Lake:
```json
{
"id": "{{.ID}}",
"time": "{{.Timestamp.UnixNano}}",
"event": "{{.Message}}",
"initiator_id": "{{.InitiatorID}}",
"target_id": "{{.TargetID}}",
"host": "netbird",
"source": "netbird",
"sourcetype": "json",
"fields": "{{.Meta}}"
}
```
<p>
<img src="/docs-static/img/manage/activity/event-streaming/sentinelone-data-lake/custom-template.png" alt="Custom Template Configuration" className="imagewrapper-big"/>
</p>
## Verify the Integration
After configuring the SentinelOne Singularity Data Lake integration in NetBird, you can verify that the integration is working correctly by checking the SentinelOne Singularity Data Lake for incoming events. If the integration is successful, you should see test events from NetBird in your Data Lake.
- Navigate to **Data Lake** > **Search** > **New Search** in your SentinelOne console
- Select to search **All Data** and filter for recent events with source **netbird**
- Verify the test events appear with the expected structure
<p>
<img src="/docs-static/img/manage/activity/event-streaming/sentinelone-data-lake/verify-integration.png" alt="Verify Integration" className="imagewrapper-big"/>
</p>
The integration is now set up and ready to stream network activity events to SentinelOne Singularity Data Lake.
src/pages/manage/activity/index.mdx
+136
View File
@@ -0,0 +1,136 @@
# Audit Events Logging
The Audit events logging functionality in NetBird allows you to observe and track changes to your network infrastructure.
This includes events such as when a new machine or user has joined your network, when access control policies have been modified,
and many other key network events.
## Related Video Content
To get started with event logging in NetBird, watch this introductory video:
<iframe width="560" height="315" src="https://www.youtube.com/embed/UlnMo1KYXPU?si=JdzEr9v2EZHlP7lc" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## Access the Audit Events Logging View
The audit events logging feature is enabled by default for every NetBird network. You can access the activity log in the web UI under the [Audit Events tab](https://app.netbird.io/events/audit). This view provides a centralized log of network events. You can use the search bar to search by activity name, and apply filters for timeframes, event types, and users.
<p>
<img src="/docs-static/img/manage/activity/activity-monitoring.png" alt="activity-monitoring" className="imagewrapper-big"/>
</p>
The current version of NetBird tracks a wide range of network changes that occur in the Management server, such as modifications to peers, groups, system settings, setup keys, and access control policies.
<details>
<summary>Click here to view the full list of tracked events</summary>
- **Peer Management:**
- Peer added by user
- Peer added with setup key
- Peer removed by user
- Peer renamed
- Peer SSH server enabled
- Peer SSH server disabled
- Peer login expiration enabled
- Peer login expiration disabled
- **User Management:**
- User joined
- User invited
- User role updated
- User blocked
- User unblocked
- User deleted
- **Group Management:**
- Group created
- Group updated
- Group deleted
- Group added to peer
- Group removed from peer
- Group added to user
- Group removed from user
- Group added to setup key
- Group removed from setup key
- Group added to disabled management DNS setting
- Group removed from disabled management DNS setting
- **Policy Management:**
- Policy added
- Policy updated
- Policy removed
- **Rule Management:**
- Rule added
- Rule updated
- Rule removed
- **Setup Key Management:**
- Setup key created
- Setup key updated
- Setup key revoked
- Setup key overused
- **Route Management:**
- Route created
- Route removed
- Route updated
- **Account Management:**
- Account created
- Account peer login expiration duration updated
- Account peer login expiration enabled
- Account peer login expiration disabled
- Account peer approval enabled
- Account peer approval disabled
- **Nameserver Group Management:**
- Nameserver group created
- Nameserver group deleted
- Nameserver group updated
- **Token Management:**
- Personal access token created
- Personal access token deleted
- **Service User Management:**
- Service user created
- Service user deleted
- **Integration Management:**
- Integration created
- Integration updated
- Integration deleted
- **Other Events:**
- Transferred owner role
- Posture check created
- Posture check updated
- Posture check deleted
- User logged in peer
- Peer login expired
- Dashboard login
</details>
Future versions will also support connection events that occur in NetBird agents (e.g., peer A connected to peer B).
<Note>
The `unknown` name or `unknown@unknown.com` email address may be displayed in the activity event store if the encryption key has been corrupted or lost. This issue is most relevant for self-hosted setups. In this case, the events returned by the API could show `unknown@unknown.com` for the email address field and `unknown` for the name field.
If the configuration files have been generated by the `configure.sh` script, you can find the previous encryption key in the backup files in the same folder as the script. Look for the <b>DataStoreEncryptionKey</b> field in the `management.json` backup file.
</Note>
## Enable Audit Events Streaming to SIEM Systems
NetBird can stream audit events to your Security Information and Event Management (SIEM) system in real-time. With this feature enabled, you can monitor and analyze NetBird network changes within your SIEM infrastructure. Check the [integrations guide](/manage/activity/event-streaming) for more information about the supported integrations and how to enable them.
## Get Started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- 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
src/pages/manage/activity/traffic-events-logging.mdx
+361
View File
@@ -0,0 +1,361 @@
# Traffic Events Logging
<Note>
This feature is available only in the NetBird cloud under the [Business plan](https://www.netbird.io/pricing?utm_source=docs&utm_content=traffic-events).
This is feature is in Beta and may change over time — including how data is collected and reported.
To use this feature, make sure you're running NetBird client version 0.39 or higher.
</Note>
The traffic events logging functionality enables comprehensive monitoring and analysis of connections across your infrastructure.
It captures network activity, including peer-to-peer, site-to-site, peer-to-resource, and other network traffic events.
It provides detailed visibility into connections and network traffic flow, helping to answer key questions such as who initiated
the connection, what resource was accessed, when it happened, where it originated, and why it was allowed. By enhancing
network monitoring capabilities, it strengthens security measures and delivers actionable operational insights, empowering
you to better manage and secure your environment.
## How Traffic Events Logging Works
NetBird offers flexibility as a peer-to-peer (p2p) overlay network and a remote network access solution. You can use NetBird to connect
machines directly (p2p) when running the NetBird client on each machine. You can also use NetBird to organize remote employee access
to internal networks like VPCs, office networks, and internal services without running the NetBird client on the remote resources using the [NetBird Networks](/manage/networks) feature.
The way you use NetBird influences the way traffic events are captured and logged. Below are the two main scenarios for traffic events logging
that describe how NetBird logs traffic events for different types of connections.
### Peer-to-Peer Connections
When two peers are connected directly (p2p), NetBird captures and logs the traffic events for that connection on both peers.
For example, if a user accessed an internal CRM server from their laptop via a browser and port 443, NetBird would log the traffic events for that
connection on both the user's machine and the CRM server. If the connection was blocked, such as when there is a
[policy](/manage/access-control/manage-network-access#managing-policies) that restricts access to the CRM server,
NetBird would log the blocked event on the peer that refused the connection.
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-traffic-events.png" alt="traffic-events-p2p-diagram" className="imagewrapper-big"/>
</p>
#### Successful P2P Connection Events
NetBird helps you better understand connection flows by correlating related events and presenting them in a clear, organized manner.
For example, in a successful peer-to-peer connection scenario, a user initiates a connection from the peer `Alice` to the peer `server`.
This is illustrated in the screenshot below.
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-successful-connection.png" alt="traffic-events-p2p-successful-connection" className="imagewrapper-big"/>
</p>
You'll see two grouped sets of events, one from each peer (source and destination). The source peer `Alice` initiates the
connection and then terminates it after a few seconds.
On the other side, the destination peer `server` receives the connection request and also terminates it shortly afterward,
following the disconnection from `Alice`. Since `server` allows the connection, the log includes the policy `IT Admins to Servers`
that authorized the connection over the `ICMP` protocol.
<Note>
Use the `P2P` filter in the table to view only peer-to-peer connection events.
</Note>
#### Blocked P2P Connections Events
If a connection is refused, NetBird logs the blocked event on the peer that denies the connection, in this case, `server`.
The initiating peer `Alice` will still report the connection attempt but won't be aware that it was blocked.
In this scenario, the `IT Admins to Servers` policy is configured to allow only ping requests (`ICMP`),
meaning all `HTTP` requests are intentionally not allowed. The screenshot below illustrates this behavior.
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-blocked-connection.png" alt="traffic-events-p2p-blocked-connection" className="imagewrapper-big"/>
</p>
### Peer-to-Network Resource Connections
When a peer connects to a [network resource](/manage/networks#resources), NetBird captures and logs the traffic
events for that connection on the peer that initiated the connection, and on the [routing peer](/manage/networks#routing-peers) that connects the peer to
the internal network resource.
A slightly modified example of the CRM server connection scenario would be if instead of running the NetBird client on the CRM server,
you used the [NetBird Networks feature](/manage/networks) and created a network resource for the CRM server. In this case, if a user accessed an internal CRM from their laptop via a browser
and port 443, NetBird would log the traffic events for that connection on the user's machine and the routing peer that
routed the connection to the CRM server. If the connection was blocked, NetBird would log the blocked event on the routing peer.
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/routed-traffic-events.png" alt="traffic-events-routed-diagram" className="imagewrapper-big"/>
</p>
#### Successful Peer-to-Network Resource Events
The screenshot below illustrates a successful connection from `Alice` to the network resource `CRM` running in the AWS VPC.
The traffic is routed through a routing peer, which logs the connection event and reports it to the NetBird servers.
The access is permitted by the policy `IT Admins to AWS Servers`, which allows connections over the `TCP` protocol on port `443`.
Note the `ROUTER` column in the table, which identifies the routing peer responsible for routing to the internal network resource.
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/network-resource-successful-connection.png" alt="network-resource-succesful-connection" className="imagewrapper-big"/>
</p>
<Note>
Use the `Routed` filter in the table to view only peer-to-network resource connection events.
</Note>
#### Blocked Peer-to-Network Resource Events
In the event of a blocked connection, the initiating peer logs the connection attempt, while the routing peer records the blocked event.
The screenshot below demonstrates this behavior: the routing peer blocks a connection to the network resource `CRM` because
the policy `IT Admins to AWS Servers` does not permit connections over the `HTTP` protocol on port `6432`.
You can see multiple blocked events reported by the routing peer, which indicates that the initiating peer `Alice` attempted to connect multiple times
in one TCP session, but the routing peer blocked all attempts.
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/network-resource-blocked-connection.png" alt="network-resource-succesful-connection" className="imagewrapper-big"/>
</p>
<Note>
For all the examples above, we used the `nc` command to initiate the connection to the CRM server from the peer `Alice`.
E.g., `nc -v crm.netbird.cloud 443`.
</Note>
## Enabling Traffic Events Logging
Traffic events logging feature is disabled by default. To enable it on the NetBird dashboard, navigate to `Settings > Networks`.
Under the Experimental section, you'll find the `Enable Traffic Events` option. Toggle the switch to enable traffic event logging.
By default, traffic reporting in userspace is always enabled, providing basic logging of network interactions.
However, packet size reporting at the kernel level is disabled by default to minimize CPU usage.
<Note>
You can optionally enable `Traffic Reporting (Kernel)` to capture additional details, such as network packet sizes,
at the kernel level. Be aware that enabling this option may lead to higher CPU usage on the NetBird client.
</Note>
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/traffic-events-logging-settings.png" alt="traffic-events-logging-settings" className="imagewrapper-big"/>
</p>
### Limiting Traffic Events to Specific Groups
You can scope traffic events logging to only the peers that belong to specific groups.
- When you select one or more groups, only peers that are members of the selected groups will report traffic events.
- If no group is selected, logging applies to all peers in the account (default behavior).
To configure this setting, navigate to `Settings > Networks` in the Experimental section, open the Group Selector under `Enable Traffic Events`
choose the groups you want to include, and click `Save Groups`.
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/traffic-events-groups-logging-settings.png" alt="traffic-events-groups-logging-settings" className="imagewrapper-big"/>
</p>
## Log Retention
While in experimental mode, logs are retained for **seven days**.
Additionally, please note that the current API returns a maximum of **50,000 events**.
We are actively working on expanding this limit in the coming days to support larger datasets and increased usage.
## Report rate
The events might take up to **ten minutes** to become available via API and Dashboard. For some TCP connections, the full event cycle might take longer, depending on OS settings and connection termination.
## Enable Traffic Events Streaming to SIEM Systems
NetBird allows you to stream traffic events directly to your Security Information and Event Management (SIEM) system in real time.
By enabling this feature, you can seamlessly monitor and analyze NetBird network flow events within your existing SIEM infrastructure,
enhancing your ability to detect and respond to security events.
For detailed instructions on supported integrations and how to set them up, refer to the [integrations guide](/manage/activity/event-streaming).
## Traffic Events Data
When enabled, a NetBird peer will record metadata for each network flow that it participates in. The data collected by peers includes:
* **Timestamp**: When the flow started and ended.
* **Flow ID**: A unique identifier for the traffic event flow.
* **Type**: The type of traffic event, such as Start, End, or Blocked.
* **Source and Destination IP Addresses**: The IP of the peer (source) and the IP of the remote endpoint (destination). For peer-to-peer traffic,
these will be the NetBird network IPs (e.g. 100.x.x.x addresses of each peer). For traffic to an external resource (like a private server or subnet), the destination might be an IP in that remote network.
* **Source and Destination Ports**: The network ports used by the connection (for TCP/UDP flows).
* **ICMP Code and Type**: For ICMP traffic, the ICMP code and type.
* **Protocol**: The protocol of the traffic, such as TCP, UDP, or ICMP.
* **Direction**: Whether the flow was inbound or outbound. This takes into consideration the perspective of the **peer reporting the traffic** and the NetBird interface.
* **Volume of Data**: The amount of data transferred, measured in number of packets and bytes sent/received for the duration of the flow.
* **Resource ID**: Network route or Networks resource ID that the flow is associated with. This is useful for identifying the routing configuration that allowed the flow. DNS route information is **available only** on the routing client.
* **Rule ID**: The ID of the policy that allowed the flow. This is useful for identifying the access control policy that allowed the flow. This information is **available only** on the receiving side of the traffic.
In addition to the data collected by the peers, the NetBird API provides additional context about the peers and resources involved in the traffic event. These details include:
* **Peer Name**: The name of the peer.
* **Peer ID**: The unique identifier of the peer.
* **Resource name**: The name of the resource or network route.
* **Policy Name**: The name of the policy that allowed the flow.
* **User ID, name, and email**: The name and email of the user associated with the source peer.
* **Reporter ID**: The unique identifier of the peer that reported the traffic event.
* **Received timestamp**: The timestamp when the event was received by the NetBird servers.
<details>
<summary>API sample response</summary>
```json
{
"destination": {
"address": "142.250.185.206:443",
"dns_label": "*.google.com",
"geo_location": {
"city_name": "",
"country_code": ""
},
"id": "cvco2st9q2cs73btphmg",
"name": "Any google.com domain",
"os": "",
"type": "DOMAIN_RESOURCE"
},
"direction": "EGRESS",
"flow_id": "9682d060-3b28-4fa3-8b47-98595a51bbda",
"icmp_code": 0,
"icmp_type": 0,
"id": "c94e398c-dbfb-4344-8c47-a731b984d86e",
"policy_id": "ndkslcanlksncl",
"policy_name": "Allow google access",
"protocol": 6,
"receive_timestamp": "2025-03-22T20:26:19.491144Z",
"reporter_id": "ldkfnwklenfklernl",
"rx_bytes": 0,
"rx_packets": 0,
"source": {
"address": "100.89.67.186:50229",
"dns_label": "macbook-pro-10-2",
"geo_location": {
"city_name": "Frankfurt",
"country_code": "DE"
},
"id": "ldkfnwklenfklernl",
"name": "MacBook-Pro-10.local",
"os": "Darwin",
"type": "PEER"
},
"timestamp": "2025-03-22T20:26:16.937522Z",
"tx_bytes": 64,
"tx_packets": 1,
"type": "TYPE_START",
"user_email": "john@example.com",
"user_id": "google-oauth2|xyz0123",
"user_name": "John Doe"
}
```
</details>
## Viewing Traffic Events on the Dashboard
There are two places where you can see the traffic events on the NetBird dashboard:
1. **Traffic events**: Under Activity, you will find the Traffic events menu. This view shows the traffic events in a table format for all peers in your network.
2. **Peer details**: When you click on a peer, you will see the traffic events for that peer in the Peer details view.
### Filters
You can use various filters to search and filter received events. The filters include:
- **Peer name**: Name of the peer that is the source or destination of the traffic event
- **Resource name**: Name of the resource or network route
- **IP address**: Source or destination IP addresses
- **Ports**: Source or destination ports
- **User**: User from the peer that initiated the connection
- **Timestamp**: Time range of the event
- **Protocol**: ICMP, TCP, UDP
- **Type of event**:
- **P2P connection started (inbound/outbound)**: Events with started status and initiated by peers to other peers
- **P2P connection stopped (inbound/outbound)**: Events with stopped status and initiated by peers to other peers
- **P2P connection blocked (inbound/outbound)**: Events with blocked status and initiated by peers to other peers
- **Routed connection started (inbound/outbound)**: Events with started status and with a remote resource destination
- **Routed connection stopped (inbound/outbound)**: Events with stopped status and with a remote resource destination
- **Routed connection blocked (inbound/outbound)**: Events with blocked status and with a remote resource destination
## Correlating events
Events can be correlated by observing the traffic from both peers involved in a traffic session. Let's say you have two peers, Peer A and Peer B, and Peer A initiates a connection to Peer B. In the traffic events,
you will see up to 4 events from these peers. If the connection was successful, you will see a started and a stopped event from Peer A and Peer B. But, if one peer blocks the connection, then you will see a started and stopped events from the initiator and
a blocked event from the responder.
<Note>
The blocked event will be available only if the destination uses the NetBird client in userspace mode.
This is the case for Windows and MacOs nodes. For Linux, you can enable userspace mode with the environment variable `NB_WG_KERNEL_DISABLED=true` and `NB_FORCE_USERSPACE_ROUTER=true`
</Note>
### Viewing TCP and UDP connections
You can use source ports to correlate TCP and UDP. Below we will analyze a few examples for a connection between a user computer and a Web and FTP servers.
The peer Maycons-MacBook-Pro.local initiates a connection to the Web server. The source port is `51997` and the destination port is TCP/80. The connection is successful, and the event is marked as started and stopped. See screenshot below:
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-tcp-allow.png" alt="P2P TCP Allowed" className="imagewrapper-big"/>
</p>
Besides the ports and protocol information, we can review the event description in the screenshot above to understand what happened. For all four events we have the following:
- **Peer `Maycons-MacBook-Pro-2.local` requested P2P connection to Peer `webserver`**: This is the event from the perspective of the peer that initiated the connection. The sources and destination provide the IPs and ports used in the connection.
- **Peer `webserver` received P2P connection from Peer `Maycons-MacBook-Pro-2.local`**: This is the event from the perspective of the peer that received the connection.
- **Peer `Maycons-MacBook-Pro-2.local` stopped P2P connection to Peer `webserver`**: This is the event from the perspective of the peer that initiated the connection when the connection ended on its side.
- **Peer `webserver` stopped P2P connection from Peer `Maycons-MacBook-Pro-2.local`**: This is the event from the perspective of the peer that received the connection when the connection has ended on its side.
In case of the peer receiving the connection, the stopped status might arrive several minutes later, due to TCP sessions.
The UDP connection is very similar:
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-udp-allow.png" alt="P2P UDP Allowed" className="imagewrapper-big"/>
</p>
<Note>
The UDP connection is stateless, so the stopped event will be generated right after a certain period of inactivity.
</Note>
When a connection is blocked, you may see similar entries to the following events but with a few differences:
**TCP**:
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-tcp-blocked.png" alt="P2P TCP Blocked" className="imagewrapper-big"/>
</p>
**UDP**:
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-udp-blocked.png" alt="P2P UDP Blocked" className="imagewrapper-big"/>
</p>
Key differences:
- There are no events that have started or stopped on the refusing side. The connection is blocked right after the request.
- Depending on the application making a request in the initiator, you may see multiple blocked events from the receiving side of the connection due to retries:
<Note>
The blocked event will be available only if the destination is using the NetBird client in userspace mode.
This is the case for Windows and MacOs nodes. For Linux, you can enable userspace mode with the environment variable `NB_WG_KERNEL_DISABLED=true` and `NB_FORCE_USERSPACE_ROUTER=true`
</Note>
### Viewing ICMP connections
ICMP events are similar to TCP and UDP events. The main difference is that ICMP doesn't have ports:
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-icmp-allowed.png" alt="P2P ICMP Allowed" className="imagewrapper-big"/>
</p>
<Note>
The ICMP connection is stateless, so the stopped event will be generated right after a certain period of inactivity.
</Note>
### Routed events
Routed events follow the same pattern as P2P events. The main difference is that the destination or source can be a resource or network route. Below, we have a few examples of a connection from a peer to a resource:
**ICMP**:
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/routed-icmp-allowed.png" alt="Routed ICMP Allowed" className="imagewrapper-big"/>
</p>
**TCP**:
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/routed-tcp-allowed.png" alt="Routed TCP Allowed" className="imagewrapper-big"/>
</p>
Key differences:
- The source or destination is a resource or network route.
- On the receiver side, we will have an indication of which routing peer reported the event.
- The source or destination identifier will be unknown on the routing peer side if the route or resource is of a DNS type.
For site-2-site connections, the events will be similar to the above examples, but you will see a routing peer for each event:
<p>
<img src="/docs-static/img/manage/activity/traffic-events-logging/s2s-tcp-allowed.png" alt="S2S TCP Allowed" className="imagewrapper-big"/>
</p>
## Limitations
There are a few differences between the different WireGuard modes NetBird supports and the data captured by the NetBird client.
| Feature | Kernel Mode | Userspace Mode | Netstack Mode |
|:---------:|:-------------:|:----------------:|:---------------:|
| Blocked traffic event | No | Yes | Yes |
| Site-2-Site events | No | Yes | Yes |
| Rule IDs | No | Yes | Yes |
| Allowed rule ID for routed events | Yes | No | No |
| Byte counters for routed events | Yes | No | No |
We are actively working to improve the data captured by the NetBird client in Kernel and userspace modes to align with customers' expectations.
## Conclusion
Traffic events logging provides a powerful tool for monitoring and analyzing network traffic across your infrastructure.
Enabling this feature can provide valuable insights into network activity, enhance security measures, and improve operational efficiency.
The ability to correlate events, view detailed traffic data, and stream events to SIEM systems empowers you to make informed decisions
and take proactive steps to protect your network environment.