GitHub - shahariarnafees/reconx: Async recon automation framework — orchestrates subfinder, httpx, naabu, nmap, katana & more into a 5-phase pipeline for pentesters & bug bounty hunters.

 ██████╗ ███████╗ ██████╗ ██████╗ ███╗   ██╗██╗  ██╗
 ██╔══██╗██╔════╝██╔════╝██╔═══██╗████╗  ██║╚██╗██╔╝
 ██████╔╝█████╗  ██║     ██║   ██║██╔██╗ ██║ ╚███╔╝ 
 ██╔══██╗██╔══╝  ██║     ██║   ██║██║╚██╗██║ ██╔██╗ 
 ██║  ██║███████╗╚██████╗╚██████╔╝██║ ╚████║██╔╝ ██╗
 ╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝

Professional Reconnaissance Automation Framework

ReconX is a modular, async-first external reconnaissance automation framework that orchestrates 11 industry-standard security tools through a single, beautiful terminal interface.
Built for penetration testers, bug bounty hunters, and red teamers who demand speed, accuracy, and professionalism.

Features • Installation • Usage • Scan Modes • Output • Tools

⚠️ AUTHORIZED USE ONLY — ReconX is designed exclusively for authorized penetration testing, bug bounty programmes, and security research. Only use this tool against systems you own or have explicit written permission to test. Unauthorized use is illegal.

📖 Overview

Modern external reconnaissance demands orchestrating dozens of tools, parsing inconsistent outputs, deduplicating results, and correlating findings across multiple data sources — all while racing against time. Doing this manually is slow, error-prone, and inconsistent.

ReconX solves this. It automates the complete external reconnaissance pipeline in five sequential phases, running tools in parallel where possible, normalizing every output into a unified structure, and presenting everything through a professional Rich-powered terminal dashboard.

Target Domain
     │
     ▼
┌─────────────────────────────────────────────────────────┐
│  Phase 1 ── Subdomain Enumeration                       │
│             subfinder · amass · assetfinder             │
├─────────────────────────────────────────────────────────┤
│  Phase 2 ── Live Host Discovery & Firewall Detection    │
│             httpx · wafw00f                             │
├─────────────────────────────────────────────────────────┤
│  Phase 3 ── Port & Service Discovery                    │
│             naabu · nmap                                │
├─────────────────────────────────────────────────────────┤
│  Phase 4 ── URL Collection                              │
│             katana · gau · waybackurls                  │
├─────────────────────────────────────────────────────────┤
│  Phase 5 ── Endpoint Classification                     │
│             login · admin · api · upload · backup ···   │
└─────────────────────────────────────────────────────────┘
     │
     ▼
Structured Results  +  JSON / TXT / HTML Reports

✨ Features

🔍 Reconnaissance Engine

5-phase full pipeline — subdomain enumeration → live host discovery → port scanning → URL collection → endpoint classification
Parallel async execution — tools run concurrently via asyncio.gather, maximizing throughput
Fault isolation — a failing tool never stops the pipeline; results from all other tools are preserved
Automatic deduplication — subdomains, URLs, and endpoints are deduplicated across all tool outputs
WAF & firewall fingerprinting — every live host is checked against known WAF signatures via wafw00f

🛠️ Three Scan Modes

Mode	Tools	Use Case
Technology Detection	httpx + internal fingerprinter + wafw00f	Quick tech stack, WAF identification, and security header audit
Light Recon	subfinder + amass + assetfinder	Fast passive subdomain enumeration only
Full Recon	All 11 tools	Complete external attack surface mapping

🎨 Professional Terminal UI

Animated ASCII banner with colour cycling
Rich-powered interactive dashboard with numbered menu
Per-phase live progress bars with spinners and elapsed timers
Post-scan results dashboard with structured tables and stat panels
Colour-coded status codes, severity-based endpoint highlighting

📊 Endpoint Classification

Automatically classifies collected URLs into twelve sensitivity categories:

