1LABREA(1) General Commands Manual LABREA(1)
2
6 labrea - Honeypot for incoming IP connection attempts
7
9 labrea [-i --device INTERFACE] [-n --network nnn.nnn.nnn.nnn[/nn]] [-m
10 --mask nnn.nnn.nnn.nnn] [-t --throttle-size BYTES] [-p --max-rate RATE
11 ] [-R --soft-restart] [-r --arp-timeout RATE] [-s --switch-safe] [-h
12 --hard-capture] [-x --disable-capture] [-X --exclude-resolvable-ips]
13 [-P --persist-mode-only] [-a --no-resp-synack] [-H --auto-hard-capture]
14 [-f --no-resp-excluded-ports] [--no-arp-sweep] [--init-file FILE] [-F
15 --bpf-file FILE] [-T --dry-run] [-d --foreground] [-o --log-to-stdout]
16 [-O --log-timestamp-epoch] [-l --log-to-syslog] [-b --log-bandwidth]
17 [-v --verbose] [-q --quiet] [-z --no-nag] [-? --usage --help ] [-V
18 --version] [-I --ip-addr nnn.nnn.nnn.nnn] [-E --my-mac-addr
19 xx:xx:xx:xx:xx:xx] [-D --list-interfaces] [-j --winpcap-dev nn] [--sys‐
20 log-server nnn.nnn.nnn.nnn] [--syslog-port nnn]
21 [BPF Filter]
23
25 labrea creates virtual machines for unused IP addresses in the speci‐
26 fied block of IP addresses. LaBrea sits and listens for ARP "who-has"
27 requests.
28 When an ARP request for a particular IP goes unanswered for longer than
30 its "rate" setting (default: 3 seconds), labrea crafts an ARP reply
31 that routes all traffic destined for the IP to a "bogus" MAC address.
32 labrea sniffs for TCP/IP traffic sent to that MAC address and then
33 responds to any SYN packet with a SYN/ACK packet that it creates.
34
36 labrea accepts the following options:
37 -i --device interface
39 By default, labrea uses the first ethernet interface. This
40 forces labrea to use the specified interface.
41 -n --network xxx.xxx.xxx.xxx[/nn]
43 labrea normally pulls information about the netblock from the IP
44 information assigned to the interface. If labrea is run on an
45 unconfigured interface (one without an assigned IP address),
46 then use this option to specify the subnet to be captured.
47 xxx.xxx.xxx.xxx is the network address. /nn is the subnet mask
49 in CIDR notation. If the subnet mask is not specified here, then
50 you must include the -m parameter.
51 -m --mask xxx.xxx.xxx.xxx
53 Another way to specify the network mask for the capture net‐
54 block. If this parameter is specified, then the -n parameter
55 must also be specified.
56 -t --throttle-size nn
58 Sets the TCP window advertisement to limit the amount of data
59 sent to labrea. The number of data bytes to allow per packet is
60 nn bytes.
61 -p --max-rate rate
63 Connect attempts will be permanently captured by forcing the
64 connection into a "persist" state (by closing the TCP window).
65 In this state, the connection will not time out. labrea will
66 permanently capture connect attempts up to maximum bandwidth
67 rate bytes. If the specified bandwidth is exceeded, labrea will
68 still tarpit the incoming connection (ie respond SYN/ACK to
69 incoming SYN).
70 -R --soft-restart
72 New captures will be held off for 5 minutes to let bandwidth
73 calculations progress. If a major scan hits just after startup,
74 this prevents labrea from capturing too many connections.
75 -r --arp-timeout rate
77 Wait rate seconds after seeing incoming arp requests before cap‐
78 turing an IP address.
79 -s --switch-safe
81 When there is an incoming ARP request, specifies that labrea
82 should send out an ARP request of its own for the same IP
83 address. This is necessary for safe operation in a switched
84 environment where one host does not necessarily see all the
85 traffic on the switch.
86 -h --hard-capture
88 Once an IP address has been captured, then do not wait for a
89 "-r" timeout for the next incoming ARP request.
90 -x --disable-capture
92 Do not capture IPs.
93 -X --exclude-resolvable-ips
95 On startup, attempt DNS resolution on all IPs within the capture
96 netblock. Automatically exclude any IP that has a corresponding
97 entry in the DNS. Be careful because this can generate a lot of
98 DNS lookups if the capture subnet is large.
99 -P --persist-mode-only
101 Try to limit bandwidth use by doing only persist capturing.
102 Note: This parameter has limited usefulness since below max b/w,
103 the same exchange that leads to persist capture also has the
104 side effect of tarpitting.
105 -a --no-resp-synack
107 By default, the LaBrea virtual hosts respond to SYN/ACK with
108 RST, and answer Pings. Disables this behaviour.
109 -H --auto-hard-capture
111 Mark all non-excluded and all non-hardexcluded IPs as being hard
112 captured. See labrea.conf(5) for more information. This parame‐
113 ter should be used with caution.
114 -f --no-resp-excluded-ports
116 Drop incoming connections to excluded ports. Normal default be‐
117 haviour is to return a RST. Makes nmap-style scanning go much
118 slower.
119 --no-arp-sweep
121 On startup, labrea sweeps the capture subnet with bursts of ARP
122 requests in an attempt to locate all live machines. This parame‐
123 ter disables the sweep.
124 --init-file file
126 Read the configuration from the specified file instead of from
127 the default location.
128 -F --bpf-file file
130 Designates the name of a file containing a BPF filter pointing
131 to machines/ports to be tarpitted. As with the command line BPF
132 filter, these connections MUST be firewalled to DROP inbound
133 traffic.
134 -T --dry-run
136 Do labrea initialization, including Dns excludes, parse of the
137 configuration file, opening the network interface etc. Print
138 diagnostic information, then exit.
139 -d --foreground
141 Do not detach the process. (Unix systems only)
142 -o --log-to-stdout
144 Send log information to stdout rather than to syslog. This
145 option also implies and sets the -d option (i.e. do not detach
146 process).
147 -O --log-timestamp-epoch
149 Same as the "-o" option, but with time output in seconds since
150 epoch to make it easier for logfile analysis programs.
151 -l --log-to-syslog
153 Send log messages to syslog.
154 -b --log-bandwidth
156 Log a message every minute detailing the current bandwidth con‐
157 sumption of the -p option (persist capture).
158 -v --verbose
160 Increase the verbosity of log messages. Use twice for more
161 effect.
162 -q --quiet
164 Do not report arp requests for IPs that are not in the capture
165 subnet.
166 -z --no-nag
168 Turn off the nag message. Before you do this, read the basic
169 warning in the Notes section just below.
170 -? --usage --help
172 Print a help message and then exit.
173 -V --version
175 Print version information and exit.
176 -I --ip-addr nnn.nnn.nnn.nnn
178 Manually specify the IP address for the labrea server.
179 -E --my-mac-addr xx:xx:xx:xx:xx:xx
181 Manually specify the MAC address of the labrea server's NIC.
182 -D --list-interfaces
184 On Windows systems, print the list of WinPcap devices, followed
185 by the list of the libdnet interfaces. Note that each API has a
186 different nomenclature for the underlying NIC.
187 -j --winpcap-dev nn
189 On windows systems, select the nth winpcap device in the list.
190
192 Basic Warning about use of labrea
193 You must understand this: As a default, LaBrea captures IP addresses by
194 creating a "virtual machine" that sits on any UNUSED IP address that it
195 sees. labrea has been carefully written and tested to transparently and
196 peacefully operate in normal production environments but ...
197 There is a potential for problems if someone decides to start using one
199 of the IP addresses that labrea has laid claim to, or if labrea erro‐
200 neously decides that an IP address is free when in fact a real machine
201 is already there.
202 Built-in protections
204 labrea tries very hard to NEVER capture an IP that has a live machine
205 sitting on it.
206 The following automatic mechanisms are provided:
208 · If labrea sees a gratuitous ARP signalling the arrival of
210 a new machine, it marks the corresponding IP address as
211 excluded. ("new kids on the block" logic)
212 · Each ARP response is noted and the corresponding IP
214 address is marked as excluded.
215 · At startup, a systematic sweep is done of the entire cap‐
217 ture subnet (as long as the subnet is not too big). All
218 IP addresses that respond are marked as excluded.
219 Then there are ways of manually specifying the exclusion of certain
221 addresses, and otherwise ensuring safe operation:
222 · The EXC config stmt allows specified IP addresses to be
224 manually excluded from capture.
225 · The IPI config stmt causes packets with the specified IP
227 source address(es) to be ignored.
228 · -s --switch-safe parameter causes mirroring of ARP
230 requests in a switched environment
231 · -X --exclude-resolvable-ips says to exclude all IPs that
233 have a corresponding Dns entry
234 Traffic rerouting: Despite all this, if labrea somehow receives traffic
236 whose IP destination address belongs to a live machine, labrea will
237 reroute that traffic to the real machine.
238 Size of the capture subnet
240 It is best to limit the capture subnet to the actual physical segment
241 (VLAN, hub) where labrea is running.
242 In some configurations, where proxy arp is being used to determine
244 routing, interface subnet masks can be quite large. (i.e. the "whole"
245 network is "directly" attached to the physical segment).
246 In this case, if labrea picks up the subnet mask from the interface,
248 then labrea will inefficiently watch addresses that it has no hope of
249 capturing. You should use the -m / -n parameters to manually limit the
250 size of the capture subnet.
251 Other usage notes
253 The labrea virtual machines use a bogus MAC address of 0:0:f:ff:ff:ff
254 On certain older Windows systems, it may be necessary to manually spec‐
256 ify the capture subnet.
257 On unix systems, KILL -USR1 will toggle logging off on and off.
259 On unix systems, KILL -HUP will cause labrea to reinitialize (and thus
261 free captured IPs).
262 If the capture subnet is too large (greater than 1024 addresses), then
264 labrea will not do an arp sweep.
265
267 On some systems, if there is absolutely no traffic to sniff, pcap_dis‐
268 patch will wait instead of timing out, making the program seem
269 unresponsive. (Workaround: ping the labrea server to "wake" it
270 up.)
271 If --exclude-resolvable-ips is enabled, and if the capture subnet is
273 large (say class A /8), then a LOT of traffic will be generated
274 to the Dns server.
275
277 1) Run safely in a switched environment with very verbose logging.
278 Don't respond to excluded ports. Log bandwidth usage from per‐
279 sist capturing. Exclude all IPs that are in the Dns. Run in the
280 foreground, and log to stdout. Maximum capture bandwidth is 2
281 MB/sec. Use toto.conf as the initialisation file. Use network
282 device "eth1" instead of the default device. Do a test run only
283 - parse input, initialize, then exit.
284 labrea --switch-safe --verbose -v --no-resp-excluded-ports
286 --log-bandwidth --exclude-resolvable-ips --foreground
287 --log-to-stdout --max-rate 2000000 --init-file toto.conf
288 --device eth1 -z --dry-run
289 (one line)
290 2) Same thing with the short parameter style.
292 labrea -z -s -v -v -f -b -X -d -o -p 2000000
294 --init-file toto.conf -i eth1 -T
295 (one line)
296
298 /usr/local/etc/labrea.conf
299 Default configuration file
300 /usr/local/sbin/labrea
302 Program
303
305 labrea.conf(5)
306
308 Tom Liston <tliston@hackbusters.net> Bugs: lorgor@users.sourceforge.net
309 or http://labrea.sourceforge.net
310 LABREA(1)