> 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).

# 安全

自主核心的信任边界：自主性与风险策略、沙盒选择、审计日志、加密密钥存储，以及与 TinySecurity 脱敏器的适配器。

`crates/openhuman-core/src/security/` 是自主核心的信任边界。当你想知道“是否允许此代理执行某项操作？如果允许，如何对其进行限制？”时，请先查看这里。

它负责：

* 决定是否允许调用工具的自主性与风险策略。
* 在主机支持时，通过沙箱选择来限制调用。
* 记录每项代理操作的只追加审计日志。
* 加密机密存储。
* 针对 TinySecurity 共享脱敏器的故障关闭适配器（`scrub.rs`).

它不负责 `encryption.*` RPC 兼容命名空间（位于 `security/encryption/`，该命名空间委托给 `credentials/` 且不包含任何密码算法代码）、按渠道存储凭据（位于 `credentials/`），或公共绑定保护（位于 `openhuman-rpc/src/server/public_bind.rs`).

## 公开接口

| 项目                                                                                                                            | 文件                                                                                                                  | 用途                                       |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `SecurityPolicy`                                                                                                              | `policy/types.rs` （路径检查位于 `policy/path_checks.rs`，命令分类位于 `policy/command_checks.rs`，准入控制位于 `policy/enforcement.rs`) | 根据以下内容组装运行时策略： `AutonomyConfig` + 工作区目录。 |
| `AutonomyLevel` (`ReadOnly` / `Supervised` / `Full`)                                                                          | `policy/types.rs`                                                                                                   | 三级自主性阶梯。                                 |
| `CommandRiskLevel`, `ToolOperation`, `ActionTracker`                                                                          | `policy/types.rs`                                                                                                   | 风险分类与每会话计数。                              |
| `SecretStore`                                                                                                                 | `secret_storage/encrypted_store.rs` (`secrets.rs` 重新导出该项）                                                           | 通过操作系统密钥链／加密文件持久化机密，并提供往返转换辅助功能。         |
| `AuditLogger`, `AuditEventType`, `AuditEvent`, `Actor`, `Action`, `ExecutionResult`, `SecurityContext`, `CommandExecutionLog` | `audit.rs`                                                                                                          | 仅追加的审计跟踪记录。                              |
| `security_policy_info_for_config(&Config) -> Outcome<serde_json::Value>`                                                      | `ops.rs`                                                                                                            | 用于 doctor / 设置界面的 RPC 处理程序。              |

## 沙箱

此模块不包含沙箱后端。每个会话的沙箱选择位于 `crates/openhuman-core/src/sandbox/`。它将本地操作系统隔离委托给 `tinybox-jail` （vendored tinybox），并保留自己的 `docker run` 执行器。命令分类器使用 `tinybox_core::shell::scan`扫描 shell 字符串，分类规则则保留在此模块中。

## 自主性阶梯

`AutonomyLevel` 是一个三级阶梯，用于设定策略对工具调用的限制严格程度。它仅在 `[autonomy] enabled = true`.

* `ReadOnly` 会直接阻止所有写入操作。任何批准都无法授权此类操作。
* `Supervised` 是默认级别。它允许读取操作，其他所有操作都必须等待审批往返流程。
* `Full` 允许读取和写入操作，但网络、安装和破坏性操作仍须等待审批。

其在线路上的表示形式为小写（`readonly`, `supervised`, `full`）。面向用户的表格位于 [审批门控](https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/approval-gate.md).

`CommandRiskLevel` 和 `ToolOperation` 用于对工具调用进行分类。 `ActionTracker` 维护每个会话的计数，供策略与其上限进行比较。智能体运行框架会在每次可执行工具分派之前向 `SecurityPolicy` 请求决策。

以上所有机制仅在启用自主性策略时生效。 `[autonomy] enabled = false` 是默认值，而 `SecurityPolicy::from_config` 会将该标志传递到每个强制执行入口。策略关闭时，命令分类、审批门控、命令允许列表和每小时操作预算均不起作用。 `workspace_only`, `forbidden_paths` 和工作区内部边界也不会得到强制执行。

有一项检查始终开启。 `is_always_forbidden` 会阻止访问凭据存储（`~/.ssh`, `~/.gnupg`, `~/.aws`）和系统根目录。它还会拒绝路径中的 `..` 目录遍历和空字节。无论配置如何，该模块都会保留这项最低限度的保护。

## 审计日志

`audit.rs` 会在工作区目录下写入仅追加的 `AuditEvent`流。每次可执行工具调用都会记录在此，其中包含调用的 `Actor` （代理或用户）、 `Action`, `ExecutionResult` 以及运行时所处的 `SecurityContext` （自主级别、沙箱后端等）。日志会记录代理事后执行了什么操作，以及这些操作为何获准。

## 公开地址绑定

没有操作员提供的 RPC 令牌时，RPC 服务器会拒绝绑定到非回环地址。这项检查由服务器负责： `is_public_bind` 位于 `crates/openhuman-rpc/src/server/public_bind.rs`，而 `serve` 会在选择端口之前执行该检查。

## 密钥存储

`SecretStore` （实现在 `security/secret_storage/encrypted_store.rs`中，并通过 `secrets.rs`重新导出）使用 ChaCha20-Poly1305 加密配置字段中的机密（前缀为`enc2:` ）。解密时，它会迁移旧版 XOR `enc:` 格式。Core 负责与平台无关的机密存储契约、内存默认实现，以及可选的加密文件后端。 `openhuman-rpc::keyring` 负责原生操作系统提供程序，并在主机启动前通过这些契约安装它们。RPC 产品主机会明确选择持久化存储；嵌入式模式默认使用内存存储，除非指定了提供程序或后端覆盖项。后端选择和迁移的说明见 `crates/openhuman-core/src/security/secret_storage/README.md`.

## 目录结构

| 路径                                                                                                                                  | 作用                                                              |
| ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `policy/` (`mod.rs`, `types.rs`, `path_checks.rs`, `command_checks.rs`, `enforcement.rs`, `policy_*_tests.rs`, `proptest_tests.rs`) | `SecurityPolicy`, `AutonomyLevel`、风险分类、路径与命令检查、操作跟踪。            |
| `audit.rs`                                                                                                                          | 仅追加的审计日志类型。                                                     |
| `secrets.rs`, `secret_storage/`                                                                                                     | `SecretStore` （实现位于 `secret_storage/encrypted_store.rs`）+ 往返测试。 |
| `ops.rs`                                                                                                                            | RPC 处理程序（`security_policy_info_for_config`).                    |
| `schemas.rs`                                                                                                                        | 控制器架构定义 + 处理程序分派。                                               |
| `mod.rs`                                                                                                                            | 重新导出上述公共接口。                                                     |
| `live_policy.rs`, `scrub.rs`, `tools.rs`                                                                                            | 实时策略查询、主机清理策略（`scrub::host_policy`）以及该领域自身的代理工具。                |
| `approval/`, `credentials/`, `devices/`, `egress/`, `encryption/`, `keyring_consent/`, `prompt_injection/`                          | 同一模块下的同级内核安全领域。每个领域都拥有自己的接口。本页仅介绍策略核心。                          |

