# SoulEyez Beta Program

Welcome to the SoulEyez beta! Thank you for helping us test and improve this penetration testing management platform.

---

## What is SoulEyez?

**SoulEyez is your penetration testing command center.** Instead of juggling dozens of terminal windows and text files, SoulEyez gives you one organized place to:

- **Run security scans** - Execute tools like Nmap, Gobuster, SQLMap with simple commands
- **Auto-discover next steps** - When one scan finds something interesting, SoulEyez automatically suggests (or runs) the next logical tool
- **Stay organized** - Keep all your targets, findings, and credentials in one searchable database
- **Generate reports** - Export professional reports when you're done

### Who is this for?

- **Security professionals** conducting authorized penetration tests
- **CTF players** who want better organization during competitions
- **Students** learning penetration testing methodology

> ⚠️ **Important**: Only use SoulEyez on systems you have explicit authorization to test.

## Version: 2.0.33

### What's Included

| Feature | FREE Tier | PRO Tier |
|---------|-----------|----------|
| Run security scans | ✅ | ✅ |
| Organize targets & findings | ✅ | ✅ |
| Encrypted credential storage | ✅ | ✅ |
| 20+ integrated tools | ✅ | ✅ |
| Report generation | ✅ | ✅ |
| AI-powered suggestions | ❌ | ✅ |
| Automatic tool chaining | ❌ | ✅ |
| Metasploit integration | ❌ | ✅ |

### System Requirements

- **Operating System**: Kali Linux or Ubuntu 22.04+ (Windows users: use WSL)
- **Python**: 3.8 or newer
- **Storage**: ~500MB for SoulEyez + tools

### Known Issues

- Very large scan outputs (>10MB) may slow the interface
- Some edge cases in tool output parsing

## Quick Start (Step-by-Step)

### Step 1: Install Prerequisites

First, we need `pipx` - a tool that safely installs Python CLI apps:

```bash
sudo apt install pipx    # Install pipx
pipx ensurepath          # Add pipx apps to your PATH
source ~/.bashrc         # Reload your shell (or close and reopen terminal)
```

> 💡 **What's pipx?** It's like `apt` but for Python command-line tools. It keeps each tool isolated so they don't conflict with each other.

### Step 2: Install SoulEyez

```bash
pipx install souleyez
```

This downloads SoulEyez and all its dependencies. Takes 1-2 minutes.

### Step 3: Launch SoulEyez

```bash
souleyez dashboard
```

### Step 4: First-Time Setup Wizard

On your first run, SoulEyez guides you through setup:

1. **Tool Installation** - Detects missing security tools (nmap, sqlmap, etc.) and offers to install them
2. **Vault Password** - You'll create a master password that encrypts sensitive data
3. **Admin Account** - Create your login credentials
4. **First Engagement** - Set up your first project (like "Home Lab Test" or "CTF Challenge")

> 💡 **What's an engagement?** Think of it as a project folder. Everything you discover during a test (hosts, services, credentials) is stored in that engagement.

### Step 5: You're Ready!

Once setup completes, you'll see the main menu. Navigate using the numbered options.

**Recommended: Run the built-in tutorial!**

Go to: **Settings & Security** → **[t] Tutorial**

The interactive tutorial walks you through:
1. Creating your first engagement
2. Running a basic reconnaissance scan
3. Viewing and understanding results
4. Using the real-time dashboard
5. Next steps and tips

---

## Common Commands

Here are the commands you'll use most often:

| Command | What it does |
|---------|--------------|
| `souleyez dashboard` | Launch the main interface |
| `souleyez doctor` | Check if everything is set up correctly |
| `souleyez setup` | Install/update pentesting tools |
| `souleyez --help` | Show all available commands |
| `souleyez <command> --help` | Get help for a specific command |

### Quick Troubleshooting

| Problem | Solution |
|---------|----------|
| "command not found: souleyez" | Run `pipx ensurepath` then restart your terminal |
| "Tool not found" errors | Run `souleyez setup` to install missing tools |
| Forgot your password | Data is encrypted - you'll need to start fresh with `rm -rf ~/.souleyez` |
| Something seems broken | Run `souleyez doctor` to diagnose the issue |

---

## Reporting Issues & Feedback

### Email (Preferred for Beta)
**cysoul.secit@gmail.com**

When reporting issues, please include:
- SoulEyez version (`souleyez --version`)
- Operating system and version
- Steps to reproduce
- Error messages (screenshots or copy/paste)
- Expected vs actual behavior

### Bug Report Template
```
**Description:**
[Brief description of the issue]

**Steps to Reproduce:**
1.
2.
3.

**Expected Behavior:**
[What should happen]

**Actual Behavior:**
[What actually happens]

**Environment:**
- OS:
- Python:
- SoulEyez version:

**Screenshots/Logs:**
[If applicable]
```

### Feature Requests
We welcome feature suggestions! Please prefix your issue title with `[Feature Request]`.

## Security Vulnerabilities

For security-related issues, please do NOT open a public GitHub issue.

Contact: cysoul.secit@gmail.com

Or see [SECURITY.md](SECURITY.md) for our security policy.

## Beta Feedback Survey

Help us improve SoulEyez by completing our quick feedback survey:

**[Take the Beta Feedback Survey](https://docs.google.com/forms/d/e/1FAIpQLSfylyvCor681VLeP7qGgFRDHCyzRDCFhiyjE6IqLbQDUB6-Jg/viewform?usp=send_form)**

## Beta Testing Guidelines

### What We Need Tested
- [ ] Full workflow: Create engagement → Add hosts → Run scans → Record findings → Generate report
- [ ] Credential encryption/decryption cycle
- [ ] Multi-user collaboration features
- [ ] Tool parsers (especially edge cases)
- [ ] Auto-chaining behavior
- [ ] Report generation quality
- [ ] UI responsiveness and navigation

### What to Avoid
- Don't test on production networks without authorization
- Don't store real client data in the beta (use test data)
- Don't share your vault password

## Support

- **Email**: cysoul.secit@gmail.com
- **Built-in Help**: Run `souleyez --help` or `souleyez <command> --help`
- **Diagnostics**: Run `souleyez doctor` to check your setup

---

## Glossary (New to Pentesting?)

| Term | Meaning |
|------|---------|
| **Engagement** | A project or assessment - contains all data for one test |
| **Target/Host** | A computer, server, or device you're testing |
| **Service** | A program running on a port (like a web server on port 80) |
| **Finding** | A security issue or vulnerability you discovered |
| **Credential** | Username/password combo found during testing |
| **Port** | A numbered "door" on a computer where services listen (e.g., 22=SSH, 80=HTTP) |
| **Nmap** | Network scanner - finds open ports and services |
| **Gobuster** | Directory scanner - finds hidden web pages |
| **SQLMap** | Automatically tests for SQL injection vulnerabilities |
| **Metasploit** | Framework for running exploits (PRO feature) |

---

## Thank You!

Your feedback is invaluable in making SoulEyez better. Every bug report, feature suggestion, and piece of feedback helps us build a tool that truly serves the security community.

Happy hacking! 🛡️

---

**Version**: 2.0.33 | **Release Date**: December 2025 | **Maintainer**: CyberSoul Security
