Provided by: labrea_2.5-stable-3build1_amd64 bug

NAME

       labrea - Honeypot for incoming IP connection attempts

SYNOPSIS

       labrea   [-i   --device   INTERFACE]   [-n   --network  nnn.nnn.nnn.nnn[/nn]]  [-m  --mask
       nnn.nnn.nnn.nnn] [-t --throttle-size BYTES] [-p --max-rate RATE ] [-R --soft-restart]  [-r
       --arp-timeout  RATE]  [-s  --switch-safe]  [-h  --hard-capture] [-x --disable-capture] [-X
       --exclude-resolvable-ips]   [-P    --persist-mode-only]    [-a    --no-resp-synack]    [-H
       --auto-hard-capture] [-f --no-resp-excluded-ports] [--no-arp-sweep] [--init-file FILE] [-F
       --bpf-file   FILE]   [-T   --dry-run]   [-d   --foreground]   [-o   --log-to-stdout]   [-O
       --log-timestamp-epoch]  [-l  --log-to-syslog]  [-b  --log-bandwidth]  [-v  --verbose]  [-q
       --quiet] [-z --no-nag] [-? --usage --help ] [-V --version] [-I --ip-addr  nnn.nnn.nnn.nnn]
       [-E   --my-mac-addr   xx:xx:xx:xx:xx:xx]  [-D  --list-interfaces]  [-j  --winpcap-dev  nn]
       [--syslog-server nnn.nnn.nnn.nnn] [--syslog-port nnn]

       [BPF Filter]

DESCRIPTION

       labrea creates virtual machines for unused IP addresses  in  the  specified  block  of  IP
       addresses.  LaBrea sits and listens for ARP "who-has" requests.

       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 sniffs for TCP/IP traffic sent to that MAC address
       and then responds to any SYN packet with a SYN/ACK packet that it creates.

OPTIONS

       labrea accepts the following options:

       -i --device interface
              By default, labrea uses the first ethernet interface. This forces labrea to use the
              specified interface.

       -n --network xxx.xxx.xxx.xxx[/nn]
              labrea  normally  pulls  information  about  the  netblock  from the IP information
              assigned to the interface.  If labrea is run  on  an  unconfigured  interface  (one
              without  an  assigned IP address), then use this option to specify the subnet to be
              captured.

              xxx.xxx.xxx.xxx is the network address.  /nn is the subnet mask in  CIDR  notation.
              If the subnet mask is not specified here, then you must include the -m parameter.

       -m --mask xxx.xxx.xxx.xxx
              Another way to specify the network mask for the capture netblock. If this parameter
              is specified, then the -n parameter must also be specified.

       -t --throttle-size nn
              Sets the TCP window advertisement to limit the amount of data sent to  labrea.  The
              number of data bytes to allow per packet is nn bytes.

       -p --max-rate rate
              Connect  attempts  will  be  permanently  captured by forcing the connection into a
              "persist" state (by closing the TCP window). In this state, the connection will not
              time out.  labrea will permanently capture connect attempts up to maximum bandwidth
              rate bytes.  If the specified bandwidth is exceeded, labrea will still  tarpit  the
              incoming connection (ie respond SYN/ACK to incoming SYN).

       -R --soft-restart
              New captures will be held off for 5 minutes to let bandwidth calculations progress.
              If a major scan hits just after startup, this prevents labrea  from  capturing  too
              many connections.

       -r --arp-timeout rate
              Wait  rate  seconds  after  seeing  incoming  arp  requests  before capturing an IP
              address.

       -s --switch-safe
              When there is an incoming ARP request, specifies that labrea should send out an ARP
              request of its own for the same IP address. This is necessary for safe operation in
              a switched environment where one host does not necessarily see all the  traffic  on
              the switch.

       -h --hard-capture
              Once  an  IP address has been captured, then do not wait for a "-r" timeout for the
              next incoming ARP request.

       -x --disable-capture
              Do not capture IPs.

       -X --exclude-resolvable-ips
              On startup, attempt  DNS  resolution  on  all  IPs  within  the  capture  netblock.
              Automatically  exclude any IP that has a corresponding entry in the DNS. Be careful
              because this can generate a lot of DNS lookups if the capture subnet is large.

       -P --persist-mode-only
              Try to limit bandwidth use by doing only persist capturing.  Note:  This  parameter
              has limited usefulness since below max b/w, the same exchange that leads to persist
              capture also has the side effect of tarpitting.

       -a --no-resp-synack
              By default, the LaBrea virtual hosts respond to SYN/ACK with RST, and answer Pings.
              Disables this behaviour.

       -H --auto-hard-capture
              Mark  all  non-excluded  and  all  non-hardexcluded IPs as being hard captured. See
              labrea.conf(5) for more information. This parameter should be used with caution.

       -f --no-resp-excluded-ports
              Drop incoming connections to excluded ports. Normal default behaviour is to  return
              a RST. Makes nmap-style scanning go much slower.

       --no-arp-sweep
              On  startup,  labrea  sweeps  the  capture subnet with bursts of ARP requests in an
              attempt to locate all live machines. This parameter disables the sweep.

       --init-file file
              Read the configuration  from  the  specified  file  instead  of  from  the  default
              location.

       -F --bpf-file file
              Designates the name of a file containing a BPF filter pointing to machines/ports to
              be tarpitted.  As with the command line  BPF  filter,  these  connections  MUST  be
              firewalled to DROP inbound traffic.

       -T --dry-run
              Do  labrea initialization, including Dns excludes, parse of the configuration file,
              opening the network interface etc. Print diagnostic information, then exit.

       -d --foreground
              Do not detach the process. (Unix systems only)

       -o --log-to-stdout
              Send log information to stdout rather than to syslog.  This option also implies and
              sets the -d option (i.e. do not detach process).

       -O --log-timestamp-epoch
              Same  as  the  "-o"  option, but with time output in seconds since epoch to make it
              easier for logfile analysis programs.

       -l --log-to-syslog
              Send log messages to syslog.

       -b --log-bandwidth
              Log a message every minute detailing the current bandwidth consumption  of  the  -p
              option (persist capture).

       -v --verbose
              Increase the verbosity of log messages. Use twice for more effect.

       -q --quiet
              Do not report arp requests for IPs that are not in the capture subnet.

       -z --no-nag
              Turn  off  the nag message. Before you do this, read the basic warning in the Notes
              section just below.

       -? --usage --help
              Print a help message and then exit.

       -V --version
              Print version information and exit.

       -I --ip-addr nnn.nnn.nnn.nnn
              Manually specify the IP address for the labrea server.

       -E --my-mac-addr xx:xx:xx:xx:xx:xx
              Manually specify the MAC address of the labrea server's NIC.

       -D --list-interfaces
              On Windows systems, print the list of WinPcap devices, followed by the list of  the
              libdnet  interfaces.  Note  that  each  API  has  a  different nomenclature for the
              underlying NIC.

       -j --winpcap-dev nn
              On windows systems, select the nth winpcap device in the list.

NOTES

   Basic Warning about use of labrea
       You must understand this: As a  default,  LaBrea  captures  IP  addresses  by  creating  a
       "virtual  machine"  that  sits  on  any  UNUSED  IP  address that it sees. labrea has been
       carefully written and tested to transparently and peacefully operate in normal  production
       environments but ...

       There  is  a  potential  for  problems  if  someone  decides  to start using one of the IP
       addresses that labrea has laid claim to, or if  labrea  erroneously  decides  that  an  IP
       address is free when in fact a real machine is already there.

   Built-in protections
       labrea tries very hard to NEVER capture an IP that has a live machine sitting on it.

       The following automatic mechanisms are provided:

              •      If  labrea sees a gratuitous ARP signalling the arrival of a new machine, it
                     marks the corresponding IP address as excluded. ("new  kids  on  the  block"
                     logic)

              •      Each  ARP  response  is  noted and the corresponding IP address is marked as
                     excluded.

              •      At startup, a systematic sweep is done of the entire capture subnet (as long
                     as  the  subnet is not too big). All IP addresses that respond are marked as
                     excluded.

       Then there are ways of  manually  specifying  the  exclusion  of  certain  addresses,  and
       otherwise ensuring safe operation:

              •      The  EXC  config  stmt allows specified IP addresses to be manually excluded
                     from capture.

              •      The IPI config stmt causes packets with the specified IP source  address(es)
                     to be ignored.

              •      -s  --switch-safe  parameter  causes mirroring of ARP requests in a switched
                     environment

              •      -X  --exclude-resolvable-ips  says  to  exclude  all   IPs   that   have   a
                     corresponding Dns entry

       Traffic  rerouting:  Despite  all  this,  if  labrea  somehow  receives  traffic  whose IP
       destination address belongs to a live machine, labrea will reroute  that  traffic  to  the
       real machine.

   Size of the capture subnet
       It  is  best  to limit the capture subnet to the actual physical segment (VLAN, hub) where
       labrea is running.

       In some configurations, where proxy arp is being  used  to  determine  routing,  interface
       subnet  masks  can be quite large. (i.e. the "whole" network is "directly" attached to the
       physical segment).

       In this case, if labrea picks up the subnet mask from  the  interface,  then  labrea  will
       inefficiently watch addresses that it has no hope of capturing. You should use the -m / -n
       parameters to manually limit the size of the capture subnet.

   Other usage notes
       The labrea virtual machines use a bogus MAC address of 0:0:f:ff:ff:ff

       On certain older Windows systems, it may be necessary  to  manually  specify  the  capture
              subnet.

       On unix systems, KILL -USR1 will toggle logging off on and off.

       On unix systems, KILL -HUP will cause labrea to reinitialize (and thus free captured IPs).

       If  the capture subnet is too large (greater than 1024 addresses), then labrea will not do
              an arp sweep.

BUGS

       On some systems, if there is absolutely no  traffic  to  sniff,  pcap_dispatch  will  wait
              instead  of timing out, making the program seem unresponsive. (Workaround: ping the
              labrea server to "wake" it up.)

       If --exclude-resolvable-ips is enabled, and if the capture subnet is large  (say  class  A
              /8), then a LOT of traffic will be generated to the Dns server.

EXAMPLES

       1)     Run  safely  in  a switched environment with very verbose logging. Don't respond to
              excluded ports. Log bandwidth usage from persist capturing. Exclude  all  IPs  that
              are in the Dns. Run in the foreground, and log to stdout. Maximum capture bandwidth
              is 2 MB/sec. Use toto.conf as the initialisation file. Use  network  device  "eth1"
              instead  of  the default device. Do a test run only - parse input, initialize, then
              exit.

              labrea --switch-safe --verbose -v  --no-resp-excluded-ports
                 --log-bandwidth --exclude-resolvable-ips --foreground
                 --log-to-stdout --max-rate 2000000 --init-file toto.conf
                 --device eth1 -z --dry-run
                 (one line)

       2)     Same thing with the short parameter style.

              labrea -z -s -v -v -f -b -X -d -o -p 2000000
                 --init-file toto.conf -i eth1 -T
                 (one line)

FILES

       /usr/local/etc/labrea.conf
              Default configuration file

       /usr/local/sbin/labrea
              Program

SEE ALSO

       labrea.conf(5)

AUTHOR

       Tom    Liston    <tliston@hackbusters.net>    Bugs:    lorgor@users.sourceforge.net     or
       http://labrea.sourceforge.net

                                                                                        LABREA(1)