# 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