199 lines
7.8 KiB
Markdown
199 lines
7.8 KiB
Markdown
# 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
|
|
- 🔔 **Alerts** *(Phase 5 - Coming Soon)* - Email and webhook notifications for misconfigurations
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Web Application (Recommended)
|
|
|
|
```bash
|
|
# 1. Clone repository
|
|
git clone <repository-url>
|
|
cd SneakyScan
|
|
|
|
# 2. Configure environment
|
|
cp .env.example .env
|
|
# Edit .env and set SECRET_KEY and SNEAKYSCANNER_ENCRYPTION_KEY
|
|
|
|
# 3. Build and start
|
|
docker compose build
|
|
docker compose up -d
|
|
|
|
# 4. Initialize database
|
|
docker compose run --rm init-db --password "YourSecurePassword"
|
|
|
|
# 5. Access web interface
|
|
# Open http://localhost:5000
|
|
```
|
|
|
|
**See [Deployment Guide](docs/DEPLOYMENT.md) for detailed setup instructions.**
|
|
|
|
### CLI Scanner (Standalone)
|
|
|
|
For quick one-off scans without the web interface:
|
|
|
|
```bash
|
|
# 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](docs/CLI_SCANNING.md) for detailed usage.**
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
### User Guides
|
|
- **[Deployment Guide](docs/DEPLOYMENT.md)** - Installation, configuration, and production deployment
|
|
- **[CLI Scanning Guide](docs/CLI_SCANNING.md)** - Standalone scanner usage, configuration, and output formats
|
|
- **[API Reference](docs/API_REFERENCE.md)** - Complete REST API documentation
|
|
|
|
### Developer Resources
|
|
- **[Roadmap](docs/ROADMAP.md)** - Project roadmap, architecture, and planned features
|
|
|
|
---
|
|
|
|
## Current Status
|
|
|
|
**Latest Version**: Phase 4 Complete ✅
|
|
**Last Updated**: 2025-11-17
|
|
|
|
### 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
|
|
|
|
### Next Up: Phase 5 - Email, Webhooks & Comparisons
|
|
|
|
**Core Use Case**: Monitor infrastructure for misconfigurations that expose unexpected ports/services. When a scan detects an open port not in the config's `expected_ports` list, trigger immediate notifications.
|
|
|
|
**Planned Features**:
|
|
- Email notifications for infrastructure changes
|
|
- Webhook integrations (Slack, PagerDuty, custom SIEM)
|
|
- Alert rule engine (unexpected ports, cert expiry, weak TLS)
|
|
- Scan comparison reports for drift detection
|
|
|
|
See [Roadmap](docs/ROADMAP.md) for complete feature timeline.
|
|
|
|
---
|
|
|
|
## 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:
|
|
- `--privileged` flag or `CAP_NET_RAW` capability for raw socket access (masscan/nmap)
|
|
- `--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.
|
|
|
|
### Security Best Practices
|
|
|
|
1. Run on dedicated scan server (not production systems)
|
|
2. Restrict network access with firewall rules
|
|
3. Use strong passwords and encryption keys
|
|
4. Enable HTTPS in production (reverse proxy recommended)
|
|
5. Regularly update Docker images and dependencies
|
|
|
|
See [Deployment Guide](docs/DEPLOYMENT.md) for production security checklist.
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
**Documentation**:
|
|
- [Deployment Guide](docs/DEPLOYMENT.md)
|
|
- [CLI Scanning Guide](docs/CLI_SCANNING.md)
|
|
- [API Reference](docs/API_REFERENCE.md)
|
|
- [Roadmap](docs/ROADMAP.md)
|
|
|
|
**Issues**: email me ptarrant at gmail dot com
|
|
|
|
---
|
|
|
|
**Version**: Phase 4 Complete
|
|
**Last Updated**: 2025-11-17
|