File: README

package info (click to toggle)
labrea 2.5-stable-3
  • links: PTS
  • area: main
  • in suites: bullseye, buster, jessie, jessie-kfreebsd, lenny, sid, squeeze, stretch, wheezy
  • size: 984 kB
  • ctags: 590
  • sloc: ansic: 5,604; sh: 3,247; makefile: 77
file content (913 lines) | stat: -rw-r--r-- 31,175 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
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 <options> <BPF filter>



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 $