recon2exploit

recon2exploit is a Python security-assessment framework that drives a complete A–Z pipeline — from passive OSINT to credential auditing, traffic analysis, and Metasploit validation — against one or more authorised domains.

Two entry points, one codebase:

Entry point	Best for
pipeline.py	New unified 10-phase pipeline (recommended) — clean CLI, all new modules wired in
recon.py	Legacy orchestrator — deep recon.py feature set with PostgreSQL/Redis persistence

A single command produces HTML dashboard + JSON + CSV + SARIF reports.

Use only on systems you own or have explicit written authorisation to test.
--authorized / --authorized-only is required for any active scan.

---

Table of contents

1. What this tool does
2. Pipeline at a glance
3. Module map
4. Architecture
5. Prerequisites
6. Installation
7. Configuration (.env)
8. Running against a domain — pipeline.py
9. Running the legacy orchestrator — recon.py
10. CLI reference
11. Reports and output
12. Safety and scope
13. Cursor MCP integrations
14. Development and CI
15. Troubleshooting
16. Legal use

---

1. What this tool does

Area	Behaviour
OSINT	Passive subdomains (crt.sh, Certspotter, SecurityTrails, HackerTarget, OTX, URLScan, Wayback, RapidDNS, BufferOver, CommonCrawl, ThreatCrowd, assetfinder, findomain, subfinder), Censys TLS cert search, SpiderFoot entity graph (API + CLI auto-select)
DNS	dnsx bulk resolution, alterx permutations, puredns/massdns brute-force, dnsrecon zone-transfer probe, SPF / DMARC / DKIM weakness analysis
Asset mapping	Nmap service/version/OS/NSE (recon_nmap), naabu fast port scan, masscan fallback, Censys host records, Shodan InternetDB (no key needed), tlsx TLS intel, wafw00f WAF fingerprinting
Web audit	Nikto server vulnerability scanner (recon_nikto), Nuclei template scan (medium/high/critical), WAF detection, robots.txt/sitemap scoring, subdomain takeover (40+ providers)
Endpoint discovery	gau + waybackurls + katana + hakrawler corpus, uro dedup, Arjun + ParamSpider parameter discovery, BFS entry-point crawler
Vulnerability scanning	Async SQLi (error + boolean-blind + time-based), reflected XSS, LFI/path traversal, SSRF cloud-metadata, exposed .git/.env/actuator/swagger, security-header audit, open-redirect (13-payload + second-canary confirm)
Secrets	JS secrets (40+ API-key patterns), .git exposure sweep, TruffleHog GitHub-org scan
Credential auditing	HIBP v3 k-anon password check + account breach lookup (recon_creds), John the Ripper hash cracking, SpyCloud enterprise lookup, hash-type identification
Traffic analysis	tshark (Wireshark CLI) pcap analysis — DNS, HTTP hosts, TLS SNI, cleartext-credential detection, top talkers; Snort / Suricata fast-alert + EVE JSON parsing (recon_traffic)
Wireless audit	Aircrack-ng suite — airodump-ng passive scan, handshake crack, monitor-mode mgmt; iw/iwlist fallback (recon_wireless)
Exploitation validation	Metasploit auxiliary scans + check (non-destructive by default); service → module mapping for SMB/HTTP/SSH/RDP/MySQL/MSSQL/FTP (recon_msf)
Cloud	AWS S3, GCS, Azure Blob, Firebase RTDB public-bucket enumeration
Reporting	Timestamped HTML dashboard, JSON, CSV, SARIF 2.1.0 per run

---

2. Pipeline at a glance

pipeline.py — 10-phase unified pipeline

python pipeline.py example.com --authorized

Phases run in strict order; each is independent — a failure never blocks the next.

