Metadata-Version: 2.4
Name: souleyez
Version: 2.2.2
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 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.2.2

### 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.2.2 | **Release Date**: December 2025 | **Maintainer**: CyberSoul Security
