A premium, modular vulnerability scanner and exploitation framework targeting Spring, GraphQL, and React Server Components (RSC) stacks.

• ✨ Key Features
• ⚙️ Architecture & Data Flow
• 🛡️ CVE & Vulnerability Coverage Matrix
• 🚀 Installation & Setup
• 💻 CLI Usage Guide
  • Global Flags
  • Subcommands
• 🖥️ Interactive TUI Menu
• 🛠️ Developer Workflows (Makefile)
• ⚖️ Legal & Ethical Warning

• 🚀 Dual-Engine Execution: High-concurrency async network engine (powered by aiohttp) for bulk scans, alongside a robust synchronous thread-pool worker engine.
• 🕵️ Deep Endpoint Discovery: Parses sitemaps, processes __NEXT_DATA__ structures inside Next.js pages, extracts React Server Action mappings (Next-Action), analyzes JavaScript routes, and tests actuator/GraphQL paths.
• 👺 Advanced WAF Evasion: Dynamic header randomization, junk query parameters/body padding, Base64 & Hex payload mutations, character encoding bypasses, and intelligent rate limiting (jitter).
• 🔎 Safe Auditing Modes: Fully passive checks (no commands executed) testing for vulnerable encoding behaviors, configuration leakage (e.g. Actuators, log4j core libraries), and estimation of Log2Shell/Log4Shell risks.
• 📡 OOB & Blind Verification: Fully integrates with self-hosted Interactsh OOB servers to detect blind RCE via DNS/HTTP call-backs, plus dual-marker echo validation.
• 🔌 Enterprise Reporting & Integrations: Generates clean TXT, JSON, HTML (interactive charts), and SARIF files. Easily uploads scan data to DefectDojo or exports templates into Nuclei v3 format.

Spring2Shell uses a clean src-layout package structure separating core logic, payloads, configuration profiles, and reporting:

src/spring2shell/
├── cli.py             # Argparse dispatching & runtime bootstrapping
├── core/              # Scan engine, exploiter, OOB, and reporter logic
├── discovery/         # Sitemap/JS analyzers, actuator/GraphQL endpoint lists
├── evasion/           # WAF engine, header generators, payload mutation
├── audit/             # Passive auditing & Log4j dependency analyzers
├── react2shell/       # Next.js Server Actions & React RSC scanning
└── utils/             # DefectDojo upload, Nuclei exporting, auth, network helpers

The diagram below details the data flow from command execution to final reporting:

graph TD
    CLI[CLI / TUI Input] --> Boot[cli.py: configure_runtime & signals]
    Boot --> Conf{YAML Configuration}
    Conf -->|1. Build Session| Session[core/session: Stealth Session]
    Conf -->|2. Evasion Config| Evasion[evasion/waf_engine: Payload Mutations]
    Conf -->|3. Discovery Scan| Discov[discovery/endpoints: Parse Sitemap/JS]
    
    Session & Evasion & Discov --> Engine[core/scanner: Bulk or Direct Engine]
    
    Engine -->|Payload DB| PL[data/payloads/cve_payloads.json]
    Engine -->|Run Probes| Network[Target HTTP/S Endpoints]
    
    Network -->|Echo Marker / OOB| Verify[core/verifier: RCE Verification]
    Verify -->|Build Findings| Rep[core/reporter: Output Builder]
    
    Rep -->|JSON / HTML| Reports[reports/scan_results.json]
    Rep -->|SARIF Export| SARIF[reports/results.sarif]
    Rep -->|Nuclei YAML| Nuclei[nuclei_templates/]
    Rep -->|DefectDojo API| DefectDojo[DefectDojo Server]

Spring2Shell contains an externalized, up-to-date payload database (data/payloads/cve_payloads.json) targeting the following vectors:

Ensure you have Python 3.8+ installed. Set up the environment using the virtual environment helper:

# Clone the repository
git clone https://github.com/C00LN3T/Spring2Shell.git
cd Spring2Shell-1

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install development dependencies and editable package
make install-dev

These arguments apply to all subcommands and modify connection and diagnostic behaviors:

