viewllm 安全设计解读:路径穿越防护、文件类型白名单与只读无状态架构

原创2026-10-25 23:40:481,026 阅读

viewllm 安全设计解读:路径穿越防护、文件类型白名单与只读无状态架构

viewllm 是一个面向 AI 编码代理(Claude Code、Codex、Cursor 等)生成产物的单二进制 HTML 报告查看器,在终端执行 npx viewllm@latest 即可把本地报告变成可浏览、可分享的网页。因为它要通过 HTTP 把本地文件暴露出去,安全设计格外值得拆解:本文结合源码,讲清它的 路径穿越防护、文件类型白名单 与 只读无状态架构 这三道防线是怎么工作的。

viewllm 报告查看器界面:经白名单过滤的本地 HTML 报告文件树与渲染结果

为什么轻量文件查看器也需要安全设计

viewllm 会在项目目录启动一个 HTTP 服务,把报告渲染到浏览器里,而且监听的是局域网端口(-tunnel 时还会生成公网链接)。这意味着只要端口可达,任何人都是"访客"。如果实现 sloppy,很容易变成文件泄露后门:

  • 🔓 路径穿越:URL 里拼上 ../../etc/passwd,就能读服务器上的任意文件
  • 📄 任意文件类型:配置文件、密钥、源代码都可能被拖走
  • ✍️ 写风险:如果 API 存在写入/删除操作,本地报告可能被篡改

viewllm 的思路是纵深防御:不信任任何输入,逐层校验,并把攻击面压到最小。

路径穿越防护是如何生效的:Clean + Abs + 前缀检查

文件请求统一走 /files/{path} 路由,处理函数 handleFiles 做了三步校验:

  1. 清理路径:filepath.Clean 规范化 ..、重复分隔符等
  2. 拼接并绝对化:与根目录 rootDir 拼接后用 filepath.Abs 得到最终绝对路径
  3. 前缀检查:绝对路径必须以 rootDir/ 开头,否则直接返回 403 Forbidden

核心代码在 main.go:

clean := filepath.Clean(reqPath)
fullPath := filepath.Join(s.rootDir, clean)

absPath, err := filepath.Abs(fullPath)
if err != nil || !strings.HasPrefix(absPath, s.rootDir+string(filepath.Separator)) {
    http.Error(w, "forbidden", http.StatusForbidden)
    return
}

两个细节值得注意:

  • 前缀比较用的是 rootDir + 分隔符,而不是裸 rootDir,避免 /data/reports 与 /data/reports-evil 这类同名前缀目录被误放行
  • main_test.go 中的 TestHandleFilesPathTraversal 直接验证了 GET /files/../../../etc/passwd、GET /files/../../etc/hosts 均返回 403——安全行为被回归测试锁死,后续改动不会悄悄破坏它

文件类型白名单:只暴露明确声明的类型

即使路径在根目录内,也不一定能下发。第二道防线是文件类型白名单(main.go),扩展名必须命中列表:

允许的扩展名 用途
.html .md 报告正文
.png .jpg .jpeg .gif .svg .webp 报告引用的图片与图表

不在名单内一律 403 file type not allowed——代码、配置、脚本、密钥统统拦截。测试 TestHandleFilesAllowedExtensions 对 8 种放行扩展与 .go、.js、.css、.txt、.exe、.sh 等 6 种禁止扩展逐一断言。

扫描阶段还有"粗筛":scan 遍历目录时只收集 .html / .md 文件,白名单之外的文件根本不会出现在文件树里。

viewllm 只读报告浏览界面:Solarized 主题下渲染白名单内的 HTML 报告

只读无状态架构:从设计上消除攻击面

最彻底的安全是不给攻击者任何可操作的抓手。viewllm 的架构本身就具备三个特点:

1️⃣ 只读

服务端没有任何写、删、改名操作,只有 os.Open、os.ReadFile、filepath.WalkDir 这类读操作。全部 API 均为 GET(见 README.md):

API 用途
GET / Web UI
GET /api/recent 最近修改文件(含预览)
GET /api/tree 目录树 JSON
GET /api/excludes 当前排除规则
GET /files/{path} 报告正文

连看似可能"写"的 /api/excludes 也显式拒绝非 GET 请求,返回 405 Method Not Allowed(见 handleExcludes)。

2️⃣ 无状态

文件列表只是内存中的快照,由 pollLoop 每 2 秒重建;预览缓存在内存中,文件删除后自动清理过期条目(测试见 main_test.go)。没有数据库、没有配置文件、没有后台进程——"停下来就消失"(README.md:9MB 二进制、约 7MB 内存、0 依赖)。自定义排除规则存在浏览器 localStorage 里,服务端不留任何痕迹。

3️⃣ 零第三方依赖

整个技术栈是 Go 标准库 + 原生 HTML/CSS/JS,前端通过 go:embed 打进单二进制(main.go)。依赖越少,供应链风险越小。

默认排除规则:敏感内容从不出现在列表里

除了"能下发什么",viewllm 还关心"什么根本不出现在列表里"。两组默认排除清单(main.go)在扫描时生效:

  • 目录:.git、node_modules、venv、__pycache__、dist、build、.idea、.vscode-server 等
  • 文件:CLAUDE.md、AGENTS.md、.cursorrules、.gitignore、.DS_Store 等

也就是说,Git 仓库内部数据、依赖源码和各种 AI 工具配置文件默认不可见;命令行参数 -exclude / -exclude-file 可以追加更多规则(见 README.md 的参数表)。

viewllm 报告查看界面:最近文件列表、文本预览与移动端适配

如何安全地使用 viewllm

  1. 默认只在本机/局域网使用,服务自动寻找可用端口,不主动外发
  2. 公网链接临时化:-tunnel 生成的公开 URL 在进程停止时即失效,每次启动都是新的随机链接,不存在长期暴露
  3. 缩小暴露面:扫描大型项目时用 -exclude 排除无关目录
  4. 保持更新:v0.3.1 曾加入路径穿越与 XSS 修复并补充回归测试,记录在 CHANGELOG.md;用 npx viewllm@latest 始终运行最新版

安全设计总结

防线 机制 生效位置
路径穿越防护 Clean → Abs → rootDir 前缀检查 /files/ 处理函数
文件类型白名单 仅 html / md / 图片扩展名 /files/ 处理函数
只读架构 全 GET API,无写操作 全部 HTTP 路由
无状态 内存快照 + 2 秒轮询重建 pollLoop
默认排除 目录 / 文件两组排除清单 scan
回归测试 403 / 405 状态码断言 main_test.go

viewllm 的安全设计并不复杂,却很适合所有"开本地 HTTP 服务的小工具"借鉴:不信任输入、只暴露必要的东西、不给攻击者留抓手。服务端逻辑集中在单个 main.go 文件中,通读一遍就是一篇很好的安全入门小教程。

登录后查看全文
viewllm