SneakyScan/README.md

# 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
- **HTML report generation**:
  - Comprehensive HTML 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
  - One-click generation from JSON scan data
- **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

## HTML Report Generation

SneakyScanner can generate comprehensive HTML reports from JSON scan data, providing an easy-to-read visual interface for analyzing scan results.

### Generating Reports

After completing a scan, generate an HTML report from the JSON output:

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