Guide · Open source
How to use Seeker: install, run and read what it collects
Updated · written with AI from the project's own documentation and checked against our catalogue data
Seeker is an open-source proof-of-concept tool that hosts a fake web page asking the visitor for location permission, then shows what a page can read from a phone. This guide covers installation, running the tool with a tunnel, the main options, and what the README says about accuracy and limits. It is written for security students, researchers, and educators who want to understand the risk, not for tracking anyone.
Seekerthewhiteh4t/seeker · ★ 10.2k · MIT Install options & downloads Quick start
- 1Check prerequisites. Make sure Python 3 and git are installed on your system. The README lists these as the requirements for the clone-and-build install.
- 2Clone the repository. Run git clone https://github.com/thewhiteh4t/seeker.git to download the project, then enter the folder with cd seeker/.
- 3Run the installer. Make install.sh executable with chmod +x install.sh, then run ./install.sh.
- 4Start Seeker. Run python3 seeker.py to start the web server, which defaults to port 8080.
- 5Open a tunnel. Start a tunnel such as ngrok http 8080 in a second terminal so the page is reachable from another network.
- 6Review the output. Check what the tool records and read the README's notes on accuracy, which says about 30 meters when permission is granted.
What Seeker does and what it is for
Seeker hosts a fake website that asks for location permission. If the visitor allows it, the tool records latitude, longitude and accuracy from the phone's GPS, along with device and browser details. The README says the project exists to show what a malicious website can collect and why people should not click random links or grant critical permissions.
The README calls Seeker a proof of concept for educational purposes only. Use it on your own devices or in a supervised classroom setting.
- Good fit: security students studying location permission abuse
- Good fit: researchers testing their own devices and privacy settings
- Good fit: educators demonstrating social engineering risks
- Not for: locating or tracking another person without consent, which the README frames as educational and says is unlawful in most places
Install Seeker on Linux or Termux
The README lists Kali Linux, Arch Linux, Ubuntu, Fedora, Parrot OS and Termux under the same clone-and-build method. Prerequisites are Python 3 and git. Run these commands in a terminal.
The README also lists a BlackArch package (sudo pacman -S seeker) and a Docker image (docker pull thewhiteh4t/seeker) as other install routes.
git clone https://github.com/thewhiteh4t/seeker.git
cd seeker/
chmod +x install.sh
./install.shRun Seeker and open a tunnel
Start Seeker in one terminal. By default it serves on port 8080. To reach the page from a phone on another network, the README uses a tunnel service such as ngrok in a second terminal. The README also gives an SSH-based alternative, localhost.run.
On macOS the README says to run seeker.py directly with python3 and install ngrok with Homebrew for tunnel mode.
- Terminal 1: start Seeker
- Terminal 2: start a tunnel to the same port, for example ngrok http 8080
- Alternative tunnel: ssh -R 80:localhost:8080 nokey@localhost.run
python3 seeker.py
./ngrok http 8080Choose options: port, template and output
Run python3 seeker.py -h to see the full option list. The README documents a KML output file for Google Earth, a custom port, and a preselected template. If you change the port, point your tunnel to the same port.
The -d option disables the automatic HTTP to HTTPS redirect for testing. The README says it only works for templates that have an index_temp.html file.
- -k, --kml: KML filename for Google Earth
- -p, --port: web server port, default 8080
- -t, --template: auto-select a template by index
- -d, --debugHTTP: disable HTTP to HTTPS redirect for testing
- -u, --update: check for updates
- -v, --version: print version
- --telegram: send info to a Telegram bot using token:chatId
- --webhook: send events to an unauthenticated endpoint that accepts POST
python3 seeker.py -k <filename>
python3 seeker.py -p 1337
./ngrok http 1337
python3 seeker.py -t 1Understand what data is collected and how accurate it is
When a visitor allows location, the README says Seeker can get longitude, latitude and accuracy. Altitude, direction and speed are included only when available, and direction and speed only when the user is moving. Without any permission, it also collects device information such as canvas-based ID, operating system, platform, browser, screen resolution and IP addresses.
The README says that when a user accepts location permission, accuracy is about 30 meters. It also says accuracy depends on the device, the browser (some block JavaScript) and GPS calibration. Laptops usually lack the GPS hardware Seeker relies on, and IP geolocation is a different and much less accurate method.
- Location: latitude, longitude, accuracy, plus altitude, direction and speed when available
- Device: canvas fingerprint ID, OS, platform, CPU cores and RAM (approximate), screen resolution, GPU, browser, public and local IP, local port
Templates and running on a server
The README lists six templates: NearYou, Google Drive, WhatsApp, Telegram, Zoom and Google reCAPTCHA. It also explains that you can create your own template by following a how-to in the repository and then propose it through a pull request.
For unattended runs, the README lists environment variables such as PORT, TEMPLATE, TITLE, REDIRECT, IMAGE, DESC, SITENAME, DISPLAY_URL, TELEGRAM and WEBHOOK. Docker usage is documented with a shared network and an ngrok container.
docker network create ngroknet
docker run --rm -it --net ngroknet --name seeker thewhiteh4t/seekerWhat people use it for
- Teaching a class how location permission prompts can be abused
- Testing how much device information your own browser exposes
- Studying how a fake permission page is built, using the templates as examples
- Exporting a recorded location to a KML file for viewing in Google Earth
Frequently asked questions
Is Seeker free and what is its licence?
Seeker is released under the MIT licence, according to the project page. The README does not list any paid version.
What do I need to install Seeker?
The README lists Python 3 and git as prerequisites. You then clone the repository and run the included install.sh script.
Does Seeker work on a laptop?
The README says Seeker relies on GPS hardware, which laptops usually lack. It can fall back to IP geolocation or cached coordinates, but the README says IP lookup is far less accurate.
How accurate is Seeker?
The README says that when a user accepts location permission, results are accurate to approximately 30 meters. Accuracy also depends on the device, browser and GPS calibration.
Is Seeker the same as IP geolocation?
No. The README says IP geolocation gives the approximate location of an ISP, while Seeker uses the phone's GPS through the browser after permission is granted.
Can I use Seeker to track someone?
The README frames the tool as educational and says it shows what a malicious site can collect. Locating or tracking another person without consent is unlawful in most places, so use it only on your own devices or in supervised teaching.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Seeker suits security students, researchers and educators who want a hands-on demonstration of location permission risk, and who can install Python tools from the command line. It is a poor choice if you need IP-based geolocation, or if you only have a laptop, since the README says it depends on phone GPS. Anyone who wants to locate another person without consent should pick a different project and should not use this one for that purpose.
Install options & downloads