styliteag/opm
GitHub: styliteag/opm
一个集成端口扫描、漏洞检测与告警的分布式监控平台，解决多站点网络可视与安全合规问题。
Stars: 0 | Forks: 0
# STYLiTE Orbit Monitor
用于安全目的、分布式网络端口扫描和监控系统，支持多站点扫描器、告警和 Web 仪表板。
## 功能
- **端口扫描**：基于 Masscan 和 Nmap 的大规模端口扫描与服务识别
- **NSE 漏洞扫描**：Nmap 脚本引擎集成，用于 CVE 检测和漏洞评估
- **22 种内置扫描配置文件**：快速扫描、完整漏洞扫描、Web 应用、基础设施、SSL/TLS 审计
- **独立检查**：EternalBlue、Shellshock、Heartbleed、SQL 注入、XSS 等
- **克隆并自定义配置文件或从头创建新配置**
- **自动从扫描结果提取 CVE 并生成告警**
- **SSH 安全分析**：自动 SSH 服务器安全审计，包括：
- 认证方法检测（publickey、password、keyboard-interactive）
- 弱加密算法和密钥交换算法检测
- SSH 版本跟踪与过期版本告警
- 扫描间配置回归检测
- **多站点扫描**：在不同位置部署扫描器代理
- **Greenbone（GVM）漏洞扫描**：可选的 Greenbone 社区版集成，用于全面的漏洞评估
- 通过 `python-gvm` Unix 套接字桥接连接——无需 Web UI
- 扫描配置预设：完整且快速、完整且深入、发现、系统发现
- 结果包含 CVSS 分数、CVE 映射、解决方案建议和质量检测
- 对中高严重性发现自动生成告警
- **告警**：针对新端口、策略违规、SSH 安全问题、NSE 查找到的漏洞以及 GVM 漏洞的可配置告警
- **合规报告**：导出 SSH 安全合规的 PDF 和 CSV 报告
- **Web 仪表板**：支持深色模式的 React 基础 UI
## 快速开始
### 先决条件
- Docker 和 Docker Compose
- Git
### 开发环境设置
1. 克隆仓库：
git clone
cd opm
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
### 服务
| 服务 | 端口 | 描述 |
|--------|------|------|
| frontend | 5173 | React + Vite Web 仪表板 |
| backend | 8000 | FastAPI REST API |
| db | 3306 | MariaDB 数据库 |
| scanner | - | 网络扫描器代理（Masscan、Nmap、NSE、Nuclei、SSH 探针、GVM） |
### 开发
开发环境使用绑定挂载以实现热重载：
- `./backend/src` -> `/app/src`（后端）
- `./frontend/src` -> `/app/src`（前端）
- `./scanner/src` -> `/app/src`（扫描器）
对源文件的更改将自动触发重载。
### 运行测试
#### 后端测试
后端拥有一个使用 pytest 并支持异步的全面测试套件。
```
cd backend
# 安装开发依赖（如尚未安装）
uv pip install -e ".[dev]"
# 运行所有测试
.venv/bin/pytest tests/ -v
# 运行特定测试文件
.venv/bin/pytest tests/test_auth.py -v
# 运行覆盖率测试
.venv/bin/pytest tests/ --cov=app --cov-report=term-missing
```
测试类别：
- `test_security.py` - 密码哈希、JWT 令牌处理
- `test_auth.py` - 认证端点
- `test_users.py` - 用户管理
- `test_networks.py` - 网络 CRUD 操作
- `test_scans.py` - 扫描生命周期管理
- `test_alerts.py` - 告警操作
#### 前端测试
前端使用 Vitest 和 React Testing Library。
```
cd frontend
# 安装依赖（如尚未安装）
npm install
# 运行所有测试
npm test
# 以监听模式运行测试
npm run test:watch
# 运行覆盖率测试
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 令牌签名的密钥（在生产环境中更改！）
- `ADMIN_EMAIL` / `ADMIN_PASSWORD`：初始管理员凭据
- `SMTP_*`：用于告警的电子邮件配置
## 运行扫描器代理
扫描器代理可以部署在与主 STYLiTE Orbit Monitor 服务器不同的主机上。这实现了从多个位置进行分布式扫描。
### 先决条件
- 已在扫描器主机上安装 Docker
- 来自主服务器的 API 密钥（通过 Web 仪表板或 API 创建）
- 与主服务器后端 API 的网络连接
### 选项 1：Docker Run
首先，从项目根目录构建扫描器镜像：
```
docker build -f scanner/Dockerfile --build-arg VERSION=$(cat VERSION) -t opm-scanner:latest scanner
```
或使用注册表中的预构建镜像：
```
docker pull your-registry/opm-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 文件中已自动配置。
## 添加 Greenbone（GVM）漏洞评估（可选）
GVM 通过 [Greenbone 社区版](https://greenbone.github.io/docs/latest/) 提供完整的漏洞评估能力。扫描器镜像包含 GVM 支持——当挂载 GVM 套接字时，扫描器会自动识别为 **unified** 并同时处理标准端口扫描和 Greenbone 漏洞评估任务。
### 扫描器类型
扫描器在启动时自动检测其能力：
| 类型 | 条件 | 能力 |
|------|------|------|
| **standard** | 未挂载 GVM 套接字 | Masscan、Nmap、NSE、Nuclei、SSH 探针 |
| **unified** | 挂载 GVM 套接字 + 存在 masscan | 所有标准工具 + GVM 漏洞扫描 |
| **gvm** | 挂载 GVM 套接字、无 masscan（`Dockerfile.gvm`） | 仅 GVM 漏洞扫描（轻量级桥接） |
单个 `Dockerfile` 同时生成标准版和统一版扫描器——区别仅在运行时（是否挂载 GVM 套接字）。
### 先决条件
- 主 OPM 堆栈正在运行（`compose.yml` 或 `compose-dev.yml`）
- 在 OPM 中创建 Scanner 记录（通过 Web 仪表板 → Scanners）并记录 API 密钥
- 足够的磁盘空间（首次同步约需 5 GB）
### 设置
1. 设置扫描器 API 密钥：
export GVM_SCANNER_API_KEY=your-api-key-here
2. 启动 GVM 堆栈：
docker compose -f compose-gvm.yml up -d
3. 等待源同步完成（首次启动耗时较长）：
docker compose -f compose-gvm.yml logs -f gvmd
4. 设置 GVM 管理员：
docker compose exec --user gvmd gvmd gvmd --user=admin --new-password=admin
# 或：docker compose -f compose-gvm.yml exec --user gvmd gvmd gvmd --user=admin --new-password=admin
5. 在 OPM Web 仪表板中，将网络的扫描器类型设置为 **Greenbone**，并选择扫描配置（例如 *完整且快速*）。
### GVM Web UI（GSA）
组成堆栈包含 Greenbone 安全助理（GSA）Web 界面，可直接访问 GVM：
```
docker compose -f compose-gvm.yml up -d gsa
```
访问地址 **http://localhost:9392** — 使用步骤 4 中设置的凭据登录（默认：`admin`/`admin`）。
GSA 端口可通过 `GVM_GSA_PORT` 环境变量修改。
### 环境变量
| 变量 | 默认值 | 描述 |
|------|--------|------|
| `GVM_SCANNER_API_KEY` | *(必需)* | 来自 OPM 的扫描器 API 密钥 |
| `GVM_BACKEND_URL` | `http://backend:8000` | OPM 后端 URL |
| `GVM_POLL_INTERVAL` | `60` | 任务轮询间隔（秒） |
| `GVM_LOG_LEVEL` | `INFO` | 日志级别 |
| `GVM_USER` | `admin` | GVM 管理员用户名 |
| `GVM_PASSWORD` | `admin` | GVM 管理员密码 |
| `GVM_GSA_PORT` | `9392` | GSA Web UI 端口 |
### 生产环境
对于生产环境，请编辑 `compose-gvm.yml` 并替换 `opm-scanner-gvm` 上的构建/镜像行：
```
# image: styliteag/opm-scanner:latest # uncomment this (same image, unified via socket)
# build: ... # comment out
```
然后设置 `GVM_BACKEND_URL=http://app:80`（生产服务名称）。
### 架构
`compose-gvm.yml` 中的扫描器使用与标准扫描器相同的镜像，但挂载了 GVM 套接字。它通过 Unix 套接字与 GVM 通信，并通过 REST API 与 OPM 通信。
```
OPM Backend <──REST──> opm-scanner (unified) <──Unix socket──> gvmd ──> ospd-openvas
```
## 架构
```
+-------------+ +---------+ +----------+
| Frontend |<--->| Backend |<--->| Database |
| (React/Vite)| | (FastAPI)| | (MariaDB)|
+-------------+ +---------+ +----------+
^
|
+----------+----------+----------+
| | | |
+--------+ +--------+ +--------+ +--------+
|Scanner1| |Scanner2| |Scanner3| |Scanner4|
| (std) | | (std) | |(unified)| | (gvm) |
+--------+ +--------+ +--------+ +--------+
(Distributed scanners) | |
+----------+ |
| gvmd |<---+
+----------+
```
## 文档
有关完整文档，请参阅 [docs 文件夹](docs/README.md)：
- **[API 参考](docs/README.md#api-reference)** - 完整的 API 文档
- **[扫描器文档](docs/README.md#scanner-documentation)** - 部署和操作指南
- **[开发文档](docs/README.md#development)** - 设置和贡献指南
## 许可证
MIT
标签：Claude, CSV报告, CTI, CVE检测, CVSS评分, Dark Mode, Docker, Docker Compose, EternalBlue, GET/POST请求分析, GraphQL引擎检测, Greenbone, GVM, Heartbleed, IOC 共享, Masscan, Nmap, NSE, PDF报告, Python, python-gvm, React, Shellshock, SOC, SSH安全, SSH审计, SSL/TLS审计, Syscalls, Unix Socket, Web仪表盘, XSS, 分布式扫描, 加密算法检测, 合规报告, 多站点扫描, 子域名侦测, 安全合规, 安全防御评估, 弱密码检测, 数据统计, 无后门, 漏洞情报, 监控平台, 端口扫描, 网络代理, 网络扫描器, 自动告警, 虚拟驱动器, 认证方法检测, 请求拦截, 质量检测, 配置回归检测