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

souleyez/storage/hosts.py

@@ -28,9 +28,12 @@ class HostManager:
         if not ip:
             raise ValueError("Host must have an IP address")
 
+        # Determine scope status for this host
+        scope_status = self._determine_scope_status(engagement_id, ip)
+
         # Check if host already exists
         existing = self.db.execute_one(
-            "SELECT id FROM hosts WHERE engagement_id = ? AND ip_address = ?",
+            "SELECT id, scope_status FROM hosts WHERE engagement_id = ? AND ip_address = ?",
             (engagement_id, ip)
         )
 
@@ -43,6 +46,10 @@ class HostManager:
             # Always update status
             update_data['status'] = host_data.get('status', 'up')
 
+            # Update scope_status if it was unknown and we now have a determination
+            if existing.get('scope_status') == 'unknown' and scope_status != 'unknown':
+                update_data['scope_status'] = scope_status
+
             # Only update these fields if they have values
             if host_data.get('hostname'):
                 update_data['hostname'] = host_data['hostname']
@@ -71,11 +78,89 @@ class HostManager:
                 'os_name': host_data.get('os'),
                 'mac_address': host_data.get('mac_address'),
                 'os_accuracy': host_data.get('os_accuracy'),
-                'status': host_data.get('status', 'up')
+                'status': host_data.get('status', 'up'),
+                'scope_status': scope_status
             })
 
             return host_id
 
