先做一个现场检查:打开当前项目的 .claude/settings.local.json,搜索 token、password、secret、Authorization、PGPASSWORD、sshpass 和数据库连接串。
如果里面出现了真实凭据,问题已经超出权限配置。这个文件需要按敏感数据事件处理。即使 Git 状态干净,也要继续检查历史提交、fork、构建目录和已经发布的制品。
原因很直接。Claude Code 可以把永久 Bash 批准写成 allow 规则。一次带密码的排障命令,经过不要再询问这一步,就可能从短期输入变成长期文件。
本文从处置现场出发,回答三个问题:秘密是否已经形成副本,副本传播到了哪里,以及怎样证明旧凭据已经失效。
十分钟确定暴露面
第一轮检查只读,不急着删除文件:
# 1. 文件是否存在,是否包含需要人工复核的命令上下文
test -f .claude/settings.local.json && \
grep -nEi 'token|password|secret|authorization|pgpassword|sshpass|mysql -p' \
.claude/settings.local.json
# 2. Git 是否忽略它,是否已经跟踪
git check-ignore -v .claude/settings.local.json
git ls-files --error-unmatch .claude/settings.local.json
# 3. 历史中是否出现过这条路径
git log --all -- .claude/settings.local.json
# 4. 暂存区是否正在提交 Agent 配置
git diff --cached -- .claude/
这四项分别回答当前内容、ignore 来源、Git Index 和历史对象。结果要分开解释:
| 结果 | 含义 | 下一步 |
|---|---|---|
| ignored 且 untracked,内容无字面量秘密 | 常规本地状态 | 继续检查构建与同步路径 |
| ignored 但 tracked | ignore 对已有跟踪无效 | 立即检查当前与历史秘密 |
| 当前文件干净,历史存在 | 删除发生在泄露之后 | 轮换凭据,评估历史清理 |
| 未进入 Git,但出现在镜像或压缩包 | 制品链绕过 Git | 停止发布并清理下游副本 |
任何扫描结果都只是线索。先保存文件路径、提交哈希、制品名称和发现时间,避免清理动作破坏调查依据。
先理解 Claude Code 已经做了哪些保护
Claude Code 当前设置文档说明,当它首次在 Git 仓库中写入 .claude/settings.local.json 时,会把 **/.claude/settings.local.json 加入当前用户的全局 Git excludes。正常情况下,本地权限不会自动进入提交。
这层保护有清晰边界:
- 全局 excludes 属于这台机器,不会随 clone 交给其他开发者;
- 手工创建的文件,在 Claude Code 写入前需要自行加入 ignore;
- 文件已经进入 Git Index 后,新增 ignore 规则不会解除跟踪;
- Docker
COPY .、压缩包、目录同步和 IDE 发布可以复制未跟踪文件。
因此,事故结论不应写成 Claude Code 总会提交秘密。准确说法是:产品为正常创建路径配置了本机排除,但永久批准仍会生成秘密承载物,仓库与制品系统需要自己的验证门禁。
官方权限文档还说明,Bash 命令的不要再询问属于按仓库与命令保存的长期规则。安全评审必须看最终持久化字符串,而不能只看命令本次是否值得执行。
例如:
# 可以持久化变量引用
PGPASSWORD="$DB_PASSWORD" psql -h db.example.internal -U app -c 'select 1'
# 不应持久化真实值
PGPASSWORD='literal-password' psql -h db.example.internal -U app -c 'select 1'
更稳妥的做法是通过 Secret Manager、短期凭据助手或受控环境变量解析秘密。权限规则保存稳定接口,秘密值留在专门的凭据系统中。
为什么当前文件扫描仍然会漏
Apiiro 2026 年 11 月 5 日的研究称,它扫描了 103,617 个公开 GitHub 仓库中的 104,185 份 .claude/settings.local.json。报告判定 1,122 份文件包含真实秘密,约占 1.1%;当前文件合计 1,379 个不同秘密,另有 734 个只存在于历史版本。
这些是 Apiiro 的直接扫描结果,本文没有复现全量样本,也不能把 1.1% 外推为所有 Claude Code 用户的泄露率。报告的价值在于揭示漏检形态:它称 Gitleaks 和 TruffleHog 扫过全部 104,185 份文件,问题文件中仍有 215 份没有被任何一种工具标记。
普通密码嵌在命令中时,往往没有供应商 Token 的固定前缀。PGPASSWORD=、sshpass -p、mysql -p 或 HTTP Header 后的值,可能只是一个普通单词。
GitHub 的支持模式文档把检测分成 provider、generic 与 AI-detected password,并说明不同类别的 Push Protection、有效性检查和套餐可用性不同。团队需要用自己的命令样本验证工具,而不是看到扫描通过就宣布安全。
最小测试集至少包含:
- 有固定前缀的 API Key;
- 数据库 URL 和连接串;
sshpass -p后的普通密码;- Bearer Header 中的字面量;
- 相同命令的
$VAR安全版本; - Base64 或模板渲染后的派生制品。
处置顺序:先让秘密失效
GitHub 的泄露秘密处置指南要求把泄露凭据视为已经失陷。删除文件、增加修复提交或重建仓库,都不能证明旧凭据失效。
现场处置按下面顺序进行。
1. 冻结事实
记录凭据类型、所有者、权限、公开时间、涉及仓库、fork、镜像、包和依赖服务。高权限生产凭据进入最高优先级。
2. 轮换或撤销
能立即撤销时先撤销。涉及生产连续性时,先生成最小权限替代凭据,完成服务切换,再撤销旧值。最终验收信号来自凭据供应商,而不是 Git 提交。
3. 检查滥用
读取供应商与应用审计日志,核对来源 IP、调用时间、资源访问和权限变更。没有发现异常只能说明当前证据范围内未见异常,不能抹去已公开事实。
4. 缩小副本
解除文件跟踪,加入仓库级 .gitignore,清理当前工作树、历史对象、CI Log、制品、缓存和同步目录。仓库级规则可以随项目传播:
.claude/settings.local.json
GitHub 的历史清理文档明确指出:历史重写无法自动清理其他人的 clone,fork、缓存视图和 Pull Request 引用也需要分别处理。清理的作用是减少副本,轮换的作用是关闭访问。
5. 复测原路径
用新凭据重新走一次批准、提交和构建流程。验证权限文件只保存变量名,Git Index 没有本地设置,最终制品清单也找不到秘密。事故只有在原路径无法再次产生同类副本时才算关闭。
把权限审批改成三色决策
开发团队可以把永久批准压缩成一个三色规则,不要求每个人记住整套事故手册。
绿色:允许持久化
- 只含稳定命令与非敏感参数;
- 秘密通过变量或凭据助手解析;
- 规则粒度与读者任务一致;
- 保存后能在权限文件 diff 中复核。
黄色:仅单次批准
- 命令来自临时排障;
- 参数包含生产主机、用户标识或一次性签名值;
- 当前无法确认工具会保存哪段字符串;
- 执行必要,但没有形成稳定安全接口。
红色:停止执行
- 命令包含秘密字面量;
- 凭据权限与任务不匹配;
- 目标主机、数据范围或副作用未知;
- 需要通过关闭扫描或扩大权限才能继续。
这个决策比全面禁用永久批准更实用。Saved Permission 可以减少重复中断,安全前提是被保存的内容本身适合长期存在。
仓库和发布系统的最低门禁
权限文件安全最终要落到可执行证据:
- Pre-commit 检查
.claude/、Transcript、Memory 和 Handoff 文件。 - CI 同时运行格式模式与命令语义模式。
- 构建后列出最终制品文件,不用 Git 清洁状态替代制品检查。
- 发布前扫描容器层、源码包和部署清单。
- 凭据轮换后验证旧值返回失效结果。
- 每次工具升级后复测权限文件位置与 ignore 行为。
这与 Agent Sandbox 五层状态模型使用同一条判断:进程、本地文件、Git 历史、外部制品和供应商凭据具有不同生命周期。编程 Agent 仓库数据流审计关注信息如何离开开发环境;权限文件是其中一个容易被忽略的持久出口。
权限弹窗的安全性,不能用点了哪一个按钮来验收。完整证据链是:保存的规则不含秘密,仓库和制品没有副本,历史暴露已经处置,旧凭据确实失效。四项同时成立,权限配置才重新回到普通配置的风险等级。
参考资料
- Claude Code Docs:Configure permissions,核验于 2026 年 11 月 9 日。
- Claude Code Docs:Settings files and precedence,核验于 2026 年 11 月 9 日。
- Apiiro:Coding Agents Copy Your Secrets to a Hidden File,发布于 2026 年 11 月 5 日,更新于 11 月 8 日。
- GitHub Docs:Remediating a leaked secret,核验于 2026 年 11 月 9 日。
- GitHub Docs:Removing sensitive data from a repository,核验于 2026 年 11 月 9 日。
- GitHub Docs:Supported secret scanning patterns,核验于 2026 年 11 月 9 日。