souleyez 2.43.34__py3-none-any.whl → 3.0.7__py3-none-any.whl

souleyez/core/version_utils.py

@@ -5,6 +5,7 @@ souleyez.core.version_utils
 Semantic version parsing and comparison for version-aware tool chaining.
 Supports conditions like: version:nginx:<1.19, version:apache:>=2.4.49,<=2.4.50
 """
+
 import re
 from dataclasses import dataclass
 from enum import Enum

souleyez/core/vuln_correlation.py

@@ -8,9 +8,10 @@ Analyzes findings from multiple tools to:
 3. Prioritize findings based on correlation
 4. Suggest exploit paths
 """
-from typing import List, Dict, Any, Optional
-from dataclasses import dataclass, field
+
 import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
 
 
 @dataclass

souleyez/core/web_utils.py

@@ -4,10 +4,11 @@ Web utility functions for SoulEyez.
 Includes HTTP redirect detection and other web-related helpers.
 """
 
-import requests
 from typing import Dict, Optional
 from urllib.parse import urlparse
 
+import requests
+
 
 def check_http_redirect(ip: str, port: int = 80, timeout: int = 3) -> Dict[str, any]:
     """

souleyez/detection/__init__.py

@@ -1,7 +1,7 @@
 # SoulEyez Detection Validation
 # Correlates attacks with SIEM detections
 
-from .validator import DetectionValidator
 from .attack_signatures import ATTACK_SIGNATURES
+from .validator import DetectionValidator
 
 __all__ = ["DetectionValidator", "ATTACK_SIGNATURES"]

souleyez/detection/attack_signatures.py

@@ -5,7 +5,7 @@ Maps SoulEyez tool names to expected Wazuh detection rules and search patterns.
 Used for correlating attacks with SIEM alerts.
 """
 
-from typing import Dict, Any, List
+from typing import Any, Dict, List
 
 # Detection window in seconds after attack completes
 DEFAULT_DETECTION_WINDOW = 300  # 5 minutes

souleyez/detection/mitre_mappings.py

@@ -5,9 +5,8 @@ Maps SoulEyez attack tools to MITRE ATT&CK techniques and tactics.
 Used for generating detection coverage reports with ATT&CK heatmaps.
 """
 
-from typing import Dict, List, Any, Optional
 from dataclasses import dataclass, field
-
+from typing import Any, Dict, List, Optional
 
 # MITRE ATT&CK Tactics (Enterprise Matrix)
 # Reference: https://attack.mitre.org/tactics/enterprise/

souleyez/detection/validator.py

@@ -9,13 +9,14 @@ Supports multiple SIEM platforms: Wazuh, Splunk, Elastic, Sentinel.
 
 import json
 import os
+from dataclasses import asdict, dataclass, field
 from datetime import datetime, timedelta
-from dataclasses import dataclass, field, asdict
-from typing import List, Dict, Any, Optional
+from typing import Any, Dict, List, Optional
 
+from souleyez.integrations.siem import SIEMClient, SIEMFactory
 from souleyez.storage.database import get_db
-from souleyez.integrations.siem import SIEMFactory, SIEMClient
-from .attack_signatures import get_signature, DEFAULT_DETECTION_WINDOW
+
+from .attack_signatures import DEFAULT_DETECTION_WINDOW, get_signature
 
 # Job queue file location (same as background.py)
 DATA_DIR = os.path.join(os.path.expanduser("~"), ".souleyez", "data")

souleyez/devtools.py

@@ -9,11 +9,13 @@ Command: souleyez dev repair
 - Verifies installed version and import path
 - Prints helpful guidance (no destructive data ops)
 """
+
 from __future__ import annotations
+
 import os
-import sys
-import subprocess
 import shutil
+import subprocess
+import sys
 from pathlib import Path
 
 CSI = "\033["

souleyez/docs/README.md

@@ -1,7 +1,7 @@
 # SoulEyez Documentation
 
-**Version:** 2.43.34
-**Last Updated:** January 26, 2026
+**Version:** 3.0.7
+**Last Updated:** January 31, 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/engine/background.py

@@ -73,6 +73,10 @@ TRANSIENT_ERROR_PATTERNS = [
     "Resource temporarily unavailable",
     "SMBTimeout",
     "timed out while waiting",
+    # Impacket-specific timeout patterns
+    "] timed out",  # Matches: [Errno Connection error (IP:port)] timed out
+    "RemoteOperations failed",  # Impacket remote operation failures
+    "Errno Connection error",  # Generic Impacket connection errors
 ]
 
 _lock = threading.RLock()  # Reentrant lock allows nested acquisition by same thread
@@ -88,6 +92,40 @@ def _is_transient_error(log_content: str) -> bool:
     return False
 
 
+def _is_netexec_flaky_empty(log_content: str, job: dict) -> bool:
+    """
+    Check if netexec/crackmapexec produced no output (flaky ARM behavior).
+
+    On ARM, netexec is ~20% flaky - it exits 0 but sometimes produces
+    zero output. This detects ONLY that case.
+
+    DOES NOT retry when:
+    - Access denied (has "[-]" error output)
+    - Connected but no shares (legitimate result)
+    - Any netexec output exists
+    """
+    tool = job.get("tool", "").lower()
+    args = job.get("args", [])
+
+    if tool not in ("crackmapexec", "nxc", "netexec"):
+        return False
+
+    args_str = " ".join(args).lower() if args else ""
+    if "--shares" not in args_str and "smb" not in args_str:
+        return False
+
+    lower = log_content.lower()
+
+    # If we got ANY netexec output, it's a real response - don't retry
+    # This includes error output like "[-]" which indicates access denied
+    has_any_output = any(
+        x in lower for x in ["smb", "[*]", "[+]", "[-]", "445", "signing"]
+    )
+
+    # Only retry if truly zero output (ARM flakiness)
+    return not has_any_output
+
+
 class _CrossProcessLock:
     """
     Cross-process file lock using fcntl.flock().
