From 1a24ef8b9f50e955989aa75e41b12b02501fbfac Mon Sep 17 00:00:00 2001 From: Krzysztof Nazarewski Date: Mon, 7 Jul 2025 17:53:17 +0200 Subject: [PATCH] wip: NET-251 revising Network Route docs --- ...configuring-routes-with-access-control.mdx | 3 +- .../routing-traffic-to-private-networks.mdx | 39 ++++++++++++++++--- 2 files changed, 35 insertions(+), 7 deletions(-) diff --git a/src/pages/how-to/configuring-routes-with-access-control.mdx b/src/pages/how-to/configuring-routes-with-access-control.mdx index be4b36d4..e1bd1d2a 100644 --- a/src/pages/how-to/configuring-routes-with-access-control.mdx +++ b/src/pages/how-to/configuring-routes-with-access-control.mdx @@ -34,7 +34,8 @@ Since release `0.30.0`, the management service and dashboard support access cont To add a Network route with access control groups, access the menu `Network Routes` tab and click the `Add Route` button to create a new route. -In the example below, we are creating a route with the following information: +In the example below, we are creating a route with the following information +(see [Concepts](routing-traffic-to-private-networks#concepts) to learn more about the fields): - Network identifier: `aws-eu-central-1-vpc` - Description: `Production VPC in Frankfurt` diff --git a/src/pages/how-to/routing-traffic-to-private-networks.mdx b/src/pages/how-to/routing-traffic-to-private-networks.mdx index 9ba5a00e..02873a27 100644 --- a/src/pages/how-to/routing-traffic-to-private-networks.mdx +++ b/src/pages/how-to/routing-traffic-to-private-networks.mdx @@ -6,6 +6,14 @@

+ + + WARNING: `Network Routes` will allow any traffic to pass through to the routed networks without regard for + the Access Control rules, unless you [configure those explicitly](./configuring-routes-with-access-control). + + See [Caveats](#caveats) below for more detailed explanation. + + NetBird provides fast and reliable end-to-end encryption between peers in your network. You can install the agent on every desktop, VM, container, or physical server and have a fast, secure peer-to-peer mesh network. That is the desired configuration, but some cases do not allow for agent installation or can slow down migration from legacy systems: - Side-by-side migrations where part of your network is already using NetBird but needs to access services that are not. @@ -25,6 +33,7 @@ In these cases, you can configure network routes assigning routing peers to conn ## Concepts + ### Network routes A network route describes the network you want to connect with your NetBird peers. It has an identifier, a network range or list of domains, a routing peer, and some parameters available for managing priority and masquerading. @@ -34,19 +43,17 @@ A network route describes the network you want to connect with your NetBird peer #### Network identifiers and ranges Network identifiers are names for each network you want to route traffic from your peers, and ranges are IP ranges declared in CIDR notation which refers to an external network. The combination of identifiers and these ranges makes a single network. + #### Routing peer A routing peer is a peer that routes packets between your routed network and the other NetBird peers. - - Only Linux OS machines can be assigned as routing peers. - + #### Routing group A routing group is a set of routing peers. Each will route packets between your routed network and the other NetBird peers. - - Only Linux OS machines can be assigned as routing peers. - + #### High availability routes A highly available route is a combination of multiple routes with the same network identifier and ranges. They have different routing peers or routing peer groups offering highly available paths for communication between your peers and external networks. Nodes connected to routing peers will choose one of them to route packets to external networks based on connection type and defined metrics. + #### Masquerade Masquerade hides other NetBird network IPs behind the routing peer local address when accessing the target Network range. This option allows access to your private networks without configuring routes on your local routers or other devices. @@ -209,6 +216,26 @@ This way, devices that don't have the agent installed can communicate with your high-level-dia

+## Caveats + +Unless [configured explicitly](./configuring-routes-with-access-control), the Network Routes feature will not take into +consideration any of the Access Control rules. Which might lead to surprising outcomes, at the first glance appearing to be security bugs. +This has lead us to creating another, more intuitive, design of `Networks` with their `Resources` and `Routers`. + +Consider following steps: +1. `Network Route NR` is distributed through `Group R` (routing Peer) to `Group A` (intended client), +2. Access Control rule granting full access from `Group A` (random client) to `Group R` (routing Peer) + - everything **seems** fine at this point in time, we're just giving access to the `Group R`, and nothing else? +3. Access Control rule allowing `ICMP` access from `All` to `All` + - it **seems** fine, we're just giving a `ping` access? + +The scenario has the following issues: +- after completing step 1, if a random client manually added an operating system routing table entry through `Group R` IP address, + it would already be able to access anything running behind the `Network Route NR` +- TBD: step 3 advertises the route to more Peers than it should and gives access to everything? +- TBD: a domain-based Network Resource resolving to the IP address also routed by `Network Route NR` + will grant full access to it, even if it is otherwise policed by Resource's access control + ## Get started