Phase 0   Preflight      Tool inventory + environment health check
Phase 1   OSINT          Passive subdomains · SpiderFoot · Censys cert search
Phase 2   DNS            Bulk resolve · brute-force · SPF/DMARC/DKIM audit
Phase 3   Assets         naabu + Nmap NSE · Shodan · Censys hosts · tlsx
Phase 4   Web            Nikto · Nuclei · WAF · robots.txt · takeover check · cloud
Phase 5   Endpoints      URL corpus · JS secrets · .git sweep · entry-point crawler
Phase 6   Vulns          SQLi · XSS · LFI · SSRF · open redirect · param discovery
Phase 7   Creds          HIBP breach · SpyCloud · John the Ripper hash cracking
Phase 8   Traffic        tshark pcap analysis · Snort/Suricata alert parsing
Phase 9   MSF            Metasploit auxiliary scans + check (non-destructive)
Phase 10  Report         HTML · JSON · CSV · SARIF

recon.py — legacy orchestrator (8 steps)

The original deep-recon engine with PostgreSQL/Redis persistence, per-IP nmap integration, NVD CVE research, Hydra exploit hooks, and Playwright screenshots. See §9.

---

3. Module map

Module	Phase	Key tools wrapped
recon_passive_subs.py	1	10 passive HTTP sources + assetfinder + findomain
recon_censys.py ★	1, 3	Censys v2 host search, host view, cert search
recon_spiderfoot.py ★	1	SpiderFoot REST API + CLI fallback
recon_dns_brute.py	2	alterx, dnsx, puredns, massdns, dnsrecon
recon_portscan.py	3	naabu, masscan, Shodan InternetDB, tlsx, wafw00f
recon_nmap.py ★	3	nmap -sV / -O / --script, XML parser
recon_nikto.py ★	4	nikto, XML + text output parsers
recon_nuclei.py	4	nuclei JSONL parser
recon_robots.py	4	robots.txt + sitemap sensitivity scoring
recon_takeover.py	4	CNAME dangling + HTTP fingerprint (40+ providers)
recon_surface.py	4	attack surface aggregation + risk score 0–100
recon_cloud_ext.py	4	S3 / GCS / Azure Blob / Firebase
recon_endpoints.py	5	gau, waybackurls, katana, hakrawler, uro
recon_jssecrets.py	5	40+ API-key regex patterns in JS files
recon_secrets_ext.py	5	.git exposure sweep, TruffleHog GitHub-org
recon_entrypoints.py	5	BFS crawler — params / forms / JS fetch
recon_webvulns.py	6	SQLi / XSS / LFI / SSRF / headers
recon_openredirect.py	6	13-payload open-redirect with second canary
recon_params.py	6	Arjun, ParamSpider, corpus extraction
recon_fuzz.py	6	feroxbuster common.txt sweep (opt-in)
recon_creds.py ★	7	HIBP v3 k-anon + account lookup, John, SpyCloud
recon_traffic.py ★	8	tshark pcap, Snort fast-alert, Suricata EVE JSON
recon_msf.py ★	9	msfconsole check + auxiliary scanners
recon_wireless.py ★	standalone	aircrack-ng suite, airodump-ng, iw/iwlist
recon_toolrunner.py	all	centralised tool resolver + async subprocess runner
recon_platform.py	all	retry/backoff, logging, scope allowlist, TLS intel
recon_exports.py	10	HTML / CSV / SARIF 2.1.0 writer
recon_parsing.py	all	nmap + gobuster output parsers

★ = added in latest update (April 2026)

---

4. Architecture

flowchart TD
  subgraph entry["Entry points"]
    PL["pipeline.py\n(unified 10-phase)"]
    RC["recon.py\n(legacy orchestrator)"]
  end

  subgraph phases["pipeline.py phases"]
    P1["Phase 1 · OSINT\npassive_subs · censys · spiderfoot"]
    P2["Phase 2 · DNS\ndns_brute · dnsrecon"]
    P3["Phase 3 · Assets\nnmap · portscan · censys hosts"]
    P4["Phase 4 · Web\nnikto · nuclei · takeover · cloud"]
    P5["Phase 5 · Endpoints\nendpoints · jssecrets · secrets_ext"]
    P6["Phase 6 · Vulns\nwebvulns · openredirect · params"]
    P7["Phase 7 · Creds\ncreds (HIBP · John · SpyCloud)"]
    P8["Phase 8 · Traffic\ntraffic (tshark · Snort)"]
    P9["Phase 9 · MSF\nmsf (auxiliary · check)"]
    P10["Phase 10 · Report\nHTML · JSON · CSV · SARIF"]
  end

  subgraph storage["Storage (recon.py)"]
    PG[("PostgreSQL")]
    RD[("Redis")]
    MEM["In-memory fallback"]
  end

  PL --> P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7 --> P8 --> P9 --> P10
  RC --> storage
  P10 --> OUT["results/<target>/\nreport.html\nreport.json\nreport.csv\nreport.sarif"]

