Phillip Tarrant
61cc24f8d2
Implements automated screenshot capture for all discovered HTTP/HTTPS services using Playwright with headless Chromium. Screenshots are saved as PNG files and referenced in JSON reports. Features: - Separate ScreenshotCapture module for code organization - Viewport screenshots (1280x720) with 15-second timeout - Graceful handling of self-signed certificates - Browser reuse for optimal performance - Screenshots stored in timestamped directories - Comprehensive documentation in README.md and new CLAUDE.md Technical changes: - Added src/screenshot_capture.py: Screenshot capture module with context manager pattern - Updated src/scanner.py: Integrated screenshot capture into HTTP/HTTPS analysis phase - Updated Dockerfile: Added Chromium and Playwright browser installation - Updated requirements.txt: Added playwright==1.40.0 - Added CLAUDE.md: Developer documentation and implementation guide - Updated README.md: Enhanced features section, added screenshot details and troubleshooting - Updated .gitignore: Ignore entire output/ directory including screenshots 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
311 lines
11 KiB
Markdown
311 lines
11 KiB
Markdown
# SneakyScanner
|
|
|
|
A dockerized network scanning tool that uses masscan for fast port discovery, nmap for service detection, and Playwright for webpage screenshots to perform comprehensive infrastructure audits. SneakyScanner accepts YAML-based configuration files to define sites, IPs, and expected network behavior, then generates machine-readable JSON reports with detailed service information and webpage screenshots.
|
|
|
|
## Features
|
|
|
|
### Network Discovery & Port Scanning
|
|
- **YAML-based configuration** for defining scan targets and expectations
|
|
- **Comprehensive scanning using masscan**:
|
|
- Ping/ICMP echo detection (masscan --ping)
|
|
- TCP port scanning (all 65535 ports at 10,000 pps)
|
|
- UDP port scanning (all 65535 ports at 10,000 pps)
|
|
- Fast network-wide discovery in seconds
|
|
|
|
### Service Detection & Enumeration
|
|
- **Service detection using nmap**:
|
|
- Identifies services running on discovered TCP ports
|
|
- Extracts product names and versions (e.g., "OpenSSH 8.2p1", "nginx 1.18.0")
|
|
- Provides detailed service information including extra attributes
|
|
- Balanced intensity level (5) for accuracy and speed
|
|
|
|
### Security Assessment
|
|
- **HTTP/HTTPS analysis and SSL/TLS security assessment**:
|
|
- Detects HTTP vs HTTPS on web services
|
|
- Extracts SSL certificate details (subject, issuer, expiration, SANs)
|
|
- Calculates days until certificate expiration for monitoring
|
|
- Tests TLS version support (TLS 1.0, 1.1, 1.2, 1.3)
|
|
- Lists all accepted cipher suites for each supported TLS version
|
|
- Identifies weak cryptographic configurations
|
|
|
|
### Visual Documentation
|
|
- **Webpage screenshot capture** (NEW):
|
|
- Automatically captures screenshots of all discovered web services (HTTP/HTTPS)
|
|
- Uses Playwright with headless Chromium browser
|
|
- Viewport screenshots (1280x720) for consistent sizing
|
|
- 15-second timeout per page with graceful error handling
|
|
- Handles self-signed certificates without errors
|
|
- Saves screenshots as PNG files with references in JSON reports
|
|
- Screenshots organized in timestamped directories
|
|
- Browser reuse for optimal performance
|
|
|
|
### Reporting & Output
|
|
- **Machine-readable JSON output** format for easy post-processing
|
|
- **Dockerized** for consistent execution environment and root privilege isolation
|
|
- **Expected vs. Actual comparison** to identify infrastructure drift
|
|
- Timestamped reports with complete scan duration metrics
|
|
|
|
## Requirements
|
|
|
|
- Docker
|
|
- Docker Compose (optional, for easier usage)
|
|
|
|
## Quick Start
|
|
|
|
### Using Docker Compose
|
|
|
|
1. Create or modify a configuration file in `configs/`:
|
|
|
|
```yaml
|
|
title: "My Infrastructure Scan"
|
|
sites:
|
|
- name: "Web Servers"
|
|
ips:
|
|
- address: "192.168.1.10"
|
|
expected:
|
|
ping: true
|
|
tcp_ports: [22, 80, 443]
|
|
udp_ports: []
|
|
```
|
|
|
|
2. Build and run:
|
|
|
|
```bash
|
|
docker-compose build
|
|
docker-compose up
|
|
```
|
|
|
|
3. Check results in the `output/` directory
|
|
|
|
## Scan Performance
|
|
|
|
SneakyScanner uses a five-phase approach for comprehensive scanning:
|
|
|
|
1. **Ping Scan** (masscan): ICMP echo detection - ~1-2 seconds
|
|
2. **TCP Port Discovery** (masscan): Scans all 65535 TCP ports at 10,000 packets/second - ~13 seconds per 2 IPs
|
|
3. **UDP Port Discovery** (masscan): Scans all 65535 UDP ports at 10,000 packets/second - ~13 seconds per 2 IPs
|
|
4. **Service Detection** (nmap): Identifies services on discovered TCP ports - ~20-60 seconds per IP with open ports
|
|
5. **HTTP/HTTPS Analysis** (Playwright, SSL/TLS): Detects web protocols, captures screenshots, and analyzes certificates - ~10-20 seconds per web service
|
|
|
|
**Example**: Scanning 2 IPs with 10 open ports each (including 2-3 web services) typically takes 2-3 minutes total.
|
|
|
|
### Using Docker Directly
|
|
|
|
1. Build the image:
|
|
|
|
```bash
|
|
docker build -t sneakyscanner .
|
|
```
|
|
|
|
2. Run a scan:
|
|
|
|
```bash
|
|
docker run --rm --privileged --network host \
|
|
-v $(pwd)/configs:/app/configs:ro \
|
|
-v $(pwd)/output:/app/output \
|
|
sneakyscanner /app/configs/your-config.yaml
|
|
```
|
|
|
|
## Configuration File Format
|
|
|
|
The YAML configuration file defines the scan parameters:
|
|
|
|
```yaml
|
|
title: "Scan Title" # Required: Report title
|
|
sites: # Required: List of sites to scan
|
|
- name: "Site Name"
|
|
ips:
|
|
- address: "192.168.1.10"
|
|
expected:
|
|
ping: true # Expected ping response
|
|
tcp_ports: [22, 80] # Expected TCP ports
|
|
udp_ports: [53] # Expected UDP ports
|
|
```
|
|
|
|
See `configs/example-site.yaml` for a complete example.
|
|
|
|
## Output Format
|
|
|
|
Scan results are saved as JSON files in the `output/` directory with timestamps. Screenshots are saved in a subdirectory with the same timestamp. The report includes the total scan duration (in seconds) covering all phases: ping scan, TCP/UDP port discovery, service detection, and screenshot capture.
|
|
|
|
```json
|
|
{
|
|
"title": "Sneaky Infra Scan",
|
|
"scan_time": "2024-01-15T10:30:00Z",
|
|
"scan_duration": 95.3,
|
|
"config_file": "/app/configs/example-site.yaml",
|
|
"sites": [
|
|
{
|
|
"name": "Production Web Servers",
|
|
"ips": [
|
|
{
|
|
"address": "192.168.1.10",
|
|
"expected": {
|
|
"ping": true,
|
|
"tcp_ports": [22, 80, 443],
|
|
"udp_ports": [53]
|
|
},
|
|
"actual": {
|
|
"ping": true,
|
|
"tcp_ports": [22, 80, 443, 3000],
|
|
"udp_ports": [53],
|
|
"services": [
|
|
{
|
|
"port": 22,
|
|
"protocol": "tcp",
|
|
"service": "ssh",
|
|
"product": "OpenSSH",
|
|
"version": "8.2p1"
|
|
},
|
|
{
|
|
"port": 80,
|
|
"protocol": "tcp",
|
|
"service": "http",
|
|
"product": "nginx",
|
|
"version": "1.18.0",
|
|
"http_info": {
|
|
"protocol": "http",
|
|
"screenshot": "scan_report_20250115_103000_screenshots/192_168_1_10_80.png"
|
|
}
|
|
},
|
|
{
|
|
"port": 443,
|
|
"protocol": "tcp",
|
|
"service": "https",
|
|
"product": "nginx",
|
|
"http_info": {
|
|
"protocol": "https",
|
|
"screenshot": "scan_report_20250115_103000_screenshots/192_168_1_10_443.png",
|
|
"ssl_tls": {
|
|
"certificate": {
|
|
"subject": "CN=example.com",
|
|
"issuer": "CN=Let's Encrypt Authority X3,O=Let's Encrypt,C=US",
|
|
"serial_number": "123456789012345678901234567890",
|
|
"not_valid_before": "2025-01-01T00:00:00+00:00",
|
|
"not_valid_after": "2025-04-01T23:59:59+00:00",
|
|
"days_until_expiry": 89,
|
|
"sans": ["example.com", "www.example.com"]
|
|
},
|
|
"tls_versions": {
|
|
"TLS 1.0": {
|
|
"supported": false,
|
|
"cipher_suites": []
|
|
},
|
|
"TLS 1.1": {
|
|
"supported": false,
|
|
"cipher_suites": []
|
|
},
|
|
"TLS 1.2": {
|
|
"supported": true,
|
|
"cipher_suites": [
|
|
"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
|
|
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
|
|
]
|
|
},
|
|
"TLS 1.3": {
|
|
"supported": true,
|
|
"cipher_suites": [
|
|
"TLS_AES_256_GCM_SHA384",
|
|
"TLS_AES_128_GCM_SHA256"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"port": 3000,
|
|
"protocol": "tcp",
|
|
"service": "http",
|
|
"product": "Node.js",
|
|
"http_info": {
|
|
"protocol": "http"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Screenshot Capture Details
|
|
|
|
SneakyScanner automatically captures webpage screenshots for all discovered HTTP and HTTPS services, providing visual documentation of your infrastructure.
|
|
|
|
### How It Works
|
|
|
|
1. **Automatic Detection**: During the HTTP/HTTPS analysis phase, SneakyScanner identifies web services based on:
|
|
- Nmap service detection results (http, https, ssl, http-proxy)
|
|
- Common web ports (80, 443, 8000, 8006, 8080, 8081, 8443, 8888, 9443)
|
|
|
|
2. **Screenshot Capture**: For each web service:
|
|
- Launches headless Chromium browser (once per scan, reused for all screenshots)
|
|
- Navigates to the service URL (HTTP or HTTPS)
|
|
- Waits for network to be idle (up to 15 seconds)
|
|
- Captures viewport screenshot (1280x720 pixels)
|
|
- Handles SSL certificate errors gracefully (e.g., self-signed certificates)
|
|
|
|
3. **Storage**: Screenshots are saved as PNG files:
|
|
- Directory: `output/scan_report_YYYYMMDD_HHMMSS_screenshots/`
|
|
- Filename format: `{ip}_{port}.png` (e.g., `192_168_1_10_443.png`)
|
|
- Referenced in JSON report under `http_info.screenshot`
|
|
|
|
### Screenshot Configuration
|
|
|
|
Default settings (configured in `src/screenshot_capture.py`):
|
|
- **Viewport size**: 1280x720 (captures visible area only, not full page)
|
|
- **Timeout**: 15 seconds per page load
|
|
- **Browser**: Chromium (headless mode)
|
|
- **SSL handling**: Ignores HTTPS errors (works with self-signed certificates)
|
|
- **User agent**: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
|
|
|
|
### Error Handling
|
|
|
|
Screenshots are captured on a best-effort basis:
|
|
- If a screenshot fails (timeout, connection error, etc.), the scan continues
|
|
- Failed screenshots are logged but don't stop the scan
|
|
- Services without screenshots simply omit the `screenshot` field in JSON output
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
SneakyScanner/
|
|
├── src/
|
|
│ ├── scanner.py # Main scanner application
|
|
│ └── screenshot_capture.py # Webpage screenshot capture module
|
|
├── configs/
|
|
│ └── example-site.yaml # Example configuration
|
|
├── output/ # Scan results
|
|
│ ├── scan_report_*.json # JSON reports with timestamps
|
|
│ └── scan_report_*_screenshots/ # Screenshot directories
|
|
├── Dockerfile
|
|
├── docker-compose.yml
|
|
├── requirements.txt
|
|
├── CLAUDE.md # Developer documentation
|
|
└── README.md
|
|
```
|
|
|
|
## Security Notice
|
|
|
|
This tool requires:
|
|
- `--privileged` flag or `CAP_NET_RAW` capability for masscan and nmap raw socket access
|
|
- `--network host` for direct network access
|
|
|
|
Only use this tool on networks you own or have explicit authorization to scan. Unauthorized network scanning may be illegal in your jurisdiction.
|
|
|
|
## Future Enhancements
|
|
|
|
- **HTML Report Generation**: Build comprehensive HTML reports from JSON output with:
|
|
- Service details and SSL/TLS information
|
|
- Visual comparison of expected vs. actual results
|
|
- Certificate expiration warnings
|
|
- TLS version compliance reports
|
|
- Embedded webpage screenshots
|
|
- **Comparison Reports**: Generate diff reports showing changes between scans
|
|
- **Email Notifications**: Alert on unexpected changes or certificate expirations
|
|
- **Scheduled Scanning**: Automated periodic scans with cron integration
|
|
- **Vulnerability Detection**: Integration with CVE databases for known vulnerabilities
|