# 安全

## 概述

Neotask 以安全优先的架构设计。Gateway 默认绑定到 localhost，所有敏感数据在静态时加密，代理执行可以在隔离的容器中沙箱化。

## 网络安全

### 默认回环

Gateway 仅在 `127.0.0.1`（localhost）上监听，除非您明确更改绑定模式。默认情况下没有外部网络暴露。

### 认证

所有 WebSocket 连接需要认证：

- **Token 认证** -- Bearer token（UUID 或自定义字符串）
- **密码认证** -- Bcrypt 哈希的密码
- **受信代理** -- 来自反向代理的预认证头
- **本地信任** -- 回环连接被隐式信任

### 远程访问安全

对于远程访问，推荐的方式是 **Tailscale VPN** 或 **SSH 隧道** -- 永远不要将 Gateway 直接暴露到互联网。

## 设备配对

### 配对工作原理

每个连接到 Gateway 的客户端必须经过配对：

1. 设备呈现其身份（指纹 + 公钥）
2. Gateway 发出配对挑战（随机数）
3. 设备用其私钥签署随机数
4. 您通过 UI 批准设备
5. Gateway 为未来连接颁发设备 token

### 信任模型

- **本地设备**（回环）为方便起见自动批准
- **非本地设备**需要明确批准
- 设备 token 本地存储，重新连接时重用
- 设备可以随时被撤销

## 加密

### 静态数据

- **AES-256-GCM** -- 所有 token、密钥和 API key 在静态时加密
- **机器派生密钥** -- 加密密钥通过 scrypt 从设备身份派生
- **无明文存储** -- Token 永远不以明文存储

### 传输中的数据

- **TLS** -- HTTPS 用于 API 通信
- **WSS** -- WebSocket Secure 用于 Gateway 连接（使用 Tailscale Serve 或反向代理时）
- **HMAC 签名** -- 带随机数和时间戳的请求完整性

## 沙箱化

### 基于 Docker 的隔离

代理命令执行可以在 Docker 容器中沙箱化：

- **按代理配置** -- 每个代理可以拥有自己的沙箱配置
- **资源限制** -- 可配置的 CPU、内存和超时限制
- **网络隔离** -- 容器可以进行网络隔离
- **文件系统隔离** -- 代理仅访问其工作空间
- **自定义镜像** -- 使用预安装了特定工具的预构建镜像

### 沙箱范围

| 范围 | 描述 |
|-------|-------------|
| **按会话** | 每个会话一个新容器 |
| **按代理** | 每个代理一个持久容器 |
| **共享** | 跨代理的共享容器 |

### 工作空间访问

沙箱化的代理可以访问其工作空间目录（挂载到容器中），但无法访问工作空间外的主机文件系统。

## 执行审批

控制代理可以在节点和 Gateway 主机上执行的命令：

### 模式

| 模式 | 描述 |
|------|-------------|
| **允许列表** | 仅预先批准的命令可执行 |
| **询问** | 未知命令提示用户批准 |
| **完全** | 无限制（谨慎使用） |

### 按节点配置

每个节点（macOS、无头主机）有自己的执行审批配置，本地存储。您可以允许特定二进制文件（例如 `/usr/bin/docker`、`/usr/local/bin/terraform`），同时阻止其他所有内容。

## 提升模式

某些操作需要直接在 Gateway 主机上运行（不在沙箱中）。提升模式：

- 在代理配置中通过明确权限控制
- 仅在 Gateway 主机上可用
- 默认禁用
- 可通过日志审计

## 安全审计

内置安全审计检查：

- 配置文件权限（应为 600）
- 会话文件权限
- Node.js 版本（安全补丁）
- 明文密钥检测
- 插件允许列表验证
- 开放网络接口审计
- 认证配置完整性

审计在获得许可后可以自动修复许多问题。

## 最佳实践

1. **保持 Gateway 在回环上** -- 使用 Tailscale 或 SSH 进行远程访问
2. **启用沙箱化** -- 在 Docker 容器中运行代理命令
3. **使用执行允许列表** -- 限制代理可以在节点上运行的命令
4. **设置认证 token** -- 始终配置 token 认证，即使是回环
5. **审查代理权限** -- 尽可能使用最小工具配置
6. **保持 Neotask 更新** -- 更新包含安全补丁
7. **定期审计** -- 运行安全审计以捕获错误配置
8. **限制插件加载** -- 仅安装受信任的插件