
                   Drawbridge Filter Compiler 3.0


The Drawbridge Filter Compiler is used to compile the filter configuration
file into the tables used by the Drawbridge Manager.  This document will
cover the syntax of the filter source language and how to use the compiler.


The Filter Configuration Language
=================================

o Comments

A comment starts with a '#' and extends to the end of the line.  Comments
can appear anywhere within the filter config file.


o Service Specification

The basic element of the language is the service specification.  A service
specification is enclosed by the symbols '<' '>' and contains up to four
pieces of information:

    The port to test (optional)
        Specifies which port (src or dest) to look at within the packet.
        The destination port is the implied default.  The keyword 'src='
        causes the source port to be used instead.

    The service
        Can be an entry from /etc/services, a numeric port value, or a
        numeric ICMP type.  Service ranges can also be specified by using
        a '-' between a pair of services.  The specified service port is
        compared to the destination (or source) port within the packet.

    The protocol (optional)
        Can be 'TCP', 'UDP', or 'ICMP' and is separated from the service
        by a '/'.  Other valid protocols can be specified but will be
        silently ignored by the compiler.  If not specified, TCP is the
        default.

    The traffic direction
        Indicates whether this specification is for outbound packets,
        inbound packets, or both.  Outbound is specified by 'out',
        inbound by 'in', and both by 'in-out'.


Examples:
        <smtp/tcp in-out>       # Allow smtp connections, either direction.
        <1-65535 out>           # Allow all outbound TCP connections.
        <ntp/udp in>            # Allow UDP based network time protocol in
        <src=ftp-data in>       # Allow data connect for outbound ftp
        <3/icmp in>             # Allow in ICMP type 3 in (dest unreachable)

Prefacing the service specification with an exclamation mark, ('!'),
indicates that this service is not allowed.  The section on 'Combining
Service Specifications' explains what this means.

Examples:
        <!tftp/udp in>          # Do not allow tftp in
        <!login in>             # Do not allow rlogin in
        <!2049/udp in>          # Do not allow NFS in
        <!8/icmp in>            # Do not allow icmp echo requests in (ping) 

Certain combinations of allowed or disallowed services are accepted, but
will generate no output, as the filter currently does not use them.  For
example, since the filter does not support outbound UDP filtering, the
specification <!tftp/udp out> will be ignored by the compiler.  See the
paper overview.ps for more information on what filtering is available.
(This paper does not yet cover the new features in version 3.0).


o Groups

Groups of service specifications can be defined to prevent having to
repeatedly enter the same data and introducing typos.  Groups can also be
used to quickly change the access characteristics of an entire set of
machines.  A group is a list of comma-separated service specifications or
other previously defined groups, terminated by a semicolon (';').  For
example:

        define normal <smtp in>, <gopher in>;

This example creates a group called 'normal' which includes inbound SMTP
and inbound GOPHER.  This group can be used in other groups to build up
larger groups:

        define server normal, <telnet in>;

In this example, the new group 'server' includes SMTP, GOPHER and TELNET
in.

The special group 'default' is used to define access class 0, which is the
default access for any machine not explicitly defined in the config file.
For example:

        define default <1-65535 out>, <0-4/icmp in>, <6-18/icmp in>,
                       <src=ftp-data in>, <smtp in>;

Allows all outbound connections, all inbound ICMP except redirects, smtp
(email) in, and ftp's data connections in for all machines which do not
appear in the config file.  Normally, all machines in the config file will
want the default services as well, therefore, group 'default' should be
added to the machines in the config file.


o Defining Host Access

To define the access for a particular host, simply give the hostname and a
comma-separated list of service specifications and/or group names.

        host myserver  default, server;
        host nyhost    default, <nntp in>;

Using the previous definitions for server, normal and default, host
'myserver' will have:
        <1-65535 out>, <0-4/icmp in>, <6-8/icmp in>,
        <src=ftp-data in>, <smtp in>, <gopher in>, <telnet in>;

and host 'myhost' will have:
        <1-65535 out>, <0-4/icmp in>, <6-8/icmp in>,
        <src=ftp-data in>, <smtp in>, <nntp in>,


o Defining Network Access

