didrod205/cookie-doctor

你设置了一个会话 cookie 并发布了它。但它发布时没有带 `HttpOnly`（因此任何 XSS 攻击都可以窃取它），没有带 `Secure`（因此它会在明文 HTTP 上传输），带有 `SameSite=None` 却没有带 `Secure`（因此浏览器**会完全拒绝它**），或者带有 `__Host-` 前缀却悄悄违反了其严格规则——结果现在登录总是莫名其妙地失效。 你往往是在渗透测试中、控制台警告中，或是凌晨 3 点的事故中才发现这些问题。 **cookie-doctor 可以在本地确定性地检查 `Set-Cookie` 中的这些问题**——无论是从字符串、`curl -I` 响应还是配置文件中。它熟知 `__Host-`/`__Secure-` 前缀规则以及 `SameSite=None`↔`Secure` 的相互作用，这些正是人们经常弄错的精确规范。 ``` npx cookie-doctor scan -c "sid=abc; SameSite=None" ``` ``` sid 46/100 (F) ✗ SameSite=None without Secure — the browser rejects the cookie [SameSite] ✗ No HttpOnly — this looks like a session cookie, JS can read it [HttpOnly] ✗ No Secure — sent over plaintext HTTP [Secure] ``` ## 为什么选择 cookie-doctor？ - 🧨 **它能捕获“静默丢弃”型 bug。** 没有 `Secure`、带有 `Domain` 或没有 `Path=/` 的 `__Host-`；没有 `Secure` 的 `SameSite=None`——浏览器会直接拒绝这些 cookie，导致你的会话*直接失效*。cookie-doctor 会将它们标记为**有效性**错误，而不是代码风格问题。 - 🎯 **懂得会话 cookie 重要性的严重性分级。** 在 `sid`/`auth`/包含 JWT 值的 cookie 上缺少 `HttpOnly` 是一个**错误**；而在 `theme=dark` 上则只是轻微警告。没有多余的噪音。 - 🔒 **本地且具有确定性。** 无需网站，无需 API key，可离线运行并集成到 CI 中。相同的 cookie → 相同的结果。阻止那些发布了不安全会话 cookie 的 PR。 - 🧩 **随处读取。** 原始的 `Set-Cookie`、`curl -I` 的输出、nginx 的 `add_header`、Apache 的 `Header set` 或是 `vercel.json`。 为什么不直接把它粘贴给 LLM？因为 `__Host-`/`__Secure-` 规则和 `SameSite=None`/`Secure` 的相互作用是极其精确的规范，而聊天机器人往往会给出不太正确的细微错误——此外，你肯定希望这种校验能在**每一个** PR 上持续拦截不安全的会话配置，而不是只做一次。 ## 安装 ``` # 立即运行 npx cookie-doctor scan -c "" # 或添加它 npm install -g cookie-doctor # global CLI npm install -D cookie-doctor # CI dependency ``` Node ≥ 18。核心代码零依赖且对浏览器安全。 ## 快速开始 ``` cookie-doctor scan -c "__Host-sid=abc; Secure; HttpOnly; SameSite=Lax; Path=/" curl -sI https://example.com | cookie-doctor scan # straight from a response cookie-doctor scan headers.txt _headers vercel.json # from configs cookie-doctor scan -c "" --min-score 80 # CI gate cookie-doctor scan headers.txt --md cookies.md # Markdown report cookie-doctor init # write a config ``` 请参阅 [`examples/sample-report.md`](./examples/sample-report.md)，以及查看评分高达 100 的 cookie 示例 [`examples/strong.cookie.txt`](./examples/strong.cookie.txt)。 ## 检查内容 | 分组 | 示例 | | ----- | -------- | | **将被浏览器丢弃** | `__Host-`/`__Secure-` 前缀规则（必须包含 Secure，不能带有 Domain，必须包含 `Path=/`），没有 `Secure` 的 `SameSite=None`，无效的 `SameSite`，大小超限 (> 4 KB) | | **XSS / 被窃取** | 缺少 `HttpOnly`（在会话/token cookie 上为错误） | | **CSRF** | 缺少 `SameSite` | | **传输** | 缺少 `Secure` | | **作用域** | `Domain` 与子域名共享，旧式的带前导点 `Domain` | | **生命周期** | 长生命周期的认证 cookie（阈值可配置） | 每一项发现都是具有相应权重的错误 / 警告 / 信息；cookie 最终会汇总为一个 0–100 的分数以及 A–F 的等级，你可以在 CI 中将其作为拦截标准。 ## 实际场景 **1. 在 CI 中拦截不安全的会话 cookie。** 如果一个 PR 添加了没有 `HttpOnly`/`Secure` 的认证 cookie，或者违反了 `__Host-` 规则，CI 构建将会失败： ``` # .github/workflows/ci.yml - run: curl -sI http://localhost:3000/login | npx cookie-doctor scan --min-score 90 ``` **2. 审计你的框架实际发送的内容。** 将真实的响应通过管道传递给它——比如 `express-session`、NextAuth 或是反向代理——看看你*自以为*设置了的属性到底是什么样。 **3. 梳理安全漏洞。** 扫描器提示“不安全的 cookie”——`cookie-doctor` 会告诉你*具体是哪个*属性以及*为什么*有问题，并提供确切的修复方案。 ## 配置 `cookie-doctor init` 会生成 `cookie-doctor.config.json` 文件： ``` { "ignore": [], // rule ids to skip "sessionNames": ["session", "sid", "auth", "token", "jwt", "..."], "maxAgeDays": 30, // warn above this lifetime "minScore": 0 // CI gate threshold } ``` ## 库 API ``` import { analyzeSetCookie, DEFAULT_CONFIG } from "cookie-doctor"; const report = analyzeSetCookie("inline", "sid=abc; Secure", DEFAULT_CONFIG, Date.now()); for (const f of report.findings) console.log(f.severity, f.rule, f.attribute); ``` 同样导出的有：`parseSetCookie`、`checkCookie`、`extractCookies`、`lifetimeSeconds` 以及各种类型定义。核心代码零运行时依赖。 ## 路线图 - 🤖 **可选的 `--ai` 层（自带 API key）** 用于结合上下文解释 cookie 的风险 / 建议更安全的 header。核心功能依然保持 100% 离线且具有确定性。 - `Partitioned` (CHIPS) 属性感知。 - 从保存的 `.har` 文件或浏览器 cookie 导出中读取 cookie。 - ✅ **一个浏览器演练场**——粘贴一个 `Set-Cookie`，查看审计结果，不上传任何数据。 [在此体验](https://didrod205.github.io/cookie-doctor/)。 ## 💖 赞助 cookie-doctor 是免费且采用 MIT 许可证的开源项目，利用业余时间开发和维护。如果它在你的用户之前帮你发现了不安全的 cookie，请考虑支持它： - ⭐ **给本仓库点个 Star**——帮助他人发现它的最简单、免费的方式。 - 🍋 **[通过 Lemon Squeezy 赞助](https://elab-studio.lemonsqueezy.com/checkout/buy/5d059b89-51d0-456b-b33a-ed56994f7010)**——支持一次性或周期性赞助。 ## 许可证 [MIT](./LICENSE) © cookie-doctor 贡献者

标签：Cookie, MITM代理, Web安全, 安全合规, 暗色界面, 网络代理, 自动化攻击, 蓝队分析