Cookie安全属性实战：HttpOnly、SameSite、Secure与检查链

简介：这份 JavaScript 工具集面向对浏览器安全与扩展机制感兴趣的读者，围绕 Cookie 的读取与演示展开，可用于前端安全入门、Web 安全课程实验或本机自测演练，帮助理解 Cookie 在会话中的作用与风险边界。压缩包共 7 个文件，约 33KB，含 3 个 JavaScript 脚本、1 个 Python 服务端脚本、1 个 HTML 页面、1 个 JSON 配置文件和 1 份 Markdown 说明文档，体量轻便、结构紧凑。目前已有 186 人学习下载。读者可借此观察浏览器扩展的目录组织与清单配置写法，了解前端脚本与本地服务端之间的配合方式，并借助说明文档快速运行示例；其中 Python 服务端承担本地接收与调试的角色，HTML 页面提供演示入口，脚本文件负责核心逻辑，适合边读边改、逐层拆解请求流程与数据流向，也便于在此基础上改造出自己的实验样例。

1. cookie-stealer 这类脚本，现在还能拿走什么

上周有读者丢来一个压缩包，名字叫 cookie-stealer，说是一个几十行的 JavaScript 小工具，问这东西到底还能不能用。我扫了一眼代码结构，思路很老派：靠一段注入到页面里的脚本把document.cookie整个读出来，再拼成请求发到收集端。这类脚本能不能得手，完全取决于目标站点的 Cookie 属性配置——属性配得松，它一行代码就够；属性配得紧，它连一个字符都拿不到。下面从防御方视角拆开讲：Cookie 的可见边界在哪、三个属性怎么配、自己搭靶场怎么验证、上线后哪些地方最容易翻车。前端开发、做业务安全基线的同学可以直接照着复现。

2. Cookie 被 JavaScript 读走的三道门：document.cookie、HttpOnly 与 SameSite

先建立一个基础认知：浏览器里的 Cookie 不是"存在某个地方等着被读"，而是每次请求时由浏览器按规则挑出来放进Cookie请求头。脚本能读到的那部分，只是浏览器愿意暴露给document.cookie的一个字符串视图。这个视图的筛选规则，就是 HttpOnly、Secure、SameSite、Domain、Path 这几项在起作用。理解这套筛选逻辑，比记住"加个 HttpOnly 就好了"有用得多，因为实际项目里翻车的基本都在这几项的边界上。

2.1 document.cookie 的可见边界到底在哪

document.cookie是一个同步的字符串接口，读的时候返回当前文档可见的全部非 HttpOnly Cookie，格式是k1=v1; k2=v2，多个之间用分号和空格分隔；写的时候一次只能写一条，写法是document.cookie = "k=v; path=/; max-age=3600"。注意写入是"追加或覆盖"语义，不是整体替换——你写一条不会把别的 Cookie 冲掉，这也是很多人第一次调试时困惑的点。

可见性由三个维度共同决定：

第三行是重点。HttpOnly 不是建议、不是约定，是浏览器在实现层把这条 Cookie 从脚本可见集合里剔除了。哪怕页面已经被注入了任意 JavaScript，document.cookie里也不会出现它。所以第 1 章那个脚本的真实能力边界就是：能拿到所有漏配 HttpOnly 的 Cookie，拿不到配了的。

还有一个容易忽略的点：document.cookie返回的是解码前的原始值。如果服务端写入时做过 URL 编码，读出来看到的是%3D这类转义序列，脚本想还原还得自己 decode。这层编码不构成安全边界，但会让粗糙的收集脚本拿到一堆看起来像乱码的东西。

2.2 HttpOnly 挡住的是读取，不是发送

这句话值得单独拎出来说，因为它是最高频的认知错误。HttpOnly 的语义是"这条 Cookie 不暴露给脚本读取接口"，而不是"这条 Cookie 不参与请求"。登录态 Cookie 加了 HttpOnly 之后，页面里的fetch('/api/profile')照样会把凭证带上，浏览器照常发。这一点既是好事也是隐患：

好事在于，正常的业务前端代码根本不需要读登录态 Cookie，因为它只需要"带上"，不需要"看见"。所以给会话 Cookie 加 HttpOnly 几乎没有改造成本。

