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

souleyez/docs/developer-guide/adding-new-tools.md

@@ -0,0 +1,562 @@
+# Adding New Tools to SoulEyez
+
+This guide covers the complete process for integrating a new external tool into SoulEyez. Follow ALL steps to ensure proper integration.
+
+## Quick Checklist
+
+Use this checklist when adding a new tool:
+
+- [ ] 1. Create plugin file (`souleyez/plugins/<tool>.py`)
+- [ ] 2. Create handler file (`souleyez/handlers/<tool>_handler.py`)
+- [ ] 3. Register handler in registry (`souleyez/handlers/registry.py`)
+- [ ] 4. Add to tool checker (`souleyez/utils/tool_checker.py`)
+- [ ] 5. Add to interactive UI menu (`souleyez/ui/interactive.py`)
+- [ ] 6. Add chain rules if applicable (`souleyez/core/tool_chaining.py`)
+- [ ] 7. Test the integration
+- [ ] 8. Commit and push
+
+---
+
+## Step 1: Create the Plugin
+
+**File:** `souleyez/plugins/<tool_name>.py`
+
+The plugin defines how to build and execute the tool command.
+
+```python
+#!/usr/bin/env python3
+"""
+souleyez.plugins.<tool_name> - Brief description
+"""
+import subprocess
+import time
+from typing import List
+
+from .plugin_base import PluginBase
+
+HELP = {
+    "name": "Tool Display Name",
+    "description": (
+        "Multi-line description of what the tool does.\n\n"
+        "When to use this tool:\n"
+        "- Use case 1\n"
+        "- Use case 2\n"
+    ),
+    "usage": "souleyez jobs enqueue <tool> <target> --args \"<arguments>\"",
+    "examples": [
+        "souleyez jobs enqueue <tool> 10.0.0.1 --args \"arg1 arg2\"",
+    ],
+    "flags": [
+        ["--flag1", "Description of flag1"],
+        ["--flag2", "Description of flag2"],
+    ],
+    "preset_categories": {
+        "category_name": [
+            {
+                "name": "Preset Name",
+                "args": ["arg1", "arg2", "<target>"],
+                "desc": "What this preset does"
+            },
+        ]
+    },
+    "presets": []  # Auto-populated from preset_categories
+}
+
+# Flatten presets
+for category_presets in HELP['preset_categories'].values():
+    HELP['presets'].extend(category_presets)
+
+
+class ToolNamePlugin(PluginBase):
+    name = "Tool Display Name"
+    tool = "tool_command"  # The actual CLI command
+    category = "category_name"  # reconnaissance, scanning, exploitation, etc.
+    HELP = HELP
+
+    def build_command(self, target: str, args: List[str] = None, label: str = "", log_path: str = None):
+        """Build command for background execution."""
+        args = args or []
+        args = [arg.replace("<target>", target) for arg in args]
+
+        cmd = ["tool_command"]
+        cmd.extend(args)
+
+        return {
+            'cmd': cmd,
+            'timeout': 1800  # 30 minutes default
+        }
+
+    def run(self, target: str, args: List[str] = None, label: str = "", log_path: str = None) -> int:
+        """Execute tool and write output to log_path."""
+        args = args or []
+        args = [arg.replace("<target>", target) for arg in args]
+
+        cmd = ["tool_command"]
+        cmd.extend(args)
+
+        if not log_path:
+            try:
+                proc = subprocess.run(cmd, capture_output=True, timeout=600, check=False)
+                return proc.returncode
+            except Exception:
+                return 1
+
+        try:
+            with open(log_path, "w", encoding="utf-8", errors="replace") as fh:
+                fh.write(f"=== Plugin: ToolName ===\n")
+                fh.write(f"Target: {target}\n")
+                fh.write(f"Args: {args}\n")
+                fh.write(f"Command: {' '.join(cmd)}\n\n")
+
+            proc = subprocess.run(cmd, capture_output=True, timeout=600, check=False, text=True)
+
+            with open(log_path, "a", encoding="utf-8", errors="replace") as fh:
+                if proc.stdout:
+                    fh.write(proc.stdout)
+                if proc.stderr:
+                    fh.write(f"\n{proc.stderr}")
+                fh.write(f"\n\nExit Code: {proc.returncode}\n")
+
+            return proc.returncode
+
+        except subprocess.TimeoutExpired:
+            with open(log_path, "a") as fh:
+                fh.write("\n\nERROR: Command timed out\n")
+            return 124
+        except FileNotFoundError:
+            with open(log_path, "w") as fh:
+                fh.write(f"ERROR: {cmd[0]} not found in PATH\n")
+            return 127
+        except Exception as e:
+            with open(log_path, "a") as fh:
+                fh.write(f"\n\nERROR: {e}\n")
+            return 1
+
+
+plugin = ToolNamePlugin()
+```
+
+**Key Points:**
+- Plugin is auto-discovered by `souleyez/engine/loader.py` via `pkgutil.iter_modules()`
+- Must have a `plugin` attribute at module level
+- The `tool` attribute should match the CLI command name
+
+---
+
+## Step 2: Create the Handler
+
+**File:** `souleyez/handlers/<tool_name>_handler.py`
+
+The handler parses tool output and displays results.
+
+```python
+#!/usr/bin/env python3
+"""
+Handler for <tool_name>.
+"""
+import logging
+import os
+import re
+from typing import Any, Dict, Optional
+
+import click
+
+from souleyez.handlers.base import BaseToolHandler
+
+logger = logging.getLogger(__name__)
+
+STATUS_DONE = 'done'
+STATUS_ERROR = 'error'
+STATUS_WARNING = 'warning'
+STATUS_NO_RESULTS = 'no_results'
+
+
+class ToolNameHandler(BaseToolHandler):
+    """Handler for tool_name."""
+
+    tool_name = "tool_name"  # Must match plugin's tool attribute
+    display_name = "Tool Display Name"
+
+    # Enable the handlers you implement
+    has_error_handler = True
+    has_warning_handler = True
+    has_no_results_handler = True
+    has_done_handler = True
+
+    # Regex patterns for parsing output
+    RESULT_PATTERN = r'RESULT:\s*(\S+)'
+    ERROR_PATTERNS = [
+        (r'connection refused', 'Connection refused'),
+        (r'timeout', 'Connection timed out'),
+    ]
+
+    def parse_job(
+        self,
+        engagement_id: int,
+        log_path: str,
+        job: Dict[str, Any],
+        host_manager: Optional[Any] = None,
+        findings_manager: Optional[Any] = None,
+        credentials_manager: Optional[Any] = None,
+    ) -> Dict[str, Any]:
+        """Parse tool results from log file."""
+        try:
+            target = job.get('target', '')
+
+            if not log_path or not os.path.exists(log_path):
+                return {
+                    'tool': self.tool_name,
+                    'status': STATUS_ERROR,
+                    'error': 'Log file not found'
+                }
+
+            with open(log_path, 'r', encoding='utf-8', errors='replace') as f:
+                log_content = f.read()
+
+            # Check for errors first
+            for pattern, error_msg in self.ERROR_PATTERNS:
+                if re.search(pattern, log_content, re.IGNORECASE):
+                    return {
+                        'tool': self.tool_name,
+                        'status': STATUS_ERROR,
+                        'target': target,
+                        'error': error_msg
+                    }
+
+            # Parse results
+            results = re.findall(self.RESULT_PATTERN, log_content)
+
+            if results:
+                # Store findings/credentials if applicable
+                # Example: Store credentials
+                # if credentials_manager and host_manager:
+                #     host = host_manager.get_host_by_ip(engagement_id, target)
+                #     if host:
+                #         credentials_manager.add_credential(...)
+
+                return {
+                    'tool': self.tool_name,
+                    'status': STATUS_DONE,
+                    'target': target,
+                    'results': results,
+                    'results_found': len(results),
+                    # Add counts for job summary display:
+                    # 'users_found': len(users),
+                    # 'credentials_added': len(credentials),
+                    # 'hosts_added': len(hosts),
+                    # 'findings_added': len(findings),
+                }
+
+            return {
+                'tool': self.tool_name,
+                'status': STATUS_NO_RESULTS,
+                'target': target
+            }
+
+        except Exception as e:
+            logger.error(f"Error parsing {self.tool_name} job: {e}")
+            return {'tool': self.tool_name, 'status': STATUS_ERROR, 'error': str(e)}
+
+    def display_done(
+        self,
+        job: Dict[str, Any],
+        log_path: str,
+        show_all: bool = False,
+        show_passwords: bool = False,
+    ) -> None:
+        """Display successful results."""
+        click.echo()
+        click.echo(click.style("=" * 70, fg='green'))
+        click.echo(click.style(f"{self.display_name.upper()} SUCCESSFUL", fg='green', bold=True))
+        click.echo(click.style("=" * 70, fg='green'))
+        click.echo()
+
+        # Parse and display results from log
+        try:
+            with open(log_path, 'r', encoding='utf-8', errors='replace') as f:
+                log_content = f.read()
+
+            results = re.findall(self.RESULT_PATTERN, log_content)
+            if results:
+                click.echo(click.style(f"  RESULTS ({len(results)})", bold=True, fg='cyan'))
+                for result in results:
+                    click.echo(f"    {click.style(result, fg='green')}")
+        except Exception as e:
+            click.echo(f"  Error reading log: {e}")
+
+        click.echo()
+
+    def display_error(
+        self,
+        job: Dict[str, Any],
+        log_path: str,
+        show_all: bool = False,
+    ) -> None:
+        """Display error results."""
+        click.echo()
+        click.echo(click.style("=" * 70, fg='red'))
+        click.echo(click.style(f"{self.display_name.upper()} FAILED", fg='red', bold=True))
+        click.echo(click.style("=" * 70, fg='red'))
+        click.echo()
+
+        try:
+            with open(log_path, 'r', encoding='utf-8', errors='replace') as f:
+                log_content = f.read()
+
+            for pattern, error_msg in self.ERROR_PATTERNS:
+                if re.search(pattern, log_content, re.IGNORECASE):
+                    click.echo(f"  Error: {error_msg}")
+                    break
+            else:
+                click.echo(f"  {self.display_name} failed - check log for details")
+        except Exception:
+            click.echo("  Could not read error details")
+
+        click.echo()
+
+    def display_warning(
+        self,
+        job: Dict[str, Any],
+        log_path: str,
+        show_all: bool = False,
+    ) -> None:
+        """Display warning results."""
+        click.echo()
+        click.echo(click.style("=" * 70, fg='yellow'))
+        click.echo(click.style(f"{self.display_name.upper()} - PARTIAL RESULTS", fg='yellow', bold=True))
+        click.echo(click.style("=" * 70, fg='yellow'))
+        click.echo()
+        click.echo("  Completed with warnings")
+        click.echo()
+
+    def display_no_results(
+        self,
+        job: Dict[str, Any],
+        log_path: str,
+        show_all: bool = False,
+    ) -> None:
+        """Display no results message."""
+        click.echo()
+        click.echo(click.style("=" * 70, fg='yellow'))
+        click.echo(click.style(f"{self.display_name.upper()} - NO RESULTS", fg='yellow', bold=True))
+        click.echo(click.style("=" * 70, fg='yellow'))
+        click.echo()
+        click.echo("  No results found.")
+        click.echo()
+```
+
+**Key Points:**
+- `tool_name` must match the plugin's `tool` attribute
+- Return dict must include standard fields for job summary display:
+  - `users_found`, `credentials_added`, `hosts_added`, `findings_added`, `shares_found`
+- The `display_*` methods are called when viewing job details
+
+---
+
+## Step 3: Register Handler in Registry
+
+**File:** `souleyez/handlers/registry.py`
+
+Add import in the `_discover_handlers()` method:
+
+```python
+try:
+    from souleyez.handlers import tool_name_handler  # noqa: F401
+except ImportError as e:
+    logger.warning(f"Failed to import tool_name_handler: {e}")
+```
+
+---
+
+## Step 4: Add to Tool Checker
+
+**File:** `souleyez/utils/tool_checker.py`
+
+Add to the appropriate category in `EXTERNAL_TOOLS`:
+
+```python
+EXTERNAL_TOOLS = {
+    # ... existing categories ...
+    'category_name': {
+        # ... existing tools ...
+        'tool_name': {
+            'command': 'tool_command',  # CLI command to check
+            'install_kali': 'sudo apt install tool-package',
+            'install_ubuntu': 'go install github.com/author/tool@latest',
+            'install_method': 'apt',  # apt, go, pipx, gem, manual
+            'description': 'Brief description for setup wizard'
+        },
+    },
+}
+```
+
+**Categories:**
+- `prerequisites` - Required system tools
+- `reconnaissance` - OSINT and info gathering
+- `web_scanning` - Web vulnerability scanning
+- `exploitation` - Active exploitation
+- `credential_attacks` - Password attacks
+- `windows_ad` - Windows/Active Directory
+- `router_iot` - Router and IoT testing
+- `remote_access` - Remote access tools
+
+---
+
+## Step 5: Add to Interactive UI Menu
+
+**File:** `souleyez/ui/interactive.py`
+
+### 5.1 Add to Phase Subsection
+
+Find the appropriate phase and add to its subsection tools list:
+
+```python
+PHASES = [
+    # ...
+    {
+        "name": "PHASE 5: POST-EXPLOITATION",
+        # ...
+        "subsections": [
+            {
+                "title": "Credential Harvesting",
+                "tools": [
+                    "tool_name",  # Add here
+                    "existing_tool",
+                ],
+            },
+        ],
+    },
+]
+```
+
+### 5.2 Add Description
+
+Add to `desc_map`:
+
+```python
+desc_map = {
+    # ...
+    "tool_name": "Brief description shown in menu",
+}
+```
+
+### 5.3 Add Display Name
+
+Add to `name_map` inside `get_display_name()`:
+
+```python
+name_map = {
+    # ...
+    "tool_name": "DisplayName",
+}
+```
+
+---
+
+## Step 6: Add Chain Rules (Optional)
+
+**File:** `souleyez/core/tool_chaining.py`
+
+If the tool should be triggered automatically based on other scan results:
+
+```python
+CHAIN_RULES = [
+    # ...
+    {
+        'id': NEXT_ID,
+        'name': 'Descriptive Chain Name',
+        'trigger_tool': 'previous_tool',
+        'trigger_status': 'done',
+        'condition': lambda job, parse: (
+            parse.get('some_condition') and
+            other_condition
+        ),
+        'action_tool': 'tool_name',
+        'action_args': ['arg1', '{placeholder}', '<target>'],
+        'description': 'When to trigger this chain',
+        'category': 'category_name',
+    },
+]
+```
+
+**Placeholders:**
+- `<target>` - Target IP/hostname
+- `{domain}` - Discovered domain name
+- `{base_dn}` - LDAP base DN
+- `{username}` - Username from credentials
+- `{password}` - Password from credentials
+
+---
+
+## Step 7: Test the Integration
+
+```bash
+# Test plugin discovery
+python3 -c "
+from souleyez.engine.loader import discover_plugins
+plugins = discover_plugins()
+print('tool_name' in plugins)
+print(plugins.get('tool_name'))
+"
+
+# Test handler registration
+python3 -c "
+from souleyez.handlers.registry import get_handler
+handler = get_handler('tool_name')
+print(handler)
+print(handler.has_done_handler if handler else 'NOT REGISTERED')
+"
+
+# Test tool checker
+python3 -c "
+from souleyez.utils.tool_checker import EXTERNAL_TOOLS
+for cat, tools in EXTERNAL_TOOLS.items():
+    if 'tool_name' in tools:
+        print(f'Found in {cat}')
+        print(tools['tool_name'])
+"
+
+# Run the tool manually
+souleyez jobs enqueue tool_name <target> --args "test args"
+souleyez jobs list
+```
+
+---
+
+## Step 8: Commit and Push
+
+```bash
+git add souleyez/plugins/tool_name.py
+git add souleyez/handlers/tool_name_handler.py
+git add souleyez/handlers/registry.py
+git add souleyez/utils/tool_checker.py
+git add souleyez/ui/interactive.py
+git add souleyez/core/tool_chaining.py  # If chain rules added
+
+git commit -m "feat: add tool_name plugin for <purpose>"
+git push
+```
+
+---
+
+## Common Mistakes to Avoid
+
+1. **Forgetting to register handler** - Tool works but results aren't parsed
+2. **Missing from tool_checker** - Won't appear in `souleyez setup` wizard
+3. **Missing from UI menu** - Users can't find the tool
+4. **Wrong tool_name in handler** - Handler won't be matched to jobs
+5. **Missing count fields in parse_job return** - Job summary won't show results
+6. **Not testing chain rules** - Automation won't trigger
+
+---
+
+## Files Modified When Adding a Tool
+
+| File | Purpose |
+|------|---------|
+| `souleyez/plugins/<tool>.py` | Plugin (command building, execution) |
+| `souleyez/handlers/<tool>_handler.py` | Handler (parsing, display) |
+| `souleyez/handlers/registry.py` | Handler registration |
+| `souleyez/utils/tool_checker.py` | Installation instructions |
+| `souleyez/ui/interactive.py` | UI menu entry |
+| `souleyez/core/tool_chaining.py` | Auto-chain rules (optional) |

