v5.2.1 · Latest Release
// recon NINJA_

14-phase automated reconnaissance framework for authorized security testing. One command drives the full pipeline — passive recon through AI threat analysis.

⚠ Use only against targets you own or have explicit written permission to test. Unauthorized scanning is illegal.
Python 3.10+ 707 Tests MIT License Security Tool Linux PyPI
02
Installation

Get Running

Only rich and python-dotenv are hard dependencies. All external tools are optional — ReconNinja detects availability and falls back gracefully.

From PyPI

bash 
# Standard install
pip install ReconNinja

# With AI support (Groq, Gemini, OpenAI, Ollama)
pip install "ReconNinja[ai]"

# Full — includes Shodan + Censys
pip install "ReconNinja[full]"

From GitHub

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

# With AI support
pip install "git+https://github.com/ExploitCraft/ReconNinja.git[ai]"

From Source

bash 
git clone https://github.com/ExploitCraft/ReconNinja.git
cd ReconNinja
pip install -e ".[full]"

Check Tool Availability

bash 
ReconNinja --check-tools

# Optional external tools: nmap, rustscan, masscan, amass,
# subfinder, httpx, feroxbuster, ffuf, dirsearch,
# whatweb, nikto, nuclei, aquatone, gowitness
03
Quick Start

Fire It Up

bash 
# Interactive guided setup
ReconNinja

# Standard scan
ReconNinja -t example.com

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

# Intelligence modules — no keys needed
ReconNinja -t example.com --whois --wayback --ssl -y

# v5.1: Censys + Hunter.io email enumeration
ReconNinja -t example.com \
  --censys --censys-key YOUR_KEY \
  --hunter --hunter-key YOUR_KEY -y

# v5.1: Diff current scan against a baseline
ReconNinja -t example.com \
  --diff reports/example.com_20260309_120000/state.json -y

# Full intelligence suite
ReconNinja -t example.com --profile full_suite \
  --whois --wayback --ssl                     \
  --shodan --shodan-key YOUR_KEY               \
  --vt --vt-key YOUR_KEY                       \
  --censys --censys-key YOUR_KEY               \
  --hunter --hunter-key YOUR_KEY               \
  --ai --ai-provider groq --ai-key YOUR_KEY    \
  -y
04
Pipeline

14-Phase Pipeline

Each phase feeds results into the next. Completed phases are checkpointed — interrupted scans resume from the last saved state.

Phase 1
Passive Recon
Subdomain enumeration via amass, subfinder, crt.sh
Phase 2
RustScan
Ultra-fast port discovery across all 65,535 ports
Phase 2b
Async TCP
Pure-Python asyncio fallback — no root required. Respects --exclude guard (fixed v5.2.1)
Phase 3
Masscan
Optional SYN sweep (root required)
Phase 4
Nmap
Deep service / version / script analysis on confirmed-open ports
Phase 4b
CVE Lookup
NVD API CVE matching on detected service versions
Phase 5
httpx
Live web detection + technology fingerprinting
Phase 6
Directory Scan
feroxbuster → ffuf → dirsearch fallback chain
Phase 7
WhatWeb
Technology stack fingerprinting
Phase 8
Nikto
Classic web vulnerability scanner
Phase 9
Nuclei
Template-based vulnerability detection
Phase 10
Screenshots
aquatone → gowitness fallback. Uses web_findings URLs when no subdomain file exists (fixed v5.2.1)
Phase 12
Intelligence Modules
WHOIS · Wayback · SSL · VirusTotal · Shodan · Censys · Hunter.io
Phase 14
AI Analysis
Groq / Ollama / Gemini / OpenAI threat summary + remediation
05
Profiles

Scan Profiles

ProfileDescription
fastTop 100 ports, no scripts
standardTop 1000 ports, scripts + version detection (default)
thoroughAll ports, OS detection, aggressive scripts
stealthSYN scan, low timing, no banners
web_onlyhttpx + directory scan + nuclei
port_onlyRustScan + Masscan + Nmap only
full_suiteAll 14 phases — auto-enables --whois, --wayback, --ssl
customInteractive CLI builder
06
Reference

All Flags

Target

-t, --targetDomain, IP, CIDR, or path to list file
-p, --profilefast · standard · thorough · stealth · web_only · port_only · full_suite · custom
-y, --yesSkip confirmation prompt

Port Scanning

--all-portsScan all 65,535 ports
--top-ports NScan top N ports (default: 1000)
--timing T1-T5Nmap timing template (default: T4)
--rustscanEnable RustScan pre-scan
--masscanEnable Masscan sweep (root required)
--masscan-rate NMasscan packets/sec (default: 5000)
--async-concurrencyAsync TCP concurrency (default: 1000)
--async-timeoutAsync TCP timeout in seconds (default: 1.5)

