Merge pull request #1435 from vyos/mergify/bp/sagitta/pr-1434

Firewall: add documentation for dynamic firewall groups. (backport #1434)

3 files changed, 292 insertions, 31 deletions

diff --git a/docs/configuration/firewall/groups.rst b/docs/configuration/firewall/groups.rst
index aee68793..6111650a 100644
--- a/docs/configuration/firewall/groups.rst
+++ b/docs/configuration/firewall/groups.rst
@@ -21,9 +21,9 @@ Address Groups
 In an **address group** a single IP address or IP address ranges are
 defined.
 
-.. cfgcmd::  set firewall group address-group <name> address [address |
+.. cfgcmd:: set firewall group address-group <name> address [address |
    address range]
-.. cfgcmd::  set firewall group ipv6-address-group <name> address <address>
+.. cfgcmd:: set firewall group ipv6-address-group <name> address <address>
 
    Define a IPv4 or a IPv6 address group
 
@@ -33,8 +33,8 @@ defined.
       set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8
       set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1
 
-.. cfgcmd::  set firewall group address-group <name> description <text>
-.. cfgcmd::  set firewall group ipv6-address-group <name> description <text>
+.. cfgcmd:: set firewall group address-group <name> description <text>
+.. cfgcmd:: set firewall group ipv6-address-group <name> description <text>
 
    Provide a IPv4 or IPv6 address group description
 
@@ -46,8 +46,8 @@ IP addresses can be added as a 32-bit prefix. If you foresee the need
 to add a mix of addresses and networks, the network group is
 recommended.
 
-.. cfgcmd::  set firewall group network-group <name> network <CIDR>
-.. cfgcmd::  set firewall group ipv6-network-group <name> network <CIDR>
+.. cfgcmd:: set firewall group network-group <name> network <CIDR>
+.. cfgcmd:: set firewall group ipv6-network-group <name> network <CIDR>
 
    Define a IPv4 or IPv6 Network group.
 
@@ -57,8 +57,8 @@ recommended.
       set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24
       set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64
 
-.. cfgcmd::  set firewall group network-group <name> description <text>
-.. cfgcmd::  set firewall group ipv6-network-group <name> description <text>
+.. cfgcmd:: set firewall group network-group <name> description <text>
+.. cfgcmd:: set firewall group ipv6-network-group <name> description <text>
 
    Provide an IPv4 or IPv6 network group description.
 
@@ -67,7 +67,7 @@ Interface Groups
 
 An **interface group** represents a collection of interfaces.
 
-.. cfgcmd::  set firewall group interface-group <name> interface <text>
+.. cfgcmd:: set firewall group interface-group <name> interface <text>
 
    Define an interface group. Wildcard are accepted too.
 
@@ -76,7 +76,7 @@ An **interface group** represents a collection of interfaces.
       set firewall group interface-group LAN interface bond1001
       set firewall group interface-group LAN interface eth3*
 
-.. cfgcmd::  set firewall group interface-group <name> description <text>
+.. cfgcmd:: set firewall group interface-group <name> description <text>
 
    Provide an interface group description
 
@@ -110,7 +110,7 @@ MAC Groups
 
 A **mac group** represents a collection of mac addresses.
 
-.. cfgcmd::  set firewall group mac-group <name> mac-address <mac-address>
+.. cfgcmd:: set firewall group mac-group <name> mac-address <mac-address>
 
    Define a mac group.
 
@@ -128,7 +128,7 @@ Domain Groups
 
 A **domain group** represents a collection of domains.
 
-.. cfgcmd::  set firewall group domain-group <name> address <domain>
+.. cfgcmd:: set firewall group domain-group <name> address <domain>
 
    Define a domain group.
 
@@ -140,10 +140,108 @@ A **domain group** represents a collection of domains.
 
    Provide a domain group description.
 
+Dynamic Groups
+==============
+
+Firewall dynamic groups are different from all the groups defined previously
+because, not only they can be used as source/destination in firewall rules,
+but members of these groups are not defined statically using vyos
+configuration.
+
+Instead, members of these groups are added dynamically using firewall
+rules.
+
+Defining Dynamic Address Groups
+-------------------------------
+
+Dynamic address group is supported by both IPv4 and IPv6 families.
+Commands used to define dynamic IPv4|IPv6 address groups are:
+
+.. cfgcmd:: set firewall group dynamic-group address-group <name>
+.. cfgcmd:: set firewall group dynamic-group ipv6-address-group <name>
+
+Add description to firewall groups:
+
+.. cfgcmd:: set firewall group dynamic-group address-group <name>
+   description <text>
+.. cfgcmd:: set firewall group dynamic-group ipv6-address-group <name>
+   description <text>
+
+Adding elements to Dynamic Firewall Groups
+------------------------------------------
+
+Once dynamic firewall groups are defined, they should be used in firewall
+rules in order to dynamically add elements to it.
+
+Commands used for this task are:
+
+* Add destination IP address of the connection to a dynamic address group:
+
+.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule
+   <1-999999> add-address-to-group destination-address address-group <name>
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group
+   destination-address address-group <name>
+.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule
+   <1-999999> add-address-to-group destination-address address-group <name>
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group
+   destination-address address-group <name>
+
+* Add source IP address of the connection to a dynamic address group:
+
+.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule
+   <1-999999> add-address-to-group source-address address-group <name>
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group
+   source-address address-group <name>
+.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule
+   <1-999999> add-address-to-group source-address address-group <name>
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group
+   source-address address-group <name>
+
+Also, specific timeout can be defined per rule. In case rule gets a hit,
+source or destinatination address will be added to the group, and this
+element will remain in the group until timeout expires. If no timeout
+is defined, then the element will remain in the group until next reboot,
+or until a new commit that changes firewall configuration is done.
+
+.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule
+   <1-999999> add-address-to-group [destination-address | source-address]
+   timeout <timeout>
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group
+   [destination-address | source-address] timeout <timeout>
+.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule
+   <1-999999> add-address-to-group [destination-address | source-address]
+   timeout <timeout>
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group
+   [destination-address | source-address] timeout <timeout>
+
+Timeout can be defined using seconds, minutes, hours or days:
+
+.. code-block:: none
+
+   set firewall ipv6 name FOO rule 10 add-address-to-group source-address timeout
+   Possible completions:
+   <number>s            Timeout value in seconds
+   <number>m            Timeout value in minutes
+   <number>h            Timeout value in hours
+   <number>d            Timeout value in days
+
+Using Dynamic Firewall Groups
+-----------------------------
+
+As any other firewall group, dynamic firewall groups can be used in firewall
+rules as matching options. For example:
+
+.. code-block:: none
+   set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO
+   set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR
+
 ********
 Examples
 ********
 
+General example
+===============
+
 As said before, once firewall groups are created, they can be referenced
 either in firewall, nat, nat66 and/or policy-route rules.
 
@@ -166,12 +264,12 @@ And next, some configuration example where groups are used:
 
    .. code-block:: none
       
-      set firewall ipv4 input filter rule 10 action accept
-      set firewall ipv4 input filter rule 10 inbound-interface group !LAN
+      set firewall ipv4 output filter rule 10 action accept
+      set firewall ipv4 output filter rule 10 outbound-interface group !LAN
       set firewall ipv4 forward filter rule 20 action accept
       set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4
       set firewall ipv6 input filter rule 10 action accept
-      set firewall ipv6 input filter rule 10 source-group network-group TRUSTEDv6
+      set firewall ipv6 input filter rule 10 source group network-group TRUSTEDv6
       set nat destination rule 101 inbound-interface group LAN
       set nat destination rule 101 destination group address-group SERVERS
       set nat destination rule 101 protocol tcp
@@ -181,30 +279,151 @@ And next, some configuration example where groups are used:
       set policy route PBR rule 201 protocol tcp
       set policy route PBR rule 201 set table 15
 
+Port knocking example
+=====================
+
+Using dynamic firewall groups, we can secure access to the router, or any other
+device if needed, by using the technique of port knocking.
+
+A 4 step port knocking example is shown next:
+
+   .. code-block:: none
+
+      set firewall global-options state-policy established action 'accept'
+      set firewall global-options state-policy invalid action 'drop'
+      set firewall global-options state-policy related action 'accept'
+      set firewall group dynamic-group address-group ALLOWED
+      set firewall group dynamic-group address-group PN_01
+      set firewall group dynamic-group address-group PN_02
+      set firewall ipv4 input filter default-action 'drop'
+      set firewall ipv4 input filter rule 5 action 'accept'
+      set firewall ipv4 input filter rule 5 protocol 'icmp'
+      set firewall ipv4 input filter rule 10 action 'drop'
+      set firewall ipv4 input filter rule 10 add-address-to-group source-address address-group 'PN_01'
+      set firewall ipv4 input filter rule 10 add-address-to-group source-address timeout '2m'
+      set firewall ipv4 input filter rule 10 description 'Port_nock 01'
+      set firewall ipv4 input filter rule 10 destination port '9990'
+      set firewall ipv4 input filter rule 10 protocol 'tcp'
+      set firewall ipv4 input filter rule 20 action 'drop'
+      set firewall ipv4 input filter rule 20 add-address-to-group source-address address-group 'PN_02'
+      set firewall ipv4 input filter rule 20 add-address-to-group source-address timeout '3m'
+      set firewall ipv4 input filter rule 20 description 'Port_nock 02'
+      set firewall ipv4 input filter rule 20 destination port '9991'
+      set firewall ipv4 input filter rule 20 protocol 'tcp'
+      set firewall ipv4 input filter rule 20 source group dynamic-address-group 'PN_01'
+      set firewall ipv4 input filter rule 30 action 'drop'
+      set firewall ipv4 input filter rule 30 add-address-to-group source-address address-group 'ALLOWED'
+      set firewall ipv4 input filter rule 30 add-address-to-group source-address timeout '2h'
+      set firewall ipv4 input filter rule 30 description 'Port_nock 03'
+      set firewall ipv4 input filter rule 30 destination port '9992'
+      set firewall ipv4 input filter rule 30 protocol 'tcp'
+      set firewall ipv4 input filter rule 30 source group dynamic-address-group 'PN_02'
+      set firewall ipv4 input filter rule 99 action 'accept'
+      set firewall ipv4 input filter rule 99 description 'Port_nock 04 - Allow ssh'
+      set firewall ipv4 input filter rule 99 destination port '22'
+      set firewall ipv4 input filter rule 99 protocol 'tcp'
+      set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED'
+
+Before testing, we can check members of firewall groups:
+
+   .. code-block:: none
+
+      vyos@vyos# run show firewall group
+      Firewall Groups
+
+      Name     Type                    References            Members        Timeout    Expires
+      -------  ----------------------  --------------------  -------------  ---------  ---------
+      ALLOWED  address_group(dynamic)  ipv4-input-filter-30  N/D            N/D        N/D
+      PN_01    address_group(dynamic)  ipv4-input-filter-10  N/D            N/D        N/D
+      PN_02    address_group(dynamic)  ipv4-input-filter-20  N/D            N/D        N/D
+      [edit]
+      vyos@vyos#
+
+With this configuration, in order to get ssh access to the router, user
+needs to:
+
+1. Generate a new TCP connection with destination port 9990. As shown next,
+a new entry was added to dynamic firewall group **PN_01**
+
+   .. code-block:: none
+
+      vyos@vyos# run show firewall group
+      Firewall Groups
+
+      Name     Type                    References            Members        Timeout    Expires
+      -------  ----------------------  --------------------  -------------  ---------  ---------
+      ALLOWED  address_group(dynamic)  ipv4-input-filter-30  N/D            N/D        N/D
+      PN_01    address_group(dynamic)  ipv4-input-filter-10  192.168.89.31  120        119
+      PN_02    address_group(dynamic)  ipv4-input-filter-20  N/D            N/D        N/D
+      [edit]
+      vyos@vyos#
+
+2. Generate a new TCP connection with destination port 9991. As shown next,
+a new entry was added to dynamic firewall group **PN_02**
+
+   .. code-block:: none
+
+      vyos@vyos# run show firewall group
+      Firewall Groups
+
+      Name     Type                    References            Members        Timeout    Expires
+      -------  ----------------------  --------------------  -------------  ---------  ---------
+      ALLOWED  address_group(dynamic)  ipv4-input-filter-30  N/D            N/D        N/D
+      PN_01    address_group(dynamic)  ipv4-input-filter-10  192.168.89.31  120        106
+      PN_02    address_group(dynamic)  ipv4-input-filter-20  192.168.89.31  180        179
+      [edit]
+      vyos@vyos#
+
+3. Generate a new TCP connection with destination port 9992. As shown next,
+a new entry was added to dynamic firewall group **ALLOWED**
+
+   .. code-block:: none
+
+      vyos@vyos# run show firewall group
+      Firewall Groups
+
+      Name     Type                    References            Members        Timeout    Expires
+      -------  ----------------------  --------------------  -------------  ---------  ---------
+      ALLOWED  address_group(dynamic)  ipv4-input-filter-30  192.168.89.31       7200       7199
+      PN_01    address_group(dynamic)  ipv4-input-filter-10  192.168.89.31        120         89
+      PN_02    address_group(dynamic)  ipv4-input-filter-20  192.168.89.31        180        170
+      [edit]
+      vyos@vyos#
+
+4. Now user can connect through ssh to the router (assuming ssh is configured).
+
 **************
 Operation-mode
 **************
 
+.. opcmd:: show firewall group
 .. opcmd:: show firewall group <name>
 
-   Overview of defined groups. You see the type, the members, and where the
-   group is used.
+   Overview of defined groups. You see the firewall group name, type,
+   references (where the group is used), members, timeout and expiration (last
+   two only present in dynamic firewall groups).
+
+Here is an example of such command:
 
    .. code-block:: none
 
-      vyos@ZBF-15-CLean:~$ show firewall group 
+      vyos@vyos:~$ show firewall group
       Firewall Groups
 
-      Name          Type                References              Members
-      ------------  ------------------  ----------------------  ----------------
-      SERVERS       address_group       nat-destination-101     198.51.100.101
-                                                                198.51.100.102
-      LAN           interface_group     ipv4-input-filter-10    bon0
-                                        nat-destination-101     eth2.2001
-      TRUSTEDv6     ipv6_network_group  ipv6-input-filter-10    2001:db8::/64
-      TRUSTEDv4     network_group       ipv4-forward-filter-20  192.0.2.0/30
-                                                                203.0.113.128/25
-      PORT-SERVERS  port_group          route-PBR-201           443
-                                        nat-destination-101     5000-5010
-                                                                http
-      vyos@ZBF-15-CLean:~$
+      Name          Type                    References              Members             Timeout    Expires
+      ------------  ----------------------  ----------------------  ----------------  ---------  ---------
+      SERVERS       address_group           nat-destination-101     198.51.100.101
+                                                                    198.51.100.102
+      ALLOWED       address_group(dynamic)  ipv4-input-filter-30    192.168.77.39          7200       7174
+      PN_01         address_group(dynamic)  ipv4-input-filter-10    192.168.0.245           120        112
+                                                                    192.168.77.39           120         85
+      PN_02         address_group(dynamic)  ipv4-input-filter-20    192.168.77.39           180        151
+      LAN           interface_group         ipv4-output-filter-10   bon0
+                                            nat-destination-101     eth2.2001
+      TRUSTEDv6     ipv6_network_group      ipv6-input-filter-10    2001:db8::/64
+      TRUSTEDv4     network_group           ipv4-forward-filter-20  192.0.2.0/30
+                                                                    203.0.113.128/25
+      PORT-SERVERS  port_group              route-PBR-201           443
+                                            route-PBR-201           5000-5010
+                                            nat-destination-101     http
+      vyos@vyos:~$
\ No newline at end of file
diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/ipv4.rst
index b5a087a7..2fe877bb 100644
--- a/docs/configuration/firewall/ipv4.rst
+++ b/docs/configuration/firewall/ipv4.rst
@@ -516,6 +516,27 @@ geoip) to keep database and rules updated.
    criteria.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source group dynamic-address-group <name | !name>
+
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+
+   Use a specific dynamic-address-group. Prepend character ``!`` for inverted
+   matching criteria.
+
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    source group network-group <name | !name>
 .. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
    source group network-group <name | !name>
diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/ipv6.rst
index 6f343323..29cbe097 100644
--- a/docs/configuration/firewall/ipv6.rst
+++ b/docs/configuration/firewall/ipv6.rst
@@ -526,6 +526,27 @@ geoip) to keep database and rules updated.
    criteria.
 
 .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source group dynamic-address-group <name | !name>
+
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+
+   Use a specific dynamic-address-group. Prepend character ``!`` for inverted
+   matching criteria.
+
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
    source group network-group <name | !name>
 .. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
    source group network-group <name | !name>