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

souleyez/detection/validator.py

@@ -37,16 +37,16 @@ def _get_job_by_id(job_id: int) -> Optional[Dict[str, Any]]:
     """Get a single job by ID from the job queue."""
     jobs = _read_jobs_file()
     for job in jobs:
-        if job.get('id') == job_id:
+        if job.get("id") == job_id:
             return job
     return None
 
 
 def _reconstruct_command(job: Dict[str, Any]) -> str:
     """Reconstruct the command string from job data."""
-    tool = job.get('tool', '')
-    target = job.get('target', '')
-    args = job.get('args', [])
+    tool = job.get("tool", "")
+    target = job.get("target", "")
+    args = job.get("args", [])
 
     # Build command string
     parts = [tool]
@@ -55,12 +55,13 @@ def _reconstruct_command(job: Dict[str, Any]) -> str:
     if target and target not in args:
         parts.append(target)
 
-    return ' '.join(parts)
+    return " ".join(parts)
 
 
 @dataclass
 class DetectionResult:
     """Result of validating detection for a single job."""
+
     job_id: int
     status: str  # 'detected', 'not_detected', 'partial', 'offline', 'unknown'
     attack_type: str = ""  # Tool name (e.g., 'nmap', 'hydra')
@@ -75,6 +76,7 @@ class DetectionResult:
 @dataclass
 class EngagementDetectionSummary:
     """Summary of detection coverage for an engagement."""
+
     engagement_id: int
     total_attacks: int
     detected: int
@@ -139,36 +141,36 @@ class DetectionValidator:
         job = _get_job_by_id(job_id)
         if not job:
             return DetectionResult(
-                job_id=job_id,
-                status='unknown',
-                reason="Job not found in queue"
+                job_id=job_id, status="unknown", reason="Job not found in queue"
             )
 
         # Verify engagement matches
-        if job.get('engagement_id') != self.engagement_id:
+        if job.get("engagement_id") != self.engagement_id:
             return DetectionResult(
                 job_id=job_id,
-                status='unknown',
-                reason="Job belongs to different engagement"
+                status="unknown",
+                reason="Job belongs to different engagement",
             )
 
-        job_tool = job.get('tool') or 'unknown'
+        job_tool = job.get("tool") or "unknown"
         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')
+        executed_at = (
+            job.get("started_at") or job.get("finished_at") or job.get("created_at")
+        )
         # 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')
+        job_status = job.get("status", "")
+        success = job_status in ("done", "no_results", "warning")
 
         # Extract target IP from command (common patterns)
         target_ip = None
-        ip_pattern = r'\b(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})\b'
+        ip_pattern = r"\b(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})\b"
         ip_matches = re.findall(ip_pattern, job_command)
         if ip_matches:
             # Filter out common non-target IPs
             for ip in ip_matches:
-                if not ip.startswith('127.') and not ip.startswith('0.'):
+                if not ip.startswith("127.") and not ip.startswith("0."):
                     target_ip = ip
                     break
 
@@ -176,23 +178,23 @@ class DetectionValidator:
         if not success:
             return DetectionResult(
                 job_id=job_id,
-                status='unknown',
+                status="unknown",
                 attack_type=job_tool,
-                target_ip=target_ip or '',
-                reason=f"Job did not complete successfully"
+                target_ip=target_ip or "",
+                reason=f"Job did not complete successfully",
             )
 
         # Get attack signature
         signature = get_signature(job_tool)
 
         # Check if offline tool (no network detection expected)
-        if signature.get('offline'):
+        if signature.get("offline"):
             result = DetectionResult(
                 job_id=job_id,
-                status='offline',
+                status="offline",
                 attack_type=job_tool,
-                target_ip=target_ip or '',
-                reason=f"{job_tool} is an offline tool, no network detection expected"
+                target_ip=target_ip or "",
+                reason=f"{job_tool} is an offline tool, no network detection expected",
             )
             self._save_result(result, job_id)
             return result
@@ -202,28 +204,32 @@ class DetectionValidator:
         if not client:
             return DetectionResult(
                 job_id=job_id,
-                status='unknown',
+                status="unknown",
                 attack_type=job_tool,
-                target_ip=target_ip or '',
-                reason="SIEM not configured for this engagement"
+                target_ip=target_ip or "",
+                reason="SIEM not configured for this engagement",
             )
 
         # Parse timestamp
         try:
             if isinstance(executed_at, str):
-                exec_time = datetime.fromisoformat(executed_at.replace('Z', '+00:00').replace(' ', 'T'))
+                exec_time = datetime.fromisoformat(
+                    executed_at.replace("Z", "+00:00").replace(" ", "T")
+                )
             else:
                 exec_time = executed_at or datetime.now()
         except Exception:
             exec_time = datetime.now() - timedelta(hours=1)
 
         # Query window: 5 minutes before execution to detection_window after
