vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1434 from nicolas-fort/fwall_dyn_groups

Browse Source 
Firewall: add documentation for dynamic firewall groups.
This commit is contained in:
Daniil Baturin 2024-05-10 11:55:52 +02:00 committed by GitHub
commit 5950dac4b5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 292 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

281
docs/configuration/firewall/groups.rst
View File

@ -21,9 +21,9 @@ Address Groups
In an **address group** a single IP address or IP address ranges are In an **address group** a single IP address or IP address ranges are
defined. defined.
.. cfgcmd:: set firewall group address-group <name> address [address | .. cfgcmd:: set firewall group address-group <name> address [address |
address range] 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 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 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 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 address-group <name> description <text>
.. cfgcmd:: set firewall group ipv6-address-group <name> description <text> .. cfgcmd:: set firewall group ipv6-address-group <name> description <text>
Provide a IPv4 or 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 to add a mix of addresses and networks, the network group is
recommended. recommended.
.. cfgcmd:: set firewall group network-group <name> network <CIDR> .. cfgcmd:: set firewall group network-group <name> network <CIDR>
.. cfgcmd:: set firewall group ipv6-network-group <name> network <CIDR> .. cfgcmd:: set firewall group ipv6-network-group <name> network <CIDR>
Define a IPv4 or IPv6 Network group. 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 network-group NET-INSIDE-v4 network 192.168.1.0/24
set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 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 network-group <name> description <text>
.. cfgcmd:: set firewall group ipv6-network-group <name> description <text> .. cfgcmd:: set firewall group ipv6-network-group <name> description <text>
Provide an IPv4 or 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. 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. 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 bond1001
set firewall group interface-group LAN interface eth3* 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 Provide an interface group description
@ -110,7 +110,7 @@ MAC Groups
A **mac group** represents a collection of mac addresses. 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. Define a mac group.
@ -128,7 +128,7 @@ Domain Groups
A **domain group** represents a collection of domains. 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. Define a domain group.
@ -140,10 +140,108 @@ A **domain group** represents a collection of domains.
Provide a domain group description. 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 Examples
******** ********
General example
===============
As said before, once firewall groups are created, they can be referenced As said before, once firewall groups are created, they can be referenced
either in firewall, nat, nat66 and/or policy-route rules. 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 .. code-block:: none
set firewall ipv4 input filter rule 10 action accept set firewall ipv4 output filter rule 10 action accept
set firewall ipv4 input filter rule 10 inbound-interface group !LAN 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 action accept
set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4 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 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 inbound-interface group LAN
set nat destination rule 101 destination group address-group SERVERS set nat destination rule 101 destination group address-group SERVERS
set nat destination rule 101 protocol tcp 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 protocol tcp
set policy route PBR rule 201 set table 15 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 Operation-mode
************** **************
.. opcmd:: show firewall group
.. opcmd:: show firewall group <name> .. opcmd:: show firewall group <name>
Overview of defined groups. You see the type, the members, and where the Overview of defined groups. You see the firewall group name, type,
group is used. 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 .. code-block:: none
vyos@ZBF-15-CLean:~$ show firewall group vyos@vyos:~$ show firewall group
Firewall Groups Firewall Groups
Name Type References Members Name Type References Members Timeout Expires
------------ ------------------ ---------------------- ---------------- ------------ ---------------------- ---------------------- ---------------- --------- ---------
SERVERS address_group nat-destination-101 198.51.100.101 SERVERS address_group nat-destination-101 198.51.100.101
198.51.100.102 198.51.100.102
LAN interface_group ipv4-input-filter-10 bon0 ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.77.39 7200 7174
nat-destination-101 eth2.2001 PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.0.245 120 112
TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64 192.168.77.39 120 85
TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30 PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.77.39 180 151
203.0.113.128/25 LAN interface_group ipv4-output-filter-10 bon0
PORT-SERVERS port_group route-PBR-201 443 nat-destination-101 eth2.2001
nat-destination-101 5000-5010 TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64
http TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30
vyos@ZBF-15-CLean:~$ 203.0.113.128/25
PORT-SERVERS port_group route-PBR-201 443
route-PBR-201 5000-5010
nat-destination-101 http
vyos@vyos:~$

21
docs/configuration/firewall/ipv4.rst
View File

@ -538,6 +538,27 @@ geoip) to keep database and rules updated.
Use a specific address-group. Prepend character ``!`` for inverted matching Use a specific address-group. Prepend character ``!`` for inverted matching
criteria. 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> .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
source group network-group <name | !name> source group network-group <name | !name>
.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> .. cfgcmd:: set firewall ipv4 input filter rule <1-999999>

21
docs/configuration/firewall/ipv6.rst
View File

@ -525,6 +525,27 @@ geoip) to keep database and rules updated.
Use a specific address-group. Prepend character ``!`` for inverted matching Use a specific address-group. Prepend character ``!`` for inverted matching
criteria. 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> .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
source group network-group <name | !name> source group network-group <name | !name>
.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> .. cfgcmd:: set firewall ipv6 input filter rule <1-999999>