Network Scanner

A comprehensive network scanning and management solution with a modern web interface, RESTful API, and AI integration via Model Context Protocol (MCP).

Author: Bryan Kemp bryan@kempville.com
License: BSD 3-Clause
Version: 1.0.0

📋 Table of Contents

• Features
• Quick Start
• Installation
• Architecture
• Usage
• API Documentation
• MCP Integration
• Development
• Testing
• Deployment
• Container Registry
• Troubleshooting

✨ Features

Core Scanning Capabilities

• 🔍 Parallel Network Scanning - Efficient multi-network CIDR scanning
• 🖥️ Virtual Machine Detection - Automatic identification of VMs and containers
• 🔐 Service Discovery - Comprehensive port scanning with service/version detection
• 🌐 Network Topology - Traceroute mapping and visualization
• 📊 OS Fingerprinting - Operating system detection with accuracy scoring

Scheduled Scanning

• ⏰ Cron-based Schedules - Create recurring scans with flexible cron expressions
• 📅 Pre-configured Presets - Common schedules (hourly, daily, weekly, etc.)
• 🔄 Manual Trigger - On-demand execution of scheduled scans

Reporting & Visualization

• 📄 HTML Reports - Detailed, styled network scan reports
• 📊 Excel Exports - Structured data in XLSX format
• 🗺️ Network Diagrams - Auto-generated topology maps (PNG/SVG)

Web Interface

• 🎨 Modern Flutter UI - Responsive Material Design 3 interface
• 📱 Mobile-Ready - Works on desktop, tablet, and mobile
• 🌓 Dark/Light Themes - Automatic theme switching
• 🔒 Role-based Access - Admin and user roles
• 🔐 JWT Authentication - Secure token-based authentication

AI Integration (MCP)

• 🤖 Claude/Warp AI Integration - Query scan data using natural language
• 💬 Conversational Queries - "Show me all VMs" or "What services are running on 192.168.1.10?"
• 📈 Network Statistics - Get insights via AI assistants

🚀 Quick Start

Automated Setup (Recommended)

# Clone the repository
git clone https://github.com/yourusername/network-scan.git
cd network-scan

# Set up development environment
python3 setup.py dev

# Run tests
python3 setup.py test

# Start the backend server
cd backend
source venv/bin/activate
uvicorn app.main:app --reload

The API will be available at http://localhost:8000
API documentation at http://localhost:8000/docs

Docker Setup

# Build and run
python3 setup.py docker

# Or use docker-compose
docker-compose up -d

Service Installation

# Install as system service (macOS/Linux)
python3 setup.py service

📦 Installation

Prerequisites

Required:

• Python 3.8+
• nmap

Optional:

• Flutter 3.9+ (for web UI)
• Docker (for containers)
• Graphviz (for diagrams)

Manual Installation

# Backend
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Frontend (optional)
cd frontend
flutter pub get

# MCP Server
cd mcp_server
pip install -r requirements.txt

🏗️ Architecture

network-scan/
├── backend/          # FastAPI REST API
├── frontend/         # Flutter web app
├── mcp_server/       # AI integration
├── tests/            # Test suite
├── setup.py          # Setup automation
└── run_tests.py      # Test runner

Tech Stack: FastAPI, Flutter, SQLite, nmap, MCP

💻 Usage

API Examples

# Create scan
curl -X POST http://localhost:8000/api/scans \
  -H "Content-Type: application/json" \
  -d '{"network_range": ["192.168.1.0/24"]}'

# Get scan details
curl http://localhost:8000/api/scans/1

# Download reports
curl http://localhost:8000/api/scans/1/artifacts/html -o report.html
curl http://localhost:8000/api/scans/1/artifacts/xlsx -o report.xlsx

Web Interface

Navigate to http://localhost:8000

Default Credentials:

• Username: admin
• Password: Admin123!
• ⚠️ Change on first login!

📚 API Documentation

Interactive docs: http://localhost:8000/docs

Key Endpoints

