ReconNinja 4.0.0

14-phase automated reconnaissance framework for security researchers

ReconNinja

14-phase automated reconnaissance framework for authorized security testing.

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

---

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, credential intelligence, 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

# With AI support (Groq, Gemini, OpenAI)
pip install "git+https://github.com/ExploitCraft/ReconNinja.git[ai]"

# Full — includes Shodan
pip install "git+https://github.com/ExploitCraft/ReconNinja.git[full]"

# From source
git clone https://github.com/ExploitCraft/ReconNinja.git
cd ReconNinja && pip install -e .

---

Quick start

# Interactive mode — guided setup
reconnja

# Standard scan
reconnja -t example.com

# Full 14-phase pipeline
reconnja -t example.com --profile full_suite -y

# v4: WHOIS + Wayback + SSL — no keys needed
reconnja -t example.com --whois --wayback --ssl -y

# v4: Full intelligence
reconnja -t example.com --profile full_suite \
  --whois --wayback --ssl \
  --shodan --shodan-key YOUR_KEY \
  --vt --vt-key YOUR_KEY \
  --ai --ai-provider groq --ai-key YOUR_KEY \
  -y

---

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 14 phases
custom	Interactive builder

---

Pipeline

Phase 1   Passive Recon      subdomain enum (amass, subfinder, crt.sh)
Phase 2   RustScan           ultra-fast port discovery (all 65535 ports)
Phase 2b  Async TCP          asyncio 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 6   Dir Scan           feroxbuster → ffuf → dirsearch fallback chain
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 12  v4 Integrations    WHOIS · Wayback · SSL · VirusTotal · Shodan
Phase 14  AI Analysis        Groq / Ollama / Gemini / OpenAI threat summary

---

What's new in v4.0.0

5 new intelligence modules — 3 need zero API keys:

Module	Flag	API Key
WHOIS lookup	--whois	None
Wayback Machine URL discovery	--wayback	None
SSL/TLS certificate analysis	--ssl	None
VirusTotal reputation	--vt --vt-key KEY	Free tier
Shodan host intelligence	--shodan --shodan-key KEY	Free tier

Output control (new flags):

--output-format html      # html | json | md | txt | all
--exclude passive,vuln    # skip specific phases
--timeout 60              # global per-operation timeout
--rate-limit 1.0          # seconds between requests

pip install now works:

pip install git+https://github.com/ExploitCraft/ReconNinja.git

---

All flags

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

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

Web & discovery
  --httpx               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 (raises rate limit 5→50 req/30s)

v4 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 needed)
  --wayback             Wayback Machine URL discovery (no key needed)
  --ssl                 SSL/TLS certificate analysis (no key needed)

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
  --output DIR          Output directory (default: reports/)
  --output-format FMT   all | html | json | md | txt (default: all)
  --exclude PHASES      Comma-separated phases to skip
  --timeout N           Global per-operation timeout seconds (default: 30)
  --rate-limit N        Seconds between requests (default: 0)

Scan management
  --resume FILE         Resume interrupted scan from state.json
  --update              Check GitHub for updates
  --force-update        Update even if already on latest
  --check-tools         Show tool availability

---

Output

Each scan creates a timestamped folder:

reports/
└── example.com_20260307_120000/
    ├── report.html         ← dark-mode dashboard
    ├── report.json         ← full machine-readable results (includes v4 data)
    ├── report.md           ← markdown summary
    ├── scan_config.json    ← exact config used
    ├── scan.log            ← full execution log
    ├── state.json          ← resume checkpoint
    ├── subdomains/
    ├── nmap/
    └── nuclei/

---

Resume interrupted scans

# Scan crashes after Phase 8 — resume from last checkpoint
reconnja --resume reports/example.com_20260307_120000/state.json

All v4 results (WHOIS, Wayback, SSL, VT, Shodan) are preserved in state.json and restored on resume.

---

Plugin system

Drop a .py file into plugins/ to extend the pipeline. It receives the full ReconResult and ScanConfig after all phases complete.

# plugins/custom.py
def run(target, out_folder, result, cfg):
    print(f"Custom: {len(result.hosts)} hosts, {len(result.shodan_results)} Shodan entries")

---

Tool dependencies

Only rich is required. All external tools are optional — ReconNinja detects what's available and falls back gracefully.

reconnja --check-tools    # show availability

Optional tools: nmap, rustscan, masscan, amass, subfinder, httpx, feroxbuster, ffuf, dirsearch, whatweb, nikto, nuclei, aquatone, gowitness

---

Development

git clone https://github.com/ExploitCraft/ReconNinja.git
cd ReconNinja
pip install -e ".[full]"
pytest                                       # run all 600+ tests
pytest tests/test_v4_modules.py -v          # v4 module tests
pytest tests/test_orchestrator.py -v        # orchestrator tests

---

License

MIT — see LICENSE

---

ExploitCraft · Bangladesh · Building tools that matter