souleyez 2.41.1

AI-Powered Penetration Testing Platform with 40+ integrated tools

SoulEyez — AI-Powered Penetration Testing Platform

LEGAL NOTICE — Use Responsibly Only use SoulEyez on systems you own or have explicit written permission to test. Unauthorized scanning or exploitation is illegal. The authors are not responsible for misuse.

---

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
• 📈 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, theHarvester, whois, dnsrecon
• Web Testing: nikto, gobuster, ffuf, sqlmap, nuclei, wpscan
• Enumeration: enum4linux-ng, smbmap, crackmapexec, snmpwalk
• Exploitation: Metasploit integration, searchsploit
• Password Attacks: hydra, hashcat, john
• Post-Exploitation: impacket suite, bloodhound

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

Purple Team / SIEM Integration

• 🛡️ Wazuh Integration - Connect to Wazuh Manager for detection validation
• 📊 Splunk Integration - Query Splunk for alerts and vulnerability data
• ✓ Detection Validation - Verify if your attacks triggered SIEM alerts
• 🔍 Vulnerability Management - View CVEs from Wazuh agents synced to Splunk
• ⚖️ 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

---

🔐 Security & Data Protection

Credential Encryption

SoulEyez encrypts all stored credentials using Fernet (AES-128-CBC + HMAC-SHA256) with PBKDF2 key derivation (600k iterations).

# Enable encryption with master password
souleyez db encrypt

# Add credentials (automatically encrypted)
souleyez creds add --username admin --password secret123 --service ssh --host 10.0.0.82

# View credentials (requires master password)
souleyez creds list

Key Points:

• Master password is never stored (cannot be recovered if lost)
• Credentials encrypted at rest with industry-standard cryptography
• Dashboard shows masked values (••••••••) until explicitly revealed
• Each user should maintain their own database

Data Masking

Sensitive data is automatically masked in the UI:

• Passwords: Su***********3!
• Credit card numbers: 45**************34
• Access warning prompts before viewing sensitive data

See SECURITY.md for complete security guidelines.

---

📝 Configuration

SoulEyez uses a flexible configuration system:

1. Environment Variables - SOULEYEZ_* prefix (highest priority)
2. Config File - ~/.souleyez/config.json (auto-created)
3. Default Values - Built-in safe defaults

# Edit config file
nano ~/.souleyez/config.json

# Or use environment variables
export SOULEYEZ_DATABASE_PATH=/custom/path/souleyez.db
export SOULEYEZ_LOGGING_LEVEL=DEBUG

See docs/CONFIG.md for complete configuration options.

---

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
Other Linux	⚠️ Unofficial	Manual testing required
macOS/Windows	❌ Not Supported	Use Linux in a VM

Architectures: AMD64, ARM64

---

System Requirements

Component	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4GB	8GB+
Disk	10GB	50GB+
GPU	None	Optional (for hashcat)

---

Installation

# Install pipx if needed
sudo apt install pipx
pipx ensurepath
source ~/.bashrc    # Kali Linux: use 'source ~/.zshrc' instead

# Install SoulEyez
pipx install souleyez

# Install pentesting tools
souleyez setup

Kali Linux users: Kali uses zsh by default. Use source ~/.zshrc instead of source ~/.bashrc

See docs/user-guide/installation.md for detailed instructions.

---

Usage

Interactive Mode (Recommended)

souleyez interactive

Menu-driven interface with guided workflows, tool selection by phase, and integrated help.

Dashboard

souleyez dashboard

Real-time monitoring with hotkeys: [h] Help, [a] Auto-chain, [m] Menu, [q] Quit

Command Line

# Engagement management
souleyez workspace create <name>
souleyez workspace use <name>

# Run scans
souleyez run nmap <target>
souleyez run gobuster <target>

# View results
souleyez findings list
souleyez creds list

---

Documentation

• Installation Guide - Setup instructions
• Getting Started - Quick start guide
• Workflows - Complete pentesting workflows
• Evidence Vault - Artifact collection
• Report Generation - Professional reports
• SECURITY.md - Security best practices
• AUTO_CHAINING_GUIDE.md - Automated workflows

---

Support

• GitHub Issues: https://github.com/cyber-soul-security/SoulEyez/issues
• Security Issues: Report privately (see SECURITY.md)

---

License

See LICENSE for details.