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

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

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.

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