GhostPath — Reconnaissance Framework

Overview

GhostPath

A modular, extensible reconnaissance engine for cybersecurity professionals. Historical URL intelligence, certificate transparency, subdomain enumeration — unified.

RECONNAISSANCE FRAMEWORK

pip install GhostPath GitHub ↗

At a glance

4

Modules

3

Sources

3

Formats

Why GhostPath exists

Traditional URL discovery tools are single-purpose scripts with no logging, no extensibility and no structured output. GhostPath was built to address all three failures — a reconnaissance framework, not a one-liner wrapper.

Every module is independently importable, centrally logged and outputs consistent structured data. It runs standalone or as the intelligence engine behind the ReconX web platform.

Capabilities

Wayback Machine

URLScan.io

Common Crawl

crt.sh CT Logs

Subdomain Enum

Path Probing

Tab Completion

Debug Logging

JSON/CSV/TXT

Multithreaded

ReconX Ready

Retry + Backoff

Interactive shell

ghostpath — interactive shell

👻 GhostPath Recon Shell | Developed by @atharvbyadav
Type 'help' for options

ghostpath> timetrail --target tesla.com --source wayback
[TimeTrail] Querying Wayback Machine...
[+] 4,231 unique historical URLs discovered
[TimeTrail] Results saved to: tesla.com.txt
ghostpath> certtrack --target tesla.com
[+] api.tesla.com
[+] staging.tesla.com
[+] fleet.tesla.com
⚠  3 noisy entries filtered

ghostpath> pathprobe --target https://tesla.com --threads 20
[+] https://tesla.com/admin (200 OK)
[→] https://tesla.com/api (301 Redirect)
[×] https://tesla.com/.env (403 Forbidden)
[PathProbe] 847 paths attempted · 3 found

ghostpath> █

Modules

Four modules.
One engine.

Passive and Active intelligence gathering, cleanly separated. Each module owns its arg parser, its logic, its output — sharing only the logger and formatter.

TimeTrail

Historical URL Discovery · Passive

CertTrack

Certificate Transparency · Passive

DomainScope

Subdomain Enumeration · Passive

PathProbe

Path Discovery · Active

Architecture

Designed for
extension.

Six-layer stack with strict separation of concerns. CLI parsing never touches core logic. Logging never mixed with output. Every module independently importable.

Execution flow

1

User Input

CLI args or interactive shell REPL

Entry

2

CLI Shell (main.py)

readline, tab-complete, banner, session state

Shell

3

Module Dispatcher

Routes command, invokes arg_parser(), passes parsed args

Router

Module Layer — independently importable

TimeTrail

Wayback · URLScan · CommonCrawl

passive

CertTrack

crt.sh CT log parsing

passive

DomainScope

crt.sh + URLScan multi-source

passive

PathProbe

Multithreaded HTTP probing

active

5

Shared Logger (stderr)

Centralized · debug mode toggle · never pollutes stdout

Shared

6

Output Formatter

TXT · JSON · CSV — consistent interface across all modules

Output

Design Principles

Separation of concernsarg_parser() never has logic. run() never parses strings.

Shared infrastructureLogger and formatter in shared/. Zero duplication across modules.

Debug without noiseAll debug output writes to stderr. Stdout stays pipeable.

Dual runtimeRuns standalone CLI or embedded inside ReconX as a library.

Installation

Up in
30 seconds.

Install from PyPI or clone from source. One dependency. Python 3.7+. Virtual environment recommended.

Install via PyPI

Recommended

# Standard install
$ pip install GhostPath
# Isolated global install (preferred)
$ pipx install GhostPath
# Verify
$ ghostpath --version
# Launch shell
$ ghostpath

Self-update from inside the shell: ghostpath update — runs pipx reinstall GhostPath automatically.

Install from Source

Development

$ git clone https://github.com/atharvbyadav/GhostPath.git
$ cd GhostPath
# Virtual environment
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install -r requirements.txt
$ python main_cli.py

Sole runtime dependency: requests. Zero heavy framework dependencies.

Requirements

Environment

Requirement	Version	Notes
Python	≥ 3.7	3.10+ recommended for best readline support
pip / pipx	latest	`pipx` gives a cleaner isolated global install
requests	≥ 2.28	Only runtime dependency — auto-installed via pip
readline	stdlib	Built-in on Linux/macOS. Windows may need `pyreadline3`
Network	—	Outbound HTTPS to Wayback, URLScan, crt.sh, Common Crawl

