viewllm 安全设计解读:路径穿越防护、文件类型白名单与只读无状态架构
viewllm 安全设计解读:路径穿越防护、文件类型白名单与只读无状态架构
viewllm 是一个面向 AI 编码代理(Claude Code、Codex、Cursor 等)生成产物的单二进制 HTML 报告查看器,在终端执行 npx viewllm@latest 即可把本地报告变成可浏览、可分享的网页。因为它要通过 HTTP 把本地文件暴露出去,安全设计格外值得拆解:本文结合源码,讲清它的 路径穿越防护、文件类型白名单 与 只读无状态架构 这三道防线是怎么工作的。
为什么轻量文件查看器也需要安全设计
viewllm 会在项目目录启动一个 HTTP 服务,把报告渲染到浏览器里,而且监听的是局域网端口(-tunnel 时还会生成公网链接)。这意味着只要端口可达,任何人都是"访客"。如果实现 sloppy,很容易变成文件泄露后门:
- 🔓 路径穿越:URL 里拼上
../../etc/passwd,就能读服务器上的任意文件 - 📄 任意文件类型:配置文件、密钥、源代码都可能被拖走
- ✍️ 写风险:如果 API 存在写入/删除操作,本地报告可能被篡改
viewllm 的思路是纵深防御:不信任任何输入,逐层校验,并把攻击面压到最小。
路径穿越防护是如何生效的:Clean + Abs + 前缀检查
文件请求统一走 /files/{path} 路由,处理函数 handleFiles 做了三步校验:
- 清理路径:
filepath.Clean规范化..、重复分隔符等 - 拼接并绝对化:与根目录
rootDir拼接后用filepath.Abs得到最终绝对路径 - 前缀检查:绝对路径必须以
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 的架构本身就具备三个特点:
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
- 默认只在本机/局域网使用,服务自动寻找可用端口,不主动外发
- 公网链接临时化:
-tunnel生成的公开 URL 在进程停止时即失效,每次启动都是新的随机链接,不存在长期暴露 - 缩小暴露面:扫描大型项目时用
-exclude排除无关目录 - 保持更新: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 文件中,通读一遍就是一篇很好的安全入门小教程。


