ScanPanel

A local-first web application for automating authorized security scans on networks and hosts with intelligent result analysis.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         ScanPanel System                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐ │
│  │   Next.js    │◄─────►│   FastAPI    │◄─────►│   Worker     │ │
│  │   Frontend   │ HTTP  │     API      │       │   Service    │ │
│  │  (Port 3000) │       │  (Port 8000) │       │              │ │
│  └──────────────┘       └──────┬───────┘       └──────┬───────┘ │
│         │                      │                       │         │
│         │                      │                       │         │
│         │              ┌───────▼───────┐      ┌───────▼───────┐ │
│         │              │  PostgreSQL   │      │     Redis     │ │
│         │              │   Database    │      │   (Cache)     │ │
│         │              └───────────────┘      └───────────────┘ │
│         │                                                       │
│         │              ┌───────────────┐                      │
│         └──────────────►│  WebSocket     │                      │
│                         │  (Live Updates)│                      │
│                         └───────────────┘                      │
│                                                                   │
│  External Services:                                              │
│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐ │
│  │   Nmap       │      │   Nuclei     │      │    Nikto     │ │
│  │  (Scanner)   │      │  (Scanner)   │      │  (Scanner)   │ │
│  └──────────────┘      └──────────────┘      └──────────────┘ │
│                                                                   │
│  ┌──────────────┐      ┌──────────────┐                         │
│  │ Local LLM    │      │  Telegram    │                         │
│  │ (gpt-oss 20b)│      │   Bot API    │                         │
│  └──────────────┘      └──────────────┘                         │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

Component Overview

• /apps/web - Next.js frontend (App Router, TypeScript, Tailwind, shadcn/ui)
• /apps/api - FastAPI backend (REST API, SQLAlchemy, Pydantic)
• /apps/worker - Job runner for scheduled scans (APScheduler)
• /packages/shared - Shared types, constants, and utilities
• /infra - Docker Compose configuration and environment templates

✨ Features

• 🔍 Multiple scanning tools: Nmap, Nuclei, Nikto (extensible adapter pattern)
• 💾 Store raw outputs and parsed findings with deduplication
• ⏰ Cyclical scans with scheduling (cron or interval-based)
• 📱 Telegram hooks for alerts and summaries
• 🎯 Simple "Add target/device" flow with safety validations
• 🤖 Automatic result analysis using local LLM (gpt-oss 20b)
• 🗄️ PostgreSQL database with optimized indexes
• 🔌 REST API + WebSocket for live scan progress
• 🔒 Safety guardrails to prevent misuse

🚀 Quick Start

TL;DR:

make dev          # Start everything
make migrate      # Setup database
make seed         # Load demo data
# Open http://localhost:3000

Detailed Steps

1. Start all services:

   make dev

   Or: cd infra && docker-compose up -d

2. Initialize database:

   make migrate
   make seed

3. Open in browser:

   • Frontend: http://localhost:3000
   • API Docs: http://localhost:8000/docs

4. Optional - Generate demo scan:

   make demo

That's it! See QUICK_START.md for more details.

Environment Configuration (Optional)

For basic usage, default configs work. To customize:

cp infra/.env.example infra/.env
# Edit infra/.env if needed (LLM endpoint, Telegram, etc.)

Default ports:

• Frontend: 3000
• API: 8000
• PostgreSQL: 5432
• Redis: 6379

🎯 Quick Tour

1. Dashboard

The dashboard provides an overview of your security posture:

• Stat cards: Total targets, scans in last 24h, open findings by severity
• Recent scans: Latest scan activity with status and duration
• New findings: Critical and high severity findings that need attention

2. Targets

Manage your scanning targets:

• Add target: Click "Add Target" → Enter name, IP/hostname/URL, select type
• Public IP warning: System detects public IPs and requires confirmation
• Target detail: View scan timeline and open findings for each target
• Run scan: Click "Run Scan" button on any target

3. Scan Profiles

Configure scan settings:

