LABREA.CONF(5)                                     LABREA.CONF(5)



NAME
       labrea.conf - labrea(1) configuration file

SYNOPSIS
       nnn.nnn.nnn.nnn [- nnn.nnn.nnn.nnn] EXC

       nnn.nnn.nnn.nnn [- nnn.nnn.nnn.nnn] HAR

       nnn.nnn.nnn.nnn[/nn] IPI

       nnnnn [- nnnnn] POR

       nnnnn [- nnnnn] PMN


DESCRIPTION
   Generalities
       labrea.conf  is  the  configuration file for the labrea(1)
       program.

       Each line consists of a selector  field,  followed  by  an
       action verb.

       Whitespace  is suppressed. Blank lines are ignored, as are
       lines beginning with "#".

   Selectors
       IPs can be specified as  either  a  single  address  (e.g.
       "192.168.0.4")   or   as   a   range  of  addresses  (e.g.
       "192.168.0.1 - 192.168.0.50").

       Ports can be specified  as  either  a  single  port  (e.g.
       12345) or as a range of ports (e.g. 1-65535).


   IP Capturing
       When  labrea sees an ARP request for an unused IP, it does
       the following:

       On an IP by IP basis, store a time and an  originating  IP
       address:

       1.     For  an  incoming  ARP  request,  check the current
              time:

              a.     If currently stored time is  0  or  the  arp
                     comes  from a different address than the one
                     stored, then store the current time and  the
                     requesting IP and return.

              b.     If the stored time is less than "-r" seconds
                     ago, ignore it and return.

              c.     If currently stored  time  is  more  than  a
                     minute ago, store 0, return. (Max timeout)

              d.     Otherwise, grab the IP.

       2.     See an ARP reply, set stored time to 0.

       When  an  ARP  request for a particular IP goes unanswered
       for longer than its "rate" setting (default:  3  seconds),
       labrea  crafts  an  ARP reply that routes all traffic des-
       tined for the IP to a "bogus" MAC address.  labrea listens
       for  TCP/IP  traffic  routed  to that MAC address and then
       responds to any SYN packet (ie incoming connection) with a
       SYN/ACK packet.

   Explanation of terms
       Excluded  IPs: Are those IPs that labrea should never cap-
       ture. Note that automatic mechanisms are also used to pre-
       vent  capturing  IPs  with  an  active  machine on it. See
       labrea(1) for more details.

       Hard captured IPs: The -h --hard-capture option  instructs
       labrea  that  once  it  captures  an  IP  address, then it
       needn't wait for a "-r"  timeout  the  next  time  around.
       These IPs are said to be "hard" captured.

       Hard  excluded  IPS:  These  are  IPs that should never be
       "hard" captured. In other words, each time there is an ARP
       request  for this IP, then labrea will always wait for the
       timeout -r secs before responding.

       Tarpitting: On a captured IP, labrea responds to an incom-
       ing SYN connection attempt with a SYN/ACK. This causes the
       remote machine's stack to initiate the Tcp connection  and
       then waste time fruitlessly trying to continue the conver-
       sation.

       Persist state capture: labrea can permanently capture con-
       nect  attempts by closing the TCP window to force the con-
       nection into "persist" state. In this state,  the  connec-
       tion  never times out, and labrea hangs on to the incoming
       connection until it is closed from the other end.

       To accomplish this, short packets are sent every so  often
       to say "keep waiting, my Tcp window is still closed". So a
       maximum b/w control is implemented to limit the total  b/w
       consumption. (see the -p --max-rate startup option)

       Auto  hard  capturing:  This is a startup option that says
       that unless an IP is excluded or hard-excluded, then  mark
       it  as being hard captured. This is normally a risky thing
       to do and should be used with caution.

   Normal virtual machine behaviour
       Default port behaviour: Incoming connections on  any  port
       will be subject to tarpitting / persist capturing.

       Since  all  connections  are  inbound,  there should be no
       incoming SYN/ACKs. Labrea will respond RST to an  incoming
       SYN/ACK unless the startup option -a --no-resp-synack dis-
       ables this behaviour.

       Excluded ports: Ports that are specifically excluded  will
       not be tarpitted or persist captured.

       Incoming  connection  attempts  on  an  excluded port will
       receive a RST.

   Virtual machine behaviour when firewalling:
       Active  ports:  When  firewalling  (i.e.   -f   --no-resp-
       excluded-ports)  is  active, then by default only the most
       widely used ports are active at startup.

       Incoming connections on these active ports will be tarpit-
       ted and/or persist captured as usual.

       Excluded  ports: When firewalling is active, incoming con-
       nections on excluded ports will not  receive  a  response.
       The packets will be dropped.

       Among  other  things, this means that nmap scans take much
       more time to complete.

       Other ports: Ports that are neither  active  nor  excluded
       are  passively  monitored  for  incoming  SYN activity. At
       startup, they behave as an excluded port (i.e. packets are
       dropped).

       However,  if  there is enough activity on a given port, it
       will dynamically become active. The threshold is more than
       6  SYNs for a given port in an hour. However every 15 min-
       utes, the port's SYN count is reduced by  1  to  eliminate
       noise.

       If  the SYN count for a port finally reaches 255, then the
       port is considered permanently active.

