Firewall 2.0

IN PROGRESS

The VNS3 Firewall 2.0 was built from a decade of networking knowledge and aims to simplify your network policy and routing.

Definitions

Term                            Definition
RuleFirewall rules are rules for handling VNS3 traffic. Rules always exist in a Table. They determine what happens to which traffic. e.g. reject all traffic not from the overlay network.
Root VNS3 policyThe root VNS3 policy is the set of enabled firewall rules.
TableRules are placed in tables and determine when the rule recieves traffic. The standard system tables are PREROUTING, INPUT, FORWARD, OUTPUT and POSTROUTING. See below for more on tables.
Rule ConditionA rule condition is how traffic matches rules. For instance, a rule condition of source=0.0.0.0/0 means match traffic from any IP address. More on conditions below.
Rule ActionA rule action is what to do with the traffic that matches the rule conditions. The most common actions are ACCEPT, REJECT, DROP and LOG. More on actions below.
PacketA network packet is the information atom of networks. Network traffic is a stream of packets.

Tables and Traffic Order

VNS3 has 5 system tables: PREROUTING, INPUT, FORWARD, OUTPUT and POSTROUTING. Traffic will move from table to table and through VNS3 matching against rules based on rule conditions and taking the defined rule action. A rule’s table and position determine when it will be matched against traffic.

VNS3 Traffic flow Diagram

There are three traffic paths: VNS3 Routing traffic, VNS3 terminating traffic and VNS3 originating traffic. These are defined as follows:

VNS3 Routing Traffic: This is traffic that originates outside of VNS3 and whose destination is outside VNS3. The table path is as follows:

  1. PREROUTING
  2. FORWARD
  3. POSTROUTING

VNS3 Terminating Traffic: This is traffic that originates outside of VNS3 and whose destination is VNS3. The table path is as follows:

  1. PREROUTING
  2. INPUT

VNS3 Originating Traffic: This is traffic that originates in VNS3 and whose destination is outside VNS3. The table path is as follows:

  1. OUTPUT
  2. POSTROUTING

Rules

Rules comprise your VNS3 network policy. These rules determine which traffic goes where. Each rule has a table and position. A rule’s table and position determine when it will be matched against traffic. Rules are 0 indexed and ordered from least to greatest. This means the rule at position 0 will be matched first, then 1, then 2 etc. Rules can also be assigned to 1 or more groups or have comments for added explanation. Each rule is provided a unique id for targeting. Finally, rules can be in a state of either enabled or disabled.

Rule data resource:

  • The original text of the rule (rule in the API)
  • The resolved text of the rule and what is in use by the OS (rule_resolved in the API)
  • An optional comment
  • An optional list of groups the rule is in
  • The table the rule is in
  • The rule’s position in the root policy
  • A unique id for the rule

Note You might be wondering why there is both a rule and a resolved rule. This is because the rule text is a simplified version of the rule and may be expanded for the OS or it may have variables defined in it that are resolved when the rule is created.

VNS3 rules list

Adding a Rule

The VNS3 Console provides a easy way for constructing policy rules. From the Rules page, click Add Rule:

VNS3 new rule

A rule is defined by 4 components:

  1. A table in which the rule will be placed
  2. A set of conditions (which can be empty) to match traffic with
  3. An action such as ACCEPT or REJECT
  4. A position where the default (-1) indicates the the end of the root policy

From the new rule form you can search a few things about the system to more easily construct rules:

  1. Variables - these are system variables and any user defined custom variables. They can be placed in rules which will be resolved at insertion time.
  2. FWSets - these are the current VNS3 FWSets. They can be placed in conditions and are typically used as either a Source or Destination condition.
  3. Subtables - these are the current VNS3 subtables that can be “jumped” to from rules in the rule action. e.g. -j ${subtable_MyGroup}

The form also provides some helpful hints on the right such as current interfaces or possible actions depending on the condition type or table.

Rule conditions

Rule conditions are how traffic is matched to rules. Here are some common conditions:

  • Source (-s): This will match the source of the traffic. e.g. -s 10.0.0.0/24. You can also use fwset variables here for match entire fwset ranges. e.g. -s #{fwset_mynamedfwset}
  • Destination (-d): This will match the destination of the traffic. e.g. -d 10.0.0.0/24. You can also use fwset variables here for match entire fwset ranges. e.g. -d #{fwset_mynamedfwset}
  • Source port (–sport): This will match the source port of the traffic. e.g. --sport 4000
  • Destination port (–dport): This will match the destination port of the traffic. e.g. --sport 443
  • Incoming interface (-i): This will match traffic coming in on a certain interface. e.g. -i eth0
  • Outgoing interface (-o): This will match traffic leaving on a certain interface. e.g. -o tun0
  • Protocol (-p): This will match traffic of the provided protocol. e.g. -p udp