• Create profile: Select tools (nmap/nuclei/nikto), configure arguments
• Schedule: Set up recurring scans (cron or interval)
• Auto-analyze: Enable automatic LLM analysis after scan completes
• Telegram thresholds: Configure notification triggers

4. Scans

Monitor scan execution:

• Scan list: Filter by target, status, date range
• Live progress: Real-time updates via WebSocket
• Scan detail: View tasks, artifacts, LLM summary, findings
• Artifacts: Download raw scanner outputs

5. Findings

Review and triage security findings:

• Global view: Filter by severity, status, tool, CVE/CWE
• Bulk triage: Update status for multiple findings
• Finding detail: View evidence, instances over time, LLM analysis
• Status workflow: open → triaged → accepted_risk / false_positive / fixed

🛠️ Development

Using Makefile

make help          # Show all available commands
make dev           # Start all services
make test          # Run all tests
make lint          # Run linters
make format        # Format code
make clean         # Clean build artifacts

Running Services Locally

Backend API

make dev-api
# Or manually:
cd apps/api
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Frontend

make dev-web
# Or manually:
cd apps/web
npm install
npm run dev

Worker

make dev-worker
# Or manually:
cd apps/worker
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m app.main

Database Migrations

make migrate                    # Run migrations
make migrate-create NAME=xyz   # Create new migration

Testing

make test           # Run all tests
make test-api       # Run API tests only
make test-worker    # Run worker tests only

📚 Documentation

• Adding a New Scanner - Guide to add scanning tools
• LLM Setup Guide - Connect local LLM endpoint
• Safety Implementation - Security guardrails
• Frontend Implementation - UI details
• Worker Implementation - Worker architecture

⚙️ Configuration

LLM Configuration

The application expects a local LLM endpoint compatible with OpenAI's API format. See LLM Setup Guide for details.

LLM_BASE_URL=http://localhost:8001
LLM_API_KEY=
LLM_MODEL=gpt-oss-20b
LLM_MAX_REQUESTS_PER_MINUTE=10

Telegram Integration

To enable Telegram notifications:

TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

See Telegram Implementation for details.

🏗️ Project Structure

ScanningPanel/
├── apps/
│   ├── web/              # Next.js frontend
│   │   ├── src/
│   │   │   ├── app/      # App Router pages
│   │   │   ├── components/
│   │   │   └── lib/
│   │   └── package.json
│   ├── api/              # FastAPI backend
│   │   ├── app/
│   │   │   ├── api/v1/   # API endpoints
│   │   │   ├── db/       # Database models
│   │   │   └── schemas/  # Pydantic schemas
│   │   ├── alembic/      # Database migrations
│   │   └── scripts/      # Utility scripts
│   └── worker/           # Job scheduler and scanner workers
│       ├── app/
│       │   ├── scanners/ # Scanner adapters
│       │   ├── workers/  # Scan execution
│       │   ├── parsers/  # Finding parsers
│       │   └── llm/      # LLM integration
│       └── tests/
├── packages/
│   └── shared/           # Shared types and utilities
├── infra/                # Docker Compose and infrastructure
├── scripts/              # Development scripts
├── docs/                 # Documentation
└── Makefile              # Development commands

🔒 Safety Features

ScanPanel includes comprehensive safety guardrails:

• Input validation: IP, CIDR, hostname validation with public IP warnings
• Command safety: Strict argument allowlists, no shell injection
• Secret redaction: Automatic redaction of secrets in logs
• UI disclaimers: One-time modal and public IP confirmation
• Auth structure: Ready for future authentication

See Safety Implementation for details.

🧪 Demo Mode

Generate demo scans without running real tools:

make demo

This creates:

• Demo targets and scan profiles
• Sample scan with fixtures
• Example findings for UI testing

📊 Performance

• Database indexes: Optimized for common query patterns
• Eager loading: Prevents N+1 queries
• Pagination: All list endpoints support pagination
• Caching: Redis for future caching layer

🤝 Contributing

1. Add a new scanner: See Adding a New Scanner
2. Run tests: make test
3. Format code: make format
4. Check linting: make lint

📝 License

MIT