# Deploying the Node for TCP Traffic Mirror Analysis Wallarm provides an artifact for deploying its filtering node, specifically designed for TCP traffic mirror analysis. This guide explains how to deploy and configure the Wallarm filtering node in this form-factor. ## Use cases Among all supported [deployment options](https://docs.wallarm.com/installation/supported-deployment-options.md), this solution is recommended for the following scenarios: * You prefer to capture TCP traffic mirrored at the network layer and require a security solution to analyze this specific traffic. * NGINX-based deployment artifacts are unavailable, too slow, or consume too many resources. In this case, implementing HTTP traffic mirror analysis can be resource-intensive. The TCP traffic mirror analysis runs independently from web servers, avoiding these issues. * You require a security solution that also parses responses, enabling features like [vulnerability detection](https://docs.wallarm.com/about-wallarm/detecting-vulnerabilities.md) and [API discovery](https://docs.wallarm.com/api-discovery/overview.md), which rely on response data. ## How does it work This solution operates in out-of-band (OOB) mode, capturing mirrored TCP traffic directly from the network interface, independent of web servers like NGINX. The captured traffic is then parsed, reassembled, and analyzed for threats. It functions as a mirror target, seamlessly switching between multiple traffic sources. The supported encapsulation formats are: * **[VLAN](https://www.ieee802.org/1/pages/802.1Q-2022.html)** (802.1Q) — captured via network interface with a BPF filter * **[VXLAN](https://datatracker.ietf.org/doc/html/rfc7348)** — received via a dedicated UDP listener * **[GENEVE](https://datatracker.ietf.org/doc/html/rfc8926)** — received via a dedicated UDP listener, including nested VXLAN for [AWS VPC Traffic Mirroring](https://docs.aws.amazon.com/vpc/latest/mirroring/what-is-traffic-mirroring.html) Other encapsulation protocols (GRE, ERSPAN, SPAN, STT) are not supported. Additionally, the solution enables response mirror parsing, providing Wallarm features that rely on response data. These features include [vulnerability detection](https://docs.wallarm.com/about-wallarm/detecting-vulnerabilities.md), [API discovery](https://docs.wallarm.com/api-discovery/overview.md) and more. ![!TCP traffic mirror scheme](https://docs.wallarm.com/images/waf-installation/oob/tcp-mirror-analysis.png) ## Requirements * Access to the account with the **Administrator** role in Wallarm Console for the [US Cloud](https://us1.my.wallarm.com/) or [EU Cloud](https://my.wallarm.com/), or [ME Cloud](https://me1.my.wallarm.com/). * The machine intended for running the node must meet the following criteria: * Linux OS * x86_64/ARM64 architecture * Executing all commands as a superuser (e.g. `root`). * Allowed outgoing connections to `https://meganode.wallarm.com` to download the Wallarm installer * Allowed outgoing connections to the Wallarm API host for your Cloud: `https://us1.api.wallarm.com`, `https://api.wallarm.com`, or `https://me1.api.wallarm.com` * Allowed outgoing connections to the IP addresses and their corresponding hostnames (if any) listed below. This is needed for downloading updates to attack detection rules and [API specifications](https://docs.wallarm.com/api-specification-enforcement/overview.md), as well as retrieving precise IPs for your [allowlisted, denylisted, or graylisted](https://docs.wallarm.com/user-guides/ip-lists/overview.md) countries, regions, or data centers **US Cloud:** ``` node-data0.us1.wallarm.com - 34.96.64.17 node-data1.us1.wallarm.com - 34.110.183.149 us1.api.wallarm.com - 35.235.66.155 34.102.90.100 34.94.156.115 35.235.115.105 ``` **EU Cloud:** ``` node-data1.eu1.wallarm.com - 34.160.38.183 node-data0.eu1.wallarm.com - 34.144.227.90 api.wallarm.com - 34.90.110.226 ``` **ME Cloud:** ``` node-data0.me1.wallarm.com - 34.166.82.208 node-data1.me1.wallarm.com - 34.166.82.208 me1.api.wallarm.com - 34.166.82.208 ``` * Traffic and response mirroring must be configured with both source and target set up, and the prepared instance chosen as a mirror target. * The mirrored traffic must use one of the supported encapsulation formats: raw/VLAN, VXLAN, or GENEVE. ## Step 1: Prepare Wallarm token To install node, you will need a token for registering the node in the Wallarm Cloud. To prepare a token: 1. Open Wallarm Console → **Settings** → **API tokens** in the [US Cloud](https://us1.my.wallarm.com/settings/api-tokens) or [EU Cloud](https://my.wallarm.com/settings/api-tokens), or [ME Cloud](https://me1.my.wallarm.com/settings/api-tokens). 1. Find or create API token with the `Node deployment/Deployment` usage type. 1. Copy this token. ## Step 2: Download Wallarm installer Wallarm suggests installations for the following processors: * x86_64 * ARM64 To download Wallarm installation script and make it executable, use the following commands: **x86_64 version:** ```bash curl -O https://meganode.wallarm.com/native/aio-native-0.25.0.x86_64.sh chmod +x aio-native-0.25.0.x86_64.sh ``` **ARM64 version:** ```bash curl -O https://meganode.wallarm.com/native/aio-native-0.25.0.aarch64.sh chmod +x aio-native-0.25.0.aarch64.sh ``` ## Step 3: Prepare the configuration file Create the `wallarm-node-conf.yaml` file on the instance. The solution requires proper configuration to identify the network interface and the traffic format (e.g., VLAN, VXLAN). The example content of the file: ```yaml version: 4 mode: tcp-capture-v2 tcp_stream: from_interface: enabled: true interface: "enp7s0" ``` In the [article](https://docs.wallarm.com/installation/native-node/all-in-one-conf.md), you will find the list of more supported configuration parameters. ### Setting the mode (required) It is required to specify the `tcp-capture-v2` mode in the corresponding parameter to run the solution for the TCP traffic mirror analysis. ### Configuring the traffic source The node supports several traffic source types depending on how mirrored traffic is delivered to the machine. At least one source should be enabled. Multiple sources can run simultaneously — they operate independently and feed into the same processing pipeline. | Source | Use when | Config section | |--------|----------|----------------| | [Network interface](#network-interface-raw-or-vlan) | Traffic is mirrored at L2 level (raw or VLAN-tagged). | `tcp_stream.from_interface` | | [VXLAN listener](#vxlan) | Traffic is encapsulated in VXLAN. | `tcp_stream.from_vxlan` | | [GENEVE listener](#geneve) | Traffic is encapsulated in GENEVE, including AWS VPC Traffic Mirroring | `tcp_stream.from_geneve` | #### Network interface (raw or VLAN) Use `tcp_stream.from_interface` to capture raw (unencapsulated) or VLAN-tagged mirrored traffic directly from a network interface. This source does **not** perform tunnel decapsulation — for VXLAN or GENEVE traffic, use the dedicated listeners below. 1. Check network interfaces available on the host: ``` ip addr show ``` 1. Specify the network interface in the `interface` parameter. The value must be the network interface name (e.g., `eth0`, `enp7s0`). To filter traffic by port or VLAN, specify a [BPF (Berkeley Packet Filter)](https://biot.com/capstats/bpf.html) expression in the `filter` parameter. **Raw traffic on a specific port:** ```yaml version: 4 mode: tcp-capture-v2 tcp_stream: from_interface: enabled: true interface: "eth0" filter: "port 80" ``` **VLAN-tagged traffic:** ```yaml version: 4 mode: tcp-capture-v2 tcp_stream: from_interface: enabled: true interface: "eth0" filter: "vlan" ``` #### VXLAN Use `tcp_stream.from_vxlan` when mirrored traffic is encapsulated in [VXLAN](https://datatracker.ietf.org/doc/html/rfc7348). The node opens a UDP socket on the configured port, decapsulates VXLAN headers, and feeds the inner Ethernet frames into the processing pipeline. Available [starting from version 0.24.0](https://docs.wallarm.com/updating-migrating/native-node/node-artifact-versions.md). ```yaml version: 4 mode: tcp-capture-v2 tcp_stream: from_vxlan: enabled: true listen_addr: "0.0.0.0:4789" # Optional: list of VNIs to accept (empty = all VNIs) vni_filter: - 100 # Optional: BPF filter applied to the inner (decapsulated) packets filter: "tcp port 80" ``` #### GENEVE Use `tcp_stream.from_geneve` when mirrored traffic is encapsulated in [GENEVE](https://datatracker.ietf.org/doc/html/rfc8926). The node opens a UDP socket on the configured port, decapsulates GENEVE headers, and feeds the inner Ethernet frames into the processing pipeline. [AWS VPC Traffic Mirroring](https://docs.aws.amazon.com/vpc/latest/mirroring/what-is-traffic-mirroring.html), which wraps VXLAN inside GENEVE, is supported automatically — no additional configuration is required. Available [starting from version 0.24.0](https://docs.wallarm.com/updating-migrating/native-node/node-artifact-versions.md). **Standard GENEVE:** ```yaml version: 4 mode: tcp-capture-v2 tcp_stream: from_geneve: enabled: true listen_addr: "0.0.0.0:6081" # Optional: list of VNIs to accept (empty = all VNIs) vni_filter: - 100 # Optional: BPF filter applied to the inner (decapsulated) packets filter: "tcp port 443" ``` **AWS VPC Traffic Mirroring (GENEVE + nested VXLAN):** AWS VPC Traffic Mirroring wraps VXLAN inside GENEVE. Nested VXLAN decapsulation is handled automatically: ```yaml version: 4 mode: tcp-capture-v2 tcp_stream: from_geneve: enabled: true listen_addr: "0.0.0.0:6081" # Optional: filter by Geneve VNI vni_filter: - 100 # Optional: filter by inner VXLAN VNI inner_vni_filter: - 200 # Optional: BPF filter applied to the inner (decapsulated) packets filter: "tcp port 443" ``` ### Identifying the original client IP and host headers When traffic passes through proxies or load balancers, they often replace the original client IP address and `Host` header with their own values. To preserve the original information, such intermediaries typically add HTTP headers like `X-Forwarded-For`, `X-Real-IP`, or `X-Forwarded-Host`. To ensure the Native Node correctly identifies the original client and target host, use the [`proxy_headers`](https://docs.wallarm.com/installation/native-node/all-in-one-conf.md#proxy_headers) configuration block, e.g.: ```yaml version: 4 mode: tcp-capture-v2 proxy_headers: # Rule 1: Internal company proxies - trusted_networks: - 10.0.0.0/8 - 192.168.0.0/16 original_host: - X-Forwarded-Host real_ip: - X-Forwarded-For # Rule 2: External edge proxies (e.g., CDN, reverse proxy) - trusted_networks: - 203.0.113.0/24 original_host: - X-Real-Host real_ip: - X-Real-IP ``` ## Step 4: Run the Wallarm installer To install the Wallarm node for TCP traffic mirror analysis, run the following command: **x86_64 version:** ```bash # US Cloud sudo env WALLARM_LABELS='group=' ./aio-native-0.25.0.x86_64.sh -- --batch --token --mode=tcp-capture-v2 --go-node-config= --host us1.api.wallarm.com # EU Cloud sudo env WALLARM_LABELS='group=' ./aio-native-0.25.0.x86_64.sh -- --batch --token --mode=tcp-capture-v2 --go-node-config= --host api.wallarm.com # ME Cloud sudo env WALLARM_LABELS='group=' ./aio-native-0.25.0.x86_64.sh -- --batch --token --mode=tcp-capture-v2 --go-node-config= --host me1.api.wallarm.com ``` **ARM64 version:** ```bash # US Cloud sudo env WALLARM_LABELS='group=' ./aio-native-0.25.0.aarch64.sh -- --batch --token --mode=tcp-capture-v2 --go-node-config= --host us1.api.wallarm.com # EU Cloud sudo env WALLARM_LABELS='group=' ./aio-native-0.25.0.aarch64.sh -- --batch --token --mode=tcp-capture-v2 --go-node-config= --host api.wallarm.com # ME Cloud sudo env WALLARM_LABELS='group=' ./aio-native-0.25.0.aarch64.sh -- --batch --token --mode=tcp-capture-v2 --go-node-config= --host me1.api.wallarm.com ``` * The `WALLARM_LABELS` variable sets group into which the node will be added (used for logical grouping of nodes in the Wallarm Console UI). * `` specifies the generated API token for the `Node deployment/Deployment` usage type. * `` specifies the path to the configuration file prepared before. The provided configuration file will be copied to the path: `/opt/wallarm/etc/wallarm/go-node.yaml`. If needed, you can change the copied file after the installation is finished. To apply the changes, you will need to restart the Wallarm service with `sudo systemctl restart wallarm`. ## Step 5: Test the solution Send the test [Path Traversal](https://docs.wallarm.com/attacks-vulns-list.md#path-traversal) attack to the mirror source address by replacing `` with the actual IP address or DNS name of the instance: ``` curl http:///etc/passwd ``` Since the Wallarm solution for TCP traffic mirror analysis operates out-of-band, it does not block attacks but only registers them. To check that the attack has been registered, proceed to Wallarm Console → **Events**: ![!Attacks in the interface](https://docs.wallarm.com/images/waf-installation/epbf/ebpf-attack-in-ui.png) ## Verifying the node operation * To check if there is traffic on the network interface you are trying to capture from, run the following command on your machine: ``` sudo tcpdump -i ``` * To verify the node is detecting traffic, you can check the logs: * The Native Node logs are written to `/opt/wallarm/var/log/wallarm/go-node.log` by default. * [Standard logs](https://docs.wallarm.com/admin-en/configure-logging.md) of the filtering node such as whether the data is sent to the Wallarm Cloud, detected attacks, etc. are located in the directory `/opt/wallarm/var/log/wallarm`. For additional debugging, set the [`log.level`](https://docs.wallarm.com/installation/native-node/all-in-one-conf.md#loglevel) parameter to `debug`. ## Installer launch options * As soon as you have the all-in one script downloaded, you can get **help** on it with: **x86_64 version:** ``` sudo ./aio-native-0.25.0.x86_64.sh -- --help ``` **ARM64 version:** ``` sudo ./aio-native-0.25.0.aarch64.sh -- --help ``` * You can also run the installer in an **interactive** mode and choose the `tcp-capture-v2` mode in the 1st step: **x86_64 version:** ``` sudo env WALLARM_LABELS='group=' ./aio-native-0.25.0.x86_64.sh ``` **ARM64 version:** ``` sudo env WALLARM_LABELS='group=' ./aio-native-0.25.0.aarch64.sh ``` * You can use the node in API Discovery-only mode (available since version 0.12.1). In this mode, attacks - including those detected by the Node's built-in mechanisms and those requiring additional configuration (e.g., credential stuffing, API specification violation attempts and brute force) - are detected and [logged](https://docs.wallarm.com/admin-en/configure-logging.md) locally but not exported to Wallarm Cloud. Since there is no attack data in the Cloud, [Threat Replay Testing](https://docs.wallarm.com/vulnerability-detection/threat-replay-testing/overview.md) does not work. Meanwhile, [API Discovery](https://docs.wallarm.com/api-discovery/overview.md), [API session tracking](https://docs.wallarm.com/api-sessions/overview.md), and [security vulnerability detection](https://docs.wallarm.com/about-wallarm/detecting-vulnerabilities.md) remain fully functional, detecting relevant security entities and uploading them to the Cloud for visualization. This mode is for those who want to review their API inventory and identify sensitive data first, and plan controlled attack data export accordingly. However, disabling attack export is rare, as Wallarm securely processes attack data and provides [sensitive attack data masking](https://docs.wallarm.com/user-guides/rules/sensitive-data-rule.md) if needed. To enable API Discovery-only mode: 1. Create or modify the `/etc/wallarm-override/env.list` file: ``` sudo mkdir /etc/wallarm-override sudo vim /etc/wallarm-override/env.list ``` Add the following variable: ``` WALLARM_APID_ONLY=true ``` 1. Follow the [node installation procedure from the 1st step](#step-1-prepare-wallarm-token). ## Upgrade and reinstallation * To upgrade the node, follow the [instructions](https://docs.wallarm.com/updating-migrating/native-node/all-in-one.md). * If there is a problem with the upgrade or reinstallation process: 1. Remove the current installation: ``` sudo systemctl stop wallarm && sudo rm -rf /opt/wallarm ``` 1. Install the node as usual following the installation steps from above. ## Limitations * Due to its out-of-band (OOB) operation, which analyzes traffic independently from actual flow, the solution has several inherent limitations: * It does not instantly block malicious requests. Wallarm only observes attacks and provides you with the [details in Wallarm Console](https://docs.wallarm.com/user-guides/events/check-attack.md). * [Rate limiting](https://docs.wallarm.com/user-guides/rules/rate-limiting.md) is not supported as it is impossible to limit load on target servers. * [Filtering by IP addresses](https://docs.wallarm.com/user-guides/ip-lists/overview.md) is not supported. * The solution analyzes only unencrypted HTTP traffic over raw TCP, not encrypted HTTPS traffic. * The solution does not support traffic mirrored as independent, one-way streams (e.g., by some FortiGate configurations), because such traffic cannot be reliably reconstructed and HTTP request/response pairs may not be matched. `tcp-capture-v2` requires bidirectional TCP streams, with all packets from both directions captured in a single coherent flow.