souleyez 2.22.0__py3-none-any.whl → 2.26.0__py3-none-any.whl

souleyez/__init__.py

@@ -1 +1 @@
-__version__ = '2.22.0'
+__version__ = '2.26.0'

souleyez/assets/__init__.py

@@ -0,0 +1 @@
+# SoulEyez assets package

souleyez/core/msf_sync_manager.py

@@ -29,15 +29,25 @@ logger = logging.getLogger(__name__)
 
 def get_msf_database_config() -> Optional[Dict[str, Any]]:
     """
-    Get MSF database configuration from ~/.msf4/database.yml
+    Get MSF database configuration from ~/.msf4/database.yml or system-wide config.
+
+    Checks user config first, then falls back to system-wide config (Kali Linux).
 
     Returns:
         Dictionary with database config or None if not found/parseable
     """
-    db_yml_path = Path.home() / ".msf4" / "database.yml"
-
-    if not db_yml_path.exists():
-        logger.debug(f"MSF database.yml not found at {db_yml_path}")
+    # Check user config first, then system-wide config (Kali uses system-wide)
+    user_db_path = Path.home() / ".msf4" / "database.yml"
+    system_db_path = Path('/usr/share/metasploit-framework/config/database.yml')
+
+    db_yml_path = None
+    if user_db_path.exists():
+        db_yml_path = user_db_path
+    elif system_db_path.exists():
+        db_yml_path = system_db_path
+
+    if not db_yml_path:
+        logger.debug("MSF database.yml not found in user or system config")
         return None
 
     try:

souleyez/core/tool_chaining.py

@@ -15,6 +15,17 @@ CATEGORY_CTF = "ctf"           # Lab/learning scenarios - vulnerable by design
 CATEGORY_ENTERPRISE = "enterprise"  # Real-world enterprise testing
 CATEGORY_GENERAL = "general"   # Standard recon that applies everywhere
 