Loading

---

5. Prerequisites

• Python 3.10+ (3.12+ tested)
• Network egress to target hosts + passive API endpoints
• Written authorisation for every target in scope

Security tools

Install as many as possible. Phase 0 (preflight) lists exactly what is and is not found.

Linux / Kali / Ubuntu

# ProjectDiscovery Go tools
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/naabu/v2/cmd/naabu@latest
go install -v github.com/projectdiscovery/dnsx/cmd/dnsx@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install -v github.com/projectdiscovery/katana/cmd/katana@latest
go install -v github.com/projectdiscovery/tlsx/cmd/tlsx@latest
go install -v github.com/projectdiscovery/alterx/cmd/alterx@latest
go install    github.com/lc/gau/v2/cmd/gau@latest
go install    github.com/tomnomnom/waybackurls@latest
go install    github.com/tomnomnom/assetfinder@latest
go install    github.com/hakluke/hakrawler@latest
go install    github.com/d3mondev/puredns/v2@latest
go install    github.com/OJ/gobuster/v3@latest
go install    github.com/trufflesecurity/trufflehog/v3@latest

# System packages
sudo apt install -y nmap nikto wireshark-common tshark john aircrack-ng \
                    wafw00f masscan dnsrecon

# Python CLI tools
pipx install arjun paramspider uro

# Metasploit
curl https://raw.githubusercontent.com/rapid7/metasploit-omnibus/master/config/templates/metasploit-framework-wrappers/msfupdate.erb | sudo ruby

# SpiderFoot (optional — richer OSINT)
pip install spiderfoot

Windows (elevated PowerShell)

# One-shot installer (covers nmap, Go tools, pipx packages, SecLists)
powershell -ExecutionPolicy Bypass -File scripts\install-tools.ps1

Then install separately:

• Nmap: nmap.org/download
• Nikto: github.com/sullo/nikto/releases
• Wireshark / tshark: wireshark.org/download (tshark is bundled)
• Metasploit: metasploit.com/download
• John the Ripper: openwall.com/john
• Aircrack-ng: aircrack-ng.org/downloads

Full tool reference:

Tool	Phase	Install
nmap	3	choco install nmap
nikto	4	apt install nikto / GitHub release
nuclei	4	go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
naabu	3	go install github.com/projectdiscovery/naabu/v2/cmd/naabu@latest
subfinder	1	go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
httpx	all	go install github.com/projectdiscovery/httpx/cmd/httpx@latest
dnsx	2	go install github.com/projectdiscovery/dnsx/cmd/dnsx@latest
tlsx	3	go install github.com/projectdiscovery/tlsx/cmd/tlsx@latest
katana	5	go install github.com/projectdiscovery/katana/cmd/katana@latest
alterx	2	go install github.com/projectdiscovery/alterx/cmd/alterx@latest
gau	5	go install github.com/lc/gau/v2/cmd/gau@latest
waybackurls	5	go install github.com/tomnomnom/waybackurls@latest
assetfinder	1	go install github.com/tomnomnom/assetfinder@latest
hakrawler	5	go install github.com/hakluke/hakrawler@latest
gobuster	6	go install github.com/OJ/gobuster/v3@latest
feroxbuster	6	GitHub release binary
puredns	2	go install github.com/d3mondev/puredns/v2@latest
trufflehog	5	go install github.com/trufflesecurity/trufflehog/v3@latest
wafw00f	4	pipx install wafw00f
arjun	6	pipx install arjun
paramspider	6	pipx install paramspider
dnsrecon	2	pipx install dnsrecon
uro	5	pipx install uro
tshark	8	Wireshark installer / apt install tshark
john	7	apt install john / openwall.com/john
aircrack-ng	standalone	apt install aircrack-ng
msfconsole	9	Metasploit installer
hydra	recon.py	apt install hydra / WSL
masscan	3	apt install masscan / WSL
searchsploit	recon.py	ExploitDB clone + WSL
findomain	1	GitHub release binary
SpiderFoot	1	pip install spiderfoot

