SneakyScanner

A comprehensive network scanning and infrastructure monitoring platform with both CLI and web interfaces. SneakyScanner uses masscan for fast port discovery, nmap for service detection, sslyze for SSL/TLS analysis, and Playwright for webpage screenshots to perform comprehensive infrastructure audits.

Features:

• 🔍 CLI Scanner - Standalone scanning tool with YAML-based configuration
• 🌐 Web Application - Flask-based web UI with REST API for scan management
• 📊 Database Storage - SQLite database for scan history and trend analysis
• ⏱️ Background Jobs - Asynchronous scan execution with APScheduler
• 🔐 Authentication - Secure session-based authentication system
• 📈 Historical Data - Track infrastructure changes over time

Table of Contents

1. Quick Start
   • Web Application (Recommended)
   • CLI Scanner (Standalone)
2. Features
3. Web Application
4. CLI Scanner
5. Configuration
6. Output Formats
7. API Documentation
8. Deployment
9. Development

---

Quick Start

Web Application (Recommended)

The web application provides a complete interface for managing scans, viewing history, and analyzing results.

1. Configure environment:

# Copy example environment file
cp .env.example .env

# Generate secure keys (Linux/Mac)
export SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_hex(32))')
export ENCRYPTION_KEY=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')

# Update .env file with generated keys
sed -i "s/your-secret-key-here/$SECRET_KEY/" .env
sed -i "s/your-encryption-key-here/$ENCRYPTION_KEY/" .env

2. Start the web application:

docker-compose -f docker-compose-web.yml up -d

3. Access the web interface:

• Open http://localhost:5000 in your browser
• Default password: admin (change immediately after first login)

4. Trigger your first scan:

• Click "Run Scan Now" on the dashboard
• Or use the API:

curl -X POST http://localhost:5000/api/scans \
  -H "Content-Type: application/json" \
  -d '{"config_file":"/app/configs/example-site.yaml"}' \
  -b cookies.txt

See Deployment Guide for detailed setup instructions.

CLI Scanner (Standalone)

For quick one-off scans or scripting, use the standalone CLI scanner:

# Build the image
docker-compose build

# Run a scan
docker-compose up

# Or run directly
docker run --rm --privileged --network host \
  -v $(pwd)/configs:/app/configs:ro \
  -v $(pwd)/output:/app/output \
  sneakyscanner /app/configs/example-site.yaml

Results are saved to the output/ directory as JSON, HTML, and ZIP files.

---

Features

Web Application (Phase 2)

• Dashboard - View scan history, statistics, and recent activity
• REST API - Programmatic access to all scan management functions
• Background Jobs - Scans execute asynchronously without blocking
• Database Storage - Complete scan history with queryable data
• Authentication - Secure session-based login system
• Pagination - Efficiently browse large scan datasets
• Status Tracking - Real-time scan progress monitoring
• Error Handling - Comprehensive error logging and reporting

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

---

Web Application

Overview

The SneakyScanner web application provides a Flask-based interface for managing network scans. All scans are stored in a SQLite database, enabling historical analysis and trending.

Key Features

Scan Management:

• Trigger scans via web UI or REST API
• View complete scan history with pagination
• Monitor real-time scan status
• Delete scans and associated files

REST API:

• Full CRUD operations for scans
• Session-based authentication
• JSON responses for all endpoints
• Comprehensive error handling

Background Processing:

• APScheduler for async scan execution
• Up to 3 concurrent scans (configurable)
• Status tracking: running → completed/failed
• Error capture and logging

Database Schema:

• 11 normalized tables for scan data
• Relationships: Scans → Sites → IPs → Ports → Services → Certificates → TLS Versions
• Efficient queries with indexes
• SQLite WAL mode for better concurrency

Web UI Routes

Route	Description
/	Redirects to dashboard
/login	Login page
/logout	Logout and destroy session
/dashboard	Main dashboard with stats and recent scans
/scans	Browse scan history (paginated)
/scans/<id>	View detailed scan results

API Endpoints

See API_REFERENCE.md for complete API documentation.

Core Endpoints:

