| name | java-route-mapper |
| description | 当用户要求从源码、WAR/class/JAR 产物中提取、枚举、映射或记录 Java Web 路由、端点和请求参数，尤其是为后续鉴权、调用链、SQL、XXE、上传、文件读取或完整流水线审计提供输入时使用；仅做漏洞判定、调用链追踪、鉴权判断、依赖 CVE 扫描，或不需要路由提取的通用 API 文档润色时不要使用。 |
Java Route Mapper
当前定位
java-route-mapper 是 Java 审计技能集的入口面数据底座。它只回答一个问题：项目中有哪些可访问入口，每个入口对应哪个代码位置，以及请求参数从哪里来。
它的输出会被下游技能读取：
java-auth-audit: 对每条路由匹配鉴权规则和绕过风险。java-route-tracer: 从入口方法继续追踪参数流向。java-sql-audit / java-xxe-audit / java-file-upload-audit / java-file-read-audit / java-deserialization-audit: 以路由和参数清单作为输入来源。java-audit-pipeline: 阶段 1 的 agent-1-N worker 调用本 skill 产出模块路由详情，agent-1-merge 再合并主索引。
本 skill 不做漏洞评估、不判断鉴权是否正确、不追踪完整调用链、不扫描组件 CVE、不生成“看起来更漂亮”的 API 文档。
何时触发
用户意图包含以下任一项时触发：
- 从 Java Web 源码、WAR、反编译目录、class 或 JAR 中提取路由。
- 梳理 Controller、Action、Servlet、JAX-RS Resource、WebService endpoint。
- 生成
route_mapper/ 输出，供后续漏洞审计、鉴权审计或调用链追踪使用。
- 要求列出接口路径、HTTP 方法、入口方法、请求参数、SOAP 方法、Struts action 实例。
- 大型多模块项目需要按模块、namespace 或 worker 范围提取入口面。
典型用户说法：
- “帮我把这个 Java 项目的所有接口和参数梳理出来。”
- “先跑 route mapper，给后续 SQL 审计用。”
- “这个 Struts 项目没有接口文档，列出所有 action。”
- “提取 CXF WebService 的服务地址和所有 SOAP 方法。”
- “流水线 agent-1-3 只处理 admin_user 模块的路由。”
何时不触发
相似但不应触发的任务：
- 只问某条接口的调用链、参数是否到达 sink：使用
java-route-tracer。
- 要判断 SQL 注入、XXE、上传、文件读取、反序列化漏洞：使用对应漏洞审计 skill。
- 要判断鉴权绕过、越权或安全拦截器规则：使用
java-auth-audit。
- 只做依赖版本和 CVE 扫描：使用
java-vuln-scanner。
- 用户已有完整路由清单，只要求改写成 OpenAPI、Postman 或人类文档：这通常是文档转换任务，不是 route mapper。
- 只分析非 Web Java 程序、CLI、定时任务、消息消费者，且没有 HTTP/WebService 入口。
边界例：
- “这个接口有没有 SQL 注入？”不触发本 skill，除非用户同时要求先补齐入口面。
- “帮我找所有
@RequestMapping。”触发，但只输出路由和参数，不扩展到漏洞判断。
- “分析所有 public 方法。”不触发，除非这些方法是 WebService 或 Web 框架入口。
成功标准
完成后必须能让下游 agent 精确回答：“从哪个 URL/方法进入，用户可控参数叫什么，入口代码在哪里。”
最低合格输出：
- 覆盖所有发现的 Web 入口，不只列关键接口。
- 每个普通路由都有 HTTP 方法、完整 URL、入口类/方法、源码或反编译位置、参数结构。
- 每个 WebService 服务地址来自配置，不靠类名或 bean id 猜测；每个 SOAP 方法单独列出签名和参数。
- 通配符、网关分发、Struts 动态 action 不以模板代替实例；必须列出实际可达实例或 sub-function。
- 输出文件链接、自检数量、状态 JSON 与实际文件一致。
- pipeline worker 模式下，只写自己的模块目录和自己的反编译目录。
- 所有数量、行数、类数、方法数和覆盖范围都必须是精确可复核值；不能写
约、~、大约、60+、200+、尾随加号或范围数量。没有精确枚举时写 不可确认 或 未精确统计。
输入与模式判断
先判断执行模式：
| 模式 | 触发条件 | 输出责任 |
|---|
| Standalone | 用户直接要求对整个项目做路由映射 | 生成主索引、模块详情、README |
| Pipeline worker | prompt 中出现 agent-1-{N}、指定 module_name、指定状态文件 | 只生成该模块详情和 .status/agent-1-{N}.json，不写主索引或项目 README |
| Pipeline merge | prompt 中出现 agent-1-merge 或只要求合并 worker 产物 | 不重新扫描源码，只合并 worker 输出为主索引 |
如果输入范围不明确：
- 可以从用户给出的源码路径、输出路径、模块路径推导时，直接执行。
- 缺少源码路径或没有可访问项目文件时，先询问。
- 在 pipeline worker 模式下，缺少
module_name、module_paths、output_path 或状态文件路径时，停止并要求负责人补齐；不要自行扩大范围。
工作流
- 确认模式、源码路径、输出目录、可写范围。
- 识别框架和入口类型。只读取与当前项目实际框架相关的 reference。
- 提取上下文路径、Servlet 映射、框架前缀、类级路径、方法级路径，组合完整 URL。
- 枚举入口方法和参数结构；源码不完整时按需反编译。
- 对通配符、dispatch 网关、WebService 动态方法做实例化展开。
- 按模板写入输出文件。
- 执行完整性自检；失败时补查源码或反编译结果，直到数量和文件对账通过。
按需读取的 references
只在需要时读取，避免把主上下文变成框架教程：
- 框架识别不确定：
references/FRAMEWORK_PATTERNS.md
- Spring MVC / Spring Boot：
references/SPRING_MVC.md
- Struts2：
references/STRUTS.md
- Servlet：
references/SERVLET.md
- JAX-RS：
references/JAXRS.md
- CXF/JAX-WS/Axis：
references/WEBSERVICE.md
- 注解参数提取：
references/ANNOTATIONS.md
- 需要反编译：
references/DECOMPILE_STRATEGY.md
- 输出文件：
references/OUTPUT_TEMPLATE_INDEX.md、references/OUTPUT_TEMPLATE_MODULE.md、references/OUTPUT_TEMPLATE_README.md
- 通用输出规范：
../java-shared/OUTPUT_STANDARD.md
CRITICAL 1: 完整输出零省略
禁止用摘要替代枚举：
- 禁止
...、等、其他、更多、部分、主要接口、关键接口。
- 禁止
共 N 个，列出部分。
- 禁止
001 ~ 050 这类范围代替逐项列表。
- 禁止只列类名、WSDL 地址、namespace 名而不列具体入口。
- 数量字段必须是精确数字，禁止
200+、约 50、大量。
- 如果只知道某类 Action/Servlet/WebService 存在但未反编译出全部方法，不得写“剩余约 N 个”或“已知约 N 个”；应写精确已枚举数，并把未枚举部分写为
不可确认。
如果输出太大，拆分文件；不要压缩为摘要。
CRITICAL 2: 动态路由必须实例化
需要展开的情况：
- Struts2 通配符 action，如
*_*、user_*、*。
- Servlet
/api/*、*.do 内部根据 pathInfo、参数、反射或 switch 分发到不同方法。
- 网关方法，如
executeInterface(String code, String json)、dispatch(String action, ...)、invoke(String type, ...)。
- WebService 中通过
interfaceId、methodId、code 执行业务方法。
输出方式：
- Struts2 通配符可用“模式族 + URL 实例列表”，模式族头部只写一次，实例列表必须逐行列出全部 URL 到方法映射。
- dispatch / executeInterface / methodId 分支必须把每个 sub-function 作为独立接口计数，并写清参数结构。
- Spring MVC
{id}、JAX-RS @PathParam 是路径变量，不展开具体值；按普通路由输出并标注 Path 参数。
CRITICAL 3: URL 只能由真实配置组合
完整 URL 按真实来源组合，不凭命名猜测：
- context path
- web.xml /
@WebServlet / Servlet registration
- Spring
server.servlet.context-path、类级和方法级 mapping
WebMvcConfigurer#configurePathMatch / PathMatchConfigurer#addPathPrefix- JAX-RS
ApplicationPath、类级 @Path、方法级 @Path
- Struts package namespace、action name、extension
- CXF/JAX-WS endpoint
address
- Axis/Axis2 service name
WebService 特别规则：
- CXF/JAX-WS 地址必须从 XML、Spring bean、endpoint 配置或注解配置读取。
UserServiceImpl 不能推断为 /UserService。- endpoint id 或 bean id 不能替代
address。
- 只给 WSDL URL 不合格，必须列出服务下所有 public SOAP 方法或配置暴露的方法。
CRITICAL 4: 参数结构必须可用于下游追踪
每个入口至少标注：
- Path 参数：名称、类型。
- Query/Form 参数：名称、类型、是否明显必填。
- Body 参数：Content-Type、对象类型、关键字段；对象字段过多时仍要列出字段，不用“对象见源码”替代。
- Header/Cookie 参数：只有自定义鉴权头、业务头或代码显式读取时列出；标准
Authorization 可按项目实际需要标注。
- File 参数：文件字段、文件名字段、保存路径相关参数。
- SOAP 参数：方法签名、参数名、类型、返回类型。
类型未知时：
- 先查源码类型、DTO、字段、getter/setter、XML/schema、反编译结果。
- 仍无法确定时标注
unknown 和证据位置；不能编造类型。
CRITICAL 5: Pipeline worker 隔离
在 agent-1-N worker 模式下：
- 只扫描负责人分配的
module_paths，但可只读访问同 WAR 的公共配置、公共基类和依赖 jar。
- 只写
{output_path}/route_mapper/{module_name}/。
- 只写
{output_path}/decompiled/agent-1-{N}/。
- 禁止写主索引、项目 README、其他 worker 子目录、共享
webservice/ 目录。
- 完成后必须原子写入
.status/agent-1-{N}.json，数字字段使用 JSON number。
- 若实际路由数超过侦查单预估 1.5 倍且大于 100，写
status="overflow" 并停止，等待重新拆分。
状态 JSON 至少包含：
{
"schema_version": 1,
"agent_id": "agent-1-N",
"recon_id": "from_recon_file",
"module_name": "module",
"module_paths": [],
"status": "success",
"attempt": 1,
"actual_route_count": 0,
"estimated_route_count": 0,
"frameworks": [],
"output_files": [],
"output_file_sha256": {},
"completed_at": "ISO8601",
"error_message"
CRITICAL 6: 输出校验
写完前后都要检查：
- 主索引链接的所有详情文件真实存在。
- 模块详情里的总接口数等于逐条列出的接口数，通配符实例和 sub-function 计入总数。
- WebService 方法数等于配置暴露方法和反编译 public 方法核对后的数量。
- 文件中不含占位符
【填写】。
- 文件中不含省略词和数量后缀。
- pipeline worker 的
.status 中 output_files 均存在且 hash 匹配。
自检失败时不要交付“待补充”版本；继续补查缺口。只有源码缺失、配置不可读、反编译失败且无法恢复时，才在输出中标注阻塞原因。
输出文件
Standalone 模式：
route_mapper/{project_name}_route_mapper_{YYYYMMDD_HHMMSS}.mdroute_mapper/{module_name}/{project_name}_module_{module_name}_{YYYYMMDD_HHMMSS}.mdroute_mapper/{project_name}_route_README_{YYYYMMDD_HHMMSS}.md- WebService 可按实际服务放入模块子目录或
route_mapper/webservice/，但主索引链接必须准确。
Pipeline worker 模式：
- 只写
{output_path}/route_mapper/{module_name}/...md
- 只写
{output_path}/route_mapper/.status/agent-1-{N}.json
Pipeline merge 模式：
- 读取 recon、status、worker 输出。
- 不重新扫描源码。
- 只写主索引和 README。
Gotchas
addPathPrefix 会改变 Spring Controller 最终 URL；漏掉会导致下游鉴权和调用链全部错位。- Struts2
*_* 不是一个接口；它是一组可达 action/method 实例。
- 网关式
executeInterface 不是一个业务接口；每个 code/interfaceId/methodId 都是独立入口。
- WebService URL 的真实来源是配置
address 和 Servlet 映射，不是实现类名。
- 只读公共基类很重要；很多 Action 参数来自父类字段或 setter。
- “参数对象 FooRequest”不够，下游需要字段名和类型。
- pipeline worker 不得为了补全上下文写入其他模块产物；只能读取必要公共上下文。
- 大项目发现数量异常增长时要 overflow 停止，而不是继续写一个失控的大文件。
- 空模块也要有明确输出或 status 说明，否则 merge 无法区分“无路由”和“漏扫”。
Evals
正例：应触发
| 用户输入 | 预期 | 理由 |
|---|
| “提取这个 Spring Boot 项目的所有接口和参数，输出 route_mapper。” | 触发 | 明确要求路由和参数映射 |
“这个 Struts2 项目 action 都是 *_*，帮我列完整 URL。” | 触发 | 动态路由实例化是核心职责 |
| “agent-1-4 只处理 biz_order 模块，生成状态 JSON。” | 触发 | pipeline worker 场景 |
| “列出 CXF 服务地址和每个 SOAP 方法参数。” | 触发 | WebService endpoint 映射 |
反例：不应触发
| 用户输入 | 预期 | 理由 |
|---|
“判断 /api/user/{id} 是否存在越权。” | 不触发 | 应使用 auth audit 或 tracer |
| “扫描 pom 里的 CVE。” | 不触发 | 依赖漏洞扫描不是路由映射 |
| “把这份接口文档润色成 Markdown。” | 不触发 | 没有源码路由提取需求 |
| “追踪这个参数到 SQL 拼接点。” | 不触发 | 应使用 route tracer / SQL audit |
边界例
| 用户输入 | 预期 | 处理 |
|---|
“找所有 @RequestMapping。” | 触发 | 输出路由和参数，不做漏洞判断 |
| “分析所有 public 方法。” | 视上下文 | 只有 WebService 暴露方法才纳入 |
| “接口太多，列关键的就行。” | 触发但拒绝省略 | 说明本 skill 必须完整输出，可拆分文件 |
失败案例
| 失败表现 | 风险 | 修复方式 |
|---|
用 /UserService 代替配置中的 /UserApi | 下游请求路径错误 | 读取 endpoint address 和 Servlet 映射 |
把 *_* 输出成 {action}_{method}.action | 漏掉实际入口 | 反编译 Action 类并逐行列出实例 |
输出 UserRequest 但不列字段 | 下游无法追踪参数 | 展开 DTO 字段或标注无法确定原因 |
worker 写了 route_mapper/README.md | 覆盖 merge 产物 | worker 只写模块目录和 status |
actual_route_count 写成 "200+" | merge 无法对账 | 查清精确数字，使用 JSON number |