---

6. Installation

# 1. Clone
git clone https://github.com/Richflexpix/recon2exploit.git
cd recon2exploit

# 2. Create virtual environment
python3 -m venv .venv
source .venv/bin/activate          # Linux/macOS
# .venv\Scripts\activate.bat       # Windows

# 3. Install Python dependencies
pip install -r requirements.txt
playwright install chromium        # needed for screenshots in recon.py

# 4. Copy and configure environment
cp .env.example .env
# Edit .env — fill in API keys and DB credentials

# 5. (recon.py only) Create PostgreSQL database
psql -h 127.0.0.1 -U postgres -c "CREATE DATABASE asset_db;"

# 6. (Windows) Run the tool installer
powershell -ExecutionPolicy Bypass -File scripts\install-tools.ps1

---

7. Configuration (.env)

Copy .env.example → .env. The tool runs without any API keys (passive + free-tier tools only), but the keys below unlock significantly richer data.

Required for full functionality

Variable	Phase	Where to get it
CENSYS_API_ID + CENSYS_API_SECRET	1, 3	search.censys.io/account/api
HIBP_API_KEY	7	haveibeenpwned.com/API/Key
SECURITYTRAILS_API_KEY	1	securitytrails.com/app/account
SHODAN_API_KEY	3	account.shodan.io

Optional enrichment

Variable	Phase	Purpose
CERTSPOTTER_API_KEY	1	Cert transparency feed
HUNTER_API_KEY	1	Email discovery
CHAOS_API_KEY	1	ProjectDiscovery Chaos subdomains
SPIDERFOOT_URL	1	Set to http://127.0.0.1:5001 when running SpiderFoot locally
SPIDERFOOT_API_KEY	1	SpiderFoot API key (if auth enabled)
SPYCLOUD_API_KEY	7	SpyCloud enterprise breach records
GITHUB_TOKEN	5	TruffleHog GitHub-org scan (read:org scope)
NVD_API_KEY	recon.py	Faster NVD CVE lookups
MSF_HOST / MSF_PORT / MSF_PASS	9	Metasploit MSGRPC daemon

Core settings

Variable	Default	Purpose
POSTGRES_DSN	postgresql://postgres:CHANGE_ME@127.0.0.1:5432/asset_db	recon.py persistence
REDIS_URL	redis://127.0.0.1:6379	recon.py caching
CONFIDENCE_THRESHOLD	0.8	Min confidence for vuln inclusion
LOG_LEVEL	INFO	DEBUG / INFO / WARNING
LOG_FORMAT	text	text or json
NMAP_SCRIPTS	vuln,default	NSE script categories
GOBUSTER_WORDLIST_PROFILE	small	small / medium / large
WSL_DISTRO	Ubuntu	WSL distro for hydra/searchsploit
MAX_PARALLEL_HOSTS	4	Parallel fingerprint workers

---

8. Running against a domain — pipeline.py

Quickest start

# Linux/macOS
./run.sh example.com --authorized

# Windows
run.bat example.com --authorized

# Direct Python (any OS)
python pipeline.py example.com --authorized

Phase control

# Run all phases (default)
python pipeline.py example.com --authorized

# OSINT + DNS only (no active probing)
python pipeline.py example.com --authorized --phases osint,dns

