安全

🔵 Agent OS 中的 auth、隔离、密钥和审计是如何设计的。

15.1 访问配置 — 汇总表

所有身份验证/授权和密钥集中在一处（详情见对应章节）：

控制内容	设置位置	类型	章节
管理员令牌（bearer）	`auth.admin_tokens` — `имя → токен` 或 `{token, templates}`	YAML	§15.2
来自 env 的令牌	在 `auth.admin_token_env` 中命名的变量（例如 `AGENT_OS_ADMIN_TOKEN`），格式 `имя=токен`	env	§15.2
Web 登录密码	`auth.users` — `логин → пароль` 或 `{password, templates}`	YAML	§15.2
角色（按模板限定范围）	令牌/用户的 `templates: [...]`	YAML	§15.3
LLM 提供商密钥	`provider.api_key` / `DEEPSEEK_API_KEY` / `AGENT_OS_API_KEY`	YAML/env	§15.4
最终用户身份	`auth.web_user_secret_env`（HMAC）	env	§15.8
入站 webhook 令牌	`inbound.token_env`	env	§15.7
工作流 webhook 令牌	`triggers.webhook.token_env`	env	§15.7
cron/webhook sink 令牌	`notify[].token_env`	env	§15.7
Telegram 机器人令牌	`telegram.token_env`（在 `agent.yaml` 中）	env	§15.4
VK 社区令牌	`vk.token_env`（在 `agent.yaml` 中）	env	§15.4
Яндекс Messenger 机器人令牌	`yandex_messenger.token_env`（在 `agent.yaml` 中）	env	§15.4
IMAP / SMTP 密码	`email.imap_password_env`、`smtp.password_env`	env	§15.4
代理主机限制	`proxy.allow_hosts`	YAML	§15.6
TLS（证书/密钥）	`AGENT_OS_TLS_CERT` / `AGENT_OS_TLS_KEY`	env	§15.5
操作审批（approval）	`approval.required_tools` + `approval:` 在 `tool.yaml` 中	YAML	§15.10
命令：成员资格和授权	`logging.team_db_path` + `teams.gated_tools` + OIDC 组	YAML	§45

总体原则：密钥值 — 仅在 .env 中；YAML 中只写 env 变量的名称（token_env / password_env）。令牌和密码本身绝不被记录到日志。

15.2 管理 API 的身份验证

受保护的端点（/v1/agents*、/v1/sessions*、/v1/budgets、/v1/cron、 /v1/workflows*、/v1/dashboard、/v1/users*、/v1/memory*、……）接受 Authorization: Bearer <токен>（API 客户端）或 cookie agentos_session （/login 之后的浏览器）。

Bearer 令牌 — 来自 auth.admin_tokens（映射 имя → токен）或 auth.admin_token_env（列表 имя=токен，以逗号/;/换行分隔）。
Web 登录 — 来自 auth.users（логин → пароль）；签发 HttpOnly cookie，有效期 12 小时。

拒绝时的行为：如果 auth 已配置，但没有任何凭据被允许 — 管理 API fails closed（对所有请求返回 401）。没有令牌和用户时 — 开放（dev 模式）。详情见 §8.3。

15.3 基于角色的访问（RBAC）

令牌或 web 用户可以按模板限定范围 — 这是限定范围的操作员：

auth:
  admin_tokens:
    drom-op:
      token: "<token>"
      templates: [drom-agent]        # принципал видит только эти шаблоны
  users:
    drom-viewer:
      password: "<password>"
      templates: [drom-agent]

完整令牌（裸 имя → токен）= 完全访问。工作流还会声明自己的 templates — 限定范围的操作员只能启动其范围内的那些（§12.4）。

与操作员 RBAC 分开的是面向最终用户的命令访问：团队中的成员资格以及对模板/工具/路由的授权（无提权）。参见 §45「命令与访问」。

15.4 密钥处理

密钥 — 仅在 .env 中（API 密钥、token_env、password_env）。 YAML 只存储环境变量的名称，绝不存储值本身。
令牌不被记录到日志：访问日志中只写入令牌/用户的名称（或 invalid），不写入值。
.env 在 .gitignore 中；模板 — .env.example。

15.5 TLS / HTTPS

设置 AGENT_OS_TLS_CERT 和 AGENT_OS_TLS_KEY（PEM 路径）— 服务器将启动 HTTPS。否则 — 普通 HTTP（例如在终止 TLS 的反向代理之后）。

15.6 代理的 SSRF 防护

/proxy 和 /proxy/content 在每一次重定向上阻止私有、loopback、link-local 和 reserved 范围（包括 169.254.169.254）。 proxy.allow_hosts 额外限制主机（精确匹配或子域）；为空 = 任意公共主机。仅 http/https，端口 80/443。

15.7 Webhook 的身份验证

入站 webhook POST /v1/inbound/:template — 来自 inbound.token_env 的 bearer 令牌（为空 = 开放，dev）。
工作流 webhook POST /v1/workflows/:name/webhook — 来自 triggers.webhook.token_env 的令牌；未设置/为空 → 所有请求被拒绝。
Cron/webhook sink — 可选的 token_env 用于 bearer 令牌。

15.8 数据隔离

代理相互隔离：一个代理不读取另一个代理的上下文，也不消耗其预算（「概念」章节）。
trace_tool 只返回调用者被允许的内容：管理员拥有完全访问（admin_templates: "*"），限定范围的管理员拥有受限访问，而没有管理令牌的最终用户代理从 X-User-Id 获得 user 范围，并且只能看到自己的历史（trace_tool）。
记忆（memory）和 state store 按用户限定范围（user_id）；没有 user id — 回退到会话 → 模板 → 进程。
身份最终用户默认使用 HMAC 签名（POST /v1/user-ticket、X-User-Token）— 参见 §8.8。

15.9 审计

访问日志（logs/access.jsonl + logs/access.db）— 每个 HTTP 请求：方法、路径、状态、持续时间、IP、user-agent、X-User-Id、管理令牌/用户的名称。令牌值不写入。
事件存储（logs/events.db）— 代理操作的审计（tool 调用、预算、错误）。
规范用户注册表（logs/users.db）— 渠道 → id 的对应关系。

15.10 操作审批（human-in-the-loop）

敏感操作（支付、扣款、群发、CRM 中的更改）可以通过内核中的强制审批进行门控 — 代理无法绕过它（包括通过 prompt injection）。由谁决定 — 通过 approver: any | end_user | operator | admin 配置；操作员的决定连同其名称写入审计（ApprovalResolved 在 events.db 中）。详见 23-approvals.md。