隐患在于，攻击者拿不到 Cookie 原文，不代表拿不到"以你的身份发请求"的能力。页面里只要能执行任意脚本，就可以直接调接口、读返回值——这叫会话内的请求伪造，和偷 Cookie 是两条路。所以 HttpOnly 解决的是"凭证被带走、拿到别处长期复用"，不解决"当前页面被完全控制"。真正的纵深是：HttpOnly 防外带、CSP 限制脚本来源和数据出口、输入输出过滤防注入，三层各管一段。

我一般的配置原则是：

• 会话标识（session id、token）一律 HttpOnly，没有例外；
• 需要前端读的东西（主题、语言、灰度标记）不要塞进会话 Cookie，单独开一条不带 HttpOnly 的；
• 前端需要用户身份信息时，走一个接口返回，别往 Cookie 里塞。

最后一条能省掉大量"要不要给这条 Cookie 去掉 HttpOnly"的争论——如果一开始就没往里塞，就没这个纠结。

2.3 SameSite 与 Secure 决定跨站时会不会被捎带

HttpOnly 管"读不读得到"，SameSite 管"什么时候会被自动带上"，Secure 管"走不走加密通道"。三者互相独立，缺一个就是缺一层。

Secure 最简单：打了这个标记，浏览器只在 HTTPS 连接上发送该 Cookie。在 HTTP 页面上，这条 Cookie 既不会被发出去，也不会被写入。本地开发时用localhost通常不受限制，但换成局域网 IP 访问就会失效，这是本地联调时很常见的一个"明明设了却没生效"。

SameSite 有三个取值，行为差异是实打实的：

• Strict：任何跨站请求都不带。从外站点链接跳进来，第一次请求也是未登录状态，用户体验上会有"点链接进来要重新登录"的观感。
• Lax：跨站的顶层导航（点击链接跳转、地址栏输入）会带，跨站的子资源请求、表单 POST、fetch 不带。这是目前多数浏览器的默认值。
• None：跨站一律带，但必须同时有 Secure，否则整条 Cookie 被丢弃。

None是嵌入场景（比如页面被别的站点以 iframe 引用）绕不开的选项，但它把跨站请求伪造的防护责任又推回给了服务端，需要额外的 CSRF token 或来源校验来补。我见过不少项目在接入第三方嵌入时，直接把会话 Cookie 改成SameSite=None; Secure，然后就不再管 CSRF——这一步是真的会出事。

比较稳妥的拆法是按 Cookie 的用途分：会话 Cookie 用Lax（或Strict，看跳转体验能否接受），确实需要跨站携带的单独开一条、范围收窄、生命周期短。别为了一条边缘 Cookie 把整个站点的会话策略放松。

3. 自建靶场验证：把三个属性逐个打开看效果

配了不等于生效。属性拼写错误、作用域写错、中间层重写了响应头，都会让配置看起来对、实际没生效。最稳的验证方式是自己在本地起一个可控站点，把三种配置都摆出来，然后用浏览器和脚本各验一遍。

3.1 用 Express 起一个可控的演示站点

下面这段起一个最小站点，登录接口同时下发三条 Cookie：会话用 HttpOnly+Secure+SameSite=Lax，界面偏好不带 HttpOnly，跨站嵌入用的单独一条 SameSite=None。三条并排放，方便对照观察。

// server.js —— 本地演示用，仅监听 127.0.0.1 const express = require('express'); const app = express(); app.get('/login', (req, res) => { // 1) 会话 Cookie：脚本不可读，跨站子请求不携带 res.cookie('sid', 'demo-session-value', { httpOnly: true, secure: true, // 仅 HTTPS 发送；本地 http 下浏览器会拒收 sameSite: 'lax', path: '/', maxAge: 30 * 60 * 1000 // 30 分钟 }); // 2) 界面偏好：故意不加 httpOnly，用来对照 document.cookie 的可见性 res.cookie('ui_pref', 'dark', { httpOnly: false, secure: true, sameSite: 'lax', path: '/', maxAge: 7 * 24 * 3600 * 1000 }); // 3) 嵌入场景专用：跨站可带，但必须 Secure，且作用域收窄 res.cookie('embed_token', 'demo-embed', { httpOnly: true, secure: true, sameSite: 'none', path: '/embed', maxAge: 5 * 60 * 1000 }); res.type('html').send('<h1>ok</h1><p>检查 DevTools > Application > Cookies</p>'); }); app.listen(8443, '127.0.0.1', () => { console.log('http://127.0.0.1:8443/login'); });

