🍎 macOS Installation Guide

🍎 WireTapper — macOS Installation Guide

Welcome! Here's how to get WireTapper up and running on macOS. 🚀

✅ Requirements

• 🍏 macOS 12 (Monterey) or newer
• 🐍 Python 3.10+ (for pip/source install)
• 🌐 Internet connection (for API lookups — Wigle, wpa-sec, OpenCellID, Shodan)
• 🛡️ sudo access (wireless interface scanning needs elevated permissions)

📦 Option 1: Standalone Binary (Easiest)

No Python required — just download and run.

1. ⬇️ Download the latest build:

   curl -L -o WireTapper-macOS https://github.com/h9zdev/WireTapper/releases/download/WireTapper/WireTapper-macOS

2. 🔓 Make it executable:

   chmod +x WireTapper-macOS

3. 🛡️ Clear the Gatekeeper quarantine flag (unsigned binary):

   xattr -d com.apple.quarantine WireTapper-macOS

4. ▶️ Run it:

   sudo ./WireTapper-macOS

(sudo is needed for raw wireless interface access)

⚠️ If macOS still blocks it, go to System Settings → Privacy & Security → Security and click Open Anyway.

🐍 Option 2: Install via PyPI (pip)

For the latest features and easier updates.

1. 🔎 Verify Python is installed:

   python3 --version

Don't have it? Install via Homebrew:

   brew install python

2. 📥 Install WireTapper:

   pip3 install wiretapper --break-system-packages

3. ▶️ Run it:

   wiretapper start

Or with custom parameters:

   # Start on custom port and auto-open browser
   wiretapper start --port 8080 --open-browser
 
   # Run with python module syntax
   python3 -m wiretapper start

4. 🔄 To update later:

   pip3 install --upgrade wiretapper --break-system-packages

🧰 Option 3: Run from Source (Developers)

1. 📂 Clone the repo:

   git clone https://github.com/h9zdev/WireTapper.git
   cd WireTapper

2. 🧪 (Recommended) Create a virtual environment:

   python3 -m venv venv
   source venv/bin/activate

3. 📦 Install dependencies:

   pip install -r requirements.txt

4. ▶️ Launch:

   sudo python3 main.py

Or build and install your own wheel:

   pip install -e . --break-system-packages
   # or
   pip install dist/wiretapper-1.0.0-py3-none-any.whl --break-system-packages

🌐 Access the Web UI

🖥️ Dashboard	🔗 URL
📶 WiFi & Telemetry Dashboard	http://localhost:8080
🔵 Bluetooth BLE Recon & RPA Resolver	http://localhost:8080/bts

🔑 API Key Setup

WireTapper uses a few external services. You can set your keys either before launch or live from the UI:

• Option A: Config File Add your keys to the config file:

    📁 config/
       └── 🔐 keys.env

    WIGLE_API_KEY=your_key_here
    SHODAN_API_KEY=your_key_here
    OPENCELLID_API_KEY=your_key_here

• Option B: In-App Settings UI Open the application dashboard in your browser and click the ⚙️ Settings gear icon in the navigation bar to enter or update your API credentials at runtime — no server restart needed.

🩹 Troubleshooting

⚠️ Issue	🛠️ Fix
"WireTapper-macOS" cannot be opened	Run xattr -d com.apple.quarantine WireTapper-macOS, or allow it in Privacy & Security
wiretapper: command not found	Ensure ~/Library/Python/3.x/bin (or your venv bin) is on PATH
Permission denied on wireless scan	Re-run with sudo
externally-managed-environment pip error	Add --break-system-packages, or use a virtualenv
Wi-Fi scanning limited/no results	Apple restricts raw Wi-Fi APIs on newer macOS — grant Location Services access to Terminal in Privacy & Security → Location Services
Port already in use	Run with wiretapper start --port <other_port>

🎯 You're all set!

Fire up WireTapper and start mapping. 📡🛰️🔍

⭐ If it's useful, consider starring the repo: github.com/h9zdev/WireTapper