用途
php-route-tracer 用于对 PHP Web 应用进行路由到 Sink 的多层数据流追踪。它根据用户指定的路由（来自 php-route-mapper 的路由定义，或 php-audit-pipeline 给出的合成入口），追踪从 handler / CLI 入口 / 指定符号 到最终 Sink（SQL / 命令 / 文件 / SSRF / XSS / 模板渲染 / 反序列化等）的位置，输出完整数据流链、参数变量名变化与可控性分析。
该工具的定位是纯追踪，明确不做漏洞结论：禁止给出“漏洞结论 / 风险等级 / CVSS / 修复建议”，只输出数据流链证据、分支执行路径、Sink 定位与参数可控性判定表。可控性不等于漏洞结论。
主要能力
- 追踪 handler 入口（controller 方法、闭包函数、中间件最终处理函数），非 HTTP 任务时以 entry_file + entry_symbol 为起点。
- 定位请求参数进入 handler 的位置（request 获取、JSON 解码、提取 $_GET/$_POST）。
- 追踪参数在函数/方法之间的传递（assignment、数组字段访问、对象属性访问）。
- 追踪分支条件（if/switch/try/catch/return/throw）与提前退出点。
- 定位最终 Sink 的调用点与参数位置（函数调用参数名/位置）。
- 输出参数可控性矩阵、Sink 参数映射、Sink 汇总表、Trace 完整性声明与 Sink 证据类型检查清单。
- 覆盖多种 Sink 类型的证据要点，包括 FILE、WRITE、UPLOAD、ARCHIVE、SSRF、SQL、NOSQL、CMD、XSS、REDIR、CRLF、XXE、DESER、TPL、LDAP、EXPR、AUTH、CSRF、SESS、CFG 等。
使用方式
输入依赖包括：
- 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 追踪的说明）。
输出文件结构（建议）：
{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 对应。
单路由报告模板为强制结构，包含：完整请求模板、参数进入点、调用链层级证据（逐层不省略）、分支路径追踪、参数可控性矩阵、Sink 定位、Sink Summary、Trace 完整性声明、Sink Evidence Type Checklist。
适用场景
- 对 PHP Web 路由进行数据流追踪，辅助代码审计。
- 在代码审计流水线中作为追踪环节，承接路由映射结果并输出可校验的追踪证据。
- 对 CLI、定时任务、队列、钩子、包含、仅 Sink 等非 HTTP 入口进行合成入口追踪。
限制
- 只输出追踪，不输出漏洞建议、漏洞结论、风险等级、CVSS、修复建议。
- 可控性判定不等于漏洞结论。
- 禁止用省略符省略调用链层级。
- 禁止保留未替换模板变量（如 ${route} 未替换为真实 route_id）。
- 禁止将“不可控”与“无风险”混为一谈。
- Trace 完整性状态分为 COMPLETE、PARTIAL、UNRESOLVED；PARTIAL 表示只有局部链路证据或分支证据不完整，但 sink 存在或参数流可证明一部分；UNRESOLVED 表示无法定位到明确 sink 或可控性证据不足。需逐条列出缺失项，允许的回退为重新 tracer 或进入对应子 skill 的 ⚠️待验证模式。