# Web-focused: assets, web, endpoints, vulns
python pipeline.py example.com --authorized --phases assets,web,endpoints,vulns

# Skip MSF (not installed)
python pipeline.py example.com --authorized --skip-phases msf

# Include active DNS brute-force + alterx permutations
python pipeline.py example.com --authorized --dns-bruteforce --alterx

# Limit to 5 hosts (faster, less aggressive)
python pipeline.py example.com --authorized --max-hosts 5

# Verbose debug output
python pipeline.py example.com --authorized -v

Traffic analysis (Phase 8)

# Analyse an existing pcap
python pipeline.py example.com --authorized --phases traffic --pcap capture.pcap

# Parse Snort / Suricata alert log
python pipeline.py example.com --authorized --phases traffic \
    --snort-log /var/log/snort/alert

# Both together
python pipeline.py example.com --authorized \
    --pcap capture.pcap --snort-log /var/log/suricata/fast.log

Credential auditing (Phase 7)

# Crack a file of discovered hashes with John
python pipeline.py example.com --authorized --phases creds \
    --hashes-file found_hashes.txt \
    --wordlist /usr/share/wordlists/rockyou.txt

Output

results/
└── example.com/
    ├── report.html   ← Visual dashboard — open in browser
    ├── report.json   ← Full machine-readable data
    ├── report.csv    ← Import into Jira / ticketing tools
    └── report.sarif  ← Import into GitHub / SonarQube

pipeline.py CLI flags

Flag	Default	Description
--authorized	—	Required for all active phases
--phases PHASES	all	Comma-separated phases to run
--skip-phases PHASES	—	Comma-separated phases to skip
--output-dir DIR	results/	Report output directory
-v / --verbose	off	Enable DEBUG logging
--dns-bruteforce	off	Active DNS brute-force (puredns/massdns)
--alterx	off	alterx subdomain permutations
--max-hosts N	10	Max hosts for port scan / Nikto / Nmap
--pcap FILE	—	pcap file for tshark analysis (Phase 8)
--snort-log FILE	—	Snort/Suricata alert log (Phase 8)
--hashes-file FILE	—	Hash file for John the Ripper (Phase 7)
--wordlist FILE	—	Wordlist for John the Ripper (Phase 7)

---

9. Running the legacy orchestrator — recon.py

recon.py retains the full original feature set: PostgreSQL/Redis persistence, NVD CVE research, Hydra exploitation hooks, Playwright screenshots, and checkpoint/resume support.

# Diagnostics (no --authorized-only required)
python recon.py --doctor

# Compare two report JSON files
python recon.py --diff-reports results/old.json results/new.json

# Scan all domains in domains.txt
python recon.py --authorized-only

# Single target with scope file and runtime cap
python recon.py -t corp.example.com --authorized-only \
    --scope-file scope.txt --max-runtime-minutes 45

# Dry plan (no scanning)
python recon.py --authorized-only --plan -t example.com

# Enable exploitation (off by default)
python recon.py -t example.com --authorized-only --allow-exploit

# Quick mode (skip deep nmap + gobuster inside integrated recon)
python recon.py --authorized-only --quick

# Export CSV and SARIF alongside JSON
python recon.py -t example.com --authorized-only \
    --export-csv results/findings.csv \
    --export-sarif results/findings.sarif

recon.py legacy steps

Step	What runs
1	Initialize PostgreSQL / Redis (in-memory fallback)
2	Passive + active subdomain enumeration; IP + email discovery
3	Async TCP banner probes + nmap NSE service fingerprinting
4	gobuster directory scan (engine-level)
5	Priority exposure path checks
6	Integrated domain recon: DNS, nmap per-IP, gobuster, page intel, cloud
6b–6o	Attack-surface enrichments (robots, takeover, web vulns, JS secrets, entry points, open redirect, endpoint corpus, params, port intel, cloud, secrets, DNS deep, feroxbuster)
7	NVD CVE research per service/version
7b	Attack surface mapping + risk score
7c	Nuclei template scan
8	Exploitation pass (opt-in) + Playwright screenshots + full report

