How to Set Up a Development Environment for GhostTrack

Setting up a GhostTrack development environment requires cloning the HunxByts/GhostTrack repository, installing Python 3, and running pip install -r requirements.txt to install the requests and phonenumbers dependencies before executing python3 GhostTR.py.

GhostTrack is a lightweight Python-based command-line utility designed for open-source intelligence (OSINT) gathering on IP addresses, phone numbers, and social media usernames. The entire application is contained within a single executable script (GhostTR.py), making it straightforward to configure a local development environment for customization or testing. This guide covers the complete setup process, dependency installation, and codebase architecture to get you running immediately.

Prerequisites and System Requirements

GhostTrack operates on Linux systems and Termux (Android environments). The tool requires Python 3 and git to be installed on your system. For Termux users, install the necessary packages using pkg install git python. The codebase relies on standard library modules plus two external packages listed in requirements.txt.

Step-by-Step Development Environment Setup

Follow these steps to configure your local development environment for GhostTrack.

Clone the Repository

Retrieve the source code from GitHub to your local machine:

git clone https://github.com/HunxByts/GhostTrack.git
cd GhostTrack

Create a Virtual Environment (Recommended)

Isolate your project dependencies from the system Python installation to avoid conflicts:

python3 -m venv venv
source venv/bin/activate

On Windows (if modifying for cross-platform support), use venv\Scripts\activate instead.

Install Python Dependencies

The requirements.txt file at the repository root specifies only two essential packages. Line 1 lists requests for HTTP API calls, and line 2 lists phonenumbers for parsing and validating phone number data. Install both using:

pip install -r requirements.txt

Verify Installation

Confirm the environment is configured correctly by launching the interactive menu:

python3 GhostTR.py

This executes the entry point defined in the main script, triggering run_banner() to display the ASCII art header and option() to render the selection menu.

Understanding the GhostTR.py Architecture

The entire application logic resides in GhostTR.py, structured as a single-file CLI tool. Lines 17-24 define ANSI color escape codes (variables like Wh, Gr, Re) used throughout the interface for colored terminal output.

The execution flow follows this pattern:

1. Entry Point: The script initializes by calling run_banner() to clear the terminal and display branding
2. Menu Rendering: The option() function builds the interactive menu from a global options list
3. Input Handling: execute_option() validates user selection via is_in_options and dispatches to the appropriate tracker
4. Execution: Each tracker function uses the @is_option decorator to automatically inject the banner display before running

Core Tracker Functions

The application implements three primary intelligence gathering modules:

• IP Tracker (IP_Track): Located at lines 45-71, this function queries http://ipwho.is/<ip> using the requests library. It extracts and displays geolocation fields including country, city, ASN, latitude, and longitude coordinates.

• Phone Number Tracker (phoneGW): Implemented at lines 86-108, this leverages the phonenumbers library to parse international numbers. It retrieves carrier information, timezone data, region codes, and validation status.

• Username Tracker (TrackLu): Found at lines 52-58, this module iterates through a hard-coded list of social media URL templates. It performs HTTP GET requests to determine username availability across platforms based on HTTP 200 responses versus "not found" messages.

Running GhostTrack for Development

Test the installation by executing the IP geolocation feature:

$ python3 GhostTR.py
[ + ] Select Option : 1
Enter IP target : 8.8.8.8

The IP_Track function (lines 45-71) automatically calls requests.get(f"http://ipwho.is/{ip}") and formats the JSON response with geolocation details.

To test phone number validation:

$ python3 GhostTR.py
[ + ] Select Option : 3
Enter phone number target [+6281xxxxxxxxx] : +14155552671

The phoneGW() function processes the input through the phonenumbers parser to display carrier and location data.

Extending the Tool

Since GhostTrack uses a single-file architecture, modifications are immediate. Edit GhostTR.py directly to:

• Add new API endpoints in the tracker functions
• Extend the username URL templates list in TrackLu()
• Implement additional error handling for network timeouts
• Refactor the menu system into a modular CLI framework

The @is_option decorator pattern (visible at line 52) allows registration of new menu items without modifying the core validation logic in execute_option().

Summary

• GhostTrack requires only Python 3, requests, and phonenumbers to operate
• Install dependencies via pip install -r requirements.txt (referencing lines 1-2)
• The complete application logic resides in GhostTR.py with color definitions at lines 17-24
• Three tracker functions handle IP geolocation (lines 45-71), phone validation (lines 86-108), and username enumeration (lines 52-58)
• Virtual environments isolate dependencies and prevent system Python conflicts

Frequently Asked Questions

What Python version is required for GhostTrack?

GhostTrack requires Python 3, which comes pre-installed on most modern Linux distributions. For Termux on Android, install it via pkg install python before running the setup commands.

Can I run GhostTrack on Windows?

The current implementation in GhostTR.py uses Unix-specific terminal commands (os.system('clear')) and ANSI color codes defined at lines 17-24. While the logic would function, you would need to modify the clear() function and potentially adjust path handling for full Windows compatibility.

How do I add a new social media platform to the username tracker?

Modify the TrackLu() function in GhostTR.py around lines 52-58 by adding a new URL template to the existing list. Ensure you import the is_option decorator and apply it to your new function to register it with the menu system handled by execute_option().

Where are the API calls configured for the IP tracker?

The IP geolocation endpoint is hard-coded in the IP_Track function at lines 45-71 of GhostTR.py. Specifically, the code executes requests.get(f"http://ipwho.is/{ip}") to fetch location data, then parses the JSON response for display using the color variables defined earlier in the file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}