0xshe/php-code-audit-skill/php-route-tracer

PHP Route Tracer（数据流追踪，不做漏洞结论）

根据 php-route-mapper 的路由（或 php-audit-pipeline 给出的合成入口），追踪从 handler / CLI 入口 / 指定符号 到最终 Sink（SQL/命令/文件/SSRF/XSS/模板渲染/反序列化等）的位置，输出完整数据流链、参数变量名变化与可控性分析。

CRITICAL：只输出追踪，不输出漏洞建议

• 禁止给出“漏洞结论/风险等级/CVSS/修复建议”
• 只输出：数据流链证据、分支执行路径、Sink 定位、参数可控性判定表（可控性不等于漏洞结论）

输入依赖

• routes_{timestamp}.md：路由定义（独立落盘时常为 route_mapping/routes_{timestamp}.md，见 shared/IO_PATH_CONVENTION.md）
• params_{timestamp}.md：参数结构（独立落盘时常为 route_mapping/params_{timestamp}.md）
• source_path：源码根目录
• route_id：来自 cross_analysis/high_risk_routes_{timestamp}.md；可为 HTTP 路由序号，或 `php-audit-pipeline` 阶段 3 的合成 ID（ENTRY_CLI: / ENTRY_CRON: / ENTRY_QUEUE: / ENTRY_HOOK: / ENTRY_INCLUDE: / SINK_ONLY: 等）。
• 合成入口（当非 HTTP 路由时必填）：entry_file（相对 source_path）、entry_symbol（函数/方法或 global）、trace_from（从何处开始向 sink 追踪的说明）。

追踪范围（必做）

1. handler 入口（controller 方法/闭包函数/中间件最终处理函数）；非 HTTP 任务时以输入中的 entry_file + entry_symbol 为追踪起点（见「输入依赖」）
2. 请求参数进入 handler 的位置（request 获取、解码 JSON、提取 $_GET/$_POST）
3. 参数在函数/方法之间的传递（assignment、数组字段访问、对象属性访问）
4. 分支条件（if/switch/try/catch/return/throw）与提前退出点
5. 最终 Sink 的调用点与参数位置（函数调用参数名/位置）

输出文件结构（建议）

{output_path}/route_tracer/
└── {route_id}/
    ├── trace_{method}_{timestamp}.md
    └── trace_all_{timestamp}.md

说明：HTTP 路由：route_id 宜与 php-route-mapper 的 routes_{timestamp}.md 中 === [N] {route_summary} === 的序号 N 一致。CLI / hook / sink-only 等：使用流水线合成 route_id，追踪起点以输入中的 entry_file + entry_symbol + trace_from 为准，不要求与 URI 对应。

单路由报告模板（强制）

# Route Call Trace
 
追踪路由: {HTTP_METHOD} {route_rule}
生成时间: {timestamp}
项目路径: {source_path}
 
---
## 1) 完整请求模板（来自 route-mapper）

{完整请求模板}

 
---
## 2) 参数进入点
| 参数 | HTTP 来源 | 进入 handler 的变量/字段 | 位置 |
|------|----------|-----------------------------|------|
|      |          |                             |      |
 
---
## 3) 调用链层级证据（逐层，不省略）
Level-1: {file}:{line} {Function/Class}.{method}({args})
关键代码:

// 展示将参数传入下一层的关键片段

 
Level-2: {file}:{line} {Function/Class}.{method}({args})
 
---
## 4) 分支路径追踪（Branch Execution Proof，必须输出）
path A:
条件: {if/switch/try/catch/return/throw 的条件摘要}
执行: {在该分支下参数如何继续流转到 Sink 的摘要}
Sink：是否执行 = 是/否
 
path B:
条件: {另一条分支条件摘要}
执行: {另一条分支下参数的处理/提前退出摘要}
 
---
## 5) 参数可控性矩阵（Controllability Matrix，强制字段名与列必须一致）
| 参数 | HTTP/Body 字段 | 预处理/归一化 | Sink类型 | 覆盖类型 | 覆盖条件 | BlockReason(如有) | 可控性结论(✅/⚠️/❌) | 实际使用(是/否) | 可控场景 |
|------|------------------|------------------|-----------|-----------|-----------|--------------------|----------------------|------------------|----------|
 
---
## 6) Sink 定位（Sink Parameter Mapping，强制字段名与列必须一致）
| Sink类型 | 函数/方法 | 调用点(file:line) | Sink参数名/位置 | 参数映射（Sink参数 <- 可控参数） | 证据(关键代码片段) |
|----------|-----------|-------------------|-------------------|----------------------------------------------|----------------------|

7) Sink Summary（强制：用于 pipeline 的硬门槛校验）

必须输出一个汇总表（不允许省略）：

8) Trace 完整性声明（强制）

并给出：

• 缺失项列表（必须逐条列出缺失：调用链层级/分支/映射/证据）
• 回退建议（允许的回退：重新 tracer 或进入对应子 skill 的 ⚠️待验证模式）

必做的“禁止项”

• 禁止用省略符省略调用链层级
• 禁止保留未替换模板变量（如 ${route} 未替换为真实 route_id）
• 禁止将“不可控”与“无风险”混为一谈：本 skill 只输出可控性，不输出漏洞结论

9) Sink Evidence Type Checklist（强制：用于 pipeline 硬门槛）

要求在每条 trace 报告中输出本检查清单（允许内容为空，但必须存在标题与表头；并对实际命中的 sink 写出证据来源与证据片段）。