-        detection_window = signature.get('detection_window_seconds', DEFAULT_DETECTION_WINDOW)
+        detection_window = signature.get(
+            "detection_window_seconds", DEFAULT_DETECTION_WINDOW
+        )
         query_start = exec_time - timedelta(minutes=5)
         query_end = exec_time + timedelta(seconds=detection_window)
 
         # Get expected rule IDs (convert to strings for compatibility)
-        expected_rules = signature.get('wazuh_rules', [])
+        expected_rules = signature.get("wazuh_rules", [])
         rule_id_strings = [str(r) for r in expected_rules] if expected_rules else None
 
         # Query SIEM for alerts
@@ -233,25 +239,25 @@ class DetectionValidator:
                 end_time=query_end,
                 dest_ip=target_ip,  # Target IP is the destination
                 rule_ids=rule_id_strings,
-                limit=100
+                limit=100,
             )
         except Exception as e:
-            siem_type = client.siem_type if client else 'SIEM'
+            siem_type = client.siem_type if client else "SIEM"
             return DetectionResult(
                 job_id=job_id,
-                status='unknown',
-                reason=f"Error querying {siem_type}: {str(e)}"
+                status="unknown",
+                reason=f"Error querying {siem_type}: {str(e)}",
             )
 
         # Also search by patterns if no rule matches
-        if not alerts and signature.get('search_patterns'):
-            for pattern in signature['search_patterns'][:3]:  # Limit searches
+        if not alerts and signature.get("search_patterns"):
+            for pattern in signature["search_patterns"][:3]:  # Limit searches
                 try:
                     pattern_alerts = client.get_alerts(
                         start_time=query_start,
                         end_time=query_end,
                         search_text=pattern,
-                        limit=50
+                        limit=50,
                     )
                     alerts.extend(pattern_alerts)
                 except Exception:
@@ -261,51 +267,52 @@ class DetectionValidator:
         seen_ids = set()
         unique_alerts = []
         for alert in alerts:
-            alert_id = getattr(alert, 'id', None) or str(getattr(alert, 'timestamp', ''))
+            alert_id = getattr(alert, "id", None) or str(
+                getattr(alert, "timestamp", "")
+            )
             if alert_id not in seen_ids:
                 seen_ids.add(alert_id)
                 unique_alerts.append(alert)
 
         # Determine detection status
         if unique_alerts:
-            rule_ids = list(set(
-                getattr(a, 'rule_id', 'unknown')
-                for a in unique_alerts
-            ))
+            rule_ids = list(
+                set(getattr(a, "rule_id", "unknown") for a in unique_alerts)
+            )
             # Convert SIEMAlert dataclass objects to dicts for storage
             # Include all normalized fields (rule_id, rule_name, severity, etc.)
             alert_dicts = []
             for a in unique_alerts[:20]:
-                if hasattr(a, '__dataclass_fields__'):
+                if hasattr(a, "__dataclass_fields__"):
                     # Convert dataclass to dict
                     alert_dict = asdict(a)
                     # Convert datetime to ISO string for JSON serialization
-                    if isinstance(alert_dict.get('timestamp'), datetime):
-                        alert_dict['timestamp'] = alert_dict['timestamp'].isoformat()
+                    if isinstance(alert_dict.get("timestamp"), datetime):
+                        alert_dict["timestamp"] = alert_dict["timestamp"].isoformat()
                     alert_dicts.append(alert_dict)
                 elif isinstance(a, dict):
                     alert_dicts.append(a)
                 else:
                     # Fallback: try to extract raw_data or convert to dict
-                    alert_dicts.append(getattr(a, 'raw_data', {}) or {})
+                    alert_dicts.append(getattr(a, "raw_data", {}) or {})
             result = DetectionResult(
                 job_id=job_id,
-                status='detected',
+                status="detected",
                 attack_type=job_tool,
-                target_ip=target_ip or '',
+                target_ip=target_ip or "",
                 alerts_count=len(unique_alerts),
                 alerts=alert_dicts,
                 rule_ids=rule_ids,
-                reason=f"Found {len(unique_alerts)} related alert(s)"
+                reason=f"Found {len(unique_alerts)} related alert(s)",
             )
         else:
             result = DetectionResult(
                 job_id=job_id,
-                status='not_detected',
+                status="not_detected",
                 attack_type=job_tool,
-                target_ip=target_ip or '',
+                target_ip=target_ip or "",
                 alerts_count=0,
-                reason=f"No alerts found for {job_tool} attack on {target_ip}"
+                reason=f"No alerts found for {job_tool} attack on {target_ip}",
             )
 
         # Save result to database
@@ -322,21 +329,21 @@ class DetectionValidator:
             return
 
         # Extract target IP from command or use job target
