|
| 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