{"id":13582561,"url":"https://github.com/schollz/find3-cli-scanner","last_synced_at":"2025-04-15T03:55:08.224Z","repository":{"id":57483203,"uuid":"123614454","full_name":"schollz/find3-cli-scanner","owner":"schollz","description":"The command-line scanner that supports Bluetooth and WiFi","archived":false,"fork":false,"pushed_at":"2020-02-07T18:00:17.000Z","size":95,"stargazers_count":150,"open_issues_count":16,"forks_count":55,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-15T03:55:00.085Z","etag":null,"topics":["bluetooth","docker","indoor-positioning","linux","scanning","wifi"],"latest_commit_sha":null,"homepage":"https://www.internalpositioning.com/doc/tracking_your_computer.md","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/schollz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-02T18:17:52.000Z","updated_at":"2025-01-15T20:13:59.000Z","dependencies_parsed_at":"2022-08-27T21:02:36.546Z","dependency_job_id":null,"html_url":"https://github.com/schollz/find3-cli-scanner","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schollz%2Ffind3-cli-scanner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schollz%2Ffind3-cli-scanner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schollz%2Ffind3-cli-scanner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schollz%2Ffind3-cli-scanner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/schollz","download_url":"https://codeload.github.com/schollz/find3-cli-scanner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249003953,"owners_count":21196794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bluetooth","docker","indoor-positioning","linux","scanning","wifi"],"created_at":"2024-08-01T15:02:50.660Z","updated_at":"2025-04-15T03:55:08.208Z","avatar_url":"https://github.com/schollz.png","language":"Go","funding_links":["https://www.buymeacoffee.com/schollz"],"categories":["Go"],"sub_categories":[],"readme":"[![](.github/find3-promo.png)](https://www.internalpositioning.com/)\n\n[![Read the docs](https://img.shields.io/badge/read-docs-blue.svg?style=for-the-badge)](https://www.internalpositioning.com/doc) \n[![Join slack](https://img.shields.io/badge/join-slack-orange.svg?style=for-the-badge)](https://join.slack.com/t/find3/shared_invite/enQtMzI0MjkwMjc3MDYzLWJiZWEzZjU5NTljM2JlYmE1MDY0NThiYmY2NDYwNGYxNTNmNTJjZjFmNjMwNGMwY2UyNzczNzZhZTIxZWY3ODQ) \n[![Docker build status](https://img.shields.io/docker/build/schollz/find3-cli-scanner.svg?style=for-the-badge)](https://hub.docker.com/r/schollz/find3-cli-scanner/) \n[![Donate](https://img.shields.io/badge/beerpay-$5-brown.svg?style=for-the-badge)](https://www.buymeacoffee.com/schollz)\n\n**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*.\n\nThis 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.\n\n## Install\n\nThere are a couple of ways to install. I recommend downloading the [latest release](https://github.com/schollz/find3-cli-scanner/releases/latest) as that is the easiest way.\n\n### Install natively\n\nFirst make sure you have [downloaded Go](https://golang.org/dl/).\n\nThen, install the dependencies. \n\n*Linux*\n\n```\n$ sudo apt-get install wireless-tools net-tools libpcap-dev bluetooth\n```\n\n*OS X*\n\n```\n$ brew install libpcap\n```\n\nNow download and install the scanner with *go get*:\n\n```\n$ GO111MODULE=on go get -v github.com/schollz/find3-cli-scanner/v3 \n```\n\nIf you are on Linux, then you should move it to a path that is available with `sudo`:\n\n```\n$ sudo mv $GOPATH/bin/find3-cli-scanner /usr/local/bin\n```\n\nThat's it! See below for usage.\n\n### Install with Docker\n\nInstall Docker:\n\n```\n$ curl -sSL https://get.docker.com | sh\n```\n\nIf *not* using a Raspberry Pi, fetch the latest image.\n\n```\n$ docker pull schollz/find3-cli-scanner\n```\n\nIf 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.\n\n```\n$ wget https://raw.githubusercontent.com/schollz/find3-cli-scanner/master/Dockerfile\n$ docker build -t schollz/find3-cli-scanner .\n```\n\nNow you can start the scanning image in the background.\n\n```\n$ docker run --net=\"host\" --privileged --name scanner -d -i -t schollz/find3-cli-scanner\n```\n\nTo use the scanner, your syntax will be\n\n```\n$ docker exec scanner sh -c \"find3-cli-scanner -device DEVICE -family FAMILY -wifi -bluetooth -forever\"\n```\n\nBe sure to use your own device/family name. Use `-help` to see which flags are available.\n\nYou can start/stop the image using\n\n```\n$ docker start scanning\n$ docker stop scanning\n```\n\n\u003e Note, you can jump inside the image and play if you are curious of trying new things.\n```\n$ docker run --net=\"host\" --privileged --name scanning -i -t scanner /bin/bash\n```\n\u003e \n\n\n## Usage\n\n### Active scanning \n\nIn *active scanning* the scanner will report the classified location of the device that is doing the scanning.\n\nTo 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.\n\nYou 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.\n\nThe default server is https://cloud.internalpositioning.com which you can specify with `-server`. \n\nI 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`.\n\nTo 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 `\u0026`. \n\nFinally, the basic command then becomes:\n\n```\n$ nohup find3-cli-scanner -i YOURINTERFACE \\\n    -device YOURDEVICE -family YOURFAMILY \\\n    -server https://cloud.internalpositioning.com \\\n    -scantime 10 -bluetooth -forever \u0026\n```\n\n### Passive scanning \n\nIn *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:\n\n- [USB Rt3070 $14](https://www.amazon.com/gp/product/B00NAXX40C/ref=as_li_tl?ie=UTF8\u0026tag=scholl-20\u0026camp=1789\u0026creative=9325\u0026linkCode=as2\u0026creativeASIN=B00NAXX40C\u0026linkId=b72d3a481799c15e483ea93c551742f4)\n- [Panda PAU5 $14](https://www.amazon.com/gp/product/B00EQT0YK2/ref=as_li_tl?ie=UTF8\u0026tag=scholl-20\u0026camp=1789\u0026creative=9325\u0026linkCode=as2\u0026creativeASIN=B00EQT0YK2\u0026linkId=e5b954672d93f1e9ce9c9981331515c4)\n- [Panda PAU6 $15](https://www.amazon.com/gp/product/B00JDVRCI0/ref=as_li_tl?ie=UTF8\u0026tag=scholl-20\u0026camp=1789\u0026creative=9325\u0026linkCode=as2\u0026creativeASIN=B00JDVRCI0\u0026linkId=e73e93e020941cada0e64b92186a2546)\n- [Panda PAU9 $36](https://www.amazon.com/gp/product/B01LY35HGO/ref=as_li_tl?ie=UTF8\u0026tag=scholl-20\u0026camp=1789\u0026creative=9325\u0026linkCode=as2\u0026creativeASIN=B01LY35HGO\u0026linkId=e63f3beda9855abd59009d6173234918)\n- [Alfa AWUSO36NH $33](https://www.amazon.com/gp/product/B0035APGP6/ref=as_li_tl?ie=UTF8\u0026tag=scholl-20\u0026camp=1789\u0026creative=9325\u0026linkCode=as2\u0026creativeASIN=B0035APGP6\u0026linkId=b4e25ba82357ca6f1a33cb23941befb3)\n- [Alfa AWUS036NHA $40](https://www.amazon.com/gp/product/B004Y6MIXS/ref=as_li_tl?ie=UTF8\u0026tag=scholl-20\u0026camp=1789\u0026creative=9325\u0026linkCode=as2\u0026creativeASIN=B004Y6MIXS\u0026linkId=0277ca161967134a7f75dd7b3443bded)\n- [Alfa AWUS036NEH $40](https://www.amazon.com/gp/product/B0035OCVO6/ref=as_li_tl?ie=UTF8\u0026tag=scholl-20\u0026camp=1789\u0026creative=9325\u0026linkCode=as2\u0026creativeASIN=B0035OCVO6\u0026linkId=bd45697540120291a2f6e169dcf81b96)\n- [Sabrent NT-WGHU $15 (b/g) only](https://www.amazon.com/gp/product/B003EVO9U4/ref=as_li_tl?ie=UTF8\u0026tag=scholl-20\u0026camp=1789\u0026creative=9325\u0026linkCode=as2\u0026creativeASIN=B003EVO9U4\u0026linkId=06d4784d38b6bcef5957f3f6e74af8c8)\n\nNamely you want to find a USB adapter with one of the following chipsets: Atheros AR9271, Ralink RT3070, Ralink RT3572, or Ralink RT5572.\nYou can simply run the command above with the flag `-passive` added to enable passive scanning.\n\n```\n$ nohup find3-cli-scanner -i YOURINTERFACE \\\n    -device YOURDEVICE -family YOURFAMILY \\\n    -server https://cloud.internalpositioning.com \\\n    -scantime 10 -bluetooth -forever -passive \u0026\n```\n\nThe 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.\n\n```\n$ find3-cli-scanner -i YOURINTERFACE -monitor-mode\n```\n\nAfter enabling monitor mode permanently you need to add a flag `-no-modify` to tell the command line scanner not to enable/disable automatically.\n\n```\n$ nohup find3-cli-scanner -i YOURINTERFACE \\\n    -device YOURDEVICE -family YOURFAMILY \\\n    -server https://cloud.internalpositioning.com \\\n    -scantime 10 -bluetooth -forever -passive -no-modify \u0026\n```\n\n## Issues?\n\nIf you have issues, please [file a bug report on Github](https://github.com/schollz/find3-cli-scanner/issues/new?template=bugs.md\u0026title=Bug:%20).\n\n## Source\n\nIf you are interested, the app is completely open-source and available at  https://github.com/schollz/find3-cli-scanner.\n\n## LICENSE\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschollz%2Ffind3-cli-scanner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschollz%2Ffind3-cli-scanner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschollz%2Ffind3-cli-scanner/lists"}