================================================================================
=                 Bluefog - Generate Phantom Bluetooth Devices                 =
=                       Tom Nardi (MS3FGX@gmail.com)                           =
================================================================================

Bluefog is able to generate an essentially unlimited number of phantom
Bluetooth devices, useful for testing Bluetooth scanning and monitoring
systems, making it more difficult for attackers to lock onto your devices, or
otherwise complicate the normal operation of Bluetooth devices.

Technically Bluefog can work with just one Bluetooth adapter, but it works much
better when you connect up multiple adapters. Currently Bluefog can support 6
simultaneous Bluetooth radios, but that value may go up as I experiment with
it some more.

--------------------------------------------------------------------------------
- WARNINGS                                                                     -
--------------------------------------------------------------------------------

The changes Bluefog makes to your Bluetooth hardware is supposed to be
temporary, but not all Bluetooth chipsets behave appropriately. During the
development of Bluefog, I managed to permanently delete the MAC address of
my laptop's internal radio. This isn't that big of a deal, but you may want to
keep it in mind.

In addition, I have occasionally found BlueZ to lock up after running Bluefog
with large numbers of Bluetooth radios (4 or more), and indeed, BlueZ in
general doesn't seem to work reliably with multiple radios. If BlueZ starts to
behave oddly after running Bluefog, just reboot and everything should be back
to normal.

--------------------------------------------------------------------------------
- Compatibility                                                                -
--------------------------------------------------------------------------------

To date, Bluefog has only been tested with Bluetooth adapters based on chipsets
from Cambridge Silicon Radio (CSR) and Broadcom. Compatibility reports in
regards to other hardware would be greatly appreciated.

--------------------------------------------------------------------------------
- Installation                                                                 -
--------------------------------------------------------------------------------

To compile Bluefog, simply run the command "make" in this directory. If you get
any message about missing libraries, use your distribution's package manager to
install them. This will let you run Bluefog from the current directory for a
quick test, but not install it to the system.

To actually install Bluefog, use the command "make install". Since this will
install Bluefog to the system directories, you will need to run this as root or
through sudo.

When and if you want to remove Bluefog, you would use the command "make
uninstall". As with "install", this makes changes to the system directories and
will therefore require root permissions.

In addition, if you are upgrading from a previous version, there is also the
command "make upgrade". This will remove any older versions of Bluefog, compile
the new version, and finally install it to the system. As you might have
guessed, this also requires root permissions.

--------------------------------------------------------------------------------
- Usage                                                                        -
--------------------------------------------------------------------------------

As of the current version, Bluefog supports the following options:

-i <interface>
    Allows you to manually select which interface Bluefog uses. Without this
option, Bluefog will automatically detect the first Bluetooth device and use
that.

If you've chosen to use multiple threads, Bluefog will use all devices
available, so this option won't have any effect.

-t <threads>
    With this option you can set how many parallel jobs you want Bluefog to
perform. This number should match however many physical Bluetooth radios your
computer currently has.

The maximum number of threads is currently 6 (which obviously requires 6
separate Bluetooth adapters to be on the system), but may change in the future.

-n <name>
    Usually, Bluefog will chose a random name from the hundreds of names
included with the software. If you use this option however, you can set Bluefog
to use the same custom name for all devices it spoofs. This option is great at
parties.

-d <seconds>
    This determines how many seconds to wait between device spoofs. The minimum
value for this option is 5 seconds, but realistically, anything under 20
probably won't work very well. Default is 30, which is rather slow but at least
has a good shot at working.

-l
    This enables "Loiter Mode", which will randomly slow down the spoofing of
devices. This is used to simulate slow moving targets, rather than a constant
stream. This mode will create a more realistic flow of phantom devices, closer
to what you would expect during real Bluetooth monitoring.

-m
    This option allows you to toggle the randomization of Bluetooth MAC
addresses by Bluefog. Realistically, there isn't much point in randomizing
the device name if you don't change the MAC (as most devices ignore the name
anyway), but I've included the option anyway.

The default is ENABLED, so most people can safely ignore this.

-c
    This option allows you to toggle the randomization of the spoofed device's
class information. If you leave this option off, Bluefog will set all spoofed
device's class to that of a standard smartphone.

-v
    This option allows you to toggle verbose mode. With verbose mode on, you'll
be able to see the hardware being initialized, and see a message in the
terminal every time a new device is spoofed.

--------------------------------------------------------------------------------
- Acknowledgements                                                             -
--------------------------------------------------------------------------------

Bluefog was greatly inspired by "SpoofTooph", written by JP Dunning (.ronin).
In addition to the spiritual support, Bluefog takes a few functions from
SpoofTooph in the areas of class and MAC address randomization, and includes
the data collected by ronin's "Bluetooth Profiling Project".

You can read more about JP Dunning's projects on his site:
http://www.hackfromacave.com/

Bluefog uses quite a bit of code from the "BlueZ" project by Marcel Holtmann,
most notably the majority of bdaddr.c, plus some functions from hciconfig.c.

For more information, check out the official BlueZ site:
http://www.bluez.org/

Bluefog also contains data collected by Brad Haines (RenderMan) during his
recent scans of the West Edmonton Mall in Alberta, Canada.

You can read more about RenderMan's projects on his site:
http://www.renderlab.net/

--------------------------------------------------------------------------------
- License                                                                      -
--------------------------------------------------------------------------------

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License version 2 as published by the Free
Software Foundation.

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.

For details, see the file "COPYING" in the source directory.

--------------------------------------------------------------------------------
- More Info                                                                    -
--------------------------------------------------------------------------------

For more information and updates, please see www.digifail.com