Claude Code 2.1.221 现在允许 Linux 和 WSL2 用户在沙箱命令读取凭据文件之前对其进行掩码处理。该功能会向命令提供一个无害的哨兵副本（sentinel copy），仅当允许的请求通过代理时，才会将真实的密钥替换进去。

掩码流程说明

  1. 哨兵副本 (Sentinel copy) – 当文件被标记为需要掩码时，Claude Code 会创建一个副本，其中包含占位符字符串，而非真实的密钥。
  2. 代理替换 (Proxy swap) – 沙箱在 TLS 终止代理（TLS-terminating proxy）后运行。如果沙箱发出的请求匹配 injectHosts 列表中的条目，代理会在请求离开机器之前，将占位符替换为真实的令牌（token）。
  3. 错误处理 – 如果提取正则表达式（regex）未能找到密钥，沙箱可以中止运行，而不是在原始文件暴露的情况下继续执行。

该方法仅适用于 Linux 和 WSL2；macOS 目前默认为“硬拒绝”（hard deny），这意味着沙箱完全无法读取该文件。

安全发布的检查清单

验证版本

  • 确认您正在运行 Claude Code 2.1.221 或更高版本。终端中的版本字符串是唯一可靠的方法；包锁定文件（package lock files）可能会产生误导。

使用一次性令牌

  • 切勿使用您的主要 GitHub 或云端凭据进行实验。创建一个指向无害“金丝雀”（canary）端点的短期令牌，并在出现问题时立即撤销。

选择正确的掩码模式

模式 使用场景
File Deny 硬性拦截；任何读取尝试都会失败。
Whole-File Mask 文件包含单个密钥（例如明文 API 密钥）。
Structured Mask 文件将密钥与其他数据混合（JSON、YAML、.netrc）。使用 extract 模式，并使用将密钥捕获在 group 1 中的正则表达式。这可以保持客户端程序的周围语法有效。

设置严格的错误规则

  • 将 onExtractNoMatch 设置为 error。如果正则表达式不匹配，沙箱将停止。如果保持默认的 warn，可能会导致原始文件在未被察觉的情况下泄露。

启用 TLS 终止

  • 代理必须终止 TLS 才能执行替换。如果没有 TLS 终止，代理无法查看请求负载（payload），替换操作也就无法进行。

收紧主机范围

  • 在 injectHosts 中填入来自 allowedDomains 的明确主机名。避免使用像 *.example.com 这样的通配符；宽泛的模式会扩大攻击面，从而违背掩码设计的初衷。

验证结果

  • 扫描日志、进程参数和错误消息，检查是否出现了真实的令牌。在这些产物中，哨兵值应该是唯一出现的值。

需要注意的局限性

掩码仅从沙箱命令的文件系统视图层面保护令牌。它并不能阻止命令发起任意的网络调用，也无法防御可能拥有特权访问权限的 Claude 内置工具。

总结

Claude Code 2.1.221 的凭据掩码功能为 Linux 和 WSL2 开发者提供了一种将密钥排除在沙箱进程之外的实用方法。