+# Managed hosting platforms - skip CGI enumeration (pointless on these)
+# These are detected from server headers/banners and product names
+MANAGED_HOSTING_PLATFORMS = {
+    'squarespace', 'wix', 'shopify', 'webflow', 'weebly',
+    'wordpress.com', 'ghost.io', 'medium', 'tumblr', 'blogger',
+    'netlify', 'vercel', 'github.io', 'pages.dev', 'cloudflare',
+    'heroku', 'railway', 'render.com', 'fly.io',
+    'aws cloudfront', 'akamai', 'fastly', 'cloudflare',
+    'azure', 'google cloud', 'firebase',
+}
+
 # Category display icons
 CATEGORY_ICONS = {
     CATEGORY_CTF: "🎯",
@@ -140,6 +151,75 @@ def classify_os_device(os_string: str, services: list) -> dict:
     return {'os_family': 'unknown', 'device_type': 'unknown', 'vendor': None}
 
 
+def is_managed_hosting(services: List[Dict[str, Any]], http_fingerprint: Dict[str, Any] = None) -> bool:
+    """
+    Detect if target is a managed hosting platform.
+
+    These platforms don't have CGI directories, so tools like nikto
+    should skip CGI enumeration to avoid long, pointless scans.
+
+    Args:
+        services: List of service dicts from nmap parser
+        http_fingerprint: Optional fingerprint data from http_fingerprint plugin
+
+    Returns:
+        True if managed hosting detected, False otherwise
+    """
+    # Check fingerprint data first (most reliable, comes from actual HTTP headers)
+    if http_fingerprint:
+        managed = http_fingerprint.get('managed_hosting')
+        if managed:
+            return True
+
+    # Fall back to checking services data (less reliable, from nmap banners)
+    for service in services:
+        # Check product field
+        product = (service.get('product') or '').lower()
+        raw_version = (service.get('raw_version') or '').lower()
+        service_name = (service.get('service') or '').lower()
+
+        # Combine all fields for matching
+        combined = f"{product} {raw_version} {service_name}"
+
+        # Check against known managed hosting platforms
+        for platform in MANAGED_HOSTING_PLATFORMS:
+            if platform in combined:
+                return True
+
+    return False
+
+
+def get_managed_hosting_platform(services: List[Dict[str, Any]], http_fingerprint: Dict[str, Any] = None) -> Optional[str]:
+    """
+    Get the name of the managed hosting platform if detected.
+
+    Args:
+        services: List of service dicts from nmap parser
+        http_fingerprint: Optional fingerprint data from http_fingerprint plugin
+
+    Returns:
+        Platform name or None
+    """
+    # Check fingerprint data first
+    if http_fingerprint:
+        managed = http_fingerprint.get('managed_hosting')
+        if managed:
+            return managed
+
+    # Fall back to services check
+    for service in services:
+        product = (service.get('product') or '').lower()
+        raw_version = (service.get('raw_version') or '').lower()
+        service_name = (service.get('service') or '').lower()
+        combined = f"{product} {raw_version} {service_name}"
+
+        for platform in MANAGED_HOSTING_PLATFORMS:
+            if platform in combined:
+                return platform.title()
+
+    return None
+
+
 # Technology to Nuclei tags mapping
 # Maps detected products/technologies to relevant nuclei template tags
 TECH_TO_NUCLEI_TAGS = {
@@ -575,6 +655,25 @@ class ChainRule:
                 new_args.append(arg)
             args = new_args
 
+        # For Nikto: Skip CGI enumeration on managed hosting platforms
+        # This prevents long, pointless scans on Squarespace, Wix, etc.
+        if self.target_tool == 'nikto':
+            services = context.get('services', [])
+            http_fingerprint = context.get('http_fingerprint', {})
+            if is_managed_hosting(services, http_fingerprint):
+                # Add -C none to skip CGI dirs (pointless on managed hosting)
+                if '-C' not in str(args):
+                    args.extend(['-C', 'none'])
+                # Add -Tuning x6 to skip remote file inclusion tests
+                if '-Tuning' not in str(args):
+                    args.extend(['-Tuning', 'x6'])
+                # Log which platform was detected
+                platform = get_managed_hosting_platform(services, http_fingerprint)
+                if platform:
+                    from souleyez.log_config import get_logger
+                    logger = get_logger(__name__)
+                    logger.info(f"[FINGERPRINT] Managed hosting detected ({platform}) - nikto using optimized scan config")
+
         # For SQLMap with POST injections, add --data if we have POST data
         if self.target_tool == 'sqlmap' and post_data and '--data' not in str(args):
             # Insert --data after -u argument
@@ -642,32 +741,42 @@ class ToolChaining:
 
         # Web service discovered → run web scanners
         self.rules.extend([
-            # Modern vulnerability scanner (Nuclei) - PRIORITY
-            # Uses {nuclei_tags} placeholder to auto-detect tech and run relevant templates
+            # HTTP Fingerprinting - runs FIRST to detect WAF/CDN/managed hosting
+            # This enables smarter tool configuration for downstream scanners
             ChainRule(
                 trigger_tool='nmap',
                 trigger_condition='service:http',
+                target_tool='http_fingerprint',
+                priority=11,  # Highest priority - runs before all other web tools
+                args_template=[],
+                description='Web server detected, fingerprinting for WAF/CDN/platform detection'
+            ),
+            # Nikto triggered by http_fingerprint (uses fingerprint data for smart config)
+            ChainRule(
+                trigger_tool='http_fingerprint',
+                trigger_condition='has:services',
+                target_tool='nikto',
+                priority=8,
+                args_template=['-nointeractive', '-timeout', '10'],
+                description='Fingerprinting complete, scanning for server misconfigurations with Nikto'
+            ),
+            # Nuclei triggered by http_fingerprint
+            ChainRule(
+                trigger_tool='http_fingerprint',
+                trigger_condition='has:services',
                 target_tool='nuclei',
                 priority=9,
                 args_template=['-tags', '{nuclei_tags}', '-severity', 'critical,high', '-rate-limit', '50', '-c', '10', '-timeout', '10'],
-                description='Web server detected (HTTP/HTTPS), scanning with Nuclei'
+                description='Fingerprinting complete, scanning with Nuclei'
             ),
+            # Gobuster triggered by http_fingerprint
             ChainRule(
-                trigger_tool='nmap',
-                trigger_condition='service:http',
+                trigger_tool='http_fingerprint',
+                trigger_condition='has:services',
                 target_tool='gobuster',
                 priority=7,
                 args_template=['dir', '-u', 'http://{target}:{port}', '-w', 'data/wordlists/web_dirs_common.txt', '-x', 'js,json,php,asp,aspx,html,txt,bak,old,zip', '--no-error', '--timeout', '30s', '-t', '5', '--delay', '20ms'],
-                description='Web server detected (HTTP/HTTPS), discovering directories and files'
-            ),
-            # Nikto - web server vulnerability scanner (complements nuclei)
-            ChainRule(
-                trigger_tool='nmap',
-                trigger_condition='service:http',
-                target_tool='nikto',
-                priority=8,
-                args_template=['-nointeractive', '-timeout', '10'],
-                description='Web server detected, scanning for server misconfigurations with Nikto'
+                description='Fingerprinting complete, discovering directories and files'
             ),
             # Dalfox - XSS scanner triggered after gobuster finds pages
             ChainRule(
@@ -746,17 +855,8 @@ class ToolChaining:
                 args_template=['-a', '{target}'],
                 description='SMB service detected, enumerating shares and users (runs after CrackMapExec)'
             ),
-            # DISABLED: smbmap has upstream pickling bug with impacket (affects all versions)
-            # Use crackmapexec/netexec --shares instead (rule #10 above)
-            ChainRule(
-                trigger_tool='nmap',
-                trigger_condition='service:smb',
-                target_tool='smbmap',
-                priority=7,
-                enabled=False,  # Disabled due to impacket pickling bug
-                args_template=['-H', '{target}'],
-                description='SMB service detected, mapping shares (DISABLED - use netexec)'
-            ),
+            # NOTE: smbmap removed - has upstream impacket pickling bug on Python 3.13+
+            # Use crackmapexec/netexec --shares instead (enum4linux rule above)
         ])
 
         # Active Directory attacks - smart chaining workflow

souleyez/detection/validator.py

@@ -156,8 +156,10 @@ class DetectionValidator:
         job_command = _reconstruct_command(job)
         # Use started_at or finished_at for execution time
         executed_at = job.get('started_at') or job.get('finished_at') or job.get('created_at')
-        # Job is successful if status is 'done'
-        success = job.get('status') == 'done'
+        # Job ran successfully if status is done, no_results, or warning
+        # (all of these sent network traffic that should be detectable by SIEM)
+        job_status = job.get('status', '')
+        success = job_status in ('done', 'no_results', 'warning')
 
         # Extract target IP from command (common patterns)
         target_ip = None

souleyez/docs/README.md

@@ -1,7 +1,7 @@
 # SoulEyez Documentation
 
-**Version:** 2.22.0
-**Last Updated:** January 6, 2026
+**Version:** 2.26.0
+**Last Updated:** January 8, 2026
 **Organization:** CyberSoul Security
 
 Welcome to the SoulEyez documentation! This documentation covers architecture, development, user guides, and operational information for the SoulEyez penetration testing platform.

souleyez/docs/user-guide/installation.md

@@ -22,6 +22,17 @@ This guide walks you through installing souleyez on your system. The process tak
 - **RAM Usage**: Running multiple heavy tools (Metasploit, SQLMap, Hashcat) simultaneously requires additional RAM
 - **Disk I/O**: SSD recommended for database operations and log processing
 
+> **🐉 Kali Linux Recommended**
+>
+> SoulEyez performs significantly better on **Kali Linux** than other distributions:
+> - All pentesting tools pre-installed and optimized
+> - Metasploit database and RPC already configured
+> - Security-focused kernel and networking stack
+> - No dependency hunting or version conflicts
+> - Wordlists, databases, and tool configs ready to go
+>
+> While Ubuntu and other Debian-based distros are supported, you may experience slower setup times and occasional tool compatibility issues.
+
 ### Software Requirements
 
 - **Operating System**: Linux (Kali Linux recommended, any Debian-based distro supported)
@@ -40,12 +51,14 @@ pipx is the Python community's recommended way to install CLI applications. It h
 # One-time setup
 sudo apt install pipx
 pipx ensurepath
-source ~/.bashrc
+source ~/.bashrc    # Kali Linux: use 'source ~/.zshrc' instead
 
 # Install SoulEyez
 pipx install souleyez
 ```
 
+> **Kali Linux users:** Kali uses zsh by default. Use `source ~/.zshrc` instead of `source ~/.bashrc`
+
 On first run, SoulEyez will prompt you to install pentesting tools (nmap, sqlmap, gobuster, etc.).
 
 ```bash

souleyez/engine/background.py

@@ -1039,7 +1039,8 @@ def _is_true_error_exit_code(rc: int, tool: str) -> bool:
     # Tools that use non-zero exit codes for non-error conditions
     # Parser will determine the actual status based on output
     # msf_exploit returns 1 when no session opened (exploit ran but target not vulnerable)
-    tools_with_nonzero_success = ['gobuster', 'hydra', 'medusa', 'msf_exploit']
+    # nikto returns non-zero when it finds vulnerabilities (not an error!)
+    tools_with_nonzero_success = ['gobuster', 'hydra', 'medusa', 'msf_exploit', 'nikto']
 
     if tool.lower() in tools_with_nonzero_success:
         # Let parser determine status
@@ -1433,6 +1434,21 @@ def _detect_and_recover_stale_jobs() -> int:
                                 "status": status,
                                 "parse_result": parse_result
                             })
