> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/architecture/security.md).

# 安全（src/openhuman/security/）

`src/openhuman/security/` 是 **自治核心的信任边界**。它负责自治/风险策略，用于决定某个工具调用是否被允许；当宿主支持时，还负责限制这些调用的可插拔沙箱后端、每个代理操作的只追加审计日志、加密的密钥存储、在 RPC 服务器公开绑定前进行把关的配对守卫，以及 `redact()` 其他所有领域用来确保日志中不出现明文凭据的辅助函数。

它确实 **不** 拥有：

* 跨领域的 `EncryptionEngine`，位于 `src/openhuman/security/encryption/`.
* 按通道的凭据存储，位于 `src/openhuman/security/credentials/`.

当你想问“这个代理操作是否允许，如果允许，又是如何受限的？”时，先看这个模块。

## 公开接口

| 项目                                                                                                                            | 文件           | 目的                                      |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------- |
| `SecurityPolicy`                                                                                                              | `policy.rs`  | 从以下内容组装运行时策略： `AutonomyConfig` + 工作区目录。 |
| `AutonomyLevel` (`受监督` / `半自主` / `自主`)                                                                                        | `policy.rs`  | 三档自治梯度。                                 |
| `CommandRiskLevel`, `ToolOperation`, `ActionTracker`                                                                          | `policy.rs`  | 风险分类 + 每会话计数。                           |
| `Sandbox` trait， `NoopSandbox`                                                                                                | `traits.rs`  | 可插拔沙箱抽象；每个后端都实现 `Sandbox`.              |
| `create_sandbox(&SecurityConfig) -> Arc<dyn Sandbox>`                                                                         | `detect.rs`  | 在运行时选择宿主机上可用的最佳后端。                      |
| `pub mod docker / bubblewrap / firejail / landlock`                                                                           | （同级文件）       | 各后端对以下内容的实现： `Sandbox`.                 |
| `SecretStore`                                                                                                                 | `secrets.rs` | 带往返辅助函数的 XOR / 操作系统钥匙串加密密钥持久化。          |
| `AuditLogger`, `AuditEventType`, `AuditEvent`, `Actor`, `Action`, `ExecutionResult`, `SecurityContext`, `CommandExecutionLog` | `audit.rs`   | 只追加审计轨迹。                                |
| `PairingGuard`, `constant_time_eq`, `is_public_bind`                                                                          | `pairing.rs` | 在将 RPC 服务器公开绑定前进行配对令牌检查。                |
| `redact(value: &str) -> String`                                                                                               | `core.rs`    | 用于日志的统一 4 字符前缀脱敏。                       |
| `security_policy_info() -> RpcOutcome<serde_json::Value>`                                                                     | `ops.rs`     | 用于 doctor / 设置界面的 RPC 处理器。              |

## 沙箱后端选择

`detect::create_sandbox` 遍历偏好列表并返回 **第一个可用的** 宿主机上的后端。确切顺序编码在 `detect.rs`；在实践中，它优先选择可用的最强隔离：

```
                ┌──────────────┐
SecurityConfig ─►│ create_sandbox│
                └──────┬───────┘
                       │ 探测
                       ├─► Docker      （最佳隔离；需要守护进程）
                       ├─► Bubblewrap  （Linux 用户命名空间沙箱）
                       ├─► Firejail    （Linux setuid 沙箱）
                       ├─► Landlock    （Linux LSM；进程内）
                       └─► Noop        （最后手段；仅记录日志）
```

代理从不会看到这个选择；它只会调用 `Sandbox::run(...)` ，其余由当前启用的后端处理。每个后端都位于同级文件中（`docker.rs`, `bubblewrap.rs`, `firejail.rs`, `landlock.rs`）；noop 回退位于 `traits.rs`.

## 自治梯度

`AutonomyLevel` 是一个三档梯度，用于控制策略对工具调用的限制强度：

* **受监督**：每个更高风险的工具调用都需要显式批准往返。
* **半自主**：低/中风险工具调用可直接通过；更高风险的仍需审批。
* **自主**：策略允许代理在预算和风险上限内无人值守运行。

`CommandRiskLevel` + `ToolOperation` 对给定的工具调用进行分类； `ActionTracker` 维护策略与上限对比所需的每会话计数。代理框架会在每次可执行工具分发前询问 `SecurityPolicy` 以获取决策。

## 审计日志

`audit.rs` 写入一条只追加的流： `AuditEvent`s，位于工作区目录下。每次可执行工具调用都会带着其 `Actor` （代理 / 用户）， `Action`, `ExecutionResult`，以及 `SecurityContext` （自治级别、沙箱后端等）运行环境。该日志是事后记录，说明代理做了什么以及为何被允许。

## 配对守卫

`PairingGuard` （在 `pairing.rs`）之间，拦在 RPC 服务器和任何尝试绑定到非回环地址的操作之间。 `is_public_bind` 检测危险情况； `PairingGuard` 要求使用常量时间比较的配对令牌（`constant_time_eq`）后，才允许这种绑定。这是 iOS / LAN 配套配对流程防止未配对对端接入桌面核心的防御措施。

## 密钥存储

`SecretStore` （在 `secrets.rs`）通过静态加密持久化每个键的密钥。在受支持的平台上，加密密钥来自操作系统钥匙串；否则回退到工作区本地的 XOR 方案（这只是 **混淆，不是安全**，源码中也明确如此说明）。

## `redact()`

`redact(value)` 返回一个统一的 4 字符前缀字符串（例如 `"sk-a"` -> `"sk-a…"`）用于日志和错误消息。只要密钥、凭据、令牌或 PII 字符串即将被格式化进 `log::` / `tracing::` 调用，就使用它。其他领域会直接调用它： `credentials/`, `webhooks/`, `composio/`，即集成适配器。

## 布局

| 路径                                                            | 角色                                                    |
| ------------------------------------------------------------- | ----------------------------------------------------- |
| `policy.rs`, `policy_tests.rs`                                | `SecurityPolicy`, `AutonomyLevel`、风险分类、操作跟踪。          |
| `traits.rs`                                                   | `Sandbox` trait + `NoopSandbox` 回退。                   |
| `detect.rs`                                                   | `create_sandbox`：选择最佳可用后端。                            |
| `docker.rs` / `bubblewrap.rs` / `firejail.rs` / `landlock.rs` | 各后端的 `Sandbox` 实现。                                    |
| `core.rs`                                                     | `redact()` + 少量共享辅助函数（有自己的 `#[cfg(test)] mod tests`). |
| `audit.rs`                                                    | 只追加审计日志类型。                                            |
| `secrets.rs`, `secrets_tests.rs`                              | `SecretStore` + 往返测试。                                 |
| `pairing.rs`, `pairing_tests.rs`                              | `PairingGuard` + 常量时间辅助函数。                            |
| `ops.rs`                                                      | RPC 处理器（`security_policy_info`).                      |
| `schemas.rs`                                                  | 控制器 schema + 处理器分发。                                   |
| `mod.rs`                                                      | 上述公开接口的重新导出。                                          |

## 调用

* `src/openhuman/config/`: `SecurityConfig`, `AutonomyConfig` 用于策略 + 沙箱选择。
* 操作系统级沙箱工具： `docker`, `bwrap`, `firejail`，以及 Landlock 系统调用（按后端）。
* 工作区文件系统，用于审计日志和密钥存储。

## 由以下调用：

* `src/openhuman/cron/scheduler.rs`：将 shell 任务包装在 `SecurityPolicy::from_config`.
* `src/openhuman/tools/local_cli.rs`, `tools/ops.rs`，以及大多数 `tools/impl/{system,network,memory,agent}/*.rs`：每个可执行工具都会查询 `SecurityPolicy`.
* `src/openhuman/tools/impl/network/{curl,http_request,composio}.rs`：对外发调用进行风险分类。
* `src/openhuman/memory/tools/{store,forget}.rs`：敏感写入跟踪。
* `src/openhuman/agent/tools/delegate.rs`：子代理分发会通过自治门控。
* `src/openhuman/security/credentials/`：使用 `SecretStore` 以及 `redact`.

## 测试

* 单元： `pairing_tests.rs`, `policy_tests.rs`, `secrets_tests.rs`.
* `core.rs` 有自己的 `#[cfg(test)] mod tests`，它会往返处理 `SecretStore` 加密 / 解密， `redact()` 用例， `PairingGuard` 默认值。
* 沙箱后端冒烟测试：每个后端文件都有自己的 `#[cfg(test)]` 块，前提是宿主机上可用该二进制。

## 相关

* [`security/README.md`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/security/README.md)：此页所镜像的、面向内部受众的权威概览。
* [架构概览](https://github.com/tinyhumansai/openhuman/tree/main/gitbooks/developing/architecture.md)：更广泛的系统上下文。
* [智能体执行框架](/openhuman/zh/kai-fa/architecture/agent-harness.md)：在此处 `SecurityPolicy` 会在每次工具分发时被查询。