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