# 安全说明

这个插件会**持有 SSH 凭据**并**在远程主机上执行命令**，所以安全边界值得单独讲清楚，
而不是散落在 README 的取舍列表里。

## 凭据存在哪里

设备名单与凭据存放在**用户私有的** `$DSH_HOME/dsh-device-monitor.json`：

- 文件权限 **0600**（仅属主可读写）。
- 密码 / 私钥口令以**明文**保存在该文件中——它不是一个密钥库，保护它的是文件系统权限，
  这一点必须知道。
- **不会**写入日志，**不会**下发给浏览器（`publicSample()` 与名单投影都会剥掉 `auth`）。
- **不在本插件仓库里**，也不在打出来的 tarball 里。所以换一台机器安装时，
  要重新登记设备——**凭据不该跟着代码走**。

如果这台机器是多用户共享的，请改用**密钥认证**，并给私钥本身设口令。

## 命令执行的三个门控

| 路径 | 默认 | 约束 |
| --- | --- | --- |
| 指标采集 | 开 | 命令体是内置的**只读**命令；勾选项决定下发哪些 |
| 自定义命令 | **关** | 逐指标替换命令体。**只替换，不打开门控**——未勾选的指标仍一条都不发 |
| 终端调试 | **关** | 不受 Agent 工具白名单约束，输入**原样**发到设备。开前请自行确认要执行的命令 |

`device_exec`（Agent 工具）**没有**白名单——它是给模型用的「在某台设备上执行」入口，
调用前请确认要执行的命令。它每次都会写一条审计记录。

## 审计日志记录什么

审计日志的硬规则是**只记字段名，绝不记值**（`src/logs.js` 顶部有这条注释）：

- 记录：设备增删改、设置变更、采集、终端开/关/拒绝、远程执行。
- **`device_exec` 只记 `commandLength`**（命令长度），**不记命令文本**——
  审计日志不该成为用户命令的永久明文副本。`mysql -p'…'` 与
  `curl -H 'Authorization: …'` 在这里都是普通命令。
- 终端**不记击键**，只记会话开关与字节数。

> **取舍**：终端出事时无法从审计回溯「当时敲了什么」。这是刻意的——
> 记下击键就等于把凭据摊在磁盘上，代价比收益大。

## 原始采集日志（未脱敏）

`$DSH_HOME/dsh-device-monitor-logs/log/devices/` 下是**逐设备采集原文，按设计不做脱敏**。
它可能包含主机名、内核版本、挂载点、进程名。可在面板「设置」里关闭。
**若要分享日志用于排障，请先看一眼内容。**

## 终端网关

- 默认关闭，且必须由用户在设置里显式打开（`terminal.enabled === true`）。
- 升级请求要**同时**通过来源地址与 `Host` 头的回环校验；两者都证明是本机之后，
  才额外接受 `dsh-app://app` 这个桌面外壳来源（`dsh-app://shell` 被**刻意排除**）。
- 上限：**3 会话/设备、10 会话/进程**，空闲超时兜底（下限 30 秒）。
- 与只读推送通道**分开**的 WS 路径。

## 不做的事

- **不做 SSH host key 校验**（无 `hostVerifier` / `known_hosts`）。本插件信任它所连接的主机，
  中间人防护依赖你所在网络的信任模型。需要严格校验时请在 SSH 配置层解决。
- **不做命令内容检查**（终端与 `device_exec` 都是）。参考系统的哲学是「服务端不审查命令」，
  代价用「默认关闭 + 回环围栏 + 上限」来抵。

## 报告问题

发现安全问题请开 issue，并在其中**不要**附上真实的凭据、内网地址或未脱敏日志。