Initial code commit

.gitignore

@@ -0,0 +1,115 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+*.whl
+
+# Virtual Environment
+venv/
+env/
+ENV/
+.venv/
+
+# PyInstaller
+*.spec
+!smb_prowl.spec
+*.manifest
+
+# Testing
+test_*.py
+*_test.py
+test_*.yaml
+test_*.yml
+test_*.png
+test_*.jpg
+test_*.jpeg
+test_*.gif
+*.log
+*.tmp
+
+# Checkpoint and backup files
+*_checkpoint.*
+*.bak
+*.backup
+*.swp
+*.swo
+*~
+
+# OS-specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+desktop.ini
+
+# IDE and editor files
+.vscode/
+.idea/
+*.sublime-project
+*.sublime-workspace
+*.code-workspace
+*.iml
+
+# Secrets and credentials
+*.key
+*.pem
+*.p12
+*.pfx
+*.crt
+*.cert
+*.secret
+.env
+.env.local
+.env.*.local
+secrets.yaml
+secrets.yml
+config.local.*
+*credentials*
+*password*
+*secret*
+
+# Logs and output files
+*.log
+*.out
+smb_prowl*.log
+downloads/
+downloads_*/
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+*.temp
+
+# Coverage reports
+.coverage
+htmlcov/
+.pytest_cache/
+.tox/
+.hypothesis/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Project-specific
+hooks/__pycache__/

README.md

@@ -1,3 +1,397 @@
-# smbprowl
+# 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 <repository-url>
+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 <local> <remote> - Upload file
+# download <remote> <local> - Download file
+# delete <path> - Delete file
+# mkdir <path> - Create directory
+# rmdir <path> - Remove directory
+# spider <share> <depth> [pattern] - Basic spider
+# spider-advanced <share> <depth> [options] - Advanced spider with filters
+# export <format> - 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.

build.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+echo "Building SMB Prowl PyInstaller executable..."
+
+# Clean previous builds (preserve smb_prowl.spec if it exists)
+rm -rf build dist
+# Only remove auto-generated spec files, not the template
+find . -maxdepth 1 -name "*.spec" ! -name "smb_prowl.spec" -delete 2>/dev/null || true
+
+# Use the virtual environment's Python directly
+if [ -d "venv" ]; then
+    echo "Using virtual environment Python: ./venv/bin/python3"
+    PYTHON_CMD="./venv/bin/python3"
+else
+    echo "No virtual environment found, using system Python"
+    PYTHON_CMD="python3"
+fi
+
+# Build executable using the specified Python
+$PYTHON_CMD -m PyInstaller --onefile --clean --additional-hooks-dir=hooks smb_prowl.py
+
+echo "Build complete! Executable is in dist/smb_prowl"

hooks/hook-aiosmb.py

@@ -0,0 +1,24 @@
+# PyInstaller hook for aiosmb
+from PyInstaller.utils.hooks import collect_data_files, collect_submodules
+
+# Collect all submodules
+hiddenimports = collect_submodules('aiosmb')
+
+# Add specific imports that might be missed
+hiddenimports += [
+    'aiosmb.commons.connection.factory',
+    'aiosmb.commons.interfaces.machine',
+    'aiosmb.commons.interfaces.share',
+    'aiosmb.commons.interfaces.file',
+    'aiosmb.commons.interfaces.directory',
+    'aiosmb.connection',
+    'aiosmb.protocol.smb2',
+    'aiosmb.protocol.smb2.messages',
+    'aiosmb.protocol.smb2.commands',
+    'aiosmb.protocol.smb2.structures',
+    'aiosmb.dcerpc',
+    'aiosmb.external',
+]
+
+# Collect data files if any
+datas = collect_data_files('aiosmb')

hooks/hook-asyauth.py

@@ -0,0 +1,19 @@
+# PyInstaller hook for asyauth
+from PyInstaller.utils.hooks import collect_data_files, collect_submodules
+
+# Collect all submodules
+hiddenimports = collect_submodules('asyauth')
+
+# Add specific imports that might be missed
+hiddenimports += [
+    'asyauth.protocols.ntlm',
+    'asyauth.protocols.kerberos',
+    'asyauth.protocols.spnego',
+    'asyauth.protocols.credssp',
+    'asyauth.protocols.spnegoex',
+    'asyauth.common',
+    'asyauth.utils',
+]
+
+# Collect data files if any
+datas = collect_data_files('asyauth')

hooks/hook-unicrypto.py

@@ -0,0 +1,19 @@
+# PyInstaller hook for unicrypto
+from PyInstaller.utils.hooks import collect_data_files, collect_submodules
+
+# Collect all submodules
+hiddenimports = collect_submodules('unicrypto')
+
+# Add specific imports that might be missed
+hiddenimports += [
+    'unicrypto.backends.pycryptodomex',
+    'unicrypto.backends.pycryptodome',
+    'unicrypto.backends.oscrypto',
+    'unicrypto.symmetric',
+    'unicrypto.asymmetric',
+    'unicrypto.hashlib',
+    'unicrypto.random',
+]
+
+# Collect data files if any
+datas = collect_data_files('unicrypto')

requirements.txt

@@ -0,0 +1,35 @@
+# Core SMB functionality
+aiosmb>=0.1.0
+
+# Enhanced features
+pillow>=10.0.0
+pytesseract>=0.3.10
+pyyaml>=6.0
+
+# Office document processing
+python-docx>=0.8.11
+openpyxl>=3.1.0
+python-pptx>=0.6.21
+
+# Archive handling
+rarfile>=4.0
+py7zr>=0.20.0
+
+# Standard library dependencies (usually included with Python)
+# asyncio
+# argparse
+# logging
+# pathlib
+# datetime
+# typing
+# json
+# csv
+# re
+# os
+# sys
+# tempfile
+# subprocess
+# shutil
+# threading
+# time
+# concurrent.futures

smb_prowl.spec

@@ -0,0 +1,38 @@
+# -*- mode: python ; coding: utf-8 -*-
+
+
+a = Analysis(
+    ['smb_prowl.py'],
+    pathex=[],
+    binaries=[],
+    datas=[],
+    hiddenimports=[],
+    hookspath=['hooks'],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    noarchive=False,
+    optimize=0,
+)
+pyz = PYZ(a.pure)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    a.binaries,
+    a.datas,
+    [],
+    name='smb_prowl',
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    runtime_tmpdir=None,
+    console=True,
+    disable_windowed_traceback=False,
+    argv_emulation=False,
+    target_arch=None,
+    codesign_identity=None,
+    entitlements_file=None,
+)