TraceSurface
从前端还原 API，用真实响应判断哪些接口值得关注。
浏览器追踪 · JavaScript AST 分析 · 无认证重放 · AI Review
下载 · 快速开始 · AI Review · 实战示例 · English
给 TraceSurface 一个 URL，它会追踪页面真实发出的请求，解析入口脚本与懒加载代码，找回当前页面没有触发的 API。随后进行无认证重放，把接口来源、请求与响应放进同一份本地报告。
接口多时，可以手动选择站点交给 AI Review 分析。所有站点的疑似接口集中呈现，保留判断依据和原始报文，方便逐项复核。
能做什么
| 从发现到复核 | TraceSurface 提供的能力 |
|---|---|
| 发现未触发的接口 | 解析 fetch、XHR、axios、自定义封装，以及 webpack / Vite 懒加载代码 |
| 还原完整地址 | 用浏览器请求和调用栈对齐源码位置，推导 baseURL，并保留证据层级 |
| 查看无认证响应 | 重放请求时不加载浏览器 Cookie、Authorization 等认证头 |
| 汇总需要关注的接口 | AI 按站点阅读重放结果，跨站点展示疑似问题与验证建议 |
| 回到原始证据 | 在本地报告中检查 API 来源、响应正文与前端敏感信息命中 |
快速开始
从 Releases 下载并解压对应平台的文件，无需安装 Python：
| 平台 | 下载文件 |
|---|---|
| Windows x86_64 | tracesurface-windows-x86_64.zip |
| macOS Apple Silicon | tracesurface-macos-arm64.tar.gz |
| Linux x86_64 | tracesurface-linux-x86_64.tar.gz |
# macOS / Linux
./tracesurface scan https://target.example
./tracesurface serve# Windows PowerShell .\tracesurface.exe scan https://target.example .\tracesurface.exe serve
打开 http://127.0.0.1:8765 查看报告。扫描优先使用本机 Google Chrome；没有 Chrome 时，会自动下载 Chromium。
从源码运行
需要 Python 3.12+ 和 uv。
git clone https://github.com/pis10/TraceSurface.git
cd TraceSurface
uv sync --locked
uv run tracesurface scan https://target.example
uv run tracesurface serve仓库包含报告页面的构建产物。修改前端后，在 frontend/ 中运行 npm ci 和 npm run build。
AI Review
扫描由工具完成，分析由你决定何时开始。 不需要为每个站点单独打开一份报告。
- 打开 AI Review → 模型设置，选择服务商与模型，填写 API Key。
- 点击 测试连接，确认模型能够返回所需的分析结果，再保存设置。
- 点击 选择站点分析，勾选站点，或选择筛选结果中的全部站点。
- 在同一列表查看疑似接口；打开详情，结合原始请求、响应与验证建议复核。
每个站点独立分析，只读取已有的 2xx + JSON 重放结果。尚未扫完的站点会提示扫描完成后再分析；没有符合条件的接口时不调用模型。关闭网页不会停止后台任务；停止报告服务后，未完成的任务需要手动重试。
接入你的模型
内置目录由 Pydantic AI 提供，包含 DeepSeek、Kimi、GLM、阿里百炼、OpenAI、Anthropic、Gemini 等服务商。可以搜索模型，也可以输入目录尚未收录的型号。内置模型不需要手工填写上下文容量。
有自己的兼容服务时，选择 自定义接入。支持 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和 Gemini generateContent 四种 API 格式。填写服务地址、模型名称、API Key、上下文容量与最大输出，再勾选服务支持的思考强度。
分析与连接测试使用同一套结果校验：提示词包含完整输入/输出示例，兼容 JSON 外的代码块、说明文字和已结束的 <think> 内容；字段或接口编号不合格时最多自动纠错三次（含首次共四次请求，仍受总超时限制）。所有接口均通过校验后才保存成功。若提示输出被截断，请增大最大输出或降低思考强度；网络、认证和截断错误不会自动重复请求。
页面中的“默认强度”就是分析实际使用的档位：例如勾选 low / high / max 后选中 high，分析便使用 high。default 表示不指定强度，由服务决定；内置模型的档位转换由 SDK 处理，不同型号的实际效果可能不同。
查看自定义接入示例
示例地址与模型名仅用于说明表单，请按服务商提供的信息填写。
扫描与重放不依赖 AI。只有主动发起分析，扫描报文才会发送至所配置的模型服务；连接测试只发送虚构样例。API Key 保存在本机，不回传页面。AI 结论用于辅助人工复核；没有疑似结果不代表站点不存在漏洞，任务详情会显示分析是否完成。
实战示例
以若依公开演示站的登录页为例，无需登录后台即可从前端代码发现接口：
tracesurface scan https://vue.ruoyi.vip/login --no-auth
登录页的验证码请求提供了 /prod-api 前缀与调用位置。TraceSurface 将运行时请求对齐到 JavaScript 调用点，再继续展开业务代码，发现角色、菜单、部门、字典和监控等接口。
| 示例扫描 | 数量 |
|---|---|
| AST 调用点（去重前） | 316 |
| 重放请求 | 92 |
| 符合 2xx + JSON 的响应 | 84 |
这些接口中的许多响应虽然是 HTTP 200，正文却明确返回 code: 401。发现接口、收到 200，都不等于发现漏洞。 在这次示例中，AI 完整分析了 84 条重放结果，没有标记疑似接口。
常见用法
| 场景 | 命令 |
|---|---|
| 只发现接口，不主动重放 | tracesurface scan https://target.example --no-replay |
| 批量扫描，最多同时处理 10 个站点 | tracesurface scan -f targets.txt -s 10 |
| 显示浏览器，手动操作页面 | tracesurface scan https://target.example --headed --wait-ms 15000 |
| 保存浏览器登录态供采集使用 | tracesurface login https://sso.example.com |
| 采集时也不使用已保存的登录态 | tracesurface scan https://target.example --no-auth |
| 启动本地报告 | tracesurface serve |
运行 tracesurface scan --help 查看完整参数。数据默认保存在 ~/.tracesurface/；重新扫描同一站点会替换该站点的旧扫描及关联的 AI 结果。
报告分为 APIs（接口与来源）、Replays（重放报文）、Secrets（前端敏感信息命中）和 AI Review（疑似接口汇总）。
工作原理
flowchart LR
A[浏览器请求与调用栈] --> C[对齐源码调用点]
B[JavaScript AST 与懒加载代码] --> C
C --> D[还原接口与来源证据]
D --> E[无认证重放]
E --> F[本地报告]
F --> G[手动选择站点]
G --> H[AI Review]
接口的证据层级
| 层级 | 含义 |
|---|---|
| runtime | 浏览器实际发出过请求 |
| full-url | 源码中已有完整 URL |
| L1 | 路径可唯一绑定到已知 baseURL |
| L2 | 通过 client 关系或扇出绑定 |
| L3 | 使用本轮扫描发现的全局 baseURL |
| L4 | 使用目标站点 origin 兜底 |
| no-url | 发现调用点，但尚未还原出完整 URL |
证据层级描述接口地址的来源与推导依据，不表示漏洞风险等级。
基于 Python、Playwright/CDP、tree-sitter、SQLite、FastAPI、React 与 Pydantic AI 构建。
使用范围
仅扫描你拥有或已获授权的目标。默认重放会主动发送 GET 和 POST；其他方法需要显式启用 --allow-destructive。URL 或请求体本身可能携带凭据，复核时仍需检查实际报文。