Usage

Two modes,
full control.

Interactive REPL for manual recon. Direct CLI for automation and scripting. All modules share a consistent argument interface.

Interactive Shell

REPL · tab-complete · history

timetrail

Historical URL discovery

certtrack

CT log analysis

domainscope

Subdomain enumeration

pathprobe

Path probing · active

Global Flags

--debug · --version · update

Logging

Auditability
by design.

Centralized logger writes to stderr, keeping stdout clean for piping. Verbosity toggled per-invocation with --debug.

DEBUG

Verbose trace

Every API request URL, params, retry attempt, HTTP status, URL parse decision, result count. Enable with --debug.

INFO

Operational

Module start events, source selected, total results count, output file path. Default stdout output.

WARN

Non-critical alerts

Noisy entries detected, wildcard entries filtered, partial results. Program continues.

ERROR

Failure events

API timeouts, network failures, JSON parse errors, unrecoverable exceptions.

Sample debug trace — stderr stream

[DEBUG] Fetching historical URLs for domain: tesla.com from source: wayback
[DEBUG] Wayback API URL: https://web.archive.org/cdx/search/cdx
[DEBUG] Params: {'url': '*.tesla.com/*', 'output': 'text', 'fl': 'original', 'limit': 5000}
[DEBUG] Attempt 1 — Sending request...
[DEBUG] HTTP 200 Response from Wayback
[DEBUG] Retrieved 4,231 unique URLs from Wayback.
[DEBUG] Total unique URLs fetched: 4231
[TimeTrail] Results saved to: tesla.com.txt

Why stderr?

Debug output deliberately writes to stderr. This keeps stdout clean for actual results — pipe

ghostpath timetrail ... >
                                            urls.txt

without log noise corrupting the output file.

Forensic value

During timed engagements or automation, --debug 2>audit.log captures every API call, retry decision and parse result — full reproducible audit trail for writeups.

Roadmap

Where this
is going.

GhostPath is actively maintained. The roadmap reflects deeper intelligence coverage, better automation primitives and broader source integration.

Shipped

In Progress

Planned

Released

PyPI Package Release done

Global install via pip and pipx. Available at pypi.org/project/GhostPath

Interactive CLI Shell done

Full REPL with readline, tab-completion, command history and ASCII banner.

Multi-Format Output done

TXT, JSON, CSV — unified interface across all four modules.

Multi-Source TimeTrail done

Wayback Machine, URLScan.io and Common Crawl all integrated with retry logic.

Centralized Logger done

stderr-based structured logging, debug mode toggle, per-invocation verbosity.

Upcoming

Async Concurrency in progress

Migrating from threading to asyncio. Estimated 5–10x throughput improvement on PathProbe.

ReconX Web Platform in progress

GhostPath powering a Streamlit-based recon dashboard as backend intelligence engine.

Shodan Integration planned

Port, banner and service intelligence layered on top of subdomain enumeration results.

API Server Mode planned

REST API exposing all modules for programmatic integration with external tooling.

Distributed Scanning planned

Multi-node support for large-scale infrastructure recon with coordinated result merging.

Security & Ethics

Authorized
testing only.

GhostPath is built for defensive security, authorized engagements and bug bounty programs. Read this before use.

⚠ RESPONSIBLE USE

GhostPath is designed for defensive security research, authorized penetration testing, bug bounty programs and red team engagements with explicit written permission from the target organization.

Using GhostPath against targets without authorization may violate the Computer Fraud and Abuse Act (CFAA), GDPR and equivalent laws in your jurisdiction.

You are solely responsible for ensuring your usage complies with all applicable laws and your organization's policies.

The author (@atharvbyadav) does not condone or accept any responsibility for unauthorized or malicious use of this software.

Intended Use Cases

✓ Permitted

Bug Bounty

In-scope assets on authorized programs

Pentest

Written authorization from asset owner

Red Team

Contracted engagement with defined scope

Own assets

Auditing infrastructure you own or control

Research

Academic or controlled lab environments

Vulnerability Disclosure

Contact

Found a security issue in GhostPath itself? Open a confidential issue on GitHub or contact via the profile linked below. We respond to responsible disclosures within 72 hours.

Open Issue ↗ @atharvbyadav ↗