Phillip Tarrant
9bd2f67150
Allow users to add ports to expected list directly from scan results page instead of navigating through site config pages. The button appears next to unexpected ports and updates the site IP configuration via the API. - Add site_id and site_ip_id to scan result data for linking to config - Add "Mark Expected" button next to unexpected ports in scan detail view - Implement markPortExpected() JS function to update site IP settings
SneakyScanner
A comprehensive network scanning and infrastructure monitoring platform with web interface and CLI scanner. 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.
Primary Interface: Web Application (Flask-based GUI) Scripting/Automation: REST API (see API Reference)
Key Features
- 🌐 Web Dashboard - Modern web UI for scan management, scheduling, and historical analysis
- 📊 Database Storage - SQLite-based scan history with trend analysis and comparison
- ⏰ Scheduled Scans - Cron-based automated scanning with APScheduler
- 🔧 Config Creator - Web-based target configuration builder for quick setup
- 🔍 Network Discovery - Fast port scanning with masscan (all 65535 ports, TCP/UDP)
- 🎯 Service Detection - Nmap-based service enumeration with version detection
- 🔒 SSL/TLS Analysis - Certificate extraction, TLS version testing, cipher suite analysis
- 📸 Screenshot Capture - Automated webpage screenshots for all discovered web services
- 📈 Drift Detection - Expected vs. actual infrastructure comparison
- 📋 Multi-Format Reports - JSON, HTML, and ZIP archives with visual reports
- 🔐 Authentication - Session-based login for single-user deployments
- 🔔 Webhook Alerts - Real-time notifications via Slack, Discord, PagerDuty, and custom integrations
- ⚠️ Alert Rules - Automated detection of infrastructure misconfigurations and anomalies
Quick Start
Web Application
Easy Setup (One Command):
# 1. Clone repository
git clone <repository-url>
cd SneakyScan
# 2. Run setup script
./setup.sh
# 3. Access web interface at http://localhost:5000
The setup script will:
- Generate secure keys automatically
- Create required directories
- Build and start the Docker containers
- Initialize the database on first run
- Display your login credentials
Manual Setup (Alternative):
# 1. Clone repository
git clone <repository-url>
cd SneakyScan
# 2. Configure environment
cp .env.example .env
# Edit .env and set SECRET_KEY, SNEAKYSCANNER_ENCRYPTION_KEY, and INITIAL_PASSWORD
# 3. Build and start (database auto-initializes on first run)
docker compose up --build -d
# 4. Access web interface
# Open http://localhost:5000
See Deployment Guide for detailed setup instructions.
Documentation
User Guides
- Deployment Guide - Installation, configuration, and production deployment
- API Reference - Complete REST API documentation for scripting and automation
Developer Resources
- Roadmap - Project roadmap, architecture, and planned features
Current Status
Latest Version: Phase 5 Complete ✅ Last Updated: 2025-11-19
Completed Phases
- ✅ Phase 1: Database schema, SQLAlchemy models, settings system
- ✅ Phase 2: REST API, background jobs, authentication, web UI
- ✅ Phase 3: Dashboard, scheduling, trend charts
- ✅ Phase 4: Config creator, target editor, config management UI
- ✅ Phase 5: Webhooks & alerting, notification templates, alert rules
Next Up: Phase 6 - CLI as API Client
Goal: Create a thin CLI client that calls the Flask API for scan operations, enabling scripting and automation workflows while leveraging centralized database storage and web dashboard features.
Planned Features:
- API token authentication for CLI access
- Remote scan triggering and status polling
- Centralized scan history accessible via web dashboard
- Scriptable automation workflows
See Roadmap for complete feature timeline and future phases.
Architecture
┌─────────────────────────────────────────────────────────────┐
│ Flask Web Application │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Web UI │ │ REST API │ │ Scheduler │ │
│ │ (Dashboard) │ │ (JSON/CRUD) │ │ (APScheduler) │ │
│ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
│ │ │ │ │
│ └─────────────────┴────────────────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ SQLAlchemy │ │
│ │ (ORM Layer) │ │
│ └────────┬────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ SQLite3 DB │ │
│ │ (scan history) │ │
│ └─────────────────┘ │
└───────────────────────────┬─────────────────────────────────┘
│
┌──────────▼──────────┐
│ Scanner Engine │
│ (scanner.py) │
│ ┌────────────────┐ │
│ │ Masscan/Nmap │ │
│ │ Playwright │ │
│ │ sslyze │ │
│ └────────────────┘ │
└─────────────────────┘
Technology Stack:
- Backend: Flask 3.x, SQLAlchemy 2.x, SQLite3, APScheduler 3.x
- Frontend: Jinja2, Bootstrap 5, Chart.js, Vanilla JavaScript
- Scanner: Masscan, Nmap, Playwright (Chromium), sslyze
- Deployment: Docker Compose, Gunicorn
Security Notice
⚠️ Important: This tool requires:
--privilegedflag orCAP_NET_RAWcapability for raw socket access (masscan/nmap)--network hostfor 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.
Security Best Practices
- Run on dedicated scan server (not production systems)
- Restrict network access with firewall rules
- Use strong passwords and encryption keys
- Enable HTTPS in production (reverse proxy recommended)
- Regularly update Docker images and dependencies
See Deployment Guide for production security checklist.
Contributing
This is a personal project. For bugs or feature requests:
- Check existing issues
- Create detailed bug reports with reproduction steps
- Submit pull requests with tests
License
MIT License - See LICENSE file for details
Support
Documentation:
Issues: email me ptarrant at gmail dot com
Version: 1.0.0-beta Last Updated: 2025-11-19