sumwolf01/NetWolf-Scanner
GitHub: sumwolf01/NetWolf-Scanner
一款基于 FastAPI 与 Next.js 的自托管跨平台网络发现与安全扫描器，提供实时可视化扫描进度、主机发现、端口检测与 OS 指纹识别功能。
Stars: 0 | Forks: 0
# NetWolf Scanner
**专业的跨平台网络发现与安全扫描器**
NetWolf Scanner 是一个自托管的网络扫描平台：后端采用 FastAPI，
可进行真实的 ARP/ICMP/TCP-connect 主机发现、带有 banner grabbing 的异步 TCP/UDP 端口
扫描，以及基于 TTL 的 OS 指纹识别；前端搭配 Next.js 控制台，提供实时的 WebSocket 扫描进度。
## 功能
- **主机发现** — ARP 扫描、ICMP ping，以及在没有 raw-socket 权限的环境下的 TCP-connect 回退机制；支持反向 DNS 和 MAC 供应商信息
丰富化
- **端口扫描** — 具有可配置线程数和超时的异步 TCP/UDP 扫描，支持 top-100/top-1000/all-65535/自定义端口预设，banner
grabbing，以及内置服务名映射（HTTP, SSH, RDP, SMB, MySQL,
PostgreSQL, Redis, MongoDB, Docker, Kubernetes 等）
- **OS 指纹识别** — 带有置信度分数的基于 TTL 的启发式算法，
通过开放端口信号（例如 3389 → Windows）进行精细化调整
- **实时进度** — 基于 WebSocket 的进度条、日志尾部追踪，以及
对每个正在运行的扫描的暂停/恢复/取消控制
- **扫描历史** — 每次扫描都会将主机 + 端口持久化到 SQLite（或
Postgres），并具有收藏、删除和专用的历史记录视图
- **网络工具** — ping、traceroute、DNS/反向 DNS 查询、WHOIS、
Wake-on-LAN，以及本地网络接口/网关列表
- **身份验证** — 基于 JWT 的注册/登录；首个注册的账号将成为
工作区管理员
- **暗黑霓虹网络安全 UI** — 玻璃拟态面板，蓝/绿/紫
信号颜色系统，使用 Next.js 15 + React 19 + Tailwind 构建
## 截图
_在你针对自己的网络运行该应用后，将截图添加到 `assets/screenshots/` 目录并在此处引用它们——这是一个入门套件，而不是托管的演示，因此目前尚未提交任何截图。_
## 技术栈
| 层级 | 技术 |
|-----------|------|
| 前端 | Next.js 15, React 19, TypeScript (strict), TailwindCSS, Framer Motion, Chart.js, React Query, React Hook Form, Lucide Icons |
| 后端 | Python 3.12, FastAPI, Scapy, asyncio, SQLAlchemy (async), SQLite (支持 Postgres), WebSockets, JWT |
| 基础设施 | Docker, Docker Compose, GitHub Actions CI |
## 项目结构
```
NetWolf-Scanner/
├── backend/
│ ├── app/
│ │ ├── api/ # FastAPI routers (auth, scans, tools, websocket)
│ │ ├── core/ # config, security (JWT, password hashing)
│ │ ├── db/ # async SQLAlchemy session/engine
│ │ ├── models/ # ORM models: User, Scan, Host, Port
│ │ ├── schemas/ # Pydantic request/response schemas
│ │ └── services/ # discovery, port_scanner, os_fingerprint,
│ │ scan_orchestrator, net_tools, ws_manager
│ ├── tests/ # pytest suite (auth, scans, scanning logic)
│ ├── requirements.txt
│ └── pytest.ini
├── frontend/
│ ├── src/
│ │ ├── app/ # Next.js App Router pages
│ │ ├── components/ # AppShell, StatCard
│ │ ├── hooks/ # useScanProgress (WebSocket)
│ │ └── lib/ # typed API client, auth context
│ ├── package.json
│ └── tailwind.config.ts
├── docker/ # Dockerfiles + docker-compose (prod + dev)
├── .github/workflows/ci.yml # pytest + typecheck/lint/build + audit
├── SECURITY.md
├── CONTRIBUTING.md
└── CHANGELOG.md
```
## 安装说明
### 前置条件
- Python 3.12+
- Node.js 20+
-（可选但推荐）root/Administrator 权限或
用于 ARP/ICMP 扫描的 `CAP_NET_RAW`/`CAP_NET_ADMIN` —— 如果没有这些权限，发现过程将
自动回退到 TCP-connect 探测。
### Linux / macOS 设置
```
# 后端
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # edit JWT_SECRET_KEY before deploying anywhere real
uvicorn app.main:app --reload
# 在第二个终端中 — frontend
cd frontend
npm install
cp .env.local.example .env.local
npm run dev
```
访问 `http://localhost:3000`，注册第一个账号（将成为管理员），
然后开始扫描。
要在不以 root 身份运行整个进程的情况下授予 raw-socket 权限：
```
sudo setcap cap_net_raw,cap_net_admin=eip $(readlink -f .venv/bin/python3)
```
### Windows 设置
1. 安装 [Python 3.12+](https://www.python.org/downloads/) 和
[Node.js 20+](https://nodejs.org/)。
2. 安装 [Npcap](https://npcap.com/#download)（Scapy 在 Windows 上进行原始数据包访问时需要）。
3. 打开一个 **Administrator** PowerShell：
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
uvicorn app.main:app --reload
4. 在第二个终端中：
cd frontend
npm install
copy .env.local.example .env.local
npm run dev
如果没有 Administrator 权限，ARP/ICMP 扫描将不可用，并且
扫描器会自动回退到 TCP-connect 发现。
### Docker
```
cd docker
cp ../backend/.env.example ../backend/.env # set a real JWT_SECRET_KEY
docker compose up --build
```
这将在 `:8000` 上启动后端，并在 `:3000` 上启动前端。
`docker-compose.yml` 中的 `cap_add: [NET_RAW, NET_ADMIN]` 启用了容器内的 ARP/ICMP
扫描；如果你在权限更严格的环境中只需要 TCP-connect
发现，请将其移除。
要在本地开发中实现热重载：
```
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
```
## 使用说明
1. 注册第一个账号（自动成为管理员）。
2. 点击 **New Scan**，以 CIDR 表示法输入目标（例如
`192.168.1.0/24`），选择 **Host Discovery**、**Port Scan** 或 **Full
Scan**，然后启动。
3. 观察实时进度 —— WebSocket 会流式传输发现/端口扫描进度，
带有滚动日志，并允许你暂停、恢复或取消。
4. 发现的主机和开放端口会实时显示在扫描详情
页面上；所有内容都会持久化到扫描列表和历史记录中。
5. 在不启动完整扫描的情况下，使用 **Tools** 页面进行一次性的 ping/DNS/WHOIS/接口查询。
## API
FastAPI 会自动生成交互式 OpenAPI 文档：
- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`
- OpenAPI schema: `http://localhost:8000/openapi.json`
关键 endpoint：`POST /api/auth/register`、`POST /api/auth/login`、
`POST /api/scans`、`GET /api/scans/{id}`、`POST /api/scans/{id}/pause`、
`GET /api/scans/dashboard/stats`、`GET /api/tools/ping`，以及
`WS /ws/scans/{id}` 实时进度 socket。
## 测试
```
# 后端 — 24 个通过的测试，覆盖 auth、scan 创建/授权、
# port-list 解析，以及 OS-fingerprint 启发式算法
cd backend && pytest -v
# 前端 — 严格的 TypeScript 检查、lint，以及 production build
cd frontend && npx tsc --noEmit && npm run lint && npm run build
```
## 路线图
有关计划的工作，请参阅 [CHANGELOG.md](./CHANGELOG.md#unreleased)：交互式
网络拓扑图，PDF/CSV/HTML 报告导出，持久化的用户设置，更完善的 CI pipeline，以及 Postgres/Alembic 迁移文档。
## 贡献
请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。
## 许可证
[MIT](./LICENSE)
标签：AV绕过, FastAPI, 云存储安全, 插件系统, 操作系统指纹识别, 数据统计, 服务器安全, 测试用例, 端口扫描, 网络扫描, 计算机取证, 请求拦截, 逆向工具