souleyez 1.4.5

AI-Powered Penetration Testing Platform with 40+ integrated tools

SoulEyez — CyberSoul SecurITy Recon Suite

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 Tracking - Discover and organize enumerated usernames and passwords
• 🔐 Credential Encryption - Encrypt credentials at storage with master password protection
• 💥 Password Cracking - Offline hash cracking with Hashcat (300+ hash types)
• 🌐 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

Pentest Workflow & Intelligence

• 📁 Evidence Vault - Unified artifact collection organized by PTES methodology phases
• 🎯 Attack Surface Dashboard - Track what's exploited vs pending with priority scoring
• 💣 Exploit Suggestions - Automatic CVE/Metasploit module recommendations for discovered services
• 🔗 Correlation Engine - Cross-phase attack tracking and gap analysis
• 📝 Report Generator - One-click professional reports in Markdown/HTML/PDF formats
• ✅ Deliverable Tracking - Manage testing requirements and acceptance criteria
• 📸 Screenshot Management - Organized visual evidence by methodology phase

---

🔐 Security Features

Credential Encryption

SoulEyez encrypts all credentials at storage using industry-standard cryptography (Fernet/AES-128).

Credentials are automatically encrypted when stored:

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

# Encrypt existing credentials
souleyez db encrypt

You'll set a master password that encrypts all stored credentials. The dashboard shows masked credentials (••••••••), while the CLI prompts for your password when viewing or using actual values.

Password Cracking (Hashcat)

Crack password hashes offline with Hashcat integration:

# Basic dictionary attack
souleyez jobs enqueue hashcat hashes.txt --args "-m 1000 /usr/share/wordlists/rockyou.txt"

# NTLM with rules
souleyez jobs enqueue hashcat ntlm.txt --args "-m 1000 -r /usr/share/hashcat/rules/best64.rule rockyou.txt"

# Interactive menu
souleyez interactive → Data Management → Credentials → [c] Crack Hashes

Supported hash types:

• Windows: NTLM, NetNTLMv2
• Linux: SHA-512, MD5 shadow
• Web: MD5, bcrypt, SHA-256
• 300+ total hash types via -m parameter

Performance: 100K-10M hashes/sec (GPU accelerated, zero detection risk)

For full documentation, see SECURITY.md

Important:

• Master password is never stored (cannot be recovered if lost)
• Credentials are encrypted at storage time (defense-in-depth)
• Each user should have their own database and password
• Cracked passwords from Hashcat are automatically stored encrypted

---

📝 Configuration

SoulEyez uses a flexible configuration system with three priority levels:

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

Quick Start

Config file is automatically created on first run. To customize:

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

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

Key Configuration Options

• Database Path - Where engagement data is stored
• Crypto Settings - Encryption strength (600k iterations default)
• Security - Session timeout, login attempts, password requirements
• Logging - Level, format, and file rotation

For complete documentation, see docs/CONFIG.md

---

🗄️ Database

SoulEyez uses SQLite with a normalized relational schema and automatic migrations.

Key Features:

• Foreign key constraints for data integrity
• Cascade deletes for engagement cleanup
• 14 performance indexes for fast queries
• Automatic migration system
• Rollback support for schema changes

Documentation:

• Database Schema - Complete table documentation
• Schema ERD - Visual relationship diagram
• Migration Guide - Managing schema changes

---

📋 Logging

SoulEyez uses structured JSON logging for debugging, monitoring, and audit trails.

Features:

• JSON-formatted logs for easy parsing
• Automatic log rotation
• Searchable with jq or grep
• Job correlation IDs
• Performance timing

Log Location: ~/.souleyez/souleyez.log

Quick Examples:

# View recent errors
cat ~/.souleyez/souleyez.log | jq 'select(.levelname=="ERROR")'

# Track a specific job
cat ~/.souleyez/souleyez.log | jq 'select(.job_id==123)'

