LABREA.CONF(5)							File Formats Manual						    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  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" time-
       out 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  cap-
       tured. 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 cap-
	      turing.

	      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)