+
+                            # Mark for auto-chaining if conditions are met
+                            try:
+                                from souleyez.core.tool_chaining import ToolChaining
+                                chaining = ToolChaining()
+                                if chaining.is_enabled() and is_chainable(status):
+                                    _update_job(jid, chainable=True)
+                                    _append_worker_log(f"job {jid} stale recovery marked as chainable")
+                                    logger.info("Stale job marked as chainable", extra={
+                                        "job_id": jid,
+                                        "tool": tool,
+                                        "status": status
+                                    })
+                            except Exception as chain_err:
+                                _append_worker_log(f"job {jid} stale recovery chainable error: {chain_err}")
                 except Exception as parse_err:
                     _append_worker_log(f"job {jid} stale recovery parse exception: {parse_err}")
 

souleyez/engine/result_handler.py

@@ -108,6 +108,8 @@ def handle_job_result(job: Dict[str, Any]) -> Optional[Dict[str, Any]]:
         parse_result = parse_nikto_job(engagement_id, log_path, job)
     elif tool == 'dalfox':
         parse_result = parse_dalfox_job(engagement_id, log_path, job)
+    elif tool == 'http_fingerprint':
+        parse_result = parse_http_fingerprint_job(engagement_id, log_path, job)
 
     # NOTE: Auto-chaining is now handled in background.py after parsing completes
     # This avoids duplicate job creation and gives better control over timing
