{"id":"fa4e3f60-77cd-4bd4-ae80-dcbdfd52a99c","slug":"network-scanner","kind":"mcp","name":"network-scanner","summary":"A network scanner with MCP server","owner":"bryankemp","repoUrl":"https://github.com/bryankemp/network-scanner","license":"BSD-3-Clause","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-12-07T21:36:58.000Z","addedAt":"2026-10-21T16:26:11.526Z","logoUrl":"https://avatars.githubusercontent.com/u/674219?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T07:00:05.996Z","sample":false,"url":"https://conduits.dev/tools/network-scanner","language":"Python","transports":["stdio"],"install":{"pypi":"network-scan"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Network Scanner\n\nA comprehensive network scanning and management solution with a modern web interface, RESTful API, and AI integration via Model Context Protocol (MCP).\n\n**Author:** Bryan Kemp <bryan@kempville.com>  \n**License:** BSD 3-Clause  \n**Version:** 1.0.0\n\n## 📋 Table of Contents\n\n- [Features](#features)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Architecture](#architecture)\n- [Usage](#usage)\n- [API Documentation](#api-documentation)\n- [MCP Integration](#mcp-integration)\n- [Development](#development)\n- [Testing](#testing)\n- [Deployment](#deployment)\n- [Container Registry](#container-registry)\n- [Troubleshooting](#troubleshooting)\n\n## ✨ Features\n\n### Core Scanning Capabilities\n- 🔍 **Parallel Network Scanning** - Efficient multi-network CIDR scanning\n- 🖥️ **Virtual Machine Detection** - Automatic identification of VMs and containers\n- 🔐 **Service Discovery** - Comprehensive port scanning with service/version detection\n- 🌐 **Network Topology** - Traceroute mapping and visualization\n- 📊 **OS Fingerprinting** - Operating system detection with accuracy scoring\n\n### Scheduled Scanning\n- ⏰ **Cron-based Schedules** - Create recurring scans with flexible cron expressions\n- 📅 **Pre-configured Presets** - Common schedules (hourly, daily, weekly, etc.)\n- 🔄 **Manual Trigger** - On-demand execution of scheduled scans\n\n### Reporting & Visualization\n- 📄 **HTML Reports** - Detailed, styled network scan reports\n- 📊 **Excel Exports** - Structured data in XLSX format\n- 🗺️ **Network Diagrams** - Auto-generated topology maps (PNG/SVG)\n\n### Web Interface\n- 🎨 **Modern Flutter UI** - Responsive Material Design 3 interface\n- 📱 **Mobile-Ready** - Works on desktop, tablet, and mobile\n- 🌓 **Dark/Light Themes** - Automatic theme switching\n- 🔒 **Role-based Access** - Admin and user roles\n- 🔐 **JWT Authentication** - Secure token-based authentication\n\n### AI Integration (MCP)\n- 🤖 **Claude/Warp AI Integration** - Query scan data using natural language\n- 💬 **Conversational Queries** - \"Show me all VMs\" or \"What services are running on 192.168.1.10?\"\n- 📈 **Network Statistics** - Get insights via AI assistants\n\n## 🚀 Quick Start\n\n### Automated Setup (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/network-scan.git\ncd network-scan\n\n# Set up development environment\npython3 setup.py dev\n\n# Run tests\npython3 setup.py test\n\n# Start the backend server\ncd backend\nsource venv/bin/activate\nuvicorn app.main:app --reload\n```\n\nThe API will be available at `http://localhost:8000`  \nAPI documentation at `http://localhost:8000/docs`\n\n### Docker Setup\n\n```bash\n# Build and run\npython3 setup.py docker\n\n# Or use docker-compose\ndocker-compose up -d\n```\n\n### Service Installation\n\n```bash\n# Install as system service (macOS/Linux)\npython3 setup.py service\n```\n\n## 📦 Installation\n\n### Prerequisites\n\n**Required:**\n- Python 3.8+\n- nmap\n\n**Optional:**\n- Flutter 3.9+ (for web UI)\n- Docker (for containers)\n- Graphviz (for diagrams)\n\n### Manual Installation\n\n```bash\n# Backend\ncd backend\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n\n# Frontend (optional)\ncd frontend\nflutter pub get\n\n# MCP Server\ncd mcp_server\npip install -r requirements.txt\n```\n\n## 🏗️ Architecture\n\n```\nnetwork-scan/\n├── backend/          # FastAPI REST API\n├── frontend/         # Flutter web app\n├── mcp_server/       # AI integration\n├── tests/            # Test suite\n├── setup.py          # Setup automation\n└── run_tests.py      # Test runner\n```\n\n**Tech Stack:** FastAPI, Flutter, SQLite, nmap, MCP\n\n## 💻 Usage\n\n### API Examples\n\n```bash\n# Create scan\ncurl -X POST http://localhost:8000/api/scans \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"network_range\": [\"192.168.1.0/24\"]}'\n\n# Get scan details\ncurl http://localhost:8000/api/scans/1\n\n# Download reports\ncurl http://localhost:8000/api/scans/1/artifacts/html -o report.html\ncurl http://localhost:8000/api/scans/1/artifacts/xlsx -o report.xlsx\n```\n\n### Web Interface\n\nNavigate to `http://localhost:8000`\n\n**Default Credentials:**\n- Username: `admin`\n- Password: `Admin123!`\n- **⚠️ Change on first login!**\n\n## 📚 API Documentation\n\nInteractive docs: `http://localhost:8000/docs`\n\n### Key Endpoints\n\n- `POST /api/scans` - Create scan\n- `GET /api/scans` - List scans\n- `POST /api/schedules` - Create schedule\n- `GET /api/hosts/unique` - Latest host data\n- `GET /api/stats` - Network statistics\n- `POST /api/auth/login` - Authentication\n\n## 🤖 MCP Integration\n\n### Available Tools\n\n- `list_scans` - List all scans\n- `query_hosts` - Search hosts\n- `get_host_services` - Get services for host\n- `get_network_stats` - Network statistics\n- `list_vms` - List VMs/containers\n- `search_service` - Find service on network\n\n### Configuration\n\n**Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Warp AI:** `~/.warp/mcp_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"network-scanner\": {\n      \"command\": \"python3\",\n      \"args\": [\"/path/to/network-scan/mcp_server/server.py\"],\n      \"env\": {\n        \"DATABASE_PATH\": \"/path/to/network-scan/network_scanner.db\"\n      }\n    }\n  }\n}\n```\n\n## 🛠️ Development\n\n```bash\n# Run with auto-reload\ncd backend\nsource venv/bin/activate\nuvicorn app.main:app --reload\n\n# Code quality\nblack backend/ --line-length 100\nruff check backend/\n\n# Tests\npython3 setup.py test\n```\n\n## 🧪 Testing\n\n**Total: 92 tests** (33 backend, 38 MCP, 21 frontend)\n\n```bash\n# All tests\npython3 setup.py test\n\n# Individual components\ncd backend && pytest tests/ -v\ncd mcp_server && pytest test_mcp_server.py -v\ncd frontend && flutter test\n```\n\n## 🚀 Deployment\n\n### Using Pre-built Container from GitHub Container Registry\n\nThe easiest way to run Network Scanner is using the pre-built container image:\n\n```bash\n# Pull the latest image\ndocker pull ghcr.io/bryank/network-scan:latest\n\n# Run the container\ndocker run -d \\\n  --name network-scan \\\n  --cap-add NET_RAW \\\n  --cap-add NET_ADMIN \\\n  -p 8000:8000 \\\n  -p 8001:8001 \\\n  -v $(pwd)/data/scan_outputs:/app/scan_outputs \\\n  -v $(pwd)/data/database:/app/database \\\n  ghcr.io/bryank/network-scan:latest\n```\n\n**Using docker-compose with GHCR:**\n\nCreate `docker-compose.ghcr.yml`:\n\n```yaml\nservices:\n  network-scan:\n    container_name: network-scan\n    image: ghcr.io/bryank/network-scan:latest\n    ports:\n      - \"8000:8000\"\n      - \"8001:8001\"\n    environment:\n      - PYTHONUNBUFFERED=1\n      - TZ=America/Chicago\n    volumes:\n      - ./data/scan_outputs:/app/scan_outputs\n      - ./data/database:/app/database\n    cap_add:\n      - NET_RAW\n      - NET_ADMIN\n    restart: unless-stopped\n    healthcheck:\n      test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8000/health\"]\n      interval: 30s\n      timeout: 10s\n      retries: 3\n      start_period: 40s\n```\n\nThen run:\n\n```bash\ndocker-compose -f docker-compose.ghcr.yml up -d\n```\n\n**Available Tags:**\n- `latest` - Most recent stable release\n- `v1.0.0` - Specific version\n- `main` - Latest from main branch\n\n### Building from Source\n\n```bash\npython3 setup.py docker\ndocker-compose -f docker-compose.production.yml up -d\n```\n\n## 📦 Container Registry\n\nFor detailed information about using GitHub Container Registry, building multi-architecture images, and publishing workflows, see:\n\n👉 **[CONTAINER_REGISTRY.md](CONTAINER_REGISTRY.md)** - Complete container registry guide\n\nKey topics covered:\n- Pulling and running pre-built images\n- Authentication for private registries\n- Multi-architecture support (amd64, arm64)\n- GitHub Actions automation\n- Tag strategies and best practices\n\n### System Service\n\n```bash\npython3 setup.py service\n\n# Manage service\n# macOS: launchctl list | grep network-scanner\n# Linux: sudo systemctl status network-scanner\n```\n\n### Environment Variables\n\nCreate `backend/.env`:\n\n```bash\nSECRET_KEY=your-secret-key-here\nDEBUG=False\nSCAN_PARALLELISM=8\n```\n\n## 🔧 Troubleshooting\n\n**nmap not found**\n```bash\n# macOS\nbrew install nmap\n\n# Linux\nsudo apt-get install nmap\n```\n\n**Permission denied**\n```bash\n# Linux: Grant nmap capabilities\nsudo setcap cap_net_raw,cap_net_admin+eip $(which nmap)\n```\n\n**Container Permission Issues**\n\nIf the container can't scan, ensure the container has the required capabilities:\n```bash\ndocker run --cap-add NET_RAW --cap-add NET_ADMIN ...\n```\n\n**Container Image Authentication**\n\nFor private registries or rate limiting:\n```bash\n# GitHub Container Registry\necho $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin\n\n# Then pull\ndocker pull ghcr.io/bryank/network-scan:latest\n```\n\n**Database locked**\n\nFor high concurrency, use PostgreSQL instead of SQLite.\n\n## 📄 License\n\nBSD 3-Clause License - see [LICENSE](LICENSE) file\n\n## 📞 Support\n\n- **Email:** bryan@kempville.com\n- **Issues:** GitHub Issues\n\n---\n\n**Made with ❤️ by Bryan Kemp**\n"}