How to write XML rules for DAXFi

Davide Alberani <alberanid@libero.it>

1. Introduction

DAXFi is a Python package useful to configure and manage several different kinds of firewalls in a consistent way, without the need to worry about firewall-dependent issues. To stay firewall-independent, DAXFi defines a common way to describe firewalls rules: it uses a XML representation.

Fortunately, DAXFi doesn't require you to rewrite all your rules in XML from scratch: if you already have a firewall with your rules running, you can use the daxfidump script to get a set of XML files with your rules. Obviously, it's possible that you want to modify these rules, so keep reading this how-to.

2. XML headers, syntax and terminology

2.1 Prolog and Document Type Declaration

If you want to write a XML rule for DAXFi, in a file or directly in a Python script, you have to begin with the XML prolog:

<?xml version='1.0'?>

It must be at the very begin of the file or string (no white spaces, tabs or newlines are allowed before this line).

Now you can point, optionally, to a DTD with a line like:

<!DOCTYPE ruleset SYSTEM '/etc/daxfid/dtd.d/daxfifw_0.4.dtd'>

where the string after 'SYSTEM' must point to the DTD file and the string after 'DOCTYPE' ('ruleset', in this example) is the name of the main tag.

2.2 Syntax

A XML document looks like a SGML or HTML file: there are normal tags, empty tags and they can have attributes. Some things you must remember to write a valid XML:

• normal tags always have an open tag (like '<tag>') and a close tag (like '</tag>').
• tag, attribute names and values are case sensitive.
• an empty tag doesn't allow other tag inside of it, and its syntax is: <empty-tag />
• tags can be nested, but not overlapped; <tag1>...<tag2>...</tag2>...</tag1> is allowed, while <tag1>...<tag2>...</tag1>...</tag2> is not.
• attribute values must be enclosed in single or double quotes, e.g.: <tag attributeName='attributeValue'>...</tag>
• every document must have a single 'main tag', which encloses any other tag.

2.3 DAXFi specific syntax

In the next sections, DAXFi specific tags and attributes are described; some notes for attribute values:

• values are case sensitive.
• attributes marked as 'boolean' can take 'yes' or 'no' as value.
• almost every attribute value can be negated, prepending a '! ' to the value. E.g.: source-port='! 1024' means every source port except 1024.

3. One or more rules?

Within a XML file or string, you may decide to put one or more rule definition.

If you want to put a single rule, you can begin with an 'action tag' as described in the next chapter; if you want to put more than one rule, you have to use 'ruleset' as the main tag (wrapping many action tags) , as:

<ruleset>
    <action1>
        ...
    </action1>
    <action2>
        ...
    </action2>
    ...
</ruleset>

4. Define a rule

Every rule must be enclosed in what I call an 'action tag'; this is one of the valid actions enumerated below and are used to tell DAXFi what to do with this rule (e.g.: append this rule at the end of a chain, purge a chain, delete a given rule and so on).

Moreover in this tag are included the attributes that belongs to every IP packets (e.g.: the source and destination addresses, the interface name, if we must consider only fragments, etc. etc.)

4.1 Action tags

• append: append this rule to the end of the given chain.
• delete: remove the defined rule (or it can be specified with a 'rule-number' attribute).
• replace: replace a rule pointed to with 'rule-number' attribute with the defined one.
• insert: insert the defined rule in the position specified with the 'rule-number' attribute.
• flush: flush the given chain.
• set-policy: set the policy for the given chain.

Examples of valid action tags are:

<append>...</append>

And:

<insert rule-number='5'>...</insert>

4.2 Action tags attributes

Inside the action tag, you can put attributes that belongs to the IP packets. These attributes are:

• source-ip: the source IP of packets; it can be a host name, a numeric address (dotted notation, hexadecimal, etc.) with or without a net mask.
• destination-ip: the destination address.
• chain: the chain can be one of 'input' (the incoming packets), 'output' (outgoing packets) or 'forward' (packets that only pass through the firewall). The chain attribute is always required (exception: in a NAT rule).
• interface: the interface where the packets are from.
• fragment-only: a boolean (the value must be 'yes' or 'no', or it can be omitted). If 'yes', matches only second and further fragments of fragmented packets; if 'no' the rules is applied only to the first fragment of fragmented packets.
• rule-number: used in the 'delete', 'insert' and 'replace' rules to specify the position of the rule within a chain.

