How to Contribute to GhostTrack: A Complete Guide for OSINT Developers

Contributing to GhostTrack requires adding a new function to GhostTR.py, decorating it with @is_option, and appending an entry to the options list to register it in the interactive menu.

GhostTrack is a lightweight, single-file Python CLI tool maintained by HunxByts that aggregates OSINT utilities for IP, phone number, and username lookups. Because the entire application lives in GhostTR.py and uses a registry-based menu system, contributing to GhostTrack is straightforward for developers familiar with Python and API integration.

Understanding the GhostTrack Architecture

The project intentionally maintains a minimal footprint to lower the barrier for contributors. The codebase is approximately 315 lines and relies on a simple dispatch pattern rather than complex frameworks.

The Entry Point and Main Loop

Execution begins at the bottom of GhostTR.py (lines 310-315) where the if __name__ == '__main__': guard calls main(). This function clears the terminal, displays the menu, and enters an interactive loop that delegates user input to execute_option (lines 96-107). The dispatcher validates selections and handles graceful shutdowns on KeyboardInterrupt.

The Options Registry Pattern

GhostTrack uses a declarative options list (lines 78-103) that maps numeric menu choices to their corresponding functions. Each entry is a dictionary containing num, text, and func keys, as shown in the existing definitions for IP_Track and phoneGW. This registry pattern means you can add capabilities without modifying the core dispatch logic in call_option (lines 119-138).

Decorator-Based Dispatch

The @is_option decorator (lines 29-37) wraps every public command with run_banner(), ensuring consistent ASCII art display and automatic menu return after execution. Feature implementations like IP_Track, phoneGW, TrackLu, and showIP (lines 41-75, 81-115, 122-165, and 69-77) all use this decorator to inherit common UI behavior.

Setting Up Your Development Environment

Before modifying the source, configure your local workspace to match the dependencies declared in requirements.txt (requests and phonenumbers).

1. Fork the repository on GitHub, then clone your fork:

   git clone https://github.com/<your-username>/GhostTrack.git
   cd GhostTrack

2. Create a virtual environment and install dependencies:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

3. Verify the baseline installation by running GhostTR.py:

   python GhostTR.py

Implementing a New OSINT Feature

Adding functionality follows a three-step pattern: write the function, decorate it, and register it.

Create the Tracker Function

Add your function to GhostTR.py following the pattern of existing trackers. Import required libraries (typically requests for HTTP calls) at the top of the file. Use the @is_option decorator to inherit banner and menu behavior:

@is_option
def domain_reputation():
    domain = input(f"{Wh}\n Enter domain to check : {Gr}")
    resp = requests.get(f"https://api.threatintelligenceplatform.com/v1/domain/{domain}")
    data = resp.json()
    print(f"\n{Wh}=== Reputation for {domain} ===")
    print(f"{Wh}Score:{Gr} {data['reputation_score']}")
    print(f"{Wh}Categories:{Gr} {', '.join(data['categories'])}")

Register in the Options List

Append a dictionary to the options list with a unique numeric identifier, descriptive text, and reference to your function:

options.append({
    'num': 5,
    'text': 'Domain Reputation Tracker',
    'func': domain_reputation
})

The surrounding code automatically handles input validation and re-renders the menu after your function completes.

Update Documentation

Modify README.md to include the new option in the usage section. Add a screenshot or description explaining the feature and any required API keys. Use environment variables for secrets, never hard-code credentials directly in GhostTR.py.

Contribution Guidelines and Best Practices

Follow these standards when preparing your pull request:

• Keep it single-file: Unless performing substantial re-architecture, maintain the monolithic structure in GhostTR.py to preserve the project's deployment simplicity.
• Code style: Follow PEP 8 naming conventions and add docstrings describing inputs, outputs, and external API dependencies.
• Error handling: Gracefully handle network failures and invalid user input, matching the existing exception handling patterns in call_option.
• Formatting: Use the existing color constants (Wh, Gr, etc.) rather than printing raw JSON to maintain consistent terminal output.
• Testing: Exercise your new menu entry locally and verify it returns to the main menu after execution.

Summary

• GhostTrack is a single-file Python CLI (GhostTR.py) using an options list registry pattern located at lines 78-103.
• The @is_option decorator (lines 29-37) and execute_option dispatcher (lines 119-138) handle menu logic automatically.
• To contribute: fork the repo, install from requirements.txt, implement your function with the decorator, append to options, and test interactively.
• Follow PEP 8, add docstrings, and update README.md with usage instructions.
• Submit changes via Pull Request against the main branch with clear commit messages describing the OSINT capability added.

Frequently Asked Questions

What programming skills do I need to contribute to GhostTrack?

You need basic Python knowledge, specifically working with the requests library for HTTP calls and understanding dictionary-based registries. Familiarity with OSINT APIs is helpful for implementing new lookup features, but the codebase is designed to be accessible to intermediate developers who can follow the existing patterns in GhostTR.py.

Can I refactor GhostTrack into multiple files?

While the project intentionally maintains a single-file architecture (GhostTR.py) for simplicity and portability, substantial improvements or modularization would be considered if they significantly enhance maintainability without complicating deployment. Discuss major architectural changes in an issue before submitting a pull request against HunxByts/GhostTrack.

How do I handle API keys when adding new OSINT sources?

Store API keys in environment variables and access them via os.environ inside your tracker function. Never hard-code credentials or commit .env files to the repository. Update the README.md to document required environment variables for your new feature so other users can configure their systems correctly.

Where is the main execution loop defined in GhostTrack?

The entry point resides at lines 310-315 of GhostTR.py, where if __name__ == '__main__': invokes the main() function. This function manages the interactive menu loop and delegates selections to execute_option, which validates input and calls the appropriate tracker function from the options registry before returning control to the user.

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