If you want to specify access for an entire range of addresses, you can use
the 'network' command, which is similar to the `host' command.  A range of
addresses can either be specified by a start - end address pair _or_ as a
start address and a network mask.  Please note that this is different from
pre 3.0 versions.  Previously, the network mask was always required but was
never used if a range was given.

    #       Address-Address Range        Service Spec
    network 123.45.66.0-123.45.67.255    <!1-65535 in-out>;  # Example 1
    network 123.45.70.5-123.45.70.255    <!1-65535 in-out>;  # Example 2

    #       Address      Netmask         Service spec
    network 123.45.66.0  255.255.254.0   <!1-65535 in-out>;  # Example 3
    network 123.45.70.5  255.255.255.0   <!1-65535 in-out>;  # Example 4

Examples 1 and 3 are equivalent.  Example 1 allows no TCP connections
in or out for addresses 123.45.66.0 through 123.45.67.255.  Example 3
shows how to do the same thing with an address and network mask.  Examples
2 and 4 are similar but do not do specify the same range of addresses.
Example 2 specifies the address range 123.45.70.5 through 123.45.70.255
while Example 4 specifies the address range 123.45.70.5 through 123.45.71.4.
Example 4 demonstrates that the host portion of the address plays a part
in determining the address range when an address and mask is given.
Basically, the size of the address range is determined by the mask and
the host portion, if non zero, will shift the start and end of the
range.

If a host is defined in more than one 'host' or 'network' command, the last
definition is the one that is used (this will probably generate an error or
warning in later versions).


o Combining Service Specifications

When multiple service specifications appear in a group definition or
host/network command, they are merged.  Service specifications are merged
by 'or'ing the _allowed_ services, then _REMOVING_ those which are
explicitly disallowed.  For example:

        define group1   <telnet in>, <!login in>, <!tftp/udp in>;
        define group2   <telnet out>, <smtp in>, <login in>;
        define group3   group1, group2, <tftp/udp in>;

'group3' will have <telnet in-out>, <smtp in>.  It is important to note
that even though 'group2' allows <login in> and 'group3' allows <tftp/udp
in>, it is not possible to override the <!login in> and <!tftp/udp in>
specified in 'group1'.  'group3' also inherits the negative service
specifications.  In other words, the actual value of group3 is:

        <telnet in-out>, <smtp in>, <!login in>, <!tftp/udp in>

Also notice that the <telnet in> and <telnet out> in the combined group are
equivalent to <telnet in-out>.


o Generation of Classes

As a host's access capability is specified, either by use of a 'host' or
'network' command, classes of hosts are generated.  All the members of a
specific class have the same access allowed to them.  It doesn't matter in
what order the accesses were given, only that in the end, they have the
exact same access.  There can be up to 256 different classes, with class 0
reserved for those hosts which are not explicitly specified in the config
file.  Class 0's capabilities are defined by the special group 'default'.
Each class can have up to 32 port ranges for each of category of filter
(incoming TCP, outgoing TCP, incoming TCP srcport, incoming UDP, and
incoming ICMP).  The filter compiler automatically merges adjacent service
specifications into a single range.


o Address Tables

Address tables can be used to selectively filter or allow, on a global
basis, sepcific ranges of addresses.  There are three address tables:
reject, allow, and override.  The reject table filters incoming packets and
the accept table filters outgoing packets.  Both tables filter packets
based on their source IP address.  The override table is a little
different.  It allows otherwise filtered outgoing packets through based on
the packet's destination IP address.

Each entry in a table defines a range of addresses by using a specified
address and network mask.  The filter action of a given entry can be
inverted by placing a '~' in front of the address.  Each table can have a
maximum of 32 entries.  The number of entries in each table should be kept
low for best performance.


Reject Table

    Syntax:
        reject [~]address netmask

    Example:
        Reject all incoming packets coming from a specified network.

            reject 18.23.45.0 255.255.255.0;

        This will reject incoming IP packets with an address in the range
        of 18.23.45.0 through 18.23.45.255.  Note that unlike defining
        network access ranges, the host portion of the address is ignored.
        For example, 18.23.45.5 with network mask 255.255.255.0 will
        produce exactly the same results as 18.23.45.0 with network mask
        255.255.255.0.  One specific host can be specified by using a mask
        of 255.255.255.255.

        This table can be used for a variety of things but is primarily
        provided to block IP packets from the outside that have a source
        address of a host on the inside network.  The only time this could
        occur is when an outside host is trying to masquerade as a host
        on the inside.  This is commonly known as address 'spoofing'.


Accept Table

    Syntax:
        accept [~]address netmask

    Example:
        Accept all outgoing packets coming from a specified network.

            accept 18.23.45.0 255.255.255.0;

        This will allow outgoing IP packets with an address in the range of
        18.23.45.0 through 18.23.45.255.  Like the reject table, the host
        portion of the address is ignored.

        This table is provided to prevent IP address 'spoofing' from hosts
        on the local (inside) network(s).  If the table is empty, all IP
        packets are passed from the inside to the outside of the filter.
        If the table is not empty, only IP packets with a source address
        included by an entry in the accept table will be passed through the
        filter - all other packets will be discarded.


Override Table

    Syntax:
        override [~]address netmask <service-specification list>;

    Example:
        Allow specified outgoing IP packets to the specified network or
        host even if it is denied by the class table.

        override 123.45.67.0 255.255.255.0   <80/tcp out>;

        This will allow all inside hosts access to the outside http servers
        in the address range 123.45.67.0 through 123.45.67.255 even if the
        inside host's class contains <!80/tcp out>.
      
        The expected use of the 'override' table is to grant access to
        specific services on specific outside hosts.  For example, if a
        set of lab PC's normally do not have access to the Internet, the
        'override' subcommand can allow these machines access to a specific
        service or services on a specific set of outside hosts/servers.



o Include Files

Any portion of the Drawbridge configuration file can be broken out and
stored in a seperate file.  This seperate file can then be included in the
main filter config file with an include statement.  Any number of files may
be included and nesting of files is allowed (up to memory capabilities).
Include loops are detected and prevented.  An include statement has the
following syntax:

        include filename

Example:
    If you had two external files named 'part1' and 'part2', they could be
    included in the main file with:

        include part1;
        include part2;



The Filter Compiler
===================

The Drawbridge Filter Compiler 'dbfc' generates the filter control tables
from the input filter config file and writes them to a single output file.
These tables can then be loaded into the filter using the 'dbmgr' utility
which is documented in the file 'MANAGER'.


Usage:  dbfc [-v] input-file [output-file]

Switches:
        -v    Displays the version and copyright notice.

After compiling the specified configuration file, the compiler will display
few statistics on the number of networks, hosts, and classes generated and
will create, or overwrite, a composit filter config file in the current
directory.  By default, this file is called 'db_filters'.  The composit
file contains the network tables, the class tables, the reject table, the
accept table, and the override table.

A network table will be created within the output file for each IP network
found in the input config file.  The size of a network table will depend on
the class (as in network class not drawbridge access class) of the network
referenced.  A class 'C' network will generate a 260 byte table.  A class
'B' network will generate a 65540 byte table.  The network tables contain
the indices into the drawbridge access class tables for each host in the
referenced networks.  The size of the compiler output file will depend
mainly on the number and size of the network tables within it.

o A Note About Drawbridge and Network Classes

Drawbridge does not yet understand CIDR (Classless Inter-Domain Routing)
blocks and is still based on the network class system.  In the network
class system, a class 'A' network has a mask of 255.0.0.0, a class 'B'
network has a mask of 255.255.0.0, and a class 'C' network has a mask of
255.255.255.0.  The drawbridge compiler automatically determines a host's
network class, and thus the network size, by looking at the first few bits
of the host addresses specified in the config file.  Future versions of
drawbridge will probably be based on CIDR blocks instead of network
classes.


Example Filter Source File
==========================

#------------------------- Group Definitions ------------------------#

#
# Make some useful definitions
#

# Allow all TCP out and no TCP in except:
# src=ftp-data, smtp, auth, gopher, and www
define tcpdefault       <1-65535/tcp out>, <src=ftp-data/tcp in>,
                        <smtp/tcp in>, <auth/tcp in>,
                        <gopher/tcp in>, <www/tcp in>;

# Allow all UDP except ports 7-19, tftp, sunrpc, snmp, xdmcp, and nfs
# Note: we don't use '!' to exclude ports because it can't be overridden
define udpdefault       <1-6/udp in>, <20-68/udp in>, <70-110/udp in>,
                        <112-160/udp in>, <162-176/udp in>, <178-2048/udp in>,
                        <2050-65535/udp in>;

# Allow all known ICMP except redirect
define icmpdefault      <0-4/icmp in>, <6-18/icmp in>;

define telftp           <telnet/tcp in>, <ftp/tcp in>;
define popmail          <109-110/tcp in>;
define blockall         <!1-65535/tcp in-out>, <!1-65535/udp in>,
                        <!0-255/icmp in>;

#
# The special name 'default' defines access for hosts not listed in this file
#
define default          icmpdefault, udpdefault, tcpdefault;

#------------------------ Table Definitions -------------------------#

#
# Reject all incoming packets with a source address of localhost or broadcast.
#
reject 127.0.0.0        255.0.0.0;
reject 0.0.0.0          255.255.255.255;
reject 255.255.255.255  255.255.255.255;

#
# Reject all incoming packets with a source address that is within our
# class B network.  Make an exception for our outside router.
#
reject 123.456.0.0      255.255.0.0;
reject ~123.456.78.9    255.255.255.255;

#
# Accept only outbound packets with a source address that is within our
# class B network.
#
accept 123.456.0.0      255.255.0.0;


#----------------------- Network Definitions ------------------------#
#
# Admin requested no access in/out for these addresses
#

# addresses defined with a mask
network 123.45.58.0 255.255.255.0       blockall

# addresses defined with a range
network 123.45.39.23-123.45.40.254      blockall


#---------------------- Broadcast Addresses -------------------------#

# Block all packets directed to the broadcast addresses within our network
host 123.45.1.0                 blockall;
host 123.45.1.255               blockall;
host 123.45.2.0                 blockall;
host 123.45.2.255               blockall;
#
#
#
host 123.45.255.0               blockall;
host 123.45.255.255             blockall;

# This would be a good use of an include file.  We run a script every
# night that queries the nearest router for the list of our current 
# broadcast addresses (around 450 addresses).  The script writes a filter 
# config file that is included in the main filter config file to block
# packets to the broadcast addresses.  For example:

include bcast-hosts.config


#------------------------ Host Definitions --------------------------#

# The Drawbridge host - UDP ports must be open for DNS queries
# Allow src=ftp-data and ssh; block ICMP echo request
host drawbridge.nowhere.edu     udpdefault, <1-65535/tcp out>,
                                <src=ftp-data/tcp in>, <ssh/tcp in>, 
                                <0-7/icmp in>, <9-18/icmp in>;

# No access in/out
host bee.nowhere.edu            blockall;
host g1.nowhere.edu             blockall;

# Allow domain to hosts running dns for zone transfers
host dns.nowhere.edu            default, <domain in>;
host mydns.cs.nowhere.edu       default, <domain in>;
host bigadd.math.nowhere.edu    default, <domain in>;

# NNTP host and CSO phonebook server
host mailnews.nowhere.edu       default, telftp,
                                <nntp in>, <time in>,
                                <csnet-ns in>, <domain in>,
                                <finger in>;

# These are all the VMS machines which have been cleared for telnet/ftp.
host h1.nowhere.edu             default, telftp;
host h2.nowhere.edu             default, telftp;
host h3.nowhere.edu             default, telftp;
host h4.nowhere.edu             default, telftp, <domain in>;  #dns also
host h5.nowhere.edu             default, telftp;

# Research group using port 4211
host h8.nowhere.edu             default, telftp, <4211/tcp in>;

# Block www and gopher to internal server
host www.english.nowhere.edu    default, <!gopher in>, <!www in>;

# NTP time server
host h9.nowhere.edu             default, telftp, <ntp in>, <time in>;

# FTP servers
host somepc.nowhere.edu         default, <ftp in>;
host d2.nowhere.edu             default, <ftp in>;
host someone.nowhere.edu        default, <ftp in>;

# Telnet and FTP servers
host slow.nowhere.edu           default, telftp;
host fast.nowhere.edu           default, telftp;
host trouble.nowhere.edu        default, telftp;
host dunno.nowhere.edu          default, telftp;
host meat.nowhere.edu           default, telftp, <finger in>;

# X11 and FTP
host arrow.nowhere.edu          default, <ftp in>, <6000/tcp in>;

# NTP server
host bird.nowhere.edu           default, <ntp in>, <time in>;

# X11
host gotta.nowhere.edu          default, <6000/tcp in>;
host be.nowhere.edu             default, <6000/tcp in>;
host very.nowhere.edu           default, <6000/tcp in>;

# Machine (PC) in library which uses tftp to do document transfers
host sender.nowhere.edu         default, <1-65535/udp in>;

# Robotics Lab
host sp1.robot.nowhere.edu      default, telftp,
                                <2650/tcp in>, <2655/tcp in>,
                                <2700-2702/tcp in>, <3200-3202/tcp in>,
                                <3300-3302/tcp in>, <3500-3502/tcp in>;

# Local MUD's
host someklingon.nowhere.edu    default, <2000/tcp in>;
host hmmmmm.nowhere.edu         default, <2000/tcp in>;

# IRC server
host ick.nowhere.edu            <1-65535/tcp out>, <6667/tcp in>,
                                <smtp in>, <auth in>,
                                udpdefaults, icmpdefaults;

#--------------------------------------------------------------------