USAGE
       This section describes the  configuration  statements  and
       their usage:

       nnn.nnn.nnn.nnn [- nnn.nnn.nnn.nnn] EXC
              Never  capture  the  specified  IP  addresses. This
              applies to local IP addresses (i.e.  on  the  local
              capture netblock) only.

       nnn.nnn.nnn.nnn [- nnn.nnn.nnn.nnn] HAR
              WHen  "hard  capturing"  is  in effect ("-h"), then
              never hard  capture  the  specified  IP  addresses.
              (i.e.  Always  wait  for  the  ARP  timeout  before
              responding.) Applies to local IP addresses only.

       nnn.nnn.nnn.nnn[/nn] IPI
              Ignore any packets with source IP  address  in  the
              specified  netblock. labrea will not tarpit or per-
              sist capture  connections  from  the  specified  IP
              addresses.

              Note  that  this  statement  can  apply  to  any IP
              address.

              Note also that the netblock is  specified  in  CIDR
              notation (ie nnn.nnn.nnn.nnn/nn) and not as a range
              of IP addresses.

       nnnnn [- nnnnn] POR
              These ports are excluded. labrea will not tarpit  /
              persist   capture  incoming  connections  on  these
              ports. A RST will be returned unless firewalling is
              active.  In  that case, the incoming packet will be
              dropped.

       nnnnn [- nnnnn] PMN
              At startup,  mark  the  indicated  ports  as  being
              active.  Incoming  connections  to  these ports are
              subject to tarpitting / persist capturing.

              This configuration statement is  useful  only  when
              firewalling is active. The port becomes immediately
              active, instead of waiting for enough SYNs to  bump
              the  port's SYN count above the activity threshold.

EXAMPLES
       Suppose that the capture subnet is 192.168.10.0/24.

       Exclude 192.168.10.5 through .7 from being captured:

              192.168.10.5 - 192.168.10.7 EXC

       "Hard exclude" 192.168.10.100:

              192.168.10.100 HAR

       Do not attempt to tarpit / persist  capture  packets  from
       the class C subnet 10.2.3.x:

              10.2.3.0/24 IPI

       Put in some comments:

              #
              #    This is a comment
              #

       Do not tarpit / persist capture on ports 21-25:

              21-25 POR

       When firewalling, make port 12345 active at startup:

              12345 PMN

FILES
       /usr/local/etc/labrea.conf
              Default configuration file on unix systems

       (current directory) LaBrea.cfg
              Default configuration file on Windows systems

SEE ALSO
       labrea(1)

AUTHOR
       Tom    Liston    <tliston@hackbusters.net>    Bugs:   lor-
       gor@users.sourceforge.net or http://labrea.sourceforge.net



                                                   LABREA.CONF(5)
