SoulEyez — AI-Powered Penetration Testing Platform
What is SoulEyez?
SoulEyez is your penetration testing command center. Instead of juggling dozens of terminal windows and text files, SoulEyez gives you one organized place to:
- Run security scans — Execute tools like Nmap, Gobuster, SQLMap with simple commands
- Auto-discover next steps — When one scan finds something interesting, SoulEyez automatically suggests (or runs) the next logical tool
- Stay organized — Keep all your targets, findings, and credentials in one searchable database
- Generate reports — Export professional reports when you're done
Who is this for?
- Security professionals conducting authorized penetration tests
- CTF players who want better organization during competitions
- Students learning penetration testing methodology
Important: Only use SoulEyez on systems you have explicit authorization to test. Unauthorized scanning or exploitation is illegal.
Features
Core Capabilities
- 🎯 Interactive Dashboard — Real-time engagement monitoring with live updates
- 🔗 Smart Tool Chaining — Automatic follow-up scans based on discoveries
- 📊 Findings Management — Track and categorize vulnerabilities by severity
- 🔑 Credential Vault — Encrypted storage for discovered credentials
- 🌐 Network Mapping — Host discovery and service enumeration
- ☁️ Cloud Attack Paths — Turn a web SSRF into cloud IAM credentials (IMDS), enumerate, escalate to admin, and pivot back to on-prem
- 📈 Progress Tracking — Monitor scan completion and tool execution
- 💾 SQLite Storage — Local database for all engagement data
- 🔄 Background Jobs — Queue-based tool execution with status monitoring
Integrated Tools (40+)
- Reconnaissance: nmap, masscan, osint_recon, whois, dnsrecon, http_fingerprint
- Web Testing: nikto, web_fuzzer, katana, sqlmap, nuclei, wpscan, dalfox
- API & Auth: api_bola (BOLA/IDOR), jwt_scan (JWT attacks), http_request (authenticated requests)
- Enumeration: enum4linux-ng, smbmap, ad_enum, snmpwalk, service_explorer (FTP/SFTP/NFS/SMB/Redis/MongoDB browsing & loot)
- Exploitation: Metasploit integration, searchsploit
- Password Attacks: hydra, hashcat, john
- Post-Exploitation: impacket suite, bloodhound
- Cloud: cloud_ssrf (SSRF → IMDS credential loot), aws_enum (cloud enumeration + privesc), ssh_pivot (cloud → on-prem)
Pentest Workflow & Intelligence
- 📁 Evidence Vault — Unified artifact collection organized by PTES phases
- 🎯 Attack Surface Dashboard — Track what's exploited vs pending with priority scoring
- 💣 Exploit Suggestions — Automatic CVE/Metasploit recommendations for discovered services
- 🔗 Correlation Engine — Cross-phase attack tracking and gap analysis
- 📝 Report Generator — Professional reports in Markdown/HTML/PDF formats
- ✅ Deliverable Tracking — Manage testing requirements and acceptance criteria
- 📸 Screenshot Management — Organized visual evidence by methodology phase
SIEM Integration
- 🛡️ SIEM Connectors — Connect to Wazuh, Splunk, and other SIEM platforms
- ✓ Detection Validation — Verify if your attacks triggered SIEM alerts
- 🔍 Vulnerability Management — View CVEs from SIEM vulnerability data
- ⚖️ Gap Analysis — Compare passive (SIEM) vs active (scan) findings
- 🗺️ MITRE ATT&CK Reports — Detection coverage heatmaps by technique
- 📡 Real-time Alerts — Monitor SIEM alerts during live engagements
Practice Lab
- 🧪 Built-in vulnerable lab —
souleyez labspins up intentionally-vulnerable practice targets in Docker on an isolated network, so you always have something safe to point SoulEyez at (learning, demos, chain regression testing) - 🎯 Four turnkey targets — the Soul family, wired as a three-zone
shop → cloud → on-premspine so a single attack path crosses every boundary:- Soul Shop — a LAMP storefront (SQLi, reflected/stored XSS, config leak); the external entry point of the spine
- SoulAPI — a FastAPI/JWT API backend (weak-secret token forgery, BOLA/IDOR)
- Stratosphere — a self-contained mini cloud estate (vulnerable web app + AWS/GCP/Azure metadata + fake cloud account + crown-jewels vault + on-prem box) for the full web → cloud → on-prem SSRF kill chain
- SoulSearching — a modern-day, all-in-one Metasploitable box (web SQLi → crack, RCE / file upload, SSH/FTP/SMB/MySQL with credential reuse, WordPress / WPScan, the Apache 2.4.49 CVE-2021-41773); the on-prem box the cloud loot pivots into → root
- 🛰️ Discovery-first by default — the Lab Targets table masks each host's IP
behind the subnet scope, so you find targets with nmap like a real engagement
(press
[r]to reveal for the session) - 🧭 Guided setup — walks you through Docker install, daemon, and the docker-group step; the Soul-family targets are multi-arch and run natively on amd64 and arm64 (no emulation needed)
- 📋 Beginner cheat sheets — a step-by-step SoulEyez attack walkthrough for
each target (
souleyez lab cheatsheet <target>), sourced from the tool's own attack-path tests
⚠️ These targets are vulnerable by design. They run on an isolated
souleyez-labbridge network — never expose them to an untrusted network.
FREE vs PRO
| Feature | FREE | PRO |
|---|---|---|
| Core features (scans, findings, credentials) | ✅ | ✅ |
| Report generation | ✅ | ✅ |
| AI-powered suggestions & auto-chaining | ❌ | ✅ |
| Metasploit integration & exploit suggestions | ❌ | ✅ |
| SIEM integration & detection validation | ❌ | ✅ |
| MITRE ATT&CK reports | ❌ | ✅ |
Quick Start
Step 1: Install Prerequisites
sudo apt install pipx # Install pipx
pipx ensurepath # Add pipx apps to your PATH
source ~/.bashrc # Reload shell (Kali: use ~/.zshrc)
Step 2: Install SoulEyez
pipx install souleyez
Step 3: Launch SoulEyez
souleyez interactive
Step 4: First-Time Setup
On your first run, the setup wizard guides you through:
- Vault Password — Create a master password that encrypts sensitive data
- First Engagement — Set up your first project and select engagement type
- Tool Check — Detect and optionally install missing security tools
- AI Setup — Configure Ollama for AI features (optional)
- Tutorial — Option to run the interactive tutorial (recommended)
Step 5: You're Ready!
Once setup completes, you'll see the main menu.
System Requirements
| Component | Minimum | Recommended |
|---|---|---|
| OS | Ubuntu 22.04+ | Kali Linux |
| Python | 3.8+ | 3.11+ |
| RAM | 4GB | 8GB+ |
| Disk | 10GB | 50GB+ |
Supported Operating Systems
| OS | Status | Notes |
|---|---|---|
| Kali Linux | ✅ Recommended | All pentesting tools pre-installed |
| Ubuntu 22.04+ | ✅ Supported | Tools installed via souleyez setup |
| Parrot OS | ✅ Supported | Security-focused distro |
| Debian 12+ | ✅ Supported | Stable base system |
| macOS/Windows | ❌ Not Supported | Use Linux in a VM |
Common Commands
| Command | What it does |
|---|---|
souleyez interactive |
Launch the main interface |
souleyez dashboard |
Real-time monitoring view |
souleyez doctor |
Check if everything is set up correctly |
souleyez setup |
Install/update pentesting tools |
souleyez lab up |
Start the built-in vulnerable practice lab |
souleyez lab status |
Show lab targets and their IPs/URLs |
souleyez lab cheatsheet <target> |
Beginner attack guide for a lab target |
souleyez --help |
Show all available commands |
Security & Encryption
SoulEyez encrypts all stored credentials using Fernet (AES-128-CBC + HMAC-SHA256) with PBKDF2 key derivation (600k iterations).
- Master password is never stored (cannot be recovered if lost)
- Credentials encrypted at rest with industry-standard cryptography
- Sensitive data is masked in the UI until explicitly revealed
See SECURITY.md for complete security guidelines.
Documentation
- Getting Started — Your first engagement in 10 minutes
- Installation Guide — Detailed setup instructions
- Workflows — Complete pentesting workflows
- Auto-Chaining — Automatic follow-up scans
- Configuration — All configuration options
- Troubleshooting — Common issues and fixes
Troubleshooting
| Problem | Solution |
|---|---|
| "command not found: souleyez" | Run pipx ensurepath then restart terminal |
| "Tool not found" errors | Run souleyez setup to install missing tools |
| Forgot vault password | Data is encrypted — start fresh with rm -rf ~/.souleyez |
| Something seems broken | Run souleyez doctor to diagnose |
Glossary
New to pentesting? Here are some common terms:
| Term | Meaning |
|---|---|
| Engagement | A project or assessment — contains all data for one test |
| Target/Host | A computer, server, or device you're testing |
| Finding | A security issue or vulnerability you discovered |
| Credential | Username/password combo found during testing |
Support & Feedback
- Issues: https://github.com/cyber-soul-security/souleyez/issues
- Security Issues: cysoul.secit@gmail.com (see SECURITY.md)
- General: cysoul.secit@gmail.com
License
See LICENSE for details.
Version: 5.0.4 | Maintainer: CyberSoul Security
1 maintainer
Metadata
1 maintainer
Release files for souleyez 5.0.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| souleyez-5.0.4.tar.gz | 2.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| souleyez-5.0.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 5.1 MB
Release files / souleyez-5.0.4.tar.gz
| Download URL | souleyez-5.0.4.tar.gz |
|---|---|
| Size | 2.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
790ac46393383ca2ecbaf423f8e75e4f47b513e471ce02482569cb3588d0bbb0
|
|
BLAKE2b-256 checksum How to use checksums |
30f4aeef54a49909bef475bfabd2806e089a740712d82b11115a6512f1e86504
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 12, 2026.
Transparency logRelease files / souleyez-5.0.4-py3-none-any.whl
| Download URL | souleyez-5.0.4-py3-none-any.whl |
|---|---|
| Size | 2.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2f7001136a4a57e4cd12b0f0548baded238b7af120d5a3d19c9d0a28ac253091
|
|
BLAKE2b-256 checksum How to use checksums |
39ace947c7e6f62a335e16fd0a350b6bf259bec11948e3c4cd3e74715d78d74b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 12, 2026.
Transparency log
