diff --git a/src/pages/client/environment-variables.mdx b/src/pages/client/environment-variables.mdx index 5f7d336d..db211819 100644 --- a/src/pages/client/environment-variables.mdx +++ b/src/pages/client/environment-variables.mdx @@ -46,7 +46,7 @@ To clear all saved service parameters (including env vars), run `sudo netbird se | `NB_USE_NETSTACK_MODE` | All | Run WireGuard on top of a userspace TCP/IP stack (gVisor netstack) instead of a TUN device. Required for environments without TUN support (e.g. unprivileged containers). | | `NB_NETSTACK_SKIP_PROXY` | All | When using netstack mode, do not start the built-in SOCKS5 proxy that exposes the WireGuard network to local applications. | | `NB_SOCKS5_LISTENER_PORT` | All | Override the port the netstack SOCKS5 proxy listens on (default: `1080`). Only relevant when netstack mode is active. | -| `NB_SOCKS5_LISTENER_ADDRESS` | All | Override the host/IP the netstack SOCKS5 proxy binds to (default: `127.0.0.1`). The proxy is unauthenticated and meant for local applications only, so it listens on loopback. Set this (e.g. to `0.0.0.0`) only when the proxy must be reachable from other hosts, such as a container gateway — this exposes an unauthenticated proxy on that address. Only relevant when netstack mode is active. | +| `NB_SOCKS5_LISTENER_ADDRESS` | All | Override the host/IP the netstack SOCKS5 proxy binds to (default: `127.0.0.1`). The proxy is unauthenticated and meant for local applications only, so it listens on loopback. Set this (e.g. to `0.0.0.0`) only when the proxy must be reachable from other hosts, such as a container gateway. Doing so exposes an unauthenticated proxy on that address. Only relevant when netstack mode is active. | ## Firewall diff --git a/src/pages/manage/activity/event-streaming/amazon-firehose.mdx b/src/pages/manage/activity/event-streaming/amazon-firehose.mdx index 417fac9d..3b212234 100644 --- a/src/pages/manage/activity/event-streaming/amazon-firehose.mdx +++ b/src/pages/manage/activity/event-streaming/amazon-firehose.mdx @@ -75,7 +75,7 @@ the stream name with your own values): ## Create an Integration in NetBird - Navigate to the [Integrations » Event Streaming](https://app.netbird.io/integrations?tab=event-streaming) tab in the NetBird dashboard

- event-streaming-integration + The Event Streaming tab showing the Datadog, Amazon S3, Amazon Data Firehose, and Generic HTTP integration cards

- On the `Amazon Data Firehose` card, click `Connect Amazon Data Firehose` or turn the card's toggle on to open the @@ -84,17 +84,17 @@ fill in the field on that step. - Step 1, `Select your Amazon Data Firehose region`: pick the region your stream lives in and click `Continue`. The dropdown defaults to `US East (N. Virginia)`, so change it if your stream is elsewhere.

- firehose-region-select + Step one of the Firehose wizard, selecting the AWS region for the delivery stream

- Step 2, `Create your Firehose Stream`: under `Enter your Firehose stream name`, enter the stream you created in [Create a Data Firehose Stream](#create-a-data-firehose-stream) and click `Continue`

- firehose-stream-name + Step two of the Firehose wizard, entering the Firehose stream name

- Step 3, `Create IAM credential`: enter the access key under `Enter your Access-Key`, the secret under `Enter your Secret-Key`, both created in [Create an IAM User](#create-an-iam-user), and click `Connect`

- firehose-iam-credentials + Step three of the Firehose wizard, entering the IAM access key and secret key

All four values (region, stream name, access key, secret key) are required. Once you click `Connect`, the integration is created diff --git a/src/pages/manage/activity/event-streaming/amazon-s3.mdx b/src/pages/manage/activity/event-streaming/amazon-s3.mdx index 0edfc3fa..444c2865 100644 --- a/src/pages/manage/activity/event-streaming/amazon-s3.mdx +++ b/src/pages/manage/activity/event-streaming/amazon-s3.mdx @@ -74,7 +74,7 @@ with your own bucket name): ## Create an Integration in NetBird - Navigate to the [Integrations » Event Streaming](https://app.netbird.io/integrations?tab=event-streaming) tab in the NetBird dashboard

- event-streaming-integration + The Event Streaming tab showing the Datadog, Amazon S3, Amazon Data Firehose, and Generic HTTP integration cards

- On the `Amazon S3` card, click `Connect Amazon S3` or turn the card's toggle on to open the `Connect NetBird with Amazon S3` wizard. @@ -82,17 +82,17 @@ The wizard has three steps, and each step's button stays disabled until you fill - Step 1, `Select your Amazon S3 region`: pick the region your bucket lives in and click `Continue`. The dropdown defaults to `US East (N. Virginia)`, so change it if your bucket is elsewhere.

- s3-region-select + Step one of the Amazon S3 wizard, selecting the AWS region for the bucket

- Step 2, `Create your S3 Bucket`: under `Enter your S3 Bucket name`, enter the bucket you created in [Create an S3 Bucket](#create-an-s3-bucket) and click `Continue`

- s3-bucket-name + Step two of the Amazon S3 wizard, entering the S3 bucket name

- Step 3, `Create IAM credential`: enter the access key under `Enter your Access-Key`, the secret under `Enter your Secret-Key`, both created in [Create an IAM User](#create-an-iam-user), and click `Connect`

- s3-iam-credentials + Step three of the Amazon S3 wizard, entering the IAM access key and secret key

All four values (region, bucket name, access key, secret key) are required. Once you click `Connect`, the integration is created @@ -126,7 +126,7 @@ containing the following events: - `integration created`

- verify-amazon-s3-integration + The S3 bucket in the AWS console containing the objects NetBird delivered

```json diff --git a/src/pages/manage/activity/event-streaming/datadog.mdx b/src/pages/manage/activity/event-streaming/datadog.mdx index 7db3d843..7a49bc73 100644 --- a/src/pages/manage/activity/event-streaming/datadog.mdx +++ b/src/pages/manage/activity/event-streaming/datadog.mdx @@ -70,18 +70,18 @@ Datadog sites: - Navigate to the `Integrations` » `Event Streaming` tab in the [NetBird Dashboard](https://app.netbird.io/integrations?tab=event-streaming)

- event-streaming-integration + The Event Streaming tab showing the Datadog, Amazon S3, Amazon Data Firehose, and Generic HTTP integration cards

- On the `Datadog` card, click `Connect Datadog` or switch the card's toggle on. Either one opens the `Connect NetBird with Datadog` wizard. - Under `Select your Datadog region`, choose your site from the dropdown and click `Continue`

- datadog-region-select + Step one of the Datadog wizard, selecting the Datadog site from the region dropdown

- Under `Get your Datadog API Key`, paste the API key you created above into the input field and click `Connect`

- datadog-api-key + Step two of the Datadog wizard, pasting the Datadog API key

The API key is the only value you type in. `Connect` stays disabled until the field is filled, and NetBird does not check @@ -96,7 +96,7 @@ service in the Log Explorer: - `integration created`

- verify-datadog-integration + The Datadog Log Explorer showing events arriving from the netbird service

The `integration test` event is sent to validate whether the provided credentials are correct and NetBird can stream events. diff --git a/src/pages/manage/activity/event-streaming/generic-http.mdx b/src/pages/manage/activity/event-streaming/generic-http.mdx index 27988e80..ee6d1e78 100644 --- a/src/pages/manage/activity/event-streaming/generic-http.mdx +++ b/src/pages/manage/activity/event-streaming/generic-http.mdx @@ -4,6 +4,10 @@ The Generic HTTP integration streams your NetBird audit and traffic events to an For every event, NetBird sends a POST request to the endpoint you configure. You control the request headers and, optionally, the shape of the body. +If your destination is Datadog, Amazon S3, or Amazon Data Firehose, use its own card instead. Those integrations ask +for a region and credentials and handle the endpoint and payload for you, so there is nothing to template and nothing +to keep in sync. Reach for Generic HTTP when no dedicated card exists for where you are sending events. + Event streaming is available in NetBird Cloud under the [Business plan](https://www.netbird.io/pricing?utm_source=docs&utm_content=event-streaming) and in licensed self-hosted Enterprise deployments. The open source management server does not serve the event streaming API, so the integration cards stay locked there. diff --git a/src/pages/manage/activity/event-streaming/index.mdx b/src/pages/manage/activity/event-streaming/index.mdx index a2694b96..de75c528 100644 --- a/src/pages/manage/activity/event-streaming/index.mdx +++ b/src/pages/manage/activity/event-streaming/index.mdx @@ -1,7 +1,7 @@ # Stream Audit and Traffic Events to Third-Party Services

- event-streaming-integration + The Event Streaming tab showing the Datadog, Amazon S3, Amazon Data Firehose, and Generic HTTP integration cards

Event Streaming forwards your NetBird activity to an external destination as the events occur. Destinations include SIEM diff --git a/src/pages/manage/activity/event-streaming/sentinelone-data-lake.mdx b/src/pages/manage/activity/event-streaming/sentinelone-data-lake.mdx index 425bb319..a5508dd1 100644 --- a/src/pages/manage/activity/event-streaming/sentinelone-data-lake.mdx +++ b/src/pages/manage/activity/event-streaming/sentinelone-data-lake.mdx @@ -31,7 +31,7 @@ Before you start configuring the `Generic HTTP` integration for SentinelOne Sing - Click **Copy to Clipboard** and store this token securely. You will need this token when configuring the integration in NetBird.

- API Key Generation + Generating a write API key in the SentinelOne console

## Get the HEC Ingestion URL @@ -48,7 +48,7 @@ to find and copy the HTTP Event Collector base URL from the documentation page. 5. Click `Continue`.

- General Settings Configuration + The Generic HTTP General tab, with the SentinelOne HEC endpoint URL and Bearer Token authentication

6. Leave the `Headers` tab empty unless your tenant requires extra headers, then click `Continue`. Do not add your own `Authorization` header here, because it conflicts with the `Bearer Token` method selected on the previous tab and blocks the save. @@ -71,7 +71,7 @@ to find and copy the HTTP Event Collector base URL from the documentation page. 8. Click `Connect`. When you are editing an integration that already exists, the button reads `Save Changes` instead.

- Custom Template Configuration + The Generic HTTP Body Template tab, with the custom template shaped for the SentinelOne HTTP Event Collector

@@ -91,7 +91,7 @@ Saving the integration makes NetBird post a synthetic test event to the endpoint - Look for an `integration test event for generic http endpoint` message followed by an `integration created` message, and confirm that the `id`, `initiator_id`, `target_id`, and `time` fields carry the values your template produced

- Verify Integration + SentinelOne Data Lake search results showing the NetBird test event and the integration created event

The integration is now set up and ready to stream network activity events to SentinelOne Singularity Data Lake. diff --git a/src/pages/manage/activity/index.mdx b/src/pages/manage/activity/index.mdx index 51642c1a..ab8c82f4 100644 --- a/src/pages/manage/activity/index.mdx +++ b/src/pages/manage/activity/index.mdx @@ -1,8 +1,11 @@ # 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. +Networks drift. A policy gets loosened, a setup key gets shared, someone is added to a group that grants more access than +anyone intended. Weeks later the question is who changed it, and when. + +Audit events answer that. NetBird records every configuration change made on the Management server, such as a peer or user +joining, an access control policy being modified, or a setup key being revoked, and keeps them in a searchable feed with the +person or system that made each change. ## Related Video Content @@ -22,7 +25,7 @@ This view provides a centralized log of network events.

- activity-monitoring + The Audit Events feed in the NetBird dashboard, listing recent configuration changes with their initiator and timestamp

Each entry in the feed shows who triggered the event (name and email address), when it happened, and a description of the change with the diff --git a/src/pages/manage/activity/traffic-events-logging.mdx b/src/pages/manage/activity/traffic-events-logging.mdx index ca87a739..1a9053e8 100644 --- a/src/pages/manage/activity/traffic-events-logging.mdx +++ b/src/pages/manage/activity/traffic-events-logging.mdx @@ -1,5 +1,13 @@ # Traffic Events Logging +Access policies tell NetBird which connections are allowed. They do not tell you what actually happened. When a +connection fails for no obvious reason, or an auditor asks who reached the production database last month, you need a +record of the attempts themselves. + +Traffic events are that record. Each event describes one connection, peer-to-peer, site-to-site, or peer-to-resource: +who started it, what they reached, when, over which protocol and port, how much data moved, and which policy allowed +or blocked it. + This feature is available in NetBird Cloud under the [Business plan](https://www.netbird.io/pricing?utm_source=docs&utm_content=traffic-events) and in licensed self-hosted Enterprise deployments with traffic flow enabled. Traffic events are experimental, so functionality and behavior may evolve, including how data is collected and reported. @@ -11,14 +19,6 @@ On self-hosted deployments, traffic flow is an opt-in part of the [Enterprise st -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 @@ -36,7 +36,7 @@ connection on both the user's machine and the CRM server. If the connection was NetBird would log the blocked event on the peer that refused the connection.

- traffic-events-p2p-diagram + Diagram of a direct peer-to-peer connection, where both peers report traffic events independently

#### Successful P2P Connection Events @@ -47,7 +47,7 @@ For example, in a successful peer-to-peer connection scenario, a user initiates This is illustrated in the screenshot below.

- traffic-events-p2p-successful-connection + Traffic events table showing an allowed peer-to-peer connection, with an empty Router column

You'll see two aggregated flow records, one reported by each peer (source and destination). The record from `Alice` counts the connection start and end from the initiator's perspective. @@ -67,7 +67,7 @@ The initiating peer `Alice` will still report the connection attempt but won't b In this scenario, the `IT Admins to Servers` policy is configured to allow only ping requests (`ICMP`), meaning `TCP` connections are intentionally not allowed. The screenshot below illustrates this behavior.

- traffic-events-p2p-blocked-connection + Traffic events table showing a blocked peer-to-peer connection and the policy that denied it

### Peer-to-Network Resource Connections @@ -82,7 +82,7 @@ and port 443, NetBird would log the traffic events for that connection on the us routed the connection to the CRM server. If the connection was blocked, NetBird would log the blocked event on the routing peer.

- traffic-events-routed-diagram + Diagram of a connection to a network resource, where the routing peer also reports the flow

#### Successful Peer-to-Network Resource Events @@ -93,7 +93,7 @@ The access is permitted by the policy `IT Admins to AWS Servers`, which allows c Note the `Router` column in the table, which identifies the routing peer responsible for routing to the internal network resource.

- network-resource-succesful-connection + Traffic events table showing an allowed connection to a network resource, with the routing peer named in the Router column

@@ -108,7 +108,7 @@ the policy `IT Admins to AWS Servers` does not permit `TCP` connections on port The routing peer's aggregate shows the number of dropped attempts, so repeated application retries increase the drop count instead of creating one top-level row for every attempt.

- network-resource-succesful-connection + Traffic events table showing a blocked connection to a network resource and the policy that denied it

@@ -146,7 +146,7 @@ You can optionally turn on `Enable Traffic Reporting (Kernel)` to capture packet

- traffic-events-logging-settings + The Enable Traffic Events toggle in the Experimental section of Settings, Networks

### Limiting Traffic Events to Specific Groups @@ -159,7 +159,7 @@ You can scope traffic events logging to only the peers that belong to specific g To configure this setting, navigate to `Settings > Networks`, and in the `Experimental` section open the `Limit To Specific Groups` selector below `Enable Traffic Events`, choose the groups you want to include, and click `Save Groups`.

- traffic-events-groups-logging-settings + The Limit To Specific Groups selector, scoping traffic event reporting to chosen groups

## Log Retention @@ -312,14 +312,14 @@ You can use endpoint addresses, destination ports, and the other flow fields to The peer `example-laptop.local` initiates a connection to the Web server on destination port TCP/80. A successful aggregate has non-zero start and end counters and totals the packets and bytes transferred in the reporting window:

- P2P TCP Allowed + Aggregated traffic event row for an allowed peer-to-peer TCP flow

Use the reporter, source, destination, direction, protocol, and destination port to align the two perspectives. An end can be reported in a later window when the operating system keeps the TCP session open. The UDP connection is very similar:

- P2P UDP Allowed + Aggregated traffic event row for an allowed peer-to-peer UDP flow

UDP is stateless, so its end counter is only updated after the client observes 30 seconds of inactivity on the connection. @@ -329,12 +329,12 @@ When a connection is blocked, you may see similar entries to the following event **TCP**:

- P2P TCP Blocked + Aggregated traffic event row for a blocked peer-to-peer TCP flow

**UDP**:

- P2P UDP Blocked + Aggregated traffic event row for a blocked peer-to-peer UDP flow

On the refusing side, retries increase `num_of_drops`; the client does not record a successful start or end for traffic it rejected. Drops are always recorded as `INGRESS`, because a peer can only observe traffic that it refused to accept. @@ -344,7 +344,7 @@ On the refusing side, retries increase `num_of_drops`; the client does not recor ### Viewing ICMP connections ICMP events are similar to TCP and UDP events. The main difference is that ICMP doesn't have ports:

- P2P ICMP Allowed + Aggregated traffic event row for an allowed peer-to-peer ICMP flow

ICMP is grouped by ICMP type and does not use ports. Its end counter is only updated after 30 seconds of inactivity. @@ -354,17 +354,17 @@ Routed events follow the same pattern as P2P events. The main difference is that **ICMP**:

- Routed ICMP Allowed + Aggregated traffic event row for an allowed ICMP flow through a routing peer

**TCP**:

- Routed TCP Allowed + Aggregated traffic event row for an allowed TCP flow through a routing peer

For routed aggregates, the source or destination can be a resource or network route, and the `Router` column identifies the routing peer that reported it. For domain based resources, the endpoint is resolved on the peer that performed the DNS resolution, so one side of the flow can show the resource name while the other side shows only the address with type `UNKNOWN`. For site-2-site connections, the events will be similar to the above examples, but you will see a routing peer for each event:

- S2S TCP Allowed + Aggregated traffic event row for an allowed site-to-site TCP flow

## Limitations