本地 PII 检测归属 [`tinymemory_api::safety`](https://github.com/tinyhumansai/tinymemory/blob/d1b06334faf7f8abb62bd1bd4ec4c4d4862f53a4/crates/tinymemory-api/src/safety/README.md) ，由其 `local-safety` 功能启用。OpenHuman 负责隐私策略和脱敏决策。

## 调用

* `crates/openhuman-core/src/config/`: `AutonomyConfig`, `SandboxConfig` 以选择策略和沙箱。
* 工作区文件系统，用于审计日志和密钥存储。

## 由以下模块调用：

* `crates/openhuman-core/src/cron/ops.rs`：将 shell 作业封装在 `SecurityPolicy::from_config`.
* `crates/openhuman-core/src/tools/ops.rs` 和 `tools/impl/{browser,filesystem,network,system}/` 和 `artifacts/tools/` （文档、演示文稿）：每个可执行工具都会查询 `SecurityPolicy`.
* `crates/openhuman-core/src/security/tool_gates/net.rs`, `crates/openhuman-core/src/mcp/tools/` 和 `crates/openhuman-core/src/mcp/server_tools.rs`：对出站调用进行风险分类。
* `crates/openhuman-core/src/memory/host_policy.rs`：为记忆写入清理器提供 TinyMemory 经交叉验证的策略。
* `crates/openhuman-core/src/agent/subagent_host/`：子代理执行会应用宿主的工具策略和自主性门控。
* `crates/openhuman-core/src/credentials/`：使用 `SecretStore`.

## 测试

* 单元测试： `policy/policy_tests*.rs`, `policy/proptest_tests.rs`, `secret_storage/encrypted_store_tests*.rs`.

## 相关内容

* [`security/README.md`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/src/security/README.md)：本页面所对应的仓库内概述。
* [架构](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/architecture/architecture.md)：更广泛的系统背景。
* [代理框架](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/architecture/agent-harness.md)： `SecurityPolicy` 会在每次工具分派时进行查询。
