souleyez 2.27.0__py3-none-any.whl → 2.28.0__py3-none-any.whl

souleyez/engine/background.py

@@ -321,7 +321,7 @@ def _next_job_id(jobs: List[Dict[str, Any]]) -> int:
         return maxid + 1
 
 
-def enqueue_job(tool: str, target: str, args: List[str], label: str = "", engagement_id: int = None, metadata: Dict[str, Any] = None, parent_id: int = None, reason: str = None, rule_id: int = None) -> int:
+def enqueue_job(tool: str, target: str, args: List[str], label: str = "", engagement_id: int = None, metadata: Dict[str, Any] = None, parent_id: int = None, reason: str = None, rule_id: int = None, skip_scope_check: bool = False) -> int:
     with _lock:
         jobs = _read_jobs()
         jid = _next_job_id(jobs)
@@ -339,6 +339,43 @@ def enqueue_job(tool: str, target: str, args: List[str], label: str = "", engage
 
         # Merge parent_id, reason, and rule_id into metadata
         job_metadata = metadata or {}
+
+        # Scope validation - check if target is within engagement scope
+        if not skip_scope_check and engagement_id:
+            try:
+                from souleyez.security.scope_validator import ScopeValidator, ScopeViolationError
+                validator = ScopeValidator(engagement_id)
+                result = validator.validate_target(target)
+                enforcement = validator.get_enforcement_mode()
+
+                if not result.is_in_scope and validator.has_scope_defined():
+                    if enforcement == 'block':
+                        validator.log_validation(target, result, 'blocked', job_id=jid)
+                        raise ScopeViolationError(
+                            f"Target '{target}' is out of scope. {result.reason}"
+                        )
+                    elif enforcement == 'warn':
+                        validator.log_validation(target, result, 'warned', job_id=jid)
+                        if 'warnings' not in job_metadata:
+                            job_metadata['warnings'] = []
+                        job_metadata['warnings'].append(
+                            f"SCOPE WARNING: {target} may be out of scope. {result.reason}"
+                        )
+                        logger.warning("Out-of-scope target allowed (warn mode)", extra={
+                            "target": target,
+                            "engagement_id": engagement_id,
+                            "reason": result.reason
+                        })
+                else:
+                    validator.log_validation(target, result, 'allowed', job_id=jid)
+            except ScopeViolationError:
+                raise  # Re-raise scope violations
+            except Exception as e:
+                # Don't block jobs if scope validation fails unexpectedly
+                logger.warning("Scope validation error (allowing job)", extra={
+                    "target": target,
+                    "error": str(e)
+                })
         if parent_id is not None:
             job_metadata['parent_id'] = parent_id
         if reason:

souleyez/engine/result_handler.py

@@ -10,6 +10,95 @@ from .job_status import STATUS_DONE, STATUS_NO_RESULTS, STATUS_WARNING, STATUS_E
 logger = logging.getLogger(__name__)
 
 
+# Common error patterns that indicate tool failure (not "no results")
+TOOL_ERROR_PATTERNS = {
+    'common': [
+        'connection refused',
+        'connection timed out',
+        'no route to host',
+        'network is unreachable',
+        'name or service not known',
+        'temporary failure in name resolution',
+        'host is down',
+        'connection reset by peer',
+    ],
+    'nmap': [
+        'host seems down',
+        'note: host seems down',
+        'failed to resolve',
+    ],
+    'gobuster': [
+        'timeout occurred during the request',
+        'error on running gobuster',
+        'unable to connect',
+        'context deadline exceeded',
+    ],
+    'hydra': [
+        'can not connect',
+        'could not connect',
+        'error connecting',
+        'target does not support',
+    ],
+    'nikto': [
+        'error connecting to host',
+        'unable to connect',
+        'no web server found',
+    ],
+    'nuclei': [
+        'could not connect',
+        'context deadline exceeded',
+        'no address found',
+    ],
+    'ffuf': [
+        'error making request',
+        'context deadline exceeded',
+    ],
+    'sqlmap': [
+        'connection timed out',
+        'unable to connect',
+        'target url content is not stable',
+    ],
+    'enum4linux': [
+        'could not initialise',
+        'nt_status_connection_refused',
+        'nt_status_host_unreachable',
+        'nt_status_io_timeout',
+    ],
+    'smbmap': [
+        'could not connect',
+        'connection error',
+        'nt_status_connection_refused',
+    ],
+}
+
+
+def detect_tool_error(log_content: str, tool: str) -> Optional[str]:
+    """
+    Check log content for tool errors that indicate failure (not just "no results").
+
+    Args:
+        log_content: The log file content
+        tool: Tool name (lowercase)
+
+    Returns:
+        Error pattern found, or None if no error detected
+    """
+    log_lower = log_content.lower()
+
+    # Check common patterns
+    for pattern in TOOL_ERROR_PATTERNS['common']:
+        if pattern in log_lower:
+            return pattern
+
+    # Check tool-specific patterns
+    tool_patterns = TOOL_ERROR_PATTERNS.get(tool, [])
+    for pattern in tool_patterns:
+        if pattern in log_lower:
+            return pattern
+
+    return None
+
+
 def handle_job_result(job: Dict[str, Any]) -> Optional[Dict[str, Any]]:
     """
     Process completed job and parse results into database.
@@ -527,9 +616,16 @@ def parse_nmap_job(engagement_id: int, log_path: str, job: Dict[str, Any]) -> Di
                         'version': svc.get('version', '')
                     })
 
+        # Check for nmap errors before determining status
+        with open(log_path, 'r', encoding='utf-8', errors='replace') as f:
+            log_content = f.read()
+        nmap_error = detect_tool_error(log_content, 'nmap')
+
         # Determine status based on results
         hosts_up = len([h for h in parsed.get('hosts', []) if h.get('status') == 'up'])
-        if hosts_up > 0:
+        if nmap_error:
+            status = STATUS_ERROR  # Tool failed to run properly
+        elif hosts_up > 0:
             status = STATUS_DONE  # Found hosts
         else:
             status = STATUS_NO_RESULTS  # No hosts up
@@ -1122,8 +1218,13 @@ def parse_gobuster_job(engagement_id: int, log_path: str, job: Dict[str, Any]) -
                 exclude_length = length_match.group(1)
                 logger.info(f"Gobuster wildcard detected: Length {exclude_length}b")
 
+        # Check for gobuster errors
+        gobuster_error = detect_tool_error(log_content, 'gobuster')
+
         # Determine status based on results
-        if wildcard_detected:
+        if gobuster_error:
+            status = STATUS_ERROR  # Tool failed to connect
+        elif wildcard_detected:
             # Wildcard detected - warning status (triggers auto-retry)
             status = STATUS_WARNING
         elif stats['total'] > 0:
@@ -1504,8 +1605,13 @@ def parse_sqlmap_job(engagement_id: int, log_path: str, job: Dict[str, Any]) ->
 
         stats = get_sqli_stats(parsed)
 
+        # Check for sqlmap errors
+        sqlmap_error = detect_tool_error(log_content, 'sqlmap')
+
         # Determine status based on results
-        if stats['sqli_confirmed'] or stats['xss_possible'] or stats['fi_possible']:
+        if sqlmap_error:
+            status = STATUS_ERROR  # Tool failed to connect
+        elif stats['sqli_confirmed'] or stats['xss_possible'] or stats['fi_possible']:
             status = STATUS_DONE  # Found injection vulnerabilities
         else:
             status = STATUS_NO_RESULTS  # No injections found
@@ -2011,11 +2117,22 @@ def parse_smbmap_job(engagement_id: int, log_path: str, job: Dict[str, Any]) ->
             )
             findings_added += 1
 
+        # Check for smbmap errors
+        smbmap_error = detect_tool_error(log_content, 'smbmap')
+
+        # Determine status
+        if smbmap_error:
+            status = STATUS_ERROR  # Tool failed to connect
+        elif shares_added > 0 or findings_added > 0:
+            status = STATUS_DONE
+        else:
+            status = STATUS_NO_RESULTS
+
         return {
             'tool': 'smbmap',
             'host': parsed['target'],
             'connection_status': parsed.get('status', 'Unknown'),  # SMB connection status
-            'status': STATUS_DONE if (shares_added > 0 or findings_added > 0) else STATUS_NO_RESULTS,  # Job status
+            'status': status,  # Job status
             'shares_added': shares_added,
             'files_added': files_added,
             'findings_added': findings_added
@@ -2382,8 +2499,13 @@ def parse_hydra_job(engagement_id: int, log_path: str, job: Dict[str, Any]) -> D
             )
             findings_added += 1
 
+        # Check for hydra errors
+        hydra_error = detect_tool_error(log_content, 'hydra')
+
         # Determine status based on results
-        if len(parsed.get('credentials', [])) > 0:
+        if hydra_error:
+            status = STATUS_ERROR  # Tool failed to connect
+        elif len(parsed.get('credentials', [])) > 0:
             status = STATUS_DONE  # Found valid credentials
         elif len(parsed.get('usernames', [])) > 0:
             status = STATUS_DONE  # Found valid usernames (partial success is still a result)
@@ -2495,8 +2617,15 @@ def parse_nuclei_job(engagement_id: int, log_path: str, job: Dict[str, Any]) ->
             )
             findings_added += 1
 
+        # Check for nuclei errors
+        with open(log_path, 'r', encoding='utf-8', errors='replace') as f:
+            log_content = f.read()
+        nuclei_error = detect_tool_error(log_content, 'nuclei')
+
         # Determine status based on results
-        if parsed.get('findings_count', 0) > 0:
+        if nuclei_error:
+            status = STATUS_ERROR  # Tool failed to connect
+        elif parsed.get('findings_count', 0) > 0:
             status = STATUS_DONE  # Found vulnerabilities
         else:
             status = STATUS_NO_RESULTS  # No vulnerabilities found
@@ -2618,6 +2747,9 @@ def parse_enum4linux_job(engagement_id: int, log_path: str, job: Dict[str, Any])
                 'ip': parsed['target']
             })
 
+        # Check for enum4linux errors
+        enum4linux_error = detect_tool_error(log_content, 'enum4linux')
+
         # Determine status: done if we found any results (shares, users, or findings)
         has_results = (
             findings_added > 0 or
@@ -2626,9 +2758,16 @@ def parse_enum4linux_job(engagement_id: int, log_path: str, job: Dict[str, Any])
             stats['total_shares'] > 0
         )
 
+        if enum4linux_error:
+            status = STATUS_ERROR  # Tool failed to connect
+        elif has_results:
+            status = STATUS_DONE
+        else:
+            status = STATUS_NO_RESULTS
+
         return {
             'tool': 'enum4linux',
-            'status': STATUS_DONE if has_results else STATUS_NO_RESULTS,
+            'status': status,
             'findings_added': findings_added,
             'credentials_added': credentials_added,
             'users_found': len(parsed['users']),
@@ -2735,13 +2874,26 @@ def parse_ffuf_job(engagement_id: int, log_path: str, job: Dict[str, Any]) -> Di
         
         if host_id and parsed.get('paths'):
             paths_added = wpm.bulk_add_web_paths(host_id, parsed['paths'])
-            
+
             # Check for sensitive paths and create findings (same as gobuster)
             created_findings = _create_findings_for_sensitive_paths(engagement_id, host_id, parsed['paths'], job)
 
+        # Check for ffuf errors
+        with open(log_path, 'r', encoding='utf-8', errors='replace') as f:
+            log_content = f.read()
+        ffuf_error = detect_tool_error(log_content, 'ffuf')
+
+        # Determine status
+        if ffuf_error:
+            status = STATUS_ERROR  # Tool failed to connect
+        elif parsed.get('results_found', 0) > 0:
+            status = STATUS_DONE
+        else:
+            status = STATUS_NO_RESULTS
+
         return {
             'tool': 'ffuf',
-            'status': STATUS_DONE if parsed.get('results_found', 0) > 0 else STATUS_NO_RESULTS,
+            'status': status,
             'target': target,
             'results_found': parsed.get('results_found', 0),
             'paths_added': paths_added,
@@ -3060,8 +3212,13 @@ def parse_nikto_job(engagement_id: int, log_path: str, job: Dict[str, Any]) -> D
             )
             findings_added += 1
 
+        # Check for nikto errors
+        nikto_error = detect_tool_error(output, 'nikto')
+
         # Determine status based on results
-        if findings_added > 0:
+        if nikto_error:
+            status = STATUS_ERROR  # Tool failed to connect
+        elif findings_added > 0:
             status = STATUS_DONE
         else:
             status = STATUS_NO_RESULTS

souleyez/main.py

@@ -173,7 +173,7 @@ def _check_privileged_tools():
 
 
 @click.group()
-@click.version_option(version='2.27.0')
+@click.version_option(version='2.28.0')
 def cli():
     """SoulEyez - AI-Powered Pentesting Platform by CyberSoul Security"""
     from souleyez.log_config import init_logging
@@ -604,6 +604,227 @@ from souleyez.commands.audit import audit
 cli.add_command(audit)
 
 
+# ============================================================================
+# SCOPE MANAGEMENT
+# ============================================================================
+
+@cli.group()
+def scope():
+    """Engagement scope management - define and enforce target boundaries."""
+    pass
+
+
+@scope.command("add")
+@click.argument("engagement_name")
+@click.option("--cidr", help="Add CIDR range (e.g., 192.168.1.0/24)")
+@click.option("--domain", help="Add domain pattern (e.g., *.example.com)")
+@click.option("--url", help="Add URL (e.g., https://app.example.com)")
+@click.option("--hostname", help="Add specific hostname or IP")
+@click.option("--exclude", is_flag=True, help="Add as exclusion (deny rule)")
+@click.option("--description", "-d", default="", help="Description for this scope entry")
+def scope_add(engagement_name, cidr, domain, url, hostname, exclude, description):
+    """Add a scope entry to an engagement."""
+    from souleyez.security.scope_validator import ScopeManager
+
+    em = EngagementManager()
+    eng = em.get(engagement_name)
+    if not eng:
+        click.echo(f"Error: Engagement '{engagement_name}' not found", err=True)
+        return
+
+    manager = ScopeManager()
+
+    # Determine scope type and value
+    if cidr:
+        scope_type, value = 'cidr', cidr
+    elif domain:
+        scope_type, value = 'domain', domain
+    elif url:
+        scope_type, value = 'url', url
+    elif hostname:
+        scope_type, value = 'hostname', hostname
+    else:
+        click.echo("Error: Must specify one of --cidr, --domain, --url, or --hostname", err=True)
+        return
+
+    try:
+        scope_id = manager.add_scope(
+            engagement_id=eng['id'],
+            scope_type=scope_type,
+            value=value,
+            is_excluded=exclude,
+            description=description
+        )
+        action = "exclusion" if exclude else "scope entry"
+        click.echo(f"Added {action}: {scope_type}={value} (id={scope_id})")
+    except ValueError as e:
+        click.echo(f"Error: {e}", err=True)
+
+
+@scope.command("list")
+@click.argument("engagement_name")
+def scope_list(engagement_name):
+    """List scope entries for an engagement."""
+    from souleyez.security.scope_validator import ScopeManager, ScopeValidator
+
+    em = EngagementManager()
+    eng = em.get(engagement_name)
+    if not eng:
+        click.echo(f"Error: Engagement '{engagement_name}' not found", err=True)
+        return
+
+    manager = ScopeManager()
+    validator = ScopeValidator(eng['id'])
+    entries = manager.list_scope(eng['id'])
+    enforcement = validator.get_enforcement_mode()
+
+    click.echo(f"\nScope for '{engagement_name}' (enforcement: {enforcement})")
+    click.echo("=" * 70)
+
+    if not entries:
+        click.echo("No scope entries defined (all targets allowed)")
+        return
+
+    click.echo(f"{'ID':<5} {'Type':<10} {'Value':<35} {'Excluded':<10}")
+    click.echo("-" * 70)
+
+    for entry in entries:
+        excluded = "EXCLUDE" if entry.get('is_excluded') else ""
+        click.echo(f"{entry['id']:<5} {entry['scope_type']:<10} {entry['value']:<35} {excluded:<10}")
+        if entry.get('description'):
+            click.echo(f"      {entry['description']}")
+
+    click.echo()
+
+
+@scope.command("remove")
+@click.argument("engagement_name")
+@click.argument("scope_id", type=int)
+def scope_remove(engagement_name, scope_id):
+    """Remove a scope entry by ID."""
+    from souleyez.security.scope_validator import ScopeManager
+
+    em = EngagementManager()
+    eng = em.get(engagement_name)
+    if not eng:
+        click.echo(f"Error: Engagement '{engagement_name}' not found", err=True)
+        return
+
+    manager = ScopeManager()
+    if manager.remove_scope(scope_id):
+        click.echo(f"Removed scope entry {scope_id}")
+    else:
+        click.echo(f"Error: Failed to remove scope entry {scope_id}", err=True)
+
+
+@scope.command("enforcement")
+@click.argument("engagement_name")
+@click.argument("mode", type=click.Choice(['off', 'warn', 'block']))
+def scope_enforcement(engagement_name, mode):
+    """Set enforcement mode for an engagement.
+
+    Modes:
+      off   - No scope validation (default)
+      warn  - Allow out-of-scope targets but log warning
+      block - Reject jobs targeting out-of-scope hosts
+    """
+    from souleyez.security.scope_validator import ScopeManager
+
+    em = EngagementManager()
+    eng = em.get(engagement_name)
+    if not eng:
+        click.echo(f"Error: Engagement '{engagement_name}' not found", err=True)
+        return
+
+    manager = ScopeManager()
+    if manager.set_enforcement(eng['id'], mode):
+        click.echo(f"Enforcement mode set to '{mode}' for '{engagement_name}'")
+    else:
+        click.echo("Error: Failed to set enforcement mode", err=True)
+
+
+@scope.command("validate")
+@click.argument("engagement_name")
+@click.argument("target")
+def scope_validate(engagement_name, target):
+    """Test if a target is in scope."""
+    from souleyez.security.scope_validator import ScopeValidator
+
+    em = EngagementManager()
+    eng = em.get(engagement_name)
+    if not eng:
+        click.echo(f"Error: Engagement '{engagement_name}' not found", err=True)
+        return
+
+    validator = ScopeValidator(eng['id'])
+    result = validator.validate_target(target)
+
+    if result.is_in_scope:
+        click.echo(f"IN SCOPE: {target}")
+        if result.matched_entry:
+            click.echo(f"  Matched: {result.matched_entry.get('value')}")
+    else:
+        click.echo(f"OUT OF SCOPE: {target}")
+        click.echo(f"  Reason: {result.reason}")
+
+    click.echo(f"  Enforcement: {validator.get_enforcement_mode()}")
+
+
+@scope.command("revalidate")
+@click.argument("engagement_name")
+def scope_revalidate(engagement_name):
+    """Revalidate scope status for all hosts in an engagement."""
+    from souleyez.storage.hosts import HostManager
+
+    em = EngagementManager()
+    eng = em.get(engagement_name)
+    if not eng:
+        click.echo(f"Error: Engagement '{engagement_name}' not found", err=True)
+        return
+
+    hm = HostManager()
+    result = hm.revalidate_scope_status(eng['id'])
+
+    click.echo(f"Revalidated hosts for '{engagement_name}':")
+    click.echo(f"  Updated: {result['updated']}")
+    click.echo(f"  In scope: {result['in_scope']}")
+    click.echo(f"  Out of scope: {result['out_of_scope']}")
+
+
+@scope.command("log")
+@click.argument("engagement_name")
+@click.option("--limit", "-n", default=50, help="Number of entries to show")
+def scope_log(engagement_name, limit):
+    """Show scope validation audit log."""
+    from souleyez.security.scope_validator import ScopeManager
+
+    em = EngagementManager()
+    eng = em.get(engagement_name)
+    if not eng:
+        click.echo(f"Error: Engagement '{engagement_name}' not found", err=True)
+        return
+
+    manager = ScopeManager()
+    log_entries = manager.get_validation_log(eng['id'], limit)
+
+    click.echo(f"\nScope validation log for '{engagement_name}' (last {limit})")
+    click.echo("=" * 80)
+
+    if not log_entries:
+        click.echo("No validation log entries")
+        return
+
+    click.echo(f"{'Time':<20} {'Target':<25} {'Result':<12} {'Action':<10}")
+    click.echo("-" * 80)
+
+    for entry in log_entries:
+        timestamp = entry.get('created_at', '')[:19]  # Trim to datetime
+        target = entry.get('target', '')[:24]
+        result = entry.get('validation_result', '')
+        action = entry.get('action_taken', '')
+        click.echo(f"{timestamp:<20} {target:<25} {result:<12} {action:<10}")
+
+
 @cli.group()
 def jobs():
     """Background job management."""

souleyez/plugins/nuclei.py

@@ -195,8 +195,9 @@ class NucleiPlugin(PluginBase):
         import os
         from pathlib import Path
 
-        # Check common template locations
+        # Check common template locations (nuclei v3 uses ~/.local/nuclei-templates)
         template_paths = [
+            Path.home() / ".local" / "nuclei-templates",  # nuclei v3 default
             Path.home() / "nuclei-templates",
             Path.home() / ".nuclei-templates",
             Path("/usr/share/nuclei-templates"),

souleyez/plugins/searchsploit.py

@@ -126,27 +126,30 @@ class SearchSploitPlugin(PluginBase):
 
     def build_command(self, target: str, args: List[str] = None, label: str = "", log_path: str = None):
         """Build command for background execution with PID tracking."""
-        # Validate target
-        if not target or target.lower() == 'none':
-            raise ValueError("SearchSploit requires a search term. Usage: souleyez run searchsploit 'Apache 2.4.49'")
-        
         args = args or []
-        
+
         # Replace <target> placeholder
         args = [arg.replace("<target>", target) for arg in args]
-        
-        # searchsploit syntax: searchsploit [--json] search_term [args]
-        cmd = ["searchsploit"]
-        
-        # Force JSON output for parsing
-        if "--json" not in args:
-            cmd.append("--json")
-        
-        # Add search term
-        cmd.append(target)
-        
-        # Add user args (after target)
-        cmd.extend(args)
+
+        # searchsploit syntax: searchsploit [--json] search_term
+        cmd = ["searchsploit", "--json"]
+
+        # Determine search term: use args if they contain a non-flag search term,
+        # otherwise use target (but skip if target is a URL - not a valid search term)
+        non_flag_args = [a for a in args if not a.startswith('-')]
+
+        if non_flag_args:
+            # Args contain search term(s) - use those, ignore URL target
+            cmd.extend(non_flag_args)
+        elif target and not target.startswith(('http://', 'https://')):
+            # Target is not a URL - use it as search term
+            cmd.append(target)
+        else:
+            raise ValueError("SearchSploit requires a search term. Usage: souleyez run searchsploit 'Apache 2.4.49'")
+
+        # Add remaining flag args (excluding --json which is already added)
+        flag_args = [a for a in args if a.startswith('-') and a != '--json']
+        cmd.extend(flag_args)
         
         return {
             'cmd': cmd,