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