@@ -204,6 +206,8 @@ def reparse_job(job_id: int) -> Dict[str, Any]:
             parse_result = parse_nikto_job(engagement_id, log_path, job)
         elif tool == 'dalfox':
             parse_result = parse_dalfox_job(engagement_id, log_path, job)
+        elif tool == 'http_fingerprint':
+            parse_result = parse_http_fingerprint_job(engagement_id, log_path, job)
         else:
             return {'success': False, 'message': f'No parser available for tool: {tool}'}
 
@@ -3068,6 +3072,91 @@ def parse_nikto_job(engagement_id: int, log_path: str, job: Dict[str, Any]) -> D
         return {'error': str(e)}
 
 
+def parse_http_fingerprint_job(engagement_id: int, log_path: str, job: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Parse HTTP fingerprint results.
+
+    Returns fingerprint data for use in auto-chaining context.
+    This enables downstream tools (nikto, nuclei, etc.) to make smarter decisions
+    based on detected WAF, CDN, or managed hosting platform.
+    """
+    try:
+        from souleyez.parsers.http_fingerprint_parser import (
+            parse_http_fingerprint_output,
+            build_fingerprint_context,
+            get_tool_recommendations
+        )
+        from souleyez.storage.hosts import HostManager
+        from urllib.parse import urlparse
+
+        target = job.get('target', '')
+
+        # Read log file
+        with open(log_path, 'r', encoding='utf-8', errors='replace') as f:
+            output = f.read()
+
+        parsed = parse_http_fingerprint_output(output, target)
+
+        # Extract host from target URL
+        parsed_url = urlparse(target)
+        target_host = parsed_url.hostname or target
+
+        # Update host with fingerprint info if we have useful data
+        if target_host and (parsed.get('server') or parsed.get('managed_hosting')):
+            hm = HostManager()
+            host_data = {
+                'ip': target_host,
+                'status': 'up'
+            }
+            # Store server info in notes or a dedicated field
+            # For now, we just ensure the host exists
+            hm.add_or_update_host(engagement_id, host_data)
+
+        # Build fingerprint context for chaining
+        fingerprint_context = build_fingerprint_context(parsed)
+
+        # Get tool recommendations
+        recommendations = get_tool_recommendations(parsed)
+
+        # Determine status
+        if parsed.get('error'):
+            status = STATUS_ERROR
+        elif parsed.get('managed_hosting') or parsed.get('waf') or parsed.get('cdn'):
+            status = STATUS_DONE  # Found useful info
+        elif parsed.get('server'):
+            status = STATUS_DONE
+        else:
+            status = STATUS_NO_RESULTS
+
+        return {
+            'tool': 'http_fingerprint',
+            'status': status,
+            'target': target,
+            'target_host': target_host,
+            # Core fingerprint data
+            'server': parsed.get('server'),
+            'managed_hosting': parsed.get('managed_hosting'),
+            'waf': parsed.get('waf', []),
+            'cdn': parsed.get('cdn', []),
+            'technologies': parsed.get('technologies', []),
+            'status_code': parsed.get('status_code'),
+            # For auto-chaining context
+            'http_fingerprint': fingerprint_context.get('http_fingerprint', {}),
+            'recommendations': recommendations,
+            # Pass through for downstream chains
+            'services': [{
+                'ip': target_host,
+                'port': parsed_url.port or (443 if parsed_url.scheme == 'https' else 80),
+                'service_name': 'https' if parsed_url.scheme == 'https' else 'http',
+                'product': parsed.get('server', ''),
+            }],
+        }
+
+    except Exception as e:
+        logger.error(f"Error parsing http_fingerprint job: {e}")
+        return {'error': str(e)}
+
+
 def parse_dalfox_job(engagement_id: int, log_path: str, job: Dict[str, Any]) -> Dict[str, Any]:
     """Parse Dalfox XSS scanner results."""
     try:

souleyez/main.py

@@ -173,7 +173,7 @@ def _check_privileged_tools():
 
 
 @click.group()
-@click.version_option(version='2.22.0')
+@click.version_option(version='2.26.0')
 def cli():
     """SoulEyez - AI-Powered Pentesting Platform by CyberSoul Security"""
     from souleyez.log_config import init_logging
@@ -1388,19 +1388,24 @@ def _run_doctor(fix=False, verbose=False):
     path_dirs = os.environ.get('PATH', '').split(':')
     pipx_bin = str(Path.home() / '.local' / 'bin')
     go_bin = str(Path.home() / 'go' / 'bin')
+
+    # Detect shell config file (zsh for Kali, bash for others)
+    shell = os.environ.get('SHELL', '/bin/bash')
+    shell_rc = '~/.zshrc' if 'zsh' in shell else '~/.bashrc'
+
     if pipx_bin in path_dirs:
         if verbose:
             check_pass("PATH includes ~/.local/bin (pipx)")
     else:
         if Path(pipx_bin).exists() and any(Path(pipx_bin).iterdir()):
-            check_warn("~/.local/bin not in PATH", "Add to ~/.bashrc: export PATH=\"$HOME/.local/bin:$PATH\"")
+            check_warn("~/.local/bin not in PATH", f"Add to {shell_rc}: export PATH=\"$HOME/.local/bin:$PATH\"")
 
     if go_bin in path_dirs:
         if verbose:
             check_pass("PATH includes ~/go/bin")
     else:
         if Path(go_bin).exists() and any(Path(go_bin).iterdir()):
-            check_warn("~/go/bin not in PATH", "Add to ~/.bashrc: export PATH=\"$HOME/go/bin:$PATH\"")
+            check_warn("~/go/bin not in PATH", f"Add to {shell_rc}: export PATH=\"$HOME/go/bin:$PATH\"")
 
     # Check database is writable
     if db_path.exists():
@@ -1430,8 +1435,10 @@ def _run_doctor(fix=False, verbose=False):
     # Section 7: MSF Database (if msfconsole available)
     if shutil.which('msfconsole'):
         click.echo(click.style("Metasploit", bold=True))
+        # Check user config first, then system-wide config (Kali uses system-wide)
         msf_db = Path.home() / '.msf4' / 'database.yml'
-        if msf_db.exists():
+        system_msf_db = Path('/usr/share/metasploit-framework/config/database.yml')
+        if msf_db.exists() or system_msf_db.exists():
             check_pass("MSF database configured")
         else:
             check_fail("MSF database not initialized", "msfdb init")
@@ -1513,6 +1520,98 @@ def tutorial():
     run_tutorial()
 
 
+@cli.command('install-desktop')
+@click.option('--remove', is_flag=True, help='Remove the desktop shortcut')
+def install_desktop(remove):
+    """Install SoulEyez desktop shortcut in Applications menu.
+
+    Creates a .desktop file so SoulEyez appears in your
+    Applications > Security menu with its icon.
+    """
+    import shutil
+    from importlib import resources
+
+    applications_dir = Path.home() / '.local' / 'share' / 'applications'
+    icons_dir = Path.home() / '.local' / 'share' / 'icons'
+    desktop_file = applications_dir / 'souleyez.desktop'
+    icon_dest = icons_dir / 'souleyez.png'
+
+    if remove:
+        # Remove desktop shortcut
+        removed = False
+        if desktop_file.exists():
+            desktop_file.unlink()
+            click.echo(click.style("  Removed desktop shortcut", fg='green'))
+            removed = True
+        if icon_dest.exists():
+            icon_dest.unlink()
+            click.echo(click.style("  Removed icon", fg='green'))
+            removed = True
+        if removed:
+            click.echo(click.style("\nSoulEyez removed from Applications menu.", fg='cyan'))
+        else:
+            click.echo(click.style("No desktop shortcut found.", fg='yellow'))
+        return
+
+    click.echo(click.style("\nInstalling SoulEyez desktop shortcut...\n", fg='cyan', bold=True))
+
+    # Create directories
+    applications_dir.mkdir(parents=True, exist_ok=True)
+    icons_dir.mkdir(parents=True, exist_ok=True)
+
+    # Find and copy icon
+    try:
+        # Try importlib.resources first (Python 3.9+)
+        try:
+            from importlib.resources import files
+            icon_source = files('souleyez.assets').joinpath('souleyez-icon.png')
+            with open(icon_source, 'rb') as src:
+                icon_data = src.read()
+        except (ImportError, TypeError, FileNotFoundError):
+            # Fallback: find icon relative to this file
+            icon_source = Path(__file__).parent / 'assets' / 'souleyez-icon.png'
+            with open(icon_source, 'rb') as src:
+                icon_data = src.read()
+
+        with open(icon_dest, 'wb') as dst:
+            dst.write(icon_data)
+        click.echo(click.style("  Installed icon", fg='green'))
+    except Exception as e:
+        click.echo(click.style(f"  Warning: Could not copy icon: {e}", fg='yellow'))
+        icon_dest = "utilities-terminal"  # Fallback to system icon
+
+    # Create .desktop file
+    desktop_content = f"""[Desktop Entry]
+Name=SoulEyez
+Comment=AI-Powered Penetration Testing Platform
+Exec=souleyez interactive
+Icon={icon_dest}
+Terminal=true
+Type=Application
+Categories=Security;System;Network;
+Keywords=pentest;security;hacking;nmap;metasploit;
+"""
+
+    desktop_file.write_text(desktop_content)
+    click.echo(click.style("  Created desktop entry", fg='green'))
+
+    # Update desktop database (optional, may not be available)
+    try:
+        import subprocess
+        subprocess.run(['update-desktop-database', str(applications_dir)],
+                      capture_output=True, check=False)
+    except Exception:
+        pass  # Not critical if this fails
+
+    click.echo()
+    click.echo(click.style("SoulEyez added to Applications menu!", fg='green', bold=True))
+    click.echo()
+    click.echo("You can find it under:")
+    click.echo(click.style("  Applications > Security > SoulEyez", fg='cyan'))
+    click.echo()
+    click.echo("To remove: souleyez install-desktop --remove")
+
+
 def main():
     """Main entry point."""
     cli()