Examples; match entering packets from the 127.0.0.1/8 subnet on interface ppp0:

<append chain='input' source-ip='127.0.0.1/8' interface='ppp0'>
    ...
</append>

Match only the first fragment of fragmented outgoing packets from 127.0.0.1 directed to 4.5.6.0/24:

<append chain='output' source-ip='127.0.0.1' destination-ip='4.5.6.0/24' fragment-only='yes'>
    ...
</append>

5. Protocol

Inside an action tag, you can put an empty tag with the name of one of the main protocols (TCP, UDP and ICMP) or a 'protocol' tag with a 'protocol' attribute. E.g., for matching only tcp packets:

<tcp />

For udp:

<udp />

And for icmp:

<icmp />

If you want to match against a different protocol:

<protocol protocol='igmp' />

5.1 Protocol tags attributes

• source-port: only for tcp and udp, specify the source port. Can be a numeric value, or a string as defined in /etc/services. Port ranges can be defined with the notation m:n (e.g.: 6000:6010).
• destination-port: only for tcp and udp, guess what...
• syn-only: only for tcp, it's a boolean. If set, only matches packets with the TCP flag SYN set and ACK and FIN flags not set. If 'no' matches only the TCP packets that are not the very first step of a connection.
• tcp-flags: only for tcp, a list of comma separated tcp flags that must be set and an optional slash separated mask of flags. E.g.: tcp-flags='syn/syn,rst,ack' is equivalent to the 'syn-only' attribute. Valid flags are: 'fin', 'syn', 'rst', 'push', 'ack', 'urg', 'ecn', 'cwr'.
• icmp-type: only for icmp, specify the ICMP type and (optionally) the ICMP code to match. The type can be one string - see the _rulesutils.py file for allowed values) or a numeric code; if a code is needed, you must split type and code with a slash.
• protocol: used only in the 'protocol' tag, can be a number or a name defined in /etc/protocols.

Examples; match TCP packets from the 1234 port:

<tcp source-port='1234' />

Match UDP to the identd daemon:

<udp destination-port='auth' />

Match the first packets of a connection to any UDP except the range 100-200:

<udp syn-only='yes' destination-port='! 100:200' />

Match 'host-redirect' ICMP packets:

<icmp icmp-type='host-redirect' />

The same, using ICMP type/code:

<icmp icmp-type='5/1' />

6. Target

Now you want to tell DAXFi what to do with the matched packets. You can use an empty tag named 'accept', 'reject' or 'drop', or you can use a 'target' tag with a 'target' attribute. The target tag must be omitted writing a NAT rule.

Examples; accept the patched packets (the packets will pass through the firewall):

<accept />

Drop packets (they will be silently discarded):

<drop />

Reject packets (packets will be dropped, and an ICMP error code sent back):

<reject />

It's equivalent to:

<target target='reject' />

6.1 Target tags attributes

• target: only valid inside a 'target' tag, specify what to do with matched packets.
• reject-with: only for reject, what kind of ICMP to return. It can be an ICMP name, an ICMP type or an ICMP 'type/code' couple.

Example; reject packets sending back a 'network-prohibited' ICMP:

<reject reject-with='network-prohibited' />

7. NAT

With this empty tag, you set up a rule to do Network Address Translation.

Sometimes you need to mangle the source or destination of a packet; we define, with empty tags, four operation: with 'snat' you alter the source address of matched packets; you have to specify the new source IP address and optionally a port or range of ports. The 'dnat' tag is used when you need to redirect a packet directed to a given IP address to another one; you have to specify the new destination address and, optionally, a new port or range of ports. 'masq' is a special case of 'snat', useful with dial-up: you don't have to specify the new source IP since the one of the outgoing interface is used; optionally you can specify a port or range of ports. 'redirect' is a special case of 'dnat': the matched packets are sent to the local machine (IP 12.7.0.0.1); optionally it's possible to specify a new destination port. The generic 'nat' tag can also be used, and requires a 'nat' attribute to specify the type of NAT you need.

