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.2.0.tar.gz (2.2 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.2.0-py3-none-any.whl (2.2 MB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for souleyez-4.2.0.tar.gz
Algorithm Hash digest
SHA256 c2c6e06c1f9e85b9c8cd5ba31e107dc0809191e2e30949572c610e5aaadc5cfd
MD5 b099e79fada8b9c349d8e9e139ca05c1
BLAKE2b-256 312ac8a0fdd38b513e8be3ae9d53c0a4d43768eb13016ce67aef589f8cad83b9

See more details on using hashes here.

Provenance

The following attestation bundles were made for souleyez-4.2.0.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.2.0-py3-none-any.whl.

File metadata

  • Download URL: souleyez-4.2.0-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.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 739a4c340f7578e1c41e97d46fbbad204553fd98e10c498bb54926e942378a68
MD5 41e303a859018981721d8b0b8b8c1b5b
BLAKE2b-256 f13697cb7b6ea57ccebc8f87335b928df9b901de916ecdc2481d1b18da44b3eb

See more details on using hashes here.

Provenance

The following attestation bundles were made for souleyez-4.2.0-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

This release

4.2.0

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