-        target_ip = job.get('target')
+        target_ip = job.get("target")
         command = _reconstruct_command(job)
 
         # Try to extract more specific IP from command
-        ip_pattern = r'\b(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})\b'
+        ip_pattern = r"\b(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})\b"
         ip_matches = re.findall(ip_pattern, command)
         if ip_matches:
             for ip in ip_matches:
-                if not ip.startswith('127.') and not ip.startswith('0.'):
+                if not ip.startswith("127.") and not ip.startswith("0."):
                     target_ip = ip
                     break
 
         # Get timestamps
-        attack_start = job.get('started_at') or job.get('created_at')
-        attack_end = job.get('finished_at') or attack_start
+        attack_start = job.get("started_at") or job.get("created_at")
+        attack_end = job.get("finished_at") or attack_start
 
         db = get_db()
         conn = db.get_connection()
@@ -346,24 +353,27 @@ class DetectionValidator:
         cursor.execute("DELETE FROM detection_results WHERE job_id = ?", (job_id,))
 
         # Insert new result
-        cursor.execute("""
+        cursor.execute(
+            """
             INSERT INTO detection_results
             (job_id, engagement_id, attack_type, target_ip, attack_start, attack_end,
              detection_status, alerts_count, wazuh_alerts_json, rule_ids, checked_at)
             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        """, (
-            job_id,
-            self.engagement_id,
-            job.get('tool'),  # attack_type (tool)
-            target_ip,
-            attack_start,
-            attack_end,
-            result.status,
-            result.alerts_count,
-            json.dumps(result.alerts[:20]) if result.alerts else None,
-            ','.join(result.rule_ids) if result.rule_ids else None,
-            datetime.now().isoformat()
-        ))
+        """,
+            (
+                job_id,
+                self.engagement_id,
+                job.get("tool"),  # attack_type (tool)
+                target_ip,
+                attack_start,
+                attack_end,
+                result.status,
+                result.alerts_count,
+                json.dumps(result.alerts[:20]) if result.alerts else None,
+                ",".join(result.rule_ids) if result.rule_ids else None,
+                datetime.now().isoformat(),
+            ),
+        )
         conn.commit()
 
     def validate_engagement(self) -> EngagementDetectionSummary:
@@ -378,20 +388,21 @@ class DetectionValidator:
         # Get all completed jobs for this engagement from job queue
         all_jobs = _read_jobs_file()
         completed_jobs = [
-            job for job in all_jobs
-            if job.get('engagement_id') == self.engagement_id
-            and job.get('status') == 'done'
+            job
+            for job in all_jobs
+            if job.get("engagement_id") == self.engagement_id
+            and job.get("status") == "done"
             # Only include known attack tools (filter out echo, cat, etc.)
-            and job.get('tool', '').lower() in ATTACK_SIGNATURES
+            and job.get("tool", "").lower() in ATTACK_SIGNATURES
         ]
 
         # Sort by finished_at descending
         completed_jobs.sort(
-            key=lambda j: j.get('finished_at') or j.get('started_at') or '',
-            reverse=True
+            key=lambda j: j.get("finished_at") or j.get("started_at") or "",
+            reverse=True,
         )
 
-        job_ids = [job.get('id') for job in completed_jobs if job.get('id') is not None]
+        job_ids = [job.get("id") for job in completed_jobs if job.get("id") is not None]
 
         if not job_ids:
             return EngagementDetectionSummary(
@@ -402,7 +413,7 @@ class DetectionValidator:
                 partial=0,
                 offline=0,
                 unknown=0,
-                coverage_percent=0.0
+                coverage_percent=0.0,
             )
 
         # Validate each job
@@ -412,11 +423,11 @@ class DetectionValidator:
             results.append(result)
 
         # Calculate summary
-        detected = sum(1 for r in results if r.status == 'detected')
-        not_detected = sum(1 for r in results if r.status == 'not_detected')
-        partial = sum(1 for r in results if r.status == 'partial')
-        offline = sum(1 for r in results if r.status == 'offline')
-        unknown = sum(1 for r in results if r.status == 'unknown')
+        detected = sum(1 for r in results if r.status == "detected")
+        not_detected = sum(1 for r in results if r.status == "not_detected")
+        partial = sum(1 for r in results if r.status == "partial")
+        offline = sum(1 for r in results if r.status == "offline")
+        unknown = sum(1 for r in results if r.status == "unknown")
 
         # Calculate coverage (excluding offline and unknown)
         countable = detected + not_detected + partial
@@ -431,10 +442,10 @@ class DetectionValidator:
             offline=offline,
             unknown=unknown,
             coverage_percent=round(coverage, 1),
-            results=results
+            results=results,
         )
 
     def get_detection_gaps(self) -> List[DetectionResult]:
         """Get list of attacks that were NOT detected."""
         summary = self.validate_engagement()