• POST /api/scans - Create scan
• GET /api/scans - List scans
• POST /api/schedules - Create schedule
• GET /api/hosts/unique - Latest host data
• GET /api/stats - Network statistics
• POST /api/auth/login - Authentication

🤖 MCP Integration

Available Tools

• list_scans - List all scans
• query_hosts - Search hosts
• get_host_services - Get services for host
• get_network_stats - Network statistics
• list_vms - List VMs/containers
• search_service - Find service on network

Configuration

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json Warp AI: ~/.warp/mcp_config.json

{
  "mcpServers": {
    "network-scanner": {
      "command": "python3",
      "args": ["/path/to/network-scan/mcp_server/server.py"],
      "env": {
        "DATABASE_PATH": "/path/to/network-scan/network_scanner.db"
      }
    }
  }
}

🛠️ Development

# Run with auto-reload
cd backend
source venv/bin/activate
uvicorn app.main:app --reload

# Code quality
black backend/ --line-length 100
ruff check backend/

# Tests
python3 setup.py test

🧪 Testing

Total: 92 tests (33 backend, 38 MCP, 21 frontend)

# All tests
python3 setup.py test

# Individual components
cd backend && pytest tests/ -v
cd mcp_server && pytest test_mcp_server.py -v
cd frontend && flutter test

🚀 Deployment

Using Pre-built Container from GitHub Container Registry

The easiest way to run Network Scanner is using the pre-built container image:

# Pull the latest image
docker pull ghcr.io/bryank/network-scan:latest

# Run the container
docker run -d \
  --name network-scan \
  --cap-add NET_RAW \
  --cap-add NET_ADMIN \
  -p 8000:8000 \
  -p 8001:8001 \
  -v $(pwd)/data/scan_outputs:/app/scan_outputs \
  -v $(pwd)/data/database:/app/database \
  ghcr.io/bryank/network-scan:latest

Using docker-compose with GHCR:

Create docker-compose.ghcr.yml:

services:
  network-scan:
    container_name: network-scan
    image: ghcr.io/bryank/network-scan:latest
    ports:
      - "8000:8000"
      - "8001:8001"
    environment:
      - PYTHONUNBUFFERED=1
      - TZ=America/Chicago
    volumes:
      - ./data/scan_outputs:/app/scan_outputs
      - ./data/database:/app/database
    cap_add:
      - NET_RAW
      - NET_ADMIN
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Then run:

docker-compose -f docker-compose.ghcr.yml up -d

Available Tags:

• latest - Most recent stable release
• v1.0.0 - Specific version
• main - Latest from main branch

Building from Source

python3 setup.py docker
docker-compose -f docker-compose.production.yml up -d

📦 Container Registry

For detailed information about using GitHub Container Registry, building multi-architecture images, and publishing workflows, see:

👉 CONTAINER_REGISTRY.md - Complete container registry guide

Key topics covered:

• Pulling and running pre-built images
• Authentication for private registries
• Multi-architecture support (amd64, arm64)
• GitHub Actions automation
• Tag strategies and best practices

System Service

python3 setup.py service

# Manage service
# macOS: launchctl list | grep network-scanner
# Linux: sudo systemctl status network-scanner

Environment Variables

Create backend/.env:

SECRET_KEY=your-secret-key-here
DEBUG=False
SCAN_PARALLELISM=8

🔧 Troubleshooting

nmap not found

# macOS
brew install nmap

# Linux
sudo apt-get install nmap

Permission denied

# Linux: Grant nmap capabilities
sudo setcap cap_net_raw,cap_net_admin+eip $(which nmap)

Container Permission Issues

If the container can't scan, ensure the container has the required capabilities:

docker run --cap-add NET_RAW --cap-add NET_ADMIN ...

Container Image Authentication

For private registries or rate limiting:

# GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# Then pull
docker pull ghcr.io/bryank/network-scan:latest

Database locked

For high concurrency, use PostgreSQL instead of SQLite.

📄 License

BSD 3-Clause License - see LICENSE file

📞 Support

• Email: bryan@kempville.com
• Issues: GitHub Issues

---

Made with ❤️ by Bryan Kemp