@@ -1516,6 +1554,78 @@ def _is_stdbuf_available() -> bool:
     return _stdbuf_available
 
 
+def _is_python_tool(cmd: List[str]) -> bool:
+    """
+    Check if a command is a Python-based tool.
+
+    stdbuf doesn't work well with Python scripts because Python manages its own
+    buffering internally. On some systems (especially ARM), stdbuf can prevent
+    Python tools from producing any output at all.
+
+    Args:
+        cmd: Command array to check
+
+    Returns:
+        True if the command is a Python tool that should skip stdbuf
+    """
+    if not cmd:
+        return False
+
+    executable = cmd[0]
+
+    # Direct Python invocation
+    if executable in ("python", "python3") or executable.startswith("python"):
+        return True
+
+    # .py extension
+    if executable.endswith(".py"):
+        return True
+
+    # Known Python tools that don't work with stdbuf
+    # These are tools installed via pip/pipx that are Python scripts
+    python_tools = {
+        "netexec",
+        "nxc",
+        "crackmapexec",
+        "cme",
+        "smbmap",
+        "impacket-GetNPUsers",
+        "impacket-GetUserSPNs",
+        "impacket-secretsdump",
+        "impacket-psexec",
+        "impacket-smbclient",
+        "impacket-wmiexec",
+        "impacket-dcomexec",
+        "impacket-atexec",
+        "GetNPUsers.py",
+        "GetUserSPNs.py",
+        "secretsdump.py",
+        "psexec.py",
+        "smbclient.py",
+        "certipy",
+        "bloodhound-python",
+        "ldapdomaindump",
+    }
+
+    # Check base name (handle full paths)
+    base_name = os.path.basename(executable)
+    if base_name in python_tools:
+        return True
+
+    # Check shebang for Python interpreter
+    exe_path = shutil.which(executable)
+    if exe_path:
+        try:
+            with open(exe_path, "rb") as f:
+                first_bytes = f.read(100)
+                if first_bytes.startswith(b"#!") and b"python" in first_bytes:
+                    return True
+        except (IOError, OSError):
+            pass
+
+    return False
+
+
 def _wrap_cmd_for_line_buffering(cmd: List[str]) -> List[str]:
     """
     Wrap a command with stdbuf for line-buffered output when available.
@@ -1524,6 +1634,9 @@ def _wrap_cmd_for_line_buffering(cmd: List[str]) -> List[str]:
     improving real-time log monitoring and ensuring output is captured
     before process termination.
 
+    Note: Python tools are excluded because stdbuf interferes with Python's
+    internal buffering and can cause zero output on some systems (Ubuntu ARM).
+
     Args:
         cmd: Command to wrap
 
@@ -1533,6 +1646,10 @@ def _wrap_cmd_for_line_buffering(cmd: List[str]) -> List[str]:
     if not cmd:
         return cmd
 
+    # Skip stdbuf for Python tools - causes output capture failures on ARM
+    if _is_python_tool(cmd):
+        return cmd
+
     if _is_stdbuf_available():
         # stdbuf -oL = line-buffered stdout, -eL = line-buffered stderr
         return ["stdbuf", "-oL", "-eL"] + cmd
@@ -2064,21 +2181,30 @@ def run_job(jid: int) -> None:
         job = get_job(jid)
         retry_count = job.get("metadata", {}).get("retry_count", 0)
         if retry_count < MAX_RETRIES:
-            # Read log to check for transient errors
-            # Note: Check even when rc==0 because tools like nxc may exit 0 but log errors
+            # Read log to check for transient errors or flaky netexec
             log_path = job.get("log", "")
             if log_path and os.path.exists(log_path):
                 try:
                     with open(log_path, "r", encoding="utf-8", errors="replace") as f:
                         log_content = f.read()
-                    if _is_transient_error(log_content):
-                        # Transient error detected - auto-retry
+
+                    # Check for transient errors OR flaky netexec (connected but no shares)
+                    is_transient = _is_transient_error(log_content)
+                    is_netexec_flaky = _is_netexec_flaky_empty(log_content, job)
+                    retry_reason = None
+
+                    if is_transient:
+                        retry_reason = "transient error"
+                    elif is_netexec_flaky:
+                        retry_reason = "netexec connected but no shares"
+
+                    if retry_reason:
                         logger.info(
-                            "Transient error detected, auto-retrying job",
+                            f"Auto-retrying job: {retry_reason}",
                             extra={"job_id": jid, "retry_count": retry_count + 1},
                         )
                         _append_worker_log(
-                            f"job {jid}: transient error detected, auto-retry {retry_count + 1}/{MAX_RETRIES}"
+                            f"job {jid}: {retry_reason}, auto-retry {retry_count + 1}/{MAX_RETRIES}"
                         )
 
                         # Build new job metadata with incremented retry count
@@ -2095,7 +2221,7 @@ def run_job(jid: int) -> None:
                             engagement_id=job.get("engagement_id"),
                             metadata=new_metadata,
                             parent_id=job.get("metadata", {}).get("parent_id"),
-                            reason=f"Auto-retry {retry_count + 1}/{MAX_RETRIES} (transient error)",
+                            reason=f"Auto-retry {retry_count + 1}/{MAX_RETRIES} ({retry_reason})",
                             rule_id=job.get("metadata", {}).get("rule_id"),
                             skip_scope_check=True,  # Already validated on first run
                         )
@@ -2120,6 +2246,41 @@ def run_job(jid: int) -> None:
 
             # Re-fetch job to get updated data
             job = get_job(jid)
+
+            # Ensure log file is fully flushed to disk before parsing
+            # Some tools (especially Python-based like impacket) may have buffered output
+            log_path = job.get("log", "")
+            if log_path and os.path.exists(log_path):
+                # Wait for completion marker with retries
+                # Log files end with "Exit Code:" or "=== Completed"
+                max_retries = 5
+                retry_delay = 0.2  # 200ms between retries
+                log_complete = False
+
+                for attempt in range(max_retries):
+                    try:
+                        with open(
+                            log_path, "r", encoding="utf-8", errors="replace"
+                        ) as f:
+                            content = f.read()
+                            # Check for completion markers
+                            if "Exit Code:" in content or "=== Completed" in content:
+                                log_complete = True
+                                break
+                    except Exception:
+                        pass
+
+                    if attempt < max_retries - 1:
+                        time.sleep(retry_delay)
+
+                if not log_complete:
+                    # Last resort: force filesystem sync and proceed anyway
+                    try:
+                        with open(log_path, "a") as f:
+                            os.fsync(f.fileno())
+                    except Exception:
+                        pass
+
             parse_result = handle_job_result(job)
 
             # Handle parse failure cases

souleyez/engine/base.py

@@ -3,7 +3,8 @@
 Simple plugin base classes and type hints for souleyez.
 Plugins should implement ScannerPlugin.run(prepared) -> dict (ScanResult).
 """
