AI Agent / 系统课时
保护密钥与敏感文件
保护密钥与敏感文件
Claude Code 会读取文件、执行命令并把工具结果带入会话上下文。若密钥同时出现在项目文件、终端输出或日志中,单靠“不要泄露”无法形成可靠边界。本课将把敏感信息从版本库、模型上下文和自动化输出中隔离。
学习目标
- 识别密钥进入提示词、日志和版本库的主要路径
- 配置 Git 忽略与 Claude Code 读取拒绝规则
- 能验证敏感文件既未提交,也不能被工具读取
先建立四层防线
第一层是不把真实密钥写入仓库;第二层是限制 Claude Code 读取敏感路径;第三层是避免命令把环境变量、请求头和完整配置打印到终端;第四层是使用外部密钥管理系统,在运行时按最小权限注入。拒绝规则可以阻止内置读取工具访问指定路径,但不能替代操作系统权限或容器隔离。:contentReference[oaicite:9]{index=9}

让版本库只保存模板
在项目根目录维护忽略规则,并提交不含真实值的 .env.example。
.env
.env.*
!.env.example
secrets/
config/credentials.json
*.pem
*.key.env.example 只保留变量名和安全占位值,例如 DATABASE_URL=<SET_AT_RUNTIME>。不要把删除过密钥的文件直接视为安全,因为 Git 历史仍可能保存旧内容;一旦真实凭据进入提交,应立即撤销并轮换。
阻止 Claude Code 读取敏感路径
在 .claude/settings.json 中加入拒绝规则:
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Read(./config/credentials.json)",
"Read(~/.ssh/**)",
"Read(~/.aws/**)"
],
"ask": [
"Bash(env *)",
"Bash(printenv *)",
"Bash(* --debug *)"
]
}
}路径规则应覆盖项目内文件和用户目录中的凭据。符号链接也需要关注:Claude Code 会检查链接路径及其解析目标,命中拒绝路径时应阻止访问。:contentReference[oaicite:10]{index=10}
验证 Git 与权限配置
先确认敏感文件被 Git 忽略:
git status --short --ignored .env预期输出
!! .env!! 表示文件被忽略。若输出为空,文件可能不存在;若出现 ?? .env,说明它未被忽略,应立即修正 .gitignore。随后在 Claude Code 中请求读取 .env,预期结果应是权限拒绝,而不是显示内容。
避免终端和日志间接泄漏
不要运行会打印全部环境变量的命令,也不要在调试日志中输出完整请求头、连接串或认证响应。应用日志应只显示密钥标识、末尾少量字符或不可逆摘要,并确保错误堆栈不会包含请求正文。对外部 MCP、Hooks 和脚本,同样按“不接收不需要的秘密”设计输入。
环境变量只比硬编码更方便,并不天然安全。更稳妥的方式是使用短期令牌、独立测试账号和只允许必要操作的凭据;任务结束后撤销临时访问。
发生泄漏后的处理顺序
先撤销或轮换凭据,再从当前工作区和日志中删除,之后清理版本库历史并通知相关人员。不要先花时间“彻底删除痕迹”再轮换,因为攻击者只需要一次可用凭据。最后补充扫描、拒绝规则和审查流程,防止相同路径再次出现。