代码逻辑很直白：三条res.cookie()分别对应三种策略，注释里标了每一项的意图。几个参数值得说清楚——maxAge单位是毫秒，不是秒，写3600会得到一条 3.6 秒就过期的 Cookie，这是新手最常见的单位错误；path决定可见范围，embed_token收窄到/embed之后，其他路径下的document.cookie都看不到它；secure: true在纯 HTTP 下会让浏览器直接丢弃整条 Cookie，所以本地验证要么上 HTTPS，要么临时把secure关掉再对比。

启动之后访问/login，打开 DevTools 的 Application 面板，能看到三条记录的 HttpOnly、Secure、SameSite 三列分别是什么。然后在 Console 里敲document.cookie，预期只看到ui_pref=dark，另外两条不出现。这一步就是最直接的验证——如果三条全出来了，说明 HttpOnly 没生效，回去查响应头的Set-Cookie原始内容。

3.2 用响应头扫描脚本做回归

手工点一次只能验证一次。配置会被人改、中间层会被人加，所以我习惯把校验做成脚本，接进发布前的检查链。下面这个脚本不依赖页面渲染，只发请求看响应头，判断每条Set-Cookie的属性是否齐全。

// check-cookie.js —— 检查目标地址下发的 Cookie 属性是否达标 const target = process.argv[2] || 'https://127.0.0.1:8443/login'; // 规则表：按 Cookie 名匹配，声明必须具备的属性 const rules = [ { name: 'sid', require: ['HttpOnly', 'Secure', 'SameSite=Lax'] }, { name: 'embed_token', require: ['HttpOnly', 'Secure', 'SameSite=None'] }, { name: 'ui_pref', require: ['Secure'] } ]; const res = await fetch(target, { redirect: 'manual' }); // Node 侧用 getSetCookie 才能拿到多条，get('set-cookie') 会被合并 const raw = res.headers.getSetCookie ? res.headers.getSetCookie() : [res.headers.get('set-cookie')].filter(Boolean); let failed = 0; for (const line of raw) { const name = line.split('=')[0].trim(); const rule = rules.find(r => r.name === name); if (!rule) { console.log(`[SKIP] ${name} 未在规则表中声明`); continue; } for (const attr of rule.require) { // 属性名大小写不敏感，统一小写比对 if (!line.toLowerCase().includes(attr.toLowerCase())) { console.log(`[FAIL] ${name} 缺少 ${attr}`); failed++; } } } console.log(failed === 0 ? '[PASS] 全部属性达标' : `[FAIL] 共 ${failed} 处缺失`); process.exit(failed === 0 ? 0 : 1);

几个实现细节：headers.getSetCookie()是拿多条Set-Cookie的正确方式，用headers.get('set-cookie')在 Node 里会被合并成一条逗号分隔的字符串，属性检查就会误判；redirect: 'manual'是为了避免跟随跳转后丢掉第一跳的响应头；退出码用0/1区分，方便直接挂在 CI 里当门禁。

规则表是这份脚本的核心，它不是通用工具，而是把你这个项目"哪条 Cookie 该有什么属性"固化下来。新加一条 Cookie 却忘了登记规则，脚本会打[SKIP]提示——这个提示本身就有价值，说明有人动了 Cookie 下发逻辑但没更新基线。

实际用法是：

# 本地验证 node check-cookie.js https://127.0.0.1:8443/login # CI 里当门禁，非 0 退出直接中断构建 node check-cookie.js "$STAGING_LOGIN_URL" || exit 1

3.3 浏览器侧的验证步骤

脚本验的是"服务端发的对不对"，浏览器验的是"浏览器最终收下了什么"。中间可能隔着反向代理重写响应头、CDN 缓存、网关统一加工，服务端发对了不代表客户端收到了。

手工验证我走这几步：

