Important

Privilege escalation reasoning engine. Parses LinPEAS/WinPEAS output and generates ranked exploitation playbooks. 329 GTFOBins entries, 86 LOLBAS binaries, 42 kernel exploits, 9 potato attacks with composite scoring and attack chain detection.

A whirlpool is a swirling vortex that draws everything into its center, creating powerful currents from scattered elements. Perfect metaphor for a reasoning engine that takes fragmented enumeration findings and draws them together into focused, prioritized attack strategies.

---

§1 / Premise

Whirlpool is a privilege escalation reasoning engine that transforms raw enumeration output into ranked exploitation playbooks. Feed it LinPEAS, WinPEAS, or manual command output and receive prioritized attack plans with exact commands, confidence ratings, and multi-step attack chains.

The engine matches findings against comprehensive offline knowledge bases containing 329 GTFOBins entries, 86 LOLBAS binaries, 42 kernel exploits, and 9 potato attacks. Everything runs offline with no API calls or internet requirements—pure analysis of enumeration data.

Authorization Required: Designed exclusively for authorized security testing with explicit written permission.

---

§2 / Specs

KEY	VALUE
PARSING	Auto-detection · LinPEAS · WinPEAS · manual commands with format variants
KNOWLEDGE	329 GTFOBins · 86 LOLBAS · 42 kernel exploits · 9 potato attacks
SCORING	Composite ranking with 5 profiles (default, OSCP, CTF, stealth, safe)
CHAINS	12 attack chain types for multi-step privilege escalation paths
ENGINE	Pure offline analysis with no network calls or API dependencies
OUTPUT	Terminal UI · Markdown · JSON with Catppuccin Mocha theming
FILTERING	Noise reduction with purpose-built parsers and false-positive filtering
PLATFORM	Python 3.9+ · Linux/Windows/macOS cross-platform compatibility

---

§3 / Quickstart

Prerequisites: Python 3.9+, pip or pipx

# Install reasoning engine
pipx install git+https://github.com/Real-Fruit-Snacks/Whirlpool.git

# Analyze enumeration output (auto-detected format)
whirlpool linpeas_output.txt
whirlpool winpeas_output.txt

# Generate focused playbook with top techniques
whirlpool enum.txt --quick-wins

# OSCP-optimized ranking for exam scenarios
whirlpool enum.txt --profile oscp

# Export structured analysis to markdown
whirlpool enum.txt --format markdown --output report.md

---

§4 / Reference

# ANALYSIS & PROFILES
whirlpool enum.txt                                    # Auto-detect format, analyze
whirlpool enum.txt --profile oscp                    # OSCP-optimized ranking
whirlpool enum.txt --profile ctf                     # Speed-focused for CTFs
whirlpool enum.txt --profile stealth                 # Low-detection techniques
whirlpool enum.txt --profile safe                    # System stability priority

# OUTPUT FORMATS
whirlpool enum.txt --quick-wins                       # Top 5 techniques only
whirlpool enum.txt --format markdown --output report.md  # Markdown export
whirlpool enum.txt --format json > results.json      # Structured JSON
whirlpool enum.txt --lhost 10.10.14.1 --lport 4444   # IP/port substitution

# CHAIN ANALYSIS
whirlpool enum.txt                                    # Chains enabled (default)
whirlpool enum.txt --no-chains                       # Disable multi-step detection

# COMPARISON & DIFFING
whirlpool first.txt --diff second.txt                # Compare two scans

# SUPPORTED FORMATS (auto-detected)
# LinPEAS .sh output (Unicode box headers)
# WinPEAS .exe output, .bat output, .exe beta format  
# Manual command output

---

§5 / Architecture

Three-Stage Pipeline: Parse enumeration → Analyze against knowledge bases → Rank with composite scoring

whirlpool/
├── cli.py              # Argparse entry point, auto-detection, output routing
├── parser/             # LinPEAS, WinPEAS, manual command parsers (3 variants)
├── engine/
│   ├── analyzer.py     # Core analysis matches findings against databases
│   ├── ranker.py       # Composite scoring with 5 ranking profiles
│   └── chain.py        # Multi-step attack chain detection (12 types)
├── data/               # Offline JSON knowledge bases (no network calls)
│   ├── gtfobins.json   # 329 binaries from GTFOBins
│   ├── lolbas.json     # 86 binaries from LOLBAS Project
│   ├── kernel_exploits.json  # 42 CVEs (23 Linux + 19 Windows)
│   └── potato_matrix.json    # 9 attacks with OS compatibility
├── output/             # Terminal (Catppuccin), Markdown, JSON renderers
└── tests/              # 237 tests with HTB/Vulnhub samples

Composite Scoring: Every technique scored across reliability (success likelihood), safety (system stability), simplicity (execution ease), and stealth (detection avoidance).

---

§6 / Authorization

Whirlpool is designed for authorized security testing with explicit written permission. The tool generates exploitation playbooks that should only be used against systems you own or have proper authorization to test.

Security vulnerabilities should be reported via GitHub Security Advisories with 90-day responsible disclosure.

Whirlpool does not: execute generated commands, scan hosts, perform active reconnaissance, make network connections, or manage persistent access—it's purely an offline analysis engine.

---

Real-Fruit-Snacks — All projects · Security · License