Provided by: labrea_2.5-stable-3build1_amd64 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)