Provided by: labrea_2.5-stable-2_i386 bug

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 destined 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 capture. Note that
       automatic  mechanisms  are  also  used to prevent 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  incoming  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 conversation.

       Persist  state capture: labrea can permanently capture connect attempts
       by closing the TCP window to force the connection into "persist" state.
       In  this  state, the connection 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 disables 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 tarpitted and/or
       persist captured as usual.

       Excluded ports: When firewalling is  active,  incoming  connections  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 minutes, 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 persist 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: lorgor@users.sourceforge.net
       or http://labrea.sourceforge.net

                                                                LABREA.CONF(5)