第19讲 · 凭据管理与 fail-closed 安全模型

《DeepSeek Harness 从上手到精通》系列 · 第六阶安全与沙箱篇

🎯 目标：掌握密钥安全与默认拒绝哲学难度 ★★☆ ⏱ 约 25 分钟前置：第 18 讲已配沙箱

系列基于 deepseek-ai/deepseek-harness（0.1.0-rc.5，MIT）。本讲是安全篇的收尾：沙箱管「能碰哪些文件」，凭据管理管「能用哪些密钥」，而 fail-closed 是贯穿两者的总哲学——无法判定时，一律拒绝。preview 阶段接口可能微调，以官方文档为准。

一、CredentialRef：配置不存明文

把 API Key 直接写进配置文件，是很多安全事故的起点。dsh 用 CredentialRef（凭据引用） 解决这个问题：配置里只存「引用」而不存明文。

配置不存明文：YAML 里写的是 CredentialRef，真正的密钥在安全的凭据库里；
逐操作解析：每次真正要用密钥时才去解析引用、取出凭据，用完即弃；
UI 只见 CredentialInfo：前端/界面只看到「这是个凭据、属于哪个服务」的元信息，永远看不到明文。

凭据管理与fail-closed安全模型 — **图 1** 配置只存引用、逐操作解析、UI 只见元信息——明文密钥从不落地、不暴露。

二、fail-closed：无法判定时默认拒绝

fail-closed（失败即关闭） 是 dsh 安全设计的底层哲学，与 fail-open（失败即放行）相反。它的含义是：当系统无法判定某次操作是否该被允许时——凭据解析失败、策略缺失、配置含糊——一律按「拒绝」处理，而不是放行了事。

实际表现举例：

凭据引用解析不出来 → 该操作拒绝，而不是用空密钥裸奔；
某路径不在白名单也不在黑名单 → 拒绝，而不是默认允许；
审批策略缺失 → 视为需审批/拒绝，而不是无脑放行。

fail-closed 可能「误伤」正常操作（本该放行却拦了）。这是安全与便利的取舍——dsh 选择宁可拦错、不可放错。若频繁误拦，去补全凭据/策略，而不是改回 fail-open。

三、审计：从会话日志回溯「谁在何时批准了什么」

安全不止「挡住」，还要「说得清」。借助第 6 讲的会话事件日志，你可以回溯：

谁：哪个会话 / 哪个 agent 触发了操作；
何时：事件时间戳，对应到具体轮次；
批准了什么：审批请求（ApprovalRequest）的同意/拒绝记录，以及用到的凭据引用。

把日志导出（JSONL / SQLite）就能做合规审计与事故复盘——这正是 fail-closed + 全量记录带来的「可问责」。

四、上线前安全自查清单（8 条）

把下面 8 条过一遍，再让 agent 碰生产环境：

#	自查项
1	配置中无任何明文密钥，全部走 CredentialRef
2	凭据库本身有访问控制，不随仓库提交
3	生产环境运行在 Linux 且 Landlock 已启用
4	沙箱只授权最小可读/可写目录
5	审批策略为「默认需审批 / fail-closed」，未误设 fail-open
6	敏感操作（写/执行）有白名单，越权默认拒绝
7	会话事件日志开启并可导出，用于审计
8	凭据有轮换计划，泄露时可快速吊销

五、动手练习：生产环境凭据与安全自查

为你的场景准备一份生产环境凭据配置与安全自查表：

把配置里的明文 Key 全部替换为 CredentialRef 引用；
确认运行平台启用沙箱（Linux + Landlock）；
逐条对照上方 8 条清单打勾，把结果存档备用。

# 配置只存引用（示意，以官方字段为准）
credentials:
  deepseek:
    ref: "vault://deepseek/api-key"   # 明文不在此处
# 验证：UI 中该凭据只显示元信息，无明文

六、常见坑

把明文 Key 提交进仓库：永远用 CredentialRef，密钥库单独管控；
误以为 fail-closed 是 bug：解析/策略不确定时被拦是正常的，去补全配置；
为省事设 fail-open：一旦放开默认放行，整条安全链形同虚设；
关了事件日志：没法审计「谁批准了什么」，事故时无从复盘；
凭据不轮换：泄露后长期有效，给攻击者留后门，设轮换计划。

七、官方文档对应章节

docs/ 中 credentials / security / audit 相关章节
第 18 讲 Landlock（沙箱与凭据共同构成纵深防御）
第 6 讲会话事件（审计所需的全量日志机制）

本讲内容基于 DeepSeek Harness 官方文档与项目源码整理，仅供学习参考，具体命令与配置请以官方最新版本为准。系列文章配合源码仓库食用效果更佳：https://github.com/deepseek-ai/deepseek-harness

咨询 DeepSeek Harness 相关问题，请加微信：A0qingfengyuan_01

个人观点，仅供参考，如有不对之处，请多包涵，欢迎指出。本文由 AI 协助完成！

DeepSeek Harness 教程 · 第19讲 凭据管理与 fail-closed 安全模型