-        return [r for r in summary.results if r.status == 'not_detected']
+        return [r for r in summary.results if r.status == "not_detected"]

souleyez/devtools.py

@@ -16,12 +16,12 @@ import subprocess
 import shutil
 from pathlib import Path
 
-CSI = '\033['
-RESET = CSI + '0m'
-BOLD = CSI + '1m'
-GREEN = CSI + '32m'
-RED = CSI + '31m'
-CYAN = CSI + '36m'
+CSI = "\033["
+RESET = CSI + "0m"
+BOLD = CSI + "1m"
+GREEN = CSI + "32m"
+RED = CSI + "31m"
+CYAN = CSI + "36m"
 
 
 def _ok(msg):
@@ -37,7 +37,9 @@ def _warn(msg):
 
 
 def _run(cmd):
-    return subprocess.run(cmd, text=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+    return subprocess.run(
+        cmd, text=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT
+    )
 
 
 def dev_repair():
@@ -53,13 +55,16 @@ def dev_repair():
     # 1) Sanity: are we in the repo root (setup.py present)?
     setup_py = project / "setup.py"
     if not setup_py.exists():
-        _warn("setup.py not found in current directory. Run from your project root (e.g., ~/apps/souleyez_app).")
+        _warn(
+            "setup.py not found in current directory. Run from your project root (e.g., ~/apps/souleyez_app)."
+        )
         return 2
     _ok("Project root looks good (setup.py found).")
 
     # 2) Check import path for souleyez
     try:
         import importlib.util
+
         spec = importlib.util.find_spec("souleyez")
         _info(f"import find_spec: {spec}")
     except Exception as e:
@@ -76,7 +81,12 @@ def dev_repair():
 
     # 5) Clean site-packages leftovers (dist-info + old copies)
     _info("Cleaning old site-packages metadata...")
-    site = Path(sys.prefix) / "lib" / f"python{sys.version_info.major}.{sys.version_info.minor}" / "site-packages"
+    site = (
+        Path(sys.prefix)
+        / "lib"
+        / f"python{sys.version_info.major}.{sys.version_info.minor}"
+        / "site-packages"
+    )
     for pat in ("souleyez-*.dist-info", "souleyez"):
         for p in site.glob(pat):
             try:
@@ -107,10 +117,13 @@ def dev_repair():
     # 9) Verify import location
     try:
         import souleyez
+
         _ok(f"'souleyez' imports from: {souleyez.__file__}")
     except Exception as e:
         _warn(f"Import failed after reinstall: {e}")
         return 1
 
-    _ok("Dev repair complete. If version still mismatches, ensure no stray pyproject.toml remains and venv is active.")
+    _ok(
+        "Dev repair complete. If version still mismatches, ensure no stray pyproject.toml remains and venv is active."
+    )
     return 0

souleyez/docs/README.md

@@ -1,7 +1,7 @@
 # SoulEyez Documentation
 
-**Version:** 2.43.29
-**Last Updated:** January 13, 2026
+**Version:** 2.43.34
+**Last Updated:** January 26, 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.
@@ -238,8 +238,8 @@ Legal and compliance documentation.
 
 ## 📞 Need Help?
 
-- **Issues**: https://github.com/cybersoul-security/souleyez/issues
-- **Discussions**: https://github.com/cybersoul-security/souleyez/discussions
+- **Issues**: https://github.com/cyber-soul-security/SoulEyez/issues
+- **Discussions**: https://github.com/cyber-soul-security/SoulEyez/discussions
 - **Security**: cysoul.secit@gmail.com
 - **General**: cysoul.secit@gmail.com
 

souleyez/docs/api-reference/cli-commands.md

@@ -292,7 +292,7 @@ souleyez jobs enqueue nmap 192.168.1.100 -a "-sS" -l "SYN Scan DC01"
 souleyez jobs enqueue nikto http://example.com -l "Web Vuln Scan"
 
 # Directory enumeration
-souleyez jobs enqueue gobuster http://example.com -a "dir -w /usr/share/wordlists/dirb/common.txt"
+souleyez jobs enqueue gobuster http://example.com -a "dir -w data/wordlists/web_dirs_common.txt"
 ```
 
 ---
@@ -801,7 +801,7 @@ souleyez dashboard
 ### Web Application Testing
 ```bash
 souleyez jobs enqueue nikto http://example.com -l "Nikto Scan"
-souleyez jobs enqueue gobuster http://example.com -a "dir -w /usr/share/wordlists/dirb/common.txt" -l "Dir Enum"
+souleyez jobs enqueue gobuster http://example.com -a "dir -w data/wordlists/web_dirs_common.txt" -l "Dir Enum"
 souleyez findings list
 ```