1. 开无痕窗口，避免历史 Cookie 干扰判断；
2. 访问登录接口，DevTools 打开 Network，找那条响应，展开 Response Headers 看Set-Cookie原文；
3. 切到 Application > Cookies，核对每条的 HttpOnly / Secure / SameSite 三列；
4. Console 执行document.cookie，确认只返回预期的那几条；
5. 把地址栏换成http://再访问一次，确认标了 Secure 的 Cookie 不再下发。

第 5 步很多人不做，但它能暴露"只在 HTTPS 上测过"的盲区。另外无痕窗口每次关掉都清空，适合反复跑同一套流程，比手动清 Cookie 靠谱。

如果想把这套流程也自动化，用无头浏览器在页面上下文里求值即可：

// verify-in-browser.js —— 在真实页面上下文里看脚本能读到什么 const { chromium } = require('playwright'); const browser = await chromium.launch(); const ctx = await browser.newContext(); const page = await ctx.newPage(); await page.goto('https://127.0.0.1:8443/login'); // 先访问，拿 Set-Cookie await page.goto('https://127.0.0.1:8443/'); // 再进业务页 const visible = await page.evaluate(() => document.cookie); console.log('脚本可见的 Cookie:', visible || '(空)'); // 断言：只应出现 ui_pref，出现 sid 即为 HttpOnly 失效 if (visible.includes('sid')) { console.error('[FAIL] 会话 Cookie 对脚本可见'); process.exit(1); } await browser.close();

page.evaluate()里执行的代码等价于页面自己的脚本，所以它看到的就是"假如有脚本被注入，能拿到什么"。这个视角比看响应头更贴近真实风险。注意要分两次goto：第一次触发登录下发 Cookie，第二次才是真正的可见性检查。

4. 排查：Cookie 防护上线后最常见的五个翻车现场

配置上线之后出问题，八成不是"属性写错了"，而是"属性被别的东西覆盖了"或者"作用域和预期不一致"。下面五条是这几年反复遇到的，按现象、原因、解决三段写。

4.1 属性明明加了，浏览器里却看不到

现象：代码里写了httpOnly: true，服务端日志也确认进了res.cookie()，但 DevTools 的 Application 面板里那条 Cookie 的 HttpOnly 列是空的，document.cookie还能读到。

原因：中间有一层把Set-Cookie重写了。常见的是反向代理或网关做了统一响应头加工，把后端下发的Set-Cookie复制了一份简化版；另一种是应用里有两处下发同名 Cookie，后一处覆盖了前一处，而后者漏了属性。

解决：先用curl -I直连后端端口拿原始响应头，再走网关拿一次，两份对比。如果网关那份缺属性，问题在网关配置；如果两份都缺，说明应用里存在第二次下发。定位同名 Cookie 的重复下发，可以在代码里搜 Cookie 名，也可以在那条响应上打断点看调用栈。

4.2 本地一切正常，线上登录态随机掉

现象：本地开发环境跑得好好的，部署到线上之后用户偶发"刚登录就掉线"，复现不稳定。

原因：横向扩容后有多台实例，会话 Cookie 上的Domain或Path配得不一致，用户请求被负载均衡打到不同实例时，读不到之前写入的那条。也可能是SameSite=Lax遇上了一个跨站的 POST 回跳（比如某些第三方支付回调），回跳请求不带 Cookie，服务端就当成未登录。

解决：先确认Domain和Path在所有实例上完全一致，最好把它们提到统一配置里而不是各写各的；再抓一次掉线时的请求，重点看Cookie请求头在不在、Referer是不是跨站。如果是跨站回跳导致，别急着改成SameSite=None，优先在那条回跳链路上加一个一次性的、短生命周期的凭据来恢复会话，把会话 Cookie 的策略保住。

4.3 加了 Secure 之后，HTTP 环境整条 Cookie 消失

现象：测试环境还是 HTTP，加了secure: true之后 Cookie 完全不写入，登录功能直接不可用。

原因：Secure 的语义是"仅在安全上下文发送"，在 HTTP 页面上浏览器会直接丢弃这条 Cookie，不是"存着不发"。所以本地或内网 HTTP 环境下，加了 Secure 就等于没加。

