miladhzzzz/nuclei-api
GitHub: miladhzzzz/nuclei-api
Nuclei API：AI增强的自动化漏洞扫描和模板管理平台
Stars: 3 | Forks: 1
# Nuclei API：自动化漏洞模板生成与扫描平台
## 概述
**Nuclei API** 是一个围绕 [Nuclei](https://nuclei.projectdiscovery.io/) 构建的先进、AI增强的自动化漏洞扫描和模板管理平台。它提供了一个REST API，用于运行扫描、管理模板以及编排一个管道，该管道可以获取新的漏洞，使用LLM生成检测模板，验证它们，并在需要时进行细化。该系统利用FastAPI、Celery、Redis、Docker和Ollama（LLM）来提供可扩展、智能和自动化的安全扫描。
## 关键特性
- **自动化CVE模板生成**：
从公共来源获取最新的漏洞（CVE），并使用LLM为每个漏洞生成Nuclei YAML模板。
- **模板验证与细化**：
通过在已知易受攻击的主机上运行模板来验证生成的模板。如果验证失败，则使用LLM细化模板并重试。
- **灵活的扫描API**：
公开端点以在目标（IP/域名）上运行Nuclei扫描，支持自定义模板、AI生成的模板和标准模板。
- **自定义模板扫描**：
通过base64编码的内容或文件上传上传并扫描您自己的Nuclei YAML模板。
- **AI驱动扫描**：
使用描述您想要检测的漏洞的自然语言提示生成和运行自定义模板。
- **MCP（模型上下文协议）集成**：
与可发现工具和标准化的工具调用接口完全集成LLM/代理，用于AI驱动的安全工作流程。
- **异步管道**：
使用Celery进行分布式、异步任务编排（获取、生成、验证、细化）。
- **指标与缓存**：
使用Redis缓存漏洞数据并跟踪管道指标。
- **容器化扫描**：
在Docker容器中运行Nuclei扫描以实现隔离和资源控制。
- **实时日志流**：
直接从运行的Docker容器中流式传输扫描日志。
- **现代Web UI**：
Next.js前端与TypeScript、Tailwind CSS和Radix UI组件相结合，提供专业的用户体验。
- **可扩展与模块化**：
具有面向服务的架构的Docker、Nuclei、指纹识别和模板的模块化控制器。
- **生产就绪的Docker设置**：
多阶段构建、优化镜像和全面的Docker Compose配置，易于部署。
## 架构
```
flowchart TD
subgraph User
A1[API Client / UI / LLM Agent]
end
subgraph API
B1[FastAPI App]
B2[NucleiRoutes]
B3[PipelineRoutes]
B4[MCP Routes]
end
subgraph ServiceLayer
S1[ScanService]
S2[TemplateService]
end
subgraph Celery
C1[fetch_vulnerabilities]
C2[process_vulnerabilities]
C3[generate_nuclei_template]
C4[store_templates]
C5[validate_template]
C6[refine_nuclei_template]
C7[run_scan]
C8[run_ai_scan]
end
subgraph Infra
D1[Ollama LLM]
D2[Redis]
D3[Docker Engine]
D4[Nuclei Scanner]
D5[FileSystem]
end
A1--REST/MCP-->B1
B1--routes-->B2
B1--routes-->B3
B1--routes-->B4
B2--calls-->S1
B2--calls-->S2
B3--calls-->S1
B3--calls-->S2
B4--calls-->S1
B4--calls-->S2
S1--orchestrates-->Celery
S2--orchestrates-->Celery
C1--uses-->D2
C2--uses-->D1
C3--uses-->D1
C4--stores-->D5
C5--runs-->D4
C5--in-->D3
C5--metrics-->D2
C6--uses-->D1
C7--runs-->D4
C8--runs-->D4
D4--runs in-->D3
```
### 描述
- **用户/代理**：通过REST或MCP端点（用于LLM/代理集成）交互。
- **API层**：模块化FastAPI路由器：
- `NucleiRoutes`（扫描、模板管理）
- `PipelineRoutes`（管道/指标）
- `MCP Routes`（LLM/代理工具清单和工具调用）
- **服务层**：`ScanService`、`TemplateService`封装业务逻辑，编排Celery管道，并与控制器交互。
- **Celery任务**：处理异步、分布式工作（获取、生成、验证、扫描、细化）。
- **控制器**：Docker、Nuclei等无状态适配器（为简洁起见，图中未显示）。
- **模型**：所有API和内部数据的Pydantic模型。
- **基础设施**：Redis（缓存/指标）、Docker（隔离）、Ollama LLM（模板生成/细化）、Nuclei（扫描）、FileSystem（模板存储）。
### API结构
- `app/api/NucleiRoutes.py` — 主要扫描/模板端点
- `app/api/PipelineRoutes.py` — 管道/指标端点
- `app/api/mcp_routes.py` — MCP端点，用于LLM/代理集成
- `app/services/` — 业务逻辑
- `app/models/` — Pydantic模型
- `app/celery_tasks/` — Celery任务定义
- `app/controllers/` — 外部系统适配器
## 管道流程
```
flowchart TD
A[fetch_vulnerabilities] --> B[process_vulnerabilities]
B --> C[generate_nuclei_templates_group]
C --> D[store_templates]
D --> E[validate_templates_callback_group]
E --> F[validate_template_per_template]
F --fail--> G[refine_nuclei_template]
G --> H[store_refined_template]
H --> F
F --success--> I[Done]
```
## 安装说明
### 前置条件
- **Python 3.8+**
- **Docker & Docker Compose**
- **Redis**
- **Ollama（或兼容的LLM API）**
- **Node.js 18+ & pnpm**（用于前端开发）
- **make**
### 克隆仓库
```
git clone
cd nuclei-api
```
### 使用Makefile快速开始
```
# 显示所有可用命令
make help
# 安装后端依赖
make install
# 启动全栈（Docker Compose）
make compose-up
# 跟踪日志
make compose-logs
# 停止栈
make compose-down
```
## Docker部署
### 生产部署
```
# 构建并启动所有服务
make compose-up
# 查看日志
make compose-logs
# 如有需要扩展服务
docker compose -f docker-compose.yml up -d --scale celery_worker=3
```
### 包含的服务
Docker Compose设置包括以下服务：
- **nuclei-api**（端口8000）：主要FastAPI应用程序
- **redis**（端口6379）：Celery的缓存和消息代理
- **celery_worker**：后台任务处理，用于扫描和模板生成
- **celery_beat**：任务调度器，用于自动生成模板
- **flower**（端口5555）：Celery监控和任务管理UI
- **ollama**（端口11434）：LLM服务，用于模板生成和细化
- **open-webui**（端口3331）：Ollama模型管理的Web界面
- **nuclei-fingerprint**（端口3330）：操作系统指纹识别服务
- **loki**（端口3100）：日志聚合和监控
### 阶段环境
```
# 使用预发布配置
docker compose -f docker-compose.staging.yaml up -d
```
### 服务管理
```
# 查看服务状态
make compose-ps
# 查看特定服务的日志
docker compose -f docker-compose.yml logs -f nuclei-api
# 重启特定服务
docker compose -f docker-compose.yml restart celery_worker
# 在高负载时扩展工作者
docker compose -f docker-compose.yml up -d --scale celery_worker=5
```
### 选项2：开发设置
#### 安装Python依赖项
```
make install
```
#### 克隆Nuclei模板
```
make templates-clone
```
#### 启动Redis和Ollama
```
docker compose -f docker-compose.yml up -d redis ollama
```
#### 运行API
```
make run-api
```
#### 运行Celery Worker和Beat
```
make run-worker
make run-beat
```
#### 运行前端（可选）
```
make install-frontend
pnpm --dir frontend dev
```
本地API（uvicorn）在 `http://localhost:8080` 上运行。
Docker Compose公开API在 `http://localhost:8000` 上。
前端在 `http://localhost:3000` 上运行。
## 使用示例
### 1. **触发自动化模板生成管道**
```
curl -X GET http://localhost:8080/nuclei/templates/generate
```
这将获取新的CVE，使用LLM生成模板，存储并验证它们。
### 2. **运行扫描（API**）
#### 基本扫描
```
curl -X POST \
-H "Content-Type: application/json" \
-d '{ "target": "https://example.com", "scan_type": "standard", "templates": ["cves/"] }' \
http://localhost:8080/nuclei/scans
```
#### AI扫描
```
curl -X POST \
-H "Content-Type: application/json" \
-d '{ "target": "https://example.com", "prompt": "Scan for SQLi" }' \
http://localhost:8080/nuclei/scans/ai
```
#### 获取扫描日志
```
curl http://localhost:8080/nuclei/containers/nuclei_scan_123456/logs
```
## API端点
### 健康检查
- **GET /**
返回 `{ "ping": "pong!" }`
### 运行扫描
- **POST /nuclei/scans**
请求：
{
"target": "https://example.com",
"scan_type": "standard",
"templates": ["cves/"] // 可选
}
响应：
返回异步扫描执行的任务ID。
### 运行AI扫描
- **POST /nuclei/scans/ai**
请求：
{
"target": "https://example.com",
"prompt": "生成一个用于XSS的模板"
}
### 兼容性扫描端点（向后兼容）
- **POST /nuclei/scan**
为旧客户端保留的旧别名。
### 获取任务状态
- **GET /nuclei/tasks/{task_id}**
获取Celery任务和扫描容器的状态/结果。
### 获取容器日志
- **GET /nuclei/containers/{container_id}/logs**
从运行的扫描容器中流式传输日志。
### 获取容器状态
- **GET /nuclei/containers/{container_name}/status**
返回容器的运行/退出/错误状态。
### 指纹目标
- **POST /nuclei/fingerprints**
排队独立目标指纹识别。
### 上传自定义模板
- **POST /nuclei/templates/upload**
上传并验证自定义Nuclei模板文件。
### 验证模板内容
- **POST /nuclei/templates/validate**
异步验证模板内容。
### 触发模板生成管道
- **GET /nuclei/templates/generate**
启动完整的CVE到模板管道。
### Prometheus指标
- **GET /metrics**
Prometheus兼容的指标端点，用于监控和警报。
返回包括以下指标的指标：
- HTTP请求计数、持续时间和大小的指标
- Celery任务执行指标
- Nuclei扫描性能和结果
- 模板生成和验证统计信息
- 系统资源使用情况（CPU、内存、磁盘）
- Redis操作和内存使用
- 自定义业务指标（活动扫描、可用的模板）
- **GET /health**
带有基本指标和服务状态的健康检查端点。
返回：
{
"status": "healthy",
"timestamp": 1234567890.123,
"services": {
"redis": "healthy",
"system": "healthy",
"api": "healthy"
},
"metrics": {
"active_scans": 5,
"cpu_usage": 45.2,
"memory_usage": 1073741824,
"redis_memory": 52428800
}
}
### Prometheus配置
将以下内容添加到您的 `prometheus.yml`：
```
scrape_configs:
- job_name: 'nuclei-api'
static_configs:
- targets: ['localhost:8000']
metrics_path: '/metrics'
scrape_interval: 15s
```
## MCP（模型上下文协议）端点
API通过模型上下文协议（MCP）公开端点，用于LLM/代理集成：
- **GET /v1/tools**
返回所有可用工具（API操作）及其参数模式清单，用于代理/LLM发现。
- **POST /v1/tool-calls**
允许代理或LLM通过名称调用任何支持的工具，将参数作为JSON对象传递。返回结果或错误。
**示例：**
```
curl -X POST \
-H "Content-Type: application/json" \
-d '{ "tool_name": "nuclei_scan", "arguments": { "target": "https://example.com" } }' \
http://localhost:8080/v1/tool-calls
```
MCP端点在 `app/api/mcp_routes.py` 中实现，并在 `main.py` 中注册。
### 监控与调试
- **Flower仪表板**：`http://localhost:5555` - 监控Celery任务和工作进程
- **Open WebUI**：`http://localhost:3331` - 管理Ollama模型和聊天
- **Loki日志**：`http://localhost:3100` - 集中日志
- **API文档**：`http://localhost:8000/docs` - 交互式API文档
- **Grafana仪表板**：`http://localhost:3000` - 综合监控仪表板（admin/admin）
- **Prometheus**：`http://localhost:9090` - 指标收集和查询
### Grafana仪表板功能
Nuclei API仪表板提供以下面板的综合监控：
#### **API性能**
- HTTP请求速率和持续时间
- 响应大小和错误率
- API端点使用模式
#### **Celery任务监控**
- 任务执行速率和持续时间
- 队列大小和工作进程状态
- 任务成功/失败率
#### **Nuclei扫描指标**
- 扫描执行速率和持续时间
- 漏洞发现跟踪
- 模板使用统计信息
#### **模板管道**
- 模板生成和验证速率
- 管道执行统计信息
- CVE的成功/失败率
#### **系统资源**
- CPU、内存和磁盘使用情况
- Redis内存和连接指标
- Docker容器统计信息
#### **业务指标**
- 活动扫描计数
- 可用的模板类型
- 错误率和系统健康
### 仪表板设置
1. **访问Grafana**：导航到 `http://localhost:3000`
2. **登录**：使用 `admin/admin`（在生产中更改）
3. **仪表板**：Nuclei API仪表板自动加载
4. **自定义**：修改面板、添加警报或创建新的仪表板
### 警报设置
在Grafana中配置以下警报：
- 高错误率（>5%持续5分钟）
- Celery工作进程计数低（<1持续5分钟）
- 系统资源使用率高（>80% CPU/内存）
- 扫描失败（>10%失败率）
## API结构 & 组织
- **app/api/NucleiRoutes.py**：主要Nuclei扫描/模板API端点
- **app/api/PipelineRoutes.py**：管道和指标端点
- **app/api/mcp_routes.py**：MCP端点，用于LLM/代理集成
- **app/services/**：业务逻辑和编排
- **app/models/**：用于请求/响应验证的Pydantic模型
- **app/celery_tasks/**：Celery任务定义
- **app/controllers/**：外部系统（Docker、Nuclei等）的无状态控制器
Routers在 `main.py` 中使用新的导入路径导入并注册（例如，`from app.api.NucleiRoutes import router as nuclei_router`）。
## 指标 & 监控
- **Redis** 用于缓存漏洞数据并跟踪管道指标（生成的模板、验证、细化、失败等）。
- **Sentry** 集成可用于错误监控（通过环境配置）。
- **管道指标**：跟踪模板生成成功率、验证尝试和扫描性能。
- **实时仪表板**：通过Web界面监控系统健康和性能。
## 扩展 & 定制
- 通过编辑 `fetch_vulnerabilities` 任务添加新的漏洞来源。
- 通过配置更改LLM模型或端点。
- 集成您自己的UI或直接使用提供的API。
- 通过扩展工具清单和处理程序添加新的MCP工具。
- 通过修改服务层自定义扫描工作流程。
- 通过添加新组件和页面扩展前端。
## 贡献
欢迎贡献！请为错误修复、新功能或改进打开问题或拉取请求。
### 开发指南
1. **代码风格**：遵循PEP 8（Python）和ESLint（TypeScript）。
2. **测试**：为新功能和API端点添加测试。
3. **文档**：更新README并添加新函数的docstrings。
4. **Docker**：确保更改与提供的Docker设置兼容。
## 许可证
[MIT](LICENSE) 或如仓库中指定。
## 联系
有关更多详细信息或支持，请联系开发团队。
标签：AI增强, AI风险缓解, AV绕过, Celery, CVE模板, Docker, FastAPI, Google, LLM, LLM评估, NIDS, Nuclei, Ollama, Redis, Unmanaged PE, 安全防御评估, 容器化, 异步处理, 搜索引擎查询, 日志流, 模板管理, 模板验证, 缓存, 自动化攻击, 请求拦截