LaBrea - The Tarpit

IMPORTANT! If you don't want to read this entire document, you MUST at
least read: SECTION 1 (What is it?), SECTION 5 (How do I run it?), and
SECTION 7 (Potential Issues).

** Trinux users should see notes 3,4 for information how to save
** configuration files to the boot floppy

SECTION 1 - What is it?

 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.

SECTION 2 - 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 /16 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...

SECTION 3 - 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...

SECTION 4 - How does it work?

 This new version works by watching ARP requests and replies.  When it
 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.  This new version 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
 the source code.

SECTION 5 - How do I run it?

 Glad you asked!

 Usage: LaBrea <options> <BPF filter>
 Options:
   -i interface : Set a non-default interface
   -t datasize  : Set connection throttling size in bytes (default 10)
   -r rate      : Set arp timeout rate in seconds (default 3)
   -s           : "Safe" operation in a switched environment
   -l           : Log activity to syslog (Note 8)
   -v           : Verbosely log activity to syslog (Note 8)
   -F filename  : Specify a BPF filter filename (Note 2)
   -h           : "Hard" capture IPs (Note 4)
   -x           : Disable IP capture
   -m           : User specified netmask (Note 1)
   -n           : User specified network number (Note 1)
   -V           : Print version information and exit
   -a           : Do not respond to SYN/ACKs and PINGs (Note 6)
   -q           : Do not report odd (out of netblock) ARPs
   -T           : Test mode - Prints out debug info but DOES NOT RUN
   -R           : Soft restart - Wait while recapturing active connects
   -p maxrate   : "Persist" state capture connect attempts (Note 7)
   -b           : Log bandwidth usage to syslog
   -d           : Do NOT detach process.
   -o           : Output to stdout instead of syslog (Note 9)
 Note 1:
  The network number and netmask are normally loaded from the interface.
  If you're using an interface that has no IP, you'll have to provide BOTH of
 these numbers.  These MUST be correct or BAD things may happen!
 Note 2:
  Connections specified by the BPF filter will also be tarpitted.  These
  connections MUST be firewalled to DROP inbound packets or this won't work!
 Note 3:
  /etc/LaBreaExclude contains a list of IPs (1/line) that you DON'T want LaBrea
  to capture. You don't need to specify "active" IPs.  LaBrea won't capture an
  IP with a machine on it. This is only for empty IPs that you DON'T want
  captured.

** Trinux users should create /etc/tux/pkg/labrea/exclude instead of
** /etc/LaBreaExclude and then type "/etc/init.d/labrea" to create the files
** in /etc. Then type "savecfg" to copy the entire /etc/tux/ directory
** to the boot floppy. Or you can just create the file \tux\pkg\labrea\exclude
** on the boot floppy and it should use the saved config automatically.

 Note 4:
  /etc/LaBreaHardExclude should contain an IP list that you NEVER want LaBrea
  to hard capture.  Only necessary with the -h option.

** Trinux users should create /etc/tux/pkg/labrea/hardexclude instead of
** /etc/LaBreaHardExclude and then type "/etc/init.d/labrea" to create the files
** in /etc. Then type "savecfg" to copy the entire /etc/tux/ directory
** to the boot floppy. Or you can just create the file \tux\pkg\labrea\hardexclude
** on the boot floppy and it should use the saved config automatically.

 Note 5:
  IPs can be specified as either a single address (i.e.: "192.168.0.4") or as a
  range of addresses (i.e.: "192.168.0.1 - 192.168.0.50")
 Note 6:
  By default, LaBrea "virtual machines" respond to an inbound SYN/ACK with a
  RST and are "pingable".  The -a option eliminates this behavior.
 Note 7:
  LaBrea will permanently capture connect attempts within the limit of the
  maximum data rate specified (in bytes/sec).
 Note 8:
  With version 2.0.1+ you can use 'kill -USR1 <LaBrea_PID>' to toggle logging
   If logging was not enabled at start this sets the '-l' flag
   If logging (-l | -v) are set this saves the value and turns off logging
   If logging is presently toggled off it restores the saved level (-l | -v)
 Note 9:
  This sends log information to stdout rather than to syslog.  This option
  also implies and sets the -d option (Do NOT detach process). 


SECTION 6 - What do all of those options do?

 -i   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.

 -t   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 10)

 -r   The number of seconds to wait between arp requests before deciding
      that an IP address is unused.  The exact protocol is:

        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.

 -s   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.  When it sees an inbound ARP request, LaBrea sends out an ARP
      request for the same IP, with itself as the target for the reply.

 -l   Logs the IP addresses of machines that are "teergrubed" (tarpitted)
      to syslog.

 -v   Logs verbosely to syslog.  It logs IPs "captured", IPs "teergrubed",
      and logs all activity from the "teergrubed" hosts.

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

 -h   This instructs LaBrea that once it captures an IP address, it needn't
      wait for a "-r" timeout the next time around.  IPs are "hard" captured.

 -x   This instructs LaBrea NOT to capture IPs.

 -m   Sometimes you might run LaBrea on an unconfigured interface (one without
 -n   an assigned IP address).  Because LaBrea normally pulls information
      about your netblock from the IP information assigned to the interface,
      it is "missing" necessary information in this situation.  You'll need
      to use these options to provide it.  Pass the "netmask" and "network
      number" with these arguments.  Note: KNOW WHAT YOU'RE DOING.
      You pass the numbers in standard form: i.e. "255.255.255.0"

 -V   Just print some version information and exit.

 -a   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".  Also, it will 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.  If you
      DON'T want this behavior, use the "-a" option to disable it.

 -p   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 5 bytes (see the "-t" option above).  Then,
      when a connection is attempted, LaBrea will force the connection into what
      it known as "persist" state.  In persist state, the connection  will NEVER
      time out.  You'll literally hang onto the scanning thread until you stop or
      they stop.  Running unchecked, this could have a very BAD effect on your
      bandwidth, so LaBrea will make every effort to only allow this process to
      take up the maximum bandwidth that you specify (in bytes/second).  If it
      can't capture a connection, LaBrea will still tarpit it.  Note: It'll stay
      pretty NEAR your MAXBW number... YMMV.

 -b   This will send an update on the current bandwidth being consumed by the
      -p option to syslog every minute.  If you're interested...  (Note: it'll
      only work if you have -p enabled.  Duh...)
      
 -