解决：开发环境用localhost或127.0.0.1（属于安全上下文），或者本地起一个自签证书的 HTTPS；不要为了迁就 HTTP 环境把 Secure 去掉，那等于把这层防护永久关掉。如果必须在局域网 IP 上调试，用一个环境变量控制secure开关，并且确保这个开关在构建生产包时是硬编码为true的，别留成运行时可改。

4.4 SameSite=None 加了，但 Cookie 依然不下发

现象：为了支持 iframe 嵌入，把会话 Cookie 设成SameSite=None，结果嵌入页面里还是拿不到登录态。

原因：SameSite=None必须同时带Secure，缺一个浏览器就整条丢弃。另外如果嵌入方是跨站 iframe，还需要页面本身允许被嵌入（响应头里的框架限制策略），两层限制是独立的，缺任何一层都表现为"拿不到"。

解决：先看响应头里SameSite=None和Secure是不是成对出现；再看被嵌入页面返回的框架限制响应头是否允许当前来源。两层都放开之后，还要评估一件事：SameSite=None意味着这条 Cookie 会在跨站请求里被带上，CSRF 防护不能只靠 SameSite 了，得补 token 校验或来源校验。

4.5 子域之间互相看不到 Cookie

现象：主站登录后，跳到子域的业务页面变成未登录；或者反过来，子域写的 Cookie 主站读不到。

原因：Cookie 的 Domain 属性决定共享范围。不设置 Domain 时，Cookie 是"仅当前主机"的，a.example.com写的 Cookie，b.example.com和example.com都读不到。设成example.com才能全子域共享——但这一步同时也把所有子域拉进了信任边界。

解决：按需要共享的最小范围设置 Domain，能不下放到父域就不下放。确实需要跨子域共享会话时，评估每个子域的可信程度——任何一个子域被拿下，共享的会话 Cookie 就跟着暴露。这种情况下更稳的做法是把会话收敛到一个统一的认证域，业务子域通过短期的、范围受限的凭据换会话，而不是让一条长期会话 Cookie 满天飞。

5. 进阶：把 Cookie 基线固化成一条可执行的检查链

零散地记住"要加 HttpOnly"没有意义，人是会忘的，尤其是在赶需求的时候。我的做法是把 Cookie 策略写成一份声明式的基线表，让检查脚本读这张表去比对，而不是把规则硬编码在脚本里。

这张表有两个作用。一是评审时的讨论载体——新加一条 Cookie，先在这张表里加一行，写清楚为什么需要、为什么是这个策略，讨论就有了具体落点。二是脚本的输入——把表导出成 JSON，检查脚本按它跑，规则变更和代码变更就绑在一起了。

检查链我一般挂三个点：本地提交前跑一次（快，只查开发服务器）、预发环境部署后跑一次（查真实网关链路）、线上按周定时跑一次（防配置漂移）。第三点最容易被忽略，但它抓到的往往是最要命的问题——某次紧急发版顺手改了网关配置，两周后才被定时任务发现。

除了属性检查，还有两条值得一起做进去。

一条是给 Cookie 加上前缀。带__Host-前缀的 Cookie 必须满足 Secure、Path 为/、且不带 Domain，浏览器会强制校验，不满足直接拒收。这相当于让浏览器帮你把关，比靠代码评审可靠。代价是这条 Cookie 不能跨子域共享，用在会话标识上正合适。

另一条是限制数据出口。就算某条 Cookie 漏配了 HttpOnly，只要页面的内容安全策略把connect-src收窄到自家域名，脚本拼出来的外发请求也发不出去。这层不专为 Cookie 设计，但它是最后一道兜底。配置的时候注意别图省事写成通配，那等于没配。

早几年我接手过一个项目，Cookie 属性全靠开发各自加，评审时没人管。上线三个月后做安全巡检，翻出来七条同名不同策略的 Cookie，其中一条会话 Cookie 漏了 HttpOnly，而它恰好是权限最高的那条。从那以后我每次接新项目，第一件事就是把这张基线表建起来，第二件事是把检查脚本挂进流水线——不是为了应付检查，是因为靠人记真的记不住。希望帮到你。

本文还有配套的精品资源，点击获取