styliteag/open-port-monitor
GitHub: styliteag/open-port-monitor
分布式网络端口扫描与监控系统，支持多站点部署、SSH安全审计和实时告警。
Stars: 0 | Forks: 0
# Open Port 监控
用于安全用途的分布式网络端口扫描与监控系统，支持多站点扫描器、告警功能和 Web 仪表板。
## 功能特性
- **端口扫描**：基于 Masscan 的高速端口扫描，支持服务检测
- **SSH 安全分析**：自动化 SSH 服务器安全审计，包括：
- 认证方式检测（publickey、password、keyboard-interactive）
- 弱加密算法和密钥交换算法检测
- SSH 版本跟踪及过时版本告警
- 扫描间的配置回退检测
- **多站点扫描**：在不同位置部署扫描器 Agent
- **告警功能**：针对新端口、策略违规和 SSH 安全问题的可配置告警
- **合规报告**：导出 SSH 安全合规性的 PDF 和 CSV 报告
- **Web 仪表板**：基于 React 的 UI，支持深色模式
## 快速开始
### 前置条件
- Docker 和 Docker Compose
- Git
### 开发环境设置
1. 克隆仓库：
git clone
cd open-port-monitor
2. 复制环境文件并进行配置：
cp .env.example .env
# 根据您的偏好设置编辑 .env
3. 启动开发环境：
docker compose -f compose-dev.yml up --build
4. 访问服务：
- 前端：http://localhost:5173
- 后端 API：http://localhost:8000
- API 文档：http://localhost:8000/docs
- 数据库：localhost:3306
### 服务
| Service | Port | Description |
|----------|------|--------------------------------------|
| frontend | 5173 | React + Vite web dashboard |
| backend | 8000 | FastAPI REST API |
| db | 3306 | MariaDB database |
| scanner | - | Masscan-based network scanner agent |
### 开发
开发环境使用绑定挂载（bind mounts）实现热重载：
- `./backend/src` -> `/app/src`（后端）
- `./frontend/src` -> `/app/src`（前端）
- `./scanner/src` -> `/app/src`（扫描器）
源文件的更改将自动触发重载。
### 运行测试
#### 后端测试
后端使用 pytest 并支持异步（async）的完整测试套件。
```
cd backend
# 安装 dev dependencies (如果尚未安装)
uv pip install -e ".[dev]"
# 运行所有 tests
.venv/bin/pytest tests/ -v
# 运行特定 test file
.venv/bin/pytest tests/test_auth.py -v
# Run with coverage
.venv/bin/pytest tests/ --cov=app --cov-report=term-missing
```
测试分类：
- `test_security.py` - 密码哈希、JWT token 处理
- `test_auth.py` - 认证端点
- `test_users.py` - 用户管理
- `test_networks.py` - 网络 CRUD 操作
- `test_scans.py` - 扫描生命周期管理
- `test_alerts.py` - 告警操作
#### 前端测试
前端使用 Vitest 和 React Testing Library。
```
cd frontend
# 安装 dependencies (如果尚未安装)
npm install
# 运行所有 tests
npm test
# Run tests in watch mode
npm run test:watch
# Run with coverage
npm run test:coverage
```
测试分类：
- `api.test.ts` - API 工具、错误处理、fetch 封装
- `scanEstimate.test.ts` - 扫描估算计算（CIDR 解析、端口计数）
- `scanLogs.test.ts` - 日志格式化和日期解析工具
- `formatRelativeTime.test.ts` - 相对时间格式化（例如 "5m ago"）
- `ThemeContext.test.tsx` - 主题提供者、localStorage 持久化
- `AuthContext.test.tsx` - 认证 Hook、登录/登出流程
- `ProtectedRoute.test.tsx` - 路由守卫组件
### 环境变量
有关所有可用的配置选项，请参阅 `.env.example`。
关键变量：
- `JWT_SECRET`：用于 JWT token 签名的密钥（生产环境中请务必修改！）
- `ADMIN_EMAIL` / `ADMIN_PASSWORD`：初始管理员凭据
- `SMTP_*`：用于告警的邮件配置
## 运行扫描器 Agent
扫描器 Agent 可以部署在不同的主机上，以连接到您的主 Open Port Monitor 服务器。这实现了从多个位置进行的分布式扫描。
### 前置条件
- 扫描器主机上已安装 Docker
- 来自主服务器的 API 密钥（通过 Web 仪表板或 API 创建）
- 到主服务器后端 API 的网络连接
### 方式 1：Docker Run
首先，（从项目根目录）构建扫描器镜像：
```
docker build -f scanner/Dockerfile --build-arg VERSION=$(cat VERSION) -t opm-scanner:latest scanner
```
或者使用 Registry 中的预构建镜像：
```
docker pull your-registry/open-port-monitor-scanner:latest
```
然后运行扫描器：
```
docker run -d \
--name opm-scanner \
--cap-add=NET_RAW \
--cap-add=NET_ADMIN \
--restart unless-stopped \
-e BACKEND_URL=https://your-server.com:8000 \
-e API_KEY=your-api-key-here \
-e POLL_INTERVAL=60 \
-e LOG_LEVEL=INFO \
opm-scanner:latest
```
**必需的环境变量：**
- `BACKEND_URL`：主服务器后端 API 的完整 URL（例如 `https://monitor.example.com:8000`）
- `API_KEY`：从主服务器获取的扫描器 API 密钥
**可选的环境变量：**
- `POLL_INTERVAL`：任务轮询之间的秒数（默认值：60）
- `LOG_LEVEL`：日志级别 - DEBUG、INFO、WARNING、ERROR（默认值：INFO）
### 方式 2：Docker Compose
1. 进入扫描器目录：
cd scanner
2. 使用您的配置创建一个 `.env` 文件：
cat > .env << EOF
BACKEND_URL=https://your-server.com:8000
API_KEY=your-api-key-here
POLL_INTERVAL=60
LOG_LEVEL=INFO
EOF
3. 启动扫描器：
docker compose up -d
4. 查看日志：
docker compose logs -f
扫描器将自动连接到您的主服务器并开始处理扫描任务。
**注意：** 扫描器需要 `NET_RAW` 和 `NET_ADMIN` 权限才能执行网络扫描。这些权限已在 compose 文件中自动配置。
## 架构
```
+-------------+ +---------+ +----------+
| Frontend |<--->| Backend |<--->| Database |
| (React/Vite)| | (FastAPI)| | (MariaDB)|
+-------------+ +---------+ +----------+
^
|
+----------+----------+
| | |
+--------+ +--------+ +--------+
|Scanner1| |Scanner2| |Scanner3|
+--------+ +--------+ +--------+
(Distributed at different sites)
```
## 文档
有关完整的文档，请参阅 [docs 文件夹](docs/README.md)：
- **[API 参考](docs/README.md#api-reference)** - 完整的 API 文档
- **[扫描器文档](docs/README.md#scanner-documentation)** - 部署和操作指南
- **[开发指南](docs/README.md#development)** - 设置和贡献指南
## 许可证
MIT
标签：AV绕过, Docker, FastAPI, HTTP/HTTPS抓包, MariaDB, Masscan, Qt框架, React, SOC, SSH安全分析, Syscalls, Vite, Web仪表盘, 分布式监控, 加密算法审计, 占用监测, 合规报告, 告警系统, 多站点管理, 子域名侦测, 安全规则引擎, 安全防御评估, 态势感知, 插件系统, 数据统计, 暗黑模式, 服务识别, 端口扫描, 网络安全, 请求拦截, 资产管理, 逆向工具, 防御监控, 隐私保护