<div align="center">

ReconNinja

21-phase automated reconnaissance framework for authorized security testing.

⚠ Use only against targets you own or have explicit written permission to test.

📄 Documentation at doc.emonpersonal.xyz

</div>

---

What it does

ReconNinja automates every phase of a reconnaissance engagement into a single command. Point it at a domain or IP and it drives the full pipeline — passive OSINT, port scanning, web discovery, vulnerability scanning, cloud intelligence, credential hunting, and AI-powered threat analysis — then generates HTML, JSON, and Markdown reports.

---

Install

# From GitHub (always latest)
pip install git+https://github.com/ExploitCraft/ReconNinja.git

# From PyPI
pip install ReconNinja

# From source (recommended)
git clone https://github.com/ExploitCraft/ReconNinja.git
cd ReconNinja && chmod +x install.sh && ./install.sh

# With optional dependencies
pip install "ReconNinja[full]"    # AI providers + Shodan + dnspython
pip install "ReconNinja[ai]"      # AI providers only
pip install "ReconNinja[dns]"     # dnspython for zone transfer

---

Quick start

# Interactive mode — guided setup
ReconNinja

# Standard scan
ReconNinja -t example.com

# Full 21-phase pipeline
ReconNinja -t example.com --profile full_suite -y

# v5 intelligence (no keys needed)
ReconNinja -t example.com --whois --wayback --ssl -y

# v6 new modules (no keys needed)
ReconNinja -t example.com --github-osint --js-extract \
  --cloud-buckets --dns-zone --waf --cors -y

# Full v6 with notifications
ReconNinja -t example.com --profile full_suite \
  --shodan --shodan-key KEY --vt --vt-key KEY \
  --ai --ai-provider groq --ai-key KEY \
  --github-osint --github-token TOKEN \
  --notify slack://hooks.slack.com/services/xxx \
  -y

# Compare two scans
ReconNinja --diff reports/example.com/20260101/report.json \
                  reports/example.com/20260301/report.json

---

Scan profiles

| Profile | What runs | |---|---| | fast | Top 100 ports, no scripts | | standard | Top 1000 ports, scripts + versions (default) | | thorough | All ports, OS detection, aggressive scripts | | stealth | SYN scan, low timing, no banners | | web_only | httpx + dir scan + nuclei | | port_only | RustScan + Masscan + Nmap | | full_suite | All 21 phases | | custom | Interactive builder |

---

Pipeline — 21 phases

Phase 1    Passive Recon         subdomain enum (amass, subfinder, crt.sh)
Phase 2    RustScan              ultra-fast port discovery (all 65535 ports)
Phase 2b   Async TCP             pure-Python fallback, no root required
Phase 3    Masscan               optional SYN sweep (root required)
Phase 4    Nmap                  deep service / version / script analysis
Phase 4b   CVE Lookup            NVD API CVE matching on detected services
Phase 5    httpx                 live web detection + tech fingerprint
Phase 5b   WAF Detection         passive headers + wafw00f (v6 NEW)
Phase 5c   CORS Scanner          misconfiguration probe (v6 NEW)
Phase 6    Dir Scan              feroxbuster → ffuf → dirsearch fallback
Phase 6b   JS Extraction         endpoint + secret extraction from JS (v6 NEW)
Phase 7    WhatWeb               technology fingerprinting
Phase 8    Nikto                 classic web vulnerability scanner
Phase 9    Nuclei                template-based vulnerability detection
Phase 10   Screenshots           aquatone → gowitness fallback
Phase 11   AI Analysis           Groq / Ollama / Gemini / OpenAI
Phase 12   Intelligence          WHOIS · Wayback · SSL · VirusTotal · Shodan
Phase 13a  GitHub OSINT          secret / config file exposure (v6 NEW)
Phase 13b  Cloud Buckets         AWS S3 / Azure / GCS enumeration (v6 NEW)
Phase 13c  DNS Zone Transfer     AXFR vulnerability check (v6 NEW)
Phase 14   Plugins               drop .py into plugins/ to extend
Phase 15   Reports               HTML · JSON · Markdown

---

What's new in v6.0.0

8 bugs fixed

