Metadata-Version: 2.4
Name: nexus-rec
Version: 1.0.1
Summary: Intelligent Reconnaissance & Vulnerability Assessment Framework
Author-email: Ihsan Alapsi <me@ihsanalapsi.dev>
License: MIT
Project-URL: Homepage, https://github.com/ihsanalapsi/Nexus-REC
Project-URL: Repository, https://github.com/ihsanalapsi/Nexus-REC.git
Project-URL: Issues, https://github.com/ihsanalapsi/Nexus-REC/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Arabic
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.7.0
Requires-Dist: urllib3>=2.0.0
Dynamic: license-file

<div align="center">
  <img src="./assets/banner.png" width="100%" alt="Nexus-REC Banner">
</div>

# 🛡️ Nexus-REC
### The Intelligent Reconnaissance & Vulnerability Assessment Framework

[![Version](https://img.shields.io/github/v/release/ihsanalapsi/Nexus-REC?style=for-the-badge)](https://github.com/ihsanalapsi/Nexus-REC/releases)
[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge)](https://www.python.org/)
[![CI](https://img.shields.io/github/actions/workflow/status/ihsanalapsi/Nexus-REC/ci.yml?style=for-the-badge)](https://github.com/ihsanalapsi/Nexus-REC/actions)
[![Security](https://img.shields.io/badge/Security-Hardened-orange?style=for-the-badge)](https://ihsanalapsi.dev)

---

**Nexus-REC** is a powerhouse modular reconnaissance engine built for **Red Teams, Bug Hunters, and Security Researchers**. It consolidates **533+ specialized techniques** into a single, high-performance automated workflow.

[🚀 Quick Start](#-quick-start) • [🧩 Modules](#-capabilities) • [🛡 Safety](#-transparency--safety-model) • [📊 Reports](#-reports) • [📂 Architecture](#-architecture)

---

## 📌 Engine Stats
<div align="center">

| 🔬 Scanners | 🎯 Tactical Research | 🏆 Bug Bounties | 🔍 API Patterns |
|:---:|:---:|:---:|:---:|
| **533+** | **62 Engagements** | **12 Ops** | **36+ Patterns** |

</div>

---

## 🚀 Capabilities

<details open>
<summary><b>Click to expand Core Modules</b></summary>

| Module | Category | Highlights |
|:---|:---:|:---|
| **Basic Recon** | 🔍 | WAF Detection (13 engines), Tech Stack (30+), Security Headers Audit |
| **Subdomain Enum** | 🌐 | crt.sh, Brute Force (incl. bkapi/student/teacher), JS-Extraction, Backend IP Discovery |
| **Cloud Recon** | ☁️ | AWS S3/CloudFront, Azure Blob, Cloudflare, Cache Poisoning |
| **JS Analysis** | 📜 | API Extraction, Webpack Detection, Secret/Token Harvesting |
| **GraphQL Recon** | 🕸️ | Introspection check, **Error-Based Schema Harvesting**, **Apollo CSRF Preflight Check**, Batching |
| **Vuln Scanner** | 🔴 | SQLi, XSS, IDOR (PII-aware), SSRF, XXE, Auth Bypass, **Mass Assignment**, **Payment Data Leak** |
| **Business Logic**| ⚖️ | Price Manipulation, Race Conditions, Coupon Abuse |
| **Cookie & Session**| 🍪 | JWT decoding, **HS256 offline secret cracking (wordlist)**, Security flags, Session IDs |
| **DNS & SSL** | 🔒 | Wildcard Detection, SSL Cert Parsing, Port Scanning (25 ports) |
| **Payment Recon** | 💳 | 25 Gateway Detection (CSP), API Key Extraction, Webhook Discovery, PII Classification |
| **Supabase Audit** | 🛢️ | RLS Policy Testing, RPC Enumeration, Storage Audit, Service Role Key checks |
| **Well-Known Files** | 📄 | robots.txt, security.txt, llms.txt & ai.txt parsing for intelligence discovery |
| **APK / Mobile** | 📱 | Downloadable APK/AAB analysis, DEX decompiling, API endpoints & keys extraction |
| **DNS Detritus** | 🗑️ | Legacy DNS records mapping, Cloudflare detritus resolution |
| **Admin Deep Scan**| 🔐 | Admin subdomain discovery, interface deep scanning, path finding |
| **Stack: Laravel** | 💎 | Debug Leak, Boost Package, WAF/OpenResty, Inertia.js, **Coolify detection**, Server audit |
| **Stack: Next.js** | 💎 | Middleware Bypass, SSG/SSR Leak, Build ID, **JS chunk Harvesting**, **Proxy scan**, **Turbopack**, **Sentry** |

</details>

---

## 📦 Installation

```bash
# Clone & Navigate
git clone https://github.com/ihsanalapsi/Nexus-REC.git && cd Nexus-REC

# Setup Environment
python3 -m venv venv && source venv/bin/activate

# Install Dependencies
pip install -r requirements.txt
```

Check the local Python environment:

```bash
python3 nexus_rec.py --check-deps
```

---

## 🚀 Quick Start

Run Nexus-REC interactively:

```bash
python3 nexus_rec.py
```

The interactive flow asks for:

1. Target domain or URL
2. Scan mode: `safe`, `active`, or `aggressive`
3. Stealth mode
4. Redacted report export
5. Authorization confirmation when active/aggressive testing is selected
6. Scan profile selection

For non-interactive usage:

```bash
python3 nexus_rec.py example.com --auto
```

---

## 🛠️ Command Usage

<details>
<summary><b>View Advanced Command Guide</b></summary>

```bash
# Standard Interactive Scan
python3 nexus_rec.py example.com

# Start full interactive mode with prompts
python3 nexus_rec.py

# Fully Automated (CI/CD Mode)
python3 nexus_rec.py example.com --auto

# Authorized active testing
python3 nexus_rec.py example.com --scan-mode active --i-have-authorization

# Higher-noise authorized testing
python3 nexus_rec.py example.com --scan-mode aggressive --i-have-authorization

# Stealth Mode (Evasion & Delays)
python3 nexus_rec.py example.com --stealth

# Targeted Module Execution
python3 nexus_rec.py example.com --modules basic,js,vuln

# Also create a shareable redacted report while keeping the raw report
python3 nexus_rec.py example.com --redact-report

# Troubleshooting mode with full Python tracebacks
python3 nexus_rec.py example.com --modules basic --auto --debug
```

</details>

---

## ⚙️ CLI Options

| Option | Purpose |
|:---|:---|
| `target` | Domain or URL to scan, e.g. `example.com` or `https://example.com` |
| `--auto` | Runs without interactive menus or prompts |
| `--modules` | Runs a comma-separated module list, e.g. `basic,js,secrets` |
| `--scan-mode safe` | Default mode; avoids state-changing payloads |
| `--scan-mode active` | Enables authorized active vulnerability checks |
| `--scan-mode aggressive` | Enables higher-noise authorized checks |
| `--i-have-authorization` | Required for `active` and `aggressive` modes |
| `--stealth` | Reduces concurrency and adds request delay where supported |
| `--redact-report` | Also writes `redacted_report.json` for sharing |
| `--debug` | Shows full tracebacks for unexpected errors |
| `--check-deps` | Checks required/optional packages and prints install suggestions |

Valid module names:

```text
basic, subdomain, cloud, js, graphql, secrets, vuln, business, cookies, dns,
endpoints, payment, supabase_rls, supabase_rpc, supabase_storage, wellknown,
apk, dns_detritus, admin_scan, backend_scan, nextjs, laravel
```

Invalid module names and malformed targets are rejected before the scan starts.

---

## 🔎 Transparency & Safety Model

Nexus-REC keeps the **raw local report complete by default**. Findings, tokens, cookies, endpoint previews, and evidence are not silently hidden from the operator.

For safer public or team sharing, use `--redact-report`. This writes a second `redacted_report.json` report next to the full raw JSON report inside the scan folder.

| Mode | Purpose | Behavior |
|:---|:---|:---|
| `safe` | Default reconnaissance | Avoids state-changing payloads and records skipped active tests |
| `active` | Authorized vulnerability testing | Enables payload-based checks after `--i-have-authorization` |
| `aggressive` | Authorized high-noise testing | Adds higher-noise probes such as race-condition/session replay checks |

---

## 🧠 Smart Scan Logic

When you select **Full Scan (Smart Guided)**, the engine:

1. **Runs fingerprinting first** and builds the rest of the scan from the detected stack, headers, WAF/CDN signals, HTML, CSP, and JavaScript indicators.
2. **Records every smart decision** in `scan_metadata.smart_plan_reasons` and `scan_metadata.smart_skip_reasons`, so the terminal, JSON, Markdown, and PDF explain why a module ran or was skipped.
3. **Auto-enables stack modules** when relevant: Next.js, Laravel, Supabase RLS/RPC/storage, GraphQL, payment gateway checks, DNS detritus, backend API follow-up scans, and well-known file discovery.
4. **Expands during the scan** when later evidence appears, such as GraphQL endpoints, backend API hosts, or mobile app references discovered from JavaScript.
5. **Respects safety gates**: active/business/admin checks are held back in `safe` mode, and WAF/security-challenge cases are reduced or require confirmation unless `aggressive` authorized mode is used.
6. **Keeps progress honest** by counting only the phases selected for the current target and mode, not every possible module in the tool.

---

## 📊 Reports

Each scan writes a dedicated report folder:

```text
results/YYYYMMDD_HHMMSS-target/
├── raw_report.json
├── redacted_report.json   # only when --redact-report is used
├── security_report.md
└── security_report.pdf
```

Reports are generated based on the modules that actually ran. Nexus-REC does not add empty sections for modules that were not selected. A `basic` scan, for example, will include target summary, scan coverage, technologies, and security headers, but it will not include vulnerability details unless the vulnerability module ran.

The Markdown and PDF reports are intended for review and handoff. The raw JSON report is best for automation, auditing, and deeper evidence inspection.

---

## 📁 Project Structure

```text
nexus_rec.py               # Main Orchestration Engine
├── modules/
│   ├── core/              # CLI, config, declarative pipeline, loading, summaries, reports
│   ├── recon/
│   │   ├── fingerprint/   # Basic fingerprinting and technology detection
│   │   ├── web/           # JS, APIs, cookies, secrets, GraphQL, payment, backend follow-up
│   │   ├── infra/         # DNS, cloud, subdomains, admin surface, stale DNS
│   │   ├── platforms/     # Supabase-specific checks
│   │   └── mobile/        # APK/mobile application analysis
│   ├── exploit/           # Vulnerability & Business Logic Scanners
│   └── stack/             # Framework-specific modules (Next.js, Laravel)
├── tests/                 # Smoke tests for registry, smart plan, CLI, dependencies
├── results/               # Per-scan folders with JSON, Markdown, and PDF reports
└── requirements.txt       # Dependencies
```

---

## 🧪 Example Workflows

Quick fingerprint:

```bash
python3 nexus_rec.py example.com --modules basic --auto
```

Web surface review:

```bash
python3 nexus_rec.py example.com --modules basic,js,secrets,cookies,endpoints --auto --redact-report
```

Authorized vulnerability pass:

```bash
python3 nexus_rec.py example.com --scan-mode active --i-have-authorization --modules basic,vuln,business,graphql --auto
```

Smart full run:

```bash
python3 nexus_rec.py example.com --auto --redact-report
```

Smoke test matrix:

```bash
python3 -m unittest tests/smoke_tests.py
```

---

## 📦 Raw JSON Shape

```json
{
  "basic": { "headers": {...}, "technologies": {...}, "waf": [...] },
  "subdomain": { "subdomains": [...], "crt_sh_subdomains": [...], "backend_discovered": [...] },
  "cookies": { "potential_jwt": [{ "cookie_name": "...", "hs256_cracked": true, "hs256_secret": "secret" }], "credential_leak": [...] },
  "graphql": { "introspection": {...}, "error_schema_leak": {...}, "csrf_protection": {...}, "batch_queries": {...} },
  "vulnerabilities": { "sqli": [...], "xss": [...], "idor": [...], "mass_assignment": [...], "payment_data_leak": [...] },
  "payment_gateway": { "csp_analysis": {...}, "payment_keys": {...}, "webhooks": [...] },
  "backend_scan": { "backend_count": 1, "scanned_backends": {...} },
  "backend_ip_discovery": [{ "ip": "...", "redirect_url": "...", "backend_domain": "..." }],
  "supabase_rls": { "supabase_project": {...}, "rls_open_tables": [...] },
  "supabase_rpc": { "rpc_exposed": [...] },
  "supabase_storage": { "public_buckets": [...], "common_buckets": [...] },
  "wellknown": { "wellknown_files": [...], "llms_txt_found": [...], "llms_analysis": {...} },
  "apk": { "apk_references": [...], "apk_secrets": [...], "apk_api_endpoints": [...] },
  "dns_detritus": { "total_detritus": 0, "cloudflare_detritus": [], "resolvable_legacy": [...] },
  "admin_scan": { "admin_subdomains": [...], "admin_paths": [...] },
  "laravel": { "api_debug_check": [...], "boost_package": {...}, "coolify": {"detected": true}, "server": "nginx", "waf": [...] },
  "nextjs": { "version": "...", "bundler": "Turbopack", "sentry_detected": true, "locale": "en", "static_subdomains": [...], "preloaded_assets": 4, "api_routes_from_chunks": [...], "backend_proxy": [...] }
}
```

---

## 🧯 Troubleshooting

| Symptom | Meaning | What to do |
|:---|:---|:---|
| `Vercel Security Challenge (403)` | The target returned an edge security/challenge page | Results are limited; retry later, use an authorized IP/session, or run passive modules |
| `Invalid module(s)` | A module name in `--modules` is not recognized | Use one of the valid module names listed above |
| `Dependency check` reports missing packages | Python environment is incomplete | Run the suggested `python3 -m pip install ...` command or `pip install -r requirements.txt` |
| `Active/aggressive scans require authorization confirmation` | The selected scan mode can send active payloads | Add `--i-have-authorization` only for targets in scope |
| Unexpected error without details | Normal user-safe error handling | Re-run with `--debug` for full traceback |

---

## ⚠️ Ethical Disclaimer
This tool is intended for **authorized security testing and educational research only**. Unauthorized use against systems you do not own or have permission to test is **illegal**.

---

<div align="center">

### Developed with ⚡ by [Ihsan Alapsi](https://ihsanalapsi.dev)
Software Engineer & Cyber Security Researcher

[GitHub](https://github.com/ihsanalapsi) · [LinkedIn](https://www.linkedin.com/in/ihsan-alapsi/) · [Twitter](https://twitter.com/ihsanalapsi)

</div>
