ReconNinja

38-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

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

Pipeline — 38 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 14a  Email Security        SPF/DKIM/DMARC + spoofability score (v7 NEW)
Phase 14b  Breach Check          HaveIBeenPwned domain breach lookup (v7 NEW)
Phase 14c  Cloud Metadata        AWS/Azure/GCP IMDS SSRF probe (v7 NEW)
Phase 14d  GraphQL Scanner       endpoint discovery + introspection (v7 NEW)
Phase 14e  JWT Scanner           none-alg + weak secret cracker (v7 NEW)
Phase 14f  ASN/BGP Map           owned IP CIDRs via RIPE Stat (v7 NEW)
Phase 14g  Supply Chain          vulnerable JS libs + npm squatting (v7 NEW)
Phase 14h  K8s/Docker Probe      unauthenticated API detection (v7 NEW)
Phase 14i  DB Exposure           Redis/ES/MongoDB/Memcached unauth (v7 NEW)
Phase 14j  SMTP Enum             VRFY/RCPT TO user enumeration (v7 NEW)
Phase 14k  SNMP Scan             community string brute + MIB walk (v7 NEW)
Phase 14l  LDAP Enum             anonymous bind + attribute dump (v7 NEW)
Phase 14m  DevOps Scan           Terraform state + Jenkins exposure (v7 NEW)
Phase 14n  GreyNoise             IP noise/RIOT/unknown tagging (v7 NEW)
Phase 14o  Typosquat             lookalike domain detection (v7 NEW)
Phase 14p  Censys                host intelligence (v7 NEW)
Phase 14q  DNS History           historical resolution via VT PDNS (v7 NEW)
Phase 15   Plugins               drop .py into plugins/ to extend
Phase 16   Reports               HTML · JSON · Markdown · SARIF

What's new in v7.1.0

1 bug fixed

#	Severity	Fix
1	Medium	`core/orchestrator.py` — 19 module-level functions were called but never imported, causing `NameError` at runtime for every v7 feature phase (`email_security_scan`, `breach_check`, `cloud_meta_scan`, `graphql_scan`, `jwt_scan`, `asn_map`, `supply_chain_scan`, `k8s_probe`, `db_exposure_scan`, `smtp_enum`, `snmp_scan`, `ldap_enum`, `terraform_state_scan`, `jenkins_scan`, `greynoise_lookup`, `typosquat_scan`, `censys_bulk_lookup`, `dns_history_lookup`, `export_sarif`). All 17 missing imports added; `smtp_user_enum` aliased as `smtp_enum` to match call sites

What's new in v7.0.0

3 bugs fixed

#	Severity	Fix
1	Medium	`js_extractor.py` — `_extract_secrets()` used `seen_labels` set so only 1 secret per type per JS file was captured. Fixed to dedup on `(label, match_prefix)` and switched to `finditer()` so all unique credential instances are found
2	Low	`dns_zone_transfer.py` — fallback `socket.getaddrinfo` block was dead misleading code; it assigned `infos` but never read it and cannot return NS records. Removed
3	Low	Version string rot across 37 files — headers/User-Agents/footers still said `v3`, `v3.3`, `v6.0.0`. All updated to `v7.0.0`

25 new features across 17 new modules

Module	Flag	Description
Email Security	`--email-security`	SPF/DKIM/DMARC validation + spoofability score 0–100
Breach Check	`--breach-check`	HaveIBeenPwned domain breach check (free API, no key)
Cloud Metadata	`--cloud-meta`	AWS/Azure/GCP IMDS SSRF probe + parameter injection test
GraphQL Scanner	`--graphql`	Endpoint discovery, introspection dump, batch + field-suggestion
JWT Scanner	`--jwt-scan`	none-algorithm bypass + weak HMAC secret cracker
ASN/BGP Map	`--asn-map`	Resolve owned ASN → all IP CIDRs via RIPE Stat (no key)
Supply Chain	`--supply-chain`	Vulnerable JS libs (jQuery/Lodash/polyfill.io) + npm squat check
K8s Probe	`--k8s-probe`	Kubernetes API + kubelet + etcd + Docker API exposure
DB Exposure	`--db-exposure`	Unauthenticated Redis / Elasticsearch / MongoDB / Memcached
SMTP Enum	`--smtp-enum`	User enumeration via VRFY / EXPN / RCPT TO
SNMP Scan	`--snmp-scan`	Community string brute-force + MIB walk
LDAP Enum	`--ldap-enum`	Anonymous bind → user/group/attribute dump
DevOps Scan	`--devops-scan`	Terraform state file exposure + Jenkins anon access + script console
GreyNoise	`--greynoise`	Tag IPs as internet noise / RIOT / unknown (free community API)
Typosquat	`--typosquat`	200+ lookalike domain variants, live DNS-resolved
Censys	`--censys`	Host intelligence (requires free Censys API credentials)
DNS History	`--dns-history`	Historical resolutions via VirusTotal PDNS (requires `--vt-key`)
SARIF Export	`--sarif`	SARIF 2.1.0 output for GitHub/VSCode/Azure DevOps

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

