git-adm/smbprowl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4429d07aab7c389ceb28b2a40706ce4e3fe2831c
smbprowl/README.md
Warezpeddler 4429d07aab Initial code commit
2026-01-28 23:57:28 +00:00

10 KiB
Raw Blame History

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

# 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

  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

# 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

  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.

Reference in New Issue View Git Blame Copy Permalink