| # | Severity | Fix | |---|---|---| | 1 | Critical | subdomains.py — _dns_brute args passed in wrong order; BUILTIN_SUBS landing in out_file slot → TypeError at runtime | | 2 | High | orchestrator.py — rustscan ports not persisted; on --resume all_open_ports was empty → Nmap skipped entirely | | 3 | High | updater.py — backup variable referenced before assignment on fresh install → UnboundLocalError | | 4 | High | orchestrator.py — AI fallback _generate_ai_analysis was dead code; condition always True → users with no key got raw error object in report | | 5 | Medium | ports.py — banner grabber sent HEAD / HTTP/1.0 to every port immediately; SSH/FTP/SMTP/Redis disconnected → banner capture failed on all non-HTTP ports | | 6 | Medium | orchestrator.py — aquatone received sub_file (bare hostnames) instead of url_file (full URLs) → screenshots broken | | 7 | Medium | cve_lookup.py — NVD rate-limit delay only fired on hits; no-result queries burst past 5 req/30s → silent 403s | | 8 | Low | utils/updater.py — stale duplicate, never imported, missing timeout=300 on pip subprocess → deleted |

6 new recon modules

| Module | Flag | Description | |---|---|---| | GitHub OSINT | --github-osint | Search GitHub for exposed secrets, API keys, config files | | JS Extraction | --js-extract | Crawl live pages, download JS files, extract endpoints + secrets | | Cloud Buckets | --cloud-buckets | Probe AWS S3, Azure Blob, GCS for public/authenticated buckets | | DNS Zone Transfer | --dns-zone | AXFR vulnerability check against all nameservers | | WAF Detection | --waf | Passive header + wafw00f fingerprinting | | CORS Scanner | --cors | Crafted Origin probe for ACAO misconfiguration |

2 new utilities

| Utility | Flag | Description | |---|---|---| | Scan Diff | --diff A.json B.json | Compare two scan reports — new ports, new vulns, new subdomains | | Notifications | --notify URL | Mid-scan alerts to Slack, Discord, or any webhook |

---

All flags

Target
  -t, --target           Domain, IP, CIDR, or path to list file
  -p, --profile          Scan profile (see above)
  -y, --yes              Skip confirmation (CI/automation)

Port scanning
  --all-ports            Scan all 65535 ports
  --top-ports N          Top N ports (default: 1000)
  --timing T1-T5         Nmap timing (default: T4)
  --rustscan             Enable RustScan pre-scan
  --masscan              Enable Masscan sweep (root)
  --masscan-rate N       Masscan pps (default: 5000)
  --async-concurrency N  Async TCP concurrency (default: 1000)
  --async-timeout N      Async TCP timeout seconds (default: 1.5)

Web & discovery
  --httpx                Live service detection
  --whatweb              WhatWeb fingerprinting
  --ferox                Feroxbuster directory scan
  --nikto                Nikto scanner
  --nuclei               Nuclei vulnerability templates
  --aquatone             Screenshots
  --subdomains           Subdomain enumeration
  --wordlist-size        small | medium | large

Vulnerability intelligence
  --cve                  NVD CVE lookup for detected services
  --nvd-key KEY          NVD API key (50 req/30s vs 5)

v5 integrations
  --shodan               Shodan host intelligence
  --shodan-key KEY       Shodan API key
  --vt                   VirusTotal reputation
  --vt-key KEY           VirusTotal API key
  --whois                WHOIS lookup (no key)
  --wayback              Wayback Machine URL discovery (no key)
  --ssl                  SSL/TLS certificate analysis (no key)

v6 new modules
  --github-osint         GitHub secret/config exposure search
  --github-token KEY     GitHub token (raises rate limit 60→5000/hr)
  --js-extract           JS endpoint and secret extraction
  --cloud-buckets        Cloud bucket enumeration (AWS/Azure/GCS)
  --dns-zone             DNS zone transfer (AXFR) check
  --waf                  WAF detection
  --cors                 CORS misconfiguration scanner

AI analysis
  --ai                   Enable AI threat analysis
  --ai-provider          groq | ollama | gemini | openai (default: groq)
  --ai-key KEY           API key for AI provider
  --ai-model MODEL       Override default model

Output & notifications
  --output DIR           Output directory (default: reports/)
  --output-format FMT    all | html | json | md | txt (default: all)
  --exclude PHASES       Comma-separated phases to skip
  --notify URL           Webhook alerts: slack://... discord://... https://...
  --timeout N            Global per-op timeout seconds (default: 30)
  --rate-limit N         Seconds between requests (default: 0)

Scan management
  --resume FILE          Resume from state.json checkpoint
  --diff A.json B.json   Compare two scan reports
  --update               Check GitHub for updates
  --force-update         Update even if already latest
  --check-tools          Show tool availability

---

Output

Each scan creates a timestamped folder:

reports/
└── example.com_20260320_120000/
    ├── report.html         ← dark-mode dashboard
    ├── report.json         ← full machine-readable results
    ├── rep