# 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 - **Automatic multi-format output** after each scan: - Machine-readable JSON reports for post-processing - Human-readable HTML reports with dark theme - ZIP archives containing all outputs for easy sharing - **HTML report features**: - Comprehensive reports with dark theme for easy reading - Summary dashboard with scan statistics, drift alerts, and security warnings - Site-by-site breakdown with expandable service details - Visual badges for expected vs. unexpected services - SSL/TLS certificate details with expiration warnings - Automatically generated after every scan - **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_report_YYYYMMDD_HHMMSS.json` - JSON report - `scan_report_YYYYMMDD_HHMMSS.html` - HTML report - `scan_report_YYYYMMDD_HHMMSS.zip` - ZIP archive - `scan_report_YYYYMMDD_HHMMSS_screenshots/` - Screenshots 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 After each scan completes, SneakyScanner automatically generates three output formats: 1. **JSON Report** (`scan_report_YYYYMMDD_HHMMSS.json`): Machine-readable scan data with all discovered services, ports, and SSL/TLS information 2. **HTML Report** (`scan_report_YYYYMMDD_HHMMSS.html`): Human-readable report with dark theme, summary dashboard, and detailed service breakdown 3. **ZIP Archive** (`scan_report_YYYYMMDD_HHMMSS.zip`): Contains JSON report, HTML report, and all screenshots for easy sharing and archival All files share the same timestamp for easy correlation. Screenshots are saved in a subdirectory (`scan_report_YYYYMMDD_HHMMSS_screenshots/`) and included in the ZIP archive. The report includes the total scan duration (in seconds) covering all phases: ping scan, TCP/UDP port discovery, service detection, screenshot capture, and report generation. ```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 ## HTML Report Generation SneakyScanner automatically generates comprehensive HTML reports after each scan, providing an easy-to-read visual interface for analyzing scan results. ### Automatic Generation HTML reports are automatically created after every scan completes, along with JSON reports and ZIP archives. All three outputs share the same timestamp and are saved to the `output/` directory. ### Manual Generation (Optional) You can also manually generate HTML reports from existing JSON scan data: ```bash # Generate HTML report (creates report in same directory as JSON) python3 src/report_generator.py output/scan_report_20251113_175235.json # Specify custom output path python3 src/report_generator.py output/scan_report.json /path/to/custom_report.html ``` ### Report Features The generated HTML report includes: **Summary Dashboard**: - **Scan Statistics**: Total IPs scanned, TCP/UDP ports found, services identified, web services, screenshots captured - **Drift Alerts**: Unexpected TCP/UDP ports, missing expected services, new services detected - **Security Warnings**: Expiring certificates (<30 days), weak TLS versions (1.0/1.1), self-signed certificates, high port services (>10000) **Site-by-Site Breakdown**: - Organized by logical site grouping from configuration - Per-IP sections with status badges (ping, port drift summary) - Service tables with expandable details (click any row to expand) - Visual badges: green (expected), red (unexpected), yellow (missing/warning) **Service Details** (click to expand): - Product name, version, extra information, OS type - HTTP/HTTPS protocol detection - Screenshot links for web services - SSL/TLS certificate details (expandable): - Subject, issuer, validity dates, serial number - Days until expiration with color-coded warnings - Subject Alternative Names (SANs) - TLS version support (1.0, 1.1, 1.2, 1.3) with cipher suites - Weak TLS and self-signed certificate warnings **UDP Port Handling**: - Expected UDP ports shown with green "Expected" badge - Unexpected UDP ports shown with red "Unexpected" badge - Missing expected UDP ports shown with yellow "Missing" badge - Note: Service detection not available for UDP (nmap limitation) **Design**: - Dark theme with slate/grey color scheme for comfortable reading - Responsive layout works on different screen sizes - No external dependencies - single HTML file - Minimal JavaScript for expand/collapse functionality - Optimized hover effects for table rows ### Report Output The HTML report is a standalone file that can be: - Opened directly in any web browser (Chrome, Firefox, Safari, Edge) - Shared via email or file transfer - Archived for compliance or historical comparison - Viewed without an internet connection or web server Screenshot links in the report are relative paths, so keep the report and screenshot directory together. ## Project Structure ``` SneakyScanner/ ├── src/ │ ├── scanner.py # Main scanner application │ ├── screenshot_capture.py # Webpage screenshot capture module │ └── report_generator.py # HTML report generation module ├── templates/ │ ├── report_template.html # Jinja2 template for HTML reports │ └── report_mockup.html # Static mockup for design testing ├── configs/ │ └── example-site.yaml # Example configuration ├── output/ # Scan results │ ├── scan_report_*.json # JSON reports with timestamps │ ├── scan_report_*.html # HTML reports (generated from JSON) │ └── 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 - **Enhanced HTML Reports**: - Sortable/filterable service tables with JavaScript - Interactive charts and graphs for trends - Timeline view of scan history - Embedded screenshot thumbnails (currently links only) - Export to PDF capability - **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