souleyez 2.37.0__tar.gz → 2.41.1__tar.gz

souleyez-2.41.1/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: souleyez
+Version: 2.41.1
+Summary: AI-Powered Penetration Testing Platform with 40+ integrated tools
+Author-email: CyberSoul Security <contact@cybersoulsecurity.com>
+Maintainer-email: CyberSoul Security <contact@cybersoulsecurity.com>
+License: MIT
+Project-URL: Homepage, https://github.com/cyber-soul-security/SoulEyez
+Project-URL: Documentation, https://github.com/cyber-soul-security/SoulEyez#readme
+Project-URL: Repository, https://github.com/cyber-soul-security/SoulEyez.git
+Project-URL: Issues, https://github.com/cyber-soul-security/SoulEyez/issues
+Keywords: pentesting,security,hacking,penetration-testing,cybersecurity,nmap,metasploit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: cryptography>=3.4.0
+Requires-Dist: defusedxml>=0.7.0
+Requires-Dist: impacket>=0.11.0
+Requires-Dist: markdown>=3.4.0
+Requires-Dist: msgpack>=1.0.0
+Requires-Dist: ollama>=0.1.0
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: python-json-logger>=2.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: rich>=10.0.0
+Requires-Dist: wcwidth>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# SoulEyez — AI-Powered Penetration Testing Platform
+
+[![CI](https://github.com/cyber-soul-security/souleyez/actions/workflows/python-ci.yml/badge.svg)](https://github.com/cyber-soul-security/souleyez/actions/workflows/python-ci.yml)
+[![codecov](https://codecov.io/gh/cyber-soul-security/souleyez/branch/main/graph/badge.svg)](https://codecov.io/gh/cyber-soul-security/souleyez)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+
+**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).
+
+```bash
+# 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](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
+
+```bash
+# 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](souleyez/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
+
+```bash
+# 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](souleyez/docs/user-guide/installation.md) for detailed instructions.
+
+---
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+```bash
+souleyez interactive
+```
+
+Menu-driven interface with guided workflows, tool selection by phase, and integrated help.
+
+### Dashboard
+
+```bash
+souleyez dashboard
+```
+
+Real-time monitoring with hotkeys: `[h]` Help, `[a]` Auto-chain, `[m]` Menu, `[q]` Quit
+
+### Command Line
+
+```bash
+# 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](souleyez/docs/user-guide/installation.md)** - Setup instructions
+- **[Getting Started](souleyez/docs/user-guide/getting-started.md)** - Quick start guide
+- **[Workflows](souleyez/docs/user-guide/workflows.md)** - Complete pentesting workflows
+- **[Evidence Vault](souleyez/docs/user-guide/evidence-vault.md)** - Artifact collection
+- **[Report Generation](souleyez/docs/user-guide/report-generation.md)** - Professional reports
+- **[SECURITY.md](SECURITY.md)** - Security best practices
+- **[AUTO_CHAINING_GUIDE.md](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](LICENSE) for details.

{souleyez-2.37.0 → souleyez-2.41.1}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "souleyez"
-version = "2.37.0"
+version = "2.41.1"
 description = "AI-Powered Penetration Testing Platform with 40+ integrated tools"
-readme = "BETA_README.md"
+readme = "README.md"
 license = {text = "MIT"}
 authors = [{name = "CyberSoul Security", email = "contact@cybersoulsecurity.com"}]
 maintainers = [{name = "CyberSoul Security", email = "contact@cybersoulsecurity.com"}]

souleyez-2.41.1/souleyez/__init__.py

@@ -0,0 +1,2 @@
+__version__ = '2.41.1'
+

{souleyez-2.37.0 → souleyez-2.41.1}/souleyez/docs/README.md

@@ -1,7 +1,7 @@
 # SoulEyez Documentation
 
-**Version:** 2.37.0
-**Last Updated:** January 9, 2026
+**Version:** 2.41.1
+**Last Updated:** January 10, 2026
 **Organization:** CyberSoul Security
 
 Welcome to the SoulEyez documentation! This documentation covers architecture, development, user guides, and operational information for the SoulEyez penetration testing platform.

{souleyez-2.37.0 → souleyez-2.41.1}/souleyez/main.py

@@ -173,7 +173,7 @@ def _check_privileged_tools():
 
 
 @click.group()
-@click.version_option(version='2.37.0')
+@click.version_option(version='2.41.1')
 def cli():
     """SoulEyez - AI-Powered Pentesting Platform by CyberSoul Security"""
     from souleyez.log_config import init_logging
@@ -1512,47 +1512,14 @@ def _run_doctor(fix=False, verbose=False):
 
     # Section 4: Pentesting Tools
     click.echo(click.style("Pentesting Tools", bold=True))
-    # Map display name -> list of possible binary names (first found wins)
-    pentest_tools = {
-        # Core scanning
-        'nikto': ['nikto'],
-        'gobuster': ['gobuster'],
-        'ffuf': ['ffuf'],
-        'nuclei': ['nuclei'],
-        # Exploitation
-        'sqlmap': ['sqlmap'],
-        'hydra': ['hydra'],
-        'msfconsole': ['msfconsole'],
-        # Enumeration (enum4linux-ng on Ubuntu, netexec replaced crackmapexec)
-        'enum4linux': ['enum4linux', 'enum4linux-ng'],
-        'smbmap': ['smbmap'],
-        'netexec': ['netexec', 'nxc', 'crackmapexec'],
-        # Recon
-        'theHarvester': ['theHarvester'],
-        'dnsrecon': ['dnsrecon'],
-        'whois': ['whois'],
-        # Password cracking
-        'hashcat': ['hashcat'],
-        'john': ['john'],
-        # Router/IoT (rsf.py for pipx installs)
-        'routersploit': ['rsf', 'rsf.py', 'routersploit'],
-        'upnpc': ['upnpc'],
-        'binwalk': ['binwalk'],
-        # Remote access
-        'vncviewer': ['vncviewer'],
-    }
-    installed = 0
-    for display_name, binaries in pentest_tools.items():
-        found = any(shutil.which(b) for b in binaries)
-        if found:
-            installed += 1
-            if verbose:
-                check_pass(display_name)
+    # Use the same tool checker as the setup wizard for consistency
+    from souleyez.utils.tool_checker import get_tool_stats
+    installed, total = get_tool_stats()
 
-    if installed == len(pentest_tools):
-        check_pass(f"All {len(pentest_tools)} tools installed")
+    if installed == total:
+        check_pass(f"All {total} tools installed")
     elif installed > 0:
-        check_warn(f"{installed}/{len(pentest_tools)} tools installed", "Run: souleyez setup")
+        check_warn(f"{installed}/{total} tools installed", "Run: souleyez setup")
     else:
         check_fail("No pentesting tools installed", "souleyez setup")
 

{souleyez-2.37.0 → souleyez-2.41.1}/souleyez/ui/tool_setup.py

@@ -24,6 +24,19 @@ from souleyez.utils.tool_checker import (
 )
 from souleyez.ui.design_system import DesignSystem
 
+
+def _reset_terminal():
+    """Reset terminal to sane state after interrupt."""
+    try:
+        # Reset terminal using stty
+        subprocess.run(['stty', 'sane'], check=False, timeout=5)
+        # Also try the reset command for good measure
+        subprocess.run(['reset', '-I'], check=False, timeout=5,
+                       stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    except Exception:
+        pass
+
+
 # Prerequisites needed for various install methods
 PREREQUISITES = {
     'build-deps': {
@@ -118,10 +131,15 @@ def _add_paths_to_shell_rc():
 
 def _run_command(cmd: str, console, description: str = "", capture: bool = False) -> tuple:
     """Run a command with proper error handling."""
+    import sys
     try:
         # Never capture sudo commands - password prompt needs to be visible
         if cmd.strip().startswith('sudo'):
             capture = False
+            # Flush output and print newline so sudo prompt appears on new line
+            sys.stdout.flush()
+            sys.stderr.flush()
+            print()  # Newline for sudo password prompt
 
         if capture:
             result = subprocess.run(
@@ -136,6 +154,7 @@ def _run_command(cmd: str, console, description: str = "", capture: bool = False
             result = subprocess.run(
                 cmd,
                 shell=True,
+                stdin=sys.stdin,  # Ensure stdin is connected for password input
                 timeout=600
             )
             return result.returncode == 0, "", ""
@@ -374,6 +393,17 @@ def _ensure_msfdb_initialized(console):
 
 def run_tool_setup(check_only: bool = False, install_all: bool = False):
     """Run the tool setup wizard."""
+    try:
+        _run_tool_setup_impl(check_only, install_all)
+    except KeyboardInterrupt:
+        # Reset terminal to sane state after Ctrl+C
+        _reset_terminal()
+        print("\n\n  Setup cancelled.")
+        raise
+
+
+def _run_tool_setup_impl(check_only: bool = False, install_all: bool = False):
+    """Internal implementation of tool setup wizard."""
     console = DesignSystem.get_console()
     distro = detect_distro()
 

souleyez-2.41.1/souleyez.egg-info/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: souleyez
+Version: 2.41.1
+Summary: AI-Powered Penetration Testing Platform with 40+ integrated tools
+Author-email: CyberSoul Security <contact@cybersoulsecurity.com>
+Maintainer-email: CyberSoul Security <contact@cybersoulsecurity.com>
+License: MIT
+Project-URL: Homepage, https://github.com/cyber-soul-security/SoulEyez
+Project-URL: Documentation, https://github.com/cyber-soul-security/SoulEyez#readme
+Project-URL: Repository, https://github.com/cyber-soul-security/SoulEyez.git
+Project-URL: Issues, https://github.com/cyber-soul-security/SoulEyez/issues
+Keywords: pentesting,security,hacking,penetration-testing,cybersecurity,nmap,metasploit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: cryptography>=3.4.0
+Requires-Dist: defusedxml>=0.7.0
+Requires-Dist: impacket>=0.11.0
+Requires-Dist: markdown>=3.4.0
+Requires-Dist: msgpack>=1.0.0
+Requires-Dist: ollama>=0.1.0
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: python-json-logger>=2.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: rich>=10.0.0
+Requires-Dist: wcwidth>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# SoulEyez — AI-Powered Penetration Testing Platform
+
+[![CI](https://github.com/cyber-soul-security/souleyez/actions/workflows/python-ci.yml/badge.svg)](https://github.com/cyber-soul-security/souleyez/actions/workflows/python-ci.yml)
+[![codecov](https://codecov.io/gh/cyber-soul-security/souleyez/branch/main/graph/badge.svg)](https://codecov.io/gh/cyber-soul-security/souleyez)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+
+**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).
+
+```bash
+# 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](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
+
+```bash
+# 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](souleyez/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
+
+```bash
+# 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](souleyez/docs/user-guide/installation.md) for detailed instructions.
+
+---
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+```bash
+souleyez interactive
+```
+
+Menu-driven interface with guided workflows, tool selection by phase, and integrated help.
+
+### Dashboard
+
+```bash
+souleyez dashboard
+```
+
+Real-time monitoring with hotkeys: `[h]` Help, `[a]` Auto-chain, `[m]` Menu, `[q]` Quit
+
+### Command Line
+
+```bash
+# 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](souleyez/docs/user-guide/installation.md)** - Setup instructions
+- **[Getting Started](souleyez/docs/user-guide/getting-started.md)** - Quick start guide
+- **[Workflows](souleyez/docs/user-guide/workflows.md)** - Complete pentesting workflows
+- **[Evidence Vault](souleyez/docs/user-guide/evidence-vault.md)** - Artifact collection
+- **[Report Generation](souleyez/docs/user-guide/report-generation.md)** - Professional reports
+- **[SECURITY.md](SECURITY.md)** - Security best practices
+- **[AUTO_CHAINING_GUIDE.md](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](LICENSE) for details.

{souleyez-2.37.0 → souleyez-2.41.1}/souleyez.egg-info/SOURCES.txt

@@ -1,4 +1,3 @@
-BETA_README.md
 LICENSE
 MANIFEST.in
 README.md