Phillip Tarrant
9804f9c032
Output files (JSON, HTML, ZIP) are stored outside the static directory, so download links in scan_detail.html were broken. This adds a /output/ route that serves files from the output directory using send_from_directory for secure file access. Route requires authentication.
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) Alternative: Standalone CLI Scanner (for testing and CI/CD)
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 - CIDR-to-YAML 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 (Recommended)
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.
CLI Scanner (Standalone)
For quick one-off scans without the web interface:
# Build and run
docker compose -f docker-compose-standalone.yml build
docker compose -f docker-compose-standalone.yml up
# Results saved to ./output/
See CLI Scanning Guide for detailed usage.
Documentation
User Guides
- Deployment Guide - Installation, configuration, and production deployment
- CLI Scanning Guide - Standalone scanner usage, configuration, and output formats
- API Reference - Complete REST API documentation
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, YAML 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/small team 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: Phase 5 Complete Last Updated: 2025-11-19