# SMB Prowl A portable SMB client using the aiosmb library with advanced share spidering capabilities. ## Features - **SMB Protocol Support**: Full SMB 2.0/3.0 support with authentication - **Interactive Mode**: Command-line interface with command history and autocompletion - **Share Spidering**: Recursive directory traversal with advanced filtering - **Multiple Search Patterns**: Support for multiple regex patterns simultaneously - **Threading & Performance**: Configurable threading for large-scale operations - **Image OCR Scanning**: Extract and search text from images using OCR - **Configuration Files**: YAML-based configuration for complex operations - **Export Formats**: JSON, CSV, and TXT export options - **OPSEC Mode**: Stealth operations to avoid noisy system access - **Error Handling**: Robust retry mechanisms and error recovery ## Installation ### Prerequisites ```bash # Install Python 3.8+ python3 --version # Install system dependencies for image processing (macOS) brew install tesseract # Install system dependencies for image processing (Ubuntu/Debian) sudo apt-get install tesseract-ocr # Install system dependencies for image processing (Windows) # Download and install Tesseract from: https://github.com/UB-Mannheim/tesseract/wiki ``` ### Python Setup ```bash # Clone the repository git clone cd smbprowl # Create virtual environment python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt # Install additional dependencies for enhanced features pip install pillow pytesseract pyyaml ``` ## Usage ### Basic Usage ```bash # Connect to SMB server python3 smb_prowl.py username:password@192.168.1.100 # List shares python3 smb_prowl.py -shares username:password@192.168.1.100 # Spider a share python3 smb_prowl.py -spider "C$" 3 username:password@192.168.1.100 ``` ### Enhanced Spider Operations #### Multiple Search Patterns ```bash # Search for multiple patterns simultaneously python3 smb_prowl.py -spider "C$" 5 -patterns "password" "secret" "admin" username:password@192.168.1.100 # Case-sensitive pattern matching python3 smb_prowl.py -spider "C$" 5 -patterns "Password" "Secret" -case-sensitive username:password@192.168.1.100 ``` #### Advanced Filtering ```bash # Exclude specific patterns and paths python3 smb_prowl.py -spider "C$" 5 -patterns "config" -exclude-patterns "*.tmp" "*.log" -exclude-paths "Windows\\System32" username:password@192.168.1.100 # Include only specific file types python3 smb_prowl.py -spider "C$" 5 -patterns "credential" -extensions .txt .ini .conf -min-size 1024 username:password@192.168.1.100 ``` #### Performance and Reliability ```bash # Configure threading and retry attempts python3 smb_prowl.py -spider "C$" 5 -patterns "password" -max-threads 20 -retry-attempts 5 username:password@192.168.1.100 # Enable image scanning for OCR text extraction python3 smb_prowl.py -spider "C$" 5 -patterns "password" -scan-images username:password@192.168.1.100 ``` #### Content Search ```bash # Search inside file contents (not just names) python3 smb_prowl.py -spider "C$" 5 -patterns "password" -search-contents username:password@192.168.1.100 # OPSEC mode for stealth operations python3 smb_prowl.py -spider "C$" 5 -patterns "secret" -opsec username:password@192.168.1.100 ``` ### Configuration Files SMB Prowl supports YAML configuration files for complex operations. This is especially useful for: - Repetitive operations - Complex filtering scenarios - Team collaboration - Automation workflows #### Minimal Configuration Example ```yaml # test_minimal.yaml target: "username:password@192.168.1.100" spider: share_name: "C$" max_depth: 3 patterns: ["password", "secret"] export: "json" search_contents: true opsec: true file_operations: shares: true ``` #### Comprehensive Configuration Example ```yaml # test_comprehensive.yaml target: "username:password@192.168.1.100" domain: "domain.local" port: "445" debug: true timestamp: true spider: share_name: "C$" max_depth: 5 patterns: ["password", "secret", "admin", "config", "credential"] export: "csv" # Advanced filtering exclude_patterns: ["*.tmp", "*.log", "*.bak"] include_patterns: ["*.txt", "*.ini", "*.conf", "*.xml"] exclude_paths: ["Windows\\System32", "Program Files", "temp"] include_paths: ["Users", "Documents", "Desktop"] # File filters extensions: [".txt", ".ini", ".conf", ".xml", ".bat", ".ps1"] min_size: 1024 max_size: 10485760 # 10MB # Behavior options show_hidden: false follow_symlinks: false case_sensitive: false search_contents: true opsec: true # Performance and reliability max_threads: 15 retry_attempts: 5 # Image scanning scan_images: true # Download options spider_download: true spider_download_path: "./downloads" file_operations: shares: true ls: "C$/Users/Administrator/Documents" download: remote: "C$/secret.txt" local: "./local_secret.txt" ``` #### Using Configuration Files ```bash # Use minimal configuration python3 smb_prowl.py -inputfile test_minimal.yaml # Use comprehensive configuration python3 smb_prowl.py -inputfile test_comprehensive.yaml # Override config file options with command line python3 smb_prowl.py -inputfile test_minimal.yaml -debug -ts ``` ### Interactive Mode Commands ```bash # Start interactive session python3 smb_prowl.py username:password@192.168.1.100 # Available commands: # shares - List available shares # ls [path] - List directory contents # upload - Upload file # download - Download file # delete - Delete file # mkdir - Create directory # rmdir - Remove directory # spider [pattern] - Basic spider # spider-advanced [options] - Advanced spider with filters # export - Export last spider results (json/csv/txt) # cache - Show cache status # clear-cache - Clear spider cache # history - Show command history # clear - Clear terminal screen # help - Show available commands # quit/exit - Exit client ``` ## Advanced Features ### Image OCR Scanning SMB Prowl can extract text from images using OCR (Optical Character Recognition) and search for patterns within the extracted text. **Requirements:** - `pillow` (PIL) for image processing - `pytesseract` for OCR functionality - System Tesseract installation **Usage:** ```bash # Enable image scanning during spider operations python3 smb_prowl.py -spider "C$" 5 -patterns "password" -scan-images username:password@192.168.1.100 ``` **Supported Image Formats:** - JPEG/JPG - PNG - BMP - TIFF - GIF (first frame) ### Threading and Performance For large-scale operations, SMB Prowl supports configurable threading: ```bash # Increase thread count for faster processing python3 smb_prowl.py -spider "C$" 5 -max-threads 20 username:password@192.168.1.100 # Configure retry attempts for reliability python3 smb_prowl.py -spider "C$" 5 -retry-attempts 5 username:password@192.168.1.100 ``` **Performance Considerations:** - Higher thread counts increase speed but may trigger security alerts - Balance between performance and stealth based on your OPSEC requirements - Monitor network and system resources during large operations ### OPSEC Mode Stealth mode that avoids potentially noisy operations: ```bash # Enable OPSEC mode python3 smb_prowl.py -spider "C$" 5 -opsec username:password@192.168.1.100 ``` **OPSEC Features:** - Skips Windows system directories (System32, SysWOW64, Program Files) - Avoids temporary and log directories - Filters out hidden and system files - Only accesses files the user context can read ## Export and Analysis ### Export Formats ```bash # JSON export (default) python3 smb_prowl.py -spider "C$" 5 -export json username:password@192.168.1.100 # CSV export for spreadsheet analysis python3 smb_prowl.py -spider "C$" 5 -export csv username:password@192.168.1.100 # Plain text export for quick review python3 smb_prowl.py -spider "C$" 5 -export txt username:password@192.168.1.100 ``` ### Result Analysis The tool provides comprehensive summaries including: - Total files and directories found - Pattern match counts - Excluded item counts - File size distributions - Depth analysis - Image text extraction results ## Error Handling and Reliability ### Retry Mechanisms - Configurable retry attempts for failed operations - Graceful degradation for inaccessible paths - Comprehensive error logging and reporting ### Connection Management - Automatic connection recovery - Timeout handling - Resource cleanup ## Security Considerations - **Authentication**: Supports NTLM, Kerberos, and hash-based authentication - **OPSEC**: Built-in stealth mode for sensitive operations - **Logging**: Configurable logging levels and output files - **Access Control**: Only accesses files within user permissions ## Troubleshooting ### Common Issues 1. **Connection Failures** - Verify network connectivity - Check firewall settings - Confirm SMB ports (139/445) are open 2. **Authentication Errors** - Verify credentials - Check domain membership - Ensure account has necessary permissions 3. **Image Processing Issues** - Install Tesseract OCR - Verify image file formats - Check file permissions 4. **Performance Issues** - Adjust thread count - Use appropriate depth limits - Enable caching for repeated operations ### Debug Mode ```bash # Enable debug output python3 smb_prowl.py -debug username:password@192.168.1.100 # Add timestamps to output python3 smb_prowl.py -ts username:password@192.168.1.100 # Log to file python3 smb_prowl.py -outputfile smb.log username:password@192.168.1.100 ``` ## Compilation with PyInstaller ### Build Process ```bash # Install PyInstaller pip install pyinstaller # Build standalone executable pyinstaller --onefile smb_prowl.py # Build with additional data files pyinstaller --onefile --add-data "templates:templates" smb_prowl.py ``` ### Build Script Use the provided `build.sh` script for automated builds: ```bash # Make executable and run chmod +x build.sh ./build.sh ``` ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## License This project is licensed under the MIT License - see the LICENSE file for details. ## Disclaimer This tool is designed for legitimate security testing and research purposes only. Users are responsible for ensuring they have proper authorization before testing any systems. The authors are not responsible for any misuse of this tool.