GoalBuddy 安全深度解析:本地看板如何抵御 DNS 重绑定与 CSRF 攻击
GoalBuddy 安全深度解析:本地看板如何抵御 DNS 重绑定与 CSRF 攻击
GoalBuddy 是让 Codex 与 Claude Code 能把长任务 /goal 跑到底的开源工具,其中的**本地看板(Local Goal Board)**会启动一个小型本地服务器,把任务状态实时推送到浏览器。既然是服务器,就免不了面对安全攻击——这篇文章带你拆解 GoalBuddy 本地看板如何优雅抵御 DNS 重绑定 与 CSRF(跨站请求伪造) 两类经典攻击,机制清晰、代码极少,新手也能看懂。
一、先认识 GoalBuddy 本地看板
运行一条命令:
npx goalbuddy board docs/goals/<slug>
GoalBuddy 就会:
- 在目标目录生成静态看板文件(
index.html、styles.css、app.js); - 启动一个只绑定在本机回环地址的 Node 服务器;
- 监听
state.yaml、notes/等文件变化,通过 Server-Sent Events 实时推送看板更新。
它的默认姿态非常克制:服务器绑定 127.0.0.1:41737,对外展示 goalbuddy.localhost 这个域名(各操作系统都会把 *.localhost 自动解析到本机,无需改 hosts 文件):
📁 本地看板模块入口:goalbuddy/surfaces/local-goal-board/,使用边界说明见 README.md。
二、为什么本地服务器也要防攻击?
很多初学者有个误区:"只在本机跑的服务器,没人能访问,何来安全问题?"
其实恰恰相反——攻击者不需要访问你的网络,他只需要让"你打开的网页"来访问你本机的服务:
| 攻击类型 | 一句话原理 | 对本地看板的可能危害 |
|---|---|---|
| DNS 重绑定(DNS Rebinding) | 攻击域名先解析到外部 IP,再悄悄改成 127.0.0.1,骗过浏览器"同源策略" |
恶意网页远程读取你的看板数据 |
| CSRF(跨站请求伪造) | 恶意网页诱导你的浏览器向 127.0.0.1 发起携带 Cookie 的请求 |
恶意网页篡改你的看板设置、注册任意目录 |
浏览器认为"同源"就能随意读数据、发请求,而你的本地看板又恰好听在回环地址上,于是这两条路都通向本地服务。GoalBuddy 的解法不是加密,而是在最外层把"你是谁"验证清楚。
三、防线一:Host 头白名单,一招破 DNS 重绑定
DNS 重绑定最狡猾的地方在于:即便域名解析成了 127.0.0.1,请求里携带的 Host 头依然是攻击者的域名。GoalBuddy 抓住了这一点——它只信任一小撮"本地域名",其余一律拒绝。
允许访问的 Host 名是硬编码的白名单,只有 localhost、127.0.0.1、[::1]、goalbuddy.localhost 以及用户显式指定的绑定主机:
const allowedHostnames = new Set(["localhost", "127.0.0.1", "[::1]", "::1", DEFAULT_PUBLIC_HOST]);
每个请求进入处理逻辑前,先经过 requestHostAllowed 校验,不认识的 Host 直接返回 403,响应体写着 Unexpected Host header for the GoalBuddy local board.(见 local-goal-board.mjs#L198-L201)。
效果非常直观:
- ✅ 浏览器访问
goalbuddy.localhost:41737→Host: goalbuddy.localhost→ 放行; - ❌ 攻击域名
evil.example重绑定到127.0.0.1→Host: evil.example→ 403 拒之门外。
重绑定把"地址"改了,却改不了"署名"。白名单验的是署名,所以攻击无效。
四、防线二:Origin 校验,封杀跨站 CSRF
DNS 重绑定被挡掉之后,还有一条路:恶意网页用 <form> 或 fetch 向本地服务发 POST/PUT 请求,浏览器会自动带上同源凭据,这就是 CSRF。
GoalBuddy 对所有会改变状态的方法(POST、PUT)追加 originAllowed 校验:Origin 头若存在,其主机名必须同样落在本地白名单内,否则返回 403 Cross-site requests are not allowed for the GoalBuddy local board.(见 local-goal-board.mjs#L202-L205)。
这意味着两个高危接口天然免疫跨站调用:
POST /api/boards:注册新看板目录(恶意网页无法让你把任意目录挂上看板);PUT /api/settings:修改看板设置(恶意网页无法篡改你的主题、密度等偏好)。
同源的正常请求(例如看板页自身发 Origin: http://127.0.0.1:41737)不受影响,日常使用零感知。
💡 设计巧思:GET 类只读请求不强制 Origin,Host 白名单仍是第一道闸;只有"写操作"才叠加 Origin 校验,属于最小化限制,避免误伤正常体验。
五、防线三:纵深防御的细节
两道主防线之外,GoalBuddy 还埋了几个容易被忽略但很关键的细节:
- 只监听回环地址:默认 DEFAULT_BIND_HOST 为
127.0.0.1,局域网内其他设备根本无法建立连接,攻击面从物理层就收窄了; - 静态路径防穿越:静态文件服务用正则
/^\/<a href="https://link.gitcode.com/i/a4bee7436b20c39fed4ddc7831443973" target="_blank">A-Za-z0-9_.-]+$/限定路径形态,直接让..这类目录穿越字符无处遁形([serveStatic); - 请求体大小上限:
/api/boards等接口读取 JSON 时,超过 1 MB 直接抛错,防止大报文拖垮本地进程(readJsonRequest); - 设置字段白名单:
PUT /api/settings的入参会经过normalizeSettings归一化,只保留已知键名与合法取值,多余字段静默丢弃,写进~/.goalbuddy/local-board-settings.json的永远是干净数据(local-goal-board.mjs#L618-L636)。
六、测试即证据:两条关键安全用例
安全声明不能只靠文档,GoalBuddy 把这两道防线写进了自动化测试(local-goal-board.test.mjs):
rejects requests with a non-local Host header:手动构造Host: evil.example的原始请求,断言返回 403,而127.0.0.1正常访问返回 200(test#L943-L964);rejects cross-site POST /api/boards:带Origin: http://evil.example的跨站 POST 断言 403,同源 POST 断言 200(test#L966-L995)。
也就是说,"攻击被拒"这件事本身是可回归、可复验的工程质量,而不是一句口号。
七、给用户的快速自查清单
如果你也在为自己的本地工具搭 Web 服务,可以照着 GoalBuddy 的思路自查:
- [ ] 服务器是否只绑定
127.0.0.1,而不是0.0.0.0? - [ ] 是否维护了一份本地域名 Host 白名单,陌生
Host直接 403? - [ ] 所有 POST/PUT 是否校验 Origin 头,拒绝跨站来源?
- [ ] 静态文件路径是否限制字符集,杜绝
..穿越? - [ ] 请求体是否设置了大小上限?
- [ ] 以上每一条是否都有对应的自动化测试兜底?
八、总结
GoalBuddy 本地看板的安全设计可以浓缩成一句话:不信任网络,只信任"本地签名"。
它没有引入复杂的令牌或加密体系,而是用 127.0.0.1 回环绑定 + Host 白名单 + Origin 校验三件套,把 DNS 重绑定和 CSRF 这两条最现实的攻击路径都切断了,再用测试固化下来。对于"本地工具也要按服务标准来防"这个课题,它给新手和普通用户提供了一个足够简单、又足够完整的范本——安全不是大项目的专属,本地看板也能做到滴水不漏。


