SoulEyez — AI-Powered Penetration Testing Platform

CI codecov Python 3.9+ Code style: black Security: bandit

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. Unauthorized scanning or exploitation is illegal.

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, osint_recon, 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

SIEM Integration

  • 🛡️ SIEM Connectors — Connect to Wazuh, Splunk, and other SIEM platforms
  • ✓ Detection Validation — Verify if your attacks triggered SIEM alerts
  • 🔍 Vulnerability Management — View CVEs from SIEM vulnerability data
  • ⚖️ 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

Practice Lab (NEW in 4.1.0)

  • 🧪 Built-in vulnerable lab — souleyez lab spins up intentionally-vulnerable practice targets in Docker on an isolated network, so you always have something safe to point SoulEyez at (learning, demos, chain regression testing)
  • 🎯 Six turnkey targets — OWASP Juice Shop & DVWA (web), Metasploitable 2 & 3 (network hosts), Apache Struts2 S2-045 / CVE-2017-5638 (named CVE), and a vulnerable WordPress (CMS / WPScan)
  • 🧭 Guided setup — walks you through Docker install, daemon, and the docker-group step; offers to register QEMU emulation so x86 targets run on ARM
  • 📋 Beginner cheat sheets — a step-by-step SoulEyez attack walkthrough for each target (souleyez lab cheatsheet <target>), sourced from the tool's own attack-path tests

⚠️ These targets are vulnerable by design. They run on an isolated souleyez-lab bridge network — never expose them to an untrusted network.

FREE vs PRO

Feature FREE PRO
Core features (scans, findings, credentials) ✅ ✅
Report generation ✅ ✅
AI-powered suggestions & auto-chaining ❌ ✅
Metasploit integration & exploit suggestions ❌ ✅
SIEM integration & detection validation ❌ ✅
MITRE ATT&CK reports ❌ ✅

Quick Start

Step 1: Install Prerequisites

sudo apt install pipx    # Install pipx
pipx ensurepath          # Add pipx apps to your PATH
source ~/.bashrc         # Reload shell (Kali: use ~/.zshrc)

Step 2: Install SoulEyez

pipx install souleyez

Step 3: Launch SoulEyez

souleyez interactive

Step 4: First-Time Setup

On your first run, the setup wizard guides you through:

  1. Vault Password — Create a master password that encrypts sensitive data
  2. First Engagement — Set up your first project and select engagement type
  3. Tool Check — Detect and optionally install missing security tools
  4. AI Setup — Configure Ollama for AI features (optional)
  5. Tutorial — Option to run the interactive tutorial (recommended)

Step 5: You're Ready!

Once setup completes, you'll see the main menu.

System Requirements

Component Minimum Recommended
OS Ubuntu 22.04+ Kali Linux
Python 3.9+ 3.11+
RAM 4GB 8GB+
Disk 10GB 50GB+

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
macOS/Windows ❌ Not Supported Use Linux in a VM

Common Commands

Command What it does
souleyez interactive Launch the main interface
souleyez dashboard Real-time monitoring view
souleyez doctor Check if everything is set up correctly
souleyez setup Install/update pentesting tools
souleyez lab up Start the built-in vulnerable practice lab
souleyez lab status Show lab targets and their IPs/URLs
souleyez lab cheatsheet <target> Beginner attack guide for a lab target
souleyez --help Show all available commands

Security & Encryption

SoulEyez encrypts all stored credentials using Fernet (AES-128-CBC + HMAC-SHA256) with PBKDF2 key derivation (600k iterations).

  • Master password is never stored (cannot be recovered if lost)
  • Credentials encrypted at rest with industry-standard cryptography
  • Sensitive data is masked in the UI until explicitly revealed

See SECURITY.md for complete security guidelines.

Documentation

Troubleshooting

Problem Solution
"command not found: souleyez" Run pipx ensurepath then restart terminal
"Tool not found" errors Run souleyez setup to install missing tools
Forgot vault password Data is encrypted — start fresh with rm -rf ~/.souleyez
Something seems broken Run souleyez doctor to diagnose

Glossary

New to pentesting? Here are some common terms:

Term Meaning
Engagement A project or assessment — contains all data for one test
Target/Host A computer, server, or device you're testing
Finding A security issue or vulnerability you discovered
Credential Username/password combo found during testing

Support & Feedback

License

See LICENSE for details.

