Skip to content

Commit 66e7501

Browse files
tarTech23tarTech23
committed
first
1 parent c8bb6f9 commit 66e7501

File tree

1 file changed

+266
-0
lines changed

1 file changed

+266
-0
lines changed

‎articles/defender-for-iot/organizations/cli-ot-sensor.md

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -396,6 +396,272 @@ lo: flags=73<UP,LOOPBACK,RUNNING> mtu 65536
396396
shell>
397397
```
398398
399+
## Traffic capture filters
400+
401+
To reduce alert fatigue and focus your network monitoring on high priority traffic, you may decide to filter the traffic that streams into Defender for IoT at the source. Capture filters allow you to block high-bandwidth traffic at the hardware layer, optimizing both appliance performance and resource usage.
402+
403+
Use include an/or exclude lists to create and configure capture filters on your OT network sensors, making sure that you don't block any of the traffic that you want to monitor.
404+
405+
The basic use case for capture filters uses the same filter for all Defender for IoT components. However, for advanced use cases, you may want to configure separate filters for each of the following Defender for IoT components:
406+
407+
- `horizon`: Captures deep packet inspection (DPI) data
408+
- `collector`: Captures PCAP data
409+
- `traffic-monitor`: Captures communication statistics
410+
411+
> [!NOTE]
412+
> - Capture filters don't apply to [Defender for IoT malware alerts](../alert-engine-messages.md#malware-engine-alerts), which are triggered on all detected network traffic.
413+
>
414+
> - The capture filter command has a character length limit that's based on the complexity of the capture filter definition and the available network interface card capabilities. If your requested filter commmand fails, try grouping subnets into larger scopes and using a shorter capture filter command.
415+
416+
### Create a basic filter for all components
417+
418+
The method used to configure a basic capture filter differs, depending on the user performing the command:
419+
420+
- **cyberx** user: Run the specified command with specific attributes to configure your capture filter.
421+
- **admin** user: Run the specified command, and then enter values as [prompted by the CLI](#create-a-basic-capture-filter-using-the-admin-user), editing your include and exclude lists in a nano editor.
422+
423+
Use the following commands to create a new capture filter:
424+
425+
|User |Command |Full command syntax |
426+
|---------|---------|---------|
427+
| **admin** | `network capture-filter` | No attributes.|
428+
| **cyberx**, or **admin** with [root access](references-work-with-defender-for-iot-cli-commands.md#access-the-system-root-as-an-admin-user) | `cyberx-xsense-capture-filter` | `cyberx-xsense-capture-filter [-h] [-i INCLUDE] [-x EXCLUDE] [-etp EXCLUDE_TCP_PORT] [-eup EXCLUDE_UDP_PORT] [-itp INCLUDE_TCP_PORT] [-iup INCLUDE_UDP_PORT] [-vlan INCLUDE_VLAN_IDS] -m MODE [-S]` |
429+
430+
Supported attributes for the *cyberx* user are defined as follows:
431+
432+
|Attribute |Description |
433+
|---------|---------|
434+
|`-h`, `--help` | Shows the help message and exits. |
435+
|`-i <INCLUDE>`, `--include <INCLUDE>` | The path to a file that contains the devices and subnet masks you want to include, where `<INCLUDE>` is the path to the file. For example, see [Sample include or exclude file](#txt). |
436+
|`-x EXCLUDE`, `--exclude EXCLUDE` | The path to a file that contains the devices and subnet masks you want to exclude, where `<EXCLUDE>` is the path to the file. For example, see [Sample include or exclude file](#txt). |
437+
|- `-etp <EXCLUDE_TCP_PORT>`, `--exclude-tcp-port <EXCLUDE_TCP_PORT>` | Excludes TCP traffic on any specified ports, where the `<EXCLUDE_TCP_PORT>` defines the port or ports you want to exclude. Delimitate multiple ports by commas, with no spaces. |
438+
|`-eup <EXCLUDE_UDP_PORT>`, `--exclude-udp-port <EXCLUDE_UDP_PORT>` | Excludes UDP traffic on any specified ports, where the `<EXCLUDE_UDP_PORT>` defines the port or ports you want to exclude. Delimitate multiple ports by commas, with no spaces. |
439+
|`-itp <INCLUDE_TCP_PORT>`, `--include-tcp-port <INCLUDE_TCP_PORT>` | Includes TCP traffic on any specified ports, where the `<INCLUDE_TCP_PORT>` defines the port or ports you want to include. Delimitate multiple ports by commas, with no spaces. |
440+
|`-iup <INCLUDE_UDP_PORT>`, `--include-udp-port <INCLUDE_UDP_PORT>` | Includes UDP traffic on any specified ports, where the `<INCLUDE_UDP_PORT>` defines the port or ports you want to include. Delimitate multiple ports by commas, with no spaces. |
441+
|`-vlan <INCLUDE_VLAN_IDS>`, `--include-vlan-ids <INCLUDE_VLAN_IDS>` | Includes VLAN traffic by specified VLAN IDs, `<INCLUDE_VLAN_IDS>` defines the VLAN ID or IDs you want to include. Delimitate multiple VLAN IDs by commas, with no spaces. |
442+
|`-p <PROGRAM>`, `--program <PROGRAM>` | Defines the component for which you want to configure a capture filter. Use `all` for basic use cases, to create a single capture filter for all components. <br><br>For advanced use cases, create separate capture filters for each component. For more information, see [Create an advanced filter for specific components](#create-an-advanced-filter-for-specific-components).|
443+
|`-m <MODE>`, `--mode <MODE>` | Defines an include list mode, and is relevant only when an include list is used. Use one of the following values: <br><br>- `internal`: Includes all communication between the specified source and destination <br>- `all-connected`: Includes all communication between either of the specified endpoints and external endpoints. <br><br>For example, for endpoints A and B, if you use the `internal` mode, included traffic will only include communications between endpoints **A** and **B**. <br>However, if you use the `all-connected` mode, included traffic will include all communications between A *or* B and other, external endpoints. |
444+
445+
<a name="txt"></a>**Sample include or exclude file**
446+
447+
For example, an include or exclude **.txt** file might include the following entries:
448+
449+
```txt
450+
192.168.50.10
451+
172.20.248.1
452+
```
453+
454+
#### Create a basic capture filter using the admin user
455+
456+
If you're creating a basic capture filter as the *admin* user, no attributes are passed in the [original command](#create-a-basic-filter-for-all-components). Instead, a series of prompts is displayed to help you create the capture filter interactively.
457+
458+
Reply to the prompts displayed as follows:
459+
460+
1. `Would you like to supply devices and subnet masks you wish to include in the capture filter? [Y/N]:`
461+
462+
Select `Y` to open a new include file, where you can add a device, channel, and/or subnet that you want to include in monitored traffic. Any other traffic, not listed in your include file, isn't ingested to Defender for IoT.
463+
464+
The include file is opened in the [Nano](https://www.nano-editor.org/dist/latest/cheatsheet.html) text editor. In the include file, define devices, channels, and subnets as follows:
465+
466+
|Type |Description |Example |
467+
|---------|---------|---------|
468+
|**Device** | Define a device by its IP address. | `1.1.1.1` includes all traffic for this device. |
469+
|**Channel** | Define a channel by the IP addresses of its source and destination devices, separated by a comma. | `1.1.1.1,2.2.2.2` includes all of the traffic for this channel. |
470+
|**Subnet** | Define a subnet by its network address. | `1.1.1` includes all traffic for this subnet. |
471+
472+
List multiple arguments in separate rows.
473+
474+
1. `Would you like to supply devices and subnet masks you wish to exclude from the capture filter? [Y/N]:`
475+
476+
Select `Y` to open a new exclude file where you can add a device, channel, and/or subnet that you want to exclude from monitored traffic. Any other traffic, not listed in your exclude file, is ingested to Defender for IoT.
477+
478+
The exclude file is opened in the [Nano](https://www.nano-editor.org/dist/latest/cheatsheet.html) text editor. In the exclude file, define devices, channels, and subnets as follows:
479+
480+
|Type |Description |Example |
481+
|---------|---------|---------|
482+
| **Device** | Define a device by its IP address. | `1.1.1.1` excludes all traffic for this device. |
483+
| **Channel** | Define a channel by the IP addresses of its source and destination devices, separated by a comma. | `1.1.1.1,2.2.2.2` excludes all of the traffic between these devices. |
484+
| **Channel by port** | Define a channel by the IP addresses of its source and destination devices, and the traffic port. | `1.1.1.1,2.2.2.2,443` excludes all of the traffic between these devices and using the specified port.|
485+
| **Subnet** | Define a subnet by its network address. | `1.1.1` excludes all traffic for this subnet. |
486+
| **Subnet channel** | Define subnet channel network addresses for the source and destination subnets. | `1.1.1,2.2.2` excludes all of the traffic between these subnets. |
487+
488+
List multiple arguments in separate rows.
489+
490+
1. Reply to the following prompts to define any TCP or UDP ports to include or exclude. Separate multiple ports by comma, and press ENTER to skip any specific prompt.
491+
492+
- `Enter tcp ports to include (delimited by comma or Enter to skip):`
493+
- `Enter udp ports to include (delimited by comma or Enter to skip):`
494+
- `Enter tcp ports to exclude (delimited by comma or Enter to skip):`
495+
- `Enter udp ports to exclude (delimited by comma or Enter to skip):`
496+
- `Enter VLAN ids to include (delimited by comma or Enter to skip):`
497+
498+
For example, enter multiple ports as follows: `502,443`
499+
500+
1. `In which component do you wish to apply this capture filter?`
501+
502+
Enter `all` for a basic capture filter. For [advanced use cases](#create-an-advanced-capture-filter-using-the-admin-user), create capture filters for each Defender for IoT component separately.
503+
504+
1. `Type Y for "internal" otherwise N for "all-connected" (custom operation mode enabled) [Y/N]:`
505+
506+
This prompt allows you to configure which traffic is in scope. Define whether you want to collect traffic where both endpoints are in scope, or only one of them is in the specified subnet. Supported values include:
507+
508+
- `internal`: Includes all communication between the specified source and destination
509+
- `all-connected`: Includes all communication between either of the specified endpoints and external endpoints.
510+
511+
For example, for endpoints A and B, if you use the `internal` mode, included traffic will only include communications between endpoints **A** and **B**. <br>However, if you use the `all-connected` mode, included traffic will include all communications between A *or* B and other, external endpoints.
512+
513+
The default mode is `internal`. To use the `all-connected` mode, select `Y` at the prompt, and then enter `all-connected`.
514+
515+
The following example shows a series of prompts that creates a capture filter to exclude subnet `192.168.x.x` and port `9000:`
516+
517+
```bash
518+
root@xsense: network capture-filter
519+
Would you like to supply devices and subnet masks you wish to include in the capture filter? [y/N]: n
520+
Would you like to supply devices and subnet masks you wish to exclude from the capture filter? [y/N]: y
521+
You've exited the editor. Would you like to apply your modifications? [y/N]: y
522+
Enter tcp ports to include (delimited by comma or Enter to skip):
523+
Enter udp ports to include (delimited by comma or Enter to skip):
524+
Enter tcp ports to exclude (delimited by comma or Enter to skip):9000
525+
Enter udp ports to exclude (delimited by comma or Enter to skip):9000
526+
Enter VLAN ids to include (delimited by comma or Enter to skip):
527+
In which component do you wish to apply this capture filter?all
528+
Would you like to supply a custom base capture filter for the collector component? [y/N]: n
529+
Would you like to supply a custom base capture filter for the traffic_monitor component? [y/N]: n
530+
Would you like to supply a custom base capture filter for the horizon component? [y/N]: n
531+
type Y for "internal" otherwise N for "all-connected" (custom operation mode enabled) [Y/n]: internal
532+
Please respond with 'yes' or 'no' (or 'y' or 'n').
533+
type Y for "internal" otherwise N for "all-connected" (custom operation mode enabled) [Y/n]: y
534+
starting "/usr/local/bin/cyberx-xsense-capture-filter --exclude /var/cyberx/media/capture-filter/exclude --exclude-tcp-port 9000 --exclude-udp-port 9000 --program all --mode internal --from-shell"
535+
No include file given
536+
Loaded 1 unique channels
537+
(000) ret #262144
538+
(000) ldh [12]
539+
......
540+
......
541+
......
542+
debug: set new filter for horizon '(((not (net 192.168))) and (not (tcp port 9000)) and (not (udp port 9000))) or (vlan and ((not (net 192.168))) and (not (tcp port 9000)) and (not (udp port 9000)))'
543+
root@xsense:
544+
```
545+
546+
### Create an advanced filter for specific components
547+
548+
When configuring advanced capture filters for specific components, you can use your initial include and exclude files as a base, or template, capture filter. Then, configure extra filters for each component on top of the base as needed.
549+
550+
To create a capture filter for *each* component, make sure to repeat the entire process for each component.
551+
552+
> [!NOTE]
553+
> If you've created different capture filters for different components, the mode selection is used for all components. Defining the capture filter for one component as `internal` and the capture filter for another component as `all-connected` isn't supported.
554+
555+
|User |Command |Full command syntax |
556+
|---------|---------|---------|
557+
| **admin** | `network capture-filter` | No attributes.|
558+
| **cyberx**, or **admin** with [root access](references-work-with-defender-for-iot-cli-commands.md#access-the-system-root-as-an-admin-user) | `cyberx-xsense-capture-filter` | `cyberx-xsense-capture-filter [-h] [-i INCLUDE] [-x EXCLUDE] [-etp EXCLUDE_TCP_PORT] [-eup EXCLUDE_UDP_PORT] [-itp INCLUDE_TCP_PORT] [-iup INCLUDE_UDP_PORT] [-vlan INCLUDE_VLAN_IDS] -p PROGRAM [-o BASE_HORIZON] [-s BASE_TRAFFIC_MONITOR] [-c BASE_COLLECTOR] -m MODE [-S]` |
559+
560+
The following extra attributes are used for the *cyberx* user to create capture filters for each component separately:
561+
562+
|Attribute |Description |
563+
|---------|---------|
564+
|`-p <PROGRAM>`, `--program <PROGRAM>` | Defines the component for which you want to configure a capture filter, where `<PROGRAM>` has the following supported values: <br>- `traffic-monitor` <br>- `collector` <br>- `horizon` <br>- `all`: Creates a single capture filter for all components. For more information, see [Create a basic filter for all components](#create-a-basic-filter-for-all-components).|
565+
|`-o <BASE_HORIZON>`, `--base-horizon <BASE_HORIZON>` | Defines a base capture filter for the `horizon` component, where `<BASE_HORIZON>` is the filter you want to use. <br> Default value = `""` |
566+
|`-s BASE_TRAFFIC_MONITOR`, `--base-traffic-monitor BASE_TRAFFIC_MONITOR` | Defines a base capture filter for the `traffic-monitor` component. <br> Default value = `""` |
567+
|`-c BASE_COLLECTOR`, `--base-collector BASE_COLLECTOR` | Defines a base capture filter for the `collector` component. <br> Default value = `""` |
568+
569+
Other attribute values have the same descriptions as in the basic use case, described [earlier](#create-a-basic-filter-for-all-components).
570+
571+
#### Create an advanced capture filter using the admin user
572+
573+
If you're creating a capture filter for each component separately as the *admin* user, no attributes are passed in the [original command](#create-an-advanced-filter-for-specific-components). Instead, a series of prompts is displayed to help you create the capture filter interactively.
574+
575+
Most of the prompts are identical to [basic use case](#create-a-basic-capture-filter-using-the-admin-user). Reply to the following extra prompts as follows:
576+
577+
1. `In which component do you wish to apply this capture filter?`
578+
579+
Enter one of the following values, depending on the component you want to filter:
580+
581+
- `horizon`
582+
- `traffic-monitor`
583+
- `collector`
584+
585+
1. You're prompted to configure a custom base capture filter for the selected component. This option uses the capture filter you configured in the previous steps as a base, or template, where you can add extra configurations on top of the base.
586+
587+
For example, if you'd selected to configure a capture filter for the `collector` component in the previous step, you're prompted: `Would you like to supply a custom base capture filter for the collector component? [Y/N]:`
588+
589+
Enter `Y` to customize the template for the specified component, or `N` to use the capture filter you'd configured earlier as it is.
590+
591+
Continue with the remaining prompts as in the [basic use case](#create-a-basic-capture-filter-using-the-admin-user).
592+
593+
### List current capture filters for specific components
594+
595+
Use the following commands to show details about the current capture filters configured for your sensor.
596+
597+
|User |Command |Full command syntax |
598+
|---------|---------|---------|
599+
| **admin** | Use the following commands to view the capture filters for each component: <br><br>- **horizon**: `edit-config horizon_parser/horizon.properties` <br>- **traffic-monitor**: `edit-config traffic_monitor/traffic-monitor` <br>- **collector**: `edit-config dumpark.properties` | No attributes |
600+
| **cyberx**, or **admin** with [root access](references-work-with-defender-for-iot-cli-commands.md#access-the-system-root-as-an-admin-user) | Use the following commands to view the capture filters for each component: <br><br>-**horizon**: `nano /var/cyberx/properties/horizon_parser/horizon.properties` <br>- **traffic-monitor**: `nano /var/cyberx/properties/traffic_monitor/traffic-monitor.properties` <br>- **collector**: `nano /var/cyberx/properties/dumpark.properties` | No attributes |
601+
602+
These commands open the following files, which list the capture filters configured for each component:
603+
604+
|Name |File |Property |
605+
|---------|---------|---------|
606+
|**horizon** | `/var/cyberx/properties/horizon.properties` | `horizon.processor.filter` |
607+
|**traffic-monitor** | `/var/cyberx/properties/traffic-monitor.properties` | `horizon.processor.filter` |
608+
|**collector** | `/var/cyberx/properties/dumpark.properties` | `dumpark.network.filter` |
609+
610+
For example with the **admin** user, with a capture filter defined for the *collector* component that excludes subnet 192.168.x.x and port 9000:
611+
612+
```bash
613+
614+
root@xsense: edit-config dumpark.properties
615+
GNU nano 2.9.3 /tmp/tmpevt4igo7/tmpevt4igo7
616+
617+
dumpark.network.filter=(((not (net 192.168))) and (not (tcp port 9000)) and (not
618+
dumpark.network.snaplen=4096
619+
dumpark.packet.filter.data.transfer=false
620+
dumpark.infinite=true
621+
dumpark.output.session=false
622+
dumpark.output.single=false
623+
dumpark.output.raw=true
624+
dumpark.output.rotate=true
625+
dumpark.output.rotate.history=300
626+
dumpark.output.size=20M
627+
dumpark.output.time=30S
628+
```
629+
630+
### Reset all capture filters
631+
632+
Use the following command to reset your sensor to the default capture configuration with the *cyberx* user, removing all capture filters.
633+
634+
|User |Command |Full command syntax |
635+
|---------|---------|---------|
636+
| **cyberx**, or **admin** with [root access](references-work-with-defender-for-iot-cli-commands.md#access-the-system-root-as-an-admin-user) | `cyberx-xsense-capture-filter -p all -m all-connected` | No attributes |
637+
638+
If you want to modify the existing capture filters, run the [earlier](#create-a-basic-filter-for-all-components) command again, with new attribute values.
639+
640+
To reset all capture filters using the *admin* user, run the [earlier](#create-a-basic-filter-for-all-components) command again, and respond `N` to all [prompts](#create-a-basic-capture-filter-using-the-admin-user) to reset all capture filters.
641+
642+
The following example shows the command syntax and response for the *cyberx* user:
643+
644+
```bash
645+
root@xsense:/# cyberx-xsense-capture-filter -p all -m all-connected
646+
starting "/usr/local/bin/cyberx-xsense-capture-filter -p all -m all-connected"
647+
No include file given
648+
No exclude file given
649+
(000) ret #262144
650+
(000) ret #262144
651+
debug: set new filter for dumpark ''
652+
No include file given
653+
No exclude file given
654+
(000) ret #262144
655+
(000) ret #262144
656+
debug: set new filter for traffic-monitor ''
657+
No include file given
658+
No exclude file given
659+
(000) ret #262144
660+
(000) ret #262144
661+
debug: set new filter for horizon ''
662+
root@xsense:/#
663+
```
664+
399665
## Next steps
400666
401667
> [!div class="nextstepaction"]

0 commit comments

Comments
 (0)