schollz/find3-cli-scanner

The command-line scanner that supports Bluetooth and WiFi

The Framework for Internal Navigation and Discovery (FIND) is like indoor GPS for your house or business, using only a simple smartphone or laptop. This command-line scanner provides a means for your laptop or your computer to monitor the address and signal of nearby WiFi and bluetooth devices (active scanning). Also, if equipped with a monitor-mode enabled WiFI card, you can use the scanner to intercept probe requests to do passive scanning.

This tool should be able to be used on Linux, Windows and OS X. Though, currently only Linux and OS X support bluetooth and passive scanning.

Install

There are a couple of ways to install. I recommend downloading the latest release as that is the easiest way.

Install natively

First make sure you have downloaded Go.

Then, install the dependencies.

Linux

$ sudo apt-get install wireless-tools net-tools libpcap-dev bluetooth

OS X

$ brew install libpcap

Now download and install the scanner with go get:

$ GO111MODULE=on go get -v github.com/schollz/find3-cli-scanner/v3 

If you are on Linux, then you should move it to a path that is available with sudo:

$ sudo mv $GOPATH/bin/find3-cli-scanner /usr/local/bin

That’s it! See below for usage.

Install with Docker

Install Docker:

$ curl -sSL https://get.docker.com | sh

If not using a Raspberry Pi, fetch the latest image.

$ docker pull schollz/find3-cli-scanner

If you are using a Raspberry Pi (armf arch), you need to build the image yourself, although I suggest Raspberry Pi’s just built natively above.

$ wget https://raw.githubusercontent.com/schollz/find3-cli-scanner/master/Dockerfile
$ docker build -t schollz/find3-cli-scanner .

Now you can start the scanning image in the background.

$ docker run --net="host" --privileged --name scanner -d -i -t schollz/find3-cli-scanner

To use the scanner, your syntax will be

$ docker exec scanner sh -c "find3-cli-scanner -device DEVICE -family FAMILY -wifi -bluetooth -forever"

Be sure to use your own device/family name. Use -help to see which flags are available.

You can start/stop the image using

$ docker start scanning
$ docker stop scanning

Note, you can jump inside the image and play if you are curious of trying new things.

$ docker run --net="host" --privileged --name scanning -i -t scanner /bin/bash

Usage

Active scanning

In active scanning the scanner will report the classified location of the device that is doing the scanning.

To use the find3-cli-scanner you must include the name of your interface (typically something like wlan0) with -i. You can determine the name using ifconfig or similar command.

You must also include a family name with -family and a device name specified with -device. This will help organize your data among the server, so choose them to be unique. You can have multiple devices in the same family.

The default server is https://cloud.internalpositioning.com which you can specify with -server.

I suggest using a scantime of about 10 seconds, which you can specify with -scantime 10. If you want bluetooth to be scanned as well, just add -bluetooth.

To keep the scanner running, just add -forever. Even if the scanner is unable to reach the server (i.e. the server is down) the scanner will continue to send out data. If the server does come back on, then it will automatically be reconnected. If you’d like to have the scanner run in the background forever you can prefix with nohup and suffix with &.

Finally, the basic command then becomes:

$ nohup find3-cli-scanner -i YOURINTERFACE \
    -device YOURDEVICE -family YOURFAMILY \
    -server https://cloud.internalpositioning.com \
    -scantime 10 -bluetooth -forever &

Passive scanning

In passive scanning the scanner will report the classified location of the devices that it scans. This mode requires having a WiFi card that supports monitor mode. There are a number of possible USB WiFi adapters that support monitor mode. Here’s a list that are popular:

• USB Rt3070 $14
• Panda PAU5 $14
• Panda PAU6 $15
• Panda PAU9 $36
• Alfa AWUSO36NH $33
• Alfa AWUS036NHA $40
• Alfa AWUS036NEH $40
• Sabrent NT-WGHU $15 (b/g) only

Namely you want to find a USB adapter with one of the following chipsets: Atheros AR9271, Ralink RT3070, Ralink RT3572, or Ralink RT5572. You can simply run the command above with the flag -passive added to enable passive scanning.

$ nohup find3-cli-scanner -i YOURINTERFACE \
    -device YOURDEVICE -family YOURFAMILY \
    -server https://cloud.internalpositioning.com \
    -scantime 10 -bluetooth -forever -passive &

The above command will start by enabling monitor mode of the specified interface, then run the scan (using tshark and the bluetooth adapter), and then it will disable monitor mode so that the scan can be uploaded to the server. The enabling/disabling of monitor mode requires about 10 seconds each time. To remove this step you can enable monitor mode permanently.

$ find3-cli-scanner -i YOURINTERFACE -monitor-mode

After enabling monitor mode permanently you need to add a flag -no-modify to tell the command line scanner not to enable/disable automatically.

$ nohup find3-cli-scanner -i YOURINTERFACE \
    -device YOURDEVICE -family YOURFAMILY \
    -server https://cloud.internalpositioning.com \
    -scantime 10 -bluetooth -forever -passive -no-modify &

Issues?

If you have issues, please file a bug report on Github.

Source

If you are interested, the app is completely open-source and available at https://github.com/schollz/find3-cli-scanner.

LICENSE

MIT