metawall.pl - Generate firewall rules using a metalanguage
metawall.pl [-hnpvx] [-b backend] [-c chain] rulefile
Metawall is a tool that generates low-level packet filtering rules using a
higher-level language that allows you to define your own protocols and netblock
macros. A unique feature of metawall is its support for multiple backend
targets, allowing you to generate stateful or stateless firewalls on different
packet filtering platforms using the same source files.
This release of metawall supports two backends. The 'iptct' backend is the
default and generates stateful rules for iptables using the connection tracking
module. The other option is 'ipt', which generates stateless iptables rules
that do not require the connection tracking module. There will hopefully be
more backend support in the future, with IP Filter being the next likely
candidate.
WARNING: This release of metawall is considered alpha quality, both because
it has received only limited testing, and because the command language is still
subject to change in future releases. Metawall is intended for use by someone
who understands IP security; it is not a magic bullet that will secure your
network. Metawall is provided as is without warranty of any kind, either
expressed or implied. To paraphrase a well-known virus parody, ``Metawall may
recalibrate your refrigerator's coolness setting so all your ice cream goes
melty, demagnetize the strips on all your credit cards, screw up the tracking
on your television and use subspace field harmonics to scratch any CD's you try
to play.''
Metawall was developed under Perl 5.6.1, though it may run on earlier versions.
It requires the NetAddr::IP module (available on CPAN).
- -b backend
-
This option allows you to select the backend target for rule generation.
Currently the valid selections are ipt or iptct. The default is iptct.
See the BACKENDS section for more details.
- -c chain
-
Set the name used for the main rule chain. The default name is
metawall.
This can be used to install rulesets directly into the FORWARD, INPUT, or
OUTPUT chains if desired, or simply to control where the rules go. This
can be helpful during ruleset testing or in startup scripts.
- -h
-
Display the help text.
- -n
-
Display the definitions of the builtin network macros. Currently the
only builtin netblock is RFC1918.
- -p
-
Display the definitions of the builtin protocols. Some common application
level protocols are predefined in the metawall script (e.g. http). These
definitions can be overridden by the protocol statement, though doing so will
generate a runtime warning.
- -v
-
Display the metawall version number.
- -x
-
Execute the iptables commands produced by metawall. The default is to just
print the commands.
Metawall supports different backend packet filtering systems. Backends are
selected with the -b command line option. Details on each backend are below.
- iptct
-
The iptct backend generates iptables rules that require the connection tracking
module. Connection tracking performs stateful monitoring of IP flows and can
dynamically allow reply packets for existing connections. When using this
backend, a rule will automatically be generated at the beginning of the main
chain which permits all reply traffic to existing connections.
- ipt
-
The ipt backend generates stateless iptables rules which do not require the
connection tracking module. In stateless mode, metawall generates a pair of
rules for each permit/accept command, one of which allows the reply traffic for
the rule. This behavior can be suppressed by using the
oneway option in a
rule. There are some exceptions to this; ICMP rules don't generate reply rules
unless they are one of the ``request'' ICMP types. TCP rules that specify flags
do not generate reply rules either.
The primary input to metawall is a rule file written in metawall's own
language. Lines are processed individually with one rule per line. Blank
lines and lines beginning with the hash mark (#) are ignored. Each line begins
with a command which is followed by some number of parameters, depending on the
specific command being used. The best way to learn to use these commands is
probably by looking at the EXAMPLES section. Valid commands are listed below.
- chain name
-
A chain is simply a list of packet filtering rules that are executed
sequentially. Metawall supports the iptables feature of multiple chains. The
chain command selects the current chain and creates a new chain if necessary.
All rules generated after the chain command become part of that chain. The
jump command can be used to create a rule that transfers control to a different
chain. The default chain is named metawall.
- define name netblock-list
-
The define command is one of the most powerful and useful features of metawall.
It allows you to define a symbolic name that will then represent an arbitrary
list of network blocks when used in rules. In addition, if the list of network
blocks can be merged into larger equivalent blocks, this will be done, courtesy
of the NetAddr::IP compact function. The name must consist only of
alphanumeric, dash and underscore characters, beginning with an alpha. The
netblock list is a comma separated list of hostnames or IP addresses with
optional netmasks. Netmasks are separated from the network address by a slash
and may be in either CIDR bit form (e.g. /24) or dotted-quad form (e.g.
/255.255.255.0). The netblock list may contain more macros previously created
by define commands. No spaces are allowed in the netblock list. There are
some netblock macros built into the metawall script; these can be displayed
with the -n option on the command line.
- protocol name base-protocol protocol-options
-
The protocol command is similar to the define command, but instead of defining
macros for network blocks it defines them for protocols. Metawall provides a
number of builtin protocols whose definitions can be displayed by using the -p
option on the command line. The name must follow the same rules as defined
names. The base protocol may be a real IP protocol such as icmp, tcp, or udp
or it may be another protocol already created by the protocol statement.
It may also be an IP protocol number from 1 to 255. If the IP protocol in
question is icmp, tcp, or udp, you may specify additional options listed below.
- code integer
-
This option is only valid with the ICMP protocol, and specifies the ICMP
code field. Valid codes range from 0-255. You may not specify a code unless
you also specify an ICMP type.
- dport portrange
-
This option is only valid with the TCP or UDP protocol. It specifies the
allowed port range for the destination port field. The port range may be a
single integer or a colon-separated range. The number before or after the
colon may be omitted when the lower or upper end of the range is 0 or 65535
respectively. This option is commonly used to distinguish between different
application layer protocols, since they often use well known destination port
numbers.
- flags tcpflags
-
This option is only valid with the TCP protocol. It specifies what TCP
flags must be set or unset for the rule to match. For example, you can
use 'flags SYN,!ACK' to match TCP packets with SYN set and ACK cleared.
Valid flags are ACK, FIN, PSH, RST, SYN, and URG.
- sport portrange
-
This option is only valid with the TCP or UDP protocol. It specifies the
allowed port range for the source port field. See the dport option for info
on the port range format.
- type integer
-
This option is only valid with the ICMP protocol, and specifies the ICMP
type field. Valid types range from 0-255.
- deny/drop rule
-
The deny and drop commands are synonyms; they perform the same function.
Any packet which matches the specified rule will be dropped, and processing
of the remainder of the chain will terminate. See the RULES
section for information on rule specification.
- reject rule
-
The reject command is similar to the deny/drop command, but in addition to
dropping the packet it will generate an ICMP unreachable message back to the
packet source. See the RULES section for information on rule specification.
- permit/accept rule
-
The permit and accept commands are synonyms; they perform the same function.
Any packets which matches the specified rule will be permitted through, and
processing of the remainder of the chain will terminate. The permit command is
generally expected to allow a two-way traffic stream. Stateful backends will
do this using the state table; on stateless backends a pair of rules will be
generated, one for the forward traffic and one for replies. The
oneway
option can be used to override this behavior on stateless backends. See the
RULES section for information on rule specification.
- jump rule
-
The jump command is used to transfer control to a different chain when the
rule is matched. The rule associated with a jump command must include the
chain option, which specifies which chain to jump to. See the RULES section
for information on rule specification.
Most metawall commands produce packet filtering rules. Those commands include
permit/accept, deny/drop, reject, and jump. Every rule has a similar format
that looks like this:
command protocol source [options] destination [options]
Actually, the parser allows everything after the protocol argument to be
arbitrarily ordered, except that the source must come before the destination.
It is suggested that you keep source and destination options grouped after
the source and destination addresses for clarity, but this is not required.
The protocol argument may be any protocol that is built into metawall (use the
-p command line option for a list) or anything that has already been defined by
using a protocol command. The source and destination arguments are formatted
exactly the same as the right hand side of the define command. In other
words, a comma separated list of networks or already defined macros. The
keyword 'any' for the source or destination is equivalent to 0.0.0.0/0.
Options may be specified anywhere in the line after the protocol argument.
All options described in the protocol command in the COMMANDS section are
supported here as well, and they will override options associated with the
chosen protocol. These option definitions will not be repeated here. The
following options are also supported:
- chain name
-
This option is only valid when used with the jump command. In that case,
it specifies the name of the chain to jump to if the rule matches.
- iint interface
-
The
iint option specifies what interface the packet must be received on.
The rule will not match if the packet was not input on the specified
interface.
- log
-
This option causes packets matching this rule to be logged via syslog. There
is currently no way to modify the logging level, though this will probably
be added in the next release.
- oint interface
-
The
oint option specifies what interface the packet will be transmitted on.
The rule will not match if the packet will not be output on the specified
interface.
- oneway
-
This option suppresses the generation of the reply rule when using a stateless
backend. This can be particularly useful when trying to permit certain ICMP
traffic in one direction only, but it can be used with any protocol.
This section provides a number of examples of metawall command syntax. These
examples are not recommendations of what rules you might want to use! The
rules that are appropriate for any firewall must be determined according to the
security policy at that site. These serve only to demonstrate the types of
things that can be done with metawall.
# Define some network macros
define BOGONS RFC1918,0.0.0.0/8,127.0.0.0/8,169.254.0.0/16
define OURNET 192.0.2.0/24
define DNS_SERVERS 192.0.2.5,192.0.2.6
# We need special protocols
protocol foobar tcp dport 2256
protocol quake3 udp dport 27960:27975
# Deny all traffic from bogus (spoofed) addresses
deny ip BOGONS any
# Prevent spoofing our addresses if eth1 is the outside
deny ip OURNET iint eth1 any log
# Allow some common outbound protocols
permit ftp OURNET any
permit ssh OURNET any
permit http OURNET any
permit https OURNET any
# We also use the all-powerful foobar protocol
permit foobar OURNET any
# Allow external access for some services
permit http any www.example.com
permit dns any DNS_SERVERS
permit quake3 any 192.0.2.50
# Allow zone transfers to our secondaries
permit dnsxfr ns2.mydyndns.org,ns3.mydyndns.org DNS_SERVERS
# Allow email to/from mailservers
permit smtp 192.0.2.20 any
permit smtp any 192.0.2.20
# See what outbound stuff we are dropping
deny ip OURNET any log
# Make sure everything else is dropped
deny ip any any
- Version 0.13
-
Rules no longer print when in exec mode.
Fixed bug that caused undefined 4-character symbols to be interpreted as
ASCII-encoded IP addresses.
- Version 0.12
-
Added support for TCP flags.
Added support for IP protocol numbers.
Changed what types of ICMP rules generate stateless reply rules.
Symbols may now contain '-' characters.
Fixed some buglets in symbol and token parsing.
Added a few more protocols.
- Version 0.11 (unreleased)
-
Replaced -i install option with more flexible -c chain name option.
- Version 0.10
-
Initial release with iptables support.
Steve Snodgrass <ssnodgra@pheran.com>
Copyright (C)2002 Steven R. Snodgrass
This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place, Suite 330, Boston, MA 02111-1307 USA
The metawall home page can be found at http://www.pheran.com/metawall/.
Thanks to Luis E. Munoz for his excellent NetAddr::IP module, and to my
wonderful wife for allowing me to hide out in my den long enough to hack
this thing together. :-)
Networking
Metawall is a perl script that allows you to write firewall rules in a simple
metalanguage. These rules can then be used to generate packet filtering
commands for a variety of backend targets.