Category	Example Patterns
`[LOGIN]`	`/login`, `/signin`, `/auth`, `/sso`, `/oauth`
`[ADMIN]`	`/admin`, `/dashboard`, `/cms`, `/wp-admin`, `/panel`
`[API]`	`/api/`, `/v1/`, `/graphql`, `/swagger`, `/rest/`
`[UPLOAD]`	`/upload`, `/file`, `/import`, `/attachment`, `/media`
`[BACKUP]`	`.bak`, `.sql`, `.old`, `.backup`, `/dump`
`[CONFIG]`	`.env`, `.yml`, `.cfg`, `.ini`, `settings`, `secrets`
`[DEV]`	`/dev`, `/staging`, `/test`, `/debug`, `/sandbox`
`[SENSITIVE]`	`password`, `token`, `secret`, `credential`, `private`
`[DATABASE]`	`phpmyadmin`, `adminer`, `mongo-express`, `redisinsight`
`[GIT]`	`.git/config`, `.git/HEAD`, `.gitmodules`, `.svn/`
`[CLOUD]`	`.aws/credentials`, `metadata/latest`, `169.254.169.254`
`[MONITORING]`	`/metrics`, `/health`, `/actuator`, `/jmx`, `/nginx_status`

ℹ️ Matching runs against the URL path and query string only — never the hostname — so a subdomain like login-portal.example.com no longer triggers a false match just because "login" appears in its name.

📁 Structured Output

All results are automatically saved to a structured directory:

results/<target>/
├── subdomains.txt        ← all discovered subdomains
├── live_hosts.txt        ← probed live hosts
├── urls.txt              ← all collected URLs
├── sensitive_urls.txt    ← classified sensitive URLs
├── endpoints.txt         ← categorised endpoints
├── ports.txt             ← open ports and services
├── technologies.txt      ← fingerprinted tech stacks
├── waf_results.txt       ← WAF / firewall detection results
├── summary.json          ← machine-readable full summary
├── report_<ts>.json      ← detailed JSON report
├── report_<ts>.txt       ← human-readable TXT report
├── report_<ts>.html      ← self-contained HTML report
└── logs.txt              ← timestamped scan log

🔒 Technology Fingerprinting

Detects: Web Server · CDN · WAF · CMS · Frameworks · JS Libraries · Language · Hosting Provider · Missing Security Headers

🔧 Integrated Tools

Tool	Category	Role	Source
subfinder	Subdomain	Passive enumeration from 40+ sources	ProjectDiscovery
amass	Subdomain	Deep OSINT-based enumeration	OWASP
assetfinder	Subdomain	Fast subdomain discovery	TomNomNom
httpx	Live Host	HTTP probing, tech detection, status codes	ProjectDiscovery
wafw00f	Firewall	WAF / firewall fingerprinting	EnableSecurity
naabu	Port	Fast SYN/CONNECT port scanning	ProjectDiscovery
nmap	Port	Deep service/version/OS detection	Nmap Project
katana	URL	Next-gen web crawler with JS support	ProjectDiscovery
gau	URL	Historical URLs from AlienVault, Wayback, URLScan	@lc
waybackurls	URL	Wayback Machine URL extraction	TomNomNom
dnsx	DNS	Multi-record DNS resolution at scale	ProjectDiscovery

Required: subfinder, httpx
Optional: all others (ReconX skips missing tools gracefully)

📋 Prerequisites

Python 3.9 or higher
Go 1.21 or higher (for Go-based tools)
Linux or macOS (Windows WSL2 supported)

🚀 Installation

1 — Clone the repository

git clone https://github.com/shahariarnafees/reconx.git
cd reconx

2 — Install Python dependencies

pip3 install -r requirements.txt

3 — Install Go-based recon tools

# Required
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest

# Recommended
go install -v github.com/projectdiscovery/naabu/v2/cmd/naabu@latest
go install -v github.com/projectdiscovery/katana/cmd/katana@latest
go install -v github.com/projectdiscovery/dnsx/cmd/dnsx@latest
go install    github.com/tomnomnom/assetfinder@latest
go install    github.com/tomnomnom/waybackurls@latest
go install    github.com/lc/gau/v2/cmd/gau@latest

# Optional
go install -v github.com/owasp-amass/amass/v4/...@master

# WAF detection (new in v1.2.0)
pip3 install wafw00f

4 — Install nmap (system package)

# Debian / Ubuntu
sudo apt install nmap -y

# macOS
brew install nmap

# Arch Linux
sudo pacman -S nmap

5 — Ensure Go bin is in your PATH

export PATH=$PATH:$(go env GOPATH)/bin
# Add this line to your ~/.bashrc or ~/.zshrc to make it permanent

6 — Launch ReconX

python3 main.py

🖥️ Usage

Starting ReconX

python3 main.py