souleyez/docs/user-guide/auto-chaining.md

@@ -36,9 +36,11 @@ Auto-chaining uses **trigger conditions** and **chain rules** to automatically l
 ```
 Port Scan (nmap)
   → Discovers HTTP on port 80
-    → Auto-chains to nikto + gobuster
-      → nikto finds admin panel
-        → Auto-chains to hydra (brute force)
+    → Auto-chains to http_fingerprint (WAF/CDN detection)
+      → http_fingerprint completes
+        → Auto-chains to nikto + gobuster + nuclei
+          → nikto finds admin panel
+            → Auto-chains to hydra (brute force)
 ```
 
 ---
@@ -55,6 +57,7 @@ Each rule contains:
 - **Target Tool** - Tool to run next (e.g., `nikto`, `gobuster`)
 - **Priority** - Execution order (1-10, higher runs first)
 - **Args Template** - Arguments to pass to target tool
+- **Target Format** - How the target should be formatted (`ip`, `url`, or `host:port`)
 
 ### Understanding Priority
 
@@ -104,8 +107,10 @@ All 5 jobs run, but crackmapexec starts first (priority 10) and hydra starts las
 
 | Trigger | Condition | Target Tool | Purpose |
 |---------|-----------|-------------|---------|
-| nmap | `service:http` | nikto | Web vulnerability scanning |
-| nmap | `service:http` | gobuster | Directory/file enumeration |
+| nmap | `service:http` | http_fingerprint | WAF/CDN/platform detection (runs first) |
+| http_fingerprint | `has:services` | nikto | Web vulnerability scanning |
+| http_fingerprint | `has:services` | gobuster | Directory/file enumeration |
+| http_fingerprint | `has:services` | nuclei | CVE and misconfiguration scanning |
 | nmap | `service:https` | sslscan | SSL/TLS configuration testing |
 
 #### Windows/SMB Chains
