From 734c3d98f30f83ee50698cd3d5c69cb6006a8588 Mon Sep 17 00:00:00 2001 From: Nicolas Fort Date: Thu, 9 May 2024 15:27:20 -0300 Subject: Firewall: add documentation for dynamic firewall groups. (cherry picked from commit 245e133042b160ca9f28b4be13d2b5c8e0edba70) --- docs/configuration/firewall/groups.rst | 281 +++++++++++++++++++++++++++++---- docs/configuration/firewall/ipv4.rst | 21 +++ docs/configuration/firewall/ipv6.rst | 21 +++ 3 files changed, 292 insertions(+), 31 deletions(-) (limited to 'docs') 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 address [address | +.. cfgcmd:: set firewall group address-group address [address | address range] -.. cfgcmd:: set firewall group ipv6-address-group address
+.. cfgcmd:: set firewall group ipv6-address-group 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 description -.. cfgcmd:: set firewall group ipv6-address-group description +.. cfgcmd:: set firewall group address-group description +.. cfgcmd:: set firewall group ipv6-address-group description 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 network -.. cfgcmd:: set firewall group ipv6-network-group network +.. cfgcmd:: set firewall group network-group network +.. cfgcmd:: set firewall group ipv6-network-group network 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 description -.. cfgcmd:: set firewall group ipv6-network-group description +.. cfgcmd:: set firewall group network-group description +.. cfgcmd:: set firewall group ipv6-network-group description 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 interface +.. cfgcmd:: set firewall group interface-group interface 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 description +.. cfgcmd:: set firewall group interface-group description 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 mac-address +.. cfgcmd:: set firewall group mac-group 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 address +.. cfgcmd:: set firewall group domain-group address 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 +.. cfgcmd:: set firewall group dynamic-group ipv6-address-group + +Add description to firewall groups: + +.. cfgcmd:: set firewall group dynamic-group address-group + description +.. cfgcmd:: set firewall group dynamic-group ipv6-address-group + description + +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 +.. cfgcmd:: set firewall ipv4 name rule <1-999999> add-address-to-group + destination-address address-group +.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule + <1-999999> add-address-to-group destination-address address-group +.. cfgcmd:: set firewall ipv6 name rule <1-999999> add-address-to-group + destination-address address-group + +* 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 +.. cfgcmd:: set firewall ipv4 name rule <1-999999> add-address-to-group + source-address address-group +.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule + <1-999999> add-address-to-group source-address address-group +.. cfgcmd:: set firewall ipv6 name rule <1-999999> add-address-to-group + source-address address-group + +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 +.. cfgcmd:: set firewall ipv4 name rule <1-999999> add-address-to-group + [destination-address | source-address] timeout +.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule + <1-999999> add-address-to-group [destination-address | source-address] + timeout +.. cfgcmd:: set firewall ipv6 name rule <1-999999> add-address-to-group + [destination-address | source-address] 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: + s Timeout value in seconds + m Timeout value in minutes + h Timeout value in hours + 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 - 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 840c522e..7b80dc67 100644 --- a/docs/configuration/firewall/ipv4.rst +++ b/docs/configuration/firewall/ipv4.rst @@ -515,6 +515,27 @@ geoip) to keep database and rules updated. Use a specific address-group. Prepend character ``!`` for inverted matching criteria. +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group dynamic-address-group +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group dynamic-address-group +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group dynamic-address-group +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source group dynamic-address-group + +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group dynamic-address-group +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group dynamic-address-group +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group dynamic-address-group +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + destination group dynamic-address-group + + 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 .. cfgcmd:: set firewall ipv4 input filter rule <1-999999> diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/ipv6.rst index c679ffd5..b0249124 100644 --- a/docs/configuration/firewall/ipv6.rst +++ b/docs/configuration/firewall/ipv6.rst @@ -525,6 +525,27 @@ geoip) to keep database and rules updated. Use a specific address-group. Prepend character ``!`` for inverted matching criteria. +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group dynamic-address-group +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group dynamic-address-group +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group dynamic-address-group +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source group dynamic-address-group + +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group dynamic-address-group +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group dynamic-address-group +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group dynamic-address-group +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + destination group dynamic-address-group + + 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 .. cfgcmd:: set firewall ipv6 input filter rule <1-999999> -- cgit v1.2.3