Skip to content

intermediate_guide.md

Latest commit

 

History

History
391 lines (300 loc) · 9.84 KB

intermediate_guide.md

File metadata and controls

391 lines (300 loc) · 9.84 KB
Raw

核心功能开发与调试技巧

本文档面向需要开发新功能或修改现有功能的开发者，涵盖 API 开发、前端开发、Header/Body 规则开发、调试技巧和测试指南。

1. 添加新 API 端点

1.1 后端 API 开发

以添加一个"任务备注"API 为例：

步骤 1: 创建请求模型 (src/backEnd/model/requestModel/)

# TaskNoteRequest.py
from pydantic import BaseModel, Field

class TaskNoteRequest(BaseModel):
    taskid: str = Field(..., description="任务ID")
    note: str = Field(..., min_length=1, max_length=1000, description="备注内容")

步骤 2: 创建 API 路由 (src/backEnd/api/webApi/)

# 在 admin.py 中添加
@router.put('/task/note')
async def update_task_note(
    request: TaskNoteRequest,
    current_user: dict = Depends(get_current_user)
):
    try:
        task = DataStore.get_task(request.taskid)
        if not task:
            return BaseResponseMsg(success=False, msg="任务不存在", code=404)
        task.note = request.note
        return BaseResponseMsg(success=True, msg="备注更新成功")
    except Exception as e:
        logger.error(f"Update task note error: {e}")
        return BaseResponseMsg(success=False, msg=str(e), code=500)

步骤 3: 注册路由 (src/backEnd/app.py)

# 路由已在 app.py 中通过 include_router 自动注册
# 如果创建了新文件，需要添加：
from api.webApi.newModule import router as new_router
app.include_router(new_router, prefix="/api", tags=["new-module"])

1.2 响应格式规范

所有 API 统一使用 BaseResponseMsg 格式：

class BaseResponseMsg:
    code: int      # 0/200 = 成功, 非0/非200 = 错误
    msg: str       # 消息描述
    data: Any      # 响应数据
    success: bool  # 操作是否成功

1.3 前端 API 调用

步骤 1: 添加 API 函数 (src/frontEnd/src/api/)

// 在 task.ts 中添加
export const updateTaskNote = async (taskid: string, note: string): Promise<BaseResponse> => {
  const response = await request.put('/web/admin/task/note', { taskid, note })
  return response.data
}

步骤 2: 在组件中使用

<script setup lang="ts">
import { updateTaskNote } from '@/api/task'

const saveNote = async () => {
  const res = await updateTaskNote(taskId.value, noteText.value)
  if (res.success) {
    // 处理成功
  }
}
</script>

2. 添加新前端页面

2.1 创建页面组件

# 创建新页面目录
mkdir -p src/frontEnd/src/views/NewFeature/components
<!-- src/frontEnd/src/views/NewFeature/index.vue -->
<template>
  <div class="new-feature-page">
    <h1>新功能</h1>
  </div>
</template>

<script setup lang="ts">
// Composition API with <script setup>
import { ref, onMounted } from 'vue'
</script>

<style scoped>
.new-feature-page {
  padding: 1rem;
}
</style>

2.2 注册路由

// src/frontEnd/src/router/index.ts
{
  path: '/new-feature',
  name: 'newFeature',
  component: () => import('@/views/NewFeature/index.vue'),
  meta: { requiresAuth: true, title: '新功能' },
}

2.3 添加导航菜单

在 Layout.vue 的侧边栏菜单中添加新菜单项：

<Menubar :model="menuItems">
  <!-- 添加新菜单项到 menuItems 数组 -->
</Menubar>

2.4 添加状态管理

// src/frontEnd/src/stores/newFeature.ts
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useNewFeatureStore = defineStore('newFeature', () => {
  const data = ref<Item[]>([])
  
  const fetchData = async () => {
    // API 调用
  }
  
  return { data, fetchData }
})

3. Header 规则开发

3.1 持久化 Header 规则

数据模型: src/backEnd/model/PersistentHeaderRule.py

规则数据结构：

  • rule_name: 规则名称
  • header_name: Header 名称
  • header_value: Header 值
  • replace_strategy: 替换策略 (REPLACE/APPEND/PREPEND等)
  • priority: 优先级 (0-100)
  • is_active: 是否启用
  • scope: 作用域配置（可选）

服务层: src/backEnd/service/headerRuleService.py

  • 提供完整的 CRUD 操作
  • 数据库存储在 SQLite (header_rules.db)

API 端点:

GET    /api/commonApi/header/persistent-header-rules
POST   /api/commonApi/header/persistent-header-rules
PUT    /api/commonApi/header/persistent-header-rules/:id
DELETE /api/commonApi/header/persistent-header-rules/:id

3.2 会话 Body 字段

数据模型: src/backEnd/model/SessionBodyField.py

支持的匹配策略：

  • KEYWORD: 关键字精确匹配
  • REGEX: 正则表达式匹配
  • JSONPATH: JSONPath 表达式（JSON格式）
  • XPATH: XPath 表达式（XML格式）

支持的替换策略：

  • REPLACE: 完全替换
  • APPEND: 追加
  • PREPEND: 前置
  • CONDITIONAL: 条件替换
  • UPSERT: 存在则替换，不存在则新增

