LaBrea - The Tarpit ******************** *** INTRODUCTION *** ******************** LaBrea is a program that creates a tarpit or, as some have called it, a "sticky honeypot". LaBrea takes over unused IP addresses on a network and creates "virtual machines" that answer to connection attempts. LaBrea answers those connection attempts in a way that causes the machine at the other end to get "stuck", sometimes for a very long time. --- --- How does it work? --- LaBrea works by watching ARP requests and replies. When the pgm sees consecutive ARP requests spaced several seconds apart, without any intervening ARP reply, it assumes that the IP in question is unoccupied. It then "creates" an ARP reply with a bogus MAC address, and fires it back to the requester. An example (from a tcpdump of LaBrea running on my network): 14:18:28.832187 ARP who-has xx.xx.xx.13 tell xx.xx.xx.1 14:18:29.646402 ARP who-has xx.xx.xx.13 tell xx.xx.xx.1 14:18:31.707295 ARP who-has xx.xx.xx.13 tell xx.xx.xx.1 14:18:31.707574 ARP reply xx.xx.xx.13 is-at 0:0:f:ff:ff:ff There is no xx.xx.xx.13 machine on my network. In this case, the timeout was set to 3 seconds (it's a command line parameter), and when that final "who-has" came in, the "is-at" reply that you see was generated by LaBrea. There isn't a MAC address of 0:0:f:ff:ff:ff either. It doesn't exist. But now, the router (xx.xx.xx.1) believes that there some machine at xx.xx.xx.13, and that it resides on the MAC address 0:0:f:ff:ff:ff, and so it dutifully sends packets on. In essence, we've created a "virtual machine" on that IP address. Now, LaBrea also watches for TCP traffic destined for the ether address 0:0:f:ff:ff:ff. When it sees an inbound TCP SYN packet, it replies with a SYN/ACK that "tarpits" that connection attempt. Everything else is ignored. (Well... sort of. LaBrea also tries to give its "virtual machines" some character... you can ping them, and they respond to a SYN/ACK with a RST...) There's more to it than that (obviously...) but you'll need to read further. ************************ *** How do I run it? *** ************************ Glad you asked! The short answer: Usage: LaBrea The long answer: --------------------------------------------- -- Interfaces / IP address / Netmask / BPF -- --------------------------------------------- --device (-i) interface : Set a non-default interface If your machine has more than one interface, and LaBrea choses the "wrong" one, you can use this option to direct it to the correct one. Use a device name ("eth0") as a parameter. On Windows, you can use the "-D" parameter to see the list of interfaces is recognized. --quiet (-q) : Do not report odd (out of netblock) ARPs If you have two netblocks, with non-contiguous addresses, LaBrea will complain about seeing ARPs that it believes it shouldn't see. This will tell it to "be quiet." --bpf-file (-F) filename : Specify a BPF filter filename Designates the name of a file containing a BPF filter pointing to machines/ports to add to the tarpit. Note that connections specified by the BPF filter will also be tarpitted. As with the command line BPF filter, these connections MUST be firewalled to DROP inbound traffic or this won't work! --mask (-m) mmm.mmm.mmm.mmm : User specified netmask --network (-n) nnn.nnn.nnn.nnn[/nn] : User specified network number Normally LaBrea picks up information from the interface in order to determine the capture subnet. Sometimes you might run LaBrea on an unconfigured interface (one without an assigned IP address). In this case, you'll have to provide the "netmask" and the "network number" for the capture subnet. The "n" parameter accepts a CIDR-format address. So the class C subnet 192.168.99.xx could be specified as: -n 192.168.99.33/24 or as: -n 192.168.99.33 -m 255.255.255.0 Note: KNOW WHAT YOU'RE DOING. If these numbers are not correct, BAD THINGS may happen. --my-ip-addr (-I) nnn.nnn.nnn.nnn : Specify system's IP address --my-mac-addr (-E) xx:xx:xx:xx:xx:xx : Specify system's MAC address LaBrea needs to know the NIC's (Network Interface Card) IP and MAC addresses. This information is used to construct the ARPs that LaBrea uses to determine if an IP address is occupied or not. On certain systems (e.g. old Win98), the API that supports the libdnet intf rtn is not installed. So you have to specify the system IP and MAC address yourself. If you specify one, then you have to specify the other. You will also have to manually specify the capture subnet information. Note: As mentioned above, be VERY careful when manually specifying this information. If you get it wrong, bad things can happen. -------------------------- -- Tarpitting behaviour -- -------------------------- --throttle-size (-t) datasize : Set connection throttling size in bytes Since you're "inviting" the scanners in, you might as well place some restrictions on them. This option sets the TCP window advertisement to limit the amount of data sent by the scanner. The number of data bytes to allow per packet is passed as a parameter. Default value is 10 unless persist mode is used. With persist mode, defualt value is 3. --arp-timeout (-r) rate : Set arp timeout rate in seconds The number of seconds to wait between arp requests before deciding that an IP address is unused. Here is a description of the algorithm used: On an IP by IP basis, we store a time and an originating IP address: 1) When you see an 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, 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. The default timeout is 3 seconds. ------------------ -- IP Capturing -- ------------------ --switch-safe (-s) : "Safe" operation in a switched environment Under a switched environment it is possible for LaBrea to see an ARP request, but not see the resulting ARP reply. LaBrea can still work under these conditions by sending out "mirror" ARP requests of its own. If this parameter is specified, when LaBrea sees an inbound ARP request the pgm sends out a duplicate ARP request for the same IP, with the LaBrea server itself as the target for the reply. --exclude-resolvable-ips (-X) : Automatically exclude resolvable IPs from capture. On startup, this will attempt DNS resolution on all IPs within your netblock, and automatically exclude any that resolve. --disable-capture (-x) : Disable IP capture This instructs LaBrea NOT to capture IPs. --hard-capture (-h) : "Hard" capture IPs The -h option instructs LaBrea that once it captures an IP address, it needn't wait for a "-r" timeout the next time it sees an Arp request for this IP. IPs are "hard" captured. See the section on the configuration file for further information. --soft-restart (-R) : Wait while recapturing active connects "Soft Restart" mode. What this does is to hold off on any new attempt to force incoming sessions into the "persist" state for 5 minutes. This lets things settle down and gets the bandwidth calculations going. Note that during this period, IPs will still be captured, pings will still be responded to (if specified), etc. After I changed some stuff in LaBrea, I thought I would be tricky and restart LaBrea quickly so I could keep hold of the connections I had already trapped. And lo, one of the dogs of the internet chose that moment to hit me with a scan. LaBrea didn't have enough information for correctly calculating bandwidth yet, so I ended up with *WAY* too many connections. "Soft restart" mode prevents this from happening. --auto-hard-capture (-H) : Automatically hard capture addresses not excluded. This marks all non-excluded and all non-hardexcluded IPs as being hard captured. Use CAREFULLY. ------------------------------ -- Persistent state capture -- ------------------------------ --max-rate (-p) maxrate : "Persist" state capture connect attempts LaBrea will permanently capture connect attempts within the limit of the maximum data rate specified (in Kbits/sec). This value is expressed in KiloBytes/Sec. (This is a change from previous versions.) This is UNBELIEVABLY COOL (if I do say so myself...) If you specify this flag and a maximum bandwidth, several things will happen. First of all, this forces data throttling to 3 bytes (see the "-t" option above). Then, when a connection is attempted, LaBrea will force the connection into what is known as "persist" state. In persist state, the connection NEVER times out. You'll literally hang onto the scanning thread until you stop or they stop. Running unchecked, this could have a detrimental effect on your bandwidth, so LaBrea will make every effort to limit itself to the maximum bandwidth that you specify (in Kb/sec). If it can't capture a connection, LaBrea will still tarpit it. Note: It'll stay pretty NEAR your MAXBW number... YMMV. --log-bandwidth (-b) : Log bandwidth usage to syslog This will send an update on the current bandwidth being consumed by the -p option to the log every minute. If you're interested... (Note: it'll only work if you have -p enabled. Duh...) --persist-mode-only (-P) : Persist mode capture only. Persist mode capture only. This tries to limit bandwidth by only persist capturing. When we're at full bandwidth, standard tarpitting won't happen, but because the same "conversation" that leads to persist capture also has the side-effect of tarpitting, when we're below our set bandwidth, it's not really effective. (It was easy to do though...) ------------------------------- -- Virtual machine behaviour -- ------------------------------- --no-resp-synack (-a) : Do not respond to SYN/ACKs and PINGs By default, LaBrea's "virtual machines" will respond to a SYN/ACK packet with a RST. This is nice behavior, because it makes it difficult for people to use your empty IP addresses to "spoof". The virtual machine will also respond to a ping, which acts as an invitation to anything that preceeds a scan with a ping to see if the target exists. Like say... NMap, or most worms. If you DON'T want this behavior, use the "-a" option to disable it. --no-resp-excluded-ports (-f) : "Firewall" excluded ports. The -f parameter says to "firewall" excluded ports. With this option, excluded ports will act as if they were firewalled to DROP inbound connections. The result is that nmap scans of LaBrea virtual machines in the capture subnet will take a long time. This discourages hacking activity while at the same time generating log entries that warn you of the activity. LaBrea is automatically configured to always respond to the "usual" hacking ports. Also, if there is enough activity on some other port, then the virtual machines will adjust by starting to respond to incoming connections on this new port. ---------------------------- Before giving the detailed explanation, first some definitions: a) A standard port is one that LaBrea always responds to. These ports are the ones that hackers and worms look for (e.g. telnet, http, ftp, etc). See ctl.c for the complete list. b) An excluded port is one that has been configured as such in the configuration file. Even a standard port can be forced to be excluded. c) A dynamic port is one that is neither standard, nor excluded. ---------------------------- When "-f" is specified, LaBrea behaves as follows: 1) Excluded ports will do not respond at all (DROP). 2) Activity on a standard port will be handled as usual (i.e. tarpitting, persist mode) 3) If LaBrea sees activity on a dynamic port, then it starts counting the number of SYNs received (ie incoming connections). When there is enough activity on the port, then LaBrea will start responding to incoming connects: a) If SYN count is less than 6, then drop the incoming connection, but increment the counter by 1. b) If SYN count is 6 or more, then respond to the incoming connection (tarpitting / persist mode). 4) Every 15 minutes, all port counts < 255 are reduced by one to eliminate the effect of SYN "noise". However, once a port count reaches 255, the port will always respond to incoming SYNs. --no-arp-sweep : Don't perform initial arp sweep of capture subnet LaBrea has a number of safety mechanisms built-in to avoid causing problems with its virtual machines. By default, LaBrea will do an arp sweep of the capture subnet in order to detect IPs that are already occupied by active machines. Arps are generated in bursts of 85 at 2 minute intervals. However if the capture subnet is too large (>1024 addresses), then a warning message is given, and the arp sweep is turned off. Specifying this parameter means that LaBrea will not do the initial arp sweep. -------------- -- Logging --- -------------- --log-to-syslog (-l) : Log activity to syslog Sends all messages to system syslog once the initialisation is completed. This is the default behaviour on Unix systems. --verbose (-v) : Verbosely log activity to syslog Log all IPs "captured", IPs "teergrubed", plus all activity from the "teergrubed" hosts. Specify twice for more effect. --log-to-stdout (-o) : Output to stdout instead of syslog This sends log information to stdout rather than to syslog. This option also implies and sets the -d option (Do NOT detach process). Yes, I know... LaBrea is chatty and dumps a whole lot of stuff into syslog. This gives you the option to have LaBrea log information go to stdout instead. "-o" is the default behaviour on Windows systems. --log-timestamp-epoch (-O) : Same as -o w/time output in seconds since epoch The same as the "-o" option, but formats the time stamp differently to make it easier for other "logfile analysis" programs to parse it. --version (-V) : Print version information and exit --------------------------------- -- Windows-specific parameters -- --------------------------------- ==> Note that on Windows systems, messages are sent by default to stdout. Also LaBrea is not yet able to detach itself and run as a standalone Windows service. ==> The following parameters are specific to Windows systems only: --list-interfaces (-D) : List available interfaces LaBrea uses two different APIs to interact with the NIC (network card): libdnet and WinPcap. The libdnet intf API is used to extract information from the NIC and to generate packets. The WinPcap API is used to sniff. Unfortunately, these two APIs have different nomenclatures for the same underlying NIC. Specifying this parameter causes LaBrea to generate the list of available interfaces. Both the WinPcap and the libdnet device lists are given. In each list, the interface by default is indicated. You get to pick an interface from each list if the defaults are not right. Use the "-i" parameter (see above) to pick the libdnet interface. See the following parameter for the WinPcap device. --winpcap-dev (-j) nn : Specify WinPcap device The WinPcap device driver is used for packet sniffing. By default, the first device in the WinPcap list is the one that is used. The "-j" parameter can be used to specify another entry in the list. For instance, "-j 2" says to use the 2cd entry in the WinPcap device driver list. ---------------------------- Note: It is ESSENTIAL that the -j and -i parameters specify the SAME physical interface (NIC). --syslog-server nnn.nnn.nnn.nnn : Specify address of remote syslog server --syslog-port nnn : Specify port to be used for remote syslog On Windows systems, LaBrea offers syslog support. For Windows NT and up, log messages will be sent to the local Windows Application Event log if the "-l" parameter is specified. However, when "--syslog-server" is specified as well, then the pgm will send log messages to a remote syslog server. This will work even on Windows 98 or ME systems. Finally, if the remote syslog doesn't open for some reason, then LaBrea will fail over to the local application Event log. -------------------------------- -- Special modes of operation -- -------------------------------- --dry-run (-T) : Test mode - Prints out debug info but DOES NOT RUN Test mode. If you're having trouble, try this first and see if LaBrea is picking up the information on your adapter, netblock, netmask, etc... correctly. This prints diagnostic information and then exits. --foreground (-d) : Do NOT detach process. Some people want to run LaBrea under the control of another process. This keeps LaBrea from detaching and running as a daemon. This is the default (only!) behaviour on Windows systems. --usage --help (-?) : Give help messages --no-nag (-z) : Turn off nag message ==> IMPORTANT ==> Be sure that you read the "Potential Issues" section in the INSTALL documentation before you actually use LaBrea. --init-file filespec : Specify alternative location for the configuration file By default, LaBrea looks for the configuration file as follows: Unix systems /usr/local/etc/labrea.conf Windows systems LaBrea.cfg in the current execution directory The "init-file" parameter can be a full filespec complete with path information. LaBrea will look in the specified location for the configuration file. --debug nn : Produce debugging output If debugging is compiled into LaBrea by specifying: ./configure enable-debugging then this parameter causes the actual production of debug output. See debug.h for an explication of debugging codes. ****************************** *** The Configuration file *** ****************************** This section describes the configuration file. The configuration file contains directives that alter pgm behaviour. ---------------------- -- Some definitions -- ---------------------- First, some definitions. * "Excluded" IPs are those that you DON'T want LaBrea to ever capture. Please note that you don't need to specify "active" IPs (ie those with a live machine sitting on the address). LaBrea won't capture an IP with a machine on it. This is only for empty IPs that you DON'T want captured. * "HardExcluded" IPs are those that you don't want LaBrea to hard capture. This is only necessary with the -h option. --------------------------- -- Specifying directives -- --------------------------- * IP addresses can be specified as either a single address: 192.168.33.99 or as a range of addresses: 192.168.0.1 - 192.168.0.50 * The same thing holds for ports and ranges of ports: 22 33-55 * The configuration file consists of lines with two parts: An IP or Port (or and IP range or Port range) followed by a "tag". For example: 192.168.0.1-192.168.0.50 exclude Blank lines are ignored as are lines starting with "#". ------------------------------ -- Configuration statements -- ------------------------------ LaBrea recognizes the following "tags": exclude - This applies to local IP addresses. This means that LaBrea is to never "capture" or "take-over" this IP address. hardexclude - Again, this applies to local IP addresses. This config stmt is only useful if "-h" (hard capture") is specified. This means that LaBrea is to never "hard capture" this address, therefore it must *always* wait for the ARP timeout. If -s is specified, then duplicate arps will be sent each time. ipignore - This can be applied to ANY IP address. This keeps LaBrea from tarpitting or persist capturing connection attempts from this IP. Note that ipignore takes a CIDR format address specification (instead of a range of addresses): nnn.nnn.nnn.nnn[/mm] portignore - Port 1 - 65535. This keeps LaBrea from tarpitting or persist capturing any connection attempts against this port. pmn - "Port monitor". This config stmt is only useful if -f (firewalling) is specified. It tells LaBrea to treat these ports as "standard" ports. In other words, LaBrea is always to respond to connections on these ports. ------------------------------- -- Sample configuration file -- ------------------------------- Let's suppose that LaBrea is started with -f (firewalling) and -h (hard capture). Here then is a sample configuration file: # # Ignore packets from IP 192.168.0.94 # 192.168.0.94 exclude # # Ignore packets from the IP address range 192.168.0.1 to 50 # 192.168.0.1-192.168.0.50 exclude # # Always wait for the arp timeout for the address 192.168.0.55 # 192.168.0.55 hardexclude # # Ignore connection attempts from the class C subnet # 123.45.67.89 # 123.45.67.89/24 ipignore # # Ignore connection attempts for the port range 121-180 # 121-180 portignore # # But still respond to port 155 (in the middle of this interval) 155 pmn ************************* *** SIGNAL PROCESSING *** ************************* If LaBrea is running in daemon mode (supported only on Unix), then it will respond to various signals. SIGHUP: LaBrea will redo the initialisation. This means in practice that you can "let go" of someone by putting the correct entry in the configuration file and then issuing a SIGHUP. SIGUSR1: This toggles logging as follows: If logging was not enabled at start this sets the '-l' flag If logging (-l | -v) is set this saves the value and turns off logging If logging is presently toggled off it restores the saved level (-l | -v) -- PCAP Dispatcher loop processing -- On some systems, the libpcap code will not time out unless there is activity on the network interface. So this means that on a really quiet network, you might have to ping the LaBrea server to get it to notice that you just did a kill -HUP or kill -USR1. The upside of this is the PCAP loop is more efficient. *************************** *** LaBrea runs as root *** *************************** If you have a message on Unix such as: "labrea: *** Couldn't open pcap device for sniffing" or on Windows you find that "labrea -D" doesn't list the interfaces, then be aware of the following: ==> On unix, LaBrea must run as root ==> On Windows NT and later, LaBrea needs admin privileges ************************************************ *** And now a few words from the sponsor ... *** ************************************************ --- --- Why did you write it? --- The original concept for LaBrea started in response to the CodeRed worm. Our IP block was being scanned non-stop. I began to wonder: "Is there anything that can be done to stop this worm?" Of course, many things came to mind, but most of them were illegal. Then, late one night, I thought, "Maybe I can't stop these machines from scanning, but I bet I can slow them down..." The following morning I posted to the INTRUSIONS list at incidents.org: "I'm pretty sure that most of you are using your allotted ip address space somewhat like I am. At any given time I'm using only about 20-30% of the ip addresses that I have available. What if I could put something on those other 80% of my ip addresses that would give "Code Red" something to play with that would slow it down to a crawl? A sort of "DoS" back at the worm. Since those "extra" ip addresses aren't actually expecting any inbound traffic, anything fired at them can safely be assumed to be "bad" traffic. If I wrote a little piece of software that sat on those ip's and listened on port 80, anything that it heard could safely be "played" with. My hypothetical program should be pretty simple: you see an inbound packet at port 80 with SYN set, and you craft up a return packet with SYN/ACK set and perhaps an option to set the MSS to something small... say about 60 bytes. What does that do? Well, as far as the attacking worm is concerned, after replying with an ACK, it has completed a three-way handshake... it's connected. It's also been told to send information back to you in small chunks (to keep traffic to a minimum), which it dutifully does. The only problem is, my program just answers SYN packets and ignores everything else. So now the worm has to sit around while the whole TCP connection times out. I'm not sure what the timeout NT is, but I think most stacks are pretty persistent about "good" connections, so it should hang it up for a good long time." A few days later, Mihnea Stoenescu sent a message back to the list: "Tom's concept works - I have a living proof. For a few hours I've been teergrubing CodeReds via three-way handshake on behalf of an entire C-block, by using only one host. At a rate of 6 hosts per minute hitting my block, I'm consuming circa 15 minutes of effective attack time every minute. A lot of hosts can be scanned in 15 minutes." Mihnea used a modified version of a program called Couic. But Couic was written to do a lot more, so I went though, hacked it apart, and put it back together to make "CodeRedneck." CodeRedneck did essentially what I described in my post, but it only worked on "real" connections that had some kind of firewalling that kept the underlying machines from responding. It did nothing for all of those "unused IPs". After CodeRedneck was done, I began trying to figure out how to deal with those unused IPs. Somehow I had to "create" machines, and my first thought was to use IP aliasing under Linux. Using the Trinux distribution I was able to put together a boot disk that, using a list of unused IPs, "created" new machines, then firewalled and "tarpitted" them. I called the new version "LaBrea". The day after I released LaBrea, someone asked if it would be able to handle a /24 network (65,535 hosts). Well, I didn't think my little program would handle it, and, well... it didn't. And so... I tried again. That's how this new version of LaBrea came into being... --- --- Why should I run it? --- If you're a network administrator, I don't REALLY need to explain this. They're out there, every day... 24/7/365. The scanners. They're out there and you get to sit and watch them beat on your network, doing reconnissance. Now you have a chance to make their life more difficult. Besides that... it's fun. And, as Mihnea so wonderfully put it, you can come into work in the morning, look at your logfiles and say "Wow - I'm *actually* saving the world" OK, maybe "saving the world" is a little much... --- --- I still don't get it! --- Try http://labrea.sourceforge.net. There's a mailing list there for users to ask questions among other things. To report bugs: Use the SourceForge Tracker at http://labrea.sourceforge.net to report bugs or email lorgor@users.sourceforge.net. Comments, hate mail, and praise can be directed to tliston@hackbusters.net --- --- Legalese --- This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. --- --- Acknowledgements --- I couldn't have written this without the patience and help of a number of people- The beta testers who put up with my constant tinkering: Barton Bruce, Ben Curran, Andrew Daviel, Bill Dodd, Becky Pinkard, and Micropterus Salmoides. Tim Rushing who came to my rescue and offered to host the website when the downloads of the original LaBrea boot disk were too much for my connection to handle. Matt Franz for putting together the Trinux package. Mihnea Stoenescu for proving it would actually work. Many thanks to Rick Downes of Radsoft (http://www.radsoft.net) for all his help and encouragement. If you deal with any type of Windows environment and you haven't checked out Radsoft's Extreme Power Tools, you really, REALLY should. Thanks also to Rob Rosenberger of VMyths (http://www.vmyths.com) for his advice and assistance. And a very special thanks to Donald Smith for putting up with LOTS of questions (and actually answering most of them) and for letting me bounce ideas off him. $Id: README,v 1.2 2003/09/12 21:23:39 lorgor Exp $