• --insecure: Disables TLS certificate validation (not recommended).
• --verbose-errors: Logs swallowed network exceptions to screen for diagnostics.
• --profile {default,aggressive,safe-audit,stealth}: Selects connection timeout, retry limits, and delays.
• --dry-run: Performs a dry-run showing what payloads and paths WOULD be sent, without making network requests.
• --proxy URL: Directs traffic through HTTP/SOCKS5 proxy (e.g. http://127.0.0.1:8080 or socks5://127.0.0.1:9050).
• --rate N: Throttles scanner to a maximum of N requests per second (0 = unlimited).
• --config FILE: Custom config path (defaults to ./config.yaml if it exists).

Runs passive encoding checks, exposed actuators, and misconfiguration scans without exploiting.

spring2shell safe-audit https://target.example -o reports/audit.json --html-report

Checks exposed paths and class definitions to estimate Log2Shell / Log4Shell risks.

spring2shell log-audit https://target.example -o reports/log_audit.json

Launches direct exploitation against a single host. You can customize the command payload or scope.

# Auto-detect endpoints and execute command
spring2shell direct https://target.example --find-endpoints -c "whoami"

# Exploit a specific endpoint using aggressive WAF bypass mutations
spring2shell direct https://target.example -e /api/graphql -c "id" --aggressive

Scans a list of target URLs. Supports resuming from checkpoints, report formatting, and encryption.

# Run scan with 15 concurrent threads, generate JSON/TXT/HTML reports, and encrypt output
spring2shell scan targets.txt reports/bulk_run -t 15 --html-report --encrypt-reports

Runs targeted CVE-specific probes across a targets list using the high-performance async engine.

spring2shell --rate 30 cve-scan targets.txt -o reports/cve_mass.json --async

Scans target for Server-Side Request Forgery or Server-Side Template Injection vulnerabilities.

spring2shell ssrf-scan https://target.example -o reports/ssrf.json --html-report
spring2shell ssti-scan https://target.example -o reports/ssti.json

Safely tests target behaviors to determine which characters/HTTP methods trigger WAF blocks.

spring2shell profile-waf https://target.example -o reports/waf_profile.json

Reruns an echo-marker and blind time-delay check to verify if a reported finding is an active vulnerable endpoint.

spring2shell verify https://target.example -e /api/graphql --method POST

Converts findings in a JSON report into custom Nuclei v3 YAML templates.

spring2shell nuclei-export reports/bulk_run_combined.json nuclei_templates/

Uploads scan results directly to your DefectDojo console.

spring2shell defectdojo-upload reports/bulk_run_combined.json \
  --url https://defectdojo.corp.internal \
  --api-key "APITOKENEXAMPLE12345" \
  --engagement-id 42

Run the terminal user interface menu to drive discovery, auditing, and exploitation interactively:

spring2shell menu

======================================================================
ULTIMATE REACT4SHELL / REACT2SHELL FRAMEWORK
CVE-2025-55182, CVE-2025-66478, Log4Shell, Spring4Shell, Text4Shell
======================================================================
  1.  Scan new targets (bulk)              ← Enter target file and threads
  2.  Load and exploit from existing report  ← Feed JSON report to shell driver
  3.  Direct exploitation (manual target)    ← Target URL, endpoint, and command
  4.  Verify RCE (echo-marker + blind test)  ← In-depth active vulnerability verify
  5.  Aggressive exploitation (WAF bypass)  ← Focuses mutations & encoding bypasses
  6.  CVE-specific scan                      ← Run precise payload tests on target
  7.  Find working endpoints (quick probe)   ← Run endpoint checkers
  8.  Safe full audit (encoding + logs + deps)← Aggregates non-intrusive risk checks
  9.  Log4Shell risk audit                   ← Run passive Log4j checks
  10. React2Shell probe                      ← Specific Next.js/React SA check
  11. SSRF scan                              ← Out-of-band/local SSRF probing
  12. SSTI scan                              ← Template injection payload scans
  13. Exit                                   ← Close TUI

Ensure code quality, execute tests, and manage local deployments using the configured Makefile targets:

• Setup Development Environment:

  make venv
  source .venv/bin/activate
  make install-dev

• Linting & Code Formatting (uses ruff for fast linting/formatting checks):

  make lint       # Inspect codebase
  make format     # Reformat code automatically

• Type checking:

  make typecheck  # Run mypy static type checking

• Running Tests (runs 247 unit tests and generates code coverage report):

  make test       # Full suite with coverage
  make test-unit  # Unit tests only