Metadata-Version: 2.4
Name: ReconNinja
Version: 7.0.0
Summary: 38-phase automated reconnaissance framework for security researchers
Author-email: ExploitCraft <emonkk06@gmail.com>
License: MIT License
        
        Copyright (c) 2026 ExploitCraft
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/ExploitCraft/ReconNinja
Project-URL: Repository, https://github.com/ExploitCraft/ReconNinja
Project-URL: Issues, https://github.com/ExploitCraft/ReconNinja/issues
Keywords: recon,reconnaissance,security,penetration-testing,osint
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Provides-Extra: ai
Requires-Dist: groq>=0.5.0; extra == "ai"
Requires-Dist: google-generativeai>=0.5.0; extra == "ai"
Requires-Dist: openai>=1.0.0; extra == "ai"
Provides-Extra: shodan
Requires-Dist: shodan>=1.28.0; extra == "shodan"
Provides-Extra: dns
Requires-Dist: dnspython>=2.4.0; extra == "dns"
Provides-Extra: full
Requires-Dist: groq>=0.5.0; extra == "full"
Requires-Dist: google-generativeai>=0.5.0; extra == "full"
Requires-Dist: openai>=1.0.0; extra == "full"
Requires-Dist: shodan>=1.28.0; extra == "full"
Requires-Dist: dnspython>=2.4.0; extra == "full"
Requires-Dist: ipwhois>=1.2.0; extra == "full"
Requires-Dist: ldap3>=2.9.1; extra == "full"
Requires-Dist: pysnmp>=6.1.0; extra == "full"
Provides-Extra: v7
Requires-Dist: ipwhois>=1.2.0; extra == "v7"
Requires-Dist: ldap3>=2.9.1; extra == "v7"
Requires-Dist: pysnmp>=6.1.0; extra == "v7"
Dynamic: license-file

<div align="center">

# ReconNinja

**38-phase automated reconnaissance framework for authorized security testing.**

[![Version](https://img.shields.io/badge/version-7.0.0-6366f1?style=flat-square)](https://github.com/ExploitCraft/ReconNinja/releases)
[![Python](https://img.shields.io/badge/python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
[![Tests](https://img.shields.io/badge/tests-passing-22c55e?style=flat-square)](tests/)
[![License](https://img.shields.io/badge/license-MIT-f4f4f5?style=flat-square)](LICENSE)
[![Author](https://img.shields.io/badge/author-ExploitCraft-a78bfa?style=flat-square)](https://github.com/ExploitCraft)
[![Docs](https://img.shields.io/badge/docs-doc.emonpersonal.xyz-00e5ff?style=flat-square)](http://doc.emonpersonal.xyz/)

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

📄 **Documentation at [doc.emonpersonal.xyz](https://doc.emonpersonal.xyz/)**
[![Changelog](https://img.shields.io/badge/Changelog-View-blue)](CHANGELOG.md)

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

```bash
# 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

```bash
# 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.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

```bash
# 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

```bash
# 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

```bash
# 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.

```python
# 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.

```bash
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

```bash
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](https://github.com/ExploitCraft/envleaks) | Codebase & git history scanner |
| [gitdork](https://github.com/ExploitCraft/gitdork) | Google/Shodan dork generator |
| [wifi-passview](https://github.com/ExploitCraft/wifi-passview) | Cross-platform WiFi credential dumper |
| **ReconNinja** | ReconNinja v7.0.0 — 21-phase recon framework (this repo)  |
| [VaultHound](https://github.com/ExploitCraft/VaultHound) | Secret & credential scanner |

---

## License

MIT — see [LICENSE](LICENSE)

---

<div align="center">

**[ExploitCraft](https://github.com/ExploitCraft)** · Bangladesh · Building tools that matter

📄 Full documentation at **[doc.emonpersonal.xyz](http://doc.emonpersonal.xyz/)**

</div>
