husk %VERSION%
http://www.huskfw.info

husk is a natural language wrapper around the Linux iptables packet filtering.
It is designed to abstract the sometimes confusing syntax of iptables into
a format that is easier and friendlier to read and understand.

husk can be used on either firewall/router computers (with multiple network
interfaces), or standalone systems (with one network interface)

Each interface (real or virtual) is called a 'zone' in husk. Zones are given
a friendly name which is what is used in the rule definitions. This abstracts
the Linux device names (eg, eth0, ppp0, bond0 etc) into much more intuitive
names such as NET, LAN and DMZ. This has the added benefit of moving interfaces
in the future can be done simply by changing the name-to-device mapping.

===============================================================================

    INSTALLATION.

Husk can be installed using standard 'make' commands. You must be root to
install correctly.

Install everything:
    make all

Install only the script:
    make bin

Install only the docs:
    make docs

Install only the configuration examples:
    make config

Uninstallation is also catered for:
    make uninstall

===============================================================================

    SETUP.

First, give your interfaces friendly names in the file 'interfaces.conf'. An
example file might look like:
    zone ME is lo
	zone NET is eth0
	zone LAN is eth1
	zone DMZ is eth2
I recommend simple 3 letter friendly names for your zones.

IMPORTANT NOTE: loopback ('lo') *must* be called the special name 'ME'.

===============================================================================

    WRITING RULES.

===============================================================================
1. Common Firewalling
husk has built-in 'common' firewall rules, prefixed with the keyword 'common'
    NAT:        common nat ZONE
                Apply a Source NAT to traffic going out ZONE, usually 'NET'
                eg: common nat NET
    SPOOF:      common spoof ZONE ADDRESS/PREFIX
                Prevent address spoofing on the specified ZONE. ADDRESS/PREFIX
                defines the addresses that are expected to be seen on the given
                ZONE. You can add multiple 'spoof' rules per interface.
                eg: common spoof LAN 10.0.0.0/24
                    common spoof LAN 10.0.1.0/24
                    common spoof DMZ 192.168.100.0/29
    BOGON:		common bogon ZONE
                Block bogon traffic on the specified ZONE. Bogon traffic is
				packets with source addresses that should never be seen outside
				private networks such as RFC1918 addresses, 127.0.0.0/8 etc.
	PORTSCAN:	common portscan ZONE
				Attempt to detect, log and drop portscans coming from the given
				zone. This is only rudimentary, but it's better than nothing.
    XMAS:		common xmas ZONE
                Block xmas packets on the specified ZONE. Xmas packets are
				packets with all flags set, or the packet "is lit up like
				a Christmas tree"
    SYN:        common syn
			    All packets that the kernel detects as belonging to a "NEW"
				connection should have the "SYN" flag set. If they don't, then
				we DROP them.
    LOOPBACK:   common loopback
                Create a rule to accept traffic in/out the 'lo' interface

===============================================================================
2. define rules ZONE to ZONE
Traffic passing between zones is known as cross-zone traffic - eg LAN to NET
Defining rules for this cross-zone traffic is done in a 'define rules' block:
    define rules LAN to NET
    <rules go here>
    end define

There is a special in-built interface called 'ANY' which as the name suggests.
allows you to write a match calls that ignores one (or both) of the IN and OUT
interfaces. For example:

Allow the whole world to access Secure POP3 on our mail server.
	define rules ANY to DMZ
	accept protocol tcp port pop3s destination address mail.example.com
	end define

This is effectively the same as the FORWARD table, but only NEW connections
are passed through here:
	define rules ANY to ANY
	accept protocol tcp port 873	# rsync anywhere is fine
	end define

NOTE: 'ANY' *excludes* the other interface to avoid bounce routing issues. So
      a match calls for 'ANY to LAN' doesn't include traffic 'LAN to LAN'. If
	  you need to allow bounce routing, then add a rule such as:
	  	define rules FORWARD
		accept incoming LAN outgoing LAN
		accept incoming DMZ outgoing DMZ
		<etc>
		end define

===============================================================================
3. define rules <USER DEFINED>
You can create your own user-defined chains (UDC) using 'define rules' block.
These user-defined chains can then be called from cross-zone blocks.
    define rules SMB_PORTS
    <rules go here>
    end define

===============================================================================
4. define rules (INPUT|OUTPUT|FORWARD)
To add rules to the standard iptables filter table chains (INPUT, FORWARD and
OUTPUT), write a 'define rules' UDC block for the appropriate chain:
    define rules INPUT
    <rules go here>
    end define

===============================================================================
5. Rule Keywords
Example rules are below. I think this will be the easiest way to explain
the keywords and functions of husk. All keywords can be mixed and matched
to suit the rule(s) you require.

    accept source address 192.168.100.100
        Accept anything from source address 192.168.100.100

    accept proto tcp port http destination address google.com.au
        Allow TCP port 80 to whatever 'google.com.au' resolves to via DNS.

    accept proto tcp ports http,https source range 192.168.0.1 to 192.168.0.10
        Allow any TCP port 80 and 443 traffic from addresses .1 to .10

    accept mac 00:14:22:d8:f9:55
        Anything from the given MAC Address is allowed.

    reject source address 169.254.53.0/24
        Reject with ICMP unreachable packet any traffic from the given IP

    SMB_PORTS destination address 192.168.1.100
        Jump to the user-defined chain "SMB_PORTS" for traffic to 192.168.1.100

    accept all
        Accept everything.

    accept proto icmp type echo-request limit 4/sec burst 8
        Allow 4 ICMP 'echo-request' packets per second, bursting to 8pps

    accept proto icmp type echo-reply limit 4/sec burst 12
        Allow 4 ICMP 'echo-reply' packets per second, bursting to 12pps

    drop
        Just drop all packets.

    accept in LAN protocol icmp
        Accept any icmp packets that come in the LAN interface.

===============================================================================
6. Port Forwarding (DNAT)
If you need to forward incoming traffic from one interface to another using the
NAT feature of the kernel, you can use the 'map' rule. For example, to NAT port
80 traffic coming in the "NET" interface to an internal server:
    map in NET destination address protocol tcp port 80 74.132.12.56 to 172.16.1.1

You can also translate the ports from one to another by appending to the
destination address:
    map in NET destination address 74.132.12.56:80 to 172.16.1.1:8080

===============================================================================
7. Intercepting / Redirection
Using the 'trap' or 'redirect' keyword, you can silently redirect traffic to
the local computer. This is useful for example to intercept all outgoing SMTP
traffic to force it through the local SMTP gateway:
    trap in LAN protocol tcp port 25

Redirecting to alternative ports is also possible:
    redirect incoming NET protocol tcp port 80 to 8080
    redirect incoming NET protocol tcp port 2222 to 22

===============================================================================
8. Raw iptables rules
Directly writing iptables rules is also supported for putting your own rules in
using iptables syntax:
    iptables -t raw -A OUTPUT -d 10.0.0.0/8 -j NOTRACK

===============================================================================
9. Includes
If your ruleset is complicated, you can spread the rules over multiple files
then consoldate them all together at compile time by using the 'include'
keyword:
    include outbound.rules
    include inbound.rules

Includes can be either relative paths (to the conf dir) or absolute paths.
You should be able to nest indefintiely, but be careful not to create loops
such as:
    [rule-one.conf]
    include rules-two.conf

    [rules-two.conf]
    include rules-one.conf

There is NO PROTECTION against this.

===============================================================================

    COPYRIGHT and LICENSE

husk is Copyright 2010 Phillip Smith <fukawi2 (at) gmail (dot) com>

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, see <http://www.gnu.org/licenses/>.