bionic (5) labrea.conf.5.gz

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)