# 安全与审计

[English](security-and-audit.en.md) · [返回 README](../README.md)

## Fail-closed 策略

- 自动批准只产生 `allowed-once`。
- `critical` 永不自动批准。
- `high` 只有在完整直接用户消息对精确目标和重要副作用建立 `high` 授权时才可自动批准。
- 被截断的用户消息不能建立授权；Assistant 文本、工具参数、工具结果、文件/Web 内容和插件上下文都属于不可信证据，而不是 Reviewer 指令。
- 缺失或歧义 callId、工具不匹配、沙箱 reason 与调用参数不一致、证据或动作超限、路由缺失、超时、Provider 故障、非法 JSON 或 Reviewer 生成工具调用都会阻止自动授权。
- 通用扩展审批只有在 Session 日志中能唯一还原精确 action 时才能自动或人工批准。

## 只读证明与审查目标

保守 Shell 分类器可证明的豁免包括 `pwd`、受限的 `ls/stat/cat/head/tail/wc/grep` 和只读 Git 子命令。所有路径必须位于 workspace；存在 Filesystem Service 时还会使用后端 canonical containment 防止符号链接逃逸。

管道、重定向、命令替换、多命令、解释器、网络命令、隐藏输入或副作用选项、工作区外路径不会被猜测为安全。网络目标只提取有界协议/主机/端口元数据，不执行额外 DNS 或网络请求。MCP 名称缺乏可信 provenance，因此按不透明远程能力审查。

## Reviewer 数据边界

Guardian 会收到经字节预算约束的待执行参数和上下文摘要。请只使用可信的数据处理 Provider。完整工具输出和 reasoning block 不会发送。

普通日志和 Guardian 卡片 payload 不包含：

- raw tool arguments；
- 完整 evidence/transcript；
- 未经处理的 Guardian rationale。

实时 UI payload 使用 owned scalar summary、枚举状态，以及一条最多 240 字符的 Guardian 判断原因。发布到 watcher 或从审计记录恢复前会压缩空白，并遮盖常见 token/password/Authorization/API key 值及 URL query values；模型提示也明确禁止复述命令、参数、凭据和其他敏感证据。payload 不写入 Session 历史；Host 重启恢复只读取已经存在的 final audit record，并重新投影相同的最小字段。

## JSONL audit-before-allow

默认路径：

```text
${DSH_HOME:-~/.dsh}/audit/auto-review.jsonl
```

每个 Review 只追加一条最终 `auto-review/final`：

- `summary` 默认只保存参数大小、SHA-256 和结构化摘要；
- `full` 保存完整 target，可能包含敏感命令、URL 或凭据，只应使用受信任私有路径；
- 目录/文件分别以 `0700`/`0600` 创建；
- 同一 Host 进程串行追加并 `fsync`，部分写入回滚；
- 首次写入校验已有 JSONL，修复缺少 LF 的完整尾记录，并隔离损坏尾部；
- 超过 `auditMaxBytes` 前轮转到 `.1`。

启用审计时，自动或人工授权只有在 append + fsync 成功后才返回。失败把本应允许的结果改为 `unavailable`。显式 `auditEnabled: false` 才允许无持久化运行。

Writer 只保证单 Host 进程安全；多个进程不得共享同一路径。

## 两类事件表面

- observer-only Cordis：`auto-review/started`、`auto-review/completed`。监听器抛错或异步拒绝不会改变审批结果。
- Guardian live UI：内存中的 `start`、`status`、`end` 更新及最近快照通过 Typert Remote watcher 传给当前 Web Session；Host 重启时可从已有 final audit line 恢复脱敏快照，但不会写入 Session 或追加额外 audit line。

两类 payload 都受最小字段白名单约束。旧 `auto-review/start|status|end` durable Session 路径保留为 `TODO(dsh-session-events)`，生产入口已禁用。