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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

# 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:

# 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:

# 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

# 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

Connection Failures
- Verify network connectivity
- Check firewall settings
- Confirm SMB ports (139/445) are open
Authentication Errors
- Verify credentials
- Check domain membership
- Ensure account has necessary permissions
Image Processing Issues
- Install Tesseract OCR
- Verify image file formats
- Check file permissions
Performance Issues
- Adjust thread count
- Use appropriate depth limits
- Enable caching for repeated operations

Debug Mode

# 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

# 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:

# Make executable and run
chmod +x build.sh
./build.sh

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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.