ReconX will:

Display the animated banner
Detect your OS and Python version
Check which tools are installed and display a status table
Prompt you to enter a target domain

Target Input

ReconX accepts any of the following formats — it normalises them automatically:

example.com
sub.example.com
https://example.com
http://example.com
*.example.com
https://example.com/some/path

Main Menu

╭──────┬────────────────────────┬──────────────────────────────────────────╮
│  #   │ Module                 │ Description                              │
├──────┼────────────────────────┼──────────────────────────────────────────┤
│  1   │ Technology Detection   │ HTTP fingerprinting · CDN · WAF · CMS    │
│  2   │ Light Recon Scan       │ Passive subdomain enumeration only       │
│  3   │ Full Recon Scan        │ Complete 5-phase recon pipeline          │
│  4   │ View Previous Results  │ Browse earlier scan results              │
│  5   │ Export Reports         │ Generate JSON / HTML / TXT reports       │
│  6   │ Change Target          │ Set a new target domain                  │
│  0   │ Exit                   │ Terminate ReconX                         │
╰──────┴────────────────────────┴──────────────────────────────────────────╯

📡 Scan Modes

Option 1 — Technology Detection

Performs rapid HTTP-based fingerprinting against the target and its live subdomains.

Detects:

Web server (Nginx, Apache, IIS, LiteSpeed, Caddy…)
CDN provider (Cloudflare, AWS CloudFront, Fastly, Akamai…)
WAF (Cloudflare WAF, AWS WAF, ModSecurity, Imperva, Sucuri… — fingerprinted via wafw00f)
CMS (WordPress, Drupal, Joomla, Shopify, Ghost…)
Frameworks (Laravel, Django, Rails, Next.js, Express…)
JavaScript libraries (React, Vue, Angular, jQuery…)
Hosting provider (AWS, GCP, Azure, DigitalOcean…)
Missing security headers (HSTS, CSP, X-Frame-Options…)

# Select option 1 from the menu after entering your target

Option 2 — Light Recon Scan

Runs subfinder, amass, and assetfinder in parallel for fast passive subdomain enumeration. No active probing — safe for initial scope mapping.

Output:

Deduplicated subdomain list
Per-tool discovery counts
Results saved to results/<target>/subdomains.txt

Option 3 — Full Recon Scan

The complete 5-phase external attack surface mapping pipeline.

Phase 1  Subdomain Enumeration     subfinder + amass + assetfinder  (parallel)
Phase 2  Live Host & Firewall      httpx + wafw00f                  (async)
Phase 3  Port & Service Discovery  naabu + nmap                     (parallel)
Phase 4  URL Collection            katana + gau + waybackurls       (parallel)
Phase 5  Endpoint Classification   internal engine                  (instant)

Estimated runtime:

Target Size	Subdomains	Est. Duration
Small	< 50	3–8 min
Medium	50–500	8–20 min
Large	500–2000	20–45 min

📊 Output Examples

Results Dashboard

After a full scan, ReconX displays a rich terminal dashboard:

◆  RECONX RESULTS DASHBOARD  ◆

TARGET INFORMATION
  Target    │ example.com
  Scan Type │ FULL
  Duration  │ 00h 08m 24s

DISCOVERY STATISTICS
  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
  │     247      │ │      89      │ │    3,412     │ │     143      │
  │  Subdomains  │ │  Live Hosts  │ │  Total URLs  │ │  Sensitive   │
  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
  │     312      │ │      47      │ │      6       │
  │  Open Ports  │ │     Tech     │ │  WAFs Found  │
  └──────────────┘ └──────────────┘ └──────────────┘

Summary JSON (`summary.json`)

{
  "target": "example.com",
  "scan_type": "full",
  "start_time": "2026-06-18T11:39:58",
  "end_time": "2026-06-18T11:48:22",
  "duration_seconds": 504.3,
  "stats": {
    "total_subdomains": 247,
    "live_hosts": 89,
    "total_urls": 3412,
    "sensitive_urls": 143,
    "open_ports": 312,
    "technologies": 47,
    "waf_detected": 6
  },
  "subdomains": ["api.example.com", "mail.example.com", "..."],
  "ports": {
    "api.example.com": [
      { "port": 443, "service": "https", "version": "OpenSSL 3.0" }
    ]
  }
}

🏗️ Project Structure