More to come

Rule actions

Rule actions define what to do with the traffic that matches the rule. Common actions are:

  • ACCEPT: accept traffic. This will allow traffic to continue through firewall tables or potentially leave VNS3
  • REJECT: reject traffic. This will prevent traffic, send a rejection response to the sender.
  • DROP: drop traffic. This will silently drop traffic packets. This differents from reject as it does not inform the sender that their packets are being dropped.
  • LOG: This will pass through traffic and log it to the server at /var/log/kern.log
  • DNAT: This is only valid in prerouting table. This routes your traffic to a new destination. Specifically, this is changing the destination of the traffic.
  • SNAT: This is only valid in postrouting table. This routes return traffic to a new destination. Specifically, this is changing the source of the traffic.
  • COPY: Copy traffic to a This requires --to and --from arguments after the copy action: -j COPY --to 10.0.1.239 --from eth0

Import / Export

To import or export firewall root policy rules from the VNS3 Console, first click Advanced to expand the advanced options. Then click the Import/Export button.

Importing Rules

There are two methods for importing rules, by file import or text input. The file import supports both the json and text file type from the export.

Notes on import/export text file type parsing

This file type is similar to the old firewall input UI. This new input maps some file syntax into the rule data model:

  1. The line number determines the position in the firewall.
  2. Rules preceded by # are imported as disabled. A # line is determined to be a rule if it begins with one of the valid table names.
  3. Lines preceded by # that are not rules are comments and will apply to the next valid rule in the list. Multiple lines of comments will be added to the next rule in the list.
  4. If a comment contains the text groups=mygroupname,othergroup then the rule this comment applies to will be added to those groups

VNS3 Import modal UI

Exporting Rules

Rules can be exported as either JSON or Text. Note that exporting rules as a text file may lose some information about the rule. JSON file type is the preferred method.

VNS3 Export modal UI

API

The API provides the following endpoints for interacting with rules:

Rules collection: /api/v2/firewall/rules

Supported methods

  • GET for reading all rules
  • POST for inserting a rule
  • PUT for bulk overwrite of entire policy (careful!)

Rule resource: /api/v2/firewall/rules/:ruleid

Supported methods

  • PUT for updating the state of the rule (enabled/disabled, comment or groups). You cannot edit the rule once created, you must delete and insert.
  • DELETE for deleting rules

Rule resource: /api/v2/firewall/rules/export

Supported methods

  • GET for downloading a JSON file or a text file that can be imported to another VNS3 controller

Rule resource: /api/v2/firewall/rules/import

Supported methods

  • PUT for uploading a raw string of rules starting at a certain position

GET /api/v2/firewall/rules

{
    "response": [
        {
            "id": "87319bd7cf225e4",
            "rule": "PREROUTING -s 4.5.4.5/32 -j DNAT --to 3.3.3.3",
            "table": "prerouting",
            "rule_resolved": "PREROUTING -s 4.5.4.5/32 -j DNAT --to 3.3.3.3",
            "position": 0,
            "comment": "For routing traffic",
            "last_resolved": "2021-11-30T21:51:14.606Z",
            "disabled": false,
            "created_at": "2021-11-30T20:03:25.880Z",
            "groups": []
        },
        {
            "id": "622a549079e3279",
            "rule": "FORWARD_CUST -j ACCEPT",
            "table": "forward",
            "rule_resolved": "FORWARD_CUST -j ACCEPT",
            "position": 0,
            "comment": "heres a nice comment",
            "last_resolved": "2021-11-30T21:51:14.606Z",
            "disabled": false,
            "created_at": "2021-11-30T20:03:25.899Z",
            "groups": [
                "Bens test group"
            ]
        }
    ]
}

Sets

Firewall sets or FWSets are sets of objects such as IPs or ports that can be used for matching traffic to rules. These allow for faster traffic matching for your rules and provide an easy and efficient way to group people, machines or services. FWsets are unique by the name and cannot have spaces. You can also use variables in your FWSet entries.

FWSet data resource:

  • name - this is unique (case insensitive)
  • description (optional)
  • a list of entries
    • entry
    • comment (optional)

VNS3 FWset View Page

Using in a rule

To use in a rule as either a source or destination, you may use it as a variable or as the fwset name directly:

Matching a set against source of traffic

INPUT -s ${fwset_myfwset} -j ACCEPT or INPUT -s name_of_fwset -j ACCEPT

Matching a set against destination of traffic

INPUT -d ${fwset_myfwset} -j ACCEPT or INPUT -d name_of_fwset -j ACCEPT