处理器: src/backEnd/utils/body_field_processor.py

  • Content-Type 检测和适配
  • JSON/XML/表单三种格式的处理逻辑
  • 作用域匹配

3.3 作用域匹配

核心模块: src/backEnd/utils/scope_matcher.py

作用域字段：

  • protocol_pattern: 协议匹配 (http/https)
  • hostname_pattern: 主机名匹配（支持通配符）
  • ip_pattern: IP 匹配（支持通配符）
  • port_pattern: 端口匹配（支持逗号分隔）
  • path_pattern: 路径匹配（支持通配符）
  • use_regex: 正则模式开关

匹配逻辑：所有已填写字段采用 AND 逻辑组合，未填写字段视为通配。

4. 扫描配置管理开发

4.1 配置预设

数据模型: src/backEnd/model/ScanPreset.py

  • name: 预设名称
  • description: 描述
  • options: SQLMap 参数字符串
  • is_default: 是否为默认配置

服务层: src/backEnd/service/scanPresetService.py

  • 提供预设 CRUD
  • 历史配置自动保存
  • 去重逻辑：同名同参的配置只更新时间戳

前端组件: src/frontEnd/src/views/Config/components/

  • DefaultConfigPanel.vue - 默认配置面板
  • PresetConfigPanel.vue - 常用配置面板
  • HistoryConfigPanel.vue - 历史配置面板
  • ScanPresetConfig.vue - 扫描预设主组件

4.2 引导式参数编辑器

核心组件: GuidedParamEditor.vue

功能：

  • 可视化 SQLMap 参数配置（215个参数）
  • 参数分类（Target/Request/Optimization/Injection/Detection等）
  • 实时命令行预览
  • 自定义模式：直接输入命令行参数
  • 预设模式：基于已有预设创建

5. 调试技巧

5.1 后端调试

# 使用 Python logging 模块
import logging
logger = logging.getLogger(__name__)

# 不同级别日志
logger.debug(f"详细调试信息: {variable}")
logger.info(f"操作信息: {action}")
logger.warning(f"警告: {warning_msg}")
logger.error(f"错误: {error}", exc_info=True)  # 包含堆栈跟踪

查看日志:

# 调整日志级别 (startup.conf)
LOG_LEVEL=DEBUG

# 或运行时查看
# 日志输出在控制台和文件

5.2 前端调试

Chrome DevTools:

  1. F12 打开开发者工具
  2. Console 标签查看 console.log() 输出
  3. Network 标签查看 API 请求/响应
  4. Vue DevTools 查看组件状态和 Pinia Store

VSCode 调试:

// .vscode/launch.json
{
  "type": "chrome",
  "request": "launch",
  "name": "Debug Frontend",
  "url": "http://localhost:5173",
  "webRoot": "${workspaceFolder}/src/frontEnd"
}

5.3 Burp 插件调试

IntelliJ IDEA 远程调试:

  1. 在 IntelliJ 中配置 Remote JVM Debug
  2. 启动 Burp Suite 时添加 JVM 参数: 
    -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005
  3. 在 IDE 中连接调试端口 5005

日志查看:

  • Burp Suite → Extender → Extensions → 选择插件 → Output 标签
  • 查看 stdout 和 stderr 输出

6. 测试指南

6.1 后端测试

cd src/backEnd
python -m pytest tests/

测试文件:

  • tests/test_scope_matcher.py - 作用域匹配逻辑测试
  • tests/test_header_processor_scope.py - Header 处理器测试
  • tests/test_api_endpoints.py - API 端点测试
  • tests/test_body_field_processor.py - Body 字段处理器测试
  • tests/test_api_scope_integration.py - Scope API 集成测试

6.2 编写测试

# tests/test_new_feature.py
import pytest
from utils.scope_matcher import ScopeMatcher

def test_scope_match_exact_host():
    matcher = ScopeMatcher()
    scope = {"host_pattern": "api.example.com"}
    url = "https://api.example.com/v1/users"
    assert matcher.matches(url, scope) == True

def test_scope_match_wildcard():
    matcher = ScopeMatcher()
    scope = {"host_pattern": "*.example.com"}
    url = "https://api.example.com/v1/users"
    assert matcher.matches(url, scope) == True

6.3 前端开发验证

cd src/frontEnd

# 代码检查
pnpm run lint

# TypeScript 类型检查
pnpm run type-check

# 构建验证
pnpm run build

7. API 端点速查

Web API (前端调用)

方法 路径 说明
POST /api/web/admin/task/add 创建扫描任务
DELETE /api/web/admin/task/delete 删除任务
POST /api/web/admin/task/stop 停止任务
GET /api/web/admin/task/list 获取任务列表
GET /api/web/admin/task/{id} 获取任务详情
GET /api/web/admin/task/{id}/log 获取任务日志
POST /api/web/admin/task/find-by-url URL 搜索任务
POST /api/web/admin/task/find-by-header Header 搜索任务

Common API

方法 路径 说明
POST /api/commonApi/auth/login 用户登录
GET /api/commonApi/auth/verify 验证 Token
GET /api/commonApi/config/refresh-interval 获取刷新间隔
PUT /api/commonApi/config/refresh-interval 设置刷新间隔
GET /api/commonApi/config/server-logs 获取系统日志

上一篇: 基础开发环境搭建与入门指南 | 下一篇: 架构设计与性能优化