# Find slow operations
cat ~/.souleyez/souleyez.log | jq 'select(.duration_ms > 1000)'

For complete documentation, see docs/LOGGING.md

---

Supported Operating Systems

OS	Status	Notes
Kali Linux	✅ Recommended	All pentesting tools pre-installed, ARM64 + AMD64 supported
Ubuntu 22.04+	✅ Supported	Clean base system, tools installed via souleyez setup
Parrot OS	✅ Supported	Security-focused distro, similar to Kali
Debian 12+	✅ Supported	Stable base, tools installed via souleyez setup
Other Linux	⚠️ Unofficial	Arch, Fedora, etc. - manual testing required
macOS	❌ Not Supported	Use Kali/Parrot in a VM instead
Windows	❌ Not Supported	Use Kali/Parrot in a VM instead

Beginners: Kali Linux or Parrot OS - all pentesting tools pre-installed, zero configuration needed.

Experienced Pentesters: Ubuntu or Debian for a cleaner base system with only the tools you need.

Architectures: Both AMD64 (x86_64) and ARM64 binaries are available.

---

System Requirements

Component	Minimum	Recommended	Heavy Workloads (Llama + Multiple Tools)
CPU	2 cores	4 cores	8+ cores
RAM	4GB	8GB	16GB+ (Llama models require 8-64GB)
GPU	None	Optional	NVIDIA GPU with 8GB+ VRAM
Disk	10GB	50GB	100GB+ (Llama models: 4-40GB each)

See docs/user-guide/installation.md for complete hardware and software requirements.

---

Installation

curl -sSL https://raw.githubusercontent.com/cyber-soul-security/SoulEyez/main/scripts/install.sh | bash

This automatically detects your OS, installs dependencies, and sets up SoulEyez.

For other installation methods (pip, .deb packages, from source), see docs/user-guide/installation.md.

---

Usage

Interactive Dashboard

Launch the live dashboard for your engagement:

souleyez dashboard

Hotkeys:

• [h] - Help Center (Security guide, Auto-chaining guide, README)
• [a] - Toggle auto-chaining
• [t] - Toggle dashboard sections
• [m] - Interactive menu
• [q] - Quit

Command Line

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

# Credential viewing (with encryption support)
souleyez creds list

# View findings
souleyez findings list

# Run tools
souleyez run nmap <target>

---

Documentation

Getting Started

• docs/user-guide/installation.md - Installation and setup instructions
• docs/user-guide/getting-started.md - Quick start guide
• docs/user-guide/workflows.md - Complete pentesting workflows
• docs/user-guide/uninstall.md - Uninstall guide (keep or remove data)

Pentest Workflow Features

• docs/user-guide/evidence-vault.md - Unified evidence collection and export
• docs/user-guide/attack-surface.md - Attack surface analysis and exploitation tracking
• docs/user-guide/exploit-suggestions.md - Automatic CVE and exploit recommendations
• docs/user-guide/report-generation.md - Professional report generation (MD/HTML/PDF)
• docs/user-guide/deliverables-screenshots.md - Testing requirements and visual evidence

Security & Advanced Topics

• SECURITY.md - Credential encryption & security best practices
• AUTO_CHAINING_GUIDE.md - Automated tool workflow documentation
• GIT_WORKFLOW.md - Git branching and contribution guidelines

---

Support

For issues, questions, or security concerns:

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

---

License

See LICENSE for details.

🔐 Security Features

SQLMap Data Encryption

Sensitive data dumped by SQLMap (credit cards, passwords, PII) can be encrypted at rest:

# Enable encryption (required first time)
python3 migrate_credentials.py

# Encrypt SQLMap dumped data
python3 migrate_sqlmap_data.py

Data Masking

Sensitive columns are automatically masked in the UI:

• Credit card numbers: 45**************34
• Passwords: Su***********3!
• CVV codes: ***

Access warning prompt before viewing sensitive data.

See docs/SQLMAP_DATA_SECURITY.md for complete security guidelines.