Merge pull request #1257 from vyos/mergify/bp/sagitta/pr-1255

Adding first documentation regarding IDS and FastNetMon. Also a brief… (backport #1255)

2 files changed, 182 insertions, 1 deletions

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 <text>
+
+    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 <x.x.x.x/x>
+.. cfgcmd:: set service ids ddos-protection exlude-network <h:h:h:h:h:h:h:h/x>
+
+    Specify IPv4 and/or IPv6 networks which are going to be excluded.
+
+.. cfgcmd:: set service ids ddos-protection listen-interface <text>
+
+    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 <x.x.x.x/x>
+.. cfgcmd:: set service ids ddos-protection network <h:h:h:h:h:h:h:h/x>
+
+    Specify IPv4 and/or IPv6 networks that should be protected/monitored.
+
+.. cfgcmd:: set service ids ddos-protection sflow listen-address <x.x.x.x>
+
+    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
+