phonetracer 0.1.0

Phone number OSINT and metadata tracing tool

PhoneTracer ⚡️

OSINT Phone Number Metadata Toolkit

PhoneTracer is a modular Python toolkit for extracting public, non-invasive metadata from phone numbers using Google’s libphonenumber (via the phonenumbers library).

❗ PhoneTracer does NOT track phones, reveal owners, or provide live locations.

---

✨ Features

• 📞 Phone number parsing & validation
• 🌍 Country / region identification
• 🏷 Carrier lookup (when available)
• 🕒 Timezone detection
• 🧠 Spam-style heuristic scoring
• 📄 Scan numbers from text files
• 📊 JSON export
• 🖥 Argument-based CLI
• 📟 Interactive command-line menu
• 🪟 Desktop GUI (Tkinter)
• 🧪 Built-in tests
• 🤖 GitHub Actions CI

---

🧱 Project Architecture

phone_tracer/
│
├── main.py        # Mode selector (entry point)
├── core.py        # Shared logic (analysis, logging, export)
├── cli_args.py    # Argument-based CLI mode
├── cli_menu.py    # Interactive command-line menu
├── gui_app.py     # GUI (Tkinter)
│
├── tracer.log     # Runtime logs
└── .github/
    └── workflows/
        └── python-ci.yml

---

🚀 Getting Started

Requirements

• Python 3.7+

Install dependency

pip install phonenumbers

---

▶️ Usage

Start PhoneTracer

python main.py

You will be prompted to choose:

1. Argument mode
2. Command-line menu
3. GUI

---

🔹 Argument Mode

python main.py
# choose option 1

Then use:

python cli_args.py -n "[phone]"
python cli_args.py -f numbers.txt

---

🔹 Command-line Menu

python main.py
# choose option 2

Interactive menu-driven interface.

---

🔹 GUI Mode

python main.py
# choose option 3

Simple desktop UI built with Tkinter.

---

📂 Output

All scan results are exported as JSON files:

YYYYMMDD_HHMMSS_<PHONE>.json

---

🧠 Spam Heuristics

PhoneTracer assigns a spam score based on simple patterns:

• Repeated digits
• Excessive zeros
• Abnormal formatting

This is only an indicator, not a classification.

---

🤖 Continuous Integration

GitHub Actions automatically:

• Installs dependencies
• Runs core sanity tests
• Ensures CLI paths load correctly

Workflow file:

.github/workflows/python-ci.yml

---

🔐 Privacy & Ethics

• ❌ No phone tracking
• ❌ No subscriber identification
• ❌ No surveillance techniques
• ✅ Metadata-only analysis

Use responsibly and legally.

---

📜 License

MIT License Educational & research use is encouraged.

---

⭐ If you find this project useful, consider starring the repository!