v7 new modules
  --email-security       SPF/DKIM/DMARC validation + spoofability score
  --breach-check         HaveIBeenPwned domain breach check
  --hibp-key KEY         HIBP API key for email-level lookup
  --cloud-meta           AWS/Azure/GCP metadata SSRF probe
  --graphql              GraphQL endpoint discovery + introspection
  --jwt-scan             JWT none-alg + weak HMAC secret cracker
  --asn-map              BGP/ASN → all owned IP CIDRs
  --supply-chain         Vulnerable JS libs + npm squat check
  --k8s-probe            Kubernetes/Docker unauthenticated API
  --db-exposure          Unauthenticated Redis/ES/MongoDB/Memcached
  --smtp-enum            SMTP user enumeration (VRFY/RCPT TO)
  --snmp-scan            SNMP community string brute + MIB walk
  --ldap-enum            LDAP anonymous bind + user/group dump
  --devops-scan          Terraform state + Jenkins exposure
  --greynoise            GreyNoise IP noise/RIOT/unknown tagging
  --greynoise-key KEY    GreyNoise API key (optional)
  --typosquat            Lookalike domain variant detection
  --censys               Censys host intelligence
  --censys-id ID         Censys API ID
  --censys-secret KEY    Censys API secret
  --dns-history          DNS history via VirusTotal PDNS (--vt-key needed)
  --sarif                Export findings as SARIF 2.1.0

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
    ├── report.md           ← markdown summary
    ├── scan_config.json    ← exact config used
    ├── scan.log            ← full execution log
    ├── state.json          ← resume checkpoint
    ├── subdomains/
    ├── nmap/
    ├── nuclei/
    ├── js_extract/         ← v6: downloaded JS files
    ├── cloud_buckets/      ← v6: bucket findings
    ├── dns_zone/           ← v6: zone transfer records
    ├── waf/                ← v6: WAF detection output
    └── cors/               ← v6: CORS findings

Scan diff

# Run a baseline scan
ReconNinja -t example.com -y

# Run again after changes
ReconNinja -t example.com -y

# See exactly what changed
ReconNinja --diff reports/example.com/20260101_120000/report.json \
                  reports/example.com/20260320_120000/report.json

Output: new open ports, closed ports, new subdomains, new vulnerabilities, new technologies, changed service versions.

Notifications

# Slack
ReconNinja -t example.com --notify slack://hooks.slack.com/services/T.../B.../xxx -y

# Discord
ReconNinja -t example.com --notify discord://discord.com/api/webhooks/xxx/yyy -y

# Generic JSON webhook
ReconNinja -t example.com --notify https://your-server.com/webhook -y

Fires alerts mid-scan for: critical ports found, critical vulnerabilities, public cloud buckets, CORS issues, GitHub exposures, zone transfer vulnerabilities, and scan completion.

Resume interrupted scans

# Scan crashes after Phase 9 — resume from last checkpoint
ReconNinja --resume reports/example.com_20260320_120000/state.json

All results (ports, findings, v5 intelligence, v6 new module data) are checkpointed after every phase and fully restored on resume.

Plugin system

Drop a .py file into plugins/ to extend the pipeline after all phases complete.

# plugins/my_check.py
PLUGIN_NAME    = "my_check"
PLUGIN_VERSION = "1.0"

def run(target, out_folder, result, cfg):
    print(f"Custom: {len(result.github_findings)} GitHub findings")
    print(f"Custom: {len(result.bucket_findings)} bucket findings")

Tool dependencies

Only rich is required. All external tools are optional — ReconNinja detects availability and falls back gracefully.

ReconNinja --check-tools

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

Optional Python packages: dnspython (zone transfer), shodan, groq, openai, google-generativeai

Development

git clone https://github.com/ExploitCraft/ReconNinja.git
cd ReconNinja
chmod +x install.sh && ./install.sh

# Run tests
python3 -m pytest tests/ -v
python3 -m pytest tests/test_orchestrator.py -v
python3 -m pytest tests/test_models.py -v

Part of the HackerInc/ExploitCraft Ecosystem

Tool	Description
envleaks	Codebase & git history scanner
gitdork	Google/Shodan dork generator
wifi-passview	Cross-platform WiFi credential dumper
ReconNinja	ReconNinja v7.1.0 — 21-phase recon framework (this repo)
VaultHound	Secret & credential scanner

License

MIT — see LICENSE

ExploitCraft · Bangladesh · Building tools that matter

📄 Full documentation at doc.emonpersonal.xyz

Name		Name	Last commit message	Last commit date
Latest commit History 88 Commits
.github/workflows		.github/workflows
core		core
output		output
plugins		plugins
tests		tests
utils		utils
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
MSG.txt		MSG.txt
README.md		README.md
environment.yml		environment.yml
install.sh		install.sh
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
reconninja.py		reconninja.py
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ReconNinja

What it does

Install

Quick start

Scan profiles

Pipeline — 38 phases

What's new in v7.1.0

1 bug fixed

What's new in v7.0.0

3 bugs fixed

25 new features across 17 new modules

All flags

Output

Scan diff

Notifications

Resume interrupted scans

Plugin system

Tool dependencies

Development

Part of the HackerInc/ExploitCraft Ecosystem

License

About

Uh oh!

Releases 14

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

ReconNinja

What it does

Install

Quick start

Scan profiles

Pipeline — 38 phases

What's new in v7.1.0

1 bug fixed

What's new in v7.0.0

3 bugs fixed

25 new features across 17 new modules

All flags

Output

Scan diff

Notifications

Resume interrupted scans

Plugin system

Tool dependencies

Development

Part of the HackerInc/ExploitCraft Ecosystem

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 14

Contributors

Uh oh!

Languages