AI Agent / 系统课时
保护密钥与敏感数据
保护密钥与敏感数据
本课解决一个直接的安全问题:让 Codex 能理解故障和代码上下文,却拿不到真实凭据。完成后,你会把密钥留在受控存储和运行环境中,只向提示词、日志、提交记录与外部工具提供变量名、脱敏片段或可撤销的测试凭据。
学习目标
- 区分 Codex 需要的上下文与绝不能进入上下文的秘密值
- 建立从本地环境、仓库、日志到第三方工具的敏感数据边界
- 在提交前用不回显秘密内容的检查阻断常见泄露
先把秘密留在运行边界内
API Key、数据库口令、私钥、会话令牌都不应该成为“调试素材”。代码只读取变量名或密钥管理系统注入的值,Codex 通常只需要知道变量是否存在、错误类型、调用路径和脱敏后的响应。
例如,真实值保存在环境或密钥管理系统中,仓库只保留 .env.example 这类模板;模板写 OPENAI_API_KEY=,不要复制任何可用值。向 Codex 描述问题时也应写“OPENAI_API_KEY 已设置,但请求返回 401”,而不是粘贴密钥本身。

提交前检查暂存变更
下面的主示例只检查暂存区新增行,不回显匹配内容。它会拦截常见敏感变量后直接出现长值的情况,以及 PEM 私钥头;在 Git 仓库根目录执行即可。
python - <<'PY'
import re
import subprocess
import sys
assignment = re.compile(
r'^\+.*(?:API_KEY|TOKEN|PASSWORD|PRIVATE_KEY)\s*[:=]\s*["\']?([A-Za-z0-9_./+=-]{16,})',
re.IGNORECASE,
)
private_key = re.compile(r'^\+\s*-----BEGIN [A-Z ]*PRIVATE KEY-----')
# 只读取 staged diff,避免扫描工作树中的无关文件。
diff = subprocess.run(
["git", "diff", "--cached", "-U0"],
check=True,
capture_output=True,
text=True,
).stdout
# 只输出是否命中,不打印可能包含秘密的原始行。
blocked = any(
assignment.search(line) or private_key.search(line)
for line in diff.splitlines()
)
print("BLOCK: secret-like material in staged additions" if blocked else "OK: staged additions look clean")
sys.exit(1 if blocked else 0)
PY预期输出
OK: staged additions look clean这是启发式兜底,可能漏报,也可能因测试夹具产生误报;生产仓库仍应使用团队批准的 secret scanner,并为合法测试样本设置明确例外。.gitignore 只能阻止未跟踪文件被新增,不能清除已经提交过的秘密。
日志也必须按最小暴露原则处理
调试日志最容易把请求头、连接串和完整异常对象带进 Codex。优先保留状态码、错误类别、请求 ID 与必要的结构字段;Authorization 头、Cookie、密码和令牌值应在产生日志时就被删除或替换,而不是等到复制提示词前再手工打码。
第三方工具只拿它完成任务所需的数据
MCP 服务、CI、错误追踪平台和其他集成都可能扩大数据传播范围。接入前确认它需要读取哪些目录、环境变量和网络目标;能用只读权限就不要给写权限,能用仓库级临时令牌就不要给个人长期令牌。
安全的判断标准很简单:如果某个值一旦被复制、记录或转发就需要立即轮换,它就不应该进入 Codex 提示词或普通日志。把秘密留在受控执行边界内,把可共享信息压缩到完成任务所需的最小集合,才能让自动化能力与凭据安全同时成立。