recon-toolkit

Modular, automated recon and XSS scanning tools for ethical hacking and bug bounty work. Two complementary scripts that share the same conventions — profile-based rate control, DVWA auto-login, Burp proxy support, and structured reporting.

Legal notice: These tools are for use only on systems you own or have explicit written permission to test. Unauthorized scanning is illegal in most jurisdictions. Always verify scope before running anything. The authors are not responsible for misuse.

---

Tools

File	Purpose
recon_pipeline.py	Full recon pipeline: port discovery -> service scan -> web enum -> vuln scan
xss_scan.py	Standalone XSS scanner (dalfox-based, extensible), runs on recon output or any URL list

Underlying tools wrapped: nmap, naabu, httpx, subfinder, gobuster, nuclei, dalfox.

---

Requirements

• Python 3.10+ (uses str | None union syntax)
• Linux / Kali / Parrot (tested on Kali 2024.x)
• Go 1.21+ (for the Go tools — install.sh bootstraps it if missing)
• sudo for nmap raw-socket scans

Install

chmod +x install.sh
./install.sh                # everything
./install.sh --go           # Go + Go tools only
./install.sh --apt          # nmap, gobuster
./install.sh --wordlists    # seclists

Then confirm both tools see their dependencies:

sudo python3 recon_pipeline.py --setup
python3 xss_scan.py --profile lab --setup

Make sure ~/go/bin is on your PATH:

echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc && source ~/.bashrc

---

Profiles (shared concept)

Both scripts require a --profile flag that controls how aggressively they behave.

	lab	bugbounty
Speed / rate	Fast, aggressive	Slow, polite
Scope confirmation	No	Yes — prompts before every scan
Use for	DVWA, HackTheBox, TryHackMe, CTF, local VMs	Live bug bounty programs

Bug bounty tip: Even in bugbounty mode, read the program's policy on automated scanning. Some programs prohibit scanners outright — in those cases use the pipeline for recon only (--phase network) and do web testing manually in Burp.

---

recon_pipeline.py

Runs port discovery (naabu) -> deep service scan (nmap) -> web enum (subfinder/httpx/gobuster) -> vuln scan (nuclei) -> report.

# Local lab (DVWA) — auto-login, full pipeline
sudo python3 recon_pipeline.py -t 127.0.0.1 --profile lab --dvwa-security low

# Bug bounty target — prompts to confirm scope first
sudo python3 recon_pipeline.py -t example.com --profile bugbounty

# Network phase only
sudo python3 recon_pipeline.py -t example.com --profile bugbounty --phase network

# Web phase only, routed through Burp
sudo python3 recon_pipeline.py -t example.com --profile bugbounty --phase web --burp-proxy

# Authenticated scan with manual cookies
sudo python3 recon_pipeline.py -t example.com --profile bugbounty \
  --cookies "session=abc123; csrf=xyz"

# Batch mode — one target per line, # for comments (scope prompt per target)
sudo python3 recon_pipeline.py -t targets.txt --batch --profile bugbounty

Key flags: --full-scan (all 65535 ports), --rate N (override naabu pps), --no-update (skip nuclei template update), --setup (check tools and exit).

Output lands in recon_output/<target>_<timestamp>/ — report.md, summary.json, and network/, web/, burp/ subfolders. The clean URL list at web/httpx_urls.txt feeds straight into xss_scan.py.

---

xss_scan.py

Wraps dalfox with a consistent CLI. Run it after recon, or independently against any URL.

# DVWA (lab) — --dvwa-url is the login root, -u is the page(s) to scan
python3 xss_scan.py --profile lab \
  --dvwa-url http://localhost --dvwa-security low \
  -u http://localhost/vulnerabilities/xss_r/

# TryHackMe / HackTheBox with a session cookie
python3 xss_scan.py --profile lab \
  -u http://10.10.x.x/vulnerable.php \
  --cookies "PHPSESSID=your_session_here"

# Bug bounty — scope confirmation, routed through Burp
python3 xss_scan.py --profile bugbounty \
  -l scope_urls.txt --burp-proxy \
  --cookies "session=your_authenticated_session"

-u (repeatable) and -l (URL-list file, repeatable) can be combined and are deduped automatically. Other flags: --tool NAME, --workers N, --timeout N, --header "K: V", --dalfox-flags "...", --output DIR, --setup.

Reading the report: [POC][V] = verified JS execution (confirm in browser, replay in Burp Repeater); [POC][R] = reflected but not auto-confirmed (test manually — CSP or interaction may be needed); [WEAK] = reflection without a clean landing (try filter-bypass variants). Output goes to xss_output/<label>_<timestamp>/.

---

Typical chained workflow

# 1. Recon
sudo python3 recon_pipeline.py -t localhost --profile lab --dvwa-security low

# 2. XSS scan the discovered URLs
python3 xss_scan.py --profile lab \
  -l recon_output/localhost_*/web/httpx_urls.txt \
  --cookies "PHPSESSID=your_session"

---

Burp Suite integration

With --burp-proxy, HTTP traffic is routed through http://127.0.0.1:8080. For the recon pipeline, discovered URLs are also exported to burp/burp_urls.txt — import via Target -> Site Map -> right-click -> Load from file. For HTTPS targets, install Burp's CA cert from http://burpsuite/cert.

---

Contributing

See CONTRIBUTING.md for how to add new tools to either script.

Disclaimer

Authorized testing only. Only run against systems you own or have explicit written permission to test. Unauthorized scanning is illegal.