+    def _determine_scope_status(self, engagement_id: int, ip: str) -> str:
+        """
+        Determine scope status for a host based on engagement scope.
+
+        Args:
+            engagement_id: Engagement ID
+            ip: IP address to check
+
+        Returns:
+            'in_scope', 'out_of_scope', or 'unknown'
+        """
+        try:
+            from souleyez.security.scope_validator import ScopeValidator
+            validator = ScopeValidator(engagement_id)
+            if validator.has_scope_defined():
+                result = validator.validate_ip(ip)
+                return 'in_scope' if result.is_in_scope else 'out_of_scope'
+            return 'unknown'  # No scope defined
+        except Exception as e:
+            logger.warning(f"Failed to determine scope status for {ip}: {e}")
+            return 'unknown'
+
+    def update_scope_status(self, host_id: int, scope_status: str) -> bool:
+        """
+        Update scope status for a host.
+
+        Args:
+            host_id: Host ID
+            scope_status: 'in_scope', 'out_of_scope', or 'unknown'
+
+        Returns:
+            True if successful
+        """
+        valid_statuses = ['in_scope', 'out_of_scope', 'unknown']
+        if scope_status not in valid_statuses:
+            raise ValueError(f"Invalid scope_status: {scope_status}. Must be one of: {valid_statuses}")
+
+        try:
+            self.db.execute(
+                "UPDATE hosts SET scope_status = ? WHERE id = ?",
+                (scope_status, host_id)
+            )
+            return True
+        except Exception:
+            return False
+
+    def revalidate_scope_status(self, engagement_id: int) -> Dict[str, int]:
+        """
+        Revalidate scope status for all hosts in an engagement.
+
+        Call this after scope entries are added/modified to update all hosts.
+
+        Args:
+            engagement_id: Engagement ID
+
+        Returns:
+            {'updated': N, 'in_scope': X, 'out_of_scope': Y}
+        """
+        hosts = self.list_hosts(engagement_id)
+        updated = 0
+        in_scope = 0
+        out_of_scope = 0
+
+        for host in hosts:
+            ip = host.get('ip') or host.get('ip_address')
+            new_status = self._determine_scope_status(engagement_id, ip)
+            if new_status != host.get('scope_status'):
+                self.update_scope_status(host['id'], new_status)
+                updated += 1
+
+            if new_status == 'in_scope':
+                in_scope += 1
+            elif new_status == 'out_of_scope':
+                out_of_scope += 1
+
+        return {'updated': updated, 'in_scope': in_scope, 'out_of_scope': out_of_scope}
+
     def add_service(self, host_id: int, service_data: Dict[str, Any]) -> int:
         """
         Add or update a service for a host.

souleyez/storage/migrations/_026_add_engagement_scope.py

@@ -0,0 +1,87 @@
+"""
+Migration 026: Add Engagement Scope Validation
+
+Tables created:
+- engagement_scope: Structured scope definitions (CIDR, domains, URLs)
+- scope_validation_log: Audit trail of scope validation decisions
+
+Columns added:
+- engagements.scope_enforcement: Enforcement mode (off, warn, block)
+- hosts.scope_status: Host scope status (in_scope, out_of_scope, unknown)
+"""
+import os
+
+
+def upgrade(conn):
+    """Add scope validation tables and columns."""
+
+    # Engagement scope definitions table
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS engagement_scope (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            engagement_id INTEGER NOT NULL,
+            scope_type TEXT NOT NULL,
+            value TEXT NOT NULL,
+            is_excluded BOOLEAN DEFAULT 0,
+            description TEXT,
+            added_by TEXT,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            FOREIGN KEY (engagement_id) REFERENCES engagements(id) ON DELETE CASCADE,
+            UNIQUE(engagement_id, scope_type, value)
+        )
+    """)
+
+    # Scope validation audit log
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS scope_validation_log (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            engagement_id INTEGER NOT NULL,
+            job_id INTEGER,
+            target TEXT NOT NULL,
+            validation_result TEXT NOT NULL,
+            action_taken TEXT NOT NULL,
+            matched_scope_id INTEGER,
+            user_id TEXT,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            FOREIGN KEY (engagement_id) REFERENCES engagements(id) ON DELETE CASCADE
+        )
+    """)
+
+    # Add scope_enforcement column to engagements
+    try:
+        conn.execute("ALTER TABLE engagements ADD COLUMN scope_enforcement TEXT DEFAULT 'off'")
+    except Exception:
+        pass  # Column may already exist
+
+    # Add scope_status column to hosts
+    try:
+        conn.execute("ALTER TABLE hosts ADD COLUMN scope_status TEXT DEFAULT 'unknown'")
+    except Exception:
+        pass  # Column may already exist
+
+    # Indexes for performance
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_scope_engagement ON engagement_scope(engagement_id)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_scope_type ON engagement_scope(scope_type)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_scope_log_engagement ON scope_validation_log(engagement_id)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_scope_log_result ON scope_validation_log(validation_result)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_scope_log_timestamp ON scope_validation_log(created_at DESC)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_hosts_scope_status ON hosts(scope_status)")
+
+    conn.commit()
+
+    if not os.environ.get('SOULEYEZ_MIGRATION_SILENT'):
+        print("Migration 026: Engagement scope validation tables created")
+
+
+def downgrade(conn):
+    """Remove scope validation tables."""
+    conn.execute("DROP TABLE IF EXISTS scope_validation_log")
+    conn.execute("DROP TABLE IF EXISTS engagement_scope")
+    conn.execute("DROP INDEX IF EXISTS idx_scope_engagement")
+    conn.execute("DROP INDEX IF EXISTS idx_scope_type")
+    conn.execute("DROP INDEX IF EXISTS idx_scope_log_engagement")
+    conn.execute("DROP INDEX IF EXISTS idx_scope_log_result")
+    conn.execute("DROP INDEX IF EXISTS idx_scope_log_timestamp")
+    conn.execute("DROP INDEX IF EXISTS idx_hosts_scope_status")
+    # Note: Cannot easily drop columns in SQLite, they remain but unused
+    print("Migration 026: Engagement scope validation tables dropped")

souleyez/ui/interactive.py

@@ -7172,6 +7172,275 @@ def view_results_menu():
             return
 
 
+def _scope_management_menu(engagement_id: int, engagement_name: str):
+    """Interactive scope management menu for an engagement."""
+    from souleyez.security.scope_validator import ScopeManager, ScopeValidator
+    from souleyez.storage.hosts import HostManager
+    from rich.console import Console
+    from rich.table import Table
+
+    manager = ScopeManager()
+    validator = ScopeValidator(engagement_id)
+
+    while True:
+        DesignSystem.clear_screen()
+        render_standard_header(f"SCOPE MANAGEMENT - {engagement_name}")
+
+        # Get current scope info
+        entries = manager.list_scope(engagement_id)
+        enforcement = validator.get_enforcement_mode()
+
+        # Show enforcement status
+        if enforcement == 'block':
+            enf_color = 'red'
+            enf_desc = 'Block out-of-scope targets'
+        elif enforcement == 'warn':
+            enf_color = 'yellow'
+            enf_desc = 'Warn but allow'
+        else:
+            enf_color = 'bright_black'
+            enf_desc = 'No validation'
+
+        click.echo()
+        click.echo(f"  Enforcement: {click.style(enforcement.upper(), fg=enf_color, bold=True)} - {enf_desc}")
+        click.echo()
+
+        # Display scope entries
+        if not entries:
+            click.echo(click.style("  No scope entries defined - all targets allowed", fg='yellow'))
+            click.echo()
+        else:
+            console = Console()
+            table = Table(show_header=True, header_style="bold", box=DesignSystem.TABLE_BOX, padding=(0, 1))
+
+            table.add_column("ID", width=4, justify="right")
+            table.add_column("Type", width=10)
+            table.add_column("Value", min_width=30)
+            table.add_column("Status", width=10)
+            table.add_column("Description", max_width=25)
+
+            for entry in entries:
+                status = "[red]EXCLUDE[/red]" if entry.get('is_excluded') else "[green]INCLUDE[/green]"
+                table.add_row(
+                    str(entry['id']),
+                    entry['scope_type'],
+                    entry['value'],
+                    status,
+                    entry.get('description', '') or ''
+                )
+
+            console.print(table)
+            click.echo()
+
+        click.echo("─" * get_terminal_width())
+        click.echo()
+        click.echo("  [+] Add scope entry")
+        click.echo("  [-] Remove scope entry")
+        click.echo("  [e] Change enforcement mode")
+        click.echo("  [t] Test target validation")
+        click.echo("  [r] Revalidate all hosts")
+        click.echo("  [l] View validation log")
+        click.echo("  [q] Back")
+        click.echo()
+
+        try:
+            choice = click.prompt("  Select option", type=str, default='q', show_default=False).strip().lower()
+
+            if choice == 'q':
+                return
+
+            elif choice == '+':
+                # Add scope entry
+                click.echo()
+                click.echo(click.style("  Add Scope Entry", fg='cyan', bold=True))
+                click.echo()
+                click.echo("  Type:")
+                click.echo("    [1] CIDR range (e.g., 192.168.1.0/24)")
+                click.echo("    [2] Domain pattern (e.g., *.example.com)")
+                click.echo("    [3] URL (e.g., https://app.example.com)")
+                click.echo("    [4] Hostname/IP (exact match)")
+                click.echo("    [c] Cancel")
+                click.echo()
+
+                type_choice = click.prompt("  Select type", type=str, default='c').strip().lower()
+
+                if type_choice == 'c':
+                    continue
+
+                type_map = {'1': 'cidr', '2': 'domain', '3': 'url', '4': 'hostname'}
+                scope_type = type_map.get(type_choice)
+
+                if not scope_type:
+                    click.echo(click.style("\n  Invalid choice!", fg='red'))
+                    click.pause()
+                    continue
+
+                # Get value
+                if scope_type == 'cidr':
+                    value_hint = "192.168.1.0/24"
+                elif scope_type == 'domain':
+                    value_hint = "*.example.com or example.com"
+                elif scope_type == 'url':
+                    value_hint = "https://app.example.com"
+                else:
+                    value_hint = "10.0.0.1 or server.local"
+
+                value = click.prompt(f"\n  Enter {scope_type} ({value_hint})", type=str).strip()
+                if not value:
+                    continue
+
+                # Ask if exclusion
+                is_excluded = click.confirm("  Is this an EXCLUSION (deny rule)?", default=False)
+
+                # Optional description
+                description = click.prompt("  Description (optional)", type=str, default="").strip()
+
+                try:
+                    scope_id = manager.add_scope(
+                        engagement_id=engagement_id,
+                        scope_type=scope_type,
+                        value=value,
+                        is_excluded=is_excluded,
+                        description=description or None
+                    )
+                    entry_type = "exclusion" if is_excluded else "scope entry"
+                    click.echo(click.style(f"\n  ✓ Added {entry_type}: {scope_type}={value} (ID: {scope_id})", fg='green'))
+                except ValueError as e:
+                    click.echo(click.style(f"\n  ✗ Invalid value: {e}", fg='red'))
+                except Exception as e:
+                    if "UNIQUE constraint" in str(e):
+                        click.echo(click.style(f"\n  ✗ This scope entry already exists!", fg='red'))
+                    else:
+                        click.echo(click.style(f"\n  ✗ Error: {e}", fg='red'))
+                click.pause()
+
+            elif choice == '-':
+                # Remove scope entry
+                if not entries:
+                    click.echo(click.style("\n  No scope entries to remove!", fg='yellow'))
+                    click.pause()
+                    continue
+
+                try:
+                    scope_id = click.prompt("\n  Enter scope ID to remove", type=int)
+                    entry = next((e for e in entries if e['id'] == scope_id), None)
+
+                    if entry:
+                        if click.confirm(f"  Remove '{entry['scope_type']}={entry['value']}'?", default=False):
+                            if manager.remove_scope(scope_id):
+                                click.echo(click.style(f"\n  ✓ Removed scope entry {scope_id}", fg='green'))
+                            else:
+                                click.echo(click.style(f"\n  ✗ Failed to remove scope entry!", fg='red'))
+                    else:
+                        click.echo(click.style(f"\n  ✗ Scope ID {scope_id} not found!", fg='red'))
+                except ValueError:
+                    click.echo(click.style("\n  ✗ Invalid ID!", fg='red'))
+                click.pause()
+
+            elif choice == 'e':
+                # Change enforcement mode
+                click.echo()
+                click.echo(click.style("  Enforcement Mode", fg='cyan', bold=True))
+                click.echo()
+                click.echo(f"  Current: {click.style(enforcement.upper(), fg=enf_color, bold=True)}")
+                click.echo()
+                click.echo("    [1] OFF - No scope validation")
+                click.echo("    [2] WARN - Allow but log warning")
+                click.echo("    [3] BLOCK - Reject out-of-scope targets")
+                click.echo("    [c] Cancel")
+                click.echo()
+
+                mode_choice = click.prompt("  Select mode", type=str, default='c').strip().lower()
+
+                mode_map = {'1': 'off', '2': 'warn', '3': 'block'}
+                new_mode = mode_map.get(mode_choice)
+
+                if new_mode:
+                    if manager.set_enforcement(engagement_id, new_mode):
+                        click.echo(click.style(f"\n  ✓ Enforcement mode set to {new_mode.upper()}", fg='green'))
+                        # Refresh validator cache
+                        validator = ScopeValidator(engagement_id)
+                    else:
+                        click.echo(click.style("\n  ✗ Failed to set enforcement mode!", fg='red'))
+                    click.pause()
+
+            elif choice == 't':
+                # Test target validation
+                click.echo()
+                target = click.prompt("  Enter target to test", type=str).strip()
+                if target:
+                    result = validator.validate_target(target)
+                    click.echo()
+                    if result.is_in_scope:
+                        click.echo(click.style(f"  ✓ IN SCOPE: {target}", fg='green', bold=True))
+                        if result.matched_entry:
+                            click.echo(f"    Matched: {result.matched_entry.get('value')}")
+                    else:
+                        click.echo(click.style(f"  ✗ OUT OF SCOPE: {target}", fg='red', bold=True))
+                        click.echo(f"    Reason: {result.reason}")
+                    click.echo(f"    Enforcement: {enforcement}")
+                click.pause()
+
+            elif choice == 'r':
+                # Revalidate all hosts
+                click.echo()
+                if click.confirm("  Revalidate scope status for all hosts in this engagement?", default=True):
+                    hm = HostManager()
+                    result = hm.revalidate_scope_status(engagement_id)
+                    click.echo()
+                    click.echo(click.style("  Revalidation complete:", fg='green'))
+                    click.echo(f"    Updated: {result['updated']}")
+                    click.echo(f"    In scope: {result['in_scope']}")
+                    click.echo(f"    Out of scope: {result['out_of_scope']}")
+                click.pause()
+
+            elif choice == 'l':
+                # View validation log
+                log_entries = manager.get_validation_log(engagement_id, limit=30)
+                click.echo()
+                click.echo(click.style("  Recent Scope Validation Log (last 30)", fg='cyan', bold=True))
+                click.echo()
+
+                if not log_entries:
+                    click.echo("  No validation log entries yet.")
+                else:
+                    console = Console()
+                    table = Table(show_header=True, header_style="bold", box=DesignSystem.TABLE_BOX, padding=(0, 1))
+
+                    table.add_column("Time", width=19)
+                    table.add_column("Target", min_width=20)
+                    table.add_column("Result", width=12)
+                    table.add_column("Action", width=10)
+                    table.add_column("Job", width=6)
+
+                    for entry in log_entries:
+                        timestamp = entry.get('created_at', '')[:19]
+                        target = entry.get('target', '')
+                        result_val = entry.get('validation_result', '')
+                        action = entry.get('action_taken', '')
+                        job_id = str(entry.get('job_id', '-') or '-')
+
+                        # Color code results
+                        if result_val == 'in_scope':
+                            result_display = "[green]in_scope[/green]"
+                        elif result_val == 'out_of_scope':
+                            result_display = "[red]out_of_scope[/red]"
+                        else:
+                            result_display = result_val
+
+                        table.add_row(timestamp, target, result_display, action, job_id)
+
+                    console.print(table)
+                click.pause()
+
+            else:
+                click.echo(click.style("\n  Invalid choice!", fg='red'))
+                click.pause()
+
+        except (KeyboardInterrupt, EOFError):
+            return
+
+
 def _engagements_bulk_action_menu(selected_ids: set, em, current_id: int):
     """Show bulk action menu for selected engagements."""
     click.echo()
@@ -7426,6 +7695,7 @@ def manage_engagements_menu():
             click.echo("  [a] All - Toggle pagination")
         click.echo("  [+] Create - Create new engagement")
         click.echo("  [-] Delete - Delete engagement(s)")
+        click.echo("  [s] Scope - Manage target scope")
         click.echo("  [d] Deliverables - Track progress")
         click.echo("  [q] Back")
 
@@ -7460,6 +7730,15 @@ def manage_engagements_menu():
                 current_page = 0
                 continue
 
+            elif choice_input == 's':
+                # Scope Management
+                if not current_ws:
+                    click.echo(click.style("\n  ⚠️  Please select an engagement first!", fg='yellow'))
+                    click.pause()
+                    continue
+                _scope_management_menu(current_ws['id'], current_ws['name'])
+                continue
+
             elif choice_input == 'd':
                 # Deliverables Tracker
                 if not current_ws:
@@ -30962,31 +31241,36 @@ def view_documentation_menu():
             'name': 'Keyboard Shortcuts',
             'file': None,  # Special handler
             'description': 'Command Center and Dashboard shortcuts'
+        },
+        '8': {
+            'name': 'Scope Management Guide',
+            'file': 'docs/user-guide/scope-management.md',
+            'description': 'Target validation and boundary enforcement'
         }
     }
 
     # Add PRO-only documentation
     if is_pro:
         docs.update({
-            '8': {
+            '9': {
                 'name': 'MSF Integration Guide',
                 'file': None,  # Special handler
                 'description': 'Metasploit Framework workflows',
                 'pro': True
             },
-            '9': {
+            '10': {
                 'name': 'RBAC & User Management',
                 'file': 'docs/user-guide/rbac.md',
                 'description': 'Roles, permissions, and audit logging',
                 'pro': True
             },
-            '10': {
+            '11': {
                 'name': 'SIEM Integration Guide',
                 'file': 'docs/user-guide/siem-integration.md',
                 'description': 'Splunk, Wazuh, Elastic, Sentinel setup',
                 'pro': True
             },
-            '11': {
+            '12': {
                 'name': 'AI Integration Guide',
                 'file': 'docs/user-guide/ai-integration.md',
                 'description': 'AI providers and autonomous execution',
@@ -31055,7 +31339,7 @@ def view_documentation_menu():
                 continue
 
             # Special handler for MSF Integration Guide
-            if choice == '8':
+            if choice == '9':
                 _show_msf_help()
                 continue
 

{souleyez-2.27.0.dist-info → souleyez-2.28.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: souleyez
-Version: 2.27.0
+Version: 2.28.0
 Summary: AI-Powered Penetration Testing Platform with 40+ integrated tools
 Author-email: CyberSoul Security <contact@cybersoulsecurity.com>
 Maintainer-email: CyberSoul Security <contact@cybersoulsecurity.com>
@@ -51,6 +51,12 @@ Dynamic: license-file
 
 # SoulEyez Beta Program
 
+[![CI](https://github.com/cyber-soul-security/souleyez/actions/workflows/python-ci.yml/badge.svg)](https://github.com/cyber-soul-security/souleyez/actions/workflows/python-ci.yml)
+[![codecov](https://codecov.io/gh/cyber-soul-security/souleyez/branch/main/graph/badge.svg)](https://codecov.io/gh/cyber-soul-security/souleyez)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+
 Welcome to the SoulEyez beta! Thank you for helping us test and improve this penetration testing management platform.
 
 ---
@@ -72,7 +78,7 @@ Welcome to the SoulEyez beta! Thank you for helping us test and improve this pen
 
 > ⚠️ **Important**: Only use SoulEyez on systems you have explicit authorization to test.
 
-## Version: 2.27.0
+## Version: 2.28.0
 
 ### What's Included
 
@@ -310,4 +316,4 @@ Happy hacking! 🛡️
 
 ---
 
-**Version**: 2.27.0 | **Release Date**: January 2026 | **Maintainer**: CyberSoul Security
+**Version**: 2.28.0 | **Release Date**: January 2026 | **Maintainer**: CyberSoul Security