pis10/TraceSurface: .\tracesurface.exe scan

TraceSurface 面向渗透测试、安全评估与 API 资产盘点。它用真实浏览器收集前端资源，用 tree-sitter 从 JavaScript 里提取 API 调用点，再拿 CDP 捕获的真实请求校准 URL。两条线索互相补足：流量里没出现的接口，代码里有；代码里看不全的地址，流量能补。找到的候选接口还会去掉浏览器认证信息重放一遍，用来验证未授权访问和弱鉴权。

实战：只扫登录页

拿若依官方 Vue 演示站做个实验。入口就是登录页，不给登录态，也不点进后台：

tracesurface scan https://vue.ruoyi.vip/login

登录页自己会请求 GET /prod-api/captchaImage。TraceSurface 把这条请求和 app.js 里的 /captchaImage 调用点对齐，确认 /prod-api 是接口前缀，然后顺着入口脚本和 webpack 懒加载 chunk 继续往下挖：

大约 61 秒后：

结果远不止验证码和登录接口——角色、菜单、部门、字典、监控、AI 会话，后台模块的 API 都从一个登录页里还原了出来。

[!NOTE] 88 条 2xx 里，有 79 条在响应体返回了 code: 401。HTTP 2xx 只代表请求被受理，不代表业务成功，判断未授权访问还要看响应内容。

核心能力

• 真实浏览器采集：记录 Fetch/XHR、发起调用栈、脚本、路由和微前端入口，看到的就是浏览器��到的一切。
• AST 接口提取：用 tree-sitter 解析 JavaScript，识别 fetch、XHR、axios、自定义封装和网关调用。
• 懒加载发现：解析 webpack / Vite 的 chunk 映射，主动拉取业务 chunk，不被动等页面触发。
• 运行时校准：把 CDP 发起栈对齐到源码调用点，确认请求并推导 baseURL。
• 证据分层：推导出的 URL 按 L1–L4 标注依据和可信度，每条结论都有出处。
• 无认证重放：去掉 Cookie、Authorization 等请求头重新发送，从攻击者视角验证接口。
• 本地报告：API、真实流量、重放结果和敏感信息，收在一个本地页面里看。

快速开始

从 GitHub Release 下载对应平台的 v1.0.5 压缩包：

解压后，在文件所在目录运行：

# macOS / Linux
./tracesurface scan https://target.example

# Windows PowerShell
.\tracesurface.exe scan https://target.example

TraceSurface 优先使用本机 Google Chrome。未检测到 Chrome 时，首次扫描会自动下载 Chromium 到 ~/.tracesurface/browsers/。启动本地报告：

./tracesurface serve

浏览器打开 http://127.0.0.1:8765。

只想发现 API、不执行主动重放：

./tracesurface scan https://target.example --no-replay

git clone https://github.com/pis10/TraceSurface.git
cd TraceSurface

uv sync

常见用法

login 会把 Playwright storage_state 和可选的 sessionStorage 保存到 ~/.tracesurface/auth.json，后续扫描默认自动加载。

scan 的完整参数：

如何解读未授权结果

TraceSurface 会重放两类请求：从前端源码推导出的 API 候选，以及浏览器捕获到的 Fetch/XHR 请求。

重放保留 URL、method、body 和 Content-Type，但不带浏览器里的 Cookie、Authorization 等认证头——拿到的就是未授权视角下的真实响应。默认只发送 GET 和 POST；其他方法需显式使用 --allow-destructive。

判断结果时记住一点：HTTP 2xx 不等于业务成功。不少接口对未授权请求也返回 200，只是在响应体里给 code: 401。结合响应内容和权限边界下结论。

报告视图

���作原理

URL
 └─ Collection   浏览器 / CDP / 路由 / 前端产物 / 微前端
     └─ Extraction   JavaScript / HTML AST → request、base、alias、secret facts
         └─ Inference   运行时对齐 / 值解析图 / client 身份图 → L1–L4
             └─ Storage   SQLite 证据模型
                 └─ Replay   去认证重放与结果回链

运行时请求为静态分析提供真实 URL，静态调用点则补足单次浏览没有触发的 API。

关键设计：Stack-to-AST Alignment

抓包知道请求去了哪里，静态分析知道请求写在哪里。TraceSurface 用 JavaScript 发起栈把两者对齐。

flowchart LR
    A["CDP<br/>真实请求 + 发起调用栈"] --> C["坐标对齐<br/>script URL · line · column"]
    B["tree-sitter<br/>API 调用点 + source span"] --> C
    C --> D["Confirmed<br/>运行时请求 ↔ 源码调用点"]
    D --> E["Evidence-driven<br/>API Surface"]

1. CDP 记录 Fetch/XHR 的脚本、行号和列号。
2. tree-sitter 提取 API 调用点及源码位置。
3. 坐标命中后，请求被标记为 Confirmed，并可为其他调用点提供 baseURL。

证据层级

Confirmed 表示运行时请求已命中源码调用点；L1–L4 表示其他 URL 的推导强度。

数据目录

数据默认保存在 ~/.tracesurface/，可以通过 TRACESURFACE_HOME 指定其他目录。

~/.tracesurface/
├── tracesurface.db
├── responses/
├── sources/
├── logs/
├── browsers/       # 备用 Chromium（按需）
└── auth.json

技术栈

• Python、Typer、asyncio、httpx
• Playwright、Chrome DevTools Protocol
• tree-sitter、tree-sitter-javascript
• SQLite、FastAPI、Uvicorn
• React、TypeScript、Vite、Tailwind CSS

安全与授权

TraceSurface 只应用于你拥有或已获得明确授权的目标。扫描默认会主动发送 GET 和 POST；--allow-destructive 会放行其他方法。不需要验证时请使用 --no-replay。