Full flag reference is in the original README section; run python recon.py --help for all options.

---

10. CLI reference

pipeline.py — phase names

preflight  osint  dns  assets  web  endpoints  vulns  creds  traffic  msf  report

Common patterns

# Check tool health without scanning
python pipeline.py any.domain --phases preflight

# Run from OSINT through vulns, skip MSF
python pipeline.py target.com --authorized \
    --phases osint,dns,assets,web,endpoints,vulns

# Full run with brute-force, verbose, custom output dir
python pipeline.py target.com --authorized \
    --dns-bruteforce --alterx -v \
    --output-dir /engagements/target-com/

# Only traffic and cred phases (post-exploitation review)
python pipeline.py target.com --authorized \
    --phases creds,traffic \
    --pcap /captures/target.pcap \
    --hashes-file /loot/hashes.txt \
    --wordlist /usr/share/wordlists/rockyou.txt

---

11. Reports and output

pipeline.py report structure (JSON)

{
  "target": "example.com",
  "run_id": "20260425_143022",
  "risk_score": 72,               // 0–100 composite
  "subdomains": [...],
  "ips": [...],
  "emails": [...],
  "open_ports": { "1.2.3.4": [80, 443, 8080] },
  "nmap_services": [...],
  "shodan_enrichment": { ... },
  "tls": [...],
  "nikto": [...],                  // per-URL reports
  "nuclei": [...],                 // parsed findings
  "wafs": [...],
  "robots": [...],
  "takeover": { "findings": [...] },
  "attack_surface": { ... },
  "cloud": { "exposed_buckets": [...] },
  "endpoints": { "total": 4821, "api_paths": [...] },
  "js_secrets": [...],
  "secrets_ext": { "exposed_git": [...] },
  "entry_points": { "ssrf_candidates": [...] },
  "web_vulns": [...],
  "open_redirects": [...],
  "params": { "ssrf_params": [...] },
  "breach_results": [...],         // HIBP per email
  "traffic": { "dns_queries": [...], "cleartext_creds": [...] },
  "snort": { "alerts": [...] },
  "msf_audit": [...],
  "findings": [...],               // consolidated for CSV/SARIF export
  "phases_run": [...],
  "phases_failed": [...]
}

Risk score bands

Score	Band	Meaning
0–25	Low	Informational only
26–49	Medium	Minor findings — monitor
50–74	High	Actionable findings — remediate
75–89	Critical	Immediate attention required
90–100	Critical+	Active exploitation risk

Finding types

Type	Source	Action
nuclei	Nuclei template	Check CVE/template for fix
nikto	Nikto server audit	Patch server software
web_vuln	SQLi/XSS/LFI probe	Fix injection points
js_secret	API key in JS	Rotate key immediately
breach	HIBP account lookup	Force password reset
takeover	Dangling CNAME	Delete or reclaim subdomain
cloud_bucket	Public bucket	Set bucket to private

---

12. Safety and scope

Mechanism	Purpose
--authorized / --authorized-only	Required flag — tool refuses active scans without it
--scope-file FILE	Allowlist of hosts/CIDRs — anything outside is dropped
--max-hosts N	Limits scan breadth for port/web/nmap phases
--phases / --skip-phases	Surgical control — run only what you need
--max-runtime-minutes N	Per-target wall-clock cap (recon.py)
MSF check mode	Metasploit auxiliary only — no active exploitation without caller opt-in
HIBP k-anonymity	Full passwords never sent — only the 5-char SHA-1 prefix
Wireless opt-in	use_monitor_mode=False by default in recon_wireless
.gitignore	.env, results/, *.pcap, *.hash, domains.txt all excluded from git

---

13. Cursor MCP integrations

.cursor/mcp.json ships two optional integrations:

Cyware (stdio — local Go)

Connects to Cyware CTIX/Orchestrate via cyware-mcpserver.

git clone https://github.com/cyware-labs/cyware-mcpserver.git
cd cyware-mcpserver && go mod tidy
cd cmd && go build -o cyware-mcp .

