安全加固¶
适用范围：独立 Python Runtime。 桌面端操作见 Desktop 使用指南。
生产环境部署前，请逐项完成以下安全清单。
安全清单总览¶
| 类别 | 项目 | 优先级 |
|---|---|---|
| 认证 | 启用 Token 认证 | P0 |
| 认证 | 配置 admin_tokens | P0 |
| 网络 | 确认绑定 localhost | P0 |
| 网络 | 配置 allowed_origins | P1 |
| 网络 | 配置 allowed_hosts | P1 |
| 工具 | 设置 security.profile | P0 |
| 工具 | 设置 tools.profile | P1 |
| 文件 | 限制数据目录权限 | P1 |
| 文件 | 保护配置文件 | P1 |
| 运行时 | 限制工具风险等级 | P1 |
认证模式¶
Gateway 提供三种认证模式，生产环境应选择 allowlist 或 pairing：
open 模式（仅限开发）¶
禁止在生产环境使用 open 模式
open 跳过平台/用户白名单与配对；独立的 API/admin token 检查仍生效。无令牌部署只适合受控本机，公网必须配置令牌、来源和工具策略。
allowlist 模式（推荐）¶
预定义平台/用户白名单；API/admin token 是独立配置，消息入口还须匹配 allowed_users 或受支持的本机身份：
gateway:
auth:
mode: allowlist
allowed_users: ["cli:local"]
api_tokens:
- "ea-user-a1b2c3d4e5f6"
- "ea-user-x7y8z9w0v1u2"
admin_tokens:
- "ea-admin-secret-token"
token_header: "X-Echo-Agent-Token"
api_tokens：读取/聊天 Token；任务管理等写操作要求 adminadmin_tokens：管理员 Token，可访问配置修改、服务管理等管理接口token_header：自定义请求头名称，默认X-Echo-Agent-Token
pairing 模式¶
适合动态设备接入场景。新客户端需通过配对码完成首次认证：
gateway:
auth:
mode: pairing
pairing_ttl_seconds: 300 # 配对码有效期
allowed_users:
- "alice"
- "bob"
admin_users:
- "alice"
Token 生成建议
使用足够长度的随机字符串作为 Token（建议 32 字符以上），避免使用可预测的值。可用 python -c "import secrets; print(secrets.token_urlsafe(32))" 生成。
网络绑定与保护¶
绑定地址¶
如必须接受远程连接（如容器环境），使用防火墙限制来源：
# iptables 示例：仅允许内网访问
iptables -A INPUT -p tcp --dport 58123 -s 10.0.0.0/8 -j ACCEPT
iptables -A INPUT -p tcp --dport 58123 -j DROP
Origin 保护¶
防止跨站请求伪造（CSRF）：
gateway:
auth:
allowed_origins:
- "http://localhost:3000"
- "https://echo-agent.internal.com"
allowed_hosts:
- "localhost"
- "echo-agent.internal.com"
Gateway 会拒绝 Origin 或 Host 头不在白名单中的请求。
空 Origin 请求
某些非浏览器客户端（如 curl）不发送 Origin 头。无 Origin 且无浏览器来源标记的原生客户端不触发浏览器 CSRF 判定；令牌与消息身份检查仍独立生效。
安全配置文件¶
Echo Agent 提供分级安全配置，通过 profile 快速应用预定义策略：
security.profile：运行形态¶
security.profile 描述的是部署形态，而非"宽松到严格"的强度等级。合法取值只有三个：
| 取值 | 含义 | 追加限制 |
|---|---|---|
personal_cli |
本机单人使用（默认） | 无 |
daemon |
长期后台运行 | 拒绝 5 个工具 + 5 类能力 |
public_gateway |
网关对外暴露 | 拒绝 12 个工具 + 9 类能力 |
不存在 relaxed / standard / strict
这三个名字不是合法取值，填入会在启动时被配置校验拒绝。请按部署形态选择上表中的取值。
tools.profile：工具白名单¶
控制 Agent 可调用的工具范围，四档累加，默认 full：
| 档位 | 工具数 | 可用范围 |
|---|---|---|
minimal |
19 | 只读问答 |
messaging |
23 | + 记忆与媒体生成 |
coding |
30 | + 文件写入、编排与定时任务 |
full |
全部 | 白名单为 *，放通所有工具（默认） |
默认档位是 full
full 放通全部工具，包括 exec、execute_code、process、skill_install、skill_manage、cronjob、skill_run 等执行/持久权限工具。生产环境应显式降到 coding 或更低，并配合 security.profile 收紧。
coding 包含 cronjob，仍受审批和逐任务无人值守授权约束；如需完全禁用定时工具，可配置 tools.deny: [cronjob]。
两个字段是独立生效的：tools.profile 决定白名单，security.profile 在白名单之上追加拒绝。完整判定顺序见安全档位矩阵。
工具风险等级¶
工具风险为 READ_ONLY、WRITE、EXEC、DANGEROUS。MINIMAL_TOOLS 等是工具档位集合，并非风险等级；消息、产物等操作也不能笼统称为只读。执行前仍需通过路径规则、守卫与审批，详见工具与权限。
可在配置中精细控制单个工具的启用/禁用：
tools:
profile: coding
deny: # 显式禁用，优先于档位
- exec
- execute_code
also_allow: # 在档位基础上额外放行
- web_search
配置中没有 tools.disabled。三个列表的关系是：deny 显式禁用，also_allow 在档位之上追加，allow 则完全覆盖档位、只放行列出的工具。
文件权限¶
数据目录¶
# 限制数据目录仅当前用户可访问
chmod 700 ~/.echo-agent
chmod 600 ~/.echo-agent/config.yaml
chmod 700 ~/.echo-agent/data
配置文件中的敏感信息¶
配置文件可能包含 API Key 等敏感信息，确保权限正确：
# 检查权限
ls -la ~/.echo-agent/config.yaml
# -rw------- 1 user user ... config.yaml
# 修复权限
chmod 600 ~/.echo-agent/config.yaml
使用环境变量存储密钥
将 API Key 通过环境变量 ECHO_AGENT_* 传入，而非写入配置文件，可降低密钥泄露风险。配合 systemd 的 EnvironmentFile 或 secret manager 使用效果更佳。
生产环境配置模板¶
综合以上加固项的推荐配置：
# ~/.echo-agent/config.yaml — 生产环境
security:
profile: daemon # 或 public_gateway（对外暴露时）
tools:
profile: coding # 不使用默认的 full
deny:
- skill_install # deny 是第一层判定，无法被绕过
gateway:
host: 127.0.0.1
port: 58123
auth:
mode: allowlist
allowed_origins:
- "http://localhost:3000"
allowed_hosts:
- "localhost"
禁用工具用 tools.deny，配置中没有 tools.disabled 字段。