# 安全与行为披露

本文件逐条写明 `dsh-devops` 会碰什么。它的用途是**让人对着源码核对**，
不是自我宣传。哪一行与代码不符就是 bug，请报告。

英文版见 [SAFETY.md](./SAFETY.md)。

## 安装期行为

- **没有任何安装生命周期脚本。** 包内未声明 `preinstall` / `install` /
  `postinstall`。`dsh plugin add` 或 `npm install` 不会在你的机器上额外执行
  本包的任何东西，唯一发生的事就是模块被加载。
- 分发的产物（`dist/index.js`、`dist/client/client.js`）是**预构建**的。
  从 Git 安装则需要你自己构建，见 [CONTRIBUTING.zh.md](./CONTRIBUTING.zh.md)。
- 运行时依赖只有 `schemastery` 与 `zod`，其余都是 devDependency。
  `@deepseek-ai/cordis` 与 `react` 是**可选** peerDependency，由宿主提供。

## 读取了哪些位置

| 路径 | 用途 | 模式 |
| --- | --- | --- |
| `<dataDir>`（默认 `~/.dsh-devops`） | SSH 配置、加密凭据、巡检历史、部署任务、已验证脚本 | 读 + 写 |
| `<dataDir>/ssh` | 插件私有的 OpenSSH 配置与工作文件 | 读 + 写 |
| 宿主存储域 `dsh_devops` | 经 `ctx.storageDomain` 的版本化记录 | 宿主托管 |
| 你添加的远程服务器 | 硬件、进程、日志文件、git 工作树 —— 走 SSH | 读（部署时写） |

`dataDir` 可通过 patch 层配置。插件**不会**读取你的 `~/.ssh`、shell 历史，
也不会碰 `dataDir` 与你显式添加的远程主机之外的任何文件。

## 存了什么、怎么存的

- SSH 密码、私钥口令、Git 凭据、sudo 口令均以 **AES-256-GCM** 认证加密封装。
  信封带版本号（`enc1:…`），密钥轮换后旧记录仍可解密。
- **密钥材料来自 `DSH_DEVOPS_KEY_FILE`。** 该变量未设置时，插件退化为进程内
  内存密钥，宿主每次启动都会重新生成 —— 此时**已保存的凭据在重启后无法解密**。
  **保存任何凭据之前请先设置这个变量。** 没有密钥托管、没有找回通道：
  密钥文件丢失即凭据永久丢失。
- 密钥文件以 `0600` 权限写入。
- 机密在进入 UI、持久化存储、远程命令行、部署脚本、日志、模型上下文之前
  统一脱敏。

## 网络出口

- **到你的服务器：** 走 OpenSSH 二进制，系统配置被逐项 `-o` 关闭
  （`UserKnownHostsFile` / `GlobalKnownHostsFile` / `IdentitiesOnly`）。
  命令行以参数数组传递，不经 shell 字符串拼接。
- **主机指纹固定：** 首次连接记录主机密钥；指纹变化会**暂停连接**而不是信任。
- **到你的模型提供方：** 硬件采样、进程列表与日志片段会送给宿主为 `modelRef`
  解析出的模型，使用宿主自己的 LLM 服务与凭据。**插件自身从不持有模型 API Key。**
  `modelRef: null` 时 AI 步骤会如实报告能力不可用，不会退化成别的方案。
- **没有遥测。** 不会向维护者、市场或任何第三方端点发送数据。插件的网络请求
  仅限上述两类。

## AI 边界

- **巡检只读，且由结构强制。** 注册给巡检的 agent 只在自己的作用域上拿到
  白名单只读工具，**不继承**通用 shell 与文件写工具。这个只读边界不依赖提示词
  措辞。
- 巡检永不重启服务、永不自行修复，只做报告。
- **部署会写**，但只发生在用户显式创建的任务内：`git pull --ff-only`、
  依赖更新、构建、服务重启、健康检查。失败的步骤最多由 AI 辅助修复重试 2 次，
  之后如实报告。
- 工作区有未提交改动、分支不符、远端分叉时一律停止并报告，**不 force-push、
  不 reset、不自动合并**，也不提供危险的全量回滚。
- 模型输出被当作**待核实的声明**而非事实：部署步骤必须与远端实际状态核对通过，
  任务才会推进。

## 宿主侧暴露面

- RPC 挂在 `/rpc/dsh-devops`，走**宿主认证通道**；所有请求载荷在 API 边界
  由 zod 全量校验。
- 副作用（定时器、监听、注册路由、打开的连接）全部经 `ctx.effect()` 或自带
  disposer 的 API 注册，宿主卸载时会一并回收。
- 路由注册包在 `try/catch` 里并降级为 no-op —— 重复的 `(kind, path)`
  掀不起宿主进程。

## 永不做的事

- 绝不读取或外传 DSH 会话内容、凭据、工作区文件。AI 上下文只由巡检与部署
  材料组装而成。
- 绝不在你的服务器上安装超出「该项目自身依赖更新步骤」所需的东西。
- 绝不下发未经校验的远程命令：所有命令都走白名单解析。
- 绝不自行提权。若配置了 sudo，也是显式的。

## 报告安全问题

**请不要开公开 issue。** 可以发邮件给维护者
[davidwu@users.noreply.github.com](https://github.com/bigbigtooth)，
或使用本仓库的私密漏洞报告（**Security → Report a vulnerability**）。

请附：受影响的插件版本、DSH 版本、复现步骤，以及脱敏后的相关日志片段。
通常几天内会得到确认。没有正式 SLA，也没有漏洞赏金。

## 不在保障范围内

dsh-devops 是运维工具，它**没有**针对恶意目标主机做过加固，也不应当被指向
这类主机。