Configure cyware-mcpserver/cmd/config.yaml with your API credentials, then Cursor picks up the cyware-mcp entry.

Wazuh SIEM (remote HTTP — Docker)

Wazuh MCP Server at http://localhost:3000/mcp:

cd wazuh-mcp-server
cp .env.example .env   # set WAZUH_HOST, WAZUH_USER, WAZUH_PASS
docker compose up -d
curl http://localhost:3000/health

Set MCP_API_KEY in your shell to the bearer token from the server logs. Use mcphost for terminal-based LLM chat:

mcphost -m ollama:qwen2.5:7b

---

14. Development and CI

# Install dev dependencies
pip install -r requirements.txt -r requirements-dev.txt

# Run tests
pytest

# Lint
ruff check recon_*.py pipeline.py tests

# Type check
mypy recon_parsing.py recon_platform.py recon_exports.py recon_surface.py \
     recon_toolrunner.py tests/test_parsing.py tests/test_platform.py

# AST smoke test (all .py files must parse)
python -c "
import ast, os
files = [f for f in os.listdir('.') if f.endswith('.py')]
[ast.parse(open(f, encoding='utf-8').read()) for f in files]
print(f'OK — {len(files)} files parsed')
"

GitHub Actions (.github/workflows/ci.yml) runs install → ruff → mypy → AST smoke → pytest on Python 3.11 and 3.12.

Windows installer (scripts/install-tools.ps1) covers: Chocolatey nmap/golang, all Go-based tools, pipx packages (arjun, paramspider, wafw00f, dnsrecon, uro), TruffleHog, feroxbuster binary, findomain binary, SecLists clone, nikto, john, tshark, and WSL hints.

---

15. Troubleshooting

Symptom	Cause	Fix
Phase 0 shows many MISSING tools	Tools not installed or not on PATH	Run scripts/install-tools.ps1 (Windows) or see §5 apt/go commands
services fingerprinted: 0	DNS resolution failed / no open ports on probed set	Check DNS; confirm subdomains resolve; try --max-hosts 1 first
Nikto / Nmap skipped	Binary not found	Install tool; PATH must include install directory
HIBP returns 401	Missing API key	Set HIBP_API_KEY in .env; k-anon password checks are free (no key needed)
Censys returns no data	Credentials not set	Set CENSYS_API_ID + CENSYS_API_SECRET in .env
Metasploit phase skipped	msfconsole not found	Install Metasploit or --skip-phases msf
SpiderFoot returns empty	Server not running	Set SPIDERFOOT_URL or install sfcli
tshark no output	No pcap supplied / tshark not installed	Pass --pcap <file> or install Wireshark
NSE / vulners errors	Script not installed with Nmap	Set NMAP_SCRIPTS=vuln in .env
PostgreSQL errors (recon.py)	Wrong DSN / DB not created	Fix .env; orchestrator falls back to memory
Playwright errors (recon.py)	Chromium not installed	python -m playwright install chromium
Hydra/searchsploit not running on Windows	No native binary; WSL not set up	Install in WSL; set WSL_DISTRO in .env
Long Nmap after Ctrl+C	Child process still running	Latest recon.py sends terminate/kill on cancellation
WinError 10054 / ConnectionResetError	Remote host RST idle TCP probes	Harmless — filtered to DEBUG; CDN/WAF behaviour

Stop a run: Press Ctrl+C once — exits with code 130, partial results are saved.

---

16. Legal use

You must hold written permission covering specific hosts, IP ranges, methods, and timing for every engagement. Unauthorised scanning and exploitation is illegal in most jurisdictions. This software is provided for defensive and authorised testing only; you are solely responsible for compliance with applicable laws and contracts.

---

Last updated: April 2026 — added recon_nmap, recon_censys, recon_nikto, recon_spiderfoot, recon_msf, recon_traffic, recon_creds, recon_wireless, unified pipeline.py, run.sh/run.bat launchers, and this revised README.