• POST /api/scans - Trigger new scan
• GET /api/scans - List scans (paginated, filterable)
• GET /api/scans/{id} - Get scan details
• GET /api/scans/{id}/status - Poll scan status
• DELETE /api/scans/{id} - Delete scan and files

Settings Endpoints:

• GET /api/settings - Get all settings
• PUT /api/settings/{key} - Update setting
• GET /api/settings/health - Health check

Authentication

Login:

curl -X POST http://localhost:5000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password":"yourpassword"}' \
  -c cookies.txt

Use session for API calls:

curl -X GET http://localhost:5000/api/scans \
  -b cookies.txt

Change password:

1. Login to web UI
2. Navigate to Settings
3. Update app password
4. Or use CLI: python3 web/utils/change_password.py

---

CLI Scanner

Requirements

• Docker
• Docker Compose (optional, for easier usage)

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

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 Formats

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.

---

API Documentation

Complete API reference available at docs/ai/API_REFERENCE.md.

Quick Reference:

Endpoint	Method	Description
/api/scans	POST	Trigger new scan
/api/scans	GET	List all scans (paginated)
/api/scans/{id}	GET	Get scan details
/api/scans/{id}/status	GET	Get scan status
/api/scans/{id}	DELETE	Delete scan
/api/settings	GET	Get all settings
/api/settings/{key}	PUT	Update setting
/api/settings/health	GET	Health check

Authentication: All endpoints (except /api/settings/health) require session authentication via /auth/login.

---

Deployment

Production Deployment

See DEPLOYMENT.md for comprehensive deployment guide.

Quick Steps:

1. Configure environment variables:

cp .env.example .env
# Edit .env and set secure keys

2. Initialize database:

docker-compose -f docker-compose-web.yml run --rm web python3 init_db.py

3. Start services:

docker-compose -f docker-compose-web.yml up -d

4. Verify health:

curl http://localhost:5000/api/settings/health

Docker Volumes

The web application uses persistent volumes:

Volume	Path	Description
data	/app/data	SQLite database
output	/app/output	Scan results (JSON, HTML, ZIP, screenshots)
logs	/app/logs	Application logs
configs	/app/configs	YAML scan configurations

Backup:

# Backup database
docker cp sneakyscanner_web:/app/data/sneakyscanner.db ./backup/

# Backup all scan results
docker cp sneakyscanner_web:/app/output ./backup/

# Or use docker-compose volumes
docker run --rm -v sneakyscanner_data:/data -v $(pwd)/backup:/backup alpine tar czf /backup/data.tar.gz /data

Environment Variables

See .env.example for complete configuration options:

Flask Configuration:

• FLASK_ENV - Environment mode (production/development)
• FLASK_DEBUG - Debug mode (true/false)
• SECRET_KEY - Flask secret key for sessions (generate with secrets.token_hex(32))

Database:

• DATABASE_URL - Database connection string (default: SQLite)

Security:

• SNEAKYSCANNER_ENCRYPTION_KEY - Encryption key for sensitive settings (generate with secrets.token_urlsafe(32))

Scheduler:

• SCHEDULER_EXECUTORS - Number of concurrent scan workers (default: 2)
• SCHEDULER_JOB_DEFAULTS_MAX_INSTANCES - Max concurrent jobs (default: 3)

---

Development

Project Structure