API

The API provides the following endpoints for interacting with fwsets:

FWsets collection: /api/v2/firewall/fwsets

Supported methods

  • GET for reading all fwsets
  • POST for creating new fwset

FWset resource: /api/v2/firewall/fwsets/:name

Supported methods

  • GET for reading fwset data and entries
  • PUT for overwrite all entries or updating description (cannot edit name after creation)
  • DELETE to delete entire fwset

FWset entries subcollection: /api/v2/firewall/fwsets/:name/entries

Supported methods

  • POST for inserting
  • DELETE to delete fwset entry. Expects JSON body: Payload: {"entry": "54.43.12.1"}

GET /api/v2/firewall/fwsets

{
    "response": [
        {
            "name": "App-Ports",
            "description": "",
            "created_at": "2021-11-30T20:03:25.845Z",
            "updated_at": "2021-11-30T20:03:25.845Z",
            "entries": [
                "6001",
                "7001"
            ],
            "size": 2,
            "type": "port"
        },
        {
            "name": "IP-Blacklist",
            "description": "A blacklist of known nefarious IPs",
            "created_at": "2021-12-01T22:35:47.103Z",
            "updated_at": "2021-12-01T22:35:47.103Z",
            "entries": [
                "174.120.121.4",
                "11.212.34.11",
                "54.43.12.1"
            ],
            "size": 3,
            "type": "net"
        }
    ]
}

Subtables

Subtables are custom tables of rules that can be directed to from rules in the VNS3 Root Policy. These are a more advanced feature of the VNS3 firewall. They are use when the Root VNS3 policy has lots of rules. Subtables can be used to improve the performance and organization of the root policy. That is the root policy can be reduced to fewer rules that route traffic to the subtable based on certain matching conditions. This improves performance by reducing the number of rules that are tried for matches against each packet.

Subtable data resource:

  • name - this is unique (case insensitive)
  • type this corresponds to a valid system table (prerouting, input, forward, output or postrouting) and determines the type of rules that can route traffic to this subtable.
  • description (optional)
  • a list of rules these have the same data as root rules except they cannot be associated with groups
    • rule (can include variables)
    • rule_resolved
    • disabled (true or false)
    • comment
    • position

VNS3 Subtables View Page

Using in a rule

To direct traffic to your subtable you will “jump” to it from a rule in the VNS3 Root policy. That is, you will specify the name of the subtable in the action of the rule: PREROUTING -s 10.100.0.0/32 -j MYGROUP

Note The type of your subtable must correspond to table you are jumping from. For instance, in the above example, MYGROUP should be of the type prerouting.

API

The API provides the following endpoints for interacting with subtables:

Subtables collection: /api/v2/firewall/subtables

Supported methods

  • GET for reading all subtables
  • POST for creating new subtable

Subtable resource: /api/v2/firewall/subtables/:name

Supported methods

  • GET for reading subtable data and rules
  • PUT for overwrite all rules or updating description (cannot edit name or type after creation)
  • DELETE to delete entire subtable

Subtables rules subcollection: /api/v2/firewall/subtables/:name/rules

Supported methods

  • POST for inserting new rule

Delete Subtables rule: /api/v2/firewall/subtables/:name/rules/:id

Supported methods

  • DELETE to delete rule by id

GET /api/v2/firewall/subtables

{
    "response": [
        {
            "name": "MySubtable",
            "description": "Heres my description",
            "created_at": "2021-11-30T20:03:25.820Z",
            "updated_at": "2021-11-30T20:03:25.820Z",
            "rules": [
                {
                    "rule": "MySubtable -s 1.1.1.1 -d 2.2.2.2 -j DNAT --to 8.8.8.8",
                    "position": 0,
                    "comment": "",
                    "rule_resolved": "MySubtable -s 1.1.1.1 -d 2.2.2.2 -j DNAT --to 8.8.8.8",
                    "disabled": false,
                    "id": "ad3f114aa0bea55"
                }
            ],
            "type": "prerouting",
            "size": 1
        }
    ]
}

VNS3 Variables

The new firewall has added a concept of variables to VNS3. These can now be used in firewall rules, fwset entries and subtable rules for more easily building your policies. VNS3 provides system variables that are defined as a function of the state of the VNS3 server. You can also define custom variables for use in the firewall.

VNS3 Variables View

Defining a custom variable

  1. Click on the Variables button from any of the Firewall pages
  2. To the top of the popup is a form New Custom Variable
  3. Enter your variable name and variable value and click Save

A Note on variable naming conventions