reconx/
├── main.py                        ← Entry point
├── requirements.txt
├── README.md
│
├── config/
│   └── settings.py                ← Tool configs, patterns, theme
│
├── core/
│   ├── banner.py                  ← Animated terminal banner
│   ├── logger.py                  ← Rotating file + console logging
│   ├── validator.py               ← Domain sanitisation & validation
│   ├── dependency_checker.py      ← Tool availability verification
│   └── result_processor.py        ← Dedup, classify, correlate
│
├── models/
│   └── scan_models.py             ← Pydantic data models
│
├── modules/                       ← One file per external tool
│   ├── base_module.py             ← Async subprocess base class
│   ├── subdomain/                 ← subfinder · amass · assetfinder
│   ├── live_host/                 ← httpx
│   ├── port/                      ← naabu · nmap
│   ├── url/                       ← katana · gau · waybackurls
│   ├── tech/                      ← HTTP fingerprint engine
│   └── firewall/                  ← wafw00f
│
├── scanners/
│   ├── light_scan.py              ← Light recon orchestrator
│   ├── full_scan.py               ← Full pipeline orchestrator
│   └── tech_scan.py               ← Tech detection orchestrator
│
├── ui/
│   ├── dashboard.py               ← Interactive Rich menu
│   └── results_display.py         ← Post-scan Rich dashboard
│
├── storage/
│   └── manager.py                 ← File I/O and results directory
│
└── reports/
    └── exporter.py                ← JSON · TXT · HTML report generator

⚙️ Adding New Tools

ReconX's modular architecture makes it straightforward to integrate new tools.

Step 1 — Add the tool config to config/settings.py:

"mynewscanner": {
    "binary":      "mynewscanner",
    "timeout":     300,
    "base_args":   ["-silent", "-json"],
    "required":    False,
    "category":    "subdomain",
    "description": "My new scanner",
    "install":     "go install github.com/user/mynewscanner@latest",
},

Step 2 — Create modules/<category>/mynewscanner.py:

from modules.base_module import BaseModule
from config.settings import TOOL_CONFIGS

class MyNewScannerModule(BaseModule):
    tool_name = "mynewscanner"

    def build_command(self, target: str):
        cfg = TOOL_CONFIGS["mynewscanner"]
        return [cfg["binary"], *cfg["base_args"], "-d", target]

    def parse_output(self, raw_lines):
        return [line.strip() for line in raw_lines if line.strip()]

Step 3 — Import and call it inside scanners/full_scan.py or light_scan.py.

📦 Dependencies

Python Libraries

Package	Version	Purpose
`rich`	≥ 13.7	Terminal UI, tables, progress bars, panels
`pydantic`	≥ 2.5	Data validation and typed models
`requests`	≥ 2.31	HTTP technology fingerprinting
`aiohttp`	≥ 3.9	Async HTTP operations
`aiofiles`	≥ 23.2	Async file I/O

🔑 Configuration

All tool arguments and framework settings live in config/settings.py. Key sections:

# Tool timeout (seconds)
TOOL_CONFIGS["subfinder"]["timeout"] = 300

# Add custom sensitive URL patterns
SENSITIVE_PATTERNS["custom"] = ["mypanel", "internal-api"]

# Adjust scan concurrency inside scanner files
# httpx: -t (threads), -rl (rate-limit)
# naabu: -rate, -c (workers)

🤝 Contributing

Contributions, bug reports, and feature requests are welcome.

Fork the repository
Create a feature branch (git checkout -b feature/new-tool-integration)
Commit your changes (git commit -m 'feat: add nuclei integration')
Push to the branch (git push origin feature/new-tool-integration)
Open a Pull Request

Please follow the existing module pattern and ensure new tools are added with proper error handling and timeout management.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

👤 Author

Shahariar Nafees

⚠️ Legal Disclaimer

This tool is provided for educational purposes and authorized security testing only.

Only use ReconX against systems you own or have explicit written permission to test
The author is not responsible for any misuse or damage caused by this tool
Unauthorized reconnaissance is illegal in most jurisdictions
Always operate within the scope of an authorized engagement or bug bounty programme

If ReconX helped your workflow, please ⭐ star the repository.

Made with ❤️ for the security community

Name		Name	Last commit message	Last commit date
config		config
core		core
models		models
modules		modules
reports		reports
scanners		scanners
storage		storage
ui		ui
README.md		README.md
main.py		main.py
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation