# 内置的安全能力总览

| 安全能力 | v1.x | v2.x | 说明 |
| --- | --- | --- | --- |
| 工具守卫 (Tool Guard) | ✅ | ✅ | 运行时工具调用检测 |
| 文件防护 (File Guard) | ✅ | ✅ | 敏感文件/目录访问拒绝列表 |
| 技能扫描器 (Skill Scanner) | ✅ | ✅ | 技能启用前安全预检 |
| Web 登录认证 | ✅ | ✅ | 控制台可选身份验证 |
| 沙箱隔离 (Sandbox) | ❌ | ✅ | **新增**：OS 内核级 Shell 执行隔离 |
| 访问策略 (Access Policy) | ❌ | ✅ | **新增**：声明式 allow/deny/ask 策略引擎 |

## 已经做的安全加固

- 操作系统层面，已启用 SE Linux 的 Enforcing 模式。其 MAC（Mandatory Access Control）防御机制，可以遏制传统 DAC 机制下被恶意攻击，提权到 root 劫持系统控制权。在 MAC 机制下，权限受限于访问策略，而非文件所有者或用户。即便是 root 权限启动的进程，也必须遵守规则，无法绕过。
- QwenPaw Linux 的实例运行在 Docker 容器中而非直接运行在宿主机，通过目录挂载的方式，将运行时生成的文件、数据持久化至宿主机上。宿主机磁盘目录不删除的前提下，容器实例宕机、重启数据不会丢失。

## 还能做的安全防护

- 定期备份数据目录：
  - 方案一、每天定时全量备份数据目录，生成压缩包上传至OSS。
  - 方案二、将数据目录挂载到NAS [点此查看方案明细](https://git.jkwlstv.cn/doc/container/src/branch/main/nas-to-nfs-linux-docker.md)
- 除此之外，还能把 Docker 也启用 SE Linux 更精细的控制文件访问权限。
- [点击跳转查看 agentscope、agentscope-java 对于容器沙箱的支持](./agentscope-sandbox.md)

## 工具守卫 (Tool Guard)

| Item | 详细说明 |
| --- | --- |
| 核心作用 | Agent 调用工具**之前**扫描参数，检测危险命令、路径遍历、数据外泄等，阻止恶意操作 |
| 主要检测对象 | 重点针对 `execute_shell_command`；结合 YAML 正则规则 + `ShellEvasionGuardian`（引号感知的 Shell 规避分析） |
| 检测示例 | `rm -rf /`、SQL 注入片段、命令替换 `$()`/`` ` ``、路径遍历 `../`、`sudo`/`su`、反向 Shell、Fork 炸弹、标志位混淆、Unicode 空白绕过等 |
| 严重级别 | CRITICAL / HIGH / MEDIUM / LOW / INFO；CRITICAL/HIGH 在交互环境进入待审批，无会话时记日志（可用 `denied_tools` 强制禁止） |
| 守护范围 (`guarded_tools`) | `null`=守护全部内置工具；`[]`=不守护；指定列表=仅守护列出工具 |
| 禁止工具 (`denied_tools`) | 无条件阻止，不提供审批 |
| 自定义规则 | 支持正则、威胁类别、严重级别、排除模式；类别含 command_injection、data_exfiltration、path_traversal 等 10 类 |
| Shell 规避检查 | 7 项独立开关（默认全关）：命令替换、混淆标志、反斜杠空白/操作符、换行、注释引号不同步、引号内换行 |
| 执行级别 (`approval_level`) | STRICT（全审批）/ SMART（高风险审批）/ AUTO（仅规则命中审批，默认）/ OFF（关闭） |
| 控制台 | 设置 → 安全 → 工具防护：启停、守护范围、禁止工具、内置/自定义规则管理；改完立即生效 |
| 环境变量 | `QWENPAW_TOOL_GUARD_ENABLED`（优先于配置文件） |

### 内置 YAML 规则

| 类别 | 规则 ID | 严重级别 | 检测目标 |
| --- | --- | --- | --- |
| 命令注入与文件操作 | `TOOL_CMD_DANGEROUS_RM` | HIGH | `rm` 危险删除 |
| 命令注入与文件操作 | `TOOL_CMD_DANGEROUS_MV` | HIGH | `mv` 移动/覆盖 |
| 命令注入与文件操作 | `TOOL_CMD_UNSAFE_PERMISSIONS` | HIGH | `chmod -R 777`、`chattr` |
| 低级别磁盘操作 | `TOOL_CMD_FS_DESTRUCTION` | CRITICAL | `mkfs`、`dd of=/dev/` 等 |
| 资源滥用 | `TOOL_CMD_DOS_FORK_BOMB` | CRITICAL | Fork 炸弹、`kill -9 -1` |
| 资源滥用 | `TOOL_CMD_SYSTEM_REBOOT` | CRITICAL | `reboot`/`shutdown`/`halt`/`init 0/6` |
| 资源滥用 | `TOOL_CMD_SERVICE_RESTART` | HIGH | `systemctl`/`service` 重启停止 |
| 资源滥用 | `TOOL_CMD_PROCESS_KILL` | HIGH | `pkill`/`killall`/`kill` |
| 代码执行 | `TOOL_CMD_PIPE_TO_SHELL` | CRITICAL | `curl/wget \| bash` |
| 代码执行 | `TOOL_CMD_OBFUSCATED_EXEC` | HIGH | `base64 -d \| bash` |
| 代码执行 | `TOOL_CMD_IFS_INJECTION` | HIGH | `$IFS` 绕过 |
| 代码执行 | `TOOL_CMD_CONTROL_CHARS` | CRITICAL | 不可见控制字符 |
| 代码执行 | `TOOL_CMD_UNICODE_WHITESPACE` | HIGH | Unicode 空白绕过 |
| 代码执行 | `TOOL_CMD_PROC_ENVIRON` | HIGH | `/proc/*/environ` 读环境 |
| 代码执行 | `TOOL_CMD_JQ_SYSTEM` | HIGH | `jq` 中 `system(` |
| 代码执行 | `TOOL_CMD_JQ_FILE_FLAGS` | HIGH | `jq` 任意读文件/加载代码 |
| 代码执行 | `TOOL_CMD_ZSH_DANGEROUS` | HIGH | zsh 危险内建 |
| 权限提升 | `TOOL_CMD_PRIVILEGE_ESCALATION` | CRITICAL | `sudo`/`su`/`doas`/`pkexec` |
| 权限提升 | `TOOL_CMD_SYSTEM_TAMPERING` | HIGH | crontab、authorized_keys、sudoers |
| 网络滥用 | `TOOL_CMD_REVERSE_SHELL` | CRITICAL | `/dev/tcp`、`nc -e`、`socat EXEC:` |

### Shell 规避

严重级别均为 **HIGH**

| 规则 ID | 说明 |
| --- | --- |
| `SHELL_EVASION_COMMAND_SUBSTITUTION` | 单引号外的反引号/命令/进程替换 |
| `SHELL_EVASION_OBFUSCATED_FLAGS` | ANSI-C/区域化引号、空引号标志技巧 |
| `SHELL_EVASION_BACKSLASH_WHITESPACE` | 引号外反斜杠转义空白 |
| `SHELL_EVASION_BACKSLASH_OPERATOR` | 引号外反斜杠转义 `;\|&<>` |
| `SHELL_EVASION_NEWLINE` | 裸换行/`\r` 拆分命令 |
| `SHELL_EVASION_COMMENT_QUOTE_DESYNC` | `#` 注释与引号状态不同步 |
| `SHELL_EVASION_QUOTED_NEWLINE` | 引号内换行后接伪注释行 |

## 文件防护 (File Guard)

| 能力项 | 详细说明 |
| --- | --- |
| 核心作用 | 阻止 Agent 工具访问敏感文件和目录；每次工具调用自动扫描路径参数 |
| 独立性 | 即使 `tool_guard.enabled=false`，只要 `file_guard.enabled=true` 仍会检查 |
| 路径提取策略 | 已知文件工具检查 `file_path`；Shell 从命令串提取（含重定向）；其他工具扫描类路径字符串 |
| 路径处理 | 相对路径解析、`~` 展开、规范化为绝对路径；以 `/` 结尾的目录递归保护 |
| 默认保护 | `{WORKING_DIR}.secret/`（默认 `~/.qwenpaw.secret/`，存 API 密钥与凭据） |
| 阻止级别 | 匹配时以 HIGH 级别发现阻止 |
| 配置字段 | `enabled`（默认 true）、`sensitive_files`（绝对/相对/`~/`/目录路径） |
| 控制台 | 设置 → 安全 → 文件防护：启停、增删保护路径、保存/重置；立即生效 |

## 技能扫描器 (Skill Scanner)

| 能力项 | 详细说明 |
| --- | --- |
| 核心作用 | 技能启用/安装前扫描恶意代码、硬编码密钥、社会工程等威胁 |
| 触发时机 | 创建新技能、启用已禁用技能、从 Skill Hub 导入 |
| 扫描机制 | YAML 正则签名 + PatternAnalyzer；支持自定义 ScanPolicy |
| 智能缓存 | 基于文件 mtime，未变更不重复扫描 |
| 超时保护 | 默认 30 秒（可配 5–300 秒） |
| 文件安全 | 跳过符号链接、校验路径边界、默认跳过二进制/归档 |
| 扫描模式 | **Block** 拦截不可用；**Warn** 警告但可用（默认）；**Off** 关闭 |
| 配置优先级 | 环境变量 `QWENPAW_SKILL_SCAN_MODE` > 控制台 > `config.json` |
| 扫描告警 | 查看详情（文件/行号/模式）、加白名单、删单条/清全部 |
| 白名单 | SHA-256 内容哈希版本锁定；文件变更后白名单失效需重扫 |
| 内置威胁类别 | command_injection、data_exfiltration、hardcoded_secrets、prompt_injection、social_engineering、supply_chain_attack、obfuscation、resource_abuse、unauthorized_tool_use |
| 自定义规则 | YAML 签名（id/category/severity/patterns/exclude_patterns/file_types 等） |
| 控制台 | 设置 → 安全 → 技能扫描器；模式与超时改完立即生效 |

### Web 登录认证

| 能力项 | 详细说明 |
| --- | --- |
| 核心作用 | 可选保护控制台，防未授权访问；**默认关闭**，需 `QWENPAW_AUTH_ENABLED=true` |
| 账户模式 | 单用户管理员；首次网页注册，或环境变量自动注册（适合 Docker/K8s） |
| 令牌 | HMAC-SHA256 签名，有效期 7 天，存 localStorage |
| 密码存储 | 加盐 SHA-256，不存明文；`auth.json` 权限 `0o600` |
| 本地免认证 | `127.0.0.1` / `::1` 跳过认证；CLI 无需令牌 |
| 豁免主机 | `security.allow_no_auth_hosts`（默认 localhost） |
| 环境变量 | `QWENPAW_AUTH_ENABLED`（必填启用）；`QWENPAW_AUTH_USERNAME` / `QWENPAW_AUTH_PASSWORD`（可选自动注册） |
| 运维能力 | `qwenpaw auth reset-password`（轮换签名密钥使所有会话失效）；侧边栏退出登录 |
| 路由保护 | 仅 `/api/*` 需认证；登录/注册/status/version 与静态资源公开；WebSocket 令牌经查询参数 |

## 沙箱隔离 (Sandbox)

**沙箱隔离来自操作系统支持**

| 能力项 | 详细说明 |
| --- | --- |
| 核心作用 | 为 Shell 命令提供 **OS 内核级**执行隔离；命令只能访问已声明的文件系统视图 |
| 在链路中的位置 | 工具守卫（静态检测）→ 治理引擎（ALLOW/DENY/ASK/SANDBOX_FALLBACK）→ **沙箱隔离（运行时强制）** → 违规检测 |
| 与既有层关系 | 即使通过工具守卫与文件防护，沙箱仍从内核层限制白名单外访问 |
| 隔离模型 | 默认拒绝 + 白名单：`mounts` 控制可写；`deny_paths` 额外阻止；最小化 `/dev`；Bubblewrap 支持 PID 隔离 |
| 配置来源 | 由治理策略引擎自动编译，用户通常无需手写；含 mode、workspace_dir、mounts、deny_paths、allow_read_all、timeout 等 |
| 违规处理 | 解析 stderr 模式填充 `sandbox_violation`；记治理日志；可按策略提示审批扩展权限 |

### 不同平台的沙箱隔离机制

| 平台 | 后端 | 机制 | 选用条件 |
| --- | --- | --- | --- |
| macOS | Seatbelt | `sandbox-exec` + S-expression 策略 | PATH 有 `sandbox-exec` |
| Linux | Bubblewrap（首选） | Mount/User/PID namespace | `bwrap` + user namespace |
| Linux | Landlock（回退） | Landlock LSM（内核 5.13+） | 无 bwrap 时回退 |
| Windows | AppContainer | AppContainer + `icacls` ACL | `allow_read_all=False`，Win10+ |
| Windows | Restricted_token | 受限令牌 + WFP 防火墙 | `allow_read_all=True`（默认），需管理员 |
| 所有 | None | 无隔离直接执行 | 无可用后端时 |

### 不同隔离机制的能力对比

| 能力 | Seatbelt | Bubblewrap | Landlock | AppContainer | Restricted_token |
| --- | --- | --- | --- | --- | --- |
| 文件系统（读） | ✅ | ✅ | ✅ | ✅ | ✅ |
| 文件系统（写） | ✅ | ✅ | ✅ | ✅ | ✅（受限令牌） |
| deny_paths 不可见 | ❌（拒绝访问） | ✅（未挂载） | ❌（拒绝访问） | ❌ | ❌ |
| PID 命名空间隔离 | ❌ | ✅ | ❌ | ❌ | ❌ |
| 最小化 /dev | ✅ | ✅ | ❌ | ❌ | ❌ |
| 网络控制 | ✅（允许/拒绝） | 计划中 | ❌ | ✅ | ✅（WFP） |

最小化 /dev 指的是沙箱里不挂载完整的 /dev 只挂载：

```text
/dev/null
/dev/zero
/dev/urandom
/dev/tty
```

这样命令仍能做重定向、读随机数、写终端等常规操作，但碰不到磁盘分区、真实网卡设备等更危险的节点。

### 沙箱目前的限制

| 限制项 | 说明 |
| --- | --- |
| 网络隔离 | 当前未真正强制；`network_allow` 暂不影响；bubblewrap 网络命名空间已规划 |
| 资源限制 | `max_processes` / `max_memory_mb` 字段存在但后端未强制 |
| Windows 要求 | 需 Windows 10 build 10240+；AppContainer/Restricted_token 常需管理员权限 |
| AppContainer 删文件 | `allow_read_all=False` 时沙箱内可能无法删除工作区文件 |

## 访问策略 (Access Policy)

| 能力项 | 详细说明 |
| --- | --- |
| 核心作用 | 声明式策略引擎：对每次能力调用裁定 **allow / deny / ask** |
| 适用范围 | 每个服务客户端独立策略；当前已在 **MCP** 落地，设计可扩展到其他协议 |
| 三种效果 | `allow` 立即执行；`deny` 阻止并返回错误；`ask` 挂起等待控制台人工审批 |
| 两级粒度 | **客户端级**默认效果；**工具级**可为特定工具覆盖（如禁 `dangerous_tool`） |
| 来源感知 | 按 `principal` 匹配来源渠道（console、dingtalk 等）与身份（user 等） |
| Subject 模式 | `user:xxx`、`session:xxx`、`channel:xxx`、`*` |
| 默认效果 | `default_effect`：无规则匹配时生效，默认 `deny` |
| 优先级裁决 | 目标名精确 > 目标类型 > Principal 具体度 > Subject 精确度 > 严格程度（deny > ask > allow） |
| 审批流程 | ask 时挂起并出审批卡片（工具/参数/身份/来源/客户端）；超时未响应则拒绝 |
| 配置位置 | MCP 客户端 YAML 的 `policy` 段；控制台 **智能体 → MCP → 工具&权限** |
| 控制台能力 | 设默认效果、客户端级规则、工具级默认与覆盖规则；保存立即生效 |
| 注意 | YAML 中高级 subject（如 `user:admin`）会保留但控制台不可编辑，显示为「未管理规则」 |

### 策略裁决示例

| 请求场景 | 结果 | 原因 |
| --- | --- | --- |
| `user:admin` 调用任意工具 | ALLOW | 精确 subject 匹配 |
| 任何人调用 `dangerous_tool` | DENY | 精确目标名称优先 |
| 控制台用户调用 `safe_tool` | ALLOW | 目标 + principal 双重匹配 |
| 钉钉用户调用 `other_tool`（无规则） | ASK | 回落到 `default_effect` |