From e2d80596eb71181b1b08071a10fac8d3c922df57 Mon Sep 17 00:00:00 2001 From: Nicolas Fort Date: Tue, 23 Jan 2024 06:57:42 -0300 Subject: Adding first documentation regarding IDS and FastNetMon. Also a brief configuration example is provided. (cherry picked from commit 57cdbe065b89ec38a779ddb7530cda3ac240caf2) --- docs/configuration/service/ids.rst | 179 +++++++++++++++++++++++++++++++++++ docs/configuration/service/index.rst | 4 +- 2 files changed, 182 insertions(+), 1 deletion(-) create mode 100644 docs/configuration/service/ids.rst (limited to 'docs/configuration') diff --git a/docs/configuration/service/ids.rst b/docs/configuration/service/ids.rst new file mode 100644 index 00000000..3e508d50 --- /dev/null +++ b/docs/configuration/service/ids.rst @@ -0,0 +1,179 @@ +.. _ids: + +############### +DDoS Protection +############### + +********** +FastNetMon +********** + +FastNetMon is a high-performance DDoS detector/sensor built on top of multiple +packet capture engines: NetFlow, IPFIX, sFlow, AF_PACKET (port mirror). It can +detect hosts in the deployed network sending or receiving large volumes of +traffic, packets/bytes/flows per second and perform a configurable action to +handle that event, such as calling a custom script. + +VyOS includes the FastNetMon Community Edition. + +Configuration +============= + +.. cfgcmd:: set service ids ddos-protection alert-script + + Configure alert script that will be executed when an attack is detected. + +.. cfgcmd:: set service ids ddos-protection ban-time <1-4294967294> + + Configure how long an IP (attacker) should be kept in blocked state. + Default value is 1900. + +.. cfgcmd:: set service ids ddos-protection direction [in | out] + + Configure direction for processing traffic. + +.. cfgcmd:: set service ids ddos-protection exclude-network +.. cfgcmd:: set service ids ddos-protection exlude-network + + Specify IPv4 and/or IPv6 networks which are going to be excluded. + +.. cfgcmd:: set service ids ddos-protection listen-interface + + Configure listen interface for mirroring traffic. + +.. cfgcmd:: set service ids ddos-protection mode [mirror | sflow] + + Configure traffic capture mode. + +.. cfgcmd:: set service ids ddos-protection network +.. cfgcmd:: set service ids ddos-protection network + + Specify IPv4 and/or IPv6 networks that should be protected/monitored. + +.. cfgcmd:: set service ids ddos-protection sflow listen-address + + Configure local IPv4 address to listen for sflow. + +.. cfgcmd:: set service ids ddos-protection sflow port <1-65535> + + Configure port number to be used for sflow conection. Default port is 6343. + +.. cfgcmd:: set service ids ddos-protection threshold general + [fps | mbps | pps] <0-4294967294> + + Configure general threshold parameters. + +.. cfgcmd:: set service ids ddos-protection threshold icmp + [fps | mbps | pps] <0-4294967294> + + Configure ICMP threshold parameters. + +.. cfgcmd:: set service ids ddos-protection threshold tcp + [fps | mbps | pps] <0-4294967294> + + Configure TCP threshold parameters + +.. cfgcmd:: set service ids ddos-protection threshold udp + [fps | mbps | pps] <0-4294967294> + + Configure UDP threshold parameters + +Example +======= + +A configuration example can be found in this section. +In this simplified scenario, main things to be considered are: + + * Network to be protected: 192.0.2.0/24 (public IPs use by + customers) + + * **ban-time** and **threshold**: these values are kept very low in order + to easily identify and generate and attack. + + * Direction: **in** and **out**. Protect public network from external + attacks, and identify internal attacks towards internet. + + * Interface **eth0** used to connect to upstream. + +Since we are analyzing attacks to and from our internal network, two types +of attacks can be identified, and differents actions are needed: + + * External attack: an attack from the internet towards an internal IP + is identify. In this case, all connections towards such IP will be + blocked + + * Internal attack: an attack from the internal network (generated by a + customer) towards the internet is identify. In this case, all connections + from this particular IP/Customer will be blocked. + + +So, firewall configuration needed for this setup: + +.. code-block:: none + + set firewall group address-group FNMS-DST-Block + set firewall group address-group FNMS-SRC-Block + + set firewall ipv4 forward filter rule 10 action 'drop' + set firewall ipv4 forward filter rule 10 description 'FNMS - block destination' + set firewall ipv4 forward filter rule 10 destination group address-group 'FNMS-DST-Block' + + set firewall ipv4 forward filter rule 20 action 'drop' + set firewall ipv4 forward filter rule 20 description 'FNMS - Block source' + set firewall ipv4 forward filter rule 20 source group address-group 'FNMS-SRC-Block' + +Then, FastNetMon configuration: + +.. code-block:: none + + set service ids ddos-protection alert-script '/config/scripts/fnm-alert.sh' + set service ids ddos-protection ban-time '10' + set service ids ddos-protection direction 'in' + set service ids ddos-protection direction 'out' + set service ids ddos-protection listen-interface 'eth0' + set service ids ddos-protection mode 'mirror' + set service ids ddos-protection network '192.0.2.0/24' + set service ids ddos-protection threshold general pps '100' + +And content of the script: + +.. code-block:: none + + #!/bin/bash + + # alert-script is called twice. + # When an attack occurs, the program calls a bash script twice: + # 1st time when threshold exceed + # 2nd when we collect 100 packets for detailed audit of what happened. + + # Do nothing if “attack_details” is passed as an argument + if [ "${4}" == "attack_details" ]; then + # Do nothing + exit + fi + # Arguments: + ip=$1 + direction=$2 + pps_rate=$3 + action=$4 + + logger -t FNMS "** Start - Running alert script **" + + if [ "${direction}" == "incoming" ] ; then + group="FNMS-DST-Block" + origin="external" + else + group="FNMS-SRC-Block" + origin="internal" + fi + + if [ "${action}" == "ban" ] ; then + logger -t FNMS "Attack detected for IP ${ip} and ${direction} direction from ${origin} network. Need to block IP address." + logger -t FNMS "Adding IP address ${ip} to firewall group ${group}." + sudo nft add element ip vyos_filter A_${group} { ${ip} } + else + logger -t FNMS "Timeout for IP ${ip}, removing it from group ${group}." + sudo nft delete element ip vyos_filter A_${group} { ${ip} } + fi + logger -t FNMS "** End - Running alert script **" + exit diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst index 1195348f..56ce55eb 100644 --- a/docs/configuration/service/index.rst +++ b/docs/configuration/service/index.rst @@ -13,7 +13,9 @@ Service dhcp-relay dhcp-server dns + eventhandler https + ids ipoe-server lldp mdns @@ -26,4 +28,4 @@ Service ssh tftp-server webproxy - eventhandler + -- cgit v1.2.3