Variables have specific, predictable names. The GET response is grouped by “collection”. The variable collections are:

  • controller: VNS3 config and global state variables
  • plugin_instances: IP addresses of your running plugin instances
  • peering: peer names (dns or IP)
  • clientpacks: Clientpack IPs
  • clientpack_groups: These are groups of clientpack IPs defined by key, value tag pairs. e.g. all clientpacks with tag type=person
  • fwsets: Names of fwsets
  • subtables: Names of subtables
  • custom: User defined variables

Using in a rule

Variables in rules should be used referenced as ${variable_name}. These will be expanded when the rule is enabled.

Some examples:

INPUT_CUST -d ${vns3_overlay_subnet} -j ACCEPT
PREROUTING -s ${fwset_blacklist} -j DROP

API

The API provides the following endpoints for interacting with variables:

Subtables collection: /api/system/variables

Supported methods

  • GET for reading all variables. Example response provided below.
  • POST for creating new variable. Payload is {"name": "myhouse", "value": "64.12.53.12", "description": "IPaddress for my house"}
  • DELETE for deleting a variable by name. Payload is {"name": "myhouse"}

GET /api/system/variables

{
    "response": {
        "controller": [
            {
                "variable": "vns3_primary_private_ip",
                "value": "10.0.1.224"
            },
            {
                "variable": "vns3_overlay_subnet",
                "value": "203.0.113.0/27",
                "description": "Subnet used for clientpack and peer IP's"
            },
            {
                "variable": "vns3_plugin_network",
                "value": "198.51.100.0/28",
                "description": "Plugin network subnet"
            },
            {
                "variable": "vns3_public_ip",
                "value": "54.174.246.212"
            },
            {
                "variable": "vns3_subnet_gateway",
                "value": "10.0.1.193",
                "description": "Local subnet gateway for vlan"
            }
        ],
        "plugin_instances": [],
        "peering": [
            {
                "variable": "peer_1_overlay_ip",
                "value": "203.0.113.1"
            },
            {
                "variable": "peer_2_overlay_ip",
                "value": "203.0.113.2"
            }
        ],
        "ipsec": [
            {
                "variable": "ipsec_local_ip",
                "value": "192.0.2.254",
                "description": "IP used for Ipsec endpoint termination (on eth0)"
            },
            {
                "variable": "ipsec_endpoint_3_ip",
                "value": "198.2.5.2",
                "description": "Ipsec endpoint [name=myendpoint] IP address"
            },
            {
                "variable": "ipsec_endpoint_3_tunnel_17_local_subnet",
                "value": "159.172.197.0/24"
            },
            {
                "variable": "ipsec_endpoint_3_tunnel_17_remote_subnet",
                "value": "10.0.0.0/8"
            }
        ],
        "clientpacks": [
            {
                "variable": "clientpack_203_0_113_10_ip",
                "value": "203.0.113.10",
                "description": "IP for clientpack 203_0_113_10"
            },
            {
                "variable": "clientpack_203_0_113_11_ip",
                "value": "203.0.113.11",
                "description": "IP for clientpack 203_0_113_11"
            }
        ],
        "groups": [],
        "fwsets": [
            {
                "variable": "fwset_bensports",
                "value": "BensPorts",
                "description": "FWset PORTS_ben ipset name"
            },
            {
                "variable": "fwset_ipblacklist",
                "value": "IPBlacklist",
                "description": "FWset IPBlacklist ipset name"
            }
        ],
        "subtables": [
            {
                "variable": "subtable_mygroup",
                "value": "MyGroup",
                "description": "Subtable MyGroup name"
            },
            {
                "variable": "subtable_mygroup",
                "value": "MyGroup",
                "description": "Subtable MyGroup name"
            }
        ],
        "custom": [
            {
                "variable": "custom_myhouse",
                "value": "64.34.12.10",
                "description": ""
            }
        ]
    }
}

Upgrading to new Firewall

You can import a snapshot into a VNS3 Firewallv2 version (starting with X.Y.Z) and it will map your rules, fwsets and subtables (previously called subgroups) into the new data model. The previous version of the firewall was treated as a single file which could have comments (lines starting with #). Some things to note:

  • Commented out rules such as # FORWARD_CUST -s 10.0.0.0/64 -j DROP will be created as disabled rules
  • Comments that are not rules will be created as comments for the next valid rule line in your firewall file
  • Consecutive non-rule comments will be concatenated and created as a comment for the next valid rule line in your firewall file
  • Important You can view the old state of your firewall data by going to https://[vns3 host]:8000/firewall/old

Viewing old firewall files

The previous versions of the firewall stored firewall rules, fwsets and subtables (previously subgroups) were edited as “flat files” and can be reviewed as such by going to https://your-vns3-controller:8000/firewall/old.