d   Don't detach the LaBrea process. Some people wanted to run LaBrea under 
      the supervision of other processes, so this will keep LaBrea from running 
      in daemon mode.
 
 -o   OK... So LaBrea can be a bit verbose... And some of you want a way to 
      send its output to something to log and display what your tarpit is 
      doing. Fire off LaBrea with this flag set. It won't detach, and all 
      messages that would've gone to syslog will now print to stdout. Send 
      this where YOU want it to go... 

 -R   "Soft restart" mode. If you need to restart LaBrea, and you do it quickly
      enough, you can continue to hang onto many of the connections you've 
      captured. This flag will force LaBrea to wait for five minutes before 
      capturing (-p) anything new. This allows you to continue to hold open any
      connections and get your bandwidth calculations running and acknowledging
      all of those "old" connections before adding anything new.

 -q   Now why would anyone have traffic from mixed netblocks on the same 
      network?? Well, I found out. Mia culpa. This lets you shut up LaBrea's 
      crabbing about "IP address not in netblock". Forgive me... 

 If you keep getting a "you  need  to  read  the  LaBrea.README  file"
 message,  you  need  to read SECTION 7 (Potential Issues) to find out
 what command line parameter you need to get past this.

 LaBrea also uses two files to control its operation:

 /etc/LaBreaExclude - contains a list of IPs (1/line) to exclude from
 LaBrea's attention.  LaBrea won't do anything to these IPs.

 /etc/LaBreaHardExclude - contains a list of IPs that LaBrea won't hard
 capture. (Note: this only makes sense when using the -h option.)

 Note:  IP  address can be specified either as single addresses (i.e.:
 "192.168.0.4") or they  can  be  specified  as  a range of addresses:
 (i.e.:  "192.168.0.1 - 192.168.0.50").

 Additional Note:  LaBrea  SHOULD  never  capture  an  IP  that has an
 active machine sitting on it.  These two files are used to  give  you
 control  over  "empty"  IP  addresses.  That being said, it certainly
 doesn't hurt to "exclude" active IPs.

 Another additional note:  LaBrea  will re-read it's "exclusion" files
 and report packet statistics to syslog when it receives a SIGHUP.

SECTION 7 - Potential Issues

 YOU MUST UNDERSTAND THIS: As a default, LaBrea captures IP addresses.
 That means that LaBrea creates  a  "virtual machine" that sits on any
 UNUSED IP address that it sees.  If you  decide  you  want  to  start
 using one of the IP addresses that LaBrea has laid claim to, THERE IS
 THE  POTENTIAL FOR PROBLEMS.  LaBrea has been written so that it does
 everything it can  to  move  out  of  the  way.   If LaBrea notices a
 machine pop up on one of the IP addresses it is controling,  it  will
 even go so far as to re-route any traffic for that address that comes
 to  its  "bogus"  MAC  to  the  correct  MAC,  until  everything gets
 straightened out.  (Note to purists:  LaBrea does not alter the "ttl"
 field of the forwarded packets when it does this.) Problems may arise
 because there are  things  beyond  LaBrea's  control.   Switches  and
 routers  may feel compelled to tell you when you first attempt to use
 an IP address that it is  already  in  use.  If your switch or router
 does this, there is nothing that LaBrea can do about  it.   Judicious
 use   of   the  "exclusion"  files  can  minimize  problems,  as  can
 reconfiguring the  router  or  switch  to  "timeout"  its  cache more
 quickly, but DON'T BLAME ME!  YOU HAVE BEEN WARNED!

 By the way,  if  you're  version  of  LaBrea  has  been compiled with
 USEZFLAG defined (the default), you'll need to pass it a command line
 parameter of "-z", in addition to any other flags, to get it to run.

 Sorry.  But at least it got you to read the instructions...

SECTION 8 - How to compile

 LaBrea requires both libnet and libpcap to compile.  Other than that,
 it should simply  "make"  with  the  included  Makefile.  It has been
 tested under Linux.  That's all.  If you are successful  at  building
 it on another platform, please let me know!


SECTION 9 - I still don't get it!

 Questions, comments, hate mail, and praise can be directed to
 tliston@hackbusters.net

SECTION 10 - 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.

SECTION 11 - 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.
