GhostRecon

GhostRecon is an experimental Python proof of concept for bounded web reconnaissance on hostnames you own or are explicitly authorized to assess. It combines a local subdomain wordlist with an optional crt.sh certificate-name query, performs HTTPS observations, and writes a static local HTML report plus CSV findings.

The project is intentionally modest in scope. It is not a vulnerability scanner, exploitation framework, stealth tool, or substitute for manual validation. A reported marker, file path, login form, or missing header is an observation that may be a false positive.

Current behavior

• accepts one DNS hostname; URLs, ports, wildcard targets, and IP literals are rejected;
• always scans the base hostname, even with no discovery results or a target cap of one;
• keeps wordlist and certificate candidates in scope using DNS label boundaries;
• verifies TLS certificates and does not follow HTTP redirects during requests;
• caps target count, retained response bytes, worker count, and simultaneous browsers;
• checks configured content markers, selected file paths, login forms, and recommended headers;
• optionally renders local screenshots from the already bounded response body, with JavaScript and all browser network requests disabled;
• produces a self-contained static report with a restrictive Content Security Policy, no JavaScript, and no remote assets.

GhostRecon does not query IP geolocation services, attempt subdomain takeover, bypass WAFs, auto-update resources, or execute remediation.

Requirements

• Python 3.11–3.13
• Chromium installed through Playwright only if screenshots are wanted

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
playwright install chromium

To work on the project, also install requirements-dev.txt.

Usage

Only scan a hostname that is explicitly within your authorized scope.

python main.py example.com

Useful controls:

python main.py example.com \
  --max-targets 50 \
  --max-response-bytes 524288 \
  --max-browser-launches 2

• --max-targets includes the base hostname. Default: 100; hard maximum: 1000.
• --max-response-bytes is applied independently to every HTTP response, including the optional crt.sh response. Default: 1 MiB; hard maximum: 10 MiB.
• --max-browser-launches bounds simultaneous Playwright instances through a semaphore. Default: 2; hard maximum: 8.
• --no-crtsh keeps discovery fully local.
• --no-screenshots skips local rendering and removes the Chromium dependency from a scan run.
• --wordlist PATH, --config PATH, and --output-dir PATH select local inputs and output.

The base target is deterministic and always first. Other candidates are de-duplicated, sorted, then truncated to the configured target cap. Wordlist entries are treated as relative names unless they already equal the target or end at its DNS label boundary. crt.sh results are treated as absolute names and out-of-scope names are discarded.

Output and interpretation

Each timestamped directory under scans/ contains:

• report.html: a local static report with escaped observed content and local screenshot links;
• results.csv: separate columns for files, content markers, header issues, and login detection, plus a Findings summary that includes all four categories;
• screenshots/: optional JPEG captures for successful HTTPS responses.

The priority score is a triage heuristic, not a severity rating. It weights matching file probes, content markers, a password input, and absent configured headers. Confirm every observation manually before treating it as a security issue.

Configuration

config.json contains runtime defaults, user-agent text, selected file signatures, content marker regular expressions, and recommended response headers. Runtime values are validated against hard limits at startup. Probe paths must be safe relative paths.

The optional subdomains.txt file is intentionally ignored by Git. Example:

www
api
admin.dev

Verification

The test suite is offline: network, DNS, HTTP, and screenshot boundaries use local fakes.

python -m pytest -q
python -m ruff check .
python -m ruff format --check .
python -m compileall -q main.py modules tests
python -m json.tool config.json >/dev/null

CI runs these checks on Python 3.11, 3.12, and 3.13 with read-only repository permissions.

Authorization and limitations

Use GhostRecon only against systems you own or have explicit written permission to test. You are responsible for rate limits, scope boundaries, data handling, and applicable law. The project has not undergone an independent security assessment and makes no guarantee of completeness.

License

Licensed under the MIT License. Copyright © 2026 Osman Kaan Kars.