EyeWitness is designed to take screenshots of websites, provide server header info, and identify default credentials if known. Now powered by Chromium browser for better reliability and easier installation.
- Cross-platform support - Windows, Linux, and macOS
- Chromium-powered - Reliable headless screenshots with Google Chrome/Chromium
- Adaptive resource management - Automatically adjusts to system capabilities
- Configuration file support - Save your preferred settings
- URL validation - Pre-flight checks to ensure URLs are valid
- Progress tracking with ETA - Know exactly when your scan will complete
- Enhanced error handling - Specific error types with actionable guidance
- Multiple input formats - Text files, Nmap XML, Nessus XML
- Isolated virtual environment - Zero system conflicts and PEP 668 bypass
EyeWitness now uses Python virtual environments for all installations, providing:
- No system conflicts - All Python packages installed in isolated environment
- No PEP 668 issues - Completely bypasses "externally-managed-environment" errors on Kali/modern Linux
- Cross-platform consistency - Same approach on Windows, Linux, and macOS
- Easy cleanup - Delete
eyewitness-venv/directory to remove everything - Production ready - Automatic error handling and rollback on failures
- Setup creates virtual environment -
eyewitness-venv/directory with isolated Python - Activate the virtual environment - Simple command to enter the isolated environment
- All packages installed in isolation - Zero impact on your system Python
- Run EyeWitness normally - Standard Python commands work within the virtual environment
EyeWitness/
├── eyewitness-venv/ # 🔒 Virtual environment (isolated Python packages)
│ ├── bin/activate # Linux/macOS activation script
│ └── Scripts/activate.bat # Windows activation script
├── Python/
│ └── EyeWitness.py # 📜 Main script (runs in virtual environment)
└── setup/ # Setup scripts and requirements
🔥 NEW: EyeWitness now uses Python virtual environments for zero conflicts and bulletproof installation across all platforms!
Note: Docker support is currently in development. Please use native installation options below for now.
Automated setup with Python virtual environment:
# 1. Open PowerShell as Administrator
# 2. Navigate to EyeWitness directory
cd path\to\EyeWitness\setup
# 3. Run the setup script (creates virtual environment)
.\setup.ps1
# 4. Test installation by activating virtual environment
cd ..
eyewitness-venv\Scripts\activate.bat
python Python\EyeWitness.py --single https://example.comWhat gets installed:
- 🔒 Isolated Python virtual environment (eyewitness-venv/)
- Python dependencies in virtual environment (selenium, etc.)
- Google Chrome browser (if not present)
- ChromeDriver for automation
Production-ready setup with Python virtual environment:
# 1. Navigate to setup directory
cd EyeWitness/setup
# 2. Run the setup script (creates virtual environment)
sudo ./setup.sh
# 3. Test installation by activating virtual environment
cd ..
source eyewitness-venv/bin/activate
python Python/EyeWitness.py --single https://example.comWhat gets installed:
- 🔒 Isolated Python virtual environment (eyewitness-venv/)
- All Python packages in virtual environment (completely bypasses PEP 668)
- Chromium browser and ChromeDriver via system packages
- Virtual display support (xvfb)
🎯 Benefits:
- ✅ No PEP 668 conflicts - Virtual environment bypasses all restrictions
- ✅ No system package issues - All Python deps isolated
- ✅ Easy cleanup - Just delete eyewitness-venv/ directory
- ✅ Production ready - Automatic rollback on installation failures
Supported Linux Distributions:
- Ubuntu 20.04+ / Linux Mint
- Debian 10+ / Kali Linux
- CentOS 8+ / RHEL / Rocky Linux
- Arch Linux / Manjaro
- Alpine Linux
Homebrew-based setup with Python virtual environment:
# 1. Install Chrome via Homebrew
brew install --cask google-chrome
# 2. Navigate to setup directory and run setup
cd EyeWitness/setup
sudo ./setup.sh
# 3. Test installation by activating virtual environment
cd ..
source eyewitness-venv/bin/activate
python Python/EyeWitness.py --single https://example.comWhat gets installed:
- 🔒 Isolated Python virtual environment (eyewitness-venv/)
- Python dependencies in virtual environment
- Chrome browser (via Homebrew)
- ChromeDriver for automation
After running the setup script, activate the virtual environment and run EyeWitness:
🐧 Linux/macOS:
# 1. Activate the virtual environment
source eyewitness-venv/bin/activate
# 2. Run EyeWitness (you're now in the isolated environment)
python Python/EyeWitness.py --single https://example.com
python Python/EyeWitness.py -f urls.txt
python Python/EyeWitness.py -x nmap_scan.xml
python Python/EyeWitness.py -f urls.txt -d /path/to/output
# 3. When finished, deactivate the virtual environment
deactivate🪟 Windows:
# 1. Activate the virtual environment
eyewitness-venv\Scripts\activate.bat
# 2. Run EyeWitness (you're now in the isolated environment)
python Python\EyeWitness.py --single https://example.com
python Python\EyeWitness.py -f urls.txt
python Python\EyeWitness.py -x nmap_scan.xml
python Python\EyeWitness.py -f urls.txt -d C:\path\to\output
# 3. When finished, deactivate the virtual environment
deactivate# Activate virtual environment first
source eyewitness-venv/bin/activate # Linux/macOS
eyewitness-venv\Scripts\activate.bat # Windows
# Create a sample config file
python Python/EyeWitness.py --create-config
# Use a config file
python Python/EyeWitness.py -f urls.txt --config ~/.eyewitness/config.json# Activate virtual environment first
source eyewitness-venv/bin/activate # Linux/macOS
eyewitness-venv\Scripts\activate.bat # Windows
# Validate URLs without taking screenshots
python Python/EyeWitness.py -f urls.txt --validate-urls
# Skip validation (use with caution)
python Python/EyeWitness.py -f urls.txt --skip-validation# Activate virtual environment first
source eyewitness-venv/bin/activate # Linux/macOS
eyewitness-venv\Scripts\activate.bat # Windows
# Adjust threads based on your system (default: auto-detected)
python Python/EyeWitness.py -f urls.txt --threads 5
# Increase timeout for slow connections
python Python/EyeWitness.py -f urls.txt --timeout 30
# Add delays and jitter
python Python/EyeWitness.py -f urls.txt --delay 2 --jitter 5
# Use proxy
python Python/EyeWitness.py -f urls.txt --proxy-ip 127.0.0.1 --proxy-port 8080
# Custom output directory
python Python/EyeWitness.py -f urls.txt -d /path/to/output
# Resume a previous scan
python Python/EyeWitness.py --resume /path/to/output/ew.dbEyeWitness automatically detects your system resources and adjusts accordingly:
- Thread count based on CPU cores (2 × cores, max 20)
- Memory monitoring to prevent system overload
- Disk space checks before starting
Create a config file to save your preferred settings:
{
"threads": 10,
"timeout": 30,
"delay": 0,
"jitter": 0,
"user_agent": "Custom User Agent",
"proxy_ip": "127.0.0.1",
"proxy_port": 8080,
"output_dir": "./sessions",
"prepend_https": false,
"show_selenium": false,
"resolve": false,
"skip_validation": false,
"results_per_page": 25,
"max_retries": 2
}Chromium/ChromeDriver not found:
- All platforms: Re-run the setup script - it installs browsers automatically
- Linux:
sudo ./setup.shin setup/ directory - Windows:
.\setup.ps1as Administrator in setup\ directory - macOS:
sudo ./setup.shin setup/ directory (afterbrew install --cask google-chrome)
Virtual environment issues:
- Delete eyewitness-venv/ directory and re-run setup script
- Ensure Python 3.7+ is installed with venv module support
- Check that you ran setup script with proper Administrator/root privileges
Connection timeouts:
- Increase timeout:
--timeout 60 - Check firewall settings
- Verify target is accessible
High memory usage:
- Reduce threads:
--threads 5 - Process URLs in smaller batches
- Close other applications
Permission errors:
- Linux/macOS: Check file permissions
- Windows: Run as Administrator if needed
All errors now include specific troubleshooting steps. For example:
- Timeout errors suggest proxy settings and timeout increases
- Connection errors provide firewall and network checks
- Resource errors show memory usage and recommendations
EyeWitness generates:
report.html- Main report with screenshotsscreens/- Screenshot imagessource/- Page source codeew.db- SQLite database for resume capability
- Categorized results (High Value, CMS, Network Devices, etc.)
- Default credential detection
- Header analysis
- Searchable and sortable
- Python 3.7+ with
venvmodule support (standard in most Python installations) - Administrator/root privileges for installation (system packages and virtual environment creation)
- Internet connection for package downloads
- Chromium/Chrome browser (automatically installed by setup script)
- ChromeDriver (automatically installed by setup script)
📝 Note: The setup script handles all dependencies automatically. You just need Python 3.7+ and admin privileges.
This fork includes significant modernization:
- Fixed deprecated Selenium APIs
- Replaced archived dependencies (fuzzywuzzy → rapidfuzz)
- Added comprehensive error handling
- Improved cross-platform support
- Added resource monitoring
- Docker support in development
- Added configuration file support
- Enhanced user experience
E-Mail: GetOffensive [@] redsiege [dot] com
EyeWitness is licensed under the GNU General Public License v3.0.
