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:**

```bash
# 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:

```bash
# 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](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:

```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
```

### 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](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](docs/database/SCHEMA.md) - Complete table documentation
- [Schema ERD](docs/database/SCHEMA_ERD.md) - Visual relationship diagram
- [Migration Guide](docs/database/MIGRATIONS.md) - 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:**
```bash
# 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](docs/LOGGING.md)**

---

## Supported Operating Systems

| OS | Status | Notes |
|----|--------|-------|
| **Kali Linux** | ✅ Recommended | All pentesting tools pre-installed |
| **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:** Works on any platform Python supports (AMD64, ARM64, etc.)

---

## 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](docs/user-guide/installation.md) for complete hardware and software requirements.

---

## Installation

```bash
pip install souleyez
```

On first run, SoulEyez will prompt you to install pentesting tools (nmap, sqlmap, gobuster, etc.).

For other installation methods, see [docs/user-guide/installation.md](docs/user-guide/installation.md).

---

## Usage

### Interactive Dashboard

Launch the live dashboard for your engagement:

```bash
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

```bash
# 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](docs/user-guide/installation.md)** - Installation and setup instructions
- **[docs/user-guide/getting-started.md](docs/user-guide/getting-started.md)** - Quick start guide
- **[docs/user-guide/workflows.md](docs/user-guide/workflows.md)** - Complete pentesting workflows
- **[docs/user-guide/uninstall.md](docs/user-guide/uninstall.md)** - Uninstall guide (keep or remove data)

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

### Security & Advanced Topics
- **[SECURITY.md](SECURITY.md)** - Credential encryption & security best practices
- **[AUTO_CHAINING_GUIDE.md](AUTO_CHAINING_GUIDE.md)** - Automated tool workflow documentation
- **[GIT_WORKFLOW.md](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](LICENSE) for details.

## 🔐 Security Features

### SQLMap Data Encryption

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

```bash
# 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.
