Skip to content

Commit 437c04e

Browse files
author
githubnull
committed
docs: update subproject README files
- Update src/frontEnd/README.md with enhanced features - Update src/burpEx/README.md with detailed usage guide - Update src/vulnTestServer/README.md with database structure - Create src/backEnd/README.md with complete API documentation
1 parent dadff95 commit 437c04e

File tree

4 files changed

+687
-189
lines changed

4 files changed

+687
-189
lines changed

src/backEnd/README.md

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
# SQLMap WebUI 后端
2+
3+
基于 FastAPI 构建的 SQL 注入扫描任务管理后端服务。
4+
5+
## 技术栈
6+
7+
| 类别 | 技术 | 版本 |
8+
|------|------|------|
9+
| 框架 | FastAPI | 0.100+ |
10+
| 运行时 | Python | 3.13+ |
11+
| 包管理器 | uv | latest |
12+
| 数据库 | SQLite | 3+ |
13+
| SQL注入引擎 | SQLMap | latest |
14+
| ASGI服务器 | Uvicorn | 0.30+ |
15+
16+
## 核心功能
17+
18+
### 任务管理
19+
- 创建/查询/停止/删除扫描任务
20+
- 任务状态监控
21+
- 实时日志获取
22+
- 扫描结果查询
23+
- 批量任务操作
24+
25+
### 请求头规则管理
26+
- **持久化规则**: 存储在 SQLite 数据库
27+
- CRUD 完整操作
28+
- 优先级排序 (0-100)
29+
- 多种替换策略 (REPLACE, APPEND, PREPEND, SKIP)
30+
- **会话级规则**: 基于客户端 IP 的临时规则
31+
- TTL 自动过期
32+
- 内存存储
33+
- **作用域匹配**: 灵活的 URL 匹配规则
34+
- 协议匹配 (http/https)
35+
- 主机名匹配 (支持通配符)
36+
- 端口匹配 (支持多值)
37+
- 路径匹配 (支持通配符)
38+
- 正则表达式支持
39+
40+
### 扩展集成
41+
- Chrome 扩展 API
42+
- Burp Suite 插件 API
43+
- 统一的认证机制
44+
45+
## 快速开始
46+
47+
### 环境要求
48+
49+
- Python 3.13+
50+
- uv 包管理器
51+
52+
### 安装依赖
53+
54+
```bash
55+
cd src/backEnd
56+
uv sync --extra thirdparty
57+
```
58+
59+
### 启动服务
60+
61+
```bash
62+
uv run python main.py
63+
```
64+
65+
服务将在 http://localhost:8775 启动。
66+
67+
### 访问 API 文档
68+
69+
- Swagger UI: http://localhost:8775/docs
70+
- ReDoc: http://localhost:8775/redoc
71+
72+
## 项目结构
73+
74+
```
75+
src/backEnd/
76+
├── api/ # API 路由模块
77+
│ ├── chromeExApi/ # Chrome 扩展 API
78+
│ │ └── admin.py # 任务管理接口
79+
│ ├── burpSuiteExApi/ # Burp Suite 插件 API
80+
│ │ └── admin.py # 扫描提交接口
81+
│ └── commonApi/ # 通用 API
82+
│ ├── headerController.py # 请求头规则管理
83+
│ ├── authController.py # 认证接口
84+
│ └── configController.py # 配置管理
85+
├── model/ # 数据模型
86+
│ ├── Task.py # 任务模型
87+
│ ├── TaskStatus.py # 任务状态枚举
88+
│ ├── DataStore.py # 内存数据存储(单例)
89+
│ ├── Database.py # 数据库连接
90+
│ ├── HeaderScope.py # 请求头作用域配置
91+
│ ├── PersistentHeaderRule.py # 持久化请求头规则
92+
│ ├── SessionHeader.py # 会话级请求头
93+
│ ├── HeaderDatabase.py # 请求头数据库操作
94+
│ ├── HeaderBatch.py # 批量请求头操作
95+
│ ├── BaseResponseMsg.py # 统一响应格式
96+
│ └── requestModel/ # 请求 DTO
97+
│ └── TaskRequest.py # 任务请求模型
98+
├── service/ # 业务逻辑层
99+
│ ├── taskService.py # 任务管理服务
100+
│ └── headerRuleService.py # 请求头规则服务(单例)
101+
├── utils/ # 工具函数
102+
│ ├── header_processor.py # 请求头处理器
103+
│ ├── scope_matcher.py # 作用域匹配器
104+
│ ├── header_parser.py # 请求头解析器
105+
│ ├── session_header_manager.py # 会话请求头管理
106+
│ ├── task_monitor.py # 任务监控
107+
│ ├── auth.py # 认证工具
108+
│ └── content_type_helper.py # Content-Type 处理
109+
├── third_lib/ # 第三方库
110+
│ └── sqlmap/ # SQLMap 集成 (git submodule)
111+
├── tests/ # 测试文件
112+
│ ├── test_scope_matcher.py
113+
│ ├── test_header_processor_scope.py
114+
│ └── test_api_endpoints.py
115+
├── static/ # 前端静态资源(构建输出)
116+
├── temp/ # 临时文件
117+
│ └── http_requests/ # HTTP 请求缓存
118+
├── app.py # FastAPI 应用核心
119+
├── main.py # 入口文件
120+
├── config.py # 配置文件
121+
├── pyproject.toml # 项目配置
122+
└── uvicorn_config.json # Uvicorn 配置
123+
```
124+
125+
## API 端点
126+
127+
### 任务管理 API
128+
129+
| 方法 | 端点 | 说明 |
130+
|------|------|------|
131+
| GET | `/chrome/admin/task/list` | 获取任务列表 |
132+
| POST | `/chrome/admin/task/add` | 创建任务 |
133+
| PUT | `/chrome/admin/task/stop` | 停止任务 |
134+
| DELETE | `/chrome/admin/task/delete` | 删除任务 |
135+
| PATCH | `/chrome/admin/task/flush` | 清空所有任务 |
136+
| GET | `/chrome/admin/task/logs/getLogsByTaskId` | 获取任务日志 |
137+
| GET | `/chrome/admin/task/getTaskScanOptionsByTaskId` | 获取扫描配置 |
138+
| GET | `/chrome/admin/task/getScanDataByTaskId` | 获取扫描结果 |
139+
140+
### 请求头规则 API
141+
142+
| 方法 | 端点 | 说明 |
143+
|------|------|------|
144+
| GET | `/commonApi/header/persistent-header-rules` | 获取规则列表 |
145+
| GET | `/commonApi/header/persistent-header-rules/{id}` | 获取单个规则 |
146+
| POST | `/commonApi/header/persistent-header-rules` | 创建规则 |
147+
| PUT | `/commonApi/header/persistent-header-rules/{id}` | 更新规则 |
148+
| DELETE | `/commonApi/header/persistent-header-rules/{id}` | 删除规则 |
149+
| POST | `/commonApi/header/session-headers` | 设置会话请求头 |
150+
| GET | `/commonApi/header/session-headers` | 获取会话请求头 |
151+
| DELETE | `/commonApi/header/session-headers` | 清除会话请求头 |
152+
| POST | `/commonApi/header/header-processing/preview` | 预览请求头处理 |
153+
| POST | `/commonApi/header/parse-headers-batch` | 批量解析请求头 |
154+
| POST | `/commonApi/header/create-persistent-rules-batch` | 批量创建规则 |
155+
156+
### Burp Suite API
157+
158+
| 方法 | 端点 | 说明 |
159+
|------|------|------|
160+
| POST | `/burp/admin/scan` | 提交扫描任务 |
161+
162+
### 通用 API
163+
164+
| 方法 | 端点 | 说明 |
165+
|------|------|------|
166+
| GET | `/api/version` | 获取版本信息 |
167+
| GET | `/api/health` | 健康检查 |
168+
169+
## 配置说明
170+
171+
### config.py
172+
173+
```python
174+
# 最大并发任务数
175+
MAX_TASKS_COUNT = 3
176+
177+
# 版本号
178+
VERSION = "1.6.0"
179+
```
180+
181+
### 环境变量
182+
183+
可通过 `.env` 文件配置:
184+
- 认证密钥
185+
- 日志级别
186+
- 其他敏感配置
187+
188+
## 数据存储
189+
190+
### 内存存储
191+
- 任务数据存储在 `DataStore` 单例中
192+
- 会话请求头存储在 `SessionHeaderManager`
193+
194+
### SQLite 数据库
195+
- 持久化请求头规则存储在 `header_rules.db`
196+
- 自动数据库迁移(新字段自动添加)
197+
198+
## 开发指南
199+
200+
### 添加新 API 端点
201+
202+
1.`api/` 对应模块创建路由函数
203+
2.`app.py` 中注册路由
204+
3. 如需要,在 `service/` 添加业务逻辑
205+
4.`model/` 添加数据模型
206+
207+
### 添加新服务
208+
209+
1.`service/` 创建服务类
210+
2. 使用单例模式(参考 `headerRuleService.py`
211+
3. 在 API 层调用服务
212+
213+
### 运行测试
214+
215+
```bash
216+
cd src/backEnd
217+
python -m pytest tests/ -v
218+
```
219+
220+
## 跨域配置
221+
222+
允许以下来源的跨域请求:
223+
- `localhost:5173-5176` (前端开发)
224+
- `localhost:8775` (后端)
225+
226+
配置在 `app.py` 中:
227+
```python
228+
app.add_middleware(
229+
CORSMiddleware,
230+
allow_origin_regex=r"http://(localhost|127\.0\.0\.1):(517[3-6]|8775)",
231+
allow_credentials=True,
232+
allow_methods=["*"],
233+
allow_headers=["*"]
234+
)
235+
```
236+
237+
## SQLMap 集成
238+
239+
SQLMap 作为 git submodule 集成在 `third_lib/sqlmap/`
240+
241+
```bash
242+
# 更新 SQLMap
243+
git submodule update --remote
244+
```
245+
246+
`main.py` 在启动时配置 SQLMap 导入路径。
247+
248+
## 部署说明
249+
250+
### 开发环境
251+
252+
```bash
253+
uv run python main.py
254+
```
255+
256+
### 生产环境
257+
258+
```bash
259+
uv run uvicorn app:app --host 0.0.0.0 --port 8775
260+
```
261+
262+
或使用配置文件:
263+
264+
```bash
265+
uv run uvicorn app:app --config uvicorn_config.json
266+
```
267+
268+
## 许可证
269+
270+
MIT

0 commit comments

Comments
 (0)