SneakyScanner/
├── src/                     # Scanner engine (CLI)
│   ├── scanner.py           # Main scanner application
│   ├── screenshot_capture.py # Webpage screenshot capture
│   └── report_generator.py  # HTML report generation
├── web/                     # Web application (Flask)
│   ├── app.py               # Flask app factory
│   ├── models.py            # SQLAlchemy models (11 tables)
│   ├── api/                 # API blueprints
│   │   ├── scans.py         # Scan management endpoints
│   │   ├── settings.py      # Settings endpoints
│   │   └── ...
│   ├── auth/                # Authentication
│   │   ├── routes.py        # Login/logout routes
│   │   ├── decorators.py    # Auth decorators
│   │   └── models.py        # User model
│   ├── routes/              # Web UI routes
│   │   └── main.py          # Dashboard, scans pages
│   ├── services/            # Business logic
│   │   ├── scan_service.py  # Scan CRUD operations
│   │   └── scheduler_service.py # APScheduler integration
│   ├── jobs/                # Background jobs
│   │   └── scan_job.py      # Async scan execution
│   ├── utils/               # Utilities
│   │   ├── settings.py      # Settings manager
│   │   ├── pagination.py    # Pagination helper
│   │   └── validators.py    # Input validation
│   ├── templates/           # Jinja2 templates
│   │   ├── base.html        # Base layout
│   │   ├── login.html       # Login page
│   │   ├── dashboard.html   # Dashboard
│   │   └── errors/          # Error templates
│   └── static/              # Static assets
│       ├── css/
│       ├── js/
│       └── images/
├── templates/               # Report templates (CLI)
│   └── report_template.html # HTML report template
├── tests/                   # Test suite
│   ├── conftest.py          # Pytest fixtures
│   ├── test_scan_service.py # Service tests
│   ├── test_scan_api.py     # API tests
│   ├── test_authentication.py # Auth tests
│   ├── test_background_jobs.py # Scheduler tests
│   └── test_error_handling.py # Error handling tests
├── migrations/              # Alembic database migrations
│   └── versions/
│       ├── 001_initial_schema.py
│       ├── 002_add_scan_indexes.py
│       └── 003_add_scan_timing_fields.py
├── configs/                 # Scan configurations
│   └── example-site.yaml
├── output/                  # Scan results
├── docs/                    # Documentation
│   ├── ai/                  # Development docs
│   │   ├── API_REFERENCE.md
│   │   ├── DEPLOYMENT.md
│   │   ├── PHASE2.md
│   │   ├── PHASE2_COMPLETE.md
│   │   └── ROADMAP.md
│   └── human/
├── Dockerfile               # Scanner + web app image
├── docker-compose.yml       # CLI scanner compose
├── docker-compose-web.yml   # Web app compose
├── requirements.txt         # Scanner dependencies
├── requirements-web.txt     # Web app dependencies
├── alembic.ini             # Alembic configuration
├── init_db.py              # Database initialization
├── .env.example            # Environment template
├── CLAUDE.md               # Developer guide
└── README.md               # This file

Running Tests

In Docker:

docker-compose -f docker-compose-web.yml run --rm web pytest tests/ -v

Locally (requires Python 3.12+):

pip install -r requirements-web.txt
pytest tests/ -v

# With coverage
pytest tests/ --cov=web --cov-report=html

Test Coverage:

• 100 test functions across 6 test files
• 1,825 lines of test code
• Coverage: Service layer, API endpoints, authentication, error handling, background jobs

Database Migrations

Create new migration:

docker-compose -f docker-compose-web.yml run --rm web alembic revision --autogenerate -m "Description"

Apply migrations:

docker-compose -f docker-compose-web.yml run --rm web alembic upgrade head

Rollback:

docker-compose -f docker-compose-web.yml run --rm web alembic downgrade -1

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.

---

Roadmap

Current Phase: Phase 2 Complete ✅

Completed Phases:

• ✅ Phase 1 - Database foundation, Flask app structure, settings system
• ✅ Phase 2 - REST API, background jobs, authentication, basic UI

Upcoming Phases:

• 📋 Phase 3 - Enhanced dashboard, trend charts, scheduled scans (Weeks 5-6)
• 📋 Phase 4 - Email notifications, scan comparison, alert rules (Weeks 7-8)
• 📋 Phase 5 - CLI as API client, token authentication (Week 9)
• 📋 Phase 6 - Advanced features (vulnerability detection, PDF export, timeline view)

See ROADMAP.md for detailed feature planning.

---

Contributing

This is a personal/small team project. For bugs or feature requests:

1. Check existing issues
2. Create detailed bug reports with reproduction steps
3. Submit pull requests with tests

---

License

MIT License - See LICENSE file for details

---

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

⚠️ Important: Only use this tool on networks you own or have explicit authorization to scan. Unauthorized network scanning may be illegal in your jurisdiction.

---

Support

Documentation:

• API Reference
• Deployment Guide
• Developer Guide
• Roadmap

Issues: https://github.com/anthropics/sneakyscanner/issues

---

Version: 2.0 (Phase 2 Complete) Last Updated: 2025-11-14