7.1 NAT tag attributes

• nat: only for 'nat' tag; the value must be one in 'snat', 'dnat', 'masq', 'redirect'.
• to-address: the IP address (or range of addresses) used as new destination or source.
• to-port: the new destination port or range of ports.

Examples; TCP packets from 1.2.3.4 are NATed as they are coming from 5.6.7.8 on interface 'le1' with a new port, in the range 1-1024:

<append source-ip='1.2.3.4' interface='le1'>
    <tcp />
    <snat to-address='5.6.7.8' to-port='1:1024' />
</append>

Packets directed to IP address 7.7.7.7 are redirected to one IP in the range from 1.1.1.1 to 3.3.3.3:

<append destination-ip'7.7.7.7'>
    <dnat to-address='1.1.1.1:3.3.3.3' />
</append>

TCP packets from 1.2.3.0/24 tcp port 80 are redirected to the local port 8080:

<append source-ip='1.2.3.0/24'>
    <tcp source-port='80' />
    <redirect to-port='8080' />
</append>

Packets from 192.168.1.0/24 will be rewritten as they are coming from the address of the 'ppp0' interface:

<append source-ip='192.16.1.0/24' interface='ppp0'>
    <masq />
</append>

8. Log

Sometimes you need to leave a message in the system logs when a given packets is received.

A 'log' empty tag can be used.

8.1 Log tag attributes

• log-priority: the priority to use; one of 'debug', 'info', 'notice', 'warning', 'err', 'crit', 'alert', 'emerg'.
• log-facility: the priority of the log messages; can be 'auth', 'authpriv', 'cron', 'daemon', 'kern', 'lpr', 'mail', 'news', 'syslog', 'user', 'uucp', 'ftp' or a level from 'local1' to 'local7'.

Examples; log with priority 'info' and with facility 'local1':

<log log-facility='local1' log-priority='info' />

9. State

With this empty tag you can specify a rule with connection tracking.

9.1 State tag attributes

• state: the state to consider; must be 'related' (any packets associated with an existing connection) or 'new' (the packet has started a new connection).

Example:

<state state='related' />

10. Limit

Actually, this empty tag is supported only by the iptables firewall and it's safely ignored by others. It set limits for matched packets.

10.1 Limit tag attributes

• rate: maximum average matching rate (can be a number with an optional time unit, like '/s', '/m', '/h', '/d').
• burst: maximum initial number of packets to match.

Example; match three packets in an hour, with a burst of 10:

<limit rate='3/h' burst='10' />

11. Processing instruction

Sometimes you need to give special instructions to the XML parser. You can add a processing instruction right below the XML prolog, with the syntax:

<?daxfi-process attributeName='attributeValue'?>

Valid attributes are:

• only-for: a comma separated list of firewalls that can use this rule or list of rules.
• not-for: a comma separated list of firewall names that ignores these rules.

Example; a set of rules to be executed only if the firewall is not iptables or ipfilter:

<?xml version='1.0'?>
<?daxfi-process not-for='iptables,ipfilter'?>
<ruleset>
    ...
</ruleset>

12. Parameter substitution

If you're using a dial-up connection normally you don't know what IP address will be assigned to you by the provider and the name of the network interface used by the pppd daemon. Using a DAXFi-based program you can leave in your XML files some placeholders and tell the program to substitute these strings with other data.

The Firewall class in the daxfi Python package takes as constructor parameter the 'substitutionDict' keyword, that must be a Python dictionary in the form {'placeHolder1': 'value1', 'placeHolder2': 'value2', ...}. Before any operation on XML files or strings, the Firewall object will replace the strings 'placeHolder1', 'placeHolder2' and so on with 'value1', 'value2', etc.

As example, the daxfid script will search for '%REMOTE_IP', '%LOCAL_IP' and '%INTERFACE', replacing these strings with the remote IP, the local assigned IP and the interface of the connection.

13. Examples

<?xml version='1.0'?>

<append source-ip='192.196.1.0/24' chain='input'>
  <tcp destination-port='80' />
  <accept />
</append>

14. Copyright

Copyright 2001, 2002 Davide Alberani <alberanid@libero.it>