| name | project-framework-analysis |
| description | 白盒建模——一次深度建模产出五张共享模型：项目架构（技术栈/分层/框架自有封装/闭源依赖位置）、 入口点（路由/中间件信任边界）、认证与权限（会话/角色/多租户/归属字段）、业务（实体/流程状态机/ 业务不变量/高价值资产）、全局威胁（攻击面×漏洞类别的适用性映射，供下游逐一全测）。本能力不做漏洞判定，为后续 漏洞维度分析建立共享底图。 |
| when-to-use | 当开始一次全量代码安全审计、需要先建立项目架构/入口点/认证权限/业务/全局威胁五张共享模型、为后续分析建立入口时 |
| allowed-tools | bash,read_file,list_files,rg |
| user-invocable | true |
| argument-hint | [target_path] |
| arguments | ["target_path"] |
白盒建模（五张模型）
本能力在审计早期做一次深度建模，产出五张共享模型作为后续多维度审计的入口——项目架构 / 入口点 / 认证与权限 / 业务 / 全局威胁。白盒源码全可见，整张攻击面图一次性静态建起并复用，仅项目结构重大变更时重建。不做漏洞判定——建模阶段产生的可疑点交对应审计能力消费。
1. 触发线索 / 适用信号
按"半径 + 项目体量 + 已有产物 + 信息完备度"四维识别命中场景。
半径维度：
- 用户给的目标路径是项目根目录（含
pom.xml / go.mod / package.json / composer.json / requirements.txt / Cargo.toml 任一特征文件），不是单文件
- 至少存在 controller 层目录（
controllers/ / handlers/ / 含 @RequestMapping 注解的 Java 文件 / routes/ / views/），项目体量大于单文件
已有产物维度：
shared/models/ 五张模型 markdown 尚不存在- 已有产物但目标项目栈 / 入口点近期发生重大变更（新增模块 / 新增框架 / 切换 ORM）
信息完备度维度：
- 多语言混合（前后端同仓 / 微服务异构）
- 多模块（monorepo / 多 maven module / lerna 工作区）
- 用户未在初始描述里给出明确技术栈或入口点
反向信号（不命中本能力）：
- 用户已显式给出技术栈 + 已知入口点（直接跳到对应漏洞维度 skill）
- 小修改半径——单文件审计、PR diff、特定函数复核
- 已有同 commit 范围内的 framework 产物（增量审计直接消费现有产物即可）
2. 造成原因
本能力 n/a（原因：本能力是前置侦察，不针对单一漏洞，无成因可写。各漏洞成因由对应 audit skill 在 §2 中独立讲清。）
3. 领域 source-sink 数据流模型
本能力 n/a（原因：侦察阶段不做 source-sink 追踪。本能力只产出"哪里可能是 source、哪里可能是 sink 的封装"这一位置盘点，跨函数可达性证明由下游 dataflow-analysis 接力。）
4. 常见类型
本能力 n/a（原因：本能力不针对漏洞分类，攻击变体由各漏洞维度 skill 自行枚举。）
5. 入口点定位
本能力的"入口点"实际是"侦察起点"——告诉模型从项目里哪些特征文件 / 声明位置进入，把侦察面建立起来。
按项目根的特征文件 + 路由声明 + 中间件声明 + ORM 配置定位起点。
下列框架 / 项目类型仅作类似项目示例 不限于此；以目标实际栈为准。
项目根特征文件（识别技术栈 + 依赖）
| 语言 | 特征文件 | 同时看什么 |
|---|
| Java | pom.xml / build.gradle / settings.gradle | dependencies 节、spring-boot-starter-* / mybatis-spring / shiro-* 信号 |
| Go | go.mod / go.sum | require 节、gin / echo / gorm / database/sql 信号 |
| Python | requirements*.txt / pyproject.toml / Pipfile | flask / django / fastapi / sqlalchemy / jinja2 信号 |
| JS / TS | package.json / pnpm-workspace.yaml / lerna.json | dependencies 节、express / koa / @nestjs/* / next / sequelize / typeorm 信号 |
| PHP | composer.json | laravel/framework / topthink/think / symfony/* 信号 |
| C / C++ | Makefile / CMakeLists.txt / meson.build | 链接的库（OpenSSL / libcurl / 框架库） |
| Rust | Cargo.toml | actix-web / axum / rocket / tokio 信号 |
路由声明文件（找入口点）
按框架 grep 路由声明位置：
- Spring：
rg "@RequestMapping|@GetMapping|@PostMapping|@PutMapping|@DeleteMapping|@PatchMapping"
- Gin / Echo：
rg "\.(GET|POST|PUT|DELETE|PATCH|Any)\(|router\.|engine\.Group"
- Flask / FastAPI：
rg "@app\.(route|get|post|put|delete)|@router\.(get|post|put|delete)"
- Django：读
urls.py 找 path(...) / re_path(...) 声明
- Express / Koa：
rg "app\.(get|post|put|delete|use)|router\.(get|post|put|delete)"
- NestJS：
rg "@(Get|Post|Put|Delete|Patch|Controller)\("
- Laravel：读
routes/web.php / routes/api.php
- ThinkPHP：约定式路由按控制器目录
中间件 / 拦截器 / 过滤器声明位置
- Spring：
@WebFilter / @Component 实现 Filter / HandlerInterceptor / @ControllerAdvice / Spring Security 配置类
- Gin：
engine.Use(...) / group.Use(...) 注册的 handler
- Django：
settings.py 的 MIDDLEWARE 列表
- Express：
app.use(...) / router.use(...)
- Laravel：
app/Http/Kernel.php 的 $middleware / $routeMiddleware
ORM / 数据访问层配置
- MyBatis：
*Mapper.xml 位置、@Mapper 注解扫描包配置
- Gorm：
*.go 里的 db.AutoMigrate(...) 调用
- SQLAlchemy / Django ORM：
models.py 位置
- Sequelize / TypeORM：
models/ 目录、ormconfig.json
6. 跨框架代码变体
本能力在不同框架下的侦察起点对照——每语言 × 框架的特征文件 + 框架信号 + 关注介质。目的是让本能力在任意项目栈都能用。
| 语言 | 框架 | 特征文件信号 | 必入侦察面的介质 |
|---|
| Java | Spring Boot | pom.xml 含 spring-boot-starter-web | *Controller.java、application*.yml、templates/ |
| Java | Spring MVC | web.xml 配 DispatcherServlet | *Controller.java、WEB-INF/、spring-*.xml |
| Java | MyBatis | pom.xml 含 mybatis-spring 或 mybatis-plus | **/*Mapper.xml、@Mapper 接口、@Select / @Update 注解 |
| Java | Shiro / Sa-Token | pom.xml 含 shiro-spring / sa-token-* | Shiro 配置类、@RequiresPermissions / @SaCheckLogin 注解位置 |
| Java | Thymeleaf / Freemarker | pom.xml 含 thymeleaf / freemarker | templates/*.html / *.ftl 模板目录 |
| Go | Gin | go.mod 含 gin-gonic/gin | router*.go、main.go、middleware 注册位置 |
| Go | Echo | go.mod 含 labstack/echo | 路由注册文件、middleware |
| Go | Beego | go.mod 含 beego/beego | routers/router.go、controllers/ |
| Go | Gorm | go.mod 含 gorm.io/gorm | 含 db.Raw / db.Exec 的文件、模型定义 |
| Go | 自定义 middleware | 项目内 middleware 包 | middleware 注册顺序与覆盖范围 |
| Python | Flask | requirements.txt 含 flask | app.py / views.py、templates/（Jinja2） |
| Python | Django | manage.py + settings.py | urls.py、views.py、models.py、MIDDLEWARE 配置 |
| Python | FastAPI | requirements.txt 含 fastapi | router 文件、main.py、Pydantic 模型 |
| Python | SQLAlchemy | requirements.txt 含 sqlalchemy | 模型定义、含 session.execute / text() 的文件 |
| Python | Jinja2 | 模板文件 .html / .j2 | templates/ 目录 |
| JS / TS | Express | package.json 含 express | routes/*.js、app.js、middlewares/ |
| JS / TS | Koa | package.json 含 koa | router 文件、koa-* 中间件 |
| JS / TS | NestJS | package.json 含 @nestjs/core | *.controller.ts、*.module.ts、*.guard.ts |
| JS / TS | Next.js SSR | next.config.js 存在 | pages/api/* / app/api/* 路由、SSR getServerSideProps |
| PHP | Laravel | composer.json 含 laravel/framework | routes/web.php、routes/api.php、app/Http/ |
| PHP | ThinkPHP | composer.json 含 topthink/think | application/ 或 app/ 目录、约定式路由 |
| PHP | Blade / Twig | 模板文件 .blade.php / .twig | resources/views/ |
| C / C++ | 通用 | Makefile / CMakeLists.txt | 命令执行点（system / popen）、内存安全点、链接的第三方库 |
详细的侦察维度展开（每维度的识别细则、grep pattern、易漏点）见 references/architecture-model.md。
7. 思考检查点
加载本 skill 时按这些问题思考——按"待回答的核心问题"驱动侦察展开：
- 这个项目是什么技术栈、什么分层结构？（MVC / 充血贫血 / 微服务边界 / monorepo）
- 攻击面入口点有哪些？路由声明在哪个文件里？有没有动态注册的路由 / 反射加载？
- request 上下文里哪些字段是服务端注入的可信值、哪些是客户端可控？中间件向上下文写入了什么？
- 框架把 source / sink / 跨过程分发 / 认证 / 过滤封装成了哪些自有类与方法？（通用 SAST 工具按标准类型匹配会看不见的盲区）
- 依赖里哪些是闭源 / 可反编译 / 混淆？落在攻击面的什么位置（是否承载鉴权 / 是否在污点必经路径上）？
- 项目里的核心业务实体的归属字段（
user_id / tenant_id / owner_id）在哪些表 / 哪些字段？
8. 建模方法论
本能力只到建模产物——跨函数追踪 / sink 可达性证明走 dataflow-analysis 与对应单漏洞维度 skill。本节是五张模型的建模骨架；每张模型的判据、易漏点、产物字段见对应 reference。
五张模型总览
一次深度建模，按下列顺序建五张模型（前四张是事实盘点，第五张综合前四张）：
建模维度（非编号——按"待回答问题"组织，结合代码事实展开顺序）
每维度按"识别信号 → 为什么这维度重要 → 须产出什么"组织；下列维度按上表归入五张模型。
技术栈与框架识别
- 识别信号：§5 项目根特征文件 + dependencies 节信号
- why：后续所有维度都依赖准确的栈识别——把 Spring 项目当 Django 审计、漏掉 MyBatis XML 介质，后续整条链路失真
- 须产出：语言 + 框架信号 + 版本线索
架构分层
- 识别信号：目录命名（
controller/ / service/ / mapper/ / dao/ / repository/）、注解模式（@Service / @Repository）、模块边界
- why：分层决定 source 入口位置与 sink 集中位置——MVC 项目 source 在 Controller，sink 在 Mapper；微服务项目要识别服务边界以确定本服务范围
- 须产出：分层模式 + 模块/微服务边界
路由与入口点枚举
- 识别信号：§5 路由声明文件 grep 结果
- why：入口点是后续所有漏洞维度 source-to-sink 追踪的起点——缺一个入口点 = 那一类漏洞维度在该端点失去 source 锚点
- 须产出：端点骨架表（Controller / 方法 / HTTP method / URL pattern / 命中的中间件 / 参数列表）
中间件与信任边界
- 识别信号：§5 中间件声明位置 + 拦截器配置 +
@ControllerAdvice / Filter / app.use 注册
- why：判断 source 是否可控、鉴权是否真实，都依赖"哪些 request 属性是 server-derived（可信）vs client-controlled（不可信）"这一事实；中间件向上下文注入的字段直接决定信任边界
- 须产出：过滤器/中间件映射表（名称 / 拦截路径 / 类型 / 注入字段 / 信任边界标注）
认证与会话架构
- 识别信号：登录端点位置、Token 类（JWT / Cookie / 自定义）、
@PreAuthorize / @RequiresRoles 注解、Spring Security 配置
- why：认证逻辑决定哪些端点匿名可达、哪些端点需要角色校验——这是越权类漏洞维度的前提
- 须产出：会话策略 + 鉴权机制 + 角色权限模型 + 多租户标识
数据模型归属字段
- 识别信号：实体类字段命名（
userId / owner_id / tenant_id / org_id / principalId）、SQL 表 schema
- why：IDOR / ownership / 越权类审计依赖 owner ↔ resource 字段对照——侦察阶段沉淀这套对照表，下游能力按字段名直接追踪
- 须产出：owner/operator 字段集合 + resource/target 字段集合 + 多租户字段
框架封装的 source / sink / 自定义工具类
- 识别信号：自定义 Controller 基类的取参方法、
StringBuffer 拼接后 prepareStatement 的伪安全预编译、包装 Runtime / ProcessBuilder 的工具类、自研 ObjectInputStream 子类、自研模板渲染封装、自研登录 Filter 与恒真校验、自研输入过滤器/编解码器
- why：通用 SAST 规则只认标准 API——自研封装把标准 source / sink 包了一层，按标准类型匹配会整段看不见；这是系统性盲区。详细分类（① Source 封装 / ② Sink 封装（SQL / 命令 / 文件 / 反序列化 / 模板）/ ③ 分发 / RPC 边界封装 / ④ 认证 / 会话封装 / ⑤ 过滤 / 校验封装）见 references/architecture-model.md
- 须产出：框架封装映射表（封装类别 / 功能 / 类#方法位置）
依赖结构与闭源 / 混淆识别
- 识别信号：依赖清单（
pom.xml / go.mod / package.json / requirements.txt / composer.json）+ 命名空间（公共 vs 私有）+ MANIFEST/Vendor/groupId/LICENSE 归属信号 + 类名混淆特征（a.a.a / o0Oo）
- why：闭源依赖如果承载鉴权 / 过滤 / sink 逻辑，标"未审"会让结论失真——需要标注其在攻击面的位置以决定是否反编译。详细分类判据（公共库 / 无源码可反编译 / 混淆 / unknown）与归属（同厂商自有 / 第三方异厂商商业 / unknown）规则见 references/architecture-model.md
- 须产出：依赖图谱表（坐标 / 分类 / 归属 / 有无可读源码 / 相对入口/边界位置 / 是否关键路径 / 处置建议）
业务建模（业务模型）
- 识别信号：领域实体类 / 表 schema、跨多方法的业务流程、实体 status 字段与流转代码、数值 / 配额 / 归属约束的校验位置
- why：语义型漏洞（越权 / 逻辑 / 状态机 / RBAC / 影响放大）的判据基准——没有业务不变量，逻辑漏洞只能靠临场直觉
- 须产出：核心实体与关系 + 关键流程与状态机合法迁移 + 业务不变量清单（含"在哪校验 / 是否校验"）+ 高价值资产与影响放大链路。细则见 business-model.md
威胁建模（全局威胁模型 = 攻击面映射）
- 识别信号：前四张模型的汇聚——入口点 × 业务语义 × sink 位置 × 可达身份
- why：把前四张模型的事实汇总为统一的攻击面映射，供下游各维度按接口逐一取用、逐一全测；本模型只供信息，不排优先级、不做维度取舍、不指挥先测后测
- 须产出：攻击面清单 + 攻击面 × 漏洞类别的全量适用性映射（每个接口的每个结构上可能成立的维度都登记，
rationale 陈述该维度在此接口成立的事实依据）。某维度在某接口结构上不可能成立可作事实记录，但不表述为 out-of-scope、不作为下游省略其他维度的依据。细则见 threat-model.md
产物落库
基线检查项
以下是已知的检查角度，作为基线起点而非必检硬清单。结合目标项目动态调整，按三态标注（[x] / [-] / [+]）处置。
9. 闭环要求（必须遵守）
本能力 n/a（原因：本能力不做漏洞判定，无 confirmed / suspected / not_vulnerable 概念。但产物契约仍是交付契约——侦察缺漏会让下游所有维度失去锚点，因此独立成"产物结构"段写在本节末尾。）
产物结构（必须遵守）
为什么这里是「必须」：产物结构是下游审计能力按入口点对账的接口。下游 dataflow-analysis / sast-scan / 各单漏洞维度 skill 都按本产物的入口点清单展开攻击面覆盖；省略一个入口点 = 一类漏洞维度在该端点失去 source 锚点，整条链路失真。产物落库规范见 common/result-with-file。
产物形态：五张模型各落一个 markdown，无 JSONL 并存：
shared/models/architecture-model.md — 技术栈 / 分层 / 框架封装（source/sink/分发/过滤/认证 wrapper）/ 依赖与闭源识别shared/models/entry-point-model.md — 入口点骨架表 + 中间件信任边界表shared/models/auth-model.md — 认证机制 + 归属字段对照表（owner/resource/tenant）shared/models/business-model.md — 业务实体 / 流程状态机 / 业务不变量表shared/models/threat-model.md — 攻击面 × 漏洞维度全量适用性映射表（attack_surface / vuln_class / rationale，不含 priority / in_scope）
各模型内的信息用 markdown 表承载（每张表的列见对应 references/<model>.md 的「产物落库」段）；入口点 id 带 ep- 前缀全局唯一、覆盖态初始 pending。
注意：shared/models/*.md 是本次审计的运行时产物；skill 目录下 references/*.md 是静态方法论细则，二者同名不同物。
落盘硬约束：五张模型必须各自落 shared/models/ 对应文件，禁止只写在 task_context.md 或仅口头描述；任一模型文件缺失 = 该模型未完成，结论降级 partial-coverage。
表约束：
- 一入口 / 一实体 / 一不变量 / 一攻击面映射独占一行——禁止用"等" / "..." / "（其余 N 条略）"省略
- 入口点穷举不省略——why：下游各漏洞维度按入口点对账，省略一个入口点会让该入口点对应的整类漏洞维度失去 source 锚点
- 威胁映射表只含
attack_surface / vuln_class / rationale，不含 priority / in_scope——本能力不排优先级、不做取舍
就地更新（必须遵守）：
why：重跑建模不应重置已有的扫描进度——下游能力可能已将部分入口点覆盖态更新为 in_progress / completed，整文件覆盖写会破坏跨批次状态追踪。
模型文件已存在时，按表行主键（入口点 id / 实体字段 / 攻击面单元）就地更新或追加新行；已有行的覆盖态原样保留、不重置，不删旧行。
反例义务（必须遵守）：
why：写"已完整盘点框架"前必须有反向覆盖证据——缺失会让下游误信"该范围内攻击面已穷举"。
写"建模已完成"结论前，五张模型的产物必须包含：
- 所有路由声明文件已 grep 覆盖的证据（grep 命令 + 命中数）
- 所有中间件注册位置已识别（middleware 数 + 拦截范围 + 注入字段信任边界）
- 所有依赖已分类（公共库 / 无源码 / 混淆 /
unknown 数量分布）
- 业务模型：核心流程 / 状态机 / 业务不变量已枚举，每条不变量标注"在哪校验 / 是否校验"
- 威胁模型：攻击面 × 漏洞类别的全量适用性映射已产出，每个接口 × 每个可能维度都登记，不省略、不排除、不排优先级
- 任一未覆盖的范围（动态注册路由 / 反射加载 / 闭源依赖内部）在对应模型的「缺口」段显式列出原因
清单不完整 → 结论降级为 partial-coverage，且必须在对应模型的 shared/models/<model>.md "缺口"段显式列出未覆盖范围。
10. 具象化反例库
本能力 n/a（原因：本能力不做漏洞判定，无 FP / FN 概念。各漏洞维度的反例库由对应 audit skill 在 §10 中独立写。）
11. 静态分析边界
本能力 n/a（原因：本能力是侦察阶段，不涉及静态分析的可达性证明边界。反射调用 / 闭源依赖 / 动态字符串构造等静态分析边界由 dataflow-analysis 与下游单漏洞维度 skill 在 §11 中独立写。本能力对这些情形的处置是侦察阶段标注其位置——反射点 / 闭源依赖 / 动态注册路由进 coverage_gap 记录，供下游能力按位置接力。）
12. 修复建议
本能力 n/a（原因：本能力不做漏洞判定，无修复对象。各漏洞维度的修复建议由对应 audit skill 在 §12 中独立写。）
