How to Report a Bug in GhostTrack: The Complete Guide for Contributors

To report a bug in GhostTrack, open a GitHub Issue on the HunxByts/GhostTrack repository and include the exact version from the README, your operating system, Python version, installed dependencies from requirements.txt, and the full traceback showing which function in GhostTR.py failed.

GhostTrack is a lightweight Python CLI tool that bundles OSINT utilities including IP lookup, phone number validation, and username enumeration across social platforms. When you encounter crashes or unexpected behavior in functions like IP_Track() or TrackLu(), submitting a structured bug report accelerates the debugging process. This guide shows exactly how to report a bug in GhostTrack by referencing the actual source code structure and required diagnostic information.

Required Information for Bug Reports

Effective bug reports for GhostTrack require specific technical details to reproduce failures. The maintainer needs these data points to trace issues back to the relevant code paths in GhostTR.py.

Version and Environment Details

Always provide the following system information:

• Exact version – Copy the version string from the README (e.g., "Version 2.2")
• Operating system – Specify Linux distribution, Termux, or Windows version
• Python interpreter – Run python3 --version and report the output
• Installation method – Note whether you cloned the repository, used the Linux .deb package, or installed manually

Dependency Verification

GhostTrack relies on third-party packages listed in requirements.txt, specifically requests and phonenumbers. Include the output of pip3 freeze to confirm exact package versions, as API compatibility issues often stem from dependency mismatches.

Error Output and Reproduction Steps

Document the failure with precision:

• The full Python traceback showing the exception type and line number in GhostTR.py
• The menu option selected during execution
• The exact input values provided (e.g., IP addresses or usernames)
• Network conditions – Note if you were offline or behind a proxy, since the tool queries external APIs

Step-by-Step Bug Reporting Process

Follow this structured workflow to ensure your issue gets triaged quickly:

1. Navigate to Issues – Go to the HunxByts/GhostTrack Issues page and click New issue.
2. Select Template – Use the bug report template if available; otherwise, start with a clear title format: Bug: [FunctionName] crashes on [condition].
3. Complete All Sections:
   • Description – Concise summary of the malfunction
   • Version – Paste the version string from README.md
   • Environment – OS, Python version, and installation method
   • Steps to Reproduce – Numbered list from launch to crash (e.g., 1. python3 GhostTR.py, 2. Select IP Tracker, 3. Enter 256.0.0.1)
   • Expected vs. Actual Result – Describe intended behavior and paste the complete console output
4. Attach Supporting Files – Include diffs if you modified the code, or screenshots of the error output.
5. Submit – Post the issue to notify the maintainer.

Common Bug Patterns in GhostTR.py

Understanding the architecture helps identify where bugs occur. The main script GhostTR.py contains four primary feature functions that are frequent sources of errors:

Network-Dependent Failures

Most bugs stem from API interactions without proper error handling. The IP_Track() function (lines 39-78) queries ipwho.is, while TrackLu() (lines 121-167) iterates through social media URLs. If these endpoints return non-200 status codes or malformed JSON, the script raises unhandled exceptions.

Input Validation Errors

Functions like phoneGW() (lines 80-119) process raw user input without extensive sanitization. Invalid IPv4 addresses (e.g., 256.0.0.1) or malformed phone numbers trigger KeyError or json.JSONDecodeError exceptions when the code attempts to parse the API response.

Capturing Debug Information for Your Report

Use these terminal commands to generate copy-paste content that helps maintainers reproduce your environment:

Capture system details:

uname -a
python3 --version
pip3 freeze | grep -E 'requests|phonenumbers'

Reproduce and capture the error:

git clone https://github.com/HunxByts/GhostTrack.git
cd GhostTrack
pip3 install -r requirements.txt
python3 GhostTR.py <<EOF
1
256.0.0.1
EOF

Paste the resulting traceback verbatim into your issue, ensuring it includes references to specific line numbers in GhostTR.py (e.g., File "GhostTR.py", line 46, in IP_Track).

Key Source Files to Reference

When describing bugs, cite these specific files and locations to demonstrate technical accuracy:

• GhostTR.py – Main executable containing IP_Track(), phoneGW(), TrackLu(), and menu infrastructure (lines 39-167)
• requirements.txt – Dependency manifest listing requests and phonenumbers
• README.md – Contains version badge and platform-specific installation instructions

By linking directly to line ranges in GhostTR.py (such as lines 39-78 for IP tracking logic), you provide maintainers with precise navigation points to the problematic code.

Summary

• Report bugs via GitHub Issues on the HunxByts/GhostTrack repository using descriptive titles that mention the affected function.
• Always include environment data: Version string, OS, Python version, and the output of pip3 freeze.
• Provide full tracebacks that point to specific functions and line numbers in GhostTR.py.
• Document network conditions since GhostTrack relies on external APIs (ipwho.is, api.ipify.org, social media endpoints).
• Attach reproduction scripts or exact input sequences that trigger the failure.

Frequently Asked Questions

Where do I report bugs in GhostTrack?

Navigate to the Issues section of the GitHub repository and create a new issue. Format your title as Bug: [function_name] - [brief description] to help maintainers quickly identify the relevant code block in GhostTR.py.

What Python version does GhostTrack require?

GhostTrack requires Python 3. Verify your installation by running python3 --version before reporting environment-specific bugs, as syntax or library differences between Python versions can cause compatibility issues.

Why does GhostTrack crash when I lose internet connectivity?

The functions IP_Track(), showIP(), and TrackLu() depend on external web APIs. When offline, the requests library fails to establish connections or receives empty responses, causing unhandled exceptions during JSON parsing. Include your network status in bug reports involving these functions.

How do I identify which function caused the error?

Examine the traceback in your terminal output. The error message specifies the function name and line number in GhostTR.py (for example, File "GhostTR.py", line 46, in IP_Track), allowing you to reference the exact implementation in your bug report and help maintainers locate the bug immediately.

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