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

> Learn to contribute to GhostTrack by adding new functions to GhostTR.py and registering them in the interactive menu. Follow this guide for OSINT developers to join the HunxByts GhostTrack project.

- Repository: [K1LLU/GhostTrack](https://github.com/HunxByts/GhostTrack)
- Tags: how-to-guide
- Published: 2026-04-29

---

**Contributing to GhostTrack requires adding a new function to [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/requirements.txt) (`requests` and `phonenumbers`).

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

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

2. **Create a virtual environment** and install dependencies:

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

3. **Verify the baseline** installation by running [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py):

   ```bash
   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`](https://github.com/HunxByts/GhostTrack/blob/main/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:

```python
@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:

```python
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`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/requirements.txt), implement your function with the decorator, append to `options`, and test interactively.
- Follow PEP 8, add docstrings, and update [`README.md`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py).

### Can I refactor GhostTrack into multiple files?

While the project intentionally maintains a single-file architecture ([`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/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.