Network Scanner

局域网扫描工具

一个全面的网络扫描和管理解决方案，具有现代web界面、RESTful API和通过模型上下文协议（MCP）的人工智能集成。

作者 布莱恩·肯普 \ 许可证： BSD 3-条款\ 版本： 1.0.0

📋 目录

• 特性
• 快速开始
• 安装
• 建筑
• 用法
• API 文档
• MCP集成
• 发展
• 测试
• 部署
• 容器注册表
• 故障排除

✨ 特性

核心扫描功能

• 🔍 并行网络扫描 -高效的多网络CIDR扫描
• 🖥️ 虚拟机检测 -自动识别虚拟机和容器
• 🔐 服务发现 -具有服务/版本检测功能的全面端口扫描
• 🌐 网络拓扑 -追踪路线映射和可视化
• 📊 操作系统识别 -操作系统检测，精度评分

计划扫描

• ⏰ 基于Cron的时间表 -使用灵活的cron表达式创建重复扫描
• 📅 预配置预设 -常见时间表（每小时、每天、每周等）
• 🔄 手动触发 -按需执行预定扫描

报告和可视化

• 📄 HTML报告 -详细、风格化的网络扫描报告
• 📊 Excel导出 -XLSX格式的结构化数据
• 🗺️ 将网络图 -自动生成的拓扑图（PNG/SVG）

web界面

• 🎨 现代Flutter用户界面 -响应式材料设计3界面
• 📱 移动就绪 -适用于台式机、平板电脑和移动设备
• 🌓 暗/亮主题 -自动切换主题
• 🔒 基于角色的访问 -管理员和用户角色
• 🔐 JWT认证 -基于安全令牌的身份验证

人工智能集成（MCP）

• 🤖 Claude/Warp人工智能集成 -使用自然语言查询扫描数据
• 💬 会话查询 -“显示所有虚拟机”或“192.168.1.10上正在运行哪些服务？”
• 📈 网络统计 -通过AI助手获得见解

🚀 快速开始

自动设置（推荐）

# 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

API将于 http://localhost:8000\ API文件，网址： http://localhost:8000/docs

Docker设置

# Build and run
python3 setup.py docker

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

服务安装

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

📦 安装

先决条件

必修的：

• Python 3.8+
• nmap

可选：

• Flutter 3.9+（用于web UI）
• Docker（用于容器）
• Graphviz（用于图表）

手动安装

# 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

🏗️ 建筑

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

技术栈： FastAPI、Flutter、SQLite、nmap、MCP

💻 用法

API示例

# 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界面

导航至 http://localhost:8000

默认凭据：

• 用户名： admin
• 密码： Admin123!
• ⚠️ 首次登录时更改！

📚 API 文档

交互式文档： http://localhost:8000/docs

关键终点

• POST /api/scans -创建扫描
• GET /api/scans -列表扫描
• POST /api/schedules -创建日程表
• GET /api/hosts/unique -最新主机数据
• GET /api/stats -网络统计
• POST /api/auth/login -身份验证

🤖 MCP集成

可用工具

• list_scans -列出所有扫描
• query_hosts -搜索主机
• get_host_services -获取主机服务
• get_network_stats -网络统计
• list_vms -列出虚拟机/容器
• search_service -在网络上查找服务

配置

克劳德桌面： ~/Library/Application Support/Claude/claude_desktop_config.json 扭曲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"
      }
    }
  }
}

🛠️ 发展

# 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

🧪 测试

总计：92次测试 （33个后端，38个MCP，21个前端）

# 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

🚀 部署

使用GitHub容器注册表中的预构建容器

运行Network Scanner最简单的方法是使用预构建的容器映像：

# 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

使用docker与GHCR组合：

创建 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

然后运行：

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

可用标签：

• latest -最新稳定版本
• v1.0.0 -具体版本
• main -主分行最新消息

从源头构建

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

📦 容器注册表

有关使用GitHub容器注册表、构建多架构映像和发布工作流的详细信息，请参阅：

👉 CONTAINER_REGISTRY.md -完整的容器注册表指南

涵盖的关键主题：

• 提取并运行预构建的图像
• 私有注册表的身份验证
• 多架构支持（amd64、arm64）
• GitHub操作自动化
• 标记策略和最佳实践

系统服务

python3 setup.py service

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

环境变量

创建 backend/.env:

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

🔧 故障排除

未找到nmap

# macOS
brew install nmap

# Linux
sudo apt-get install nmap

权限不足

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

集装箱许可问题

如果容器无法扫描，请确保容器具有所需的功能：

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

容器图像身份验证

对于私人注册或限速：

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

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

数据库锁

为了实现高并发性，请使用PostgreSQL而不是SQLite。

📄 许可证

BSD 3条款许可证-请参阅 许可证 文件

📞 支持

• 电子邮件： bryan@kempville.com
• 问题： GitHub问题

______________________________________________________________________

由以下材料制成❤️ 作者：布莱恩·肯普