Web & Discovery

--httpxLive web service detection and fingerprinting
--whatwebWhatWeb technology fingerprinting
--feroxFeroxbuster directory scan
--niktoNikto web vulnerability scanner
--nucleiNuclei template-based vulnerability detection
--aquatoneScreenshot capture (gowitness fallback)
--subdomainsSubdomain enumeration
--wordlist-sizesmall · medium · large

Intelligence Integrations

--shodanShodan host intelligence lookup
--shodan-key KEYShodan API key
--vtVirusTotal reputation — auto-routes domain vs IP lookup
--vt-key KEYVirusTotal API key
--whoisWHOIS lookup (no key needed)
--waybackWayback Machine URL discovery
--sslSSL/TLS certificate analysis
--cveNVD CVE lookup for detected services
--nvd-key KEYNVD API key — raises rate limit from 5 to 50 req/30s
--censysCensys host intelligence — CDN/WAF detection NEW v5.1
--censys-key KEYCensys API key
--hunterHunter.io email enumeration — pattern + confidence scoring NEW v5.1
--hunter-key KEYHunter.io API key

Scan Diff

--diff STATE_FILECompare current scan against a previous state.json NEW v5.1

AI Analysis

--aiEnable AI threat analysis (Phase 14)
--ai-providergroq · ollama · gemini · openai (default: groq)
--ai-key KEYAPI key for AI provider
--ai-model MODELOverride the default model for selected provider

Output

--output DIROutput directory (default: reports/)
--output-format FMTall · html · json · md · txt (default: all)
--exclude PHASESComma-separated list of phases to skip
--timeout NGlobal per-operation timeout seconds (default: 30)
--rate-limit NSeconds between requests (default: 0)

Scan Management

--resume FILEResume interrupted scan from state.json
--updateCheck GitHub for updates and install latest
--force-updateUpdate even if already on latest version
--update-branchBranch to pull from (default: main)
--check-toolsShow availability of all optional tools
07
History

Changelog

5.2.1
2026-03-13  ·  BUGFIX  ·  707 tests
10 bugs fixed across orchestrator, updater, resume, and test suite
  • orchestrator.py — --exclude flag was parsed but never applied; all phase guards now check cfg.exclude_phases
  • orchestrator.py — VirusTotal always called vt_domain_lookup even on IP targets; now routes via ipaddress.ip_address()
  • orchestrator.py — Screenshots phase skipped when no subdomain file existed; now uses web_findings URLs with main domain as fallback
  • ReconNinja.py / reports.py / orchestrator.py / resume.py — Version hardcoded as 5.0.0 across multiple files; all bumped to 5.2.1
  • orchestrator.py — Dead imports (signal, sys, asdict) removed
  • updater.py — subprocess.run calls missing timeout parameter; added timeout=300
  • orchestrator.py — Phase 2b Async TCP ran even when port phase excluded; wrapped in exclude guard
  • resume.py — State file version field hardcoded 5.0.0; updated to 5.2.1
  • requirements.txt — Added python-dotenv>=1.0.0 dependency
  • Test version assertions updated to 5.2.1 across the full test suite
5.1.0
2026-03-11  ·  FEATURES
Censys host intelligence, Hunter.io email enumeration, Scan Diff Engine
  • core/censys_lookup.py — Censys Search v2 host lookup with CDN/WAF heuristic detection. --censys --censys-key KEY
  • core/hunter_lookup.py — Hunter.io domain email enumeration with pattern detection and per-email confidence scoring. --hunter --hunter-key KEY
  • core/diff.py — Compare two state.json snapshots; structured delta of new/closed ports, changed services, new/resolved subdomains. --diff STATE_FILE
  • 110+ new tests covering all three modules
5.0.0
2026-03-09  ·  BUGFIX
4 critical fixes across ports, web scanner, and plugin loader
  • core/ports.py — Removed duplicate port 587 from _NMAP_TOP_PORTS
  • core/web.py: run_whatweb — Added missing ensure_dir() preventing crash on missing output dir
  • core/web.py: run_nikto — Same ensure_dir() fix
  • plugins/__init__.py — Removed erroneous @staticmethod from module-level _load_module
4.0.0
2026-03-07  ·  FEATURES
5 intelligence modules + full pip publish support
  • Shodan, VirusTotal, WHOIS, Wayback Machine, SSL/TLS analysis
  • --output-format, --exclude, --timeout, --rate-limit flags
  • pyproject.toml + MANIFEST.in — full PyPI publish support; [ai] and [full] extras
  • Resume round-trips fixed — intelligence results now correctly restored from state.json
  • HTML / JSON / Markdown reports now include all intelligence sections
  • 80+ tests in tests/test_v4_modules.py
08
Intelligence

Intelligence Modules

