# 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](docs/API_REFERENCE.md))

---

## 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):**

```bash
# 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):**

```bash
# 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](docs/DEPLOYMENT.md) for detailed setup instructions.**

---

## Documentation

### User Guides
- **[Deployment Guide](docs/DEPLOYMENT.md)** - Installation, configuration, and production deployment
- **[API Reference](docs/API_REFERENCE.md)** - Complete REST API documentation for scripting and automation

### Developer Resources
- **[Roadmap](docs/ROADMAP.md)** - 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](docs/ROADMAP.md) 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:
- `--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 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)
- [API Reference](docs/API_REFERENCE.md)
- [Roadmap](docs/ROADMAP.md)

**Issues**: email me ptarrant at gmail dot com

---

**Version**: 1.0.0-beta
**Last Updated**: 2025-11-19