-from typing import Dict, Any, Optional
+
+from typing import Any, Dict, Optional
 
 ScanResult = Dict[str, Any]
 

souleyez/engine/loader.py

@@ -2,10 +2,12 @@
 """
 Simple plugin loader for souleyez (L1).
 """
+
 from __future__ import annotations
-import pkgutil
+
 import importlib
-from typing import Dict, Any
+import pkgutil
+from typing import Any, Dict
 
 
 def _safe_import_module(fullname: str):

souleyez/engine/log_sanitizer.py

@@ -5,6 +5,7 @@ souleyez.engine.log_sanitizer - Sanitize sensitive data from logs
 Redacts credentials and sensitive information from job logs to prevent
 plaintext password exposure, while maintaining log readability.
 """
+
 import re
 from typing import Optional
 

souleyez/engine/manager.py

@@ -6,11 +6,13 @@ This manager contains a small built-in adapter for "nmap" that uses your existin
 souleyez.scanner.run_nmap function. Later plugins can be added by implementing
 ScannerPlugin in their own modules and registering them here.
 """
+
+import importlib
 import threading
 from typing import Optional
+
 from ..storage.db import init_db, insert_scan, update_scan
 from ..utils import timestamp_str
-import importlib
 
 # lazy import existing run_nmap (your project has souleyez/scanner.py)