8 modules — 5 free, 3 require API keys. All results preserved in state.json and restored on resume.

🔍
WHOIS
Domain registration, registrar, expiry dates, nameservers, registrant.
No key
📼
Wayback Machine
Historical URL discovery via CDX API. Categorizes by extension and path — surfaces old .env, /admin, etc.
No key
🔒
SSL/TLS
Certificate expiry, self-signed flag, SANs, weak ciphers (RC4, DES), old protocols (TLS 1.0, 1.1).
No key
🦠
VirusTotal
Domain/IP reputation across 80+ vendors. Auto-routes to correct endpoint for IP vs domain targets.
Free tier
📡
Shodan
Host intelligence — ports, banners, known CVEs, org, ISP, geolocation.
Free tier
🛡️
CVE Lookup
NVD API CVE matching against Nmap-detected service versions.
Optional key
🌐
Censys
Censys Search v2 host intelligence with CDN/WAF heuristic detection. Added v5.1.0.
API key · v5.1
📧
Hunter.io
Domain email enumeration — addresses, email patterns, confidence scores, sources. Added v5.1.0.
API key · v5.1
ModuleFlagKeySince
WHOIS--whoisNonev4.0.0
Wayback Machine--waybackNonev4.0.0
SSL/TLS Analysis--sslNonev4.0.0
VirusTotal--vt --vt-key KEYFree tierv4.0.0
Shodan--shodan --shodan-key KEYFree tierv4.0.0
NVD CVE Lookup--cve --nvd-key KEYOptionalv3.3.0
Censys--censys --censys-key KEYRequiredv5.1.0
Hunter.io--hunter --hunter-key KEYRequiredv5.1.0
09
Scan Diff · v5.1.0

Scan Diff Engine

Compare any two state.json snapshots and get a structured delta — track your attack surface over time, catch new exposure, verify remediations.

bash 
# Scan today and diff against last week's baseline
ReconNinja -t example.com \
  --diff reports/example.com_20260309_120000/state.json \
  -y
diff.json  ·  example.com  ·  20260309 → 20260314
NEW PORT
192.168.1.5:8443 (HTTPS)
CLOSED
192.168.1.5:23 (Telnet)
NEW SUB
staging.example.com
CHANGED
192.168.1.5:80 · Apache/2.4.41 → Apache/2.4.57
10
AI Analysis

AI-Powered Analysis

Phase 14 feeds all scan results into an LLM for threat prioritization and remediation suggestions. Four providers supported.

ProviderFlagDefault Model
Groq--ai-provider groqllama3-8b-8192
Ollama--ai-provider ollamallama3
Gemini--ai-provider geminigemini-pro
OpenAI--ai-provider openaigpt-4o-mini
bash 
ReconNinja -t example.com \
  --ai                              \
  --ai-provider groq               \
  --ai-key YOUR_GROQ_KEY           \
  --ai-model llama3-70b-8192       # optional override
11
Output

Output & Reports

Every scan creates a timestamped folder. All formats generated by default.

reports/ └── example.com_20260314_090000/ ├── report.html ← dark-mode dashboard ├── report.json ← full machine-readable results ├── report.md ← markdown summary ├── diff.json ← delta vs baseline (if --diff used) ├── scan_config.json ← exact config used ├── scan.log ← full execution log ├── state.json ← resume checkpoint ├── subdomains/ ├── nmap/ └── nuclei/
12
Resume

Resume Scans

Every completed phase writes a checkpoint to state.json. If a scan crashes or is interrupted, resume with zero repeated work.

bash 
# Scan crashed after Phase 8 — resume from checkpoint
ReconNinja --resume reports/example.com_20260314_090000/state.json

All intelligence results (WHOIS, Wayback, SSL, VirusTotal, Shodan, Censys, Hunter.io) are serialized into state.json and fully restored on resume.

13
Plugins

Plugin System

Drop any .py file into the plugins/ directory. Plugins receive the full ReconResult and ScanConfig after all phases complete. A built-in example plugin cve_banner_check.py is included.

plugins/my_plugin.py 
def run(target, out_folder, result, cfg):
    print(f"Hosts found:   {len(result.hosts)}")
    print(f"Shodan hits:   {len(result.shodan_results)}")
    print(f"Emails found:  {len(result.hunter_results)}")
    # write custom reports, call external APIs, post to Slack, etc.
14
Development

Dev Setup

bash 
git clone https://github.com/ExploitCraft/ReconNinja.git
cd ReconNinja
pip install -e ".[full]"

# Run all 707 tests
pytest

# v4 intelligence module tests
pytest tests/test_v4_modules.py -v

# v5.1 module tests (Censys, Hunter, Diff)
pytest tests/test_reconninja_v510.py -v

# Orchestrator tests
pytest tests/test_orchestrator.py -v