Version: 2.43.21 | Maintainer: CyberSoul Security

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (4.2.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for cybersoulsecurity from gravatar.com cybersoulsecurity

Credits

Author/Maintainer: CyberSoul Security

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.8

Provides Extra

dev

Tags

pentesting security hacking penetration-testing cybersecurity nmap metasploit

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

souleyez-4.1.1.tar.gz (2.1 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

souleyez-4.1.1-py3-none-any.whl (2.2 MB view details)

Uploaded Python 3

File details

Details for the file souleyez-4.1.1.tar.gz.

File metadata

  • Download URL: souleyez-4.1.1.tar.gz
  • Upload date:
  • Size: 2.1 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for souleyez-4.1.1.tar.gz
Algorithm Hash digest
SHA256 41622eeb5cf2f62836f61747f1f3dd9206e91b3747f197d7ceabd35adb6959be
MD5 6aa795a0c7bf021879c42cce716ce244
BLAKE2b-256 63341d8a1577ab56a836b635d846b0b1a397fd9e0c08f967cb221ea3e329bd42

See more details on using hashes here.

Provenance

The following attestation bundles were made for souleyez-4.1.1.tar.gz:

Publisher: python-ci.yml on cyber-soul-security/SoulEyez

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file souleyez-4.1.1-py3-none-any.whl.

File metadata

  • Download URL: souleyez-4.1.1-py3-none-any.whl
  • Upload date:
  • Size: 2.2 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for souleyez-4.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 920a090a050b9aebcf29f3e7de397b47e5033bc8cc398267708e3fabc929e44f
MD5 096e29735793129a38c132b25e3d0c07
BLAKE2b-256 8bc72ce30545ca1b2a3b9a4c783560343d1e82ea5164b927c44ecd203299ec7d

See more details on using hashes here.

Provenance

The following attestation bundles were made for souleyez-4.1.1-py3-none-any.whl:

Publisher: python-ci.yml on cyber-soul-security/SoulEyez

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

4.2.2

4.2.1

4.2.0

This release

4.1.1

4.1.0

4.0.5

4.0.4

4.0.3

4.0.2

4.0.1

4.0.0

4.0.0a3 pre-release

4.0.0a2 pre-release

3.0.91

3.0.90

3.0.89

3.0.88

3.0.87

3.0.86

3.0.85

3.0.84

3.0.83

3.0.82

3.0.81

3.0.80

3.0.79

3.0.78

3.0.77

3.0.76

3.0.75

3.0.74

3.0.73

3.0.72

3.0.71

3.0.69

3.0.68

3.0.67

3.0.66

3.0.65

3.0.63

3.0.62

3.0.61

3.0.60

3.0.59

3.0.58

3.0.57

3.0.56

3.0.55

3.0.54

3.0.53

3.0.52

3.0.51

3.0.49

3.0.48

3.0.47

3.0.46

3.0.45

3.0.43

3.0.42

3.0.41

3.0.40

3.0.39

3.0.38

3.0.37

3.0.36

3.0.35

3.0.34

3.0.33

3.0.32

3.0.31

3.0.30

3.0.28

3.0.27

3.0.25

3.0.24

3.0.23

3.0.22

3.0.21

3.0.20

3.0.19

3.0.16

3.0.15

3.0.14

3.0.13

3.0.12

3.0.11

3.0.10

3.0.9

3.0.8

3.0.7

3.0.6

3.0.5

3.0.4

3.0.3

3.0.2

3.0.1

3.0.0

2.43.34

2.43.32

2.43.29

2.43.28

2.43.27

2.43.26

2.43.25

2.43.24

2.43.23

2.43.22

2.43.21

2.43.20

2.43.19

2.43.18

2.43.17

2.43.16

2.43.15

2.43.14

2.43.13

2.43.12

2.43.11

2.43.10

2.43.9

2.43.8

2.43.7

2.43.6

2.43.5

2.43.4

2.43.3

2.43.2

2.43.1

2.43.0

2.41.1

2.40.0

2.39.0

2.38.0

2.37.0

2.36.0

2.35.0

2.32.0

2.31.0

2.30.0

2.29.0

2.28.0

2.27.1

2.27.0

2.26.0

2.25.0

2.24.0

2.23.0

2.22.0

2.21.0

2.20.0

2.19.0

2.18.0

2.17.0

2.16.0

2.15.0

2.14.0

2.13.0

2.12.0

2.11.0

2.10.1

2.10.0

2.9.0

2.8.0

2.7.0

2.6.0

2.5.0

2.4.0

2.3.0

2.2.13

2.2.12

2.2.11

2.2.10

2.2.9

2.2.8

2.2.7

2.2.6

2.2.5

2.2.4

2.2.3

2.2.2

2.2.1

2.2.0

2.1.33

2.1.32

2.1.31

2.1.30

2.1.29

2.1.28

2.1.27

2.1.26

2.1.25

2.1.24

2.1.23

2.1.22

2.1.21

2.1.20

2.1.19

2.1.18

2.1.17

2.1.16

2.1.14

2.1.13

2.1.12

2.1.11

2.1.9

2.1.8

2.1.7

2.1.6

2.1.5

2.1.4

2.1.3

2.1.2

2.1.1

2.1.0

2.0.33

2.0.32

2.0.31

2.0.30

2.0.29

2.0.28

2.0.27

2.0.25

2.0.24

2.0.23

2.0.21

2.0.20

2.0.19

2.0.18

2.0.17

2.0.16

2.0.15

2.0.14

2.0.13

2.0.12

2.0.11

2.0.10

2.0.9

2.0.8

2.0.7

2.0.6

2.0.5

2.0.4

2.0.3

2.0.2

2.0.1

2.0.0

1.4.6

1.4.5

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page