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

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:

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:

docker build -t sneakyscanner .

2. Run a scan:

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:

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.

{
  "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:

# 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