@@ -400,14 +405,18 @@ Pending chains are stored in `data/chains/pending.json`:
 
 ```
 1. nmap discovers HTTP/HTTPS
+   └─→ http_fingerprint (WAF/CDN/platform detection)
+
+2. http_fingerprint completes
    ├─→ nikto (vulnerability scan)
    ├─→ gobuster (directory brute force)
+   ├─→ nuclei (CVE scanning)
    └─→ sslscan (if HTTPS)
 
-2. gobuster finds /admin, /api
+3. gobuster finds /admin, /api
    └─→ hydra (login brute force)
 
-3. Form detected with SQL parameter
+4. Form detected with SQL parameter
    └─→ sqlmap (SQL injection testing)
 ```
 
@@ -527,6 +536,7 @@ ChainRule(
 
 Available placeholders in `args_template`:
 - `{target}` - IP address or hostname
+- `{target_url}` - Full URL with scheme and port (e.g., `http://192.168.1.1:8080`)
 - `{port}` - Port number from trigger
 - `{service}` - Service name
 - `{nuclei_tags}` - Auto-detected technology tags for Nuclei (see below)
@@ -534,6 +544,18 @@ Available placeholders in `args_template`:
 - `{dc_ip}` - Domain controller IP
 - `{subnet}` - /24 subnet of target (e.g., 10.0.0.0/24)
 
+### Target Format
+
+The `target_format` field controls how the target is passed to chained tools:
+
+| Format | Example | Use Case |
+|--------|---------|----------|
+| `ip` (default) | `192.168.1.1` | Most tools (crackmapexec, nmap, etc.) |
+| `url` | `http://192.168.1.1:8080` | Web tools (gobuster, nuclei, nikto) |
+| `host:port` | `192.168.1.1:445` | Tools needing explicit port |
+
+**Example:** When http_fingerprint triggers gobuster, the rule has `target_format=url` so gobuster receives the full URL (e.g., `http://192.168.1.1:8080`) instead of just the IP.
+
 ### Smart Scanning Features
 
 #### Tech-Based Template Selection (Nuclei)
@@ -672,4 +694,4 @@ Auto-chaining can launch many parallel jobs:
 
 ---
 
-**Last Updated:** 2025-12-27 | **Version:** 2.1.0
+**Last Updated:** 2026-01-18 | **Version:** 2.2.0

souleyez/docs/user-guide/getting-started.md

@@ -466,7 +466,7 @@ souleyez jobs enqueue nmap 192.168.1.100 -a "-sV -sC -p 80,443,22" -l "Service S
 souleyez jobs enqueue nikto http://192.168.1.100 -l "Nikto Scan"
 
 # 2. Directory enumeration
-souleyez jobs enqueue gobuster http://192.168.1.100 -a "dir -w /usr/share/wordlists/dirb/common.txt" -l "Dir Brute"
+souleyez jobs enqueue gobuster http://192.168.1.100 -a "dir -w data/wordlists/web_dirs_common.txt" -l "Dir Brute"
 
 # 3. SQL injection testing
 souleyez jobs enqueue sqlmap http://192.168.1.100/login.php?id=1 -l "SQLMap"

souleyez/docs/user-guide/installation.md

@@ -83,8 +83,8 @@ For developers who want to modify the source code:
 
 ```bash
 # Clone the repository
-git clone https://github.com/cyber-soul-security/souleyez.git
-cd souleyez
+git clone https://github.com/cyber-soul-security/SoulEyez.git
+cd SoulEyez
 
 # Install python3-venv if not already installed
 sudo apt install python3-venv
@@ -242,6 +242,29 @@ nuclei -version
 nuclei -update-templates
 ```
 
+### Web Crawling (Katana)
+
+**Katana** - Web crawler for parameter and endpoint discovery:
+
+Katana crawls web applications to discover URLs with parameters, forms, and JavaScript-rendered endpoints. It's essential for finding attack surface before running injection tests.
+
+> **Note**: Katana requires Chromium for headless browser mode (enabled by default).
+
+```bash
+# Install Go and Chromium first
+sudo apt install -y golang-go chromium
+
+# Install katana via Go
+go install github.com/projectdiscovery/katana/cmd/katana@latest
+
+# Add Go bin to PATH if not already done
+echo 'export PATH=$PATH:~/go/bin' >> ~/.zshrc   # Kali uses zsh
+source ~/.zshrc
+
+# Verify installation
+katana -version
+```
+
 ### Directory Bruteforcing
 
 **Gobuster** - Fast directory/file & DNS brute-forcer:
@@ -544,5 +567,5 @@ See [Uninstall Guide](uninstall.md) for more options.
 
 ## Support
 
-**Issues**: https://github.com/cyber-soul-security/souleyez/issues  
+**Issues**: https://github.com/cyber-soul-security/SoulEyez/issues  
 **Security Concerns**: See [SECURITY.md](../../SECURITY.md)