Ubuntu Manpage: labrea - Honeypot for incoming IP connection attempts

Provided by: labrea_2.5-